net.jinx.db
Class Hierarchy

java.lang.Object
  net.jinx.db.Hierarchy

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

DefaultHierarchy, ImmutableHierarchy, SimpleHierarchy, SynchronizedHierarchy

public abstract class Hierarchy
extends java.lang.Object
implements java.io.Serializable

Hierarchy implementations store data in a hierarchical form, based on nodes and attributes. Each node is also a Hierachy object. Any Hierarchy can store attributes; String keys attached to values. These values can be of many different types ranging from primitives to Strings. Sub-nodes and attributes with the same name can coexist inside the same node.
There are methods in this class for storing attributes as primitive types and arrays of them, as well as a few handy odds and ends like java.math.BigDecimal Objects.

API Stability: Stable.

See Also:

Serialized Form

Constructor Summary

protected

Hierarchy() Constructs a new Hierarchy.

Method Summary

void	addListener(HierarchyListener listener) Allows a HierarchyListener to receive events from this specific Hierarchy, but not any of it's children.
abstract java.util.Iterator	attributes() Provides an Iterator for the attributes that are stored in this Hierarchy, but not any of it's sub-nodes.
void	clear() Clears all attributes and sub-nodes from this Hierarchy.
abstract void	clearAttributes() Clears all attributes from this Hierarchy.
abstract void	clearNodes() Clears all sub-nodes from this hierarchy.
void	close() Closes the Hierarchy.
void	commit() Completes the current transaction.
void	copyTo(Hierarchy h) Recursively copies this Hierarchy object's contents into another.
abstract Hierarchy	createNode(java.lang.String name) Creates a new node with the given name.
abstract void	deleteNode(java.lang.String name) Removes the node with the given name.
java.lang.String	getAttribute(java.lang.String name) Gets the value for the given attribute name, returning null if the attribute does not exist.
java.math.BigDecimal	getAttribute(java.lang.String name, java.math.BigDecimal defaultValue)
java.math.BigDecimal[]	getAttribute(java.lang.String name, java.math.BigDecimal[] defaultValue)
java.math.BigInteger	getAttribute(java.lang.String name, java.math.BigInteger defaultValue)
java.math.BigInteger[]	getAttribute(java.lang.String name, java.math.BigInteger[] defaultValue)
boolean	getAttribute(java.lang.String attribute, boolean defaultValue) Gets the value of an attribute as a boolean.
boolean[]	getAttribute(java.lang.String attribute, boolean[] defaultValue) Gets the value of an attribute as a boolean array.
byte	getAttribute(java.lang.String attribute, byte defaultValue) Provides the means to get an attribute as a byte value.
byte[]	getAttribute(java.lang.String attribute, byte[] defaultValue)
char	getAttribute(java.lang.String name, char defaultValue)
char[]	getAttribute(java.lang.String name, char[] defaultValue)
double	getAttribute(java.lang.String attribute, double defaultValue) Provides the means to get an attribute as a double value.
double[]	getAttribute(java.lang.String attribute, double[] defaultValue)
float	getAttribute(java.lang.String attribute, float defaultValue) Provides the means to get an attribute as a float value.
float[]	getAttribute(java.lang.String attribute, float[] defaultValue)
int	getAttribute(java.lang.String attribute, int defaultValue) Provides the means to get an attribute as an int value.
int[]	getAttribute(java.lang.String attribute, int[] defaultValue)
double[]	getAttribute(java.lang.String attribute, int len, double[] defaultValue)
float[]	getAttribute(java.lang.String attribute, int len, float[] defaultValue)
long	getAttribute(java.lang.String attribute, long defaultValue) Provides the means to get an attribute as a long value.
long[]	getAttribute(java.lang.String attribute, long[] defaultValue)
short	getAttribute(java.lang.String attribute, short defaultValue) Provides the means to get an attribute as a short value.
short[]	getAttribute(java.lang.String attribute, short[] defaultValue)
java.lang.String	getAttribute(java.lang.String name, java.lang.String defaultValue) Gets the value for the given attribute name, returning defaultValue if the attribute does not exist.
java.net.URL	getAttribute(java.lang.String name, java.net.URL defaultValue) Parses a URL from an attribute.
protected abstract java.lang.Object	getAttributeObject(java.lang.String name) Gets the attribute's value Object.
abstract Hierarchy	getNode(java.lang.String name) Provides the Hierarchy for the given node name.
abstract boolean	hasAttribute(java.lang.String name)
abstract java.util.Iterator	nodes() Provides an Iterator for the sub-nodes that are direct sub-nodes of this Hierarchy.
void	parseFromProperties(java.util.Properties prop) Sets attributes in this Hierarchy according to a Properties Object.
void	parseFromXML(java.io.InputStream in) Reads attributes and nodes for the Hierarchy from the given InputStream.
protected void	propertyChanged(java.lang.String name, int ec) Should be called when an attribute or node directly in this Hierarchy has changed in some manner.
abstract java.lang.Object	removeAttribute(java.lang.String name) Remove the value for the given attribute name, returning the previous value.
void	removeListener(HierarchyListener listener) Removes a HierarchyListener from this Hiereachy.
void	rollback() Discards all changes since the most recent call to commit().
void	setAttribute(java.lang.String name, java.math.BigDecimal val)
void	setAttribute(java.lang.String name, java.math.BigDecimal[] values)
void	setAttribute(java.lang.String name, java.math.BigInteger val)
void	setAttribute(java.lang.String name, java.math.BigInteger[] values)
void	setAttribute(java.lang.String attribute, boolean value) Sets an attribute.
void	setAttribute(java.lang.String attribute, boolean[] values) Sets an attribute.
void	setAttribute(java.lang.String attribute, byte value)
void	setAttribute(java.lang.String attribute, byte[] values)
void	setAttribute(java.lang.String name, char value)
void	setAttribute(java.lang.String name, char[] value)
void	setAttribute(java.lang.String attribute, double value)
void	setAttribute(java.lang.String attribute, double[] values)
void	setAttribute(java.lang.String attribute, float value)
void	setAttribute(java.lang.String attribute, float[] values)
void	setAttribute(java.lang.String attribute, int value)
void	setAttribute(java.lang.String attribute, int[] values)
void	setAttribute(java.lang.String attribute, long value)
void	setAttribute(java.lang.String attribute, long[] values)
void	setAttribute(java.lang.String attribute, short value)
void	setAttribute(java.lang.String attribute, short[] values)
java.lang.String	setAttribute(java.lang.String name, java.lang.String obj) Sets the value for the given attribute name, returning the previous value.
void	setAttribute(java.lang.String name, java.net.URL val) Sets the value of an attribute based on the String version of a URL object.
protected abstract java.lang.Object	setAttributeObject(java.lang.String name, java.lang.Object obj) Sets an attribute's value Object.
void	storeToProperties(java.util.Properties prop) Stores this Hierarchy tree in a Properties Object.
void	storeToXML(java.io.OutputStream o) Stores the Hierarchy tree to the given java.io.OutputStream as XML.

