# Package org.eclipse.team.core.variants

Application programming interfaces for accessing and managing resource variants.

## Package Specification

This package specifies the API for accessing and managing variants for local workspace resources. The classes in this package can be used by Subscribers (see the org.eclipse.team.core.subscribers package) or others. The classes are roughly divided into three categories:

### Access to Resource Variants

The following interfaces define the API required for subscribers to access and manage variants of local resources.

- IResourceVariant: provides access to information about a variant resource, such as it's name, its type (file or container) and its contents.
- IResourceVariantComparator: supports the comparison of a local resource with a variant or the comparison of two variants (if three-way comparison is supported).
- IResourceVariantTree: provides access to a tree of locally cached resource variants along with API to refresh the cached variants.

### Implementing Resource Variants

Several classes are available that provide partial, extandable implementations of the above mentioned interfaces.

- CachedResourceVariant: an IResourceVariant implementation that supports the caching of the contents of the variant. Subclasses must override to provide fecthing of contents.
- AbstractResourceVariantTree: an IResourceVariantTree that contains logic for performing a refresh of the cached resource variants. The caching mechanism is delegated to subclasses as is the fetching of the resource variants.
  - ResourceVariantTree: An AbstractResourceVariantTree that uses a ResourceVariantByteStore to cache the resource variants. Subclasses must still provide the fecthing of the remote state.
- ResourceVariantByteStore: An abstract class that defines the API required for caching resource variants as byte arrays.
  - PersistantResourceVariantByteStore: a ResourceVariantByteStore that persists the bytes accross workbench invocations.
  - SessionResourceVariantByteStore: a ResourceVariantByteStore that caches the bytes in a session store and does not persist them.

### Implementing Subscribers

This package also contains two partial subscriber implementations.

- ResourceVariantTreeSubscriber: a subscriber that makes use of IResourceVariantTree objects to provide the traversal and refresh of the base and remote trees.
- ThreeWaySubscriber: a ResourceVariantTreeSubscriber that is build on top of the following classes.
  - ThreeWaySynchronizer: a byte store that maintains the complete synchronization state (local, base and remote) required by a subscriber. It provides API to access and set the base and remote bytes corresponding to resource variants as well as change notification to registered ISynchronizerChangeListener instances.
  - ThreeWayRemoteTree: A remote tree that uses the ThreeWaySynchronizer remote slot as its byte store. Subclasses of ResourceVariantTreeSubscriber must also subclass ThreeWayRemoteTree in order to provide the tree refresh behavior.
  - ThreeWayResourceComparator: a IResourceVariantComparator that uses the state from a ThreeWaySynchronizer to compare local resources to their variants.

Interface Summary
IResourceVariant: This interface is used by `SyncInfo` instances to provide access to the base and remote resources that correspond to a local resource.
IResourceVariantComparator: An `IResourceVariantComparator` is provided by a `Subscriber` and used by a `SyncInfo` to calculate the sync state of the workspace resources.
IResourceVariantTree: A handle that provides access to locally cached resource variants that represent a resource line-up such as a project version or branch.
ISynchronizerChangeListener: Listener that can receive notification from a `ThreeWaySynchronizer` when the synchronization state of one or more resources has changed.

Class Summary
AbstractResourceVariantTree: An implementation of `IResourceVariantTree` that provides the logic for refreshing the tree and collecting the results so they can be cached locally.
CachedResourceVariant: A resource variant is a partial implementation of a remote resource whose contents and handle are cached locally.
PersistantResourceVariantByteStore: A `ResourceVariantByteStore` that caches the variant bytes using the `org.eclipse.core.resources.ISynchronizer` so that the tree is cached across workbench invocations.
ResourceVariantByteStore: The purpose of a `ResourceVariantByteStore` is to support the caching of the synchronization bytes for the resource variants that represent a resource line-up of interest such as a version, baseline or branch.
ResourceVariantTree: Provides caching for a `AbstractResourceVariantTree` using a `ResourceVariantByteStore`.
ResourceVariantTreeSubscriber: A specialization of Subscriber that uses `IResourceVariantTree` objects to manage the base (for three-way) and remote trees.
SessionResourceVariantByteStore: A `ResourceVariantByteStore` that caches the variant bytes in memory and does not persist them over workbench invocations.
ThreeWayRemoteTree: A resource variant tree that caches and obtains its bytes from the remote slot in a three-way synchronizer.
ThreeWayResourceComparator: A resource comparator that uses the `ThreeWaySynchronizer` to compare local resources to their resource variants.
ThreeWaySubscriber: A resource variant tree subscriber whose trees use an underlying `ThreeWaySynchronizer` to store and manage the synchronization state for the local workspace.
ThreeWaySynchronizer: This class manages the synchronization between local resources and their corresponding resource variants.