import org.eclipse.core.runtime.IPath;

import org.eclipse.core.runtime.IProgressMonitor;

import org.eclipse.core.runtime.QualifiedName;

import org.eclipse.vcm.provider.TeamProviderException;

/**

* The team provider interface defines the API that third-party providers should implement to

* offer target management and browsing through Eclipse. Implementations should adhere to the documentation for the APIs

* to ensure that the caller gets a consistent team experience.

public interface ITeamProvider {

/**

* Returns a qualified name that uniquely identifies this provider type. The qualified

* name may include a provider version number and other provider-specific information.

*

* The qualified name is a constant used to organize provider types, it is not displayed

* to users. For example:

* <pre>

* new QualifedName("org.eclipse.team.provider.foo", "foo type provider V1.0");

* </pre>

* @return the provider's qualified name.

* @see QualifiedName

public QualifiedName getType();

/**

* Informs the provider that a local resource is to be the subject of further API calls that

* require a managed resource.

*

* Some providers may use this call to initialize data structures or prepare the repository for

* future API calls on this local resource; others may do nothing on this call other than

* remember that the resource has been managed.

*

* If the resource is already being managed then this call has no effect. If the provider is

* incapable of managing this resource it throws an exception.

*

* Note that being managed not the same as being version-controlled. In

* particular, providers are not required to maintain vesions of their managed resources

* (though they may do so), and, where they do, the life-cycle of managed resources is

* not the same as that of version-controlled resources. A resource will be managed before

* it is initially checked-in to the provider, and unmanaging a resource does not imply

* removing it from version control.

* @param resource the local resource that is to be managed.

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @throws TeamProviderException if the resource cannot be managed. Valid exception

* status codes include:

* <ul>

* <li>UNABLE</li>

* </ul>

* @see isManaged(IResource)

* @see unmanage(IResource)

public void manage(IResource[] resources, int depth, IProgressMonitor progress) throws TeamProviderException;

/**

* Answers whether the local resource is being managed by the receiver.

* @param resource the resource that is being tested.

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @return <code>true</code> if the resource is being managed by this provider, or

* <code>false</code> if it is not being managed by this provider.

* @throws TeamProviderException if there is a problem determining the managed status of

* the resource

* @see manage(IResource)

* @see unmanage(IResource)

public boolean isManaged(IResource resource, IProgressMonitor progress) throws TeamProviderException;

/**

* Indicates to the provider that the local resource is no longer the subject of provider

* calls that require a managed resource.

*

* Some implementations will use this call to destroy data structures relating to the

* local resource, others will do nothing.

*

* If the local resource is not being managed by the provider then this method has

* no effect.

*

* Note: this method must not have a visible effect on the corresponding

* remote resource, if any. In particular, this method does not delete or un-release

* a remote resource.

* @param resources the array of local resources that are to be unmanaged.

* @param depth the depth to traverse the given resources, taken from <code>IResource</code>

* constants.

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @throws TeamProviderException if there is a problem unmanaging one or more of the resources.

* The exception will contain multiple statuses, one for each resource in the <code>resources</code>

* array. Possible status codes include:

* <ul>

* <li>UNMANAGED_RESOURCE</li>

* </ul>

* @see manage(IResource)

* @see isManaged(IResource)

public void unmanage(IResource[] resources, int depth, IProgressMonitor progress) throws TeamProviderException;

/**

* Updates the local resource to have the same content as the corresponding remote

* resource, and makes this new content the 'base' state for this resource.

*

* Before making this call the local resource must have been managed.

*

* Note that it is the provider's responsibility to identify the fetched state of a resource

* both locally (by file system last-modified timestamp) and remotely (e.g., by repository

* timestamp, E-Tag, version identifier, etc.). This fetched state is called the base

* of this resource and is used to answer the <code>isDirty()</code> and <code>

* isOutOfDate()</code> interrogation.

* @param resources an array of local resources to update from the corresponding remote

* resources.

* @param depth the depth to traverse the given resources, taken from <code>IResource</code>

* constants.

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @throws TeamProviderException if there is a problem getting one or more of the resources. The

* exception will contain multiple statuses, one for each resource in the <code>resources</code>

* array. Possible status codes include:

* <ul>

* <li>UNMANAGED_RESOURCE</li>

* <li>NO_REMOTE_RESOURCE</li>

* </ul>

public void get(IResource[] resources, int depth, IProgressMonitor progress) throws TeamProviderException;

/**

* Changes the state of the local resource from checked-out to checked-in, and commits the content

* of the checked-in local resource.

*

* If a remote resource does not exist this method creates a new remote resource with the same content

* as the given local resource. The local resource is said to correspond to the new remote resource.

*

* If a corresponding remote resource already exists, and it is in a checked-out state, then checkin

* simply updates the remote resource content. It is envisaged that where the server maintains resource

* versions, checkin creates a new version of the remote resource.

*

* The base state of the local resource becomes the state in which it was checked-in. The committed

* changes to the remote resource become the release state of that resource.

* @param resources an array of local resources to be checked-in.

* @param the depth to traverse the given resources, taken from <code>IResource</code>

* constants.

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @throws TeamProviderException if there is a problem checking-in one or more of the resources.

* The exception will contain multiple statuses, one for each resource in the <code>resources</code>

* array. Possible status codes include:

* <ul>

* <li>UNMANAGED_RESOURCE</li>

* <li>NOT_CHECKED_OUT</li>

* </ul>

* @see checkout(IResource[], int, IProgressMonitor)

public void checkin(IResource[] resources, int depth, IProgressMonitor progress) throws TeamProviderException;

/**

* Changes the state of the local resource from checked-in to checked-out. Where the given

* resource is a folder, all members of the resource are also checked-out.

*

* The check-out operation is deliberately described as only effecting a state change on

* local resources. Implementations may optimistically flag the state change locally and rely on

* resolving conflicts during check-in, or they may pessimistically lock the remote resource

* during a check-out to avoid conflicts. The provider API does not subscribe to either model

* and supports each equally.

*

* Where checkout is applied to a resource that is already checked-out the method has no

* effect.

* @param resources the array of local resources to be checked-out.

* @param depth the depth to traverse the given resources, taken from <code>IResource</code>

* constants.

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @throws TeamProviderException if there is a problem checking-out one or more of the resources.

* The exception will contain multiple statuses, one for each resource in the <code>resources</code>

* array. Possible status codes include:

* <ul>

* <li>UNMANAGED_RESOURCE</li>

* <li>NOT_CHECKED_IN</li>

* </ul>

* @see checkin(IResource[], int, IProgressMonitor)

public void checkout(IResource[] resources, int depth, IProgressMonitor progress) throws TeamProviderException;

/**

* Changes the state of the remote resource from checked-out to checked-in without updating the contents

* of the remote resource.

*

* Note that where the provider is a versioning provider, it is envisaged (though not required) that the

* uncheckout operation does not create a new version.

*

* Note also that <code>uncheckout()</code> does not affect the local resource, the caller is required to

* perform a <code>get()</code> to revert the local resource if that is required (otherwise the local resource

* will be left with the changes that were made while the remote resource was checked-out.

* @param resources an array of the local resources that are to be unchecked-out.

* @param depth the depth to traverse the given resources, taken from <code>IResource</code>

* constants.

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @throws TeamProviderException if there is a problem undoing the check-out of one or more of

* the resources. The exception will contain multiple statuses, one for each resource in the

* <code>resources</code> array. Possible status codes include:

* <ul>

* <li>UNMANAGED_RESOURCE</li>

* <li>NOT_CHECKED_OUT</li>

* </ul>

* @see checkin(IResource)

* @see uncheckout(IResource)

public void uncheckout(IResource[] resources, int depth, IProgressMonitor progress) throws TeamProviderException;

/**

* Deletes the released remote resource corresponding to the given local resource

* (i.e. 'unrelease').

*

* The notion of delete is simply to make the released resource unavailable, i.e., upon successful

* completion of this API call, some API calls will throw an exception because the remote resource

* no longer exists. Where the provider supports versioning it is not specified whether the delete

* operation makes the version forever unavailable, or indeed whether the entire history is made

* unavailable.

*

* If there is no corresponding remote resource then an exception is thrown.

*

* After the API call has completed the local resource becomes unmanaged.

*

* Note that the <code>IResource</code>'s passed as arguments may be non-existant in the

* workbench, the typical case is when such a resource has been received in a core callback.

*

* The reource may be checked-in or checked-out prior to deletion.

* @param resources the array of resources to be deleted.

* @param depth the depth to traverse the given resources, taken from <code>IResource</code>

* constants.

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @throws TeamProviderException if there is a problem deleting one or more of

* the resources. The exception will contain multiple statuses, one for each resource in the

* <code>resources</code> array. Possible status codes include:

* <ul>

* <li>UNMANAGED_RESOURCE</li>

* <li>NO_REMOTE_RESOURCE</li>

* </ul>

public void delete(IResource[] resources, int depth, IProgressMonitor progress) throws TeamProviderException;

/**

* Answers if the local resource state is checked-out.

* @param resource the local resource to test.

* @return <code>true</code> if the resource is checked-out and <code>false</code> if it is not.

* @throws TeamProviderException if there is a problem testing the resource. The exception will

* contain a single status. Possible status codes include:

* <ul>

* <li>UNMANAGED_RESOURCE</li>

* </ul>

* @see checkout(IResource)

public boolean isCheckedOut(IResource[] resources) throws TeamProviderException;

/**

* Answers if the resource has a corresponding remote resource.

*

* Note that every resource that has been checked-in has a released remote resource, so this

* method can be used to determine whether (some state of) this resource has been

* checked-in.

* @param resource the local resource to test.

* @return <code>true</code> if the local resource has a corresponding remote resource,

* and <code>false</code> otherwise.

* @see checkin(IResource)

public boolean isVersionControlled(IResource[] resources);

/**

* Potentially record the fact that the resource has been moved to a new path.

* This also includes renames.

*

* If there is no corresponding remote resource then this method does nothing.

*

* The reource may be checked-in or checked-out prior to deletion.

* @param resource the resource that was moved and whose path is the new path

* @param source the path to the resource before it was moved

* @param progress a progress monitor to indicate the duration of the operation, or

* <code>null</code> if progress reporting is not required.

* @throws TeamProviderException if there is a problem moving the resource

public void move(IResource resource, IPath source, IProgressMonitor progress) throws TeamProviderException;