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.


Apache Derby V10.0 Engine Documentation - Copyright © 1997,2004 The Apache Software Foundation or its licensors, as applicable.