org.ceryle.xnode
Class XNodeCollectionImpl

java.lang.Object
  org.purl.xnode.XNode
      org.ceryle.xnode.XNodeImpl
          org.ceryle.xnode.XNodeCollectionImpl

All Implemented Interfaces:

Comparable, XNodeCollection

public class XNodeCollectionImpl
extends XNodeImpl
implements Comparable, XNodeCollection

XNodeCollectionImpl implements XNodeCollection, an interface for a collection of XNodes, with methods also supporting a hierarchy of XNodeCollections.

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.

The class extends XNodeImpl, using a modified DOM version of the XNode as the metadata repository, and adding in the machinery to communicate with the backing database store.

Note that in this implementation, built upon Berkeley DB JE, individual XNodes are stored within JE Databases, which are not stored within the XNodeCollection itself, only referenced by it. The XNodeCollection is is the link between the metadata and the data; in effect, a registry object. All XNodeCollections are stored within the root XNodeCollection's Database (rather than in their own), and their IDs within the root XNodeCollection's own metadata. This does preclude any subcollection having the same ID as the root (which might be confusing anyway).

The document index is initially read from the DOM <xnode:Collection> Element's index attribute, then maintained in an internal Collection. If the XNode is serialized, the DOM is harmonized when the getIndex() method is called, if the index is dirty.

Since:

XNode 1.2

Version:

$Id: XNodeCollectionImpl.java,v 3.5 2007-06-20 01:28:40 altheim Exp $

Author:

Murray Altheim

Field Summary

Fields inherited from class org.ceryle.xnode.XNodeImpl

m_content, m_document, PERMIT_XML_CONTENT, PFX_ATTR_created, PFX_ATTR_modified, PFX_ATTR_xmlns, PFX_ELT_link, PFX_ELT_property, PRESERVE_WS, PROPERTY_DOCTYPE_NAME, PROPERTY_EXTENSION, PROPERTY_PUBLIC_ID, PROPERTY_SYSTEM_ID, VALUE_STORED_AS_ATTRIBUTE

Fields inherited from class org.purl.xnode.XNode

ATTR_created, ATTR_id, ATTR_index, ATTR_modified, ATTR_name, ATTR_size, ATTR_value, ATTR_version, ATTR_weight, ELT_body, ELT_collection, ELT_envelope, ELT_header, ELT_link, ELT_property, ELT_repository, ELT_revision, ELT_text, VERSION_10, VERSION_11, VERSION_12, VERSION_13, XMLNS_base, XMLNS_pfx, XMLNS_xnode, XMLNS_xnode10, XMLNS_xnode11, XMLNS_xnode12, XMLNS_xnode13

Fields inherited from interface org.purl.xnode.XNodeCollection

ROOT_ID

Constructor Summary

protected

XNodeCollectionImpl(XNodeStore xnodestore, String cid, String created, Node node) Constructor for a new XNodeCollection, with a required ID cid.

Method Summary

boolean	addCollection(XNodeCollection collection) Add a child XNodeCollection collection to this XNodeCollection.
boolean	addXNode(XNode xnode, boolean overwrite) Writes the XNode xnode to this XNodeCollection.
boolean	close() Close this XNodeCollection's database.
int	compareTo(Object o) Compares this object with the specified object for order.
XNodeCollection	getCollection(String cid) Return the child XNodeCollection with ID cid of this XNodeCollection, or null if unavailable.
protected Element	getCollectionElement() Return this Collection's <xnode:Collection> Element.
List	getCollectionIndex() Returns a List containing the IDs of child XNodeCollections, based on the internally-stored metadata.
List	getIndex() Returns a List containing this XNodeCollection's index of XNode IDs.
int	getIndexCount() Returns the number of XNodes in this XNodeCollection.
XNodeCollection	getParentCollection() Return the parent XNodeCollection of this XNodeCollection, or null if no parent XNodeCollection exists.
static XNodeCollection	getRootCollection() Return the root XNodeCollection, null if not yet instantiated.
XNode	getXNode(String nid) Retrieves the XNode with ID nid from this XNodeCollection, returning null if it does not exist.
boolean	hasCollection(String cid) Returns true if a child XNodeCollection with ID cid exists as a child XNodeCollection of this XNodeCollection, false otherwise.
boolean	hasXNode(String nid) Returns true if the XNode ID nid exists as a key in this XNodeCollection.
boolean	isDirty() Returns the dirty state of the collection (true if any changes have occurred).
void	printCollections() Prints the collections currently found in the cache to System.err.
boolean	removeCollection(String cid) Remove a child XNodeCollection with ID cid from this XNodeCollection.
boolean	removeXNode(String nid) Removes the XNode whose ID is xnode from this XNodeCollection.
void	setCollectionIndexDirty()
void	setContent(Node node) Sets the content of this XNodeCollection to the Node node (which can be a DOM Document or Element node), throwing an XNodeException if the content is already set.
void	setDirty() Sets the dirty state of the collection to true.
protected void	setIndex(List list) Forceably sets the node index to the contents of the provided List.
String	toString() Return a String representation of this XNodeCollection.

