net.jinx.db
Class DefaultHierarchy

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

All Implemented Interfaces:

java.io.Serializable

public class DefaultHierarchy
extends Hierarchy

Hierarchy implementation based on a pair of Hierarchy objects. The first of the two is checked for attributes and then failing that, the second is checked, using it as a source of default values. Calling methods that modify the Hierarchy modify the first, but not the second.

API Stability: Alpha.

See Also:

Serialized Form

Constructor Summary

DefaultHierarchy(Hierarchy main, Hierarchy defaults)
Constructs a new DefaultHierarchy.

Method Summary

void	addListener(HierarchyListener listener) Allows a HierarchyListener to receive events from this specific Hierarchy, but not any of it's children.
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.
void	clearAttributes() Clears all attributes from this Hierarchy.
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.
Hierarchy	createNode(java.lang.String name) Creates a new node with the given name.
void	deleteNode(java.lang.String name) Removes the node with the given name.
protected java.lang.Object	getAttributeObject(java.lang.String name) Gets the attribute's value Object.
protected Hierarchy	getDefaults()
protected Hierarchy	getMain()
Hierarchy	getNode(java.lang.String name) Provides the Hierarchy for the given node name.
boolean	hasAttribute(java.lang.String name)
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.
java.lang.Object	removeAttribute(java.lang.String name) Remove the value for the given attribute name, returning the previous value.
void	rollback() Discards all changes since the most recent call to commit().
protected 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 net.jinx.db.Hierarchy

getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, propertyChanged, removeListener, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultHierarchy

public DefaultHierarchy(Hierarchy main,
                        Hierarchy defaults)

Constructs a new DefaultHierarchy.

Parameters:

main - the Hierarchy that is checked for values first.

defaults - the Hierarchy that is checked if main doesn't have a given value.

Method Detail

getDefaults

protected Hierarchy getDefaults()

getMain

protected Hierarchy getMain()

attributes

public java.util.Iterator attributes()

Description copied from class: Hierarchy

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.

Specified by:

attributes in class Hierarchy

Returns:

a java.util.Iterator.

clearAttributes

public void clearAttributes()

Description copied from class: Hierarchy

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

Specified by:

clearAttributes in class Hierarchy

clearNodes

public void clearNodes()

Description copied from class: Hierarchy

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.

Specified by:

clearNodes in class Hierarchy

createNode

public Hierarchy createNode(java.lang.String name)

Description copied from class: Hierarchy

Creates a new node with the given name.

Specified by:

createNode in class Hierarchy

Parameters:

name - the name of the node.

Returns:

the new node's Hierarchy object.

deleteNode

public void deleteNode(java.lang.String name)

Description copied from class: Hierarchy

Removes the node with the given name.

Specified by:

deleteNode in class Hierarchy

Parameters:

name - the name of the node.

getAttributeObject

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

Description copied from class: Hierarchy

Gets the attribute's value Object.

Specified by:

getAttributeObject in class Hierarchy

Parameters:

name - the name of the attribute to access.

Returns:

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

getNode

public Hierarchy getNode(java.lang.String name)

Description copied from class: Hierarchy

Provides the Hierarchy for the given node name.

Specified by:

getNode in class Hierarchy

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.

hasAttribute

public boolean hasAttribute(java.lang.String name)

Specified by:

hasAttribute in class Hierarchy

Returns:

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

nodes

public java.util.Iterator nodes()

Description copied from class: Hierarchy

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.

Specified by:

nodes in class Hierarchy

Returns:

a java.util.Iterator.

removeAttribute

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

Description copied from class: Hierarchy

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

Specified by:

removeAttribute in class Hierarchy

Parameters:

name - the name of the attribute to access.

Returns:

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

setAttributeObject

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

Description copied from class: Hierarchy

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

Specified by:

setAttributeObject in class Hierarchy

Parameters:

name - the name of the attribute to access.

Returns:

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

addListener

public void addListener(HierarchyListener listener)

Description copied from class: Hierarchy

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

Overrides:

addListener in class Hierarchy

Parameters:

listener - the HierarchyListener to add.

clear

public void clear()

Description copied from class: Hierarchy

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

Overrides:

clear in class Hierarchy

close

public void close()

Description copied from class: Hierarchy

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.

Overrides:

close in class Hierarchy

commit

public void commit()

Description copied from class: Hierarchy

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.

Overrides:

commit in class Hierarchy

copyTo

public void copyTo(Hierarchy h)

Description copied from class: Hierarchy

Recursively copies this Hierarchy object's contents into another.

Overrides:

copyTo in class Hierarchy

Parameters:

h - the Hierarchy to copy to.

parseFromProperties

public void parseFromProperties(java.util.Properties prop)

Description copied from class: Hierarchy

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

Overrides:

parseFromProperties in class Hierarchy

Parameters:

prop - the Properties object.

parseFromXML

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

Description copied from class: Hierarchy

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.

Overrides:

parseFromXML in class Hierarchy

Parameters:

in - the InputStream to read from.

Throws:

java.io.IOException

org.xml.sax.SAXException

javax.xml.parsers.ParserConfigurationException

rollback

public void rollback()

Description copied from class: Hierarchy

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

Overrides:

rollback in class Hierarchy

storeToProperties

public void storeToProperties(java.util.Properties prop)

Description copied from class: Hierarchy

Stores this Hierarchy tree in a Properties Object.

Overrides:

storeToProperties in class Hierarchy

Parameters:

prop - the Properties object.

storeToXML

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

Description copied from class: Hierarchy

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

Overrides:

storeToXML in class Hierarchy

Parameters:

o - the OutputStream to write to.

Throws:

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