diff options
author | Jean Michel-Lemieux | 2004-06-18 13:09:08 +0000 |
---|---|---|
committer | Jean Michel-Lemieux | 2004-06-18 13:09:08 +0000 |
commit | 97b7da9063dc1934ccdbb7c07ea9d441b48f56e9 (patch) | |
tree | 420d93b6722bf65d916a86ee648db93c663ef30a | |
parent | 81ef0e34450b73d6a499674fcd98cf4449852753 (diff) | |
download | eclipse.platform.team-branch_20040618_javadoc_changes.tar.gz eclipse.platform.team-branch_20040618_javadoc_changes.tar.xz eclipse.platform.team-branch_20040618_javadoc_changes.zip |
updates to javadoc for 3.0branch_20040618_javadoc_changes
16 files changed, 249 insertions, 180 deletions
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipant.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipant.java index 62a428970..6664cc251 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipant.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipant.java @@ -20,33 +20,36 @@ import org.eclipse.ui.part.IPageBookViewPage; * A synchronize participant is a visual compoment that can be displayed within any * control (e.g. view, editor, dialog). Typically a participant is used to show changes between * local resources and variant states of those resources and allows the user to perform actions - * to manipulate the changes. For example, a participant could show the relative synchronization - * between local resources and those on an FTP server, or alternatively, between local - * resources and local history. + * to manipulate the changes. * <p> + * This class does not mandate how the synchronization state is displayed, but instead provides + * the accessors that clients would use to create a visual instance of the this participant. + * </p><p> + * A participant can display multiple instances of its synchronization state to the user via the creation + * of a page {@link #createPage(ISynchronizePageConfiguration)} and + * clients can decide where to display the page. For example, the synchronize view is an example + * of a client that displays a participant in a view. However, you can imagine that a client may + * also want to display this state in a wizard or dialog instead. That is possible by + * </p><p> * When a participant is registered with the {@link ISynchronizeManager} it will automatically display * in the <i>Synchronize View</i> and if the participant extension point - * enabled <code>globalSynchronize</code> it will also appear in the global synchronize action - * toolbar. + * enabled <code>synchronizeWizards</code> it will also appear in the global synchronize action + * toolbar. * <p> * A participant is added to the workbench as follows: * <ul> * <li>A <code>synchronizeParticipant</code> extension is contributed to * the team registry. This extension defines the participant id, name, icon, type, and * participant class. - * <li>The participant type is <code>static</code> it is automatically added - * to the {@link ISynchronizeManager}. - * <li>If a participant is not static, plug-in developers can add the participant to the - * manager via {@link ISynchronizeManager#addSynchronizeParticipants(ISynchronizeParticipant[]) and - * remove it using {@link ISynchronizeManager#removeSynchronizeParticipants(ISynchronizeParticipant[]). - * Note that you don't have to add the participant to the manager. You can instead create the - * participant, display it, and then dispose of it yourself. - * <li>For non-static participants you can configure the participant to support multiple instances. This will - * allow multiple instances to be created and registered with the synchronize manager. + * <li>A user via a wizard provided by the <code>synchronizeWizards</code> extension point + * or client code, creates a participant instance and registers it with the + * synchronize manager. It then appears in the synchronize view. + * <li>A synchronization can be persistent and thus re-initialized at startup. + * <li>A pinned participant will only be removed from the synchronize manager if it is un-pinned. * </ul></p> * <p> * Once a participant is added to the synchronize manager its lifecycle will be managed. On shutdown if - * the <code>persistent</code> property is set, the participant will be asked to persist state via + * the participant is persistable, the participant will be asked to persist state via * the <code>saveState()</code> method. At startup the <code>init()</code> method is called * with a handle to the state that was saved. The dispose method is called when the participant is * removed from the manager and at shutdown. @@ -136,7 +139,7 @@ public interface ISynchronizeParticipant extends IExecutableExtension { public IPageBookViewPage createPage(ISynchronizePageConfiguration configuration); /** - * Runs the participants action. Typically this would be some action to refresh the synchronizatin + * Runs the participants action. Typically this would be some action to refresh the synchronization * state of the participant. This action is run from the global synchronize drop-down. * * @param part the part in which the action is run or <code>null</code> if the action @@ -167,12 +170,10 @@ public interface ISynchronizeParticipant extends IExecutableExtension { * resources associated with a participant. When a participant is added * to the {@link ISynchronizeManager} this method is called when the * manager is shutdown or the participant is removed from the manager. - * </p> - * <p> + * </p><p> * Within this method a participant may release any resources, fonts, images, etc. * held by this part. It is also very important to deregister all listeners. - * </p> - * <p> + * </p><p> * Clients should not call this method (the synchronize manager calls this * method at appropriate times). * </p> diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipantListener.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipantListener.java index 6dde603ae..7d784d7c2 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipantListener.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipantListener.java @@ -16,6 +16,7 @@ package org.eclipse.team.ui.synchronize; * <p> * Clients may implement this interface. * </p> + * @see ISynchronizeManager * @since 3.0 */ public interface ISynchronizeParticipantListener { @@ -34,5 +35,4 @@ public interface ISynchronizeParticipantListener { * @param participants removed participants */ public void participantsRemoved(ISynchronizeParticipant[] participants); - } diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipantReference.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipantReference.java index 2594892f4..7505acf87 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipantReference.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeParticipantReference.java @@ -15,17 +15,19 @@ import org.eclipse.team.core.TeamException; /** * A reference is a light weight handle used by the {@link ISynchronizeManager} * to manage registered participants. It is used to reference information - * about a particular participant instance without requiring the particpant - * to be instantiated. + * about a particular participant instance without requiring the participant + * to be instantiated. Calling the {@link #getParticipant()} method will + * cause the participant to be instantiated. * <p> * Clients are not intended to implement this interface. - * + * </p> * @see ISynchronizeManager * @since 3.0 */ public interface ISynchronizeParticipantReference { /** * Returns the id of the participant type referenced by this handle. + * * @return the id of the participant type references by this handle. */ public String getId(); @@ -34,6 +36,7 @@ public interface ISynchronizeParticipantReference { * Returns the secondary id (e.g. instance id) of the participant type referenced * by this handle or <code>null</code> if the participant doesn't support * multiple instances. + * * @return the secondary id of the participant type referenced * by this handle or <code>null</code> if the participant doesn't support * multiple instances. @@ -53,12 +56,14 @@ public interface ISynchronizeParticipantReference { * Returns the participant referenced by this handle. This may trigger loading of the * participant and and a result may be long running. The method may return <code>null</code> * if the participant cannot be de-referenced. + * * @return the participant referencesd by this handle. */ public ISynchronizeParticipant getParticipant() throws TeamException; /** * Returns the descriptor for this participant type. + * * @return the descriptor for this participant type. */ public ISynchronizeParticipantDescriptor getDescriptor(); diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeScope.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeScope.java index f93428e3b..4d3e3ad46 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeScope.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeScope.java @@ -14,11 +14,11 @@ import org.eclipse.core.resources.IResource; import org.eclipse.jface.util.IPropertyChangeListener; /** - * A synchronize scope defines the set of resources involved in a synchronize. - * Instance of this interface are used to scope the resources of a - * {@link SubscriberParticipant}. + * A synchronize scope defines the set of resources involved in a synchronization. + * Instance of this interface are used to scope the resources of a created {@link SubscriberParticipant}. * <p> * This interface is not intended to be implemented by clients + * </p> * @see SubscriberParticipant * @since 3.0 */ @@ -31,6 +31,7 @@ public interface ISynchronizeScope { /** * Return the name of the scope + * * @return the name of the scope */ public String getName(); @@ -47,6 +48,7 @@ public interface ISynchronizeScope { /** * Add a propety change listener that will get invoked when a * property of the reciever cnahges. + * * @param listener */ public void addPropertyChangeListener(IPropertyChangeListener listener); @@ -54,6 +56,7 @@ public interface ISynchronizeScope { /** * Remove a propety change listener. Removing an unregistered listener * has no effect. + * * @param listener */ public void removePropertyChangeListener(IPropertyChangeListener listener); diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeView.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeView.java index 4b1e2ecb3..629114e39 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeView.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizeView.java @@ -27,7 +27,7 @@ import org.eclipse.ui.IViewPart; * <p> * Clients are not intended to implement this interface. * </p> - * @see ISynchronizeManager + * @see ISynchronizeManager#showSynchronizeViewInActivePage() * @since 3.0 */ public interface ISynchronizeView extends IViewPart { @@ -36,6 +36,10 @@ public interface ISynchronizeView extends IViewPart { */ public static final String VIEW_ID = "org.eclipse.team.sync.views.SynchronizeView"; //$NON-NLS-1$ + /** + * This id is no longer used. + * @deprecated not used, please use {@link #VIEW_ID} instead. + */ public static final String COMPARE_VIEW_ID = "org.eclipse.team.sync.views.CompareView"; //$NON-NLS-1$ /** diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ParticipantPageDialog.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ParticipantPageDialog.java index c442d4111..c56c1b024 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ParticipantPageDialog.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ParticipantPageDialog.java @@ -20,7 +20,7 @@ import org.eclipse.team.ui.*; /** * A dialog that displays the option of adding the participant to the {@link org.eclipse.team.ui.synchronize.ISynchronizeManager} * when the dialog is closed. This can be useful for showing changes for a participant modally and allowing the - * user to decide if the participant shown be made available non-modally. + * user to decide if the participant shown should be made available non-modally. * * @see SaveablePartAdapter * @see ISynchronizeParticipant @@ -85,6 +85,11 @@ public class ParticipantPageDialog extends SaveablePartDialog { } } + /** + * Returns the participant showing in this dialog. + * + * @return the participant showing in this dialog. + */ protected ISynchronizeParticipant getParticipant() { return participant; } diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ParticipantPageSaveablePart.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ParticipantPageSaveablePart.java index 725ab5a90..15b064fc0 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ParticipantPageSaveablePart.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ParticipantPageSaveablePart.java @@ -43,9 +43,8 @@ import org.eclipse.ui.part.IPageBookViewPage; import org.eclipse.ui.progress.IProgressService; /** - * Displays a synchronize participant page combined with the compare/merge - * infrastructured. This only works if the synchronize page viewer provides - * selections that ITypedElement and ICompareInput. + * Displays a synchronize participant page combined with the compare/merge infrastructured. This only works if the + * synchronize page viewer provides selections that are of the following types: ITypedElement and ICompareInput. * * @since 3.0 */ @@ -320,7 +319,8 @@ public class ParticipantPageSaveablePart extends SaveablePartAdapter implements control = parent; } - /* (non Javadoc) + /** + * This method should not be called from clients. * TODO: using internal compare classes to support page navigation. This is required because * we are building our own compare editor input that includes a participant page instead of a * viewer. @@ -508,9 +508,9 @@ public class ParticipantPageSaveablePart extends SaveablePartAdapter implements return actionBars; } - /** * Return the synchronize page configiration for this part + * * @return Returns the pageConfiguration. */ public ISynchronizePageConfiguration getPageConfiguration() { @@ -519,6 +519,7 @@ public class ParticipantPageSaveablePart extends SaveablePartAdapter implements /** * Return the Synchronize participant for this part + * * @return Returns the participant. */ public ISynchronizeParticipant getParticipant() { diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ResourceScope.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ResourceScope.java index 2506c75e3..e0f097ba4 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ResourceScope.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ResourceScope.java @@ -24,6 +24,7 @@ import org.eclipse.ui.IMemento; * A synchronize scope whose roots are a set of resources. * <p> * Clients are not expected to subclass this class. + * </p> * @since 3.0 */ public class ResourceScope extends AbstractSynchronizeScope { @@ -41,6 +42,7 @@ public class ResourceScope extends AbstractSynchronizeScope { /** * Create the resource scope for the given resources + * * @param resources the resources that define this scope */ public ResourceScope(IResource[] resources) { @@ -49,7 +51,8 @@ public class ResourceScope extends AbstractSynchronizeScope { /** * Create this scope from it's previously saved state - * @param memento + * + * @param memento persisted state that can be restored */ protected ResourceScope(IMemento memento) { super(memento); @@ -57,6 +60,7 @@ public class ResourceScope extends AbstractSynchronizeScope { /** * Set the resources that define this scope + * * @param resources the resources that define this scope */ public void setResources(IResource[] resources) { 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 c93ba1198..d6cd79bf5 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 @@ -11,7 +11,6 @@ package org.eclipse.team.ui.synchronize; import java.util.Arrays; - import org.eclipse.core.resources.IResource; import org.eclipse.core.runtime.*; import org.eclipse.jface.util.IPropertyChangeListener; @@ -31,7 +30,8 @@ import org.eclipse.ui.part.IPageBookViewPage; /** * 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. + * by listening to workspace resource changes and remote changes thus creating a live view of + * changes in the workspace. * <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. @@ -82,6 +82,7 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa /** * Constructor which should be called when creating a particpant whose resources * are to be scoped. + * * @param scope a synchronize scope */ public SubscriberParticipant(ISynchronizeScope scope) { @@ -100,7 +101,7 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa /** * Returns the resources supervised by this participant. It will - * either be the roots of the subscriber or the resources + * either be the roots of the subscriber or the resource scope * provided when the subscriber was set. * * @return the resources supervised by this participant. @@ -112,6 +113,7 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa /* * Set the resources supervised by this participant. If <code>null</code>, * the participant will include all roots of its subscriber + * * @param roots the root resources to consider or <code>null</code> * to consider all roots of the subscriber */ @@ -121,6 +123,7 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa /** * Refresh this participants synchronization state and displays the result in a model dialog. + * * @param resources * @param taskName * @param site @@ -131,9 +134,16 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa } /** - * Refresh a participant in the background the result of the refresh are shown in the progress view. + * Refresh a participant in the background the result of the refresh are shown in the progress view. Refreshing + * can also be considered synchronizing, or refreshing the synchronization state. Basically this is a long + * running operation that will update the participants sync info sets with new changes detected on the + * server. * * @param resources the resources to be refreshed. + * @param shortTaskName the taskName of the background job that will run the synchronize. + * @param longTaskName the taskName of the progress monitor running the synchronize + * @param site the workbench site the synchronize is running from. This can be used to notify the site + * that a job is running. */ public final void refresh(IResource[] resources, String shortTaskName, String longTaskName, IWorkbenchSite site) { IRefreshSubscriberListener listener = new RefreshUserNotificationPolicy(this); @@ -192,7 +202,11 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa } /** - * Returns a participant that matches the scoping + * Returns a participant that matches the given resource scoping + * + * @param ID the type id of participants to match + * @param resources the resources to match in the scope + * @return a participant that matches the given resource scoping */ public static SubscriberParticipant getMatchingParticipant(String ID, IResource[] resources) { ISynchronizeParticipantReference[] refs = TeamUI.getSynchronizeManager().getSynchronizeParticipants(); @@ -332,6 +346,7 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa * <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) { @@ -367,21 +382,19 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa } /** - * Provide a filter that is used to filter the contents of the - * sync info set for the participant. Normally, all out-of-sync - * resources from the subscriber will be included in the - * participant's set. However, a filter can be used to exclude + * Provide a filter that is used to filter the contents of the sync info set for the participant. Normally, all out-of-sync + * resources from the subscriber will be included in the participant's set. However, a filter can be used to exclude * some of these out-of-sync resources, if desired. * <p> - * Subsclasses can invoke this method any time after - * <code>setSubscriber</code> has been invoked. + * Subsclasses can invoke this method any time after <code>setSubscriber</code> has been invoked. + * </p> * @param filter a sync info filter */ protected void setSyncInfoFilter(SyncInfoFilter filter) { collector.setFilter(filter); } - /** + /* * Create and schedule a subscriber refresh job. * * @param resources resources to be synchronized @@ -402,6 +415,7 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa /** * Return the scope that defines the resources displayed by this participant. + * * @return Returns the scope. */ public ISynchronizeScope getScope() { diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SyncInfoCompareInput.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SyncInfoCompareInput.java index b9583c65c..2483cc4a2 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SyncInfoCompareInput.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SyncInfoCompareInput.java @@ -41,6 +41,8 @@ import org.eclipse.ui.progress.UIJob; * in an editor. This input can alternatly be used to show compare results in * a dialog by calling {@link CompareUI#openCompareDialog()}. * <p> + * The editor will not update when the elements in the sync info are changed. + * </p><p> * Supports saving the local resource that is changed in the editor and will be updated * when the local resources is changed. * </p><p> diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelAction.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelAction.java index bf0eca122..cdacf39e1 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelAction.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelAction.java @@ -26,16 +26,14 @@ import org.eclipse.ui.ide.IDE; /** * This action provides utilities for performing operations on selections that - * are obtained from a view populated by a - * {@link org.eclipse.team.ui.synchronize.viewers.SynchronizeModelProvider}. - * The {@link org.eclipse.team.internal.ui.synchronize.SubscriberParticipantPage} is an example of such a view. - * Subclasses can use this support to filter the selection in order to - * determine action enablement and generate the input for a {@link SynchronizeModelOperation}. + * contain {@link org.eclipse.team.ui.synchronize.ISynchronizeModelElement} + * instances. Subclasses can use this support to filter the selection in order + * to determine action enablement and generate the input for a + * {@link SynchronizeModelOperation}. + * * @see SyncInfo * @see SyncInfoSet - * @see org.eclipse.team.ui.synchronize.viewers.SynchronizeModelProvider - * @see org.eclipse.team.internal.ui.synchronize.SubscriberParticipantPage - * @see org.eclipse.team.ui.synchronize.SynchronizeModelOperation + * @see SynchronizeModelOperation * @since 3.0 */ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction { @@ -46,6 +44,7 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction * Create an action with the given text and configuration. By default, * the action registers for selection change with the selection provider * from the configuration's site. + * * @param text the action's text * @param configuration the actions synchronize page configuration */ @@ -56,6 +55,7 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction /** * Create an action with the given text and configuration. By default, * the action registers for selection change with the given selection provider. + * * @param text the action's text * @param configuration the actions synchronize page configuration * @param selectionProvider a selection provider @@ -70,6 +70,7 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction * Method invoked from the constructor. * The default implementation registers the action as a selection change * listener. Subclasses may override. + * * @param configuration the synchronize page configuration * @param selectionProvider a selection provider */ @@ -103,6 +104,7 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction /** * Return whether dirty editor should be saved before this action is run. * Default is <code>true</code>. + * * @return whether dirty editor should be saved before this action is run */ protected boolean needsToSaveDirtyEditors() { @@ -110,8 +112,9 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction } /** - * Returns whether the user should be prompted to save dirty editors. - * The default is <code>true</code>. + * Returns whether the user should be prompted to save dirty editors. The + * default is <code>true</code>. + * * @return whether the user should be prompted to save dirty editors */ protected boolean confirmSaveOfDirtyEditor() { @@ -119,20 +122,24 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction } /** - * Return the subscriber operation associated with this action. This operation - * will be run when the action is run. Subclass may implement this method and provide - * an operation subclass or may override the <code>run(IAction)</code> method directly - * if they choose not to implement a <code>SynchronizeModelOperation</code>. - * @param configuration the synchronize page configuration for the page - * to which this action is associated - * @param elements the selected diff element for which this action is enabled. + * Return the subscriber operation associated with this action. This + * operation will be run when the action is run. Subclass may implement this + * method and provide an operation subclass or may override the + * <code>run(IAction)</code> method directly if they choose not to + * implement a <code>SynchronizeModelOperation</code>. + * + * @param configuration the synchronize page configuration for the page to + * which this action is associated + * @param elements the selected diff element for which this action is + * enabled. * @return the subscriber operation to be run by this action. */ protected abstract SynchronizeModelOperation getSubscriberOperation(ISynchronizePageConfiguration configuration, IDiffElement[] elements); - /** - * Generic error handling code that uses an error dialog to show the error to the - * user. Subclasses can use this method and/or override it. + /** + * Generic error handling code that uses an error dialog to show the error + * to the user. Subclasses can use this method and/or override it. + * * @param e the exception that occurred. */ protected void handle(Exception e) { @@ -162,10 +169,10 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction } /** - * Filter uses to filter the user selection to contain only those - * elements for which this action is enabled. - * Default filter includes all out-of-sync elements in the current - * selection. Subsclasses may override. + * Filter uses to filter the user selection to contain only those elements + * for which this action is enabled. Default filter includes all out-of-sync + * elements in the current selection. Subsclasses may override. + * * @return a sync info filter which selects all out-of-sync resources. */ protected FastSyncInfoFilter getSyncInfoFilter() { @@ -174,7 +181,8 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction /** * Return the selected diff element for which this action is enabled. - * @return the list of selected diff elements for which this action is enabled. + * @return the list of selected diff elements for which this action is + * enabled. */ protected final IDiffElement[] getFilteredDiffElements() { IDiffElement[] elements = getSelectedDiffElements(); @@ -193,6 +201,7 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction /** * Set the selection of this action to the given selection + * * @param selection the selection */ public void selectionChanged(ISelection selection) { @@ -205,21 +214,21 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction } /** - * @return Returns the configuration. + * Returns the configuration showing this action. + * + * @return the configuration showing this action. */ public ISynchronizePageConfiguration getConfiguration() { return configuration; } /** - * Save all dirty editors in the workbench that are open on files that - * may be affected by this operation. Opens a dialog to prompt the - * user if <code>confirm</code> is true. Return true if successful. - * Return false if the user has cancelled the command. Must be called - * from the UI thread. + * Save all dirty editors in the workbench that are open on files that may + * be affected by this operation. Opens a dialog to prompt the user if + * <code>confirm</code> is true. Return true if successful. Return false + * if the user has cancelled the command. Must be called from the UI thread. * - * @param confirm - * prompt the user if true + * @param confirm prompt the user if true * @return boolean false if the operation was cancelled. */ public final boolean saveAllEditors(boolean confirm) { diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelOperation.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelOperation.java index ab356aa90..797863076 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelOperation.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelOperation.java @@ -23,11 +23,11 @@ import org.eclipse.team.ui.TeamOperation; import org.eclipse.ui.IWorkbenchPart; /** - * A subscriber operation provides access to a {@link SyncInfoSet} containing - * the selection from a {@link SynchronizeModelAction}. - * When used in conjuntion with a {@link SynchronizeModelAction}, the selected - * elements in the view will show busy indication if this - * operation is run as a job. + * A specialized team operation that operates on + * {@link org.eclipse.team.ui.synchronize.ISynchronizeModelElement}elements. If + * the operation is run in the background the elements the operation is created + * with will be updated to show that they are busy while the operation is + * running and will be marked un-busy after the operation completes. * * @see SyncInfoSet * @see SynchronizeModelAction @@ -61,10 +61,11 @@ public abstract class SynchronizeModelOperation extends TeamOperation { } /** - * Create an operation that will operate on the given diff elements - * that were obtained from a view populated by a - * {@link org.eclipse.team.ui.synchronize.viewers.SynchronizeModelProvider}. - * @param elements + * Create an operation that will operate on the given diff elements. + * + * @param configuration the participant configuration in which this + * operation is run + * @param elements the model elements this operation will run with */ protected SynchronizeModelOperation(ISynchronizePageConfiguration configuration, IDiffElement[] elements) { super(getPart(configuration), getRunnableContext(configuration)); @@ -72,8 +73,11 @@ public abstract class SynchronizeModelOperation extends TeamOperation { } /** - * Returns a sync info set that contains the {@link SyncInfo} for the + * Returns a sync info set that contains the {@link SyncInfo}for the * elements of this operations. + * + * @return the sync info set that contains the elements this operation is + * operating on. */ protected SyncInfoSet getSyncInfoSet() { return makeSyncInfoSetFromSelection(getSyncInfos()); @@ -106,6 +110,7 @@ public abstract class SynchronizeModelOperation extends TeamOperation { /* * Return the selected SyncInfo for which this action is enabled. + * * @return the selected SyncInfo for which this action is enabled. */ private SyncInfo[] getSyncInfos() { diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizePageActionGroup.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizePageActionGroup.java index b51b04be4..6d79a4c07 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizePageActionGroup.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizePageActionGroup.java @@ -10,24 +10,12 @@ *******************************************************************************/ package org.eclipse.team.ui.synchronize; -import java.util.ArrayList; -import java.util.HashMap; -import java.util.Iterator; -import java.util.List; -import java.util.Map; - +import java.util.*; import org.eclipse.core.runtime.Platform; -import org.eclipse.jface.action.IAction; -import org.eclipse.jface.action.IContributionItem; -import org.eclipse.jface.action.IContributionManager; -import org.eclipse.jface.action.IMenuManager; +import org.eclipse.jface.action.*; import org.eclipse.jface.util.ListenerList; import org.eclipse.jface.util.SafeRunnable; -import org.eclipse.jface.viewers.ISelection; -import org.eclipse.jface.viewers.ISelectionChangedListener; -import org.eclipse.jface.viewers.ISelectionProvider; -import org.eclipse.jface.viewers.SelectionChangedEvent; -import org.eclipse.jface.viewers.StructuredSelection; +import org.eclipse.jface.viewers.*; import org.eclipse.team.internal.ui.synchronize.SynchronizePageConfiguration; import org.eclipse.ui.IActionBars; import org.eclipse.ui.actions.ActionGroup; @@ -63,8 +51,7 @@ import org.eclipse.ui.actions.ActionGroup; * a chance to adjust the input to actions that operate on all visible elements. * <li>The <code>dispose()</code> method is called when the page is disposed. * </ul> - * <p> - * TODO: Describe menu configuration and adding actions to groups + * </p> * @since 3.0 */ public abstract class SynchronizePageActionGroup extends ActionGroup { @@ -75,10 +62,10 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { private VisibleRootsSelectionProvider visibleRootSelectionProvider; - /** - * A selection provider whose selection is the root elements - * visible in the page. Selection changed events are sent out - * when the model roots change or their visible children change + /* + * A selection provider whose selection is the root elements visible in the + * page. Selection changed events are sent out when the model roots change + * or their visible children change */ private class VisibleRootsSelectionProvider extends SynchronizePageActionGroup implements ISelectionProvider { @@ -144,15 +131,15 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { } /** - * Initialize the actions of this contribution. - * This method will be invoked once before any calls are - * made to <code>filleContextMenu</code> or <code>setActionBars</code> - * but after the control for the page has been created. As a result - * of this, the site of the configuration can be accessed. - * Sublcasses may override this method but must invoke - * the overriden method. - * @param configuration the configuration for the part to which - * the contribution is associated + * Initialize the actions of this contribution. This method will be invoked + * once before any calls are made to <code>filleContextMenu</code> or + * <code>setActionBars</code> but after the control for the page has been + * created. As a result of this, the site of the configuration can be + * accessed. Sublcasses may override this method but must invoke the + * overriden method. + * + * @param configuration the configuration for the part to which the + * contribution is associated */ public void initialize(ISynchronizePageConfiguration configuration) { this.configuration = configuration; @@ -162,10 +149,11 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { } /** - * This method is invoked whenever the model being displayed in the - * view changes. This includes when the input to the view changes - * and when the children of the input change. The default implementation - * of this method does nothing. Subclasses may override. + * This method is invoked whenever the model being displayed in the view + * changes. This includes when the input to the view changes and when the + * children of the input change. The default implementation of this method + * does nothing. Subclasses may override. + * * @param root the root of the model being viewed */ public void modelChanged(ISynchronizeModelElement root) { @@ -184,11 +172,11 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { } /** - * Helper method to find the group of the given id for the page - * associated with the configuration of this action group. - * The id of the returned group will not match that of the - * provided id since the group must be modified to ensure that - * groups are unique accross pages. + * Helper method to find the group of the given id for the page associated + * with the configuration of this action group. The id of the returned group + * will not match that of the provided id since the group must be modified + * to ensure that groups are unique accross pages. + * * @param menu the menu * @param groupId the id of the group being searched for * @return the group for the given id or <code>null</code> @@ -205,8 +193,9 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { /** * Helper method to add an action to a group in a menu. The action is only - * added to the menu if the group exists in the menu. Calling this method + * added to the menu if the group exists in the menu. Calling this method * also has no effect if either the menu or action are <code>null</code>. + * * @param manager the menu manager * @param groupId the group to append the action to * @param action the action to add @@ -224,9 +213,11 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { } /** - * Helper method to add a contribution item to a group in a menu. The item is only - * added to the menu if the group exists in the menu. Calling this method - * also has no effect if either the menu or item are <code>null</code>. + * Helper method to add a contribution item to a group in a menu. The item + * is only added to the menu if the group exists in the menu. Calling this + * method also has no effect if either the menu or item are + * <code>null</code>. + * * @param manager the menu manager * @param groupId the group to append the action to * @param item the item to add @@ -244,13 +235,15 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { } /** - * Helper method that can be invoked during initialization to add an - * action to a particular menu (one of P_TOOLBAR_MENU, P_VIEW_MENU, P_CONTEXT_MENU - * from ISynchronizePageConfiguration). The action is added to the given group - * if it is present. Otherwise the action is not added to the menu. - * @param menuId the menu id (one of P_TOOLBAR_MENU, P_VIEW_MENU, P_CONTEXT_MENU - * from ISynchronizePageConfiguration) - * @param groupId the group id in the menu to which the action is to be added + * Helper method that can be invoked during initialization to add an action + * to a particular menu (one of P_TOOLBAR_MENU, P_VIEW_MENU, P_CONTEXT_MENU + * from ISynchronizePageConfiguration). The action is added to the given + * group if it is present. Otherwise the action is not added to the menu. + * + * @param menuId the menu id (one of P_TOOLBAR_MENU, P_VIEW_MENU, + * P_CONTEXT_MENU from ISynchronizePageConfiguration) + * @param groupId the group id in the menu to which the action is to be + * added * @param action the action to be added */ protected void appendToGroup(String menuId, String groupId, IAction action) { @@ -258,12 +251,13 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { } /** - * Helper method that can be invoked during initialization to add an - * item to a particular menu (one of P_TOOLBAR_MENU, P_VIEW_MENU, P_CONTEXT_MENU + * Helper method that can be invoked during initialization to add an item to + * a particular menu (one of P_TOOLBAR_MENU, P_VIEW_MENU, P_CONTEXT_MENU * from ISynchronizePageConfiguration). The item is added to the given group * if it is present. Otherwise the item is not added to the menu. - * @param menuId the menu id (one of P_TOOLBAR_MENU, P_VIEW_MENU, P_CONTEXT_MENU - * from ISynchronizePageConfiguration) + * + * @param menuId the menu id (one of P_TOOLBAR_MENU, P_VIEW_MENU, + * P_CONTEXT_MENU from ISynchronizePageConfiguration) * @param groupId the group id in the menu to which the item is to be added * @param item the item to be added */ @@ -272,10 +266,10 @@ public abstract class SynchronizePageActionGroup extends ActionGroup { } /** - * Return a selection provider whose selection includes all roots - * of the elements - * visible in the page. Selection change events are fired when the + * Return a selection provider whose selection includes all roots of the + * elements visible in the page. Selection change events are fired when the * elements visible in the view change. + * * @return a selection provider whgose selection is the roots of all * elements visible in the page */ diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/WorkingSetScope.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/WorkingSetScope.java index eac227110..b789a8610 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/WorkingSetScope.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/WorkingSetScope.java @@ -40,6 +40,7 @@ public class WorkingSetScope extends AbstractSynchronizeScope implements IProper /** * Create the scope for the subscriber and working set + * * @param subscriber the subscriber that defines this scope * @param set the working set that defines this scope */ @@ -48,9 +49,11 @@ public class WorkingSetScope extends AbstractSynchronizeScope implements IProper PlatformUI.getWorkbench().getWorkingSetManager().addPropertyChangeListener(this); } - /** + /** * Create this scope from it's previously saved state - * @param memento + * + * @param memento the memento containing a previous scope information + * that is used to initialize this scope. */ protected WorkingSetScope(IMemento memento) { super(memento); @@ -74,7 +77,6 @@ public class WorkingSetScope extends AbstractSynchronizeScope implements IProper return name.toString(); } - /* (non-Javadoc) * @see org.eclipse.team.ui.synchronize.ISynchronizeScope#getRoots() */ diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/WorkspaceScope.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/WorkspaceScope.java index 30fabebd3..1b71dc4a2 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/WorkspaceScope.java +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/WorkspaceScope.java @@ -17,6 +17,7 @@ import org.eclipse.team.internal.ui.Policy; * A synchronize scope whose roots are the workspace. * <p> * Clients are not expected to subclass this class. + * </p> * @since 3.0 */ public class WorkspaceScope extends AbstractSynchronizeScope { diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/package.html b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/package.html index ae46ea670..99dcbec67 100644 --- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/package.html +++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/package.html @@ -51,12 +51,18 @@ into Eclipse.<br> <li><span style="font-weight: bold;">Synchronize View Interfaces</span> - Represents a set of classes and interfaces to support a generic synchronize view that can show multiple -synchronize participants.</li> - <li><span style="font-weight: bold;">Viewer Advisors</span> - The -advisors allow decoupling viewer behavior from the viewers presentation -and basically provide the ability to show synchronization information -stored as <code>SyncInfo </code>or in a <code>SyncInfoSet</code> to -be shown in a Viewer.</li> +synchronize participants.<br> + </li> + <li><span style="font-weight: bold;">SubscriberParticipants</span> - +Concrete implementation of the synchronize view interfaces for +synchronizations that are SyncInfo based. Subclasses get the well-known +synchronize page that supports 4 modes (e.g. +incomming/outgoing/conficting/both) and the standard resource layouts +(compressed folder and hierarchical). This is the easy entry point into +the Synchronize View since all a client would have to provide is a +Subscriber class that generates SyncInfo instances for resources and a +set of operations that run on the sync nodes.<br> + </li> <li><span style="font-weight: bold;">Compare Inputs</span> - These are helpers for allowing users to display and edit the resources being synchronized.</li> @@ -75,24 +81,37 @@ Synchronize View consists of:<br> </p> <ul> <li>A ISynchronizeManager manages registered synchronize -participants. There can be several instances of the same participant -type.</li> +participants. Every participant has a type and and instance identifier.</li> <li>A ISynchronizeParticipant is a logical representation of a connection between workspace resources and a remote location used to -shared those resources.</li> - <li>A ISynchronizeView is a page book view of participants.</li> +shared those resources. A participant creates a page in that shows the +synchronization for the participant.<br> + </li> + <li>A ISynchronizeView is a page book view of participants. The +synchronize view has support for showing multiple synchronizations. As +described above, you will see merges, 2 way-compares, and basic +synchronizations. Synchronizations are categorized into types, for +example the CVS plugin defines three types: CVS, CVS Merge, and CVS +Compare. You can switch between synchronizations using the drop-down +menu in the sync view. When you create a new synchronization it will +replace the first existing synchronization of the same type unless it +is pinned. Pinning allows you to manage the synchronizations that are +of interest to you and ensure that they remain easily accessible. This +should provide for easy management of multiple synchronizations.<br> + </li> <li>A ISynchronizeParticipant must create a page that will be displayed in the ISynchronizeView page book view.</li> <li>The ISynchronizeView shows a drop-down of all registered participants and allows switching between them.</li> - <li>A ISynchronizeParticipant can contribute actions to the toolbar, -menus, and view menu.</li> + <li>A ISynchronizeParticipant creates a configuration which is used +to configure the presentation of the participant by clients. For +example, clients using a ISynchronizeParticipant instances can decide +to show the participant page with a set of customized menus or toolbar +actions.<br> + </li> </ul> <p>Synchronize participants are declared by extending the <strong>synchronizeParticipants -</strong>extension point. There are two classes of synchronize -participants: <em>static </em>participants will be created when the -synchronize view is created, and <em>dynamic</em> participants that -are created by user code at some other time. A synchronize manager +</strong>extension point. A synchronize manager manages all active synchronize participants, and provides notification of participants which are added and removed. Participants are displayed in a page book view. Each participant implementation is reponsible for @@ -102,18 +121,15 @@ participant may be displayed simultaneously in multiple synchronize views, and in different workbench windows.<br> </p> <hr style="width: 100%; height: 2px;"> -<h3>Viewer Advisors</h3> -- StructuredViewerAdvisor: are used to -display the logical structure to the user and define the basics such as -the SynchronizeModelProvider, label provider, and context menus.<br> -<p>- SyncInfoCompareInput: is used to show a comparison between a local -resource and a variant in a compare editor.<br> -- SyncInfoSetCompareInput: is used to showing a set of variants in a -compare editor<br> -</p> -<p>Default implementations are provided and there are many levels of -customizations available.<br> -</p> +<h3>SubscriberParticipants<br> +</h3> + SubscriberParticipant is an abstract class that is intented to +support a common synchronization workflow. It is the easy way to get +into the Synchronize View and essentially inherit the default +synchronize experience. The requirement for using a +SubscriberParticipant is to create a subscriber that can produce +SyncInfo (e.g. objects that describe the synchronization between local +and remote resources). <hr style="width: 100%; height: 2px;"> <h3>Compare Inputs</h3> These are helpers for allowing users to display and edit resources @@ -126,8 +142,11 @@ shown in synchronize viewers.<br> <hr style="width: 100%; height: 2px;"> <h3>Related Documentation</h3> <ul> - <li>Pointer to the ISV docs?</li> - <li>Tutorials?<br> + <li>For examples of these APIs in action please see the <a + href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.examples.filesystem/">org.eclipse.team.examples.filesystem</a> +plug-in example and also refer to the <span style="font-weight: bold;">Platform +Plug-in Developer Guide > Programmer's Guide > Team Support</span> +documentation.<br> </li> </ul> </body> |