com.bigdata.counters
Class CounterSet

java.lang.Object
  com.bigdata.counters.AbstractCounterSet
      com.bigdata.counters.CounterSet

All Implemented Interfaces:

ICounterNode, ICounterSet

public class CounterSet
extends AbstractCounterSet
implements ICounterSet

A set of counters arranged in a hierarchy, much like a file system. Each node has a name and a path. The name is a local and immutable label. The path is the {separator, name} sequence reading down from the root to a given node. The "root" is the top-most node in the hierarchy - it always has an empty name and its path is /. The direct children of a root are typically fully qualified host names. E.g., /www.bigdata.com.

Nodes are always created as children of an existing root. Once created, any non-root node may be attached as a child of any other node, including a root node, as long as cycles would not be formed. When a node is attached as a child of another node, the path of the child and all of its children are updated recursively. E.g., if /Memory is attached to /www.bigdata.com then its path becomes /www.bigdata.com/Memory.

Children are either CounterSets or individual Counters. Counter sets and counters are declared in the namespace and their names must be distinct.

Version:

$Id: CounterSet.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

TODO:

The CounterSet should perhaps obtain a lock on the node(s) to be modified rather than the root for better concurrency., the syntax "." and ".." are not recognized., should declare the units and the counter description with the counter but only propagate the description once (alternatively, specify a counter description interface and pass that along). The more difficult question is how to limit the transfer of the full description. Perhaps by having the LBS query for it?

Nested Class Summary

Nested classes/interfaces inherited from interface com.bigdata.counters.ICounterSet

ICounterSet.IInstrumentFactory

Field Summary

protected static org.apache.log4j.Logger

log

Fields inherited from class com.bigdata.counters.AbstractCounterSet

name, parent

Fields inherited from interface com.bigdata.counters.ICounterSet

pathSeparator

Constructor Summary

CounterSet()
Ctor for a root node.

Method Summary

ICounter	addCounter(String path, IInstrument instrument) Add a counter.
void	asXML(Writer w, Pattern filter) Per AbstractCounterSet.asXML(OutputStream, String, Pattern) but does not write out the header declaring the encoding.
void	attach(ICounterNode src) Attaches a CounterSet as a child of this node.
void	attach(ICounterNode src, boolean replace)
Iterator<ICounter>	counterIterator(Pattern filter) Visits direct child counters matching the optional filter.
Iterator<ICounterSet>	counterSetIterator() Iterator visits the directly attached ICounterSet children.
ICounterNode	detach(String path) Detaches and returns the node having that path.
Iterator	directChildIterator(boolean sorted, Class<? extends ICounterNode> type) Iterator visits all directly attached children.
ICounterNode	getChild(String name) Return the directly attached object by name.
Iterator<ICounter>	getCounters(Pattern filter) Visits ICounter matching the optional filter declared anywhere in the hierarchy spanned by this ICounterSet.
Iterator<ICounterNode>	getNodes(Pattern filter) All spanned nodes.
boolean	isLeaf()
CounterSet	makePath(String path) Adds any necessary CounterSets described in the path (ala mkdirs).
Iterator	postOrderIterator() Iterator visits ICounterSet children recursively expanding each child with a post-order traversal of its children and finally visits this node itself.
Iterator	preOrderIterator() Iterator visits this node recursively expanding each ICounterSet child with a pre-order traversal of its children and finally visits this node itself.
void	readXML(InputStream is, ICounterSet.IInstrumentFactory instrumentFactory, Pattern filter) Reads counters into this hierarchy.

Methods inherited from class com.bigdata.counters.AbstractCounterSet

asXML, asXML, asXML, getDepth, getName, getParent, getPath, getPath, getPathComponents, getRoot, isCounter, isCounterSet, isRoot, toString, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.bigdata.counters.ICounterSet

asXML, asXML, toString, toString

Methods inherited from interface com.bigdata.counters.ICounterNode

getDepth, getName, getParent, getPath, getPath, getRoot, isCounter, isCounterSet, isRoot

Field Detail

log

protected static final org.apache.log4j.Logger log

Constructor Detail

CounterSet

public CounterSet()

Ctor for a root node.

