com.partnersoft.cog
Class Cog

java.lang.Object
  com.partnersoft.cog.Cog

All Implemented Interfaces:

Identifiable, java.lang.Iterable<Cog>

public class Cog
extends java.lang.Object
implements java.lang.Iterable<Cog>, Identifiable

A Configurable Object Graph.

A Cog is a Configurable Object Graph, where the term "graph" is used in the mathematical structure sense of a network of connected nodes. The structure is that of a double-linked tree, where each Cog knows its single parent and one or more children. Branch nodes form stuctures or collections of subnodes.

Cogs have datatypes. The typing structure is separated from the data structure to allow e.g. loading an older version of a datatype and upgrading it by manipulating the contents. However, the typing structure allows rich description of the contents and how to read, edit, and report them.

While Cogs can be used to serialize Java objects, they are most useful as a runtime-configurable object-oriented data structure for describing user data, business objects, interface structures and other payloads.

The tree structure lends itself naturally to hierarchical traversal and storage in formats such as XML. It does not map as easily into relational structures like SQL, but it is possible by using the unique ID structure included.

Cogs are arranged in a tree structure. A twist on this structure is that the children may be accessed by name or ID as well as by order in the child list. The tree structure is double-linked so that you can traverse up or down with equal facility.

Be aware that Cogs are designed primarily for ease of use and flexibility, and not for size or time performance.

Copyright 2005-2009 Partner Software, Inc.

Version:

$Id: Cog.java 2474 2010-03-13 14:28:43Z paul $

Author:

Paul Reavis, Russell Cagle

Constructor Summary

Cog()
Creates an empty, unnamed, detached node with no type.

Cog(CogSchema schema, java.lang.String typeName)
Creates a root cog with the given schema and type name.

Cog(java.util.Collection contents)
Creates a cog node and adds the objects in the given collection to it via addAll().

Cog(java.util.Map contents)
Creates a cog node and adds the objects in the given map to it via putAll().

Cog(java.lang.String xmlString)
Creates a cog from the given XML string.

Cog(java.lang.String typeName, java.lang.String name)
Creates an empty node of the given type and name.

Cog(java.lang.String typeName, java.lang.String name, java.lang.Object data)
Creates an empty node with the given typeName, name, and data.

Method Summary

