KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > team > ui > synchronize > 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags