org.purl.xnode
Interface XNodeStoreProvider

All Known Implementing Classes:

AbstractXNodeStoreProvider, BerkeleyDBProvider, FileSystemProvider

public interface XNodeStoreProvider

An interface for the backing storage for an XNodeStore.

The XNode Implementation (the package org.ceryle.xnode.*, both its source code and documentation), are released under the Apache 2.0 License. For more details, check the LICENSE file contained with the distribution, or see The Ceryle Project for more information. It is distributed with no warranty.

Since:

XNode 1.2

Version:

$Id: XNodeStoreProvider.java,v 3.1 2007-06-15 12:10:37 altheim Exp $

Author:

Murray Altheim

Method Summary

void	closeDatabase(String did) Close the Database backing the XNodeCollection having ID did.
void	deleteContent(String did, String rid) Permanently deletes the key/data pair (database record) matching the key String rid from the Database with ID did.
void	deleteDatabase(String did) Delete the Database backing the XNodeCollection having ID did.
String	getContent(String did, String rid) The method that does the actual work of retrieving the contents in the record with key String rid (record ID) from the Database with ID did.
int	getContentSize(String did, String rid) Returns the record storage size of the document in the Database with ID did for the data matching the key String rid (record ID).
Object	getDatabase(String did) Return the Database backing the XNodeCollection having ID did.
List	getDatabaseIndex() Returns the List of existing Database IDs.
List	getDocumentIndex(String did) Returns the document index for the Database with key did, sorted, created from the Database.
boolean	hasContent(String did, String rid) Returns true if the Database with ID did contains data matching the key String rid (record ID).
boolean	hasDatabase(String did) Returns true if there is an existing Database with key did.
void	initialize(XNodeStore xnodestore) Initializes the XNodeStoreProvider provided its parent XNodeStore.
boolean	isLoadedDatabase(String did) Returns true if the Database with key did has already been loaded.
void	optimize(ActionListener listener) Using any native processes, optimizes the Database.
void	putContent(String did, String rid, String content, boolean overwrite) The method that does the actual work of storing the String content in the Database db using the key String rid (record ID).
void	start() Start the database service.
void	stop() Shuts down the database service.
boolean	storageExists() Temporary method (do not rely on its longevity).
void	writeXNodeToDatabase(XNode xnode, XNodeCollection collection, boolean overwrite) Writes the provided XNode to the XNodeCollection's Database using the XNode's ID as the key.

Method Detail

storageExists

boolean storageExists()

Temporary method (do not rely on its longevity).

initialize

void initialize(XNodeStore xnodestore)
                throws XNodeStoreProviderException

Initializes the XNodeStoreProvider provided its parent XNodeStore. Calling this method subsequently throws an XNodeStoreProviderException.

Parameters:

xnodestore - the parent XNodeStore.

Throws:

XNodeStoreProviderException - if any error occurs while initializing the provider.

start

void start()
           throws XNodeStoreProviderException

Start the database service. If already started, this has no effect.

Throws:

XNodeStoreProviderException - if unable to start the database.

stop

void stop()
          throws XNodeStoreProviderException

Shuts down the database service. If already stopped, this has no effect.

Throws:

XNodeStoreProviderException - if an error occurs while stopping the database.

isLoadedDatabase

boolean isLoadedDatabase(String did)

Returns true if the Database with key did has already been loaded. If the implementation does not perform caching this method should always return false (otherwise that might suggest the database does not need to be loaded).

getDatabase

Object getDatabase(String did)
                   throws XNodeStoreProviderException

Return the Database backing the XNodeCollection having ID did. This will create the database if it does not already exist.

The returned Object will necessarily be implementation-dependent and is likely be of no use outside the implementing class. Implementations are free to return a null value if returning a value is inappropriate or introduces a security or other issue.

Parameters:

did - the ID of the Database

Returns:

the backing Database as an Object.

Throws:

XNodeStoreProviderException - if any error occurs while getting or creating the Database.

hasDatabase

boolean hasDatabase(String did)
                    throws XNodeStoreProviderException

Returns true if there is an existing Database with key did. This directly queries the stored databases from the Environment, not the XNodeCollections that are their registries. (If the current list of loaded Databases is needed, use m_dbCache.)

Parameters:

did - the ID of the Database to query.

Returns:

true if the Database exists.

Throws:

XNodeStoreProviderException - if any error occurs while querying.

getDatabaseIndex

List getDatabaseIndex()
                      throws XNodeStoreProviderException

