org.eclipse.team.core.subscribers
Class SubscriberResourceMappingContext

java.lang.Object
  org.eclipse.core.resources.mapping.ResourceMappingContext
      org.eclipse.core.resources.mapping.RemoteResourceMappingContext
          org.eclipse.team.core.subscribers.SubscriberResourceMappingContext

public class SubscriberResourceMappingContext

extends org.eclipse.core.resources.mapping.RemoteResourceMappingContext

A resource mapping context that provides the client access to the remote state of local resources using a subscriber. It uses a SyncInfoFilter to determine whether the local contents differ from the remote contents. This allows the context to be used for different operations (check-in, update and replace).

EXPERIMENTAL. This class or interface has been added as part of a work in progress. There is a guarantee neither that this API will work nor that it will remain the same. Please do not use this API without consulting with the Platform/Team team.

Since:

3.2

Field Summary

Fields inherited from class org.eclipse.core.resources.mapping.RemoteResourceMappingContext

FILE_CONTENTS_REQUIRED, NONE

Fields inherited from class org.eclipse.core.resources.mapping.ResourceMappingContext

LOCAL_CONTEXT

Constructor Summary

SubscriberResourceMappingContext(Subscriber subscriber, boolean autoRefresh)
Create a resource mapping context for the given subscriber

Method Summary

boolean	contentDiffers(IFile file, IProgressMonitor monitor)
static org.eclipse.core.resources.mapping.RemoteResourceMappingContext	createContext(Subscriber subscriber) Return a resource mapping context suitable for comparison operations.
IStorage	fetchBaseContents(IFile file, IProgressMonitor monitor) For three-way comparisons, returns an instance of IStorage in order to allow the caller to access the contents of the base resource that corresponds to the given local resource.
IResource[]	fetchMembers(IContainer container, IProgressMonitor monitor) Returns the list of member resources whose corresponding remote resources are members of the corresponding remote resource of the given local container.
IStorage	fetchRemoteContents(IFile file, IProgressMonitor monitor) Returns an instance of IStorage in order to allow the caller to access the contents of the remote that corresponds to the given local resource.
IProject[]	getProjects() Return the list of projects that apply to this context.
boolean	hasLocalChange(IResource resource, IProgressMonitor monitor) For three-way comparisons, this method indicates whether local modifications have been made to the given resource.
boolean	hasRemoteChange(IResource resource, IProgressMonitor monitor) For two-way comparisons, return whether the contents of the corresponding remote differs from the content of the local file in the context of the current operation.
boolean	isThreeWay() Return true if the context is associated with an operation that is using a three-way comparison and false if it is using a two-way comparison.
protected void	refresh(IResource[] resources, int depth, int flags, IProgressMonitor monitor) Refresh the subscriber and cache the fact that the resources were refreshed by calling the refreshed method.
void	refresh(org.eclipse.core.resources.mapping.ResourceTraversal[] traversals, int flags, IProgressMonitor monitor) Refresh the known remote state for any resources covered by the given traversals.
protected void	refreshed(IResource[] resources, int depth) Record the fact that the resources have been refreshed to the given depth.
void	setAutoRefresh(boolean autoRefresh) Set whether the context should refresh the state of resources when their state is requested.

Methods inherited from class java.lang.Object

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

Constructor Detail

SubscriberResourceMappingContext

public SubscriberResourceMappingContext(Subscriber subscriber,
                                        boolean autoRefresh)

Create a resource mapping context for the given subscriber

Parameters:

subscriber - the subscriber from the local contents

Method Detail

createContext

public static org.eclipse.core.resources.mapping.RemoteResourceMappingContext createContext(Subscriber subscriber)

Return a resource mapping context suitable for comparison operations. Comparisons require that any out-of-sync resources have contents that differ.

Returns:

a resource mapping context suitable for compare operations

hasRemoteChange

public final boolean hasRemoteChange(IResource resource,
                                     IProgressMonitor monitor)
                              throws CoreException

Description copied from class: org.eclipse.core.resources.mapping.RemoteResourceMappingContext

For two-way comparisons, return whether the contents of the corresponding remote differs from the content of the local file in the context of the current operation. By this we mean that this method will return true if the remote contents differ from the local contents.

For three-way comparisons, return whether the contents of the corresponding remote differ from the contents of the base. In other words, this method returns true if the corresponding remote has changed since the last time the local resource was updated with the remote contents.