Methods inherited from class java.lang.Object

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

Constructor Detail

Hierarchy

protected Hierarchy()

Constructs a new Hierarchy.

Method Detail

close

public void close()

Closes the Hierarchy. This should only function for the root Hierarchy Object, not any of it's sub-nodes. This is used for clean-up operations, such as closing the persistent backing store. This implies a call to commit().
The default implementation does nothing.

commit

public void commit()

Completes the current transaction. This is for crash recovery, so the database will always be in a consistent state. If the system crashes, the next time a Hierarchy is created with the same configuration (implementation specific), it will rollback to the state it was in the last time this was called.
For example, commit() is called. All data is consistent. The program starts putting data in the Hierarchy, but does not complete the current batch of operations, due to a crash. The program is started again, and it sees that commit was not called, so all changes made since the most recent call to commit() are discarded.
NOTE: This method should only function for the base hierarchy, not any of the sub-nodes.

rollback

public void rollback()

Discards all changes since the most recent call to commit().

storeToProperties

public void storeToProperties(java.util.Properties prop)

Stores this Hierarchy tree in a Properties Object.

Parameters:

prop - the Properties object.

parseFromProperties

public void parseFromProperties(java.util.Properties prop)

Sets attributes in this Hierarchy according to a Properties Object. Any attribute in prop that contains "/" will affect sub-nodes of this Hierarchy.

