things.data.impl
Class ThingsPropertyTreeRAM

java.lang.Object
  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