org.ceryle.xnode.providers
Class AbstractXNodeStoreProvider

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

All Implemented Interfaces:

XNodeStoreProvider

Direct Known Subclasses:

BerkeleyDBProvider, FileSystemProvider

public abstract class AbstractXNodeStoreProvider
extends Object
implements XNodeStoreProvider

An implementation of the XNodeStoreProvider API as the basis for implementing common behaviours of an XNodeStoreProvider, in particular the use of the Apache serialization features. initialize(XNodeStore) must be called following instantiation of the class to initialize the provider.

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: AbstractXNodeStoreProvider.java,v 1.1 2007-06-15 12:08:26 altheim Exp $

Author:

Murray Altheim

Field Summary

static String	Filesep
protected String	m_homepath
protected File	m_storage
protected String	m_storagepath
protected XNodeStore	m_xns
protected MessageHandler	mh

Constructor Summary

AbstractXNodeStoreProvider()
Default constructor.

Method Summary

abstract void	closeDatabase(String did) Close the Database backing the XNodeCollection having ID did.
abstract 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.
abstract void	deleteDatabase(String did) Remove the Database backing the XNodeCollection having ID did.
void	error(String message) Write message to console or message output as an error message.
abstract 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.
abstract 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).
abstract Object	getDatabase(String did) Return the Database backing the XNodeCollection having ID did.
abstract List	getDatabaseIndex() Returns the List of existing Database IDs.
abstract List	getDocumentIndex(String did) Returns the document index, sorted, created from the Database, not the XNode metadata.
abstract boolean	hasContent(String did, String rid) Returns true if the Database with ID did contains data matching the key String rid (record ID).
abstract 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	message(String message) Write message to console or message output as an informational message.
void	optimize(ActionListener listener) Using any native processes, optimizes the Database.
abstract 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).
protected void	setPaths()
abstract void	start() Start the database service.
abstract void	stop() Shuts down the database service.
boolean	storageExists() Returns true if the storage directory exists.
void	warning(String message) Write message to console or message output as a warning message.
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.

Methods inherited from class java.lang.Object

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

Field Detail

m_homepath

protected String m_homepath

m_storagepath

protected String m_storagepath

m_storage

protected File m_storage

mh

protected MessageHandler mh

m_xns

protected XNodeStore m_xns

Filesep

public static final String Filesep

Constructor Detail

AbstractXNodeStoreProvider

public AbstractXNodeStoreProvider()

Default constructor.

Method Detail

initialize

public void initialize(XNodeStore xnodestore)
                throws XNodeStoreProviderException

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

(This is an XNodeStoreProvider API method)

Specified by:

initialize in interface XNodeStoreProvider

Parameters:

xnodestore - the parent XNodeStore.

Throws:

XNodeStoreProviderException - if any error occurs while initializing the provider.

setPaths

protected void setPaths()
                 throws XNodeStoreProviderException

Throws:

XNodeStoreProviderException

storageExists

public boolean storageExists()

Returns true if the storage directory exists.

Specified by:

storageExists in interface XNodeStoreProvider

start

public abstract void start()
                    throws XNodeStoreProviderException

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

Specified by:

start in interface XNodeStoreProvider

Throws:

XNodeStoreProviderException - if unable to start the database.

stop

public abstract void stop()
                   throws XNodeStoreProviderException

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

Specified by:

stop in interface XNodeStoreProvider

Throws:

XNodeStoreProviderException - if an error occurs while stopping the database.

isLoadedDatabase

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

Specified by:

isLoadedDatabase in interface XNodeStoreProvider

getDatabase

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

If did equals the root ID ("db"), use that as the base name, otherwise the root should be added as part of the path , e.g., "db/did".

(This is an XNodeStoreProvider API method)

Specified by:

getDatabase in interface XNodeStoreProvider

Parameters:

did - the ID of the Database

Returns:

null.

Throws:

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

hasDatabase

public abstract boolean hasDatabase(String did)
                             throws XNodeStoreProviderException

Returns true if there is an existing Database with key did. This directly queries the stored databases (as directories) from the file system.

(This is an XNodeStoreProvider API method)

Specified by:

hasDatabase in interface XNodeStoreProvider

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 abstract List getDatabaseIndex()
                               throws XNodeStoreProviderException

Returns the List of existing Database IDs. This directly queries the stored databases (as directories) from the file system, 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.

(This is an XNodeStoreProvider API method)

Specified by:

getDatabaseIndex in interface XNodeStoreProvider

Returns:

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

Throws:

XNodeStoreProviderException - if any error occurs while building the index.

closeDatabase

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

Specified by:

closeDatabase in interface XNodeStoreProvider

Parameters:

did - the ID of the Database to close.

Throws:

XNodeStoreProviderException - if any error occurs while closing the Database.

deleteDatabase

public abstract void deleteDatabase(String did)
                             throws XNodeStoreProviderException

Remove the Database backing the XNodeCollection having ID did.

This will ignore requests to delete the root directory ("db").

(This is an XNodeStoreProvider API method)

Specified by:

deleteDatabase in interface XNodeStoreProvider

Parameters:

did - the ID of the Database to delete.

Throws:

XNodeStoreProviderException - if any error occurs while removing the Database.

putContent

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

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 abstract 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

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 abstract 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

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 abstract 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

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 abstract 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

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 abstract List getDocumentIndex(String did)
                               throws XNodeStoreProviderException

Returns the document index, sorted, created from the Database, not the XNode metadata. The collection ID is only used for error messages and is optional.

(This is an XNodeStoreProvider API method)

Specified by:

getDocumentIndex in interface XNodeStoreProvider

Parameters:

did - the ID of the Database.

Returns:

a List containing the IDs of the XNodes in this XNodeCollection.

Throws:

XNodeStoreProviderException - if an error occurs obtaining the document index.

Since:

XNode 1.2

writeXNodeToDatabase

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

(This is an XNodeStoreProvider API method)

Specified by:

writeXNodeToDatabase in interface XNodeStoreProvider

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

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.

In this abstract class this is a stub method and does nothing.

Specified by:

optimize in interface XNodeStoreProvider

Parameters:

listener - an optional listener to receive notification upon completion.

message

public void message(String message)

Write message to console or message output as an informational message.

warning

public void warning(String message)

Write message to console or message output as a warning message.

error

public void error(String message)

Write message to console or message output as an error message.