org.ceryle.xnode.providers
Class BerkeleyDBProvider

java.lang.Object
  org.ceryle.xnode.providers.AbstractXNodeStoreProvider
      org.ceryle.xnode.providers.BerkeleyDBProvider

All Implemented Interfaces:

XNodeStoreProvider

public class BerkeleyDBProvider
extends AbstractXNodeStoreProvider
implements XNodeStoreProvider

Implements the XNodeStoreProvider API for an XNodeStore, using a Berkeley DB JE backend store.

Note that no XML ID validity checking is done here; IDs supplied to methods within this class should already be validated.

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: BerkeleyDBProvider.java,v 1.2 2007-06-20 01:28:00 altheim Exp $

Author:

Murray Altheim

Field Summary

protected long

storageRatioThreshold The threshold ratio after which the cleaner thread is started.

Fields inherited from class org.ceryle.xnode.providers.AbstractXNodeStoreProvider

Filesep, m_homepath, m_storage, m_storagepath, m_xns, mh

Constructor Summary

BerkeleyDBProvider()

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.
com.sleepycat.je.Environment	getEnvironment() Returns the BerkeleyDB JE Environment used with this implementation.
static long	getFileSize(File file, int maxfiles) Returns the size of indicated File (or directory) file.
float	getStorageRatio() Calculates the average document size, based on the ratio of the total count of documents in the entire database and the space in the filesystem used, in bytes.
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 kernel.
void	stop() Shuts down the database service.

Methods inherited from class org.ceryle.xnode.providers.AbstractXNodeStoreProvider

error, message, setPaths, storageExists, warning, writeXNodeToDatabase

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.purl.xnode.XNodeStoreProvider

storageExists, writeXNodeToDatabase

Field Detail

storageRatioThreshold

protected long storageRatioThreshold

The threshold ratio after which the cleaner thread is started.

Constructor Detail

BerkeleyDBProvider

public BerkeleyDBProvider()

Method Detail

initialize

public void initialize(XNodeStore xnodestore)
                throws XNodeStoreProviderException

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

Specified by:

initialize in interface XNodeStoreProvider

Overrides:

initialize in class AbstractXNodeStoreProvider

Parameters:

xnodestore - the parent XNodeStore.

Throws:

XNodeStoreProviderException - if any error occurs while initializing the provider.

start

public void start()
           throws XNodeStoreProviderException

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

Specified by:

start in interface XNodeStoreProvider

Specified by:

start in class AbstractXNodeStoreProvider

Throws:

XNodeStoreProviderException - if unable to start the database.

getEnvironment

public com.sleepycat.je.Environment getEnvironment()
                                            throws XNodeStoreProviderException

Returns the BerkeleyDB JE Environment used with this implementation.

This is not an XNode API method.

.

Throws:

XNodeStoreProviderException

stop

public void stop()
          throws XNodeStoreProviderException

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

Specified by:

stop in interface XNodeStoreProvider

Specified by:

stop in class AbstractXNodeStoreProvider

Throws:

XNodeStoreProviderException - if an error occurs while stopping the database.

getDatabase

public 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.

(This is an XNodeStoreProvider API method)

Specified by:

getDatabase in interface XNodeStoreProvider

Specified by:

getDatabase in class AbstractXNodeStoreProvider

Parameters:

did - the ID of the Database

Returns:

the backing Database.

Throws:

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

isLoadedDatabase

public boolean isLoadedDatabase(String did)

Returns true if the Database with key did has already been loaded.

Specified by:

isLoadedDatabase in interface XNodeStoreProvider

Overrides:

isLoadedDatabase in class AbstractXNodeStoreProvider

hasDatabase

public 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.)

(This is an XNodeStoreProvider API method)

Specified by:

hasDatabase in interface XNodeStoreProvider

Specified by:

hasDatabase in class AbstractXNodeStoreProvider

Parameters:

did - the ID of the Database to query.