Parameters:

prop - the Properties object.

copyTo

public void copyTo(Hierarchy h)

Recursively copies this Hierarchy object's contents into another.

Parameters:

h - the Hierarchy to copy to.

parseFromXML

public void parseFromXML(java.io.InputStream in)
                  throws java.io.IOException,
                         org.xml.sax.SAXException,
                         javax.xml.parsers.ParserConfigurationException

Reads attributes and nodes for the Hierarchy from the given InputStream. The stream is assumed to be attached to an XML file describing a Hierarchy. If an exception is thrown, the Hierachy may be left in an inconsistent state, so a rollback might be needed. The stream is not closed by this method.

Parameters:

in - the InputStream to read from.

Throws:

java.io.IOException

org.xml.sax.SAXException

javax.xml.parsers.ParserConfigurationException

storeToXML

public void storeToXML(java.io.OutputStream o)
                throws java.io.IOException

Stores the Hierarchy tree to the given java.io.OutputStream as XML.

Parameters:

o - the OutputStream to write to.

Throws:

java.io.IOException - if an I/O error occurs.

clear

public void clear()

Clears all attributes and sub-nodes from this Hierarchy. The default implementation calls clearAttributes() and clearNodes().

clearAttributes

public abstract void clearAttributes()

Clears all attributes from this Hierarchy. Does not affect any of the sub-nodes.

clearNodes

public abstract void clearNodes()

Clears all sub-nodes from this hierarchy. Depending on the implementation, this may take quite some time to complete, as it will most likely have to recursively delete all the sub-nodes and their attributes from the backing store.

attributes

public abstract java.util.Iterator attributes()

Provides an Iterator for the attributes that are stored in this Hierarchy, but not any of it's sub-nodes. The remove() method, while it may be functional, should NEVER be used. It is not guaranteed to function properly. For example, JDBMHierarchy's Iterator has a remove() method that will seem to function, but will in fact only work on the in-memory copy of the java.util.HashMap that backs it's Iterator.

To put it more plainly, the Iterator returned from this method is for informational purposes only! If multiple threads manipulate the Hierarchy concurrently (something that is not part of this design), then the Iterator's results could be wrong.

Returns:

a java.util.Iterator.

nodes

public abstract java.util.Iterator nodes()

Provides an Iterator for the sub-nodes that are direct sub-nodes of this Hierarchy. The remove() method, while it may be functional, should NEVER be used. It is not guaranteed to function properly. For example, JDBMHierarchy's Iterator has a remove() method that will seem to function, but will in fact only work on the in-memory copy of the java.util.HashMap that backs it's Iterator.

To put it more plainly, the Iterator returned from this method is for informational purposes only! If multiple threads manipulate the Hierarchy concurrently (something that is not part of this design), then the Iterator's results could be wrong.

Returns:

a java.util.Iterator.

getAttribute

public char getAttribute(java.lang.String name,
                         char defaultValue)

setAttribute

public void setAttribute(java.lang.String name,
                         char value)

getAttribute

public char[] getAttribute(java.lang.String name,
                           char[] defaultValue)

setAttribute

public void setAttribute(java.lang.String name,
                         char[] value)

getAttribute

public java.net.URL getAttribute(java.lang.String name,
                                 java.net.URL defaultValue)

Parses a URL from an attribute. If anything goes wrong (malformed url or missing attribute), then defaultValue is returned.

Parameters:

name - the name of the attribute to parse the URL from.

defaultValue - the default to use in case of error.

Returns:

the URL.

setAttribute

public void setAttribute(java.lang.String name,
                         java.net.URL val)

Sets the value of an attribute based on the String version of a URL object.

Parameters:

name - the name of the attribute to set.

val - the URL to store as a String.

getAttribute

public java.lang.String getAttribute(java.lang.String name,
                                     java.lang.String defaultValue)

