org.eclipse.team.ui.mapping
Class SynchronizationStateTester

java.lang.Object
  org.eclipse.team.ui.mapping.SynchronizationStateTester

public class SynchronizationStateTester

extends Object

A state change tester is used by logical models to communicate the synchronization state of their logical model elements to the lightweight label decorators of team providers.

There are two different types of elements being decorated: those that have a one-to-one mapping to a resource and those that do not. Those that do should adapt to their corresponding resource. Doing so will ensure that label updates occur when the state of that resource changes (i.e. the team provider will generate label updates for those resources and the modle can translate them to appropriate label updates of their model elements).

For those elements that do not have a one-to-one mapping to resources, the model must do extra work. The purpose of this class is to allow the model to decide when a label update for a logical model element is required and to communicate the dirty state of their logical model elements to the team decorator. For logical model elements, the team decorator will only decorate based on the supervised state and the dirty state. This class provides methods for determining both of these so that logical models can track whether a label update is required for a model element.

Model providers need to re-evaluate the state of a model element whenever a change in the resources occurs by listening to both resource deltas and subscriber change events.

Decoration enablement changes and decoration configuration changes are handled by the IDecoratorManager.update(String) API. A call to this method will result in label changes to all elements. The isDecorationEnabled(Object) API on this class can be used to determine if an element will receive team decorations. If decoration is disabled. team state changes on the element can be ignored.

Since:

3.2

See Also:

IWorkspace.addResourceChangeListener(IResourceChangeListener), Subscriber.addListener(org.eclipse.team.core.subscribers.ISubscriberChangeListener)

Field Summary

static String

PROP_TESTER Constant that is used as the property key on an IDecorationContext.

Constructor Summary

SynchronizationStateTester()
Create a tester that uses the workspace subscriber to obtain the synchronization state of resources.

SynchronizationStateTester(Subscriber subscriber)
Create a tester that obtains the synchroniation state from the given subscriber.

Method Summary

int	getDecoratedStateMask(Object element) Return the mask that indicates what state the appropriate team decorator is capable of decorating.
int	getState(Object element, int stateMask, IProgressMonitor monitor) Return the synchronization state of the given element.
Subscriber	getSubscriber() Return the subscriber associated with this tester.
boolean	isDecorationEnabled(Object element) Return whether decoration is enabled for the given model element.
boolean	isStateDecorationEnabled() Return whether state decoration is enabled for the context to which this tester is associated.
boolean	isSupervised(Object element) Return whether the given element is supervised.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROP_TESTER

public static final String PROP_TESTER

Constant that is used as the property key on an IDecorationContext. If a context passed to a team decorator has this property, the associated state tester will be used by the deocator to determine whether elements have an outgoing change.

See Also:

Constant Field Values

Constructor Detail

SynchronizationStateTester

public SynchronizationStateTester()

Create a tester that uses the workspace subscriber to obtain the synchronization state of resources.

See Also:

Team.getWorkspaceSubscriber()

SynchronizationStateTester

public SynchronizationStateTester(Subscriber subscriber)

Create a tester that obtains the synchroniation state from the given subscriber.

Parameters:

subscriber - the subscriber

Method Detail

isDecorationEnabled

public final boolean isDecorationEnabled(Object element)

Return whether decoration is enabled for the given model element. If decoration is not enabled, the model does not need to fire label change events when the team state of the element changes.

Parameters:

element - the model element

Returns:

whether decoration is enabled for the given model element

getDecoratedStateMask

public final int getDecoratedStateMask(Object element)

Return the mask that indicates what state the appropriate team decorator is capable of decorating. The state is determined by querying the org.eclipse.team.ui.teamDecorators extension point.

The state mask can consist of the following flags:

• The diff kinds of IDiff.ADD, IDiff.REMOVE and IDiff.CHANGE.
• The directions IThreeWayDiff.INCOMING and IThreeWayDiff.OUTGOING.

For convenience sake, if there are no kind flags but there is at least one direction flag then all kinds are assumed.

Parameters:

element - the model element to be decorated

Returns:

the mask that indicates what state the appropriate team decorator will decorate

See Also:

IDiff, IThreeWayDiff

isStateDecorationEnabled

public boolean isStateDecorationEnabled()

Return whether state decoration is enabled for the context to which this tester is associated. If true is returned, team decorators will use the state methods provided on this class to calculate the synchronization state of model elements for the purpose of decoration. If false is returned, team decorators will not decorate the elements with any synchronization related decorations. Subclasses will want to disable state decoration if state decoration is being provided another way (e.g. by a SynchronizationLabelProvider). By default, trueis returned. Subclasses may override.

Returns:

whether state decoration is enabled

getState

public int getState(Object element,
                    int stateMask,
                    IProgressMonitor monitor)
             throws CoreException

Return the synchronization state of the given element. Only the portion of the synchronization state covered by stateMask is returned. By default, this method calls Subscriber.getState(ResourceMapping, int, IProgressMonitor).

Team decorators will use this method to detemine how to decorate the provided element. The getDecoratedStateMask(Object) returns the state that the corresponding team decorator is capable of decorating but the decorator may be configured to decorate only a portion of that state. When the team decorator invokes this method, it will pass the stateMask that it is currently configured to show. If a mask of zero is provided, this indicates that the team decorator is not configured to decorate the synchronization state of model elements.

Subclasses may want to override this method in the following cases:

1. The subclass wishes to fire appropriate label change events when the decorated state of a model element changes. In this case the subclass can override this method to record the stateMask and returned state. It can use this recorded information to determine whether local changes or subscriber changes result in a change in the deocrated sstate of the model element.
2. The subclasses wishes to provide a more accurate change description for a model element that represents only a portion of the file. In this case, the subclass can use the remote file contents available from the subscriber to determine whether

Parameters:

element - the model element

stateMask - the mask that identifies which state flags are desired if present

monitor - a progress monitor

Returns:

the synchronization state of the given element

Throws:

CoreException

See Also:

Subscriber.getState(ResourceMapping, int, IProgressMonitor)

isSupervised

public final boolean isSupervised(Object element)
                           throws CoreException

Return whether the given element is supervised. To determine this, the element is adapted to a resource mapping and, using the mapping's traversals, the subcriber is consulted to determine if the element is supervised. An element is supervised if all the resources covered by it's traversals are supervised.

Parameters:

element - the element being tested

Returns:

whether the given element is supervisied.

Throws:

CoreException - if an error occurres

See Also:

Subscriber.isSupervised(org.eclipse.core.resources.IResource)

getSubscriber

public Subscriber getSubscriber()

Return the subscriber associated with this tester.

Returns:

the subscriber associated with this tester.