things.data.impl
Class ThingsPropertyTreeRAM

java.lang.Object
  extended by things.data.impl.ThingsPropertyTreeRAM
All Implemented Interfaces:
ThingsProperty, ThingsPropertyTree, ThingsPropertyView, ThingsPropertyViewReader

public class ThingsPropertyTreeRAM
extends java.lang.Object
implements ThingsPropertyTree, ThingsPropertyView

A very basic property view for an in-memory store using java HashMap.

SPECIAL NOTE

The real implementation of a property tree remains proprietary. This is a cheap implementation provided so we can release everything else. It works well enough for casual use, but don't expect this to be a good example of how to design on code.

THIS IMPLEMENTATION IS A BIG FAT BUCKET OF ConcurrentModificationException, since it uses HashMap. This might cause you some hassle.

Version:
1.0

Version History

 EPG - Initial - 26 MAR 05
 EPG - Shift implementation to generic HashMap - 14 JUN 05
 EPG - Added sub - 19 JUL 07
 
Author:
Erich P. Gatejen

Field Summary
 
Fields inherited from interface things.data.ThingsProperty
PROPERTY_COMMENT_CHARACTER, PROPERTY_CR, PROPERTY_EMPTY, PROPERTY_ESCAPE_CHARACTER, PROPERTY_ESCAPED_CR, PROPERTY_ESCAPED_LF, PROPERTY_LF, PROPERTY_LINE_CONTINUATION, PROPERTY_LINE_CONTINUATION_STRING, PROPERTY_LINE_EQUALITY, PROPERTY_LINE_SEPARATOR, PROPERTY_LINE_SEPARATOR_ASSTRING, PROPERTY_LINE_TERMINATION, PROPERTY_PATH_SEPARATOR
 
Constructor Summary
ThingsPropertyTreeRAM()
          Default constructor
ThingsPropertyTreeRAM(java.util.HashMap<java.lang.String,java.lang.String[]> properties, java.lang.String root)
          Construct a child.
 
Method Summary
 ThingsPropertyViewReader branch(java.lang.String path)
          Branch the view to create a new view.
 void copyAndGraftBranch(java.lang.String sourceBranchPath, java.lang.String graftRoot)
          Copy a branch and graft it somewhere else.
 ThingsPropertyTree copyBranch(java.lang.String branchPath)
          Copy a branch of the tree as a new tree.
 ThingsPropertyView cutting(java.lang.String path)
          Pruning to get a new a new view.
 ThingsPropertyView getBranch(java.lang.String path)
          Get a view of a branch on the tree.
 java.lang.String getProperty(java.lang.String... pathElements)
          Get a property value as a string.
 java.lang.String getProperty(java.lang.String path)
          Get a property value as a string.
 java.lang.String[] getPropertyMultivalue(java.lang.String path)
          Get a property value as a multivalue.
 NVImmutable getPropertyNV(java.lang.String path)
          Get a property value as a multivalue.
 ThingsPropertyView getRoot()
          Get a view from the root.
 void graft(ThingsPropertyView sourceView)
          Graft one view onto this view.
 void infliltrate(ThingsPropertyTrunk tio)
          This is how you load and merge properties into an already populated tree.
 void init(ThingsPropertyTrunk tio)
          Tell the tree to init itself.
 void load()
          Tell the tree to load fresh.
 java.util.Collection<java.lang.String> ply(java.lang.String path)
          Get the ply at this path.
 void prune(java.lang.String path)
          Prune off the path.
 void removeProperty(java.lang.String path)
          Remove a specific property without subverting a tree.
 void save()
          Tell the tree to save itself.
 void setProperty(NVImmutable item)
          Set a property value from an NVImmutable item.
 void setProperty(java.lang.String path, java.lang.String value)
          Set a property value as a string.
 void setProperty(java.lang.String path, java.lang.String value, java.lang.String defaultValue)
          Set a property value as a string.
 void setPropertyMultivalue(java.lang.String path, java.lang.String... values)
          Set a property value as a multivalue.
 java.util.Collection<java.lang.String> sub(java.lang.String path)
          Get all property names under this at this path.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ThingsPropertyTreeRAM

public ThingsPropertyTreeRAM()
Default constructor