Gets the value for the given attribute name, returning defaultValue if the attribute does not exist. The default implementation uses getAttribute(String).

Parameters:

name - the name of the attribute to access.

defaultValue - the default value to return if the attribute doesn't exist.

Returns:

the attribute's value or the default value.

getAttribute

public java.lang.String getAttribute(java.lang.String name)

Gets the value for the given attribute name, returning null if the attribute does not exist.

Parameters:

name - the name of the attribute to access.

Returns:

the attribute's value or null if it doesn't exist.

setAttribute

public java.lang.String setAttribute(java.lang.String name,
                                     java.lang.String obj)

Sets the value for the given attribute name, returning the previous value.

Parameters:

name - the name of the attribute to access.

Returns:

the attribute's previous value or null if it didn't exist.

getAttributeObject

protected abstract java.lang.Object getAttributeObject(java.lang.String name)

Gets the attribute's value Object.

Parameters:

name - the name of the attribute to access.

Returns:

the value object, or null if the attribute didn't exist.

setAttributeObject

protected abstract java.lang.Object setAttributeObject(java.lang.String name,
                                                       java.lang.Object obj)

Sets an attribute's value Object. This should not be used to store any type of Object. It should only be used by the methods in this class to store Strings and Objects that wrap primitives (Boolean, Byte, Short, Int, Long, Float, Double, etc.).

Parameters:

name - the name of the attribute to access.

Returns:

the previous value object, or null if the attribute didn't exist.

removeAttribute

public abstract java.lang.Object removeAttribute(java.lang.String name)

Remove the value for the given attribute name, returning the previous value.

Parameters:

name - the name of the attribute to access.

Returns:

the attribute's previous value or null if it didn't exist.

hasAttribute

public abstract boolean hasAttribute(java.lang.String name)

Returns:

true if and only if there is an attribute for the given name.

deleteNode

public abstract void deleteNode(java.lang.String name)

Removes the node with the given name.

Parameters:

name - the name of the node.

createNode

public abstract Hierarchy createNode(java.lang.String name)

Creates a new node with the given name.

Parameters:

name - the name of the node.

Returns:

the new node's Hierarchy object.

getNode

public abstract Hierarchy getNode(java.lang.String name)

Provides the Hierarchy for the given node name.

Parameters:

name - the name of the node to access.

Returns:

the Hierarchy object for the node. This will be null if it doesn't exist.

propertyChanged

protected void propertyChanged(java.lang.String name,
                               int ec)

Should be called when an attribute or node directly in this Hierarchy has changed in some manner.

Parameters:

name - the name of the attribute that changed.

ec - the event constant from HierarchyEvent for what occured.

addListener

public void addListener(HierarchyListener listener)

Allows a HierarchyListener to receive events from this specific Hierarchy, but not any of it's children.

Parameters:

listener - the HierarchyListener to add.

removeListener

public void removeListener(HierarchyListener listener)

Removes a HierarchyListener from this Hiereachy.

Parameters:

listener - the HierarchyListener to add.

setAttribute

public void setAttribute(java.lang.String attribute,
                         boolean[] values)

Sets an attribute.

Parameters:

attribute - the name of the attribute.

values - the value as a boolean array.

getAttribute

public boolean[] getAttribute(java.lang.String attribute,
                              boolean[] defaultValue)

Gets the value of an attribute as a boolean array.

Parameters:

attribute - the name of the attribute.

defaultValue - the default value to return on a failure.

Returns:

the value for the attribute, or the default value if it hasn't been set.

setAttribute

public void setAttribute(java.lang.String attribute,
                         boolean value)

Sets an attribute.

Parameters:

attribute - the name of the attribute.

value - the value as a boolean.

getAttribute

public boolean getAttribute(java.lang.String attribute,
                            boolean defaultValue)

Gets the value of an attribute as a boolean.

Parameters:

attribute - the name of the attribute.

defaultValue - the default value to return on a failure.

Returns:

the value for the attribute, or the default value if it hasn't been set.

setAttribute

public void setAttribute(java.lang.String attribute,
                         float[] values)

getAttribute