Returns the List of existing Database IDs. This directly queries the stored databases from the Environment, not the XNodeCollections that are their registries. This returns an empty List rather than null if there are no collections. It does not include the root Database ("db") in the list.

Returns:

an immutable List of the Database IDs (as Strings).

Throws:

XNodeStoreProviderException - if any error occurs while building the index.

closeDatabase

void closeDatabase(String did)
                   throws XNodeStoreProviderException

Close the Database backing the XNodeCollection having ID did. If a Database matching the ID does not exist or is not loaded, nothing happens. This is only used for implementations that require housekeeping upon closing a database.

Parameters:

did - the ID of the Database to close.

Throws:

XNodeStoreProviderException - if any error occurs while closing the Database.

deleteDatabase

void deleteDatabase(String did)
                    throws XNodeStoreProviderException

Delete the Database backing the XNodeCollection having ID did.

Parameters:

did - the ID of the Database to delete.

Throws:

XNodeStoreProviderException - if any error occurs while deleting the Database.

putContent

void putContent(String did,
                String rid,
                String content,
                boolean overwrite)
                throws XNodeStoreProviderException

The method that does the actual work of storing the String content in the Database db using the key String rid (record ID). The boolean overwrite is used as a failsafe to keep from accidentally overwriting an existing record — if true, throws an exception if the record already exists.

Parameters:

did - the ID of the Database

rid - the ID of the record

content - the content String.

overwrite - when true permit the overwrite of previous content.

Throws:

XNodeStoreProviderException - if any error occurs while putting the content into the Database.

hasContent

boolean hasContent(String did,
                   String rid)
                   throws XNodeStoreProviderException

Returns true if the Database with ID did contains data matching the key String rid (record ID). This returns false under all other circumstances.

Parameters:

did - the ID of the Database

rid - the ID of the record

Returns:

true if a record matching the key 'id' exists.

Throws:

XNodeStoreProviderException - if an error occurs retrieving the content.

getContentSize

int getContentSize(String did,
                   String rid)

Returns the record storage size of the document in the Database with ID did for the data matching the key String rid (record ID). This may be used as an alternative to hasContent(String,String) since it does basically the same function but returns a more useful value. This returns -1 if either of the parameters is null, if the collection or document doesn't exist, and returns a -2 if any error occurs, rather than throwing an exception.

Parameters:

did - the ID of the Database

rid - the ID of the record

Returns:

the size of the record matching the key 'id'; -1 if it doesn't exist; -2 upon error.

getContent

String getContent(String did,
                  String rid)
                  throws XNodeStoreProviderException

The method that does the actual work of retrieving the contents in the record with key String rid (record ID) from the Database with ID did.

Parameters:

did - the ID of the Database

rid - the ID of the record

Returns:

a String representation of the data, or null if unavailable.

Throws:

XNodeStoreProviderException - if an error occurs retrieving the content.

deleteContent

void deleteContent(String did,
                   String rid)
                   throws XNodeStoreProviderException

Permanently deletes the key/data pair (database record) matching the key String rid from the Database with ID did.

Parameters:

did - the ID of the Database

rid - the ID of the record

Throws:

XNodeStoreProviderException - if an error occurs deleting the key/data pair.

getDocumentIndex

List getDocumentIndex(String did)
                      throws XNodeStoreProviderException

Returns the document index for the Database with key did, sorted, created from the Database. Returns an empty List rather than null.

Parameters:

did - the database ID

Returns:

a List containing the IDs of the documents in the database.

Throws:

XNodeStoreProviderException - if an error occurs obtaining the document index.

Since:

XNode 1.2

writeXNodeToDatabase

void writeXNodeToDatabase(XNode xnode,
                          XNodeCollection collection,
                          boolean overwrite)
                          throws XNodeStoreProviderException

Writes the provided XNode to the XNodeCollection's Database using the XNode's ID as the key. Note that this is entirely a write-to-Database transaction; no DOM changes are made. If overwrite is false, throws an exception if the XNode already exists within the Database.

Parameters:

xnode - the XNode to write.

collection - the XNodeCollection.

overwrite - when true permit the overwrite of previous content.

Throws:

XNodeStoreProviderException - if an error occurs deleting writing the XNode.

optimize

void optimize(ActionListener listener)

Using any native processes, optimizes the Database. Does nothing in implementations where this does not apply.

If the optional ActionListener is provided its ActionListener.actionPerformed(ActionEvent) method will be called upon completion of the optimization.

Parameters:

listener - an optional listener to receive notification upon completion.