Package org.eclipse.team.core.subscribers

## Class Subscriber

- java.lang.Object
- - org.eclipse.team.core.subscribers.Subscriber

Direct Known Subclasses:
  `ResourceVariantTreeSubscriber`

    public abstract class Subscriber
    extends Object

A Subscriber provides synchronization between local resources and a remote location that is used to share those resources.

When queried for the `SyncInfo` corresponding to a local resource using `getSyncInfo(IResource)`, the subscriber should not contact the server. Server round trips should only occur within the `refresh` method of the subscriber. Consequently, the implementation of a subscriber must cache enough state information for a remote resource to calculate the synchronization state without contacting the server. During a refresh, the latest remote resource state information should be fetched and cached. For a subscriber that supports three-way compare, the refresh should also fetch the latest base state unless this is available by some other means (e.g. for some repository tools, the base state is persisted on disk with the local resources).

After a refresh, the subscriber must notify any listeners of local resources whose corresponding remote resource or base resource changed. The subscriber does not need to notify listeners when the state changes due to a local modification since local changes are available through the `IResource` delta mechanism. However, the subscriber must cache enough information (e.g. the local timestamp of when the file was in-sync with its corresponding remote resource) to determine if the file represents an outgoing change so that `SyncInfo` obtained after a delta will indicate that the file has an outgoing change. The subscriber must also notify listeners when roots are added or removed. For example, a subscriber for a repository provider would fire a root added event when a project was shared with a repository. No event is required when a root is deleted as this is available through the `IResource` delta mechanism. It is up to clients to re-query the subscriber when the state of a resource changes locally by listening to `IResource` deltas.

The remote and base states can also include the state for resources that do not exist locally (i.e outgoing deletions or incoming additions). When queried for the members of a local resource, the subscriber should include any children for which a remote exists even if the local does not.

Since:
  3.0

### Constructor Summary

