net.dpml.transit
Interface CacheHandler

public interface CacheHandler

The CacheHandler interface defines the contract for classes capable of supporting the cache management aspects of a transit system. Cache management encompasses the retreval of resources based on artifact identifiers. A cache manager implementations may provide varying levels of quality-of-services. Selection of a cache manager is defined under the transit cache configuration properties.

Version:

1.0.3

Author:

Digital Product Meta Library

Method Summary

OutputStream	createOutputStream(Artifact artifact) Creates an output stream to where the artifact content can be written to.
File	getCacheDirectory() Return the current cache directory.
Layout	getLayout() Return the layout used by the cache.
LayoutRegistry	getLayoutRegistry() Return the layout registry.
File	getLocalFile(Artifact artifact) Return the cache directory.
InputStream	getResource(Artifact artifact) Attempts to download and cache a remote artifact using a set of remote repositories.
InputStream	getResource(Artifact artifact, String internalReference) Attempts to download and cache a remote artifact using a set of remote repositories.
void	initialize() Initialization of the cache handler.

Method Detail

getLocalFile

File getLocalFile(Artifact artifact)
                  throws IOException

Return the cache directory.

Parameters:

artifact - the artifact to resolve

Returns:

the working cache directory

Throws:

IOException - if an IO error occurs

initialize

void initialize()
                throws IOException

Initialization of the cache handler. This operation is invoked by the transit context following the establishment of bootstrap services. During initialization the implementation loads any custom resource hosts.

Throws:

IOException - if an IO error occurs

getResource

InputStream getResource(Artifact artifact)
                        throws IOException,
                               TransitException

Attempts to download and cache a remote artifact using a set of remote repositories.

Parameters:

artifact - the artifact to retrieve and cache

Returns:

an input stream to the local resource

Throws:

IOException - if an IO error occurs

TransitException - is a transit system error occurs

getResource

InputStream getResource(Artifact artifact,
                        String internalReference)
                        throws IOException,
                               TransitException

Attempts to download and cache a remote artifact using a set of remote repositories.

This method allows an internal reference to be passed to the cache handler and it is expected to return the InputStream of the internal item inside Jar/Zip files. If this method is called, the implementation can assume that the artifact is a Zip file.

Parameters:

artifact - the artifact to retrieve and cache

internalReference - referencing a item within the artifact. This argument may start with "!" or "!/", which should be ignored.

Returns:

a file referencing the local resource

Throws:

IOException - if an IO error occurs

TransitException - is a transit system error occurs

createOutputStream

OutputStream createOutputStream(Artifact artifact)
                                throws NullArgumentException,
                                       ArtifactAlreadyExistsException,
                                       IOException

Creates an output stream to where the artifact content can be written to.

If the artifact already exists, a ArtifactAlreadyExistsException will be thrown. If the directory doesn't exists, it will be created. The CacheHandler is responsible to recognize the completion of the writes through the close() method in the output stream, and do any post-processing there.

Parameters:

artifact - the artifact

Returns:

an output stream

Throws:

NullArgumentException - if the artifact argument is null.

ArtifactAlreadyExistsException - if the artifact already exists in the cache.

IOException - if an IO error occurs

getLayout

Layout getLayout()

Return the layout used by the cache.

Returns:

the cache layout

getLayoutRegistry

LayoutRegistry getLayoutRegistry()

Return the layout registry.

Returns:

the layout registry.

getCacheDirectory

File getCacheDirectory()

Return the current cache directory.

Returns:

the cache directory.