org.apache.derby.iapi.store.access
Interface FileResource

All Known Implementing Classes:

RFResource

public interface FileResource

Management of file resources within a database. Suitable for jar files, images etc.

A file resource is identified by the pair (name,generationId). Name is an arbitrary String supplied by the caller. GenerationId is a non-repeating sequence number constructed by the database. Within a database a (name,generationId) pair uniquely identifies a version of a file resource for all time. Newer generation numbers reflect newer versions of the file.

A database supports the concept of a designated current version of a fileResource. The management of the current version is transactional. The following rules apply

1. Adding a FileResource makes the added version the current version
2. Removing a FileResource removes the current version of the resource. After this operation the database holds no current version of the FileResoure.
3. Replacing a FileResource removes the current version of the resource.

For the benefit of replication, a database optionally retains historic versions of stored files. These old versions are useful when processing old transactions in the stage.

Method Summary

long	add(java.lang.String name, java.io.InputStream source) Add a file resource, copying from the input stream.
StorageFile	getAsFile(java.lang.String name) Get the File handle to a file resource.
StorageFile	getAsFile(java.lang.String name, long generationId) Get the File handle to a file resource.
java.io.InputStream	getAsStream(java.lang.String name) Get the file resource as a stream.
java.io.InputStream	getAsStream(java.lang.String name, long generationId) Get the file resource as a stream.
char	getSeparatorChar()
void	purgeOldGenerations(DatabaseInstant purgeTo) Purge old generations that were removed or replaced before the database instant provided.
void	remove(java.lang.String name, long currentGenerationId, boolean purgeOnCommit) Remove the current generation of a file resource from the database.
long	replace(java.lang.String name, long currentGenerationId, java.io.InputStream source, boolean purgeOnCommit) Replace a file resource with a new version.

Method Detail

add

public long add(java.lang.String name,
                java.io.InputStream source)
         throws StandardException

Add a file resource, copying from the input stream. The InputStream will be closed by this method.

Parameters:

name - the name of the file resource.

source - an input stream for reading the content of the file resource.

Returns:

the generationId for the file resource. This quantity increases when you replace the file resource.

Throws:

StandardException - some error occured.

remove

public void remove(java.lang.String name,
                   long currentGenerationId,
                   boolean purgeOnCommit)
            throws StandardException

Remove the current generation of a file resource from the database.

Parameters:

name - the name of the fileResource to remove.

purgeOnCommit - true means purge the fileResource when the current transaction commits. false means retain the file resource for use by replication.

Throws:

StandardException - some error occured.

replace

public long replace(java.lang.String name,
                    long currentGenerationId,
                    java.io.InputStream source,
                    boolean purgeOnCommit)
             throws StandardException

Replace a file resource with a new version.

The InputStream will be closed by this method.

Parameters:

name - the name of the file resource.

source - an input stream for reading the content of the file resource.

purgeOnCommit - true means purge the existing version of fileResource when the current transaction commits. false means retain the existing version for use by replication.

Returns:

the generationId for the new 'current' version of the file resource.

Throws:

StandardException - some error occured.

getAsFile

public StorageFile getAsFile(java.lang.String name,
                             long generationId)

Get the File handle to a file resource. In some situations higher level code can make optimisations if it can access a file as a File, rather than an output stream. If this call returns null then the resouce is not accessable as a file (e.g. the database is in a zip file).

Parameters:

name - The name of the fileResource

generationId - the generationId of the fileResource

Returns:

A File object representing the file, or null if the resource is not accessable as a file.

getAsFile

public StorageFile getAsFile(java.lang.String name)

Get the File handle to a file resource. In some situations higher level code can make optimisations if it can access a file as a File, rather than an output stream. If this call returns null then the resouce is not accessable as a file (e.g. the database is in a zip file).

Parameters:

name - The name of the fileResource

Returns:

A File object representing the file, or null if the resource is not accessable as a file.

getAsStream

public java.io.InputStream getAsStream(java.lang.String name,
                                       long generationId)
                                throws java.io.IOException

Get the file resource as a stream.

Throws:

java.io.IOException - some io error occured

java.io.FileNotFoundException - file does not exist.

getAsStream

public java.io.InputStream getAsStream(java.lang.String name)
                                throws java.io.IOException

Get the file resource as a stream.

Throws:

java.io.IOException - some io error occured

java.io.FileNotFoundException - file does not exist.

purgeOldGenerations

public void purgeOldGenerations(DatabaseInstant purgeTo)
                         throws StandardException

Purge old generations that were removed or replaced before the database instant provided.

Throws:

StandardException - Ooops

getSeparatorChar

public char getSeparatorChar()

Returns:

the separator character to be used in file names.