Cog	add(Cog newChild) Adds a node as a child.
Cog	add(java.lang.String childName) Creates and adds a blank child node.
Cog	add(java.lang.String typeName, java.lang.String childName) Creates and adds a new child.
Cog	add(java.lang.String typeName, java.lang.String childName, java.lang.Object data) Creates and adds a new child with data value.
void	addAll(java.util.Collection items) Adds all items in the given collection via addObject().
void	addObject(java.lang.Object object) Treating this cog as a list, adds the given object to the end.
Cog	childAt(int index) Returns the child at the given index.
Cog	childNamed(java.lang.String childName) Returns the first direct child with the given name.
Cog	childWithId(java.lang.String id) Returns the child with the given unique ID.
void	cleanStructure() Attempts to clean up the structure and type names of this cog using its type information.
Cog	copy() Creates a complete, deep copy of this Cog.
void	detachNode() Removes this cog and attaches its descendants to this cog's current parent.
Cog	detachNodeFor(Path path) Removes the given relative node using detachNode().
Cog	detachNodeFor(java.lang.String pathString) Removes the given relative node using detachNode().
void	detachTree() Removes this cog and its descendants from its parent.
Cog	detachTreeFor(Path path) Removes the given relative node using detachTree().
Cog	detachTreeFor(java.lang.String pathString) Removes the given relative node using detachTree().
boolean	equals(java.lang.Object nother)
void	fireChanged(java.lang.String what)
java.util.ArrayList	getArrayList(Path path)
java.util.ArrayList	getArrayList(java.lang.String path)
boolean	getBoolean(Path path)
boolean	getBoolean(java.lang.String path)
byte[]	getBytes(Path path)
byte[]	getBytes(java.lang.String path)
int	getChildCount() Returns the number of children.
Naming<java.lang.Object>	getChildData() Gets the child data as a Naming.
java.util.List<Cog>	getChildren() Returns an immutable list of children.
java.lang.Object	getData() Returns the payload data.
java.lang.Object	getData(Path path) Gets the data object from the node specified by the path.
java.lang.Object	getData(java.lang.String path) Same as getData(Path path) but automatically creates the Path object from the given string.
double	getDouble(Path path)
double	getDouble(java.lang.String path)
float	getFloat(Path path)
float	getFloat(java.lang.String path)
java.lang.String	getGuid() Globally-unique ID (GUID) for this object.
CogHeader	getHeader() Returns the CogHeader attached to the root.
int	getId() Numeric ID for this object.
int	getIndex() Returns the index location of this node in its parent's child list, or 0 if this is root.
int	getInt(Path path)
int	getInt(java.lang.String path)
java.util.List	getList(Path path)
java.util.List	getList(java.lang.String path)
long	getLong(Path path)
long	getLong(java.lang.String path)
java.lang.String	getName() Name of this object.
Naming	getNaming(Path path)
Naming	getNaming(java.lang.String path)
Cog	getNode(Path path) Gets the node specified by the path.
Cog	getNode(java.lang.String path) Same as getNode(Path path) but automatically creates the Path object from the given string.
java.lang.Object	getObject(Path path) Gets the object specified by the path.
java.lang.Object	getObject(java.lang.String path) Same as getObject(Path path) but automatically creates the Path object from the given string.
Cog	getOrCreateNodeFor(Path path) Gets a descendant of this node, according to the given path.
Cog	getParent() Returns the parent cog, or null if this is a root Cog.
Path	getPath() Returns the full path to this Cog from the root.
Cog	getRoot() Returns the root of the structure this cog is in.
CogSchema	getSchema() Returns the schema for this Cog structure.
short	getShort(Path path)
short	getShort(java.lang.String path)
java.lang.String	getString(Path path)
java.lang.String	getString(java.lang.String path)
java.lang.String	getStringButNullBlanks(Path path)
java.lang.String	getStringButNullBlanks(java.lang.String path)
CogType	getType() Returns the CogType corresponding to the type name in the schema.
java.lang.String	getTypeName()
boolean	isAncestorOf(Cog nother) Returns true if this node is an ancestor of the given node.
boolean	isDescendantOf(Cog nother) Returns true if this node is a descendant of the given node.
boolean	isLeaf() Returns true if this is a leaf node with no children.
boolean	isRoot() Returns true if this is the root of a Cog hierarchy.
java.util.Iterator<Cog>	iterator() Iterates through the children.
java.util.List<Cog>	listAncestors() Returns all ancestors of this node as a new list in order from parent to root.
java.util.List<Cog>	listChildren() Returns a freshly-allocated list of this node's children.
java.util.List<Cog>	listChildrenNamed(java.lang.String name) Returns a freshly-allocated list of the children with the given name.
java.util.List<Cog>	listDescendants() Returns all descendants of this node as a new list.
Cog	nodeFor(Path path) Gets a another node relative to this one, according to the given path.
Cog	nodeFor(java.lang.String pathString) Gets a another node relative to this one, according to the given path string.
void	putAll(java.util.Map map) Adds all items in the given map via putAll().
void	putArrayList(Path path, java.util.ArrayList value)
void	putArrayList(java.lang.String path, java.util.ArrayList value)
void	putBoolean(Path path, boolean value)
void	putBoolean(java.lang.String path, boolean value)
void	putBytes(Path path, byte[] value)
void	putBytes(java.lang.String path, byte[] value)
void	putData(Path path, java.lang.Object data) Places the given data object at a node specified by the given path.
void	putData(Path path, java.lang.String typeName, java.lang.Object data) Places the given data object at a node specified by the given path.
void	putData(java.lang.String path, java.lang.Object data) Same as putData(Path path, Object data) but automatically creates the Path object from the given string.
void	putData(java.lang.String path, java.lang.String typeName, java.lang.Object data) Same as putData(Path path, typeName, Object data) but automatically creates the Path object from the given string.
void	putDouble(Path path, double value)
void	putDouble(java.lang.String path, double value)
void	putFloat(Path path, float value)
void	putFloat(java.lang.String path, float value)
void	putInt(Path path, int value)
void	putInt(java.lang.String path, int value)
void	putList(Path path, java.util.List value)
void	putList(Path path, java.lang.String typeName, java.util.List value)
void	putList(java.lang.String path, java.util.List value)
void	putList(java.lang.String path, java.lang.String typeName, java.util.List value)
void	putLong(Path path, long value)
void	putLong(java.lang.String path, long value)
void	putNaming(Path path, Naming value)
void	putNaming(java.lang.String path, Naming value)
void	putNode(Path path, Cog node) Places the given node at the location specified by the given path.
void	putNode(java.lang.String path, Cog node) Same as putNode(Path path, Cog node) but automatically creates the Path object from the given string.
void	putObject(Path path, java.lang.Object object) Places the given object at the location specified by the given path.
void	putObject(java.lang.String path, java.lang.Object object) Same as putObject(Path path, Object object) but automatically creates the Path object from the given string.
void	putShort(Path path, short value)
void	putShort(java.lang.String path, short value)
void	putString(Path path, java.lang.String value)
void	putString(Path path, java.lang.String typeName, java.lang.String value)
void	putString(java.lang.String path, java.lang.String value)
void	putString(java.lang.String path, java.lang.String typeName, java.lang.String value)
Cog	renameChild(java.lang.String oldName, java.lang.String newName) Renames the given child node.
Cog	setChildAt(int index, Cog child) Sets the child at the given index.
void	setChildData(Naming<java.lang.Object> childData) Sets the child data using the given named values.
void	setData(java.lang.Object newData) Sets the payload data.
void	setGuid(java.lang.String newGuid)
void	setId(int newID)
void	setName(java.lang.String newName)
void	setParent(Cog newParent) Sets the parent cog.
void	setSchema(CogSchema newSchema) Sets the schema for this Cog structure.
void	setTypeName(java.lang.String newTypeName)
java.lang.String	toDetailedString() Gives a more detailed String representation of the entire Cog structure from this node down.
java.util.List	toList() Converts this cog to an List of objects, where the objects are generated via the toObject() method on each child.
Naming	toNaming() Converts this cog to an Naming of objects, where the objects are generated via the toObject() method on each child.
java.lang.Object	toObject() Converts the cog to a Java object.
java.lang.String	toString()
java.util.List<CogValidationException>	validate() Validates this node and all of its children.

Methods inherited from class java.lang.Object

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

Constructor Detail

Cog

public Cog()

Creates an empty, unnamed, detached node with no type.

Cog

public Cog(java.lang.String xmlString)
    throws java.io.IOException

Creates a cog from the given XML string.

Throws:

java.io.IOException

Cog

public Cog(CogSchema schema,
           java.lang.String typeName)

Creates a root cog with the given schema and type name.

Cog

public Cog(java.util.Collection contents)

Creates a cog node and adds the objects in the given collection to it via addAll().

Cog

public Cog(java.util.Map contents)

Creates a cog node and adds the objects in the given map to it via putAll().

Cog

public Cog(java.lang.String typeName,
           java.lang.String name)

Creates an empty node of the given type and name.

Cog

public Cog(java.lang.String typeName,
           java.lang.String name,
           java.lang.Object data)

Creates an empty node with the given typeName, name, and data.

Method Detail

add

public Cog add(Cog newChild)

Adds a node as a child. Automatically sets the child's parent to this node as well.

add

public Cog add(java.lang.String childName)

Creates and adds a blank child node.

add

public Cog add(java.lang.String typeName,
               java.lang.String childName)

Creates and adds a new child. Returns it after adding.

add

public Cog add(java.lang.String typeName,
               java.lang.String childName,
               java.lang.Object data)

Creates and adds a new child with data value. Returns it after adding.

addAll

public void addAll(java.util.Collection items)

Adds all items in the given collection via addObject().

Parameters:

items -

addObject

public void addObject(java.lang.Object object)

Treating this cog as a list, adds the given object to the end. Does not add a name (though if the object is a cog or coggable, it may have one already).

childAt

public Cog childAt(int index)
            throws java.lang.ArrayIndexOutOfBoundsException

Returns the child at the given index.

Throws:

java.lang.ArrayIndexOutOfBoundsException

setChildAt

public Cog setChildAt(int index,
                      Cog child)
               throws java.lang.ArrayIndexOutOfBoundsException

Sets the child at the given index. Detaches and returns the current node at that index, if there is any.

Throws:

java.lang.ArrayIndexOutOfBoundsException

childNamed

public Cog childNamed(java.lang.String childName)

Returns the first direct child with the given name. Returns null if the child is not found.

childWithId

public Cog childWithId(java.lang.String id)

Returns the child with the given unique ID. Returns null if none is found.

cleanStructure

public void cleanStructure()

Attempts to clean up the structure and type names of this cog using its type information.

copy

public Cog copy()

Creates a complete, deep copy of this Cog. The result is completely independent of this node, and identical except that it will not have a parentOrHeader set. WARNING: currently data is only copied by reference; we will need to consider a clone of data if data is used to store non-primitive (String, Number, etc.) values.

detachNode

public void detachNode()

Removes this cog and attaches its descendants to this cog's current parent. Copies the schema from the current root. This cog becomes a standalone cog with no children.

detachNodeFor

public Cog detachNodeFor(Path path)

Removes the given relative node using detachNode(). Does nothing if the child doesn't exist.

detachNodeFor

public Cog detachNodeFor(java.lang.String pathString)

Removes the given relative node using detachNode(). Does nothing if the child doesn't exist.

detachTree

public void detachTree()

Removes this cog and its descendants from its parent. Copies the schema from the current root. This cog becomes the new root of its descendant tree.

detachTreeFor

public Cog detachTreeFor(Path path)

Removes the given relative node using detachTree(). Does nothing if the child doesn't exist.

detachTreeFor

public Cog detachTreeFor(java.lang.String pathString)

Removes the given relative node using detachTree(). Does nothing if the child doesn't exist.

equals

public boolean equals(java.lang.Object nother)

Overrides:

equals in class java.lang.Object

fireChanged

public void fireChanged(java.lang.String what)

getArrayList

public java.util.ArrayList getArrayList(Path path)

getArrayList

public java.util.ArrayList getArrayList(java.lang.String path)

getBoolean

public boolean getBoolean(Path path)

getBoolean

public boolean getBoolean(java.lang.String path)

getChildCount

public int getChildCount()

Returns the number of children.

getChildData

public Naming<java.lang.Object> getChildData()

Gets the child data as a Naming. Handles id, name, and guid by getting them from this node.

getChildren

public java.util.List<Cog> getChildren()

Returns an immutable list of children.

getData

public java.lang.Object getData()

Returns the payload data.

getData

public java.lang.Object getData(Path path)

Gets the data object from the node specified by the path. Returns null if the node or data is missing.

getData

public java.lang.Object getData(java.lang.String path)

Same as getData(Path path) but automatically creates the Path object from the given string.

getDouble

public double getDouble(Path path)

getDouble

public double getDouble(java.lang.String path)

getFloat

public float getFloat(Path path)

getFloat

public float getFloat(java.lang.String path)

getGuid

public java.lang.String getGuid()

Description copied from interface: Identifiable

Globally-unique ID (GUID) for this object. GUIDs should be globally unique for all of a specific kind of identifiable - in fact they should generally follow the UUID design and be unique for all things in the universe. They are used for synchronization in long-transaction, multiple-machine systems. GUIDs are represented as a single String; this interface does not require a required format. GUIDs are generally too long to be very human-legible.

Specified by:

getGuid in interface Identifiable

getHeader

public CogHeader getHeader()

Returns the CogHeader attached to the root. If there is none, creates it first.

getId

public int getId()

Description copied from interface: Identifiable

Numeric ID for this object. Numeric IDs may only be unique for a set of Identifiables in a specific context (e.g. a single computer or database). They are generally small enough to be human-legible but may be automatically generated (e.g. auto incremented).

Specified by:

getId in interface Identifiable

getInt

public int getInt(Path path)

getInt

public int getInt(java.lang.String path)

getList

public java.util.List getList(Path path)

getList

public java.util.List getList(java.lang.String path)

getLong