ThingsPropertyTreeRAM

public ThingsPropertyTreeRAM(java.util.HashMap<java.lang.String,java.lang.String[]> properties,
                             java.lang.String root)
                      throws ThingsException
Construct a child. Do not use this directly.

Throws:
ThingsException
Method Detail

getBranch

public ThingsPropertyView getBranch(java.lang.String path)
                             throws ThingsException
Get a view of a branch on the tree. This view is on a shared tree, so any changes will be visible to every view. The branch will always be relative to the root.

Specified by:
getBranch in interface ThingsPropertyTree
Parameters:
path - path to the branch. null we return the root
Returns:
a view of the branch
Throws:
ThingsException

getRoot

public ThingsPropertyView getRoot()
                           throws ThingsException
Get a view from the root. This view is on a shared tree, so any changes will be visible to every view

Specified by:
getRoot in interface ThingsPropertyTree
Returns:
a view
Throws:
ThingsException

copyBranch

public ThingsPropertyTree copyBranch(java.lang.String branchPath)
                              throws ThingsException
Copy a branch of the tree as a new tree. The new tree will have no connection to the original.

Specified by:
copyBranch in interface ThingsPropertyTree
Parameters:
branchPath - path to the branch from where to start the copy. An empty or null value will return the root.
Returns:
a new property tree starting from the branch
Throws:
ThingsException

copyAndGraftBranch

public void copyAndGraftBranch(java.lang.String sourceBranchPath,
                               java.lang.String graftRoot)
                        throws ThingsException
Copy a branch and graft it somewhere else. The new nodes will have no connection to the other branch.

Specified by:
copyAndGraftBranch in interface ThingsPropertyTree
Parameters:
sourceBranchPath - path to the branch from where to copy. An empty or null value will return the root.
graftRoot - the path to where it should be grafted.
Throws:
ThingsException

prune

public void prune(java.lang.String path)
           throws ThingsException
Prune off the path. Properties will be removed and gone forever.

Specified by:
prune in interface ThingsPropertyView
Parameters:
path - the property path (relative to the view root). A null is not allowed.
Throws:
ThingsException

load

public void load()
          throws ThingsException
Tell the tree to load fresh. The actual action is up to the implementation.

Specified by:
load in interface ThingsPropertyTree
Throws:
ThingsException

save

public void save()
          throws ThingsException
Tell the tree to save itself. The actual action is up to the implementation.

Specified by:
save in interface ThingsPropertyTree
Specified by:
save in interface ThingsPropertyView
Throws:
ThingsException

init

public void init(ThingsPropertyTrunk tio)
          throws ThingsException
Tell the tree to init itself. It will dump any current properties. You'll need to load() new props. Typically, the ThingsPropertyTrunk needs to be primed with a ThingsPropertyTrunk.startRead() before the load() method is called. However this may be left up to the implementation.

Specified by:
init in interface ThingsPropertyTree
Parameters:
tio - a trunk to load and save the properties
Throws:
ThingsException

infliltrate

public void infliltrate(ThingsPropertyTrunk tio)
                 throws ThingsException
This is how you load and merge properties into an already populated tree. Typically, the ThingsPropertyTrunk needs to be primed with a ThingsPropertyTrunk.startRead() before the load() method is called. However this may be left up to the implementation.

Specified by:
infliltrate in interface ThingsPropertyTree
Parameters:
tio - a trunk to load and save the properties
Throws:
ThingsException

setProperty

public void setProperty(java.lang.String path,
                        java.lang.String value)
                 throws ThingsException
Set a property value as a string. The property will be from the root of the view. Bad parameters will result in ERROR level exceptions.

Specified by:
setProperty in interface ThingsPropertyView
Parameters:
path - the property path (relative to the view root)
value - the property value as a string
Throws:
ThingsException

setProperty

public void setProperty(java.lang.String path,
                        java.lang.String value,
                        java.lang.String defaultValue)
                 throws ThingsException
Set a property value as a string. The property will be from the root of the view. If the value is null, it will set it as the defaultValue instead.

Specified by:
setProperty in interface ThingsPropertyView
Parameters:
path - the property path (relative to the view root)
value - the property value as a string
defaultValue - the default value.
Throws:
ThingsException