For two-way comparisons, return true if the remote contents differ from the local contents. In this case, this method is equivalent to RemoteResourceMappingContext.hasLocalChange(IResource, IProgressMonitor)

This can be used by clients to determine if they need to fetch the remote contents in order to determine if the resources that constitute the model element are different in the remote location. If the local file exists and the remote file does not, or the remote file exists and the local does not then the contents will be said to differ (i.e. true is returned). Also, implementors will most likely use a timestamp based comparison to determine if the contents differ. This may lead to a situation where true is returned but the actual contents do not differ. Clients must be prepared handle this situation.

Parameters:

resource - the local resource

monitor - a progress monitor, or null if progress reporting is not desired

Returns:

whether the contents of the corresponding remote differ from the base.

Throws:

CoreException - if the contents could not be compared. Reasons include:

• The server could not be contacted for some reason.
• The corresponding remote resource is not a container (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).

hasLocalChange

public boolean hasLocalChange(IResource resource,
                              IProgressMonitor monitor)
                       throws CoreException

Description copied from class: org.eclipse.core.resources.mapping.RemoteResourceMappingContext

For three-way comparisons, this method indicates whether local modifications have been made to the given resource. For two-way comparisons, calling this method has the same effect as calling RemoteResourceMappingContext.hasRemoteChange(IResource, IProgressMonitor).

Parameters:

resource - the resource being tested

monitor - a progress monitor

Returns:

whether the resource contains local modifications

Throws:

CoreException - if the contents could not be compared. Reasons include:

• The server could not be contacted for some reason.
• The corresponding remote resource is not a container (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).

fetchRemoteContents

public final IStorage fetchRemoteContents(IFile file,
                                          IProgressMonitor monitor)
                                   throws CoreException

Description copied from class: org.eclipse.core.resources.mapping.RemoteResourceMappingContext

Returns an instance of IStorage in order to allow the caller to access the contents of the remote that corresponds to the given local resource. If the remote file does not exist, null is returned. The provided local file handle need not exist locally. A exception is thrown if the corresponding remote resource is not a file.

This method may be long running as a server may need to be contacted to obtain the contents of the file.

Parameters:

file - the local file

monitor - a progress monitor, or null if progress reporting is not desired

Returns:

a storage that provides access to the contents of the local resource's corresponding remote resource. If the remote file does not exist, null is returned

Throws:

CoreException - if the contents could not be fetched. Reasons include:

• The server could not be contacted for some reason.
• The corresponding remote resource is not a container (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).

fetchBaseContents

public final IStorage fetchBaseContents(IFile file,
                                        IProgressMonitor monitor)
                                 throws CoreException

Description copied from class: org.eclipse.core.resources.mapping.RemoteResourceMappingContext

For three-way comparisons, returns an instance of IStorage in order to allow the caller to access the contents of the base resource that corresponds to the given local resource. The base of a resource is the contents of the resource before any local modifications were made. If the base file does not exist, or if this is a two-way comparison, null is returned. The provided local file handle need not exist locally. A exception is thrown if the corresponding base resource is not a file.

This method may be long running as a server may need to be contacted to obtain the contents of the file.

Parameters:

file - the local file

monitor - a progress monitor, or null if progress reporting is not desired

Returns:

a storage that provides access to the contents of the local resource's corresponding remote resource. If the remote file does not exist, null is returned

Throws:

CoreException - if the contents could not be fetched. Reasons include:

• The server could not be contacted for some reason.
• The corresponding remote resource is not a container (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).

fetchMembers

public final IResource[] fetchMembers(IContainer container,
                                      IProgressMonitor monitor)
                               throws CoreException

Description copied from class: org.eclipse.core.resources.mapping.RemoteResourceMappingContext

Returns the list of member resources whose corresponding remote resources are members of the corresponding remote resource of the given local container. The container need not exist locally and the result may include entries that do not exist locally and may not include all local children. An empty list is returned if the remote resource which corresponds to the container is empty or if the remote does not exist. An exception is thrown if the corresponding remote is not capable of having members.

This method may be long running as a server may need to be contacted to obtain the members of the container's corresponding remote resource.

Parameters:

container - the local container

monitor - a progress monitor, or null if progress reporting is not desired