public long getLong(Path path)

getLong

public long getLong(java.lang.String path)

getName

public java.lang.String getName()

Description copied from interface: Identifiable

Name of this object. Names may not be unique for any given set of Identifiables. They are generally human-oriented.

Specified by:

getName in interface Identifiable

getNaming

public Naming getNaming(Path path)

getNaming

public Naming getNaming(java.lang.String path)

getNode

public Cog getNode(Path path)

Gets the node specified by the path. Returns null if the node is missing.

getNode

public Cog getNode(java.lang.String path)

Same as getNode(Path path) but automatically creates the Path object from the given string.

getObject

public java.lang.Object getObject(Path path)

Gets the object specified by the path. Returns null if the object is missing.

getObject

public java.lang.Object getObject(java.lang.String path)

Same as getObject(Path path) but automatically creates the Path object from the given string.

getOrCreateNodeFor

public Cog getOrCreateNodeFor(Path path)

Gets a descendant of this node, according to the given path. Creates any nodes that do not exist.

getParent

public Cog getParent()

Returns the parent cog, or null if this is a root Cog.

getIndex

public int getIndex()

Returns the index location of this node in its parent's child list, or 0 if this is root.

getPath

public Path getPath()

Returns the full path to this Cog from the root.

getRoot

public Cog getRoot()

Returns the root of the structure this cog is in. If this is the root, returns this object.

getSchema

public CogSchema getSchema()

Returns the schema for this Cog structure. If there is none assigned, returns the CogBootStrapSchema.

getShort

public short getShort(Path path)

getShort

public short getShort(java.lang.String path)

getBytes

public byte[] getBytes(Path path)

getBytes

public byte[] getBytes(java.lang.String path)

getString

public java.lang.String getString(Path path)

getString

public java.lang.String getString(java.lang.String path)

getStringButNullBlanks

public java.lang.String getStringButNullBlanks(Path path)

getStringButNullBlanks

public java.lang.String getStringButNullBlanks(java.lang.String path)

getType

public CogType getType()

Returns the CogType corresponding to the type name in the schema. Returns null if there is no schema or no corresponding type for the type name.

getTypeName

public java.lang.String getTypeName()

isAncestorOf

public boolean isAncestorOf(Cog nother)

Returns true if this node is an ancestor of the given node.

isDescendantOf

public boolean isDescendantOf(Cog nother)

Returns true if this node is a descendant of the given node.

isLeaf

public boolean isLeaf()

Returns true if this is a leaf node with no children.

isRoot

public boolean isRoot()

Returns true if this is the root of a Cog hierarchy.

iterator

public java.util.Iterator<Cog> iterator()

Iterates through the children.

Specified by:

iterator in interface java.lang.Iterable<Cog>

listAncestors

public java.util.List<Cog> listAncestors()

Returns all ancestors of this node as a new list in order from parent to root.

listChildren

public java.util.List<Cog> listChildren()

Returns a freshly-allocated list of this node's children.

Returns:

listChildrenNamed

public java.util.List<Cog> listChildrenNamed(java.lang.String name)

Returns a freshly-allocated list of the children with the given name.

listDescendants

public java.util.List<Cog> listDescendants()

Returns all descendants of this node as a new list.

nodeFor

public Cog nodeFor(Path path)

Gets a another node relative to this one, according to the given path.

nodeFor

public Cog nodeFor(java.lang.String pathString)

Gets a another node relative to this one, according to the given path string.

putAll

public void putAll(java.util.Map map)

Adds all items in the given map via putAll().

putArrayList

public void putArrayList(Path path,
                         java.util.ArrayList value)

putArrayList

public void putArrayList(java.lang.String path,
                         java.util.ArrayList value)

putBoolean

public void putBoolean(Path path,
                       boolean value)

putBoolean

public void putBoolean(java.lang.String path,
                       boolean value)

putData

public void putData(Path path,
                    java.lang.Object data)

Places the given data object at a node specified by the given path. Creates any nodes needed to do this if they are missing.

putData

public void putData(Path path,
                    java.lang.String typeName,
                    java.lang.Object data)

Places the given data object at a node specified by the given path. Creates any nodes needed to do this if they are missing.

