### Eclipse Workspace Patch 1.0 #P Saros Index: src/de/fu_berlin/inf/dpp/ui/actions/NewSessionAction.java =================================================================== --- src/de/fu_berlin/inf/dpp/ui/actions/NewSessionAction.java (revision 2290) +++ src/de/fu_berlin/inf/dpp/ui/actions/NewSessionAction.java (working copy) @@ -35,6 +35,30 @@ @Component(module = "action") public class NewSessionAction extends GeneralNewSessionAction { + /** + * @JTourBusStop 1, Invitation Process: + * + * Clicking on "Share project..." brings execution here. This + * begins a process that includes: + * + * - Beginning a new session. + * + * - Inviting people to join the newly created session, and + * adding them if they accept. + * + * - Determining which files need to be sent to the invitees + * depending on their response. + * + * - Sending/receiving those files. + * + * We begin the whole process at the run() method below. This + * function is automatically called by Eclipse whenever an + * Action is executed. It simply calls runNewSession() in the + * GeneralNewSessionAction class (notice that NewSessionAction + * inherits from this class). + * + */ + private static final Logger log = Logger.getLogger(NewSessionAction.class .getName()); Index: src/de/fu_berlin/inf/dpp/invitation/OutgoingInvitationProcess.java =================================================================== --- src/de/fu_berlin/inf/dpp/invitation/OutgoingInvitationProcess.java (revision 2290) +++ src/de/fu_berlin/inf/dpp/invitation/OutgoingInvitationProcess.java (working copy) @@ -63,10 +63,10 @@ import de.fu_berlin.inf.dpp.synchronize.StopManager; import de.fu_berlin.inf.dpp.ui.wizards.InvitationWizard; import de.fu_berlin.inf.dpp.util.CommunicationNegotiatingManager; +import de.fu_berlin.inf.dpp.util.CommunicationNegotiatingManager.CommunicationPreferences; import de.fu_berlin.inf.dpp.util.FileZipper; import de.fu_berlin.inf.dpp.util.Util; import de.fu_berlin.inf.dpp.util.VersionManager; -import de.fu_berlin.inf.dpp.util.CommunicationNegotiatingManager.CommunicationPreferences; import de.fu_berlin.inf.dpp.util.VersionManager.Compatibility; import de.fu_berlin.inf.dpp.util.VersionManager.VersionInfo; @@ -134,6 +134,26 @@ this.doStream = doStream; } + /** + * @JTourBusStop 7, Invitation Process: + * + * And here is the start() method. It dispatches sequentially + * a series of function calls for performing an invitation. + * Having knowledge of only some of them is necessary for + * understanding partial sharing. + * + * The first two calls simply check if the peer has Saros + * installed and if it is a compatible version. + * sendInvitation() asks the peer to accept an invitation, + * then waits for the file list request (which it will receive + * if the peer accepts). + * + * At the next stop, we will see how the file list is put + * together... + * + * + */ + public void start(SubMonitor monitor) throws SarosCancellationException { log.debug("Inv" + Util.prefix(peer) + ": Invitation has started."); @@ -264,8 +284,8 @@ } else { log.debug("Inv" + Util.prefix(peer) + ": Unable to obtain peer's version information."); - if (!InvitationWizard.confirmUnknownVersion(peer, versionManager - .getVersion())) + if (!InvitationWizard.confirmUnknownVersion(peer, + versionManager.getVersion())) localCancel(null, CancelOption.DO_NOT_NOTIFY_PEER); } } @@ -302,17 +322,18 @@ .getFileListRequestCollector(invitationID); CommunicationPreferences comPrefs = comNegotiatingManager.getOwnPrefs(); - transmitter.sendInvitation(sharedProject.getProjectMapper().getID( - this.project), peer, description, colorID, hostVersionInfo, - invitationID, sharedProject.getSessionStart(), doStream, comPrefs); + transmitter.sendInvitation( + sharedProject.getProjectMapper().getID(this.project), peer, + description, colorID, hostVersionInfo, invitationID, + sharedProject.getSessionStart(), doStream, comPrefs); subMonitor.worked(25); subMonitor .setTaskName("Invitation sent. Waiting for acknowledgement..."); transmitter.receiveFileListRequest(fileListRequestCollector, - invitationID, subMonitor.newChild(75, - SubMonitor.SUPPRESS_ALL_LABELS)); + invitationID, + subMonitor.newChild(75, SubMonitor.SUPPRESS_ALL_LABELS)); log.debug("Inv" + Util.prefix(peer) + ": File list request has received."); } @@ -349,8 +370,9 @@ FileList localFileList; try { if (partialProjectResources != null) { - localFileList = new FileList(partialProjectResources - .toArray(new IResource[partialProjectResources.size()])); + localFileList = new FileList( + partialProjectResources + .toArray(new IResource[partialProjectResources.size()])); } else { localFileList = new FileList(project); } @@ -362,8 +384,8 @@ log.debug("Inv" + Util.prefix(peer) + ": Sending file list..."); subMonitor.setTaskName("Sending file list..."); - transmitter.sendFileList(peer, invitationID, localFileList, subMonitor - .newChild(50, SubMonitor.SUPPRESS_ALL_LABELS)); + transmitter.sendFileList(peer, invitationID, localFileList, + subMonitor.newChild(50, SubMonitor.SUPPRESS_ALL_LABELS)); subMonitor.setTaskName("Waiting for the peer's file list..."); checkCancellation(CancelOption.NOTIFY_PEER); @@ -405,8 +427,8 @@ List startHandles; synchronized (sharedProject) { startHandles = stopManager.stop(usersToStop, - "Synchronizing invitation", subMonitor.newChild(25, - SubMonitor.SUPPRESS_ALL_LABELS)); + "Synchronizing invitation", + subMonitor.newChild(25, SubMonitor.SUPPRESS_ALL_LABELS)); } try { @@ -497,8 +519,8 @@ List startHandles; synchronized (sharedProject) { startHandles = stopManager.stop(usersToStop, - "Synchronizing invitation", subMonitor.newChild(25, - SubMonitor.SUPPRESS_ALL_LABELS)); + "Synchronizing invitation", + subMonitor.newChild(25, SubMonitor.SUPPRESS_ALL_LABELS)); } try { @@ -529,8 +551,8 @@ subMonitor.setTaskName("Streaming archive..."); - performFileStream(archiveStreamService, streamSession, subMonitor - .newChild(75)); + performFileStream(archiveStreamService, streamSession, + subMonitor.newChild(75)); // } } catch (Exception e) { @@ -612,8 +634,7 @@ if (filesSent >= 1) zout.finish(); } catch (IOException e) { - log - .warn("IOException occurred when finishing the ZipOutputStream."); + log.warn("IOException occurred when finishing the ZipOutputStream."); } IOUtils.closeQuietly(output); IOUtils.closeQuietly(zout); @@ -632,8 +653,9 @@ invitationCompleteCollector = transmitter .getInvitationCompleteCollector(invitationID); - transmitter.receiveInvitationCompleteConfirmation(monitor.newChild(50, - SubMonitor.SUPPRESS_ALL_LABELS), invitationCompleteCollector); + transmitter.receiveInvitationCompleteConfirmation( + monitor.newChild(50, SubMonitor.SUPPRESS_ALL_LABELS), + invitationCompleteCollector); log.debug("Inv" + Util.prefix(peer) + ": Notifying participants that the invitation is complete."); @@ -659,8 +681,8 @@ .getUserListConfirmationCollector(); for (User user : sharedProject.getRemoteUsers()) { - transmitter.sendUserList(user.getJID(), invitationID, sharedProject - .getParticipants()); + transmitter.sendUserList(user.getJID(), invitationID, + sharedProject.getParticipants()); } log.debug("Inv" + Util.prefix(peer) Index: src/de/fu_berlin/inf/dpp/ui/actions/PartialNewSessionAction.java =================================================================== --- src/de/fu_berlin/inf/dpp/ui/actions/PartialNewSessionAction.java (revision 2290) +++ src/de/fu_berlin/inf/dpp/ui/actions/PartialNewSessionAction.java (working copy) @@ -41,6 +41,30 @@ .getLogger(PartialNewSessionAction.class.getName()); /** + * @JTourBusStop 2, Invitation Process: + * + * Before we continue, here's a little detour. This class + * definition looks almost the same as the previous one. In + * fact, it's the Action that is executed when you click + * "Share project partially...", the feature that you will be + * working on. + * + * Notice that the run() method differs a little from that in + * the NewSessionAction. In this case, before calling + * runNewSession(), the program opens a dialog box. Take a + * look at the PartialProjectSelectionDialog, and even better, + * try the feature out. + * + * You should see that this dialog allows the user to select + * specific files from the chosen project. When finished, the + * dialog returns the chosen files in a List (an + * IResource is Eclipse's abstraction for the constituents of + * a project, e.g. files, folders etc). This list is passed to + * the runNewSession() method. + * + */ + + /** * @review runSafe OK */ public void run(IAction action) { Index: src/de/fu_berlin/inf/dpp/ui/actions/GeneralNewSessionAction.java =================================================================== --- src/de/fu_berlin/inf/dpp/ui/actions/GeneralNewSessionAction.java (revision 2290) +++ src/de/fu_berlin/inf/dpp/ui/actions/GeneralNewSessionAction.java (working copy) @@ -63,6 +63,26 @@ Saros.reinject(this); } + /** + * @JTourBusStop 3, Invitation Process: + * + * The runNewSession() method simply calls through to the + * SessionManager, instructing it to begin the session. In + * doing so, it passes the selected project and the list of + * IResources. + * + * You can probably work out how the selectedProject variable + * is initialised, but how can the sessionManager variable be + * non-null at this point, seeing as it has not yet been + * initialised? Notice that the declaration of the + * sessionManager above has the @Inject annotation. This flags + * that the creation of this variable is managed by the + * PicoContainer. + * + * TODO: Explain PicoContainer. + * + */ + public void runNewSession(List resource) { try { sessionManager.startSession(this.selectedProject, resource); Index: src/de/fu_berlin/inf/dpp/project/SessionManager.java =================================================================== --- src/de/fu_berlin/inf/dpp/project/SessionManager.java (revision 2290) +++ src/de/fu_berlin/inf/dpp/project/SessionManager.java (working copy) @@ -51,8 +51,8 @@ import de.fu_berlin.inf.dpp.exceptions.LocalCancellationException; import de.fu_berlin.inf.dpp.exceptions.RemoteCancellationException; import de.fu_berlin.inf.dpp.invitation.IncomingInvitationProcess; -import de.fu_berlin.inf.dpp.invitation.OutgoingInvitationProcess; import de.fu_berlin.inf.dpp.invitation.InvitationProcess.CancelOption; +import de.fu_berlin.inf.dpp.invitation.OutgoingInvitationProcess; import de.fu_berlin.inf.dpp.net.ConnectionState; import de.fu_berlin.inf.dpp.net.IConnectionListener; import de.fu_berlin.inf.dpp.net.JID; @@ -72,10 +72,10 @@ import de.fu_berlin.inf.dpp.ui.SarosUI; import de.fu_berlin.inf.dpp.ui.wizards.InvitationWizard; import de.fu_berlin.inf.dpp.util.CommunicationNegotiatingManager; +import de.fu_berlin.inf.dpp.util.CommunicationNegotiatingManager.CommunicationPreferences; import de.fu_berlin.inf.dpp.util.StackTrace; import de.fu_berlin.inf.dpp.util.Util; import de.fu_berlin.inf.dpp.util.VersionManager; -import de.fu_berlin.inf.dpp.util.CommunicationNegotiatingManager.CommunicationPreferences; import de.fu_berlin.inf.dpp.util.VersionManager.VersionInfo; /** @@ -148,6 +148,19 @@ protected static final Random sessionRandom = new Random(); + /** + * @JTourBusStop 4, Invitation Process: + * + * Now we can initialise the session (note that this is done + * before the invitations are sent). The shared project is + * created and started (at which point the host enters the + * session) and the SessionManager takes its own copy of the + * partialProjectResources for use later. + * + * At the end, the openInviteDialog() method is called... + * + */ + public void startSession(IProject project, List partialProjectResources) throws XMPPException { if (!saros.isConnected()) { @@ -328,6 +341,16 @@ expectedSequenceNumbers, true); } + /** + * @JTourBusStop 5, Invitation Process: + * + * This method starts the invitation wizard, which you use to + * select the user(s) you wish to invite. Take a look at + * {@link InvitationWizard#performFinish()}, which is the code + * executed when you click on the wizard's finish button. + * Notice that it calls back to this class (i.e. the invite() + * method). + */ public void openInviteDialog(final @Nullable List toInvite) { final SharedProject sharedProject = currentlySharedProject.getValue(); @@ -352,6 +375,19 @@ } /** + * @JTourBusStop 6, Invitation Process: + * + * The session is established and the host has chosen the + * invitees. Now the invitations can be sent. + * + * This is done using the OutgoingInvitationProcess; notice + * that this is instantiated in the invite() method below. If + * you dig into the outgoingInvitationJob a little deeper, + * you'll notice that + * {@link OutgoingInvitationProcess#start()} is called. + */ + + /** * Invites a user to the shared project. * * @param toInvite @@ -417,8 +453,8 @@ this.process = process; this.peer = process.getPeer().getBase(); setProperty(IProgressConstants.KEEP_PROPERTY, Boolean.TRUE); - setProperty(IProgressConstants.ICON_PROPERTY, SarosUI - .getImageDescriptor("/icons/invites.png")); + setProperty(IProgressConstants.ICON_PROPERTY, + SarosUI.getImageDescriptor("/icons/invites.png")); } @Override