Getting Started with Saros
Welcome to Saros! Here you will find a guideline on how to setup Saros. After setting up Saros, find out what awesome features Saros has on the complete
feature list!
Step 1: Connecting
You need an XMPP account to use Saros. You can create a new account within Saros by using the FU-Berlin servers, if you don't already have an account. You can reuse existing Googlemail, or web.de Emailaddresses (they are valid xmpp accounts!).
Creating a new account in saros:
- Open the Create Account wizard (Menu > Saros > Create XMPP/Jabber Account...)
- Enter your account details.
- Click Finish. You will be prompted to confirm the new account creation.
Using an existing account:
- Open the Saros preferences (Menu > Saros > Preferences...).
- If you have already the account stored, you can highlight the account in list and click Activate Account.
- Otherwise, click Add Account and enter the existing account details.
Step 2: Adding buddies to work with
To add a buddy to your buddy list you need to know his/her XMPP ID. Also remember that buddies can only be added while you are connected.
There are two places in Saros where a buddy can be added:
- (Menu > Saros > Add buddy...)
Using either one of these possibilities you will be redirected to the following window:
After entering your partners XMPP ID and optionally assigning a nickname, a message will be sent to your partner. Once he/she accepts your buddy invite you will be able to see her online status in your buddy list. From here on, you may invite him/her into a session.
Step 3: Starting and Joining Shared Project Sessions
You join sessions by either starting your own and inviting others, or by being invited to one yourself. When starting a distributed session, Saros will copy the complete project to the machine of the invited users.
a) How to start a shared project session (host):
- Right-click on a project in your Navigator (or Package Explorer), select Share With
- You can choose one of the listed users
- Or you select Multiple Buddies... In the appearing invitation dialog you can first choose the Project(s) you want to share, and then the Buddies you want to invite. To complete the invitation click on Finish.
b) How to join an already running shared project session (client):
- If you're invited to a session, an invitation will appear on your screen. It includes the username of the inviter and the name of the project(s) to which you are invited.
- Select Finish if you want to accept the invitation. You can reject the invitation by clicking Cancel.
- After accepting, you can instruct Saros where to put the new project. You can create a new project, or synchronise with an existing copy already stored on your computer.
- Click Finish and wait for the shared project to be copied to your computer.
c) Some additional information:
- Saros will share all files which are not marked as derived by Eclipse, because it should be possible to recreate such files (.class files for instance) at the client's side. If you use a build tool such as Ant, it might be necessary to manually set the resulting files or folders to derived on both the host (so they won't be copied to the client) and the client (otherwise the files will be deleted on synchronisation).
- If you accept an invitation and decide to synchronise the incoming project with your own copy, Saros will automatically add, change, or delete all files as necessary. You will have the chance to review changes before accepting.
Step 4: Exploring the Saros View
The Saros View consists of three parts: the buddy list, the session list and the chat area.
The buddy list is where all your contacts are stored, allowing you to check their availability, send them instant messages, and invite them to Saros sessions. When you begin a Saros session you will see all participants in the session list. Saros also provides an instant messaging chat to accompany your sessions. Whenever you begin a Saros session, a chat session is also automatically started.
Step 5: Expore the Saros Toolbar Items
Connecting: Click here to connect or disconnect from the server, or to switch between user accounts if you have more than one. When you connect, you will see information about your buddies (including whether they are connected and also whether they support Saros).
Add Buddy: To add a new buddy click here (you will need the full XMPP address of your buddy in the format:
username@server).
Inconsistency repair: Sometimes accidents can happen and your copy of the project can become out of sync with the host's copy. When it does, this button will light up. When you click it, the inconsistencies will be repaired.
Switch follow mode on/off: You can turn the follow mode on and of. In follow mode Saros will automatically sync your eclipse view with the user you are following, opening shared files the the other users is opening, and autoamtically scrolling the visible part of the editor of open files, so you always see what the followed user sees.
Turn beep notification on/off: If you want to hear a sound when a buddy comes online or goes offline or when you received a chat message, you can turn this beep notification on.
Leave the session: Click here to leave the current session. If you are the host, the session will be closed and all participants will be ejected from the session.
Context Menu Tasks
Grant Write Access: Gives the selected participant write access.
Restrict to Read-Only Access: Removes the write access right from the selected participant. The affected participant will only have read access afterwards.
Follow Participant: Follows the selected participant as described in section
Follow Mode.
Jump to Position: Jumps to the cursor position of the selected participant and open the corresponding file if necessary.
Send File: Gives you the opportunity to select a file to be sent to the selected participant.
Share Your Screen: Lets you share your screen with the selected participant. Please make sure you properly configured the encoder if one of the participants is not using Microsoft Windows.
Start VoIP? Session: Starts a
VoIP? session with the selected participant.
Leave Access /
Stop Session: If you have been invited to a session this button makes you leave the session without affecting other participants. If you are the creator of the session you cannot leave but only stop the session.
User Roles
By default all participants of a session have a writing access. To restrict or grant this access to another user, right-click on that user name in the
Session list and select
Restrict to read-only access or
Grant writing access. This can only be done by the host (the user that started the session by inviting another user)
Follow-Mode
You can use this feature to follow a single driver as s/he navigates the project and performs changes. When you follow a driver:
- Whenever s/he opens a file on her/his computer, it is opened on yours too.
- Any time s/he switches to view a different file, it is switched on yours.
- As s/he scrolls through a file, the viewpoint is moved on your computer also, so that you see what the driver sees.
Staying Aware of your Fellow Participants
There are multiple ways of staying aware of what a driver is currently doing:
- In the package explorer (or resource navigator):
- A small yellow dot decorates all files that the driver currently has open.
- A small green dot decorates the file that the driver currently has in focus.
- The position of a user's cursor appears in the file in that user's colour.
- Any text selected by a user also appears highlighted in the file.
- On the left and right side of editors you can see coloured bars representing the viewports of each user. These show which part of the file each user can see.
- If a driver writes something, her/his text will appear highlighted in her/his colour.
- Follow-mode allows an observer to follow all movements of another user as s/he moves within and between files. In the Session list, right click on the user you wish to follow and select Follow Participant.
NOTE: You can change your own colour by right-clicking your user-name in the
Session list and selecting
Change color.
png 
