ITeamStateProvider


1   /*******************************************************************************
2    * Copyright (c) 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.mapping;
12  
13  import org.eclipse.core.resources.mapping.RemoteResourceMappingContext;
14  import org.eclipse.core.resources.mapping.ResourceMappingContext;
15  import org.eclipse.core.runtime.*;
16  import org.eclipse.team.core.RepositoryProviderType;
17  import org.eclipse.team.core.diff.IDiff;
18  import org.eclipse.team.core.diff.IThreeWayDiff;
19  import org.eclipse.team.ui.synchronize.TeamStateProvider;
20  import org.eclipse.team.ui.synchronize.SubscriberTeamStateProvider;
21  
22  /**
23   * A team state provider is used by the {@link SynchronizationStateTester}
24   * to obtain the team state for model elements. A team
25   * state provider is associated with a {@link RepositoryProviderType} using the
26   * adaptable mechanism. A default decoration provider that uses the subscriber
27   * of the type is provided.
28   * <p>
29   * This interface is not intended to be implemented by clients. Clients should
30   * instead subclass {@link TeamStateProvider} or
31   * {@link SubscriberTeamStateProvider}.
32   * 
33   * @see IAdapterManager
34   * @see RepositoryProviderType
35   * @see RepositoryProviderType#getSubscriber()
36   * @see TeamStateProvider
37   * @see SubscriberTeamStateProvider
38   * @see SynchronizationStateTester
39   * 
40   * @since 3.2
41   */
42  public interface ITeamStateProvider {
43  
44      /**
45       * A state mask that can be passed to the {@link #getStateDescription(Object, int, String[], IProgressMonitor)}
46       * method to indicate that only the decorated state flags are desired. It is equivalent to
47       * passing he mask returned from {@link #getDecoratedStateMask(Object)};
48       */
49      public static final int USE_DECORATED_STATE_MASK = -1;
50      
51      /**
52       * Return whether decoration is enabled for the given model element. If
53       * decoration is not enabled, the model does not need to fire label change
54       * events when the team state of the element changes.
55       * 
56       * @param element
57       *            the model element
58       * @return whether decoration is enabled for the given model element
59       */
60      public boolean isDecorationEnabled(Object   element);
61  
62      /**
63       * Return whether the given element has any decorated state.
64       * 
65       * @param element
66       *            the element being decorated
67       * @return whether the given element has any decorated state
68       * @throws CoreException
69       */
70      public boolean hasDecoratedState(Object   element) throws CoreException;
71  
72      /**
73       * Return the mask that indicates what state the appropriate team decorator
74       * is capable of decorating. Clients can used this to obtain the current
75       * decorated state from
76       * {@link #getStateDescription(Object, int, String[], IProgressMonitor)} in
77       * order to determine if the decorated state has changed.
78       * 
79       * <p>
80       * The state mask can consist of the following standard flags:
81       * <ul>
82       * <li>The diff kinds of {@link IDiff#ADD}, {@link IDiff#REMOVE} and
83       * {@link IDiff#CHANGE}.
84       * <li>The directions {@link IThreeWayDiff#INCOMING} and
85       * {@link IThreeWayDiff#OUTGOING}.
86       * </ul>
87       * For convenience sake, if there are no kind flags but there is at least
88       * one direction flag then all kinds are assumed.
89       * <p>
90       * The mask can also consist of flag bits that are unique to the repository
91       * provider associated with the resources that the element maps to.
92       * 
93       * @param element
94       *            the model element to be decorated
95       * @return the mask that indicates what state the appropriate team decorator
96       *         will decorate
97       * @see IDiff
98       * @see IThreeWayDiff
99       */
100     public int getDecoratedStateMask(Object   element);
101 
102     /**
103      * Return the set of property identifiers that represent the set of
104      * properties that the team decorator would decorate for the given model
105      * element.
106      * 
107      * @param element
108      *            the model element to be decorated
109      * @return the set of decorated properties
110      */
111     public String  [] getDecoratedProperties(Object   element);
112 
113     /**
114      * Return the state description for the given element. A <code>null</code>
115      * is return if the element is not decorated or if decoration is disabled.
116      * Only the portion of the synchronization state covered by
117      * <code>stateMask</code> is returned. The <code>stateMask</code> should
118      * be {@link #USE_DECORATED_STATE_MASK} or the mask returned from
119      * {@link #getDecoratedStateMask(Object)} and the requested properties
120      * should be <code>null</code> or the value returned from
121      * {@link #getDecoratedProperties(Object)} if the client wishes to obtain
122      * the current decorated state.
123      * 
124      * @param element
125      *            the model element
126      * @param stateMask
127      *            the mask that identifies which synchronization state flags are
128      *            desired if present
129      * @param properties
130      *            the set of properties that should be included in the result or
131      *            <code>null</code> if the decorated properties are desired
132      * @param monitor
133      *            a progress monitor
134      * @return the state for the given element or <code>null</code>
135      * @throws CoreException
136      */
137     public ITeamStateDescription getStateDescription(Object   element,
138             int stateMask, String  [] properties, IProgressMonitor monitor)
139             throws CoreException;
140 
141     /**
142      * Return a resource mapping context that gives access to the remote state
143      * of the resources associated with the provider. If a
144      * {@link RemoteResourceMappingContext} is returned, then the client may
145      * access the remote state.
146      * 
147      * @param element
148      *            the element for which remote contents are desired
149      * 
150      * @return a resource mapping context that gives access to the remote state
151      *         of the resources associated with the provider
152      */
153     public ResourceMappingContext getResourceMappingContext(Object   element);
154 
155     /**
156      * Add a decorated state change listener to the provider.
157      * Adding the same listener more than once has no effect.
158      * 
159      * @param listener
160      *            the listener
161      */
162     public void addDecoratedStateChangeListener(
163             ITeamStateChangeListener listener);
164 
165     /**
166      * Remove the decorated state change listener to the provider.
167      * Removing a listener that is not registered has no effect.
168      * 
169      * @param listener
170      *            the listener
171      */
172     public void removeDecoratedStateChangeListener(
173             ITeamStateChangeListener listener);
174 
175 }
176
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags