org.purl.xnode
Interface XNodeStore

All Known Implementing Classes:

XNodeStoreImpl

public interface XNodeStore

Defines a database manager API for XNode content.

The XNode API (the package org.purl.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.0

Version:

$Id: XNodeStore.java,v 3.13 2007-06-20 01:28:44 altheim Exp $

Author:

Murray Altheim

Field Summary

static String	ALL_COLLECTIONS A String indicator used to refer to all maintained collections.
static String	DATABASE_ROOT The System property name for the XNode database root URI.
static String	FEATURE_COPY_MOVE A property indicating support for copy and move operations.
static String	XNODE_DEFAULT_ROOT The default value of the URL for the root collection.
static String	XNODE_PROTOCOL The protocol name for XNode.

Method Summary

XNode	addXNode(String cid, String nid, Node node) Add a new XNode with ID nid, whose content is the DOM Node node, to the XNodeCollection with ID cid.
XNode	addXNode(String cid, String nid, String content) Insert a new XNode with ID nid whose content is the String content, into the XNodeCollection with ID cid, returning the ID value of the added XNode.
void	addXNodeStoreListener(XNodeStoreListener listener) Adds listener as a listener for changes to the XNodeStore.
boolean	closeCollection(String cid) Close an existing XNodeCollection cid.
void	connect(String root, String driver, int timeout) Make a database connection to the XNodeCollection root and establish service, using timeout as the maximum number of seconds to wait for the collection manager to open before abandoning.
void	copyXNode(String scid, String snid, String dcid, String dnid, boolean move, boolean overwrite) Copy the XNode with ID snid from Collection scid to XNode nid in the Collection ID cid.
void	copyXNode(XNodeID xids, XNodeID xidd, boolean move, boolean overwrite) Copy the XNode with XNodeID xids to XNodeID xidd.
XNodeCollection	createCollection(String cid, boolean overwrite) Create an new XNodeCollection identified by the ID cid.
XNode	createRevision(String cid, String nid) Creates a revision of the specified XNode, storing it internal to the XNode.
XNode	createRevision(XNode xnode) Creates a revision of the provided XNode, storing it internal to the XNode.
XNode	createRevision(XNodeID xid) Creates a revision of the specified XNode, storing it internal to the XNode.
XNode	createXNode(String nid, Node node) Returns an XNode provided a DOM Node node.
void	deleteCollection(String cid) Delete an existing XNodeCollection cid.
void	deleteXNode(String cid, String nid) Delete the XNode identified by ID nid from the XNodeCollection cid.
void	deleteXNode(XNodeID xid) Delete the XNode identified by the XNodeID xid.
void	disconnect() Disconnect any connection to the root XNodeCollection and close down all services.
XNodeCollection	getCollection(String cid) Return an existing XNodeCollection whose ID is cid, null if it does not exist.
List	getCollectionIndex() Return a List containing the IDs of all available XNodeCollections.
String	getCollectionMetadata(String cid, String name) Return the value of the XNodeCollection metadata property name for the XNodeCollection whose ID is cid, null if it has not been set.
String	getDatabaseURI(String cid, String nid) Returns a URI representing the Collection ID cid and Node ID id using the currently available database base URI.
List	getIndex(String cid) Return a List containing the XNode IDs (as Strings) within the XNodeCollection cid.
XNodeRevisionManager	getRevisionManager() Returns the XNodeRevisionManager for this XNodeStore, null if revision control is not active or supported.
XNodeCollection	getRootCollection() Returns the root database XNodeCollection.
String	getRootURI() Return the URI of the root XNodeCollection as a String.
XNodeState	getState() Return the state of this XNodeStore, as according to the processing states enumerated in XNodeState.
XNode	getXNode(String cid, String nid) Retrieves an XNode with ID nid from XNodeCollection with ID cid, or null if unable to retrieve.
XNode	getXNode(XNodeID xid) Retrieves an XNode specified via the XNodeID xid, or null if unable to retrieve.
XNodeCollectionFactory	getXNodeCollectionFactory() Returns a lazily-instantiated XNodeCollectionFactory.
Node	getXNodeContent(XNode xnode) Returns the DOM Node node envelope provided an XNode.
XNodeFactory	getXNodeFactory() Returns the XNodeFactory associated with this XNodeStore.
boolean	hasCollection(String cid) Returns true if the XNodeCollection whose ID is cid exists.
boolean	hasXNode(String cid, String nid) Returns true if an XNode with ID nid exists in the XNodeCollection with ID cid.
boolean	hasXNode(XNodeID xid) Returns true if an XNode matching the XNodeID xid exists, false if not.
boolean	isConnected() Returns true if a connection with database has been made and its service is available.
boolean	isRevisionControlActive() Returns true if revision control features are active.
XNode	modifyXNode(String cid, String nid, Node node) Modify an XNode with ID nid, whose content is the DOM Node node, in the XNodeCollection with ID cid.
XNode	modifyXNode(String cid, String nid, String content) Modify an XNode with ID nid in XNodeCollection cid, replacing its contents with the contents of the String content.
XNode	modifyXNode(XNodeID xid, Node node) Modify an XNode with XNodeID xid, replacing its content with the DOM Node node, returning the modified XNode.
void	removeXNodeStoreListener(XNodeStoreListener listener) Removes listener from the XNodeStore.
void	setCollectionMetadata(String cid, String name, String value) Set a metadata property of XNodeCollection metadata (a name-value pair) for the XNodeCollection whose ID is cid.
void	setXNodeProperties(XNode xnode, Map properties) For an XNode with ID nid in XNodeCollection cid, set the named properties provided by the key-value pairs found in the Map properties.
void	setXNodeProperty(XNode xnode, String name, String value) For an XNode with ID nid in XNodeCollection cid, set the named property name whose value is the String value.
void	start() Start the database service.
void	stop() Stop the database service.
String	toURI(XNodeID xid) Returns a URI representation of the XNodeID xid based on the root database URI, eg., ""xnode://db/cid/nid".
XNode	writeXNode(String cid, XNode xnode) Write the XNode xnode to the XNodeCollection cid.

Field Detail

DATABASE_ROOT

static final String DATABASE_ROOT

The System property name for the XNode database root URI. The value is "xnode-database-root".

See Also:

Constant Field Values

XNODE_PROTOCOL

static final String XNODE_PROTOCOL

The protocol name for XNode. The value is "xnode://".

See Also:

Constant Field Values

XNODE_DEFAULT_ROOT

static final String XNODE_DEFAULT_ROOT

The default value of the URL for the root collection. The value is "xnode://db/".

See Also:

Constant Field Values

ALL_COLLECTIONS

static final String ALL_COLLECTIONS

A String indicator used to refer to all maintained collections.

FEATURE_COPY_MOVE

static final String FEATURE_COPY_MOVE

A property indicating support for copy and move operations. The value is "http://purl.org/xnode/1.2/feature/copy-move". If this property is set to "true" it indicates the implementation supports the copyXNode(String,String,String,String,boolean,boolean) and copyXNode(XNodeID,XNodeID,boolean,boolean) methods.

See Also:

Constant Field Values

Method Detail

getXNodeFactory

XNodeFactory getXNodeFactory()

Returns the XNodeFactory associated with this XNodeStore.

getXNodeCollectionFactory

XNodeCollectionFactory getXNodeCollectionFactory()

Returns a lazily-instantiated XNodeCollectionFactory.

getRootCollection

XNodeCollection getRootCollection()
                                  throws XNodeException

Returns the root database XNodeCollection. If the database implementation does not support a root XNodeCollection, this should throw an UnsupportedOperationException.

Returns:

the root database XNodeCollection.

Throws:

XNodeException

Since:

XNode 1.0

getState

XNodeState getState()

Return the state of this XNodeStore, as according to the processing states enumerated in XNodeState.

Returns:

the current state of this XNodeStore

Since:

XNode 1.1

See Also:

XNodeState

start

void start()
           throws XNodeException

Start the database service.

Throws:

XNodeException - if an error occurs during starting the database.

Since:

XNode 1.2

stop

void stop()
          throws XNodeException

Stop the database service.

Throws:

XNodeException - if an error occurs during shutdown.

Since:

XNode 1.2

connect

void connect(String root,
             String driver,
             int timeout)
             throws XNodeException

Make a database connection to the XNodeCollection root and establish service, using timeout as the maximum number of seconds to wait for the collection manager to open before abandoning. Setting this to zero will cause it to wait indefinitely. For systems that do not use a remote connection, the timeout may be ignored.

Note that implementations that are not client-server will not implement this method.

Parameters:

root - the URI of the root XNodeCollection.

driver - the driver identifier for the database provider

timeout - time in seconds to wait before abandoning.

Throws:

XNodeException - if unable to make the connection.

Since:

XNode 1.0

disconnect

void disconnect()
                throws XNodeException

Disconnect any connection to the root XNodeCollection and close down all services.

Note that implementations that are not client-server will not implement this method.

Throws:

XNodeException - if an error occurs during this process.

Since:

XNode 1.0

isConnected

boolean isConnected()

Returns true if a connection with database has been made and its service is available.

Returns:

true if a database connection has been made.

Since:

XNode 1.0

isRevisionControlActive

boolean isRevisionControlActive()

Returns true if revision control features are active.

createCollection

XNodeCollection createCollection(String cid,
                                 boolean overwrite)
                                 throws XNodeException

Create an new XNodeCollection identified by the ID cid. If overwrite is true, this will overwrite any existing XNodeCollection with the same ID. If false, attempts to overwrite an existing XNodeCollection throw an XNodeException.

Parameters:

cid - the XNodeCollection ID String.

overwrite - if true, will overwrite any existing XNodeCollection.

Returns:

the new XNodeCollection

Throws:

XNodeException - if unable to create the XNodeCollection

Since:

XNode 1.0

getCollection

XNodeCollection getCollection(String cid)
                              throws XNodeException

Return an existing XNodeCollection whose ID is cid, null if it does not exist.

Parameters:

cid - the XNodeCollection ID String.

Returns:

the XNodeCollection matching ID 'cid', null if it doesn't exist.

Throws:

XNodeException - if unable to locate the XNodeCollection

Since:

XNode 1.0

hasCollection

boolean hasCollection(String cid)

Returns true if the XNodeCollection whose ID is cid exists.

Parameters:

cid - the XNodeCollection ID String.

Returns:

true if the XNodeCollection matching ID 'cid' exists.

Since:

XNode 1.2

getCollectionIndex

List getCollectionIndex()
                        throws XNodeException

Return a List containing the IDs of all available XNodeCollections. This returns an empty List rather than null.

Returns:

a List containing all available XNodeCollection IDs.

Throws:

XNodeException - if unable to provide the List.

Since:

XNode 1.0

getIndex

List getIndex(String cid)
              throws XNodeException

Return a List containing the XNode IDs (as Strings) within the XNodeCollection cid. This returns an empty List rather than null.

Parameters:

cid - the XNodeCollection ID String.

Returns:

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

Throws:

XNodeException - if the ID is invalid or the XNodeCollection(s) did not exist.

Since:

XNode 1.0

closeCollection

boolean closeCollection(String cid)
                        throws XNodeException

Close an existing XNodeCollection cid. If the value equals ALL_COLLECTIONS, will close all open XNodeCollection.

Parameters:

cid - the XNodeCollection ID String.

Returns:

true if the XNodeCollection was successfully closed.

Throws:

XNodeException - if the ID is invalid or the XNodeCollection(s) did not exist.

Since:

XNode 1.0

deleteCollection

void deleteCollection(String cid)
                      throws XNodeException

Delete an existing XNodeCollection cid. If the ID value is ALL_COLLECTIONS, will delete all existing XNodeCollection.

Parameters:

cid - the XNodeCollection ID String.

Throws:

XNodeException - if the XNodeCollection ID is invalid, the XNodeCollection(s) did not exist, or an error occurred.

Since:

XNode 1.0

setCollectionMetadata

void setCollectionMetadata(String cid,
                           String name,
                           String value)
                           throws XNodeException

Set a metadata property of XNodeCollection metadata (a name-value pair) for the XNodeCollection whose ID is cid.

Throws:

XNodeException

Since:

XNode 1.2

getCollectionMetadata

String getCollectionMetadata(String cid,
                             String name)
                             throws XNodeException

Return the value of the XNodeCollection metadata property name for the XNodeCollection whose ID is cid, null if it has not been set.

Throws:

XNodeException

Since:

XNode 1.2

hasXNode

boolean hasXNode(XNodeID xid)

Returns true if an XNode matching the XNodeID xid exists, false if not.

Parameters:

xid - the XNodeID.

Returns:

true if the XNode exists.

hasXNode

boolean hasXNode(String cid,
                 String nid)
                 throws XNodeException

Returns true if an XNode with ID nid exists in the XNodeCollection with ID cid. Throws an XNodeException if the specified XNodeCollection does not exist or either ID is invalid.

Parameters:

cid - the XNodeCollection ID String.

nid - the ID String for the stored XNode.

Returns:

true if the XNode exists.

Throws:

XNodeException - if either ID is invalid.

Since:

XNode 1.0

getXNode

XNode getXNode(XNodeID xid)
               throws XNodeException

Retrieves an XNode specified via the XNodeID xid, or null if unable to retrieve.

Parameters:

xid - the XNodeID.

Returns:

the retrieved XNode.

Throws:

XNodeException - if an error occurs retrieving the XNodeCollection or XNode.

getXNode

XNode getXNode(String cid,
               String nid)
               throws XNodeException

Retrieves an XNode with ID nid from XNodeCollection with ID cid, or null if unable to retrieve. Note that the retrieved XNode content includes its wrapper elements and is returned as a DOM Node, then reconstituted as an XNode object.

Parameters:

cid - the XNodeCollection ID String.

nid - the XNode ID String.

Returns:

the retrieved XNode.

Throws:

XNodeException - if the XNodeCollection does not exist or either ID is invalid.

Since:

XNode 1.0

createXNode

XNode createXNode(String nid,
                  Node node)
                  throws XNodeException

Returns an XNode provided a DOM Node node. The provided content is that meant to be enclosed in the envelope. The XNode is created but not written to the XNodeStore.

Parameters:

nid - the ID String of the stored XNode.

node - the DOM Node to be used as the XNode source.

Returns:

the created XNode.

Throws:

XNodeException - if unable to create the XNode.

Since:

XNode 1.2

addXNode

XNode addXNode(String cid,
               String nid,
               String content)
               throws XNodeException

Insert a new XNode with ID nid whose content is the String content, into the XNodeCollection with ID cid, returning the ID value of the added XNode.

Note:

This method implies that the supplied content String be well-formed XML, as it will by necessity be parsed into a DOM Node. If not well-formed XML, an exception is thrown and nothing is stored.

Parameters:

cid - the XNodeCollection ID String.

nid - the ID String of the stored XNode.

content - the String content to be parsed into a DOM Node.

Returns:

the new XNode.

Throws:

XNodeException - if unable to add the XNode.

Since:

XNode 1.0

addXNode

XNode addXNode(String cid,
               String nid,
               Node node)
               throws XNodeException

Add a new XNode with ID nid, whose content is the DOM Node node, to the XNodeCollection with ID cid. This returns the ID value of the added XNode.

Parameters:

cid - the XNodeCollection ID String.

nid - the ID String for the stored XNode.

node - the DOM Node content.

Returns:

the new XNode.

Throws:

XNodeException - if unable to add the XNode.

Since:

XNode 1.0

modifyXNode

XNode modifyXNode(String cid,
                  String nid,
                  String content)
                  throws XNodeException

Modify an XNode with ID nid in XNodeCollection cid, replacing its contents with the contents of the String content.

Parameters:

cid - the XNodeCollection ID String.

nid - the ID String of the stored XNode.

content - the String content to be parsed into a DOM Node.

Returns:

the modified XNode.

Throws:

XNodeException - if unable to modify the XNode.

Since:

XNode 1.0

modifyXNode

XNode modifyXNode(String cid,
                  String nid,
                  Node node)
                  throws XNodeException

Modify an XNode with ID nid, whose content is the DOM Node node, in the XNodeCollection with ID cid.

Parameters:

cid - the XNodeCollection ID String.

nid - the ID String for the stored XNode.

node - the DOM Node content.

Returns:

the modified XNode.

Throws:

XNodeException - if unable to modify the XNode.

Since:

XNode 1.0

modifyXNode

XNode modifyXNode(XNodeID xid,
                  Node node)
                  throws XNodeException

Modify an XNode with XNodeID xid, replacing its content with the DOM Node node, returning the modified XNode.

Parameters:

xid - the XNode identifier.

node - the new DOM Node content.

Returns:

the modified XNode

Throws:

XNodeException - if unable to add the XNode to the XNodeCollection.

writeXNode

XNode writeXNode(String cid,
                 XNode xnode)
                 throws XNodeException

Write the XNode xnode to the XNodeCollection cid. This locates any existing XNode by ID and replaces it with the provided one.

Note:

This method is generally used to set metadata on an existing XNode, so document-level metadata (e.g., creation or modification timestamps) are not altered by this method — this just writes the XNode to the XNodeCollection.

Parameters:

cid - the XNodeCollection ID String.

xnode - the XNode to be written.

Returns:

the stored XNode

Throws:

XNodeException - if unable to write the XNode to the XNodeCollection.

Since:

XNode 1.0

deleteXNode

void deleteXNode(String cid,
                 String nid)
                 throws XNodeException

Delete the XNode identified by ID nid from the XNodeCollection cid.

Parameters:

cid - the XNodeCollection ID String.

nid - the XNode ID String.

Throws:

XNodeException - if unable to delete the XNode.

Since:

XNode 1.0

deleteXNode

void deleteXNode(XNodeID xid)
                 throws XNodeException

Delete the XNode identified by the XNodeID xid.

Parameters:

xid - the XNodeID identifier for the XNode.

Throws:

XNodeException - if the XNode does not exist or otherwise unable to delete.

getXNodeContent

Node getXNodeContent(XNode xnode)
                     throws XNodeException

Returns the DOM Node node envelope provided an XNode.

Parameters:

xnode - the XNode to be processed

Returns:

the created DOM node.

Throws:

XNodeException - if an error occurs during recreation.

Since:

XNode 1.0

setXNodeProperty

void setXNodeProperty(XNode xnode,
                      String name,
                      String value)
                      throws XNodeException

For an XNode with ID nid in XNodeCollection cid, set the named property name whose value is the String value.

Note:

This only modifies the property of the supplied XNode and does not involve any transactions with the database, which must be performed separately.

Parameters:

xnode - the XNode to which the property is set.

name - the name of the property.

value - the value of the property.

Throws:

XNodeException - if the XNode does not exist or the property is invalid.

Since:

XNode 1.0

setXNodeProperties

void setXNodeProperties(XNode xnode,
                        Map properties)
                        throws XNodeException

For an XNode with ID nid in XNodeCollection cid, set the named properties provided by the key-value pairs found in the Map properties. This is to provide some efficiency over setting properties individually, which requires a save operation for each property. A null value will clear the property.

Note:

This only modifies the properties of the supplied XNode and does not involve any transactions with the database, which must be performed separately.

Parameters:

xnode - the XNode to which the properties are to be set.

properties - the Map containing the properties.

Throws:

XNodeException - if the XNode does not exist or any of the properties are invalid.

Since:

XNode 1.0

getRootURI

String getRootURI()

Return the URI of the root XNodeCollection as a String.

Returns:

the URI of the root XNodeCollection.

Since:

XNode 1.0

getDatabaseURI

String getDatabaseURI(String cid,
                      String nid)

Returns a URI representing the Collection ID cid and Node ID id using the currently available database base URI. If nid is null, a URI for the Collection alone is returned. If both cid and nid are null, null is returned.

Parameters:

cid - the collection ID.

nid - the node ID.

Returns:

a URI (as a String).

Since:

XNode 1.2

toURI

String toURI(XNodeID xid)

Returns a URI representation of the XNodeID xid based on the root database URI, eg., ""xnode://db/cid/nid".

Parameters:

xid - the XNodeID to convert to a URI.

Returns:

a URI (as a String).

Since:

XNode 1.2

copyXNode

void copyXNode(String scid,
               String snid,
               String dcid,
               String dnid,
               boolean move,
               boolean overwrite)
               throws XNodeException

Copy the XNode with ID snid from Collection scid to XNode nid in the Collection ID cid. See notes on copyXNode(XNodeID,XNodeID,boolean,boolean).

Parameters:

scid - the source Collection ID.

snid - the source XNode ID.

dcid - the destination Collection ID.

dnid - the destination XNode ID.

move - when true, deletes the source XNode

overwrite - when true, will overwrite any existing dcid/dnid

Throws:

XNodeException - if the copy/move is not successful.

copyXNode

void copyXNode(XNodeID xids,
               XNodeID xidd,
               boolean move,
               boolean overwrite)
               throws XNodeException

Copy the XNode with XNodeID xids to XNodeID xidd. If move is true, will delete the source XNode once the copy has completed. If overwrite is false, an attempt to overwrite will not succeed (registering an error).

Optional Operation

This is an optional operation. If supported, the System property "http://purl.org/xnode/1.2/feature/copy-move" (see FEATURE_COPY_MOVE) of supporting implementations will return a value of "true". If not supported, will throw an UnsupportedOperationException.

Parameters:

xids - the source XNodeID.

xidd - the destination XNodeID.

move - when true, deletes the source XNode

overwrite - when true, will overwrite any existing dcid/dnid

Throws:

XNodeException - if the copy/move is not successful.

addXNodeStoreListener

void addXNodeStoreListener(XNodeStoreListener listener)
                           throws UnsupportedOperationException

Adds listener as a listener for changes to the XNodeStore.

Note:

XNodeStoreListener extends ChangeListener as a listener for changes to the XNodeStore, e.g., connecting or disconnecting from the database. In contexts where listeners are inappropriate, implementations should throw an UnsupportedOperationException upon an attempt to add a listener.

Parameters:

listener - the XNodeStoreListener to be added

Throws:

UnsupportedOperationException - if listener support is unavailable

Since:

XNode 1.1

See Also:

XNodeStoreListener

removeXNodeStoreListener

void removeXNodeStoreListener(XNodeStoreListener listener)

Removes listener from the XNodeStore. See the note at addXNodeStoreListener(XNodeStoreListener) for details.

Parameters:

listener - the XNodeStoreListener to be removed

Throws:

UnsupportedOperationException - if listener support is unavailable

Since:

XNode 1.1

See Also:

XNodeStoreListener

getRevisionManager

XNodeRevisionManager getRevisionManager()

Returns the XNodeRevisionManager for this XNodeStore, null if revision control is not active or supported.

Since:

XNode 1.2

createRevision

XNode createRevision(String cid,
                     String nid)
                     throws XNodeException

Creates a revision of the specified XNode, storing it internal to the XNode. This does not write to the database.

Parameters:

cid - the XNodeCollection ID String.

nid - the XNode ID String.

Returns:

the XNode, modified if the revision has been created.

Throws:

XNodeException - if an error occurs in creating the revision.

Since:

XNode 1.2

createRevision

XNode createRevision(XNodeID xid)
                     throws XNodeException

Creates a revision of the specified XNode, storing it internal to the XNode. This does not write to the database.

Parameters:

xid - the XNodeID specifying the XNode.

Returns:

the XNode, modified if the revision has been created.

Throws:

XNodeException - if an error occurs in creating the revision.

Since:

XNode 1.2

createRevision

XNode createRevision(XNode xnode)
                     throws XNodeException

Creates a revision of the provided XNode, storing it internal to the XNode. This does not write to the database.

Parameters:

xnode - the XNode to be processed.

Returns:

the XNode, modified if the revision has been created.

Throws:

XNodeException - if an error occurs in creating the revision.

Since:

XNode 1.2