Constructors
`Subscriber()`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`void` `accept​(IResource[] resources, int depth, IDiffVisitor visitor)` Visit any out-of-sync resources in the given resources visited to the given depth.
`void` `accept​(ResourceTraversal[] traversals, IDiffVisitor visitor)` Visit any out-of-sync resources covered by the given traversals.
`void` `addListener​(ISubscriberChangeListener listener)` Adds a listener to this team subscriber.
`void` `collectOutOfSync​(IResource[] resources, int depth, SyncInfoSet set, IProgressMonitor monitor)` Adds all out-of-sync resources (`getKind() !`
`protected void` `fireTeamResourceChange​(ISubscriberChangeEvent[] deltas)` Fires a team resource change event to all registered listeners.
`IDiff` `getDiff​(IResource resource)` Returns synchronization info, in the form of an `IDiff` for the given resource, or `null` if there is no synchronization info because the subscriber does not apply to this resource or the resource is in-sync.
`abstract String` `getName()` Return the name of this subscription, in a format that is suitable for display to an end user.
`abstract IResourceVariantComparator` `getResourceComparator()` Returns the comparison criteria that will be used by the sync info created by this subscriber.
`int` `getState​(ResourceMapping mapping, int stateMask, IProgressMonitor monitor)` Return the synchronization state of the given resource mapping.
`abstract SyncInfo` `getSyncInfo​(IResource resource)` Returns synchronization info for the given resource, or `null` if there is no synchronization info because the subscriber does not apply to this resource.
`abstract boolean` `isSupervised​(IResource resource)` Returns `true` if this resource is supervised by this subscriber.
`abstract IResource[]` `members​(IResource resource)` Returns all non-transient member resources of the given resource.
`abstract void` `refresh​(IResource[] resources, int depth, IProgressMonitor monitor)` Refreshes the resource hierarchy from the given resources and their children (to the specified depth) from the corresponding resources in the remote location.
`void` `refresh​(ResourceTraversal[] traversals, IProgressMonitor monitor)` Refresh the subscriber for the given traversals.
`void` `removeListener​(ISubscriberChangeListener listener)` Removes a listener previously registered with this team subscriber.
`abstract IResource[]` `roots()` Returns the list of root resources this subscriber considers for synchronization.

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### Subscriber

    public Subscriber()

### Method Detail

#### getName

    public abstract String getName()

Return the name of this subscription, in a format that is suitable for display to an end user.

Returns:
  String representing the name of this subscription.

#### isSupervised

    public abstract boolean isSupervised​(IResource resource)
                                  throws TeamException

Returns `true` if this resource is supervised by this subscriber. A supervised resource is one for which this subscriber maintains the synchronization state. Supervised resources are the only resources returned when `members(IResource)` was invoked with the parent of the resource. Returns `false` in all other cases.

Parameters:
  `resource` - the resource being tested
Returns:
  `true` if this resource is supervised, and `false` otherwise
Throws:
  `TeamException` - if an error occurs

#### members

    public abstract IResource[] members​(IResource resource)
                                 throws TeamException

Returns all non-transient member resources of the given resource. The result will include entries for resources that exist either in the workspace or are implicated in an incoming change. Returns an empty list if the given resource exists neither in the workspace nor in the corresponding subscriber location, or if the given resource is transient.

This is a fast operation; the repository is not contacted.

Parameters:
  `resource` - the resource
Returns:
  a list of member resources
Throws:
  `TeamException` - if an error occurs

#### roots

    public abstract IResource[] roots()

Returns the list of root resources this subscriber considers for synchronization. A client should call this method first then can safely call `members` to navigate the resources managed by this subscriber.

Returns:
  a list of resources

#### getSyncInfo

    public abstract SyncInfo getSyncInfo​(IResource resource)
                                  throws TeamException

Returns synchronization info for the given resource, or `null` if there is no synchronization info because the subscriber does not apply to this resource.

Note that sync info may be returned for non-existing or for resources which have no corresponding remote resource.

This method will be quick. If synchronization calculation requires content from the server it must be cached when the subscriber is refreshed. A client should call refresh before calling this method to ensure that the latest information is available for computing the sync state.

The sync-info node returned by this method does not fully describe all types of changes. A more descriptive change can be obtained from the `getDiff(IResource)` method.

Parameters:
  `resource` - the resource of interest
Returns:
  sync info
Throws:
  `TeamException` - if an error occurs
See Also:
  `getDiff(IResource)`

#### getResourceComparator

    public abstract IResourceVariantComparator getResourceComparator()

Returns the comparison criteria that will be used by the sync info created by this subscriber.

Returns:
  the comparator to use when computing sync states for this subscriber.

#### refresh

    public abstract void refresh​(IResource[] resources,
                                 int depth,
                                 IProgressMonitor monitor)
                          throws TeamException

Refreshes the resource hierarchy from the given resources and their children (to the specified depth) from the corresponding resources in the remote location. Resources are ignored in the following cases:

- if they do not exist either in the workspace or in the corresponding remote location
- if the given resource is not supervised by this subscriber
- if the given resource is a closed project (they are ineligible for synchronization)

Typical synchronization operations use the statuses computed by this method as the basis for determining what to do. It is possible for the actual sync status of the resource to have changed since the current local sync status was refreshed. Operations typically skip resources with stale sync information. The chances of stale information being used can be reduced by running this method (where feasible) before doing other operations. Note that this will of course affect performance.

The depth parameter controls whether refreshing is performed on just the given resource (depth= `DEPTH_ZERO`), the resource and its children (depth= `DEPTH_ONE`), or recursively to the resource and all its descendents (depth= `DEPTH_INFINITE`). Use depth `DEPTH_ONE`, rather than depth `DEPTH_ZERO`, to ensure that new members of a project or folder are detected.

This method might change resources; any changes will be reported in a subsequent subscriber resource change event indicating changes to server sync status.

This method contacts the server and is therefore long-running; progress and cancellation are provided by the given progress monitor.

Parameters:
  `resources` - the resources
  `depth` - valid values are `DEPTH_ZERO`, `DEPTH_ONE`, or `DEPTH_INFINITE`
  `monitor` - progress monitor, or `null` if progress reporting and cancellation are not desired
Throws:
  `TeamException` - if this method fails. Reasons include:
  - The server could not be contacted.

#### addListener

    public void addListener​(ISubscriberChangeListener listener)

Adds a listener to this team subscriber. Has no effect if an identical listener is already registered.

Team resource change listeners are informed about state changes that affect the resources supervised by this subscriber.

Parameters:
  `listener` - a team resource change listener

#### removeListener

    public void removeListener​(ISubscriberChangeListener listener)

Removes a listener previously registered with this team subscriber. Has no effect if an identical listener is not registered.

Parameters:
  `listener` - a team resource change listener

#### collectOutOfSync

    public void collectOutOfSync​(IResource[] resources,
                                 int depth,
                                 SyncInfoSet set,
                                 IProgressMonitor monitor)

Adds all out-of-sync resources (`getKind() != SyncInfo.IN_SYNC`) that occur under the given resources to the specified depth. The purpose of this method is to provide subscribers a means of optimizing the determination of all out-of-sync descendants of a set of resources.

If any of the directly provided resources are not supervised by the subscriber, then they should be removed from the set. If errors occur while determining the sync info for the resources, they should be added to the set using `SyncInfoSet.addError`.

Parameters:
  `resources` - the root of the resource subtrees from which out-of-sync sync info should be collected
  `depth` - the depth to which sync info should be collected (one of `IResource.DEPTH_ZERO`, `IResource.DEPTH_ONE`, or `IResource.DEPTH_INFINITE`)
  `set` - the sync info set to which out-of-sync resources should be added (or removed). Any errors should be added to the set as well.
  `monitor` - a progress monitor

#### fireTeamResourceChange

    protected void fireTeamResourceChange​(ISubscriberChangeEvent[] deltas)

Fires a team resource change event to all registered listeners. Only listeners registered at the time this method is called are notified. Listener notification makes use of an `ISafeRunnable` to ensure that client exceptions do not affect the notification to other clients.

#### getDiff

    public IDiff getDiff​(IResource resource)
                  throws CoreException

Returns synchronization info, in the form of an `IDiff` for the given resource, or `null` if there is no synchronization info because the subscriber does not apply to this resource or the resource is in-sync.

Note that a diff may be returned for non-existing or for resources which have no corresponding remote resource.

This method will be quick. If synchronization calculation requires content from the server it must be cached when the subscriber is refreshed. A client should call refresh before calling this method to ensure that the latest information is available for computing the diff.

The diff node returned by this method describes the changes associated with the given resource in more detail than the sync-info returned by calling `getSyncInfo(IResource)`.

Parameters:
  `resource` - the resource of interest
Returns:
  the diff for the resource or `null`
Throws:
  `CoreException` - if an error occurs
  `TeamException` - if errors occur
Since:
  3.2

#### accept

    public void accept​(ResourceTraversal[] traversals,
                       IDiffVisitor visitor)
                throws CoreException

Visit any out-of-sync resources covered by the given traversals. Any resources covered by the traversals are ignored in the following cases:

- if they do not exist either in the workspace or in the corresponding remote location
- if the given resource is not supervised by this subscriber
- if the given resource is a closed project (they are ineligible for synchronization)

Parameters:
  `traversals` - the traversals to be visited
  `visitor` - the visitor
Throws:
  `CoreException` - if an error occurs
  `TeamException` - if errors occur
Since:
  3.2

#### accept

    public void accept​(IResource[] resources,
                       int depth,
                       IDiffVisitor visitor)
                throws CoreException

Visit any out-of-sync resources in the given resources visited to the given depth. Resources are ignored in the following cases:

- if they do not exist either in the workspace or in the corresponding remote location
- if the given resource is not supervised by this subscriber
- if the given resource is a closed project (they are ineligible for synchronization)

Parameters:
  `resources` - the root of the resource subtrees from which out-of-sync sync info should be visited
  `depth` - the depth to which sync info should be collected (one of `IResource.DEPTH_ZERO`, `IResource.DEPTH_ONE`, or `IResource.DEPTH_INFINITE`)
  `visitor` - the visitor
Throws:
  `CoreException` - if errors occur
Since:
  3.2

#### refresh

    public void refresh​(ResourceTraversal[] traversals,
                        IProgressMonitor monitor)
                 throws TeamException

Refresh the subscriber for the given traversals. By default this method calls `refresh(IResource[], int, IProgressMonitor)` for each traversal. Any resources covered by the traversals are ignored in the following cases:

- if they do not exist either in the workspace or in the corresponding remote location
- if the given resource is not supervised by this subscriber
- if the given resource is a closed project (they are ineligible for synchronization)

Subclasses may override.

Parameters:
  `traversals` - the traversals to be refreshed
  `monitor` - a progress monitor
Throws:
  `TeamException` - if errors occur
Since:
  3.2

#### getState

    public int getState​(ResourceMapping mapping,
                        int stateMask,
                        IProgressMonitor monitor)
                 throws CoreException

Return the synchronization state of the given resource mapping. Only return the portion of the synchronization state that matches the provided `stateMask`. The synchronization state flags that are guaranteed to be interpreted by this method are:

- The kind flags `IDiff.ADD`, `IDiff.REMOVE` and `IDiff.CHANGE`. If none of these flags are included then all are assumed.
- The direction flags `IThreeWayDiff.INCOMING` and `IThreeWayDiff.OUTGOING` if the subscriber is a three-way subscriber. If neither are provided, both are assumed.

Other flags can be included and may or may not be interpreted by the subscriber.

An element will only include `IDiff.ADD` in the returned state if all resources covered by the traversals mappings are added. Similarly, `IDiff.REMOVE` will only be included if all the resources covered by the traversals are deleted. Otherwise `IDiff.CHANGE` will be returned.

Parameters:
  `mapping` - the resource mapping whose synchronization state is to be determined
  `stateMask` - the mask that identifies the state flags of interested
  `monitor` - a progress monitor
Returns:
  the synchronization state of the given resource mapping
Throws:
  `CoreException` - if an error occurs
Since:
  3.2
See Also:
  `IDiff`, `IThreeWayDiff`