Methods inherited from class org.ceryle.xnode.XNodeImpl

getBodyElement, getContent, getCreated, getDocument, getEnvelopeElement, getHeaderElement, getID, getModified, getProperties, getProperty, getRepository, getRepositoryElement, hasRepository, modifyContent, setCreated, setID, setModified, setProperty, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.purl.xnode.XNodeCollection

getContent, getCreated, getID, getModified, getProperties, getProperty, setCreated, setID, setModified, setProperty

Constructor Detail

XNodeCollectionImpl

protected XNodeCollectionImpl(XNodeStore xnodestore,
                              String cid,
                              String created,
                              Node node)
                       throws XNodeException

Constructor for a new XNodeCollection, with a required ID cid. If the parameter for the parent XNodeCollection is not null, this XNodeCollection parameter will be added to the parameter as a child collection. If an attempt is made to instantiate the root collection after it already exists, an exception is thrown.

Parameters:

xnodestore - the XNodeStore supporting the collection.

cid - the XNodeCollection ID.

created - the required creation timestamp.

node - the XNodeCollection ID.

Throws:

XNodeException - if the ID value is not an XML Name.

Since:

XNode 1.2

Method Detail

getRootCollection

public static XNodeCollection getRootCollection()

Return the root XNodeCollection, null if not yet instantiated. This is a reliable indicator of the database being active.

This is not an XNode API method.

setDirty

public void setDirty()

Sets the dirty state of the collection to true.

isDirty

public boolean isDirty()

Returns the dirty state of the collection (true if any changes have occurred).

getParentCollection

public XNodeCollection getParentCollection()

Return the parent XNodeCollection of this XNodeCollection, or null if no parent XNodeCollection exists. For the root collection this returns null; for all others (in this single level implementation) this returns the root collection.

Specified by:

getParentCollection in interface XNodeCollection

Returns:

the parent XNodeCollection, or null if no parent exists.

Since:

XNode 1.2

setCollectionIndexDirty

public void setCollectionIndexDirty()

getCollectionIndex

public List getCollectionIndex()
                        throws XNodeException

Returns a List containing the IDs of child XNodeCollections, based on the internally-stored metadata. Non-root collections always return an empty List.

Note that this does not load the collection, only indicate its existence in the index.

Specified by:

getCollectionIndex in interface XNodeCollection

Returns:

a List containing the IDs of all child XNodeCollections.

Throws:

XNodeException - if an error occurs while indexing the root XNodeCollection.

Since:

XNode 1.2

hasCollection

public boolean hasCollection(String cid)

Returns true if a child XNodeCollection with ID cid exists as a child XNodeCollection of this XNodeCollection, false otherwise.

