javadoc update

1 files changed, 180 insertions, 149 deletions

diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberParticipant.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberParticipant.java
index 284a17481..d1c35035c 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberParticipant.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberParticipant.java
@@ -34,56 +34,52 @@ import org.eclipse.ui.part.IPageBookViewPage;
 import org.eclipse.ui.progress.UIJob;
 
 /**
- * A synchronize participant that displays synchronization information for local
- * resources that are managed via a {@link Subscriber}.
- * 
- * Participant:
- * 1. maintains a collection of all out-of-sync resources for a subscriber
- * 2. synchronize schedule
- * 3. APIs for creating specific: sync page, sync wizard, sync advisor (control ui pieces)
- * 4. allows refreshing the participant synchronization state
- *
+ * A synchronize participant that displays synchronization information for local resources that are 
+ * managed via a {@link Subscriber}. It maintains a dynamic collection of all out-of-sync resources
+ * by listening to workspace resource changes and remote changes.
+ * <p>
+ * The subscriber can be configured to be synchronized in the background based on a schedule. This
+ * effectively refreshes the subscriber and updates the dynamic sync set.
+ * </p><p>
+ * Subclasses will typically want to override the following methods:
+ * <ul>
+ * <li>initializeConfiguration: participants can add toolbar actions, configure the context menu, decorator.
+ * <li>saveState and init: persist settings between sessions.
+ * </ul>
+ * This class is intended to be subclassed. 
+ * </p>
  * @since 3.0
  */
 public abstract class SubscriberParticipant extends AbstractSynchronizeParticipant implements IPropertyChangeListener {
 	
-	/**
+	/*
 	 * Collects and maintains set of all out-of-sync resources of the subscriber
 	 */
 	private SubscriberSyncInfoCollector collector;
 	
+	/*
+	 * Controls the automatic synchronization of this participant
+	 */
 	private SubscriberRefreshSchedule refreshSchedule;
 	
-	/**
+	/*
 	 * Key for settings in memento
 	 */
 	private static final String CTX_SUBSCRIBER_PARTICIPANT_SETTINGS = TeamUIPlugin.ID + ".TEAMSUBSRCIBERSETTINGS"; //$NON-NLS-1$
 	
-	/**
+	/*
 	 * Key for schedule in memento
 	 */
 	private static final String CTX_SUBSCRIBER_SCHEDULE_SETTINGS = TeamUIPlugin.ID + ".TEAMSUBSRCIBER_REFRESHSCHEDULE"; //$NON-NLS-1$
 	
 	/**
-	 * Property constant indicating the schedule of a page has changed. 
+	 * Constructor initializes the schedule. Subclasses must call this method.
 	 */
-	public static final String P_SYNCVIEWPAGE_SCHEDULE = TeamUIPlugin.ID  + ".P_SYNCVIEWPAGE_SCHEDULE";	 //$NON-NLS-1$
-	
 	public SubscriberParticipant() {
 		super();
 		refreshSchedule = new SubscriberRefreshSchedule(this);
 	}
 	
-	/**
-	 * Initialize the particpant sync info set in the configuration.
-	 * Subclasses may override but must invoke the inherited method.
-	 * @param configuration the page configuration
-	 * @see org.eclipse.team.ui.synchronize.AbstractSynchronizeParticipant#initializeConfiguration(org.eclipse.team.ui.synchronize.ISynchronizePageConfiguration)
-	 */
-	protected void initializeConfiguration(ISynchronizePageConfiguration configuration) {
-		configuration.setProperty(SynchronizePageConfiguration.P_PARTICIPANT_SYNC_INFO_SET, collector.getSyncInfoSet());
-	}
-	
 	/* (non-Javadoc)
 	 * @see org.eclipse.team.ui.sync.ISynchronizeViewPage#createPage(org.eclipse.team.ui.sync.ISynchronizeView)
 	 */
@@ -92,19 +88,6 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 		return new SubscriberParticipantPage(configuration, getSubscriberSyncInfoCollector());
 	}
 	
-	/**
-	 * This method is invoked before the given configuration is used to
-	 * create the page (see <code>createPage(ISynchronizePageConfiguration)</code>).
-	 * The configuration would have been initialized by 
-	 * <code>initializeConfiguration(ISynchronizePageConfiguration)</code>
-	 * but may have also been tailored further. This method gives the particpant 
-	 * a chance to validate those changes before the page is created.
-	 * @param configuration the page configuration that is about to be used to create a page.
-	 */
-	protected void validateConfiguration(ISynchronizePageConfiguration configuration) {
-		// Do nothing by default
-	}
-	
 	/* (non-Javadoc)
 	 * @see org.eclipse.team.ui.synchronize.ISynchronizeParticipant#createRefreshPage()
 	 */