setProperty

public void setProperty(NVImmutable item)
                 throws ThingsException
Set a property value from an NVImmutable item. The property will be from the root of the view.

Specified by:
setProperty in interface ThingsPropertyView
Parameters:
item - the item
Throws:
ThingsException
See Also:
NVImmutable

setPropertyMultivalue

public void setPropertyMultivalue(java.lang.String path,
                                  java.lang.String... values)
                           throws ThingsException
Set a property value as a multivalue. The property will be from the root of the view.

Specified by:
setPropertyMultivalue in interface ThingsPropertyView
Parameters:
path - the property path (relative to the view root)
values - the property values as Strings.
Throws:
ThingsException

removeProperty

public void removeProperty(java.lang.String path)
                    throws ThingsException
Remove a specific property without subverting a tree.

Specified by:
removeProperty in interface ThingsPropertyView
Parameters:
path - the property path (relative to the view root). A null or bogus path will be ignored.
Throws:
ThingsException

cutting

public ThingsPropertyView cutting(java.lang.String path)
                           throws ThingsException
Pruning to get a new a new view. The new view will have the path as its root.

Specified by:
cutting in interface ThingsPropertyView
Parameters:
path - the property path (relative to the view root)
Returns:
The new view.
Throws:
ThingsException

graft

public void graft(ThingsPropertyView sourceView)
           throws ThingsException
Graft one view onto this view. All properties will be added. The values will be copies, so the original tree will be left unaltered.

SLOWWWW since it takes too passes. Yuck! We'll let the NVImmutable take care of the "copies so the original tree will be left unaltered).

Specified by:
graft in interface ThingsPropertyView
Parameters:
sourceView - view to graft on.
Throws:
ThingsException

branch

public ThingsPropertyViewReader branch(java.lang.String path)
                                throws ThingsException
Branch the view to create a new view. The new view will have the path as its root.

Specified by:
branch in interface ThingsPropertyViewReader
Parameters:
path - the property path (relative to the view root)
Returns:
The new view.
Throws:
ThingsException

getProperty

public java.lang.String getProperty(java.lang.String path)
                             throws ThingsException
Get a property value as a string. It will return null if the property is not set. If it is a multivalue, it will return it encoded to a single String.

Specified by:
getProperty in interface ThingsPropertyViewReader
Parameters:
path - the property name
Returns:
value of the property or null if it does not exist
Throws:
ThingsException

getProperty

public java.lang.String getProperty(java.lang.String... pathElements)
                             throws ThingsException
Get a property value as a string. It will return null if the property is not set. If it is a multivalue, it will return it encoded to a single String.

Specified by:
getProperty in interface ThingsPropertyViewReader
Parameters:
pathElements - a stitch-able path.
Returns:
value of the property or null if it does not exist
Throws:
ThingsException

getPropertyMultivalue

public java.lang.String[] getPropertyMultivalue(java.lang.String path)
                                         throws ThingsException
Get a property value as a multivalue. It will return null if the property is not set.

Specified by:
getPropertyMultivalue in interface ThingsPropertyViewReader
Parameters:
path - the property name
Returns:
value A array of the values.
Throws:
ThingsException

getPropertyNV

public NVImmutable getPropertyNV(java.lang.String path)
                          throws ThingsException
Get a property value as a multivalue. It will return null if the property is not set.

Specified by:
getPropertyNV in interface ThingsPropertyViewReader
Parameters:
path - the property name
Returns:
value of the property or null if it does not exist
Throws:
ThingsException
See Also:
NVImmutable

sub

public java.util.Collection<java.lang.String> sub(java.lang.String path)
                                           throws ThingsException
Get all property names under this at this path.

Specified by:
sub in interface ThingsPropertyViewReader
Parameters:
path - a offset path.
Returns:
a collection of strings
Throws:
ThingsException

ply

public java.util.Collection<java.lang.String> ply(java.lang.String path)
                                           throws ThingsException
Get the ply at this path. It'll return all the node names at this path but no more.

Specified by:
ply in interface ThingsPropertyViewReader
Parameters:
path - a root path.
Returns:
a collection of strings
Throws:
ThingsException


Things.