http://www.eclipse.org/platform: Team Support Core (Eclipse Foundation) 
Copyright (c) 2000, 2017 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation

/*******************************************************************************
 * Copyright (c) 2000, 2017 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.team.core.variants;

import java.io.IOException;
import java.io.InputStream;

import org.eclipse.core.resources.IEncodedStorage;
import org.eclipse.core.resources.IResourceStatus;
import org.eclipse.core.resources.IStorage;
import org.eclipse.core.runtime.Assert;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Path;
import org.eclipse.core.runtime.PlatformObject;
import org.eclipse.core.runtime.Status;
import org.eclipse.osgi.util.NLS;
import org.eclipse.team.core.TeamException;
import org.eclipse.team.internal.core.Messages;
import org.eclipse.team.internal.core.ResourceVariantCache;
import org.eclipse.team.internal.core.ResourceVariantCacheEntry;
import org.eclipse.team.internal.core.TeamPlugin;


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
/**
 * 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.
 * <p>
 * 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 <code>fetchContents</code> to retrieve the contents of the
 * resource variant and then call <code>setContents</code> to place these contents in the cache.
 * Subclasses may also call <code>cacheHandle</code> in order to place the handle in the
 * cache so that it can be retrieved later by calling <code>getCachedHandle</code> 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.
 * </p>
 * <p>
 * The <code>IStorage</code> instance returned by this class will be
 * an {@link org.eclipse.core.resources.IEncodedStorage}.
 * <p>
 * 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.
 * </p>
 *
 * @since 3.0
 */
public abstract class CachedResourceVariant extends PlatformObject implements IResourceVariant {

	// holds the storage instance for this resource variant
	private IStorage storage;

	/*
	 * Internal class which provides access to the cached contents
	 * of this resource variant
	 */
	class ResourceVariantStorage implements IEncodedStorage {
		@Override
		public InputStream getContents() throws CoreException {
			if (!isContentsCached()) {
				// The cache may have been cleared if someone held
				// on to the storage too long
				throw new TeamException(NLS.bind(Messages.CachedResourceVariant_0, new String[] { getCachePath() }));
			}
			return getCachedContents();
		}
		@Override
		public IPath getFullPath() {
			return getDisplayPath();
		}
		@Override
		public String getName() {
			return CachedResourceVariant.this.getName();
		}
		@Override
		public boolean isReadOnly() {
			return true;
		}
		@Override
		public <T> T getAdapter(Class<T> adapter) {
			return CachedResourceVariant.this.getAdapter(adapter);
		}
		@Override
		public String getCharset() throws CoreException {
			InputStream contents = getContents();
			try {
				String charSet = TeamPlugin.getCharset(getName(), contents);
				return charSet;
			} catch (IOException e) {
				throw new TeamException(new Status(IStatus.ERROR, TeamPlugin.ID, IResourceStatus.FAILED_DESCRIBING_CONTENTS, NLS.bind(Messages.CachedResourceVariant_1, new String[] { getFullPath().toString() }), e));
			} finally {
				try {
					contents.close();
				} catch (IOException e1) {
					// Ignore
				}
			}
		}
	}

	@Override
	public IStorage getStorage(IProgressMonitor monitor) throws TeamException {
		if (isContainer()) return null;
		ensureContentsCached(monitor);
		if (storage == null) {
			storage = new ResourceVariantStorage();
		}
		return storage;
	}

