ISynchronizeParticipant


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.team.ui.synchronize;
12  
13  import org.eclipse.compare.CompareConfiguration;
14  import org.eclipse.core.runtime.*;
15  import org.eclipse.jface.preference.PreferencePage;
16  import org.eclipse.jface.resource.ImageDescriptor;
17  import org.eclipse.jface.util.IPropertyChangeListener;
18  import org.eclipse.team.core.TeamException;
19  import org.eclipse.ui.*;
20  import org.eclipse.ui.part.IPageBookViewPage;
21  
22  /**
23   * A synchronize participant is a visual component that can be displayed within any
24   * control (e.g. view, editor, dialog).  Typically a participant is used to show changes between 
25   * local resources and variant states of those resources and allows the user to perform actions
26   * to manipulate the changes. 
27   * <p>
28   * This class does not mandate how the synchronization state is displayed, but instead provides
29   * the accessors that clients would use to create a visual instance of the this participant.
30   * </p><p>
31   * A participant can display multiple instances of its synchronization state to the user via the creation 
32   * of a page {@link #createPage(ISynchronizePageConfiguration)} and
33   * clients can decide where to display the page. For example, the synchronize view is an example
34   * of a client that displays a participant in a view. However, you can imagine that a client may
35   * also want to display this state in a wizard or dialog instead. That is possible by 
36   * </p><p>
37   * When a participant is registered with the {@link ISynchronizeManager} it will automatically display 
38   * in the <i>Synchronize View</i> and if the participant extension point
39   * enabled <code>synchronizeWizards</code> it will also appear in the global synchronize action
40   * toolbar. 
41   * <p>
42   * A participant is added to the workbench as follows:
43   * <ul>
44   * <li>A <code>synchronizeParticipant</code> extension is contributed to 
45   * the team registry. This extension defines the participant id, name, icon, type, and 
46   * participant class.
47   * <li>A user via a wizard provided by the <code>synchronizeWizards</code> extension point
48   * or client code, creates a participant instance and registers it with the
49   * synchronize manager. It then appears in the synchronize view.
50   * <li>A synchronization can be persistent and thus re-initialized at startup. 
51   * <li>A pinned participant will only be removed from the synchronize manager if it is un-pinned.
52   * </ul></p>
53   * <p>
54   * Once a participant is added to the synchronize manager its lifecycle will be managed. On shutdown if
55   * the participant is persistable, the participant will be asked to persist state via 
56   * the <code>saveState()</code> method. At startup the <code>init()</code> method is called
57   * with a handle to the state that was saved. The dispose method is called when the participant is
58   * removed from the manager and at shutdown.
59   * </p><p>
60   * Clients are not intended to implement this interface. Instead, subclass {@link AbstractSynchronizeParticipant}.
61   * </p>
62   * @see ISynchronizeView
63   * @see ISynchronizeManager
64   * @see AbstractSynchronizeParticipant
65   * @since 3.0
66   */
67  public interface ISynchronizeParticipant extends IExecutableExtension, IAdaptable {
68      
69      /**
70       * A property constant that can be used to indicate that the content of this participant 
71       * has changed. This is a general event that can be used to indicate to the user that there
72       * is a change in state for the participant. In general, the values associated with the event do not have
73       * any meaning.
74       * 
75       * @see #addPropertyChangeListener(IPropertyChangeListener)
76       */
77      public static final String   P_CONTENT = "org.eclipse.team.ui.content"; //$NON-NLS-1$
78  
79      /**
80       * Returns the unique id that identified the <i>type</i> of this
81       * synchronize participant. The synchronize manager supports registering
82       * several instances of the same participant type.
83       * 
84       * @return the unique id that identified the <i>type</i> of this
85       * synchronize participant.
86       */
87      public String   getId();
88      
89      /**
90       * Returns the instance id that identified the unique instance of this
91       * participant. The synchronize manager supports registering
92       * several instances of the same participant type and this id is used
93       * to differentiate between them.
94       * 
95       * @return  the instance id that identified the unique instance of this
96       * participant or <code>null</code> if this participant doesn't support
97       * multiple instances.
98       */ 
99      public String   getSecondaryId();
100     
101     /**
102      * Returns the name of this synchronize participant. This name is displayed to the user.
103      * 
104      * @return the name of this synchronize participant
105      */
106     public String   getName();
107     
108     /**
109      * Returns an image descriptor for this synchronize participant, or <code>null</code>
110      * if none.
111      * 
112      * @return an image descriptor for this synchronize participant, or <code>null</code>
113      * if none
114      */
115     public ImageDescriptor getImageDescriptor();
116     
117     /**
118      * Returns if this participant is pinned. Pinned participants will only be removed from the
119      * synchronize manager until they are un-pinned. 
120      * 
121      * @return <code>true</code> if this participant is pinned and <code>false</code>
122      * otherwise.
123      */
124     public boolean isPinned();
125     
126     /**
127      * Sets whether this participant is pinned.
128      * 
129      * @param pinned sets if the participant is pinned. 
130      */
131     public void setPinned(boolean pinned);
132     
133     /**
134      * Creates the configuration for the participant page. The configuration controls the
135      * options for displaying the participant. The configuration used to initialize the page
136      * when {@link #createPage(ISynchronizePageConfiguration)} is called and as such
137      * can be used to pre-configure visual properties of the displayed page.
138      * 
139      * @return the configuration for the participant page.
140      */
141     public ISynchronizePageConfiguration createPageConfiguration();
142     
143     /**
144      * Creates and returns a new page for this synchronize participant. The
145      * page is displayed using the parameters from the configuration. For example,
146      * the configuration defines the context in which the page is shown, via the
147      * {@link ISynchronizePageSite}. 
148      * 
149      * @param configuration used to initialize the page
150      * @return a page book view page representation of this synchronize
151      * participant
152      */
153     public IPageBookViewPage createPage(ISynchronizePageConfiguration configuration);
154     
155     /**
156      * Runs the participants action. Typically this would be some action to refresh the synchronization
157      * state of the participant. This action is run from the global synchronize drop-down.
158      * 
159      * @param part the part in which the action is run or <code>null</code> if the action
160      * is not being run in a workbench part.
161      */
162     public void run(IWorkbenchPart part);
163     
164     /**
165      * Initializes this participant with the given participant state.  
166      * A memento is passed to the participant which contains a snapshot 
167      * of the participants state from a previous session.
168      * <p>
169      * This method is automatically called by the team plugin shortly after
170      * participant construction. It marks the start of the views
171      * lifecycle. Clients must not call this method.
172      * </p> 
173      * @param secondaryId the secondayId of this participant instance or <code>null</code>
174      * if this participant doesn't support multiple instances.
175      * @param memento the participant state or <code>null</code> if there 
176      * is no previous saved state
177      * @exception PartInitException if this participant was not initialized 
178      * successfully
179      */
180     public void init(String   secondaryId, IMemento memento) throws PartInitException;
181     
182     /**
183      * Disposes of this synchronize participant and is called to free the 
184      * resources associated with a participant. When a participant is added
185      * to the {@link ISynchronizeManager} this method is called when the
186      * manager is shutdown or the participant is removed from the manager.
187      * </p><p>
188      * Within this method a participant may release any resources, fonts, images, etc. 
189      * held by this part.  It is also very important to remove all listeners.
190      * </p><p>
191      * Clients should not call this method (the synchronize manager calls this 
192      * method at appropriate times).
193      * </p>
194      */
195     public void dispose();
196     
197     /**
198      * Saves the participants object state within the memento. This state
199      * will be available when the participant is restored via <code>init</code>.
200      * <p>
201      * This method can be called multiple times during the lifetime of the
202      * participant object.
203      * </p>
204      * @param memento a memento to receive the object state
205      */
206     public void saveState(IMemento memento);
207     
208     /**
209      * Adds a listener for changes to properties of this synchronize
210      * participant. Has no effect if an identical listener is already
211      * registered.
212      * <p>
213      * The changes supported by the synchronize view are as follows:
214      * <ul>
215      * <li><code>IBasicPropertyConstants.P_TEXT</code>- indicates the name
216      * of a synchronize participant has changed</li>
217      * <li><code>IBasicPropertyConstants.P_IMAGE</code>- indicates the
218      * image of a synchronize participant has changed</li>
219      * </ul></p>
220      * <p>
221      * Clients may define additional properties as required.
222      * </p>
223      * @param listener a property change listener
224      */
225     public void addPropertyChangeListener(IPropertyChangeListener listener);
226     
227     /**
228      * Removes the given property listener from this synchronize participant.
229      * Has no effect if an identical listener is not already registered.
230      * 
231      * @param listener a property listener
232      */
233     public void removePropertyChangeListener(IPropertyChangeListener listener);
234     
235     /**
236      * Prepare the given element and compare configuration for use with a compare editor
237      * input.
238      * @param element the sync model element whose contents are about to be displayed to the user
239      *      in a compare editor or compare dialog
240      * @param configuration the compare configuration that will be used to configure the compare editor or dialog
241      * @param monitor a progress monitor that can be used if contacting a server to prepare the element and configuration
242      * @throws TeamException if an error occurred that should prevent the display of the compare editor containing
243      *      the element
244      * 
245      * @since 3.1
246      */
247     public void prepareCompareInput(
248             ISynchronizeModelElement element, 
249             CompareConfiguration configuration, 
250             IProgressMonitor monitor) 
251                 throws TeamException;
252 
253     /**
254      * Return the list of preference pages that are associated with this participant
255      * @return the list of preference pages that are associated with this participant
256      * @since 3.1
257      */
258     public PreferencePage[] getPreferencePages();
259 }
260
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags