KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > team > ui > mapping > SynchronizationStateTester


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.IResourceChangeListener;
14 import org.eclipse.core.resources.IWorkspace;
15 import org.eclipse.core.resources.mapping.ResourceMapping;
16 import org.eclipse.core.runtime.CoreException;
17 import org.eclipse.core.runtime.IProgressMonitor;
18 import org.eclipse.jface.viewers.IDecorationContext;
19 import org.eclipse.team.core.diff.IDiff;
20 import org.eclipse.team.core.subscribers.Subscriber;
21 import org.eclipse.team.internal.ui.TeamUIPlugin;
22 import org.eclipse.ui.IDecoratorManager;
23
24 /**
25  * A state change tester is used by logical models to communicate the
26  * synchronization state of their logical model elements to
27  * the lightweight label decorator of a team provider.
28  * <p>
29  * There are two different types of elements being decorated: those
30  * that have a one-to-one mapping to a resource and those that do not.
31  * Those that do should adapt to their corresponding resource. Doing
32  * so will ensure that label updates occur when the state of that
33  * resource changes (i.e. the team provider will generate label updates
34  * for those resources and the model can translate them to appropriate
35  * label updates of their model elements).
36  * <p>
37  * For those elements that do not have a one-to-one mapping to resources,
38  * the model must do extra work. The purpose of this class is to allow
39  * the model to decide when a label update for a logical model element is
40  * required and to communicate the dirty state of their logical model
41  * elements to the team decorator.
42  * <p>
43  * Model providers need to re-evaluate the state of a
44  * model element whenever a change in the resources occurs by listening
45  * to both resource deltas and change events from the team state provider
46  * ({@link #getTeamStateProvider()}.
47  * <p>
48  * Decoration enablement changes and decoration configuration changes
49  * are handled by the {@link IDecoratorManager#update(String)} API.
50  * A call to this method will result in label changes to all elements.
51  * The {@link #isDecorationEnabled(Object)} API on this class can
52  * be used to determine if an element will receive team decorations.
53  * If decoration is disabled. team state changes on the element can
54  * be ignored.
55  * <p>
56  * Clients may subclass this class.
57  *
58  * @since 3.2
59  * @see IWorkspace#addResourceChangeListener(IResourceChangeListener)
60  * @see Subscriber#addListener(org.eclipse.team.core.subscribers.ISubscriberChangeListener)
61  */
62 public class SynchronizationStateTester {
63     
64     /**
65      * Constant that is used as the property key on an
66      * {@link IDecorationContext}. Model based views can assign their state
67      * test to this property in the decoration context. If a context passed to a
68      * team decorator has this property, the associated state tester will be
69      * used by the decorator to determine the team state of the elements being
70      * decorated.
71      */
72     public static final String JavaDoc PROP_TESTER = "org.eclipse.team.ui.syncStateTester"; //$NON-NLS-1$
73
74     /**
75      * Create a synchronization state tester.
76      */
77     public SynchronizationStateTester() {
78         super();
79     }
80     
81     /**
82      * Return whether state decoration is enabled for the context
83      * to which this tester is associated. If <code>true</code>
84      * is returned, a team decorator will use the state methods provided
85      * on this class to calculate the synchronization state of model
86      * elements for the purpose of decoration. If <code>false</code>
87      * is returned, a team decorator will not decorate the elements with any
88      * synchronization related decorations. Subclasses will want to disable
89      * state decoration if state decoration is being provided another way
90      * (e.g. by a {@link SynchronizationLabelProvider}). By default,
91      * <code>true</code>is returned. Subclasses may override.
92      * @return whether state decoration is enabled
93      */
94     public boolean isStateDecorationEnabled() {
95         return true;
96     }
97     
98     /**
99      * Return whether decoration is enabled for the given model element in the
100      * context to which this tester is associated. By default, the value
101      * returned from {@link #isStateDecorationEnabled()} is used but subclasses
102      * may override to disable decoration of particular elements.
103      * <p>
104      * A team decorator should call this method before decorating a model
105      * element. If the method returns <code>true</code>, no team state
106      * decorations should be applied to the model element. Otherwise, the
107      * {@link #getState(Object, int, IProgressMonitor)} should be consulted in
108      * order to determine what state to decorate.
109      *
110      * @param element
111      * the model element
112      * @return whether decoration is enabled for the given model element
113      */
114     public boolean isDecorationEnabled(Object JavaDoc element) {
115         return isStateDecorationEnabled();
116     }
117
118     /**
119      * Return the synchronization state of the given element. Only the portion
120      * of the synchronization state covered by <code>stateMask</code> is
121      * returned. By default, this method calls
122      * {@link Subscriber#getState(ResourceMapping, int, IProgressMonitor)}.
123      * <p>
124      * A team decorator will use this method to determine how to decorate the
125      * provided element. The {@link ITeamStateProvider#getDecoratedStateMask(Object)} returns the
126      * state that the corresponding team decorator is capable of decorating but
127      * the decorator may be configured to decorate only a portion of that state.
128      * When the team decorator invokes this method, it will pass the stateMask that
129      * it is currently configured to show. If a mask of zero is provided, this indicates
130      * that the team decorator is not configured to decorate the synchronization state
131      * of model elements.
132      * <p>
133      * Subclasses may want to override this method in the following cases:
134      * <ol>
135      * <li>The subclass wishes to fire appropriate label change events when the
136      * decorated state of a model element changes. In this case the subclass
137      * can override this method to record the stateMask and returned state. It can
138      * use this recorded information to determine whether local changes or subscriber changes
139      * result in a change in the decorated state of the model element.
140      * <li>The subclasses wishes to provide a more accurate change description for a model
141      * element that represents only a portion of the file. In this case, the subclass can
142      * use the remote file contents available from the provider to determine the proper
143      * state for the element.
144      * </ol>
145      *
146      * @param element the model element
147      * @param stateMask the mask that identifies which state flags are desired if
148      * present
149      * @param monitor a progress monitor
150      * @return the synchronization state of the given element
151      * @throws CoreException
152      */
153     public int getState(Object JavaDoc element, int stateMask, IProgressMonitor monitor) throws CoreException {
154         ITeamStateDescription desc = getTeamStateProvider().getStateDescription(element, stateMask, new String JavaDoc[0], monitor);
155         if (desc != null)
156             return desc.getStateFlags();
157         return IDiff.NO_CHANGE;
158     }
159     
160     /**
161      * Return a team state provider that delegates to the appropriate team
162      * provider.
163      * @return a team state provider that delegates to the appropriate team
164      * provider
165      */
166     public final ITeamStateProvider getTeamStateProvider() {
167         return TeamUIPlugin.getPlugin().getDecoratedStateProvider();
168     }
169     
170     /**
171      * A callback to the tester made from the team decorator to notify the
172      * tester that the given element has been decorated with the given state.
173      * The purpose of the callback is to allow the owner of the tester to
174      * cache the decorated state in order to detect whether a future state
175      * change requires a label update for the element.
176      * @param element the element that was decorated
177      * @param description a description of the decorated state of the element
178      */
179     public void elementDecorated(Object JavaDoc element, ITeamStateDescription description) {
180         // do nothing by default
181 }
182     
183
184 }
185
Popular Tags