IMPORTANT: This is an indication of the existence of the XNodeCollection in the root collection cache, not simply its ID occurring in the index (which is the answer returned from getCollectionIndex().

This method always returns false for all non-root XNodeCollections.

Specified by:

hasCollection in interface XNodeCollection

Parameters:

cid - the ID of the child XNodeCollection.

Returns:

true if the child XNodeCollection exists.

Since:

XNode 1.2

getCollection

public XNodeCollection getCollection(String cid)
                              throws XNodeException

Return the child XNodeCollection with ID cid of this XNodeCollection, or null if unavailable. Always returns null in this implementation for all non-root XNodeCollections.

Specified by:

getCollection in interface XNodeCollection

Parameters:

cid - the ID of the child XNodeCollection.

Returns:

the child XNodeCollection, or null if unavailable.

Throws:

XNodeException - if an error occurs while getting the XNodeCollection.

Since:

XNode 1.2

addCollection

public boolean addCollection(XNodeCollection collection)
                      throws XNodeException

Add a child XNodeCollection collection to this XNodeCollection. When called for non-root collections, this throws an XNodeException, since only the root collection can contain subcollections.

Specified by:

addCollection in interface XNodeCollection

Parameters:

collection - the XNodeCollection to be added.

Returns:

true if the XNodeCollection was added.

Throws:

XNodeException - if an error occurs while adding the XNodeCollection.

Since:

XNode 1.2

removeCollection

public boolean removeCollection(String cid)
                         throws XNodeException

Remove a child XNodeCollection with ID cid from this XNodeCollection. This does not remove the associated backing Database, just returns true if the XNodeCollection is successfully removed from the index and the cache.

Specified by:

removeCollection in interface XNodeCollection

Parameters:

cid - the ID of the XNodeCollection to be removed.

Returns:

true if the XNodeCollection was removed.

Throws:

XNodeException - if an error occurs during removal of the XNodeCollection.

Since:

XNode 1.2

close

public boolean close()
              throws XNodeException

Close this XNodeCollection's database. Once done, access to the Database content is unavailable.

Specified by:

close in interface XNodeCollection

Returns:

true if the XNodeCollection was closed. This also returns true if it has already been closed.

Throws:

XNodeException - if an error occurs during closing of the Database.

Since:

XNode 1.2

printCollections

public void printCollections()

Prints the collections currently found in the cache to System.err. TEMP: A temporary test method.

setIndex

protected void setIndex(List list)

Forceably sets the node index to the contents of the provided List. If the node index is supplied as the parameter, only updates the DOM.

This is not an XNode API method.

getIndex

public List getIndex()
              throws XNodeException

Returns a List containing this XNodeCollection's index of XNode IDs. For the root collection this always returns an empty List.

Specified by:

getIndex in interface XNodeCollection

Returns:

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

Throws:

XNodeException - if an error occurs obtaining the index.

Since:

XNode 1.2

getIndexCount

public int getIndexCount()

Returns the number of XNodes in this XNodeCollection. For the root collection, returns the number of XNodeCollections in this XNodeCollection.

Specified by:

getIndexCount in interface XNodeCollection

Returns:

the number of XNodes or XNodeCollections in the index.

Throws:

XNodeException - if an error occurs obtaining the index.

Since:

XNode 1.2

getCollectionElement

protected Element getCollectionElement()
                                throws XNodeException

Return this Collection's <xnode:Collection> Element. This is a convenience method.

Throws:

XNodeException - if there is no collection element.

addXNode

public boolean addXNode(XNode xnode,
                        boolean overwrite)
                 throws XNodeException

Writes the XNode xnode to this XNodeCollection. If an XNode with the same ID already exists, this will overwrite it if overwrite is true, otherwise an XNodeException will be thrown. For the root collection this is a noop and always returns false.

Specified by:

addXNode in interface XNodeCollection

Parameters:

xnode - the XNode to add to the XNodeCollection.

Returns:

true if the XNode was added.

Throws:

XNodeException - if the XNode could not be written, or if a matching XNode ID exists and overwrite is false.

Since:

XNode 1.2

hasXNode

public boolean hasXNode(String nid)
                 throws XNodeException

Returns true if the XNode ID nid exists as a key in this XNodeCollection. This does not load the resource. For the root collection, this returns true only for the internal metadata XNode.

Specified by:

hasXNode in interface XNodeCollection

Parameters:

nid - the ID of the XNode to be queried.

Returns:

true the XNode exists in this XNodeCollection.

Throws:

XNodeException - if an error occurs during retrieval.

Since:

XNode 1.2

getXNode

public XNode getXNode(String nid)
               throws XNodeException

Retrieves the XNode with ID nid from this XNodeCollection, returning null if it does not exist. In the absence of the XNode, this will register an error with the messaging system but not throw an XNodeException unless an actual error occurs while retrieving or recreating an existing XNode.

Specified by:

getXNode in interface XNodeCollection

Parameters:

nid - the ID of the XNode to be retrieved.

Returns:

the XNode.

Throws:

XNodeException - if an error occurs during retrieval.

Since:

XNode 1.2

removeXNode

public boolean removeXNode(String nid)
                    throws XNodeException

Removes the XNode whose ID is xnode from this XNodeCollection.

Specified by:

removeXNode in interface XNodeCollection

Parameters:

nid - the ID of the XNode to remove from the XNodeCollection.

Returns:

true if the XNode was removed.

Throws:

XNodeException - if the String is not a valid ID.

Since:

XNode 1.2

setContent

public void setContent(Node node)
                throws XNodeException

Sets the content of this XNodeCollection to the Node node (which can be a DOM Document or Element node), throwing an XNodeException if the content is already set.

Overrides:

setContent in class XNodeImpl

Parameters:

node - the Node to set as the content of this XNode.

Throws:

XNodeException - if there is existing content.

toString

public String toString()

Return a String representation of this XNodeCollection. This is generally just a list of the Collection's XNode IDs as a whitespace-delimited String.

Specified by:

toString in interface XNodeCollection

Overrides:

toString in class XNodeImpl

Returns:

a String representation of this XNodeCollection.

Since:

XNode 1.2

compareTo

public int compareTo(Object o)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object. The parameter is expected to be another XNodeCollection, otherwise a ClassCastException is thrown.

Specified by:

compareTo in interface Comparable