putData

public void putData(java.lang.String path,
                    java.lang.Object data)

Same as putData(Path path, Object data) but automatically creates the Path object from the given string.

putData

public void putData(java.lang.String path,
                    java.lang.String typeName,
                    java.lang.Object data)

Same as putData(Path path, typeName, Object data) but automatically creates the Path object from the given string.

putDouble

public void putDouble(Path path,
                      double value)

putDouble

public void putDouble(java.lang.String path,
                      double value)

putFloat

public void putFloat(Path path,
                     float value)

putFloat

public void putFloat(java.lang.String path,
                     float value)

putInt

public void putInt(Path path,
                   int value)

putInt

public void putInt(java.lang.String path,
                   int value)

putList

public void putList(Path path,
                    java.util.List value)

putList

public void putList(Path path,
                    java.lang.String typeName,
                    java.util.List value)

putList

public void putList(java.lang.String path,
                    java.util.List value)

putList

public void putList(java.lang.String path,
                    java.lang.String typeName,
                    java.util.List value)

putLong

public void putLong(Path path,
                    long value)

putLong

public void putLong(java.lang.String path,
                    long value)

putNaming

public void putNaming(Path path,
                      Naming value)

putNaming

public void putNaming(java.lang.String path,
                      Naming value)

putNode

public void putNode(Path path,
                    Cog node)

Places the given node at the location specified by the given path. Creates any nodes needed to do this if they are missing.

putNode

public void putNode(java.lang.String path,
                    Cog node)

Same as putNode(Path path, Cog node) but automatically creates the Path object from the given string.

putObject

public void putObject(Path path,
                      java.lang.Object object)

Places the given object at the location specified by the given path. Converts it to a Cog if necessary. Creates any nodes needed to do this if they are missing.

putObject

public void putObject(java.lang.String path,
                      java.lang.Object object)

Same as putObject(Path path, Object object) but automatically creates the Path object from the given string.

putShort

public void putShort(Path path,
                     short value)

putShort

public void putShort(java.lang.String path,
                     short value)

putString

public void putString(Path path,
                      java.lang.String value)

putString

public void putString(Path path,
                      java.lang.String typeName,
                      java.lang.String value)

putString

public void putString(java.lang.String path,
                      java.lang.String value)

putString

public void putString(java.lang.String path,
                      java.lang.String typeName,
                      java.lang.String value)

putBytes

public void putBytes(java.lang.String path,
                     byte[] value)

putBytes

public void putBytes(Path path,
                     byte[] value)

renameChild

public Cog renameChild(java.lang.String oldName,
                       java.lang.String newName)

Renames the given child node. Replaces any node that already has that name, and returns it. If no node has the new name it returns null. Does nothing if the child specified by oldName does not exist.

setChildData

public void setChildData(Naming<java.lang.Object> childData)

Sets the child data using the given named values. Handles id, name, and guid by setting them on this node.

setData

public void setData(java.lang.Object newData)

Sets the payload data.

setGuid

public void setGuid(java.lang.String newGuid)

setId

public void setId(int newID)

setName

public void setName(java.lang.String newName)

setParent

public void setParent(Cog newParent)

Sets the parent cog. Root cogs have null parents. Automatically adds this node to the parent's child list as well, and detaches it from its current parent (if any).

setSchema

public void setSchema(CogSchema newSchema)

Sets the schema for this Cog structure. Only works if this is the root node, otherwise throws IllegalStateException.

setTypeName

public void setTypeName(java.lang.String newTypeName)

toDetailedString

public java.lang.String toDetailedString()

Gives a more detailed String representation of the entire Cog structure from this node down.

Returns:

toList

public java.util.List toList()

Converts this cog to an List of objects, where the objects are generated via the toObject() method on each child.

toNaming

public Naming toNaming()

Converts this cog to an Naming of objects, where the objects are generated via the toObject() method on each child.

toObject

public java.lang.Object toObject()

Converts the cog to a Java object. Has to be connected to a CogSchema so that it can look up its datatype definitions and figure out what Java classes to instantiate.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

validate

public java.util.List<CogValidationException> validate()

Validates this node and all of its children.