@@ -112,101 +95,15 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 		return new SubscriberRefreshWizard(this);
 	}
 	
-	/* (non-Javadoc)
-	 * @see org.eclipse.team.ui.synchronize.ISynchronizeParticipant#getResources()
+	/**
+	 * Returns the resources supervised by this participant.
+	 * 
+	 * @return the resources supervised by this participant.
 	 */
 	public IResource[] getResources() {
 		return collector.getSubscriber().roots();
 	}
 	
-	private void internalRefresh(IResource[] resources, final IRefreshSubscriberListener listener, String taskName, IWorkbenchSite site) {
-		final IWorkbenchAction[] gotoAction = new IWorkbenchAction[] {null};
-		final RefreshSubscriberJob job = new RefreshSubscriberJob(taskName, resources, collector.getSubscriber());
-		IProgressMonitor group = Platform.getJobManager().createProgressGroup();
-		group.beginTask(taskName + " " + getName(), 100);
-		job.setProgressGroup(group, 80);
-		collector.setProgressGroup(group, 20);
-		job.setUser(true);
-		job.setSubscriberCollector(collector);
-		job.setProperty(new QualifiedName("org.eclipse.ui.workbench.progress", "icon"), getImageDescriptor());
-		job.setProperty(new QualifiedName("org.eclipse.ui.workbench.progress", "goto"), new WorkbenchAction() {
-			public void run() {
-				if(gotoAction[0] != null) {
-					gotoAction[0].run();
-				}
-			}
-			public boolean isEnabled() {
-				if(gotoAction[0] != null) {
-					return gotoAction[0].isEnabled();
-				}
-				return false;
-			}
-			
-			public void dispose() {
-				super.dispose();
-				if(gotoAction[0] != null) {
-					gotoAction[0].dispose();
-				}
-			}
-		});
-		// Listener delagate
-		IRefreshSubscriberListener autoListener = new IRefreshSubscriberListener() {
-			public void refreshStarted(IRefreshEvent event) {
-				if(listener != null) {
-					listener.refreshStarted(event);
-				}
-			}
-			public ActionFactory.IWorkbenchAction refreshDone(IRefreshEvent event) {
-				if(listener != null) {
-					// Update the progress properties. Only keep the synchronize if the operation is non-modal.
-					Boolean modelProperty = (Boolean)job.getProperty(ProgressManager.PROPERTY_IN_DIALOG);
-					boolean isModal = true;
-					if(modelProperty != null) {
-						isModal = modelProperty.booleanValue();
-					}
-
-					ActionFactory.IWorkbenchAction runnable = listener.refreshDone(event);
-					if(runnable != null) {
-					// If the job is being run modally then simply prompt the user immediatly
-					if(isModal) {
-						if(runnable != null) {
-							final IAction[] r = new IAction[] {runnable};
-							Job update = new UIJob("") {
-								public IStatus runInUIThread(IProgressMonitor monitor) {
-									r[0].run();
-									return Status.OK_STATUS;
-								}
-							};
-							update.setSystem(true);
-							update.schedule();
-						}
-					// If the job is being run in the background, don't interrupt the user and simply update the goto action
-					// to perform the results.
-					} else {
-						gotoAction[0] = runnable;
-						gotoAction[0].setEnabled(runnable.isEnabled());
-						runnable.addPropertyChangeListener(new IPropertyChangeListener() {
-							public void propertyChange(PropertyChangeEvent event) {
-								if(event.getProperty().equals(IAction.ENABLED)) {
-									Boolean bool = (Boolean) event.getNewValue();
-									gotoAction[0].setEnabled(bool.booleanValue());
-								}
-							}
-						});
-					}
-					}
-					RefreshSubscriberJob.removeRefreshListener(this);
-				}
-				return null;
-			}
-		};
-		
-		if (listener != null) {
-			RefreshSubscriberJob.addRefreshListener(autoListener);
-		}	
-		Utils.schedule(job, site);
-	}
-	
 	/**
 	 * Refresh this participants synchronization state and displays the result in a model dialog. 
 	 * @param resources
@@ -237,29 +134,23 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 		collector.dispose();
 	}
 	
+	/**
+	 * Returns the <code>SyncInfoTree</code> for this participant. This set
+	 * contains the out-of-sync resources supervised by this participant. 
+	 * 
+	 * @return the sync info set that contains the out-of-sync resources
+	 * for this participant.
+	 */
 	public SyncInfoTree getSyncInfoSet() {
 		return getSubscriberSyncInfoCollector().getSyncInfoSet();
 	}
 	