Returns:

a list of member resources whose corresponding remote resources are members of the remote counterpart of the given container or null if the remote does not exist.

Throws:

CoreException - if the members could not be fetched. Reasons include:

• The server could not be contacted for some reason.
• The corresponding remote resource is not a container (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).

refresh

public final void refresh(org.eclipse.core.resources.mapping.ResourceTraversal[] traversals,
                          int flags,
                          IProgressMonitor monitor)
                   throws CoreException

Description copied from class: org.eclipse.core.resources.mapping.RemoteResourceMappingContext

Refresh the known remote state for any resources covered by the given traversals. Clients who require the latest remote state should invoke this method before invoking any others of the class. Mappings can use this method as a hint to the context provider of which resources will be required for the mapping to generate the proper set of traversals.

Note that this is really only a hint to the context provider. It is up to implementors to decide, based on the provided traversals, how to efficiently perform the refresh. In the ideal case, calls to RemoteResourceMappingContext.hasRemoteChange(IResource, IProgressMonitor) and RemoteResourceMappingContext.fetchMembers(org.eclipse.core.resources.IContainer, org.eclipse.core.runtime.IProgressMonitor) would not need to contact the server after a call to a refresh with appropriate traversals. Also, ideally, if RemoteResourceMappingContext.FILE_CONTENTS_REQUIRED is on of the flags, then the contents for these files will be cached as efficiently as possible so that calls to RemoteResourceMappingContext.fetchRemoteContents(org.eclipse.core.resources.IFile, org.eclipse.core.runtime.IProgressMonitor) will also not need to contact the server. This may not be possible for all context providers, so clients cannot assume that the above mentioned methods will not be long running. It is still advisable for clients to call RemoteResourceMappingContext.refresh(org.eclipse.core.resources.mapping.ResourceTraversal[], int, org.eclipse.core.runtime.IProgressMonitor) with as much details as possible since, in the case where a provider is optimized, performance will be much better.

Parameters:

traversals - the resource traversals that indicate which resources are to be refreshed

flags - additional refresh behavior. For instance, if RemoteResourceMappingContext.FILE_CONTENTS_REQUIRED is one of the flags, this indicates that the client will be accessing the contents of the files covered by the traversals. RemoteResourceMappingContext.NONE should be used when no additional behavior is required

monitor - a progress monitor, or null if progress reporting is not desired

Throws:

CoreException - if the refresh fails. Reasons include:

• The server could not be contacted for some reason.

refresh

protected void refresh(IResource[] resources,
                       int depth,
                       int flags,
                       IProgressMonitor monitor)
                throws TeamException

Refresh the subscriber and cache the fact that the resources were refreshed by calling the refreshed method. The default implementation only refreshes the state and does not fetch contents in the FILE_CONTENTS_REQUIRED flag is passed. It is up to subclass to handle this.

Parameters:

resources - the resources to be refreshed

depth - the depth of the refresh

flags - the flags that indicate extra state that should be fetched

monitor - a progress monitor

Throws:

TeamException

refreshed

protected final void refreshed(IResource[] resources,
                               int depth)

Record the fact that the resources have been refreshed to the given depth. This is done so that accesses to refreshed resources will not need to perform another refresh.

Parameters:

resources - the resources that were refreshed

depth - the depth to which the resources were refreshed

setAutoRefresh

public void setAutoRefresh(boolean autoRefresh)

Set whether the context should refresh the state of resources when their state is requested. The context keeps track of what resources were refreshed and only auto-refreshes a resource once.

Parameters:

autoRefresh - whether the context should refresh the state of resources when their state is requested

isThreeWay

public boolean isThreeWay()

Description copied from class: org.eclipse.core.resources.mapping.RemoteResourceMappingContext

Return true if the context is associated with an operation that is using a three-way comparison and false if it is using a two-way comparison.

Returns:

whether the context is a three-way or two-way

contentDiffers

public boolean contentDiffers(IFile file,
                              IProgressMonitor monitor)
                       throws CoreException

Throws:

CoreException

getProjects

public IProject[] getProjects()

Description copied from class: org.eclipse.core.resources.mapping.RemoteResourceMappingContext

Return the list of projects that apply to this context. In other words, the context is only capable of querying the remote state for projects that are contained in the returned list.

Returns:

the list of projects that apply to this context