public float[] getAttribute(java.lang.String attribute,
                            int len,
                            float[] defaultValue)

getAttribute

public float[] getAttribute(java.lang.String attribute,
                            float[] defaultValue)

setAttribute

public void setAttribute(java.lang.String attribute,
                         float value)

getAttribute

public float getAttribute(java.lang.String attribute,
                          float defaultValue)

Provides the means to get an attribute as a float value.

Parameters:

attribute - the name of the attribute to retrieve.

defaultValue - the value to return if the attribute doesn't exist.

setAttribute

public void setAttribute(java.lang.String attribute,
                         double[] values)

getAttribute

public double[] getAttribute(java.lang.String attribute,
                             int len,
                             double[] defaultValue)

getAttribute

public double[] getAttribute(java.lang.String attribute,
                             double[] defaultValue)

setAttribute

public void setAttribute(java.lang.String attribute,
                         double value)

getAttribute

public double getAttribute(java.lang.String attribute,
                           double defaultValue)

Provides the means to get an attribute as a double value.

Parameters:

attribute - the name of the attribute to retrieve.

defaultValue - the value to return if the attribute doesn't exist.

setAttribute

public void setAttribute(java.lang.String attribute,
                         long[] values)

getAttribute

public long[] getAttribute(java.lang.String attribute,
                           long[] defaultValue)

setAttribute

public void setAttribute(java.lang.String attribute,
                         long value)

getAttribute

public long getAttribute(java.lang.String attribute,
                         long defaultValue)

Provides the means to get an attribute as a long value.

Parameters:

attribute - the name of the attribute to retrieve.

defaultValue - the value to return if the attribute doesn't exist.

setAttribute

public void setAttribute(java.lang.String attribute,
                         int[] values)

getAttribute

public int[] getAttribute(java.lang.String attribute,
                          int[] defaultValue)

setAttribute

public void setAttribute(java.lang.String attribute,
                         int value)

getAttribute

public int getAttribute(java.lang.String attribute,
                        int defaultValue)

Provides the means to get an attribute as an int value.

Parameters:

attribute - the name of the attribute to retrieve.

defaultValue - the value to return if the attribute doesn't exist.

setAttribute

public void setAttribute(java.lang.String attribute,
                         short[] values)

getAttribute

public short[] getAttribute(java.lang.String attribute,
                            short[] defaultValue)

setAttribute

public void setAttribute(java.lang.String attribute,
                         short value)

getAttribute

public short getAttribute(java.lang.String attribute,
                          short defaultValue)

Provides the means to get an attribute as a short value.

Parameters:

attribute - the name of the attribute to retrieve.

defaultValue - the value to return if the attribute doesn't exist.

setAttribute

public void setAttribute(java.lang.String attribute,
                         byte[] values)

getAttribute

public byte[] getAttribute(java.lang.String attribute,
                           byte[] defaultValue)

setAttribute

public void setAttribute(java.lang.String attribute,
                         byte value)

getAttribute

public byte getAttribute(java.lang.String attribute,
                         byte defaultValue)

Provides the means to get an attribute as a byte value.

Parameters:

attribute - the name of the attribute to retrieve.

defaultValue - the value to return if the attribute doesn't exist.

getAttribute

public java.math.BigDecimal getAttribute(java.lang.String name,
                                         java.math.BigDecimal defaultValue)

getAttribute

public java.math.BigDecimal[] getAttribute(java.lang.String name,
                                           java.math.BigDecimal[] defaultValue)

setAttribute

public void setAttribute(java.lang.String name,
                         java.math.BigDecimal val)

setAttribute

public void setAttribute(java.lang.String name,
                         java.math.BigDecimal[] values)

getAttribute

public java.math.BigInteger getAttribute(java.lang.String name,
                                         java.math.BigInteger defaultValue)

getAttribute

public java.math.BigInteger[] getAttribute(java.lang.String name,
                                           java.math.BigInteger[] defaultValue)

setAttribute

public void setAttribute(java.lang.String name,
                         java.math.BigInteger val)

setAttribute

public void setAttribute(java.lang.String name,
                         java.math.BigInteger[] values)