* This interface contains the basic methods for implementing a * document repository application. Such an application is responsible * for managing a document storage system (or repository), which contains * document folders and which allows clients to store or retrieve * documents into them. How the repository system is implemented and what * exactly constitutes a document or a folder is determined by each particular * subclass that implements this interface. * *
* A document folder consists of zero or more documents. A folder is * uniquely identified within the repository by its identifier. A folder may * have default properties, which are properties that are applied to * documents within the folder by default. * *
* A document consists of content data (such as an image, text, or other * kind of user data) and zero or more properties. Typically, the * properties comprise the keys used to store the document in the repository * system. * *
* Implementations of a repository system must subclass either the * {@link RepositoryReader} or {@link RepositoryWriter} class, or both. * Repository reader implementations must also subclass the * {@link Folder} and {@link Document} classes, while repository writer * implementations must subclass the {@link StorableFolder} and * {@link StorableDocument} classes. * *
* Configuration properties specific to the repository implementation are passed * to the {@link #initialize initialize()} method in order to initialize the * repository reader or writer appropriately. Once the repository reader or * writer has been properly initialized, calling its {@link #open open()} method * establishes a connection to the repository system. Documents can then be * retrieved from or stored into the repository. After all repository operations * have been completed, the {@link #close close()} method must be called, which * closes the connection to the repository system and deallocates any resources * used by the reader/writer object. * *
* Most of the methods in these classes throw an IOException if an * error occurs. * *
* Note: This requires Java 1.5 or later. * * *
* The name and format of the properties is determined by the actual * implementation of the repository system. Typically, properties specify * the details required to establish a connection to the repository system, * e.g., host or path names, user-ID and password credentials, database * names, and other similar information. The properties passed to this * method thus establish a specific context in which access to the repository * system takes place. This context exists for all of the operations * occurring between the calls to {@link #open open()} and * {@link #close close()}. * *
* Certain implementations might not require any context information at all * prior to calling {@link #open open()}, in which case this method may * accept an empty or null Hashtable object. * *
* Implementations may allow this method to be called more than once. * This could be useful in cases where configuration information is taken * from multiple sources. * * @param props * Configuration properties (hash table) to initialize the repository reader. * Typically this is a {@link java.util.Properties} object. * Some implementations may allow this to be empty or null. * * @throws IOException * Thrown if a required property is missing or malformed. * * @since API 2.0, 2008-04-03 */ public abstract void initialize(Hashtable props) throws IOException; /*************************************************************************** * Establish a connection and attach a repository system to this repository * handler. * * @param name * Name of the document collection within the repository to be opened. * The format and meaning of this name is determined by the implementation. * Some implementations may allow this to be empty ("") or null. * * @throws IOException * Thrown if an error occurs while opening the repository system. * * @throws IllegalStateException (unchecked) * Thrown if {@link #initialize initialize()} has not been called yet. * * @since API 2.0, 2008-04-19 */ public abstract void open(String name) throws IOException; /*************************************************************************** * Close the connection and detach the repository system from this repository * handler. * Resources used by this repository handler are deallocated. * *
* Any subsequent attempts to use this repository handler without calling * {@link #open open()} again will result in exceptions. * *
* Note that this method does not throw any exceptions. * * @since API 2.0, 2008-04-03 */ //@Override public abstract void close(); /*************************************************************************** * Retrieve the default properties for documents managed by this repository * handler. * *
* Note that implementations are not required to support default document * properties, in which case this method can throw an * UnsupportedOperationException or simply return null. * * @return * The default document properties for this repository handler. * * @throws IllegalStateException (unchecked) * Thrown if {@link #initialize initialize()} has not been called yet. * * @throws UnsupportedOperationException (unchecked) * This operation is not supported, i.e., the implementation does not support * default document properties. * * @since API 2.0, 2008-04-03 */ public abstract DocumentProperty[] getDefaultProperties() throws IOException; } // End Repository.java