public abstract class Subscriber extends Object
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.
Constructor and Description |
---|
Subscriber() |
Modifier and Type | Method and Description |
---|---|
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.
|
public abstract String getName()
public abstract boolean isSupervised(IResource resource) throws TeamException
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.resource
- the resource being testedtrue
if this resource is supervised, and false
otherwiseTeamException
public abstract IResource[] members(IResource resource) throws TeamException
This is a fast operation; the repository is not contacted.
resource
- the resourceTeamException
public abstract IResource[] roots()
members
to navigate the resources managed by this
subscriber.public abstract SyncInfo getSyncInfo(IResource resource) throws TeamException
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.
resource
- the resource of interestTeamException
getDiff(IResource)
public abstract IResourceVariantComparator getResourceComparator()
public abstract void refresh(IResource[] resources, int depth, IProgressMonitor monitor) throws TeamException
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.
resources
- the resourcesdepth
- valid values are DEPTH_ZERO
,
DEPTH_ONE
, or DEPTH_INFINITE
monitor
- progress monitor, or null
if progress
reporting and cancellation are not desiredTeamException
- if this method fails. Reasons include:
public void addListener(ISubscriberChangeListener listener)
Team resource change listeners are informed about state changes that affect the resources supervised by this subscriber.
listener
- a team resource change listenerpublic void removeListener(ISubscriberChangeListener listener)
listener
- a team resource change listenerpublic void collectOutOfSync(IResource[] resources, int depth, SyncInfoSet set, IProgressMonitor monitor)
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
.
resources
- the root of the resource subtrees from which out-of-sync sync info should be collecteddepth
- 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 monitorprotected void fireTeamResourceChange(ISubscriberChangeEvent[] deltas)
ISafeRunnable
to ensure that
client exceptions do not affect the notification to other clients.public IDiff getDiff(IResource resource) throws CoreException
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)
.
resource
- the resource of interestnull
CoreException
TeamException
- if errors occurpublic void accept(ResourceTraversal[] traversals, IDiffVisitor visitor) throws CoreException
traversals
- the traversals to be visitedvisitor
- the visitorCoreException
TeamException
- if errors occurpublic void accept(IResource[] resources, int depth, IDiffVisitor visitor) throws CoreException
resources
- the root of the resource subtrees from which out-of-sync
sync info should be visiteddepth
- the depth to which sync info should be collected (one of
IResource.DEPTH_ZERO
,
IResource.DEPTH_ONE
, or
IResource.DEPTH_INFINITE
)visitor
- the visitorCoreException
- if errors occurpublic void refresh(ResourceTraversal[] traversals, IProgressMonitor monitor) throws TeamException
refresh(IResource[], int, IProgressMonitor)
for each traversal. Any resources
covered by the traversals are ignored in the following cases:
Subclasses may override.
traversals
- the traversals to be refreshedmonitor
- a progress monitorTeamException
- if errors occurpublic int getState(ResourceMapping mapping, int stateMask, IProgressMonitor monitor) throws CoreException
stateMask
. The synchronization state flags that are
guaranteed to be interpreted by this method are:
IDiff.ADD
, IDiff.REMOVE
and IDiff.CHANGE
.
If none of these flags are included then all are assumed.
IThreeWayDiff.INCOMING
and IThreeWayDiff.OUTGOING
if the
subscriber is a three-way subscriber. If neither are provided, both are assumed.
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.
mapping
- the resource mapping whose synchronization state is to be determinedstateMask
- the mask that identifies the state flags of interestedmonitor
- a progress monitorCoreException
IDiff
,
IThreeWayDiff
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.