org.ungoverned.oscar
Interface BundleCache

All Known Implementing Classes:
DefaultBundleCache

public interface BundleCache

This interface represents the storage mechanism that Oscar uses for caching bundles. It is possible for multiple implementations of this interface to exist for different storage technologies, such as the file system, memory, or a database. Oscar includes a default implementation of this interface that uses the file system. Oscar allows you to specify alternative implementations to use by specifying a class name via the oscar.cache.class system property. Bundle cache implemenations should implement this interface and provide a default constructor.

See Also:
BundleArchive

Method Summary
 BundleArchive create(long id, java.lang.String location, java.io.InputStream is)
           Creates a new bundle archive for the specified bundle identifier using the supplied location string and input stream.
 BundleArchive getArchive(long id)
           Returns the bundle archive associated with the specified bundle indentifier.
 BundleArchive[] getArchives()
           Returns all cached bundle archives.
 void initialize(Oscar oscar)
           This method is called before using the BundleCache implementation to initialize it and to pass it a reference to its associated Oscar instance.
 void purge(BundleArchive ba)
           Purges all old revisions of the specified bundle from the cache.
 void remove(BundleArchive ba)
           Removes the specified bundle from the cache.
 void update(BundleArchive ba, java.io.InputStream is)
           Saves an updated revision of the specified bundle to the bundle cache using the supplied input stream.
 

Method Detail

initialize

public void initialize(Oscar oscar)
                throws java.lang.Exception

This method is called before using the BundleCache implementation to initialize it and to pass it a reference to its associated Oscar instance. The main purpose for passing the BundleCache implementation a reference to its Oscar instance is to allow it to use Oscar.getConfigProperty() to access system property values; the BundleCache implementation should not use System.getProperty() directly. Oscar.getConfigProperty() provides access to properties passed into the Oscar instance's constructor. If no properties were passed in to the constructor then it searches System.getProperty(). This approach allows multiple instances of Oscar to exist in memory at the same time, but for them to be configured differently. For example, an application may want two instances of Oscar, where each instance stores their cache in a different location in the file system. When using multiple instances of Oscar in memory at the same time, system properties should be avoided and all properties should be passed in to Oscar's constructor.

Parameters:
oscar - the Oscar instance associated with the bundle cache.
Throws:
java.lang.Exception - if any error occurs.

getArchives

public BundleArchive[] getArchives()
                            throws java.lang.Exception

Returns all cached bundle archives.

Returns:
an array of all cached bundle archives.
Throws:
java.lang.Exception - if any error occurs.

getArchive

public BundleArchive getArchive(long id)
                         throws java.lang.Exception

Returns the bundle archive associated with the specified bundle indentifier.

Parameters:
id - the identifier of the bundle archive to retrieve.
Returns:
the bundle archive assocaited with the specified bundle identifier.
Throws:
java.lang.Exception - if any error occurs.

create

public BundleArchive create(long id,
                            java.lang.String location,
                            java.io.InputStream is)
                     throws java.lang.Exception

Creates a new bundle archive for the specified bundle identifier using the supplied location string and input stream. The contents of the bundle JAR file should be read from the supplied input stream, which will not be null. The input stream is closed by the caller; the implementation is only responsible for closing streams it opens. If this method completes successfully, then it means that the initial bundle revision of the specified bundle was successfully cached.

Parameters:
id - the identifier of the bundle associated with the new archive.
location - the location of the bundle associated with the new archive.
is - the input stream to the bundle's JAR file.
Returns:
the created bundle archive.
Throws:
java.lang.Exception - if any error occurs.

update

public void update(BundleArchive ba,
                   java.io.InputStream is)
            throws java.lang.Exception

Saves an updated revision of the specified bundle to the bundle cache using the supplied input stream. The contents of the updated bundle JAR file should be read from the supplied input stream, which will not be null. The input stream is closed by the caller; the implementation is only responsible for closing streams it opens. Updating a bundle in the cache does not replace the current revision of the bundle, it makes a new revision available. If this method completes successfully, then it means that the number of revisions of the specified bundle has increased by one.

Parameters:
ba - the bundle archive of the bundle to update.
is - the input stream to the bundle's updated JAR file.
Throws:
java.lang.Exception - if any error occurs.

purge

public void purge(BundleArchive ba)
           throws java.lang.Exception

Purges all old revisions of the specified bundle from the cache. If this method completes successfully, then it means that only the most current revision of the bundle should exist in the cache.

Parameters:
ba - the bundle archive of the bundle to purge.
Throws:
java.lang.Exception - if any error occurs.

remove

public void remove(BundleArchive ba)
            throws java.lang.Exception

Removes the specified bundle from the cache. If this method completes successfully, there should be no trace of the removed bundle in the cache.

Parameters:
ba - the bundle archive of the bundle to remove.
Throws:
java.lang.Exception - if any error occurs.