Returns:

true if the Database exists.

Throws:

XNodeStoreProviderException - if any error occurs while querying.

getDatabaseIndex

public 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. Note that the returned List is immutable.

(This is an XNodeStoreProvider API method)

Specified by:

getDatabaseIndex in interface XNodeStoreProvider

Specified by:

getDatabaseIndex in class AbstractXNodeStoreProvider

Returns:

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

Throws:

XNodeStoreProviderException - if any error occurs while building the index.

closeDatabase

public 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.

(This is an XNodeStoreProvider API method)

Specified by:

closeDatabase in interface XNodeStoreProvider

Specified by:

closeDatabase in class AbstractXNodeStoreProvider

Parameters:

did - the ID of the Database to close.

Throws:

XNodeStoreProviderException - if any error occurs while closing the Database.

deleteDatabase

public void deleteDatabase(String did)
                    throws XNodeStoreProviderException

Delete the Database backing the XNodeCollection having ID did.

(This is an XNodeStoreProvider API method)

Specified by:

deleteDatabase in interface XNodeStoreProvider

Specified by:

deleteDatabase in class AbstractXNodeStoreProvider

Parameters:

did - the ID of the Database to delete.

Throws:

XNodeStoreProviderException - if any error occurs while deleting the Database.

putContent

public 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.

(This is an XNodeStoreProvider API method)

Specified by:

putContent in interface XNodeStoreProvider

Specified by:

putContent in class AbstractXNodeStoreProvider

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

public 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.

(This is an XNodeStoreProvider API method)

Specified by:

hasContent in interface XNodeStoreProvider

Specified by:

hasContent in class AbstractXNodeStoreProvider

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

public 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.

(This is an XNodeStoreProvider API method)

Specified by:

getContentSize in interface XNodeStoreProvider

Specified by:

getContentSize in class AbstractXNodeStoreProvider

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

public 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.

(This is an XNodeStoreProvider API method)

Specified by:

getContent in interface XNodeStoreProvider

Specified by:

getContent in class AbstractXNodeStoreProvider

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

public 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.

(This is an XNodeStoreProvider API method)

Specified by:

deleteContent in interface XNodeStoreProvider

Specified by:

deleteContent in class AbstractXNodeStoreProvider

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

public 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.

(This is an XNodeStoreProvider API method)

Specified by:

getDocumentIndex in interface XNodeStoreProvider

Specified by:

getDocumentIndex in class AbstractXNodeStoreProvider

Parameters:

did - the ID of the Database.

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

optimize

public 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.

Notes

Checks the ratio of storage space to database record count to determine average file size, and if the average file size falls above a threshold, starts a low-priority cleaner thread.

If the ActionListener is non-null, its actionPerformed() method will receive an ActionEvent upon completion of the cleanup (from this application's perspective; what happens within BerkeleyDB JE timing-wise is relatively unknown).

Note that this method does not throw any exceptions; it only writes error messages to the MessageHandler.

Specified by:

optimize in interface XNodeStoreProvider

Overrides:

optimize in class AbstractXNodeStoreProvider

Parameters:

listener - an optional listener to receive notification upon completion.

getStorageRatio

public float getStorageRatio()

Calculates the average document size, based on the ratio of the total count of documents in the entire database and the space in the filesystem used, in bytes. This is returned as a ratio of that value and the storageRatioThreshold, e.g., with a threshold of 20K (the default) if the average file size was 40K this would return a value of 2.0.

If the database is disconnected, returns a zero value.

getFileSize

public static long getFileSize(File file,
                               int maxfiles)
                        throws IOException

Returns the size of indicated File (or directory) file. This is recursive so any loops in the structure will cause a continuous loop. To keep this from happening infinitely, if the file count reaches the limit set by maxfiles it will throw an exception to exit. This is admittedly a more primitive solution than checking for previous access.

Throws:

IOException - if the File reference is null, does not exist, or can't be read.