Method Detail

isLeaf

public boolean isLeaf()

attach

public void attach(ICounterNode src)

Attaches a CounterSet as a child of this node. If child is a root, then all children of the child are attached instead. If a CounterSet already exists then its children are attached. If a Counters already exists then it is overwritten. During recursive attach if we encounter a node that already exists then just copy its children. If there is a conflict (trying to copy a counter over a counter set or visa-versa), then a warning is logged and we ignore the conflicting node.

Parameters:

src - The child counter set.

Throws:

IllegalArgumentException - if child is null

IllegalStateException - if child is either this node or any parent of this node since a cycle would be formed.

attach

public void attach(ICounterNode src,
                   boolean replace)

detach

public ICounterNode detach(String path)

Detaches and returns the node having that path.

Parameters:

path - The path.

Returns:

The node -or- null if there is no node with that path.

counterIterator

public Iterator<ICounter> counterIterator(Pattern filter)

Visits direct child counters matching the optional filter.

Note: Since the filter does NOT have to be anchored at the root, the only place we can apply a filter that is NOT anchored at the root is when checking a fully qualified counter name.

TODO:

optimize for patterns that are anchored by filtering the child ICounterSet.

getNodes

public Iterator<ICounterNode> getNodes(Pattern filter)

All spanned nodes.

Parameters:

filter - An optional filter.

Returns:

getCounters

public Iterator<ICounter> getCounters(Pattern filter)

Description copied from interface: ICounterSet

Visits ICounter matching the optional filter declared anywhere in the hierarchy spanned by this ICounterSet.

Specified by:

getCounters in interface ICounterSet

Parameters:

filter - An optional regular expression that will be applied to ICounterNode.getPath() to filter matches. When specified, only ICounters whose ICounterNode.getPath() match will be visited by the Iterator.

directChildIterator

public Iterator directChildIterator(boolean sorted,
                                    Class<? extends ICounterNode> type)

Iterator visits all directly attached children.

Parameters:

sorted - When true the children will be visited in order by their name.

type - An optional type filter - specify either ICounterSet or ICounter you want to be visited by the iterator. When null all directly attached children (counters and counter sets) are visited.

counterSetIterator

public Iterator<ICounterSet> counterSetIterator()

Iterator visits the directly attached ICounterSet children.

postOrderIterator

public Iterator postOrderIterator()

Iterator visits ICounterSet children recursively expanding each child with a post-order traversal of its children and finally visits this node itself.

preOrderIterator

public Iterator preOrderIterator()

Iterator visits this node recursively expanding each ICounterSet child with a pre-order traversal of its children and finally visits this node itself.

getChild

public ICounterNode getChild(String name)

Description copied from interface: ICounterNode

Return the directly attached object by name.

Specified by:

getChild in interface ICounterNode

Parameters:

name - The counter name.

Returns:

The object.

makePath

public CounterSet makePath(String path)

Adds any necessary CounterSets described in the path (ala mkdirs).

Specified by:

makePath in interface ICounterSet

Parameters:

path - The path.

Returns:

The CounterSet described by the path.

addCounter

public ICounter addCounter(String path,
                           IInstrument instrument)

Add a counter.

Parameters:

path - The path of the counter (absolute or relative).

instrument - The object that is used to take the measurements from which the counter's value will be determined.

asXML

public void asXML(Writer w,
                  Pattern filter)
           throws IOException

Per AbstractCounterSet.asXML(OutputStream, String, Pattern) but does not write out the header declaring the encoding.

Specified by:

asXML in interface ICounterSet

Parameters:

w - The XML will be written on this object.

filter - The optional filter.

Throws:

IOException

readXML

public void readXML(InputStream is,
                    ICounterSet.IInstrumentFactory instrumentFactory,
                    Pattern filter)
             throws IOException,
                    ParserConfigurationException,
                    SAXException

Description copied from interface: ICounterSet

Reads counters into this hierarchy.

Specified by:

readXML in interface ICounterSet

instrumentFactory - Used to create counters on an as needed basis.

filter - An optional filter, when specified only counters matching the filter will be processed.

Throws:

IOException

ParserConfigurationException

SAXException