-	protected void setSubscriber(Subscriber subscriber) {
-		collector = new SubscriberSyncInfoCollector(subscriber);
-		
-		// listen for global ignore changes
-		TeamUI.addPropertyChangeListener(this);
-		
-		// Start collecting changes
-		collector.start();
-		
-		// Start the refresh now that a subscriber has been added
-		SubscriberRefreshSchedule schedule = getRefreshSchedule();
-		if(schedule.isEnabled()) {
-			getRefreshSchedule().startJob();
-		}
-	}
-	
 	/**
-	 * Get the <code>Subscriber</code> for this participant
-	 * @return a <code>TamSubscriber</code>
+	 * Return the <code>Subscriber</code> associated with this this participant. This
+	 * method will only return <code>null</code> if the participant has not been initialized
+	 * yet. 
+	 * 
+	 * @return the <code>Subscriber</code> associated with this this participant.
 	 */
 	public Subscriber getSubscriber() {
 		if (collector == null) return null;
@@ -279,6 +170,7 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 	 * @see org.eclipse.team.ui.synchronize.ISynchronizeParticipant#init(org.eclipse.ui.IMemento)
 	 */
 	public void init(String secondaryId, IMemento memento) throws PartInitException {
+		super.init(secondaryId, memento);
 		if(memento != null) {
 			IMemento settings = memento.getChild(CTX_SUBSCRIBER_PARTICIPANT_SETTINGS);
 			if(settings != null) {
@@ -292,35 +184,85 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 	 * @see org.eclipse.team.ui.synchronize.ISynchronizeParticipant#saveState(org.eclipse.ui.IMemento)
 	 */
 	public void saveState(IMemento memento) {
+		super.saveState(memento);
 		IMemento settings = memento.createChild(CTX_SUBSCRIBER_PARTICIPANT_SETTINGS);
 		refreshSchedule.saveState(settings.createChild(CTX_SUBSCRIBER_SCHEDULE_SETTINGS));
 	}
 
-	/*
+	/**
 	 * Reset the sync set of the particpant by repopulating it from scratch.
 	 */
 	public void reset() {
 		getSubscriberSyncInfoCollector().reset();
 	}
 	
-	/*
+	/* (non-Javadoc)
 	 * Return the <code>SubscriberSyncInfoCollector</code> for the participant.
 	 * This collector maintains the set of all out-of-sync resources for the subscriber.
+	 * 
 	 * @return the <code>SubscriberSyncInfoCollector</code> for this participant
 	 */
 	public SubscriberSyncInfoCollector getSubscriberSyncInfoCollector() {
 		return collector;
 	}
 	
+	/*(non-Javadoc)
+	 * Not to be called by clients.
+	 */
 	public void setRefreshSchedule(SubscriberRefreshSchedule schedule) {
 		this.refreshSchedule = schedule;
-		firePropertyChange(this, P_SYNCVIEWPAGE_SCHEDULE, null, schedule);
 	}
 	
+	/* (non-Javadoc)
+	 * Not to be called by clients.
+	 */
 	public SubscriberRefreshSchedule getRefreshSchedule() {
 		return refreshSchedule;
 	}
 	
+	/* (non-Javadoc)
+	 * @see org.eclipse.team.ui.synchronize.AbstractSynchronizeParticipant#initializeConfiguration(org.eclipse.team.ui.synchronize.ISynchronizePageConfiguration)
+	 */
+	protected void initializeConfiguration(ISynchronizePageConfiguration configuration) {
+		configuration.setProperty(SynchronizePageConfiguration.P_PARTICIPANT_SYNC_INFO_SET, collector.getSyncInfoSet());
+	}
+	
+	/**
+	 * This method is invoked before the given configuration is used to
+	 * create the page (see <code>createPage(ISynchronizePageConfiguration)</code>).
+	 * The configuration would have been initialized by 
+	 * <code>initializeConfiguration(ISynchronizePageConfiguration)</code>
+	 * but may have also been tailored further. This method gives the particpant 
+	 * a chance to validate those changes before the page is created.
+	 * @param configuration the page configuration that is about to be used to create a page.
+	 */
+	protected void validateConfiguration(ISynchronizePageConfiguration configuration) {
+		// Do nothing by default
+	}
+	
+	/**
+	 * Subclasses must call this method to initialize the participant. Typically this
+	 * method is called in {@link #init(String, IMemento)}. This method will initialize
+	 * the sync info collector.
+	 * 
+	 * @param subscriber the subscriner to associate with this participant.
+	 */
+	protected void setSubscriber(Subscriber subscriber) {
+		collector = new SubscriberSyncInfoCollector(subscriber);
+		
+		// listen for global ignore changes
+		TeamUI.addPropertyChangeListener(this);
+		
+		// Start collecting changes
+		collector.start();
+		
+		// Start the refresh now that a subscriber has been added
+		SubscriberRefreshSchedule schedule = getRefreshSchedule();
+		if(schedule.isEnabled()) {
+			getRefreshSchedule().startJob();
+		}
+	}
+	
 	/**
 	 * Provide a filter that is used to filter the contents of the
 	 * sync info set for the participant. Normally, all out-of-sync
@@ -335,4 +277,93 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 	protected void setSyncInfoFilter(SyncInfoFilter filter) {
 		collector.setFilter(filter);
 	}
+	
+	private void internalRefresh(IResource[] resources, final IRefreshSubscriberListener listener, String taskName, IWorkbenchSite site) {
+		final IWorkbenchAction[] gotoAction = new IWorkbenchAction[] {null};
+		final RefreshSubscriberJob job = new RefreshSubscriberJob(taskName, resources, collector.getSubscriber());
+		
+		IProgressMonitor group = Platform.getJobManager().createProgressGroup();
+		group.beginTask(taskName + " " + getName(), 100);
+		job.setProgressGroup(group, 80);
+		collector.setProgressGroup(group, 20);
+		job.setUser(true);
+		job.setSubscriberCollector(collector);
+		job.setProperty(new QualifiedName("org.eclipse.ui.workbench.progress", "icon"), getImageDescriptor());
+		job.setProperty(new QualifiedName("org.eclipse.ui.workbench.progress", "goto"), new WorkbenchAction() {
+			public void run() {
+				if(gotoAction[0] != null) {
+					gotoAction[0].run();
+				}
+			}
+			public boolean isEnabled() {
+				if(gotoAction[0] != null) {
+					return gotoAction[0].isEnabled();
+				}
+				return false;
+			}
+			
+			public void dispose() {
+				super.dispose();
+				if(gotoAction[0] != null) {
+					gotoAction[0].dispose();
+				}
+			}
+		});
+		// Listener delagate
+		IRefreshSubscriberListener autoListener = new IRefreshSubscriberListener() {
+			public void refreshStarted(IRefreshEvent event) {
+				if(listener != null) {
+					listener.refreshStarted(event);
+				}
+			}
+			public ActionFactory.IWorkbenchAction refreshDone(IRefreshEvent event) {
+				if(listener != null) {
+					// Update the progress properties. Only keep the synchronize if the operation is non-modal.
+					Boolean modelProperty = (Boolean)job.getProperty(ProgressManager.PROPERTY_IN_DIALOG);
+					boolean isModal = true;
+					if(modelProperty != null) {
+						isModal = modelProperty.booleanValue();
+					}
+
+					ActionFactory.IWorkbenchAction runnable = listener.refreshDone(event);
+					if(runnable != null) {
+					// If the job is being run modally then simply prompt the user immediatly
+					if(isModal) {
+						if(runnable != null) {
+							final IAction[] r = new IAction[] {runnable};
+							Job update = new UIJob("") {
+								public IStatus runInUIThread(IProgressMonitor monitor) {
+									r[0].run();
+									return Status.OK_STATUS;
+								}
+							};
+							update.setSystem(true);
+							update.schedule();
+						}
+					// If the job is being run in the background, don't interrupt the user and simply update the goto action
+					// to perform the results.
+					} else {
+						gotoAction[0] = runnable;
+						gotoAction[0].setEnabled(runnable.isEnabled());
+						runnable.addPropertyChangeListener(new IPropertyChangeListener() {
+							public void propertyChange(PropertyChangeEvent event) {
+								if(event.getProperty().equals(IAction.ENABLED)) {
+									Boolean bool = (Boolean) event.getNewValue();
+									gotoAction[0].setEnabled(bool.booleanValue());
+								}
+							}
+						});
+					}
+					}
+					RefreshSubscriberJob.removeRefreshListener(this);
+				}
+				return null;
+			}
+		};
+		
+		if (listener != null) {
+			RefreshSubscriberJob.addRefreshListener(autoListener);
+		}	
+		Utils.schedule(job, site);
+	}
 }
\ No newline at end of file