	private void ensureContentsCached(IProgressMonitor monitor) throws TeamException {
		// Ensure that the contents are cached from the server
		if (!isContentsCached()) {
			fetchContents(monitor);
		}
	}

	
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.

Params:
  • monitor – a progress monitor
/**
	 * 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.
	 * <code>isContainer()</code> returns <code>false</code>.
	 * Subclasses should override this method and invoke <code>setContents</code>
	 * with a stream containing the fetched contents.
	 * @param monitor a progress monitor
	 */
	protected abstract void fetchContents(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.

Params:
  • stream – the stream containing the contents of the resource variant
  • monitor – a progress monitor
Throws:
/**
	 * This method should be invoked by subclasses from within their <code>fetchContents</code>
	 * method in order to cache the contents for this resource variant.
	 * <p>
	 * This method is not intended to be overridden by clients.
	 * @param stream the stream containing the contents of the resource variant
	 * @param monitor a progress monitor
	 * @throws TeamException
	 */
	protected void setContents(InputStream stream, IProgressMonitor monitor) throws TeamException {
		// Ensure that there is a cache entry to receive the contents
		Assert.isTrue(!isContainer());
		if (!isHandleCached()) cacheHandle();
		getCacheEntry().setContents(stream, monitor);
	}

	private ResourceVariantCacheEntry getCacheEntry() {
		return getCache().getCacheEntry(this.getCachePath());
	}

	
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.

Returns:whether there are contents cached for this resource variant
/**
	 * Return whether there are already contents cached for this resource variant.
	 * This method will return <code>false</code> 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 <code>false</code>.
	 * <p>
	 * This method is not intended to be overridden by clients.
	 * @return whether there are contents cached for this resource variant
	 */
	public boolean isContentsCached() {
		if (isContainer() || !isHandleCached()) {
			return false;
		}
		ResourceVariantCacheEntry entry = getCache().getCacheEntry(getCachePath());
		return entry.getState() == ResourceVariantCacheEntry.READY;
	}

	
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.

Throws:
Returns:the cached contents or null
/**
	 * Return the cached contents for this resource variant or <code>null</code>
	 * if the contents have not been cached.
	 * For containers, this method will always return <code>null</code>.
	 * <p>
	 * This method is not intended to be overridden by clients.
	 * @return the cached contents or <code>null</code>
	 * @throws TeamException
	 */
	protected InputStream getCachedContents() throws TeamException {
		if (isContainer() || !isContentsCached()) return null;
		return getCache().getCacheEntry(getCachePath()).getContents();
	}

	
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.

Returns:whether the variant is cached
@nooverrideThis method is not intended to be overridden by clients.
/**
	 * Return <code>true</code> 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 <code>getCachedHandle()</code>. Note that
	 * cached contents can be retrieved from any handle to a resource variant whose
	 * cache path (as returned by <code>getCachePath()</code>) match but other
	 * state information may only be accessible from the cached copy.
	 *
	 * @return whether the variant is cached
	 * @nooverride This method is not intended to be overridden by clients.
	 */
	protected boolean isHandleCached() {
		return (getCache().hasEntry(getCachePath()));
	}

	
Get the path that uniquely identifies the remote resource
variant. This path describes 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.
This path is also returned as the full path of the IStorage
returned from this variant so the path could be converted to an
IPath and displayed to the user.

Returns:the full path of the remote resource variant
/**
	 * Get the path that uniquely identifies the remote resource
	 * variant. This path describes 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.
	 * This path is also returned as the full path of the <code>IStorage</code>
	 * returned from this variant so the path could be converted to an
	 * <code>IPath</code> and displayed to the user.
	 * @return the full path of the remote resource variant
	 */
	protected abstract String getCachePath();

	
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.

Returns:the size (in bytes) of the contents of this resource variant
/**
	 * 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.
	 * @return the size (in bytes) of the contents of this resource variant
	 */
	public long getSize() {
		if (isContainer() || !isContentsCached()) return 0;
		ResourceVariantCacheEntry entry = getCacheEntry();
		if (entry == null || entry.getState() != ResourceVariantCacheEntry.READY) {
			return 0;
		}
		return entry.getSize();
	}

	/*
	 * Return the cache that is used to cache this resource variant and its contents.
	 * @return Returns the cache.
	 */
	private ResourceVariantCache getCache() {
		ResourceVariantCache.enableCaching(getCacheId());
		return ResourceVariantCache.getCache(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
/**
	 * 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.
	 * @return the cache ID
	 */
	protected abstract String getCacheId();

	
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.

Returns:a cached copy of this resource variant or null
@nooverrideThis method is not intended to be overridden by clients.
/**
	 * Return the cached handle for this resource variant if there is
	 * one. If there isn't one, then <code>null</code> is returned.
	 * If there is no cached handle and one is desired, then <code>cacheHandle()</code>
	 * should be called.
	 *
	 * @return a cached copy of this resource variant or <code>null</code>
	 * @nooverride This method is not intended to be overridden by clients.
	 */
	protected CachedResourceVariant getCachedHandle() {
		ResourceVariantCacheEntry entry = getCacheEntry();
		if (entry == null) return null;
		return entry.getResourceVariant();
	}

	
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.

@nooverrideThis method is not intended to be overridden by clients.
/**
	 * 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 <code>getCachePath()</code> 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.
	 *
	 * @nooverride This method is not intended to be overridden by clients.
	 */
	protected void cacheHandle() {
		getCache().add(getCachePath(), this);
	}

	
Return the full path of this resource that should be displayed to the
user. This path is also used as the path of the IStorage that
is returned by this instance.
Subclasses may override.

Returns:the full path of this resource that should be displayed to the
user
Since:3.1
/**
	 * Return the full path of this resource that should be displayed to the
	 * user. This path is also used as the path of the <code>IStorage</code> that
	 * is returned by this instance.
	 * Subclasses may override.
	 * @return the full path of this resource that should be displayed to the
	 * user
	 *
	 * @since 3.1
	 */
	public IPath getDisplayPath() {
		return new Path(null, getCachePath());
	}

}