Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.team.core.variants
Class CachedResourceVariant

    java.lang.Object
      org.eclipse.core.runtime.PlatformObject
          org.eclipse.team.core.variants.CachedResourceVariant

All Implemented Interfaces:
  IAdaptable, IResourceVariant

public abstract class CachedResourceVariant
extends PlatformObject
implements IResourceVariant

A resource variant is a partial implementation of a remote resource whose contents and handle are cached locally. It is assumed that a resource variant is an immutable version or revision of a resource. Therefore, once the contents are cached they cannot be replaced. However, the cached handle can be replaced to allow clients to cache addition state or properties for a resource variant.

Overriding subclasses need to provide a cache Id for all their resource variants and a cache path for each resource variant that uniquely identifies it. In addition, they must implement `fetchContents` to retrieve the contents of the resource variant and then call `setContents` to place these contents in the cache. Subclasses may also call `cacheHandle` in order to place the handle in the cache so that it can be retrieved later by calling `getCachedHandle` on any resource variant whose cache path is the same as the cached handle. This allows subclasses to cache additional resource variant properties such as author, comment, etc.

The `IStorage` instance returned by this class will be an `IEncodedStorage`.

The cache in which the resource variants reside will occasionally clear cached entries if they have not been accessed for a certain amount of time.

Since:
  3.0

Constructor Summary
`CachedResourceVariant()`

Method Summary
`protected void` | `cacheHandle()` Cache this handle in the cache, replacing any previously cached handle.
`protected abstract void` | `fetchContents(IProgressMonitor monitor)` Method that is invoked when the contents of the resource variant need to be fetched.
`protected InputStream` | `getCachedContents()` Return the cached contents for this resource variant or `null` if the contents have not been cached.
`protected CachedResourceVariant` | `getCachedHandle()` Return the cached handle for this resource variant if there is one.
`protected abstract String` | `getCacheId()` Return the ID that uniquely identifies the cache in which this resource variant is to be cache.
`protected abstract String` | `getCachePath()` Get the path that uniquely identifies the remote resource variant.
`long` | `getSize()` Return the size (in bytes) of the contents of this resource variant.
`IStorage` | `getStorage(IProgressMonitor monitor)` Return an instance of IStorage or `null` if the remote resource does not have contents (i.e. is a folder).
`protected boolean` | `isContentsCached()` Return whether there are already contents cached for this resource variant.
`protected boolean` | `isHandleCached()` Return `true` if the cache contains an entry for this resource variant.
`protected void` | `setContents(InputStream stream, IProgressMonitor monitor)` This method should be invoked by subclasses from within their `fetchContents` method in order to cache the contents for this resource variant.

Methods inherited from class org.eclipse.core.runtime.PlatformObject
`getAdapter`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.eclipse.team.core.variants.IResourceVariant
`asBytes, equals, getContentIdentifier, getName, isContainer`

Constructor Detail

### CachedResourceVariant

    public CachedResourceVariant()

Method Detail

### getStorage

    public IStorage getStorage(IProgressMonitor monitor)
                        throws TeamException

  Description copied from interface: `IResourceVariant`
  Return an instance of IStorage or `null` if the remote resource does not have contents (i.e. is a folder). Since the `ISorage#getContents()` method does not accept an `IProgressMonitor`, this method must ensure that the contents access by the resulting `IStorage` is cached locally (hence the `IProgressMonitor` argument to this method). Implementations of this method should ensure that the resulting `IStorage` is accessing locally cached contents and is not contacting the server.

  The returned storage object may be an instance of (@link org.eclipse.core.resources.IEncodedStorage} in which case clients can determine the character encoding of the contents.

  Specified by:
    `getStorage` in interface `IResourceVariant`
  Returns:
    an `IStorage` that provides access to the contents of the remote resource or `null` if the remote resource is a container.
  Throws:
    `TeamException`

### fetchContents

    protected abstract void fetchContents(IProgressMonitor monitor)
                                   throws TeamException

  Method that is invoked when the contents of the resource variant need to be fetched. This method will only be invoked for files (i.e. `isContainer()` returns `false`. Subclasses should override this method and invoke `setContents` with a stream containing the fetched contents.

  Parameters:
    `monitor` - a progress monitor
  Throws:
    `TeamException`

### setContents

    protected void setContents(InputStream stream,
                               IProgressMonitor monitor)
                        throws TeamException

  This method should be invoked by subclasses from within their `fetchContents` method in order to cache the contents for this resource variant.

  This method is not intended to be overridden by clients.

  Parameters:
    `stream` - the stream containing the contents of the resource variant
    `monitor` - a progress monitor
  Throws:
    `TeamException`

### isContentsCached

    protected boolean isContentsCached()

  Return whether there are already contents cached for this resource variant. This method will return `false` even if the contents are currently being cached by another thread. The consequence of this is that the contents may be fetched twice in the rare case where two threads request the same contents concurrently. For containers, this method will always return `false`.

  This method is not intended to be overridden by clients.

### getCachedContents

    protected InputStream getCachedContents()
                                     throws TeamException

  Return the cached contents for this resource variant or `null` if the contents have not been cached. For containers, this method will always return `null`.

  This method is not intended to be overridden by clients.

  Returns:
    the cached contents or `null`
  Throws:
    `TeamException`

### isHandleCached

    protected boolean isHandleCached()

  Return `true` if the cache contains an entry for this resource variant. It is possible that another instance of this variant is cached. To get the cached instance, call `getCachedHandle()`. Note that cached contents can be retrieved from any handle to a resource variant whose cache path (as returned by `getCachePath()`) match but other state information may only be accessible from the cached copy.

  This method is not intended to be overridden by clients.

  Returns:
    whether the variant is cached

### getCachePath

    protected abstract String getCachePath()

  Get the path that uniquely identifies the remote resource variant. This path descibes the remote location where the remote resource is stored and also uniquely identifies each resource variant. It is used to uniquely identify this resource variant when it is stored in the resource variant cache.

  Returns:
    the full path of the remote resource variant

### getSize

    public long getSize()

  Return the size (in bytes) of the contents of this resource variant. The method will return 0 if the contents have not yet been cached locally. For containers, this method will always return 0.

### getCacheId

    protected abstract String getCacheId()

  Return the ID that uniquely identifies the cache in which this resource variant is to be cache. The ID of the plugin that provides the resource variant subclass is a good candidate for this ID. The creation, management and disposal of the cache is managed by Team.

  Returns:
    the cache ID

### getCachedHandle

    protected CachedResourceVariant getCachedHandle()

  Return the cached handle for this resource variant if there is one. If there isn't one, then `null` is returned. If there is no cached handle and one is desired, then `cacheHandle()` should be called.

  This method is not intended to be overridden by clients.

  Returns:
    a cached copy of this resource variant or `null`

### cacheHandle

    protected void cacheHandle()

  Cache this handle in the cache, replacing any previously cached handle. Note that caching this handle will replace any state associated with a previously cached handle, if there is one, but the contents will remain. The reason for this is the assumption that the cache path for a resource variant (as returned by `getCachePath()` identifies an immutable resource version (or revision). The ability to replace the handle itself is provided so that additional state may be cached before or after the contents are fetched.

  This method is not intended to be overridden by clients.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.