org.purl.xnode
Interface XNodeCollection

All Known Implementing Classes:

XNodeCollectionImpl

public interface XNodeCollection

XNodeCollection is a simple interface for a collection of XNodes, with methods also supporting a hierarchy of XNodeCollections.

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.

It shares an isomorphism with most of the XNode API methods, since this is generally meant to be implemented as a class that extends the XNode API, using the XNode to store the collection-level metadata, as XNodeCollection then becomes a registry API. The methods classed as "XNode methods" are meant to return the values of their like-named XNode methods.

Since:

XNode 1.2

Version:

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

Author:

Murray Altheim

Field Summary

static String

ROOT_ID The String constant used as the ID/name of the root Collection.

Method Summary

boolean	addCollection(XNodeCollection collection) Add a child XNodeCollection collection to this XNodeCollection.
boolean	addXNode(XNode xnode, boolean overwrite) Adds the XNode xnode to this XNodeCollection.
boolean	close() Close the underlying database containing this XNodeCollection's data.
XNodeCollection	getCollection(String cid) Return a child XNodeCollection of this XNodeCollection, or null if unavailable.
List	getCollectionIndex() Returns a List containing the IDs of child XNodeCollections.
Node	getContent() Return a DOM Node containing this XNodeCollection's embedded content (exclusive of the XNode envelope), null if not set.
String	getCreated() Return the creation date of this XNodeCollection as a String.
String	getID() Return the ID of this XNodeCollection as a String.
List	getIndex() Returns a List containing this XNodeCollection's index of XNode IDs.
int	getIndexCount() Returns the number of XNodes in this XNodeCollection.
String	getModified() Return the modification date of this XNode as a String.
XNodeCollection	getParentCollection() Return the parent XNodeCollection of this XNodeCollection, or null if no parent XNodeCollection exists.
Set	getProperties() Return a Set containing all named properties of this XNodeCollection, null if none have been set.
Object	getProperty(String name) Return the named property name as an Object, null if it has not been set.
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	removeCollection(String cid) Remove a child XNodeCollection with ID cid from this XNodeCollection.
boolean	removeXNode(String nid) Removes the XNode with ID nid from this XNodeCollection.
void	setCreated(String timestamp) Set the creation date of this XNodeCollection to the String timestamp.
void	setID(String cid) Set the ID of this XNodeCollection to the String cid.
void	setModified(String timestamp) Set the modification date of this XNodeCollection to the String timestamp.
void	setProperty(String name, Object value) Set the named property name to the Object value.
String	toString() Return a String representation of this XNodeCollection.

Field Detail

ROOT_ID

static final String ROOT_ID

The String constant used as the ID/name of the root Collection. The value is "db".

See Also:

Constant Field Values

Method Detail

setID

void setID(String cid)
           throws XNodeException

Set the ID of this XNodeCollection to the String cid. XNodeCollection implementations should throw an XNodeException if the ID is already set or if the value is not a valid XML Name.

Parameters:

cid - the XNodeCollection ID.

Throws:

XNodeException - if already set, or is not an XML Name.

Since:

XNode 1.0

getID

String getID()

Return the ID of this XNodeCollection as a String.

Returns:

the XNode ID.

Since:

XNode 1.0

setCreated

void setCreated(String timestamp)
                throws XNodeException

Set the creation date of this XNodeCollection to the String timestamp.

Parameters:

timestamp - the creation timestamp as a String.

Throws:

XNodeException - if already set.

Since:

XNode 1.0

getCreated

String getCreated()

Return the creation date of this XNodeCollection as a String.

Returns:

the creation date as a String.

Since:

XNode 1.0

setModified

void setModified(String timestamp)
                 throws XNodeException

Set the modification date of this XNodeCollection to the String timestamp.

Parameters:

timestamp - the modification timestamp as a String.

Throws:

XNodeException - if an error occurs (such as the timestamp being in an unrecognizable format).

Since:

XNode 1.0

getModified

String getModified()

Return the modification date of this XNode as a String.

See Note.

Returns:

the modification date as a String, null if not set.

Since:

XNode 1.0

setProperty

void setProperty(String name,
                 Object value)
                 throws XNodeException,
                        NullPointerException

Set the named property name to the Object value. If the property has already been set, its value is replaced. If the property has been set and the provided value is null, the named property is removed.

The provided value must be a String or a DOM Node, otherwise an XNodeException is thrown.

Parameters:

name - the property name.

value - the property value, a String or DOM Node.

Throws:

XNodeException - if the property value is invalid.

NullPointerException - if either name or value parameter is null.

Since:

XNode 1.1

getProperty

Object getProperty(String name)
                   throws NullPointerException

Return the named property name as an Object, null if it has not been set. The returned value will be either a String or DOM Node.

Modified from XNode 1.0

Parameters:

name - the property name.

Returns:

the property value, null if not set.

Throws:

NullPointerException - if the name parameter is null.

Since:

XNode 1.1

getProperties

Set getProperties()

Return a Set containing all named properties of this XNodeCollection, null if none have been set.

Returns:

the Set of named properties (as Strings).

Since:

XNode 1.1

getContent

Node getContent()
                throws XNodeException

Return a DOM Node containing this XNodeCollection's embedded content (exclusive of the XNode envelope), null if not set. This will be an <xnode;Collection> Element containing child <xnode;Collection> Elements for each subcollection.

Returns:

the DOM Node containing this XNode's content.

Throws:

XNodeException

Since:

XNode 1.0

getCollectionIndex

List getCollectionIndex()
                        throws XNodeException

Returns a List containing the IDs of child XNodeCollections. If no child collections exist, an empty List is returned.

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

getParentCollection

XNodeCollection getParentCollection()

Return the parent XNodeCollection of this XNodeCollection, or null if no parent XNodeCollection exists.

Returns:

the parent XNodeCollection, or null if no parent exists.

Since:

XNode 1.2

hasCollection

boolean hasCollection(String cid)

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

Parameters:

cid - the ID of the child XNodeCollection.

Returns:

true if the child XNodeCollection exists.

Since:

XNode 1.2

getCollection

XNodeCollection getCollection(String cid)
                              throws XNodeException

Return a child XNodeCollection of this XNodeCollection, or null if unavailable.

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

boolean addCollection(XNodeCollection collection)
                      throws XNodeException

Add a child XNodeCollection collection to this 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

boolean removeCollection(String cid)
                         throws XNodeException

Remove a child XNodeCollection with ID cid from this 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

getIndex

List getIndex()
              throws XNodeException

Returns a List containing this XNodeCollection's index of XNode IDs. Returns an empty List rather than null.

Returns:

a List containing the index of XNode IDs of this XNodeCollection.

Throws:

XNodeException - if an error occurs obtaining the index.

Since:

XNode 1.2

getIndexCount

int getIndexCount()
                  throws XNodeException

Returns the number of XNodes in this XNodeCollection. If this is the root XNodeCollection, returns the count of child XNodeCollections.

Returns:

the number of XNodes or XNodeCollections in the index.

Throws:

XNodeException - if an error occurs obtaining the index.

Since:

XNode 1.2

addXNode

boolean addXNode(XNode xnode,
                 boolean overwrite)
                 throws XNodeException

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

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

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.

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

XNode getXNode(String nid)
               throws XNodeException

Retrieves the XNode with ID nid from this XNodeCollection, returning null if it does not exist.

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

boolean removeXNode(String nid)
                    throws XNodeException

Removes the XNode with ID nid from this 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

close

boolean close()
              throws XNodeException

Close the underlying database containing this XNodeCollection's data. This method should always be called prior to closing the collection. Though opening and closing databases may not be necessary in some implementations, in order to remain independent of implementation this method should be called even if it does nothing.

Returns:

true if the database was successfully closed, or is already closed.

Throws:

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

Since:

XNode 1.2

toString

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.

Overrides:

toString in class Object

Returns:

a String representation of this XNodeCollection.

Since:

XNode 1.2