com.persistit

Class Tree

java.lang.Object

com.persistit.Tree

public class Tree
extends Object

Cached meta-data about a single B-Tree within a Volume. A Tree object keeps track of the Volume, the index root page, the index depth, various other statistics and the Accumulators for a B-Tree.

As of Persistit 3.3, this class supports version within transactions. A new Tree created within the cope of a Transaction is not visible within the other transactions until it commits. Similarly, if a Tree is removed within the scope of a transaction, other transactions that started before the current transaction commits will continue to be able to read and write the Tree. As a side-effect, the physical storage for a Tree is not deallocated until there are no remaining active transactions that started before the commit timestamp of the current transaction. Concurrent transactions that attempt to create or remove the same Tree instance are subject to a a write-write dependency (see Transaction); all but one such transaction must roll back.

Tree instances are created by Volume.getTree(String, boolean). If the Volume already has a B-Tree with the specified name, then the Tree object returned by getTree reflects the stored information. Otherwise, getTree can create a new B-Tree. In either case, the Tree is merely a transient in-memory cache for the B-Tree information ultimately stored on disk.

Persistit ensures that Tree instances are unique, that is, for a given Volume and name, there is only one Tree. if multiple threads call Volume.getTree(String, boolean) for the same name on the same volume, the first such call will create a new Tree instance and subsequent calls will return the same instance.

Each Tree may have up to 64 Accumulator instances that may be used to aggregate statistical information such as counters. Accumulators work within the MVCC transaction scheme to provide highly concurrent access to a small number of variables that would otherwise cause a significant performance degradation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Tree.TreeVersionException Unchecked wrapper for PersistitException thrown while trying to acquire a TreeVersion.

Field Summary

Fields

Modifier and Type	Field and Description
protected Persistit	_persistit
static long	DEFAULT_MAX_WAIT_TIME Default maximum time to wait for access to this resource.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
Object	getAppCache()
int	getDepth()
long	getGeneration()
int	getHandle()
Accumulator.MaxAccumulator	getMaxAccumulator(int index) Return a MaxAccumulator for this Tree and the specified index value between 0 and 63, inclusive.
Accumulator.MinAccumulator	getMinAccumulator(int index) Return a MinAccumulator for this Tree and the specified index value between 0 and 63, inclusive.
String	getName()
long	getRootPageAddr() Returns the page address of the root page of this Tree.
Accumulator.SeqAccumulator	getSeqAccumulator(int index) Return a SeqAccumulator for this Tree and the specified index value between 0 and 63, inclusive.
TreeStatistics	getStatistics()
String	getStatusCode()
static String	getStatusCode(int state)
String	getStatusDisplayString()
Accumulator.SumAccumulator	getSumAccumulator(int index) Return a SumAccumulator for this Tree and the specified index value between 0 and 63, inclusive.
Volume	getVolume()
Thread	getWriterThread()
int	hashCode()
boolean	isAvailable(boolean writer)
boolean	isDeleted()
boolean	isTemporary()
boolean	isValid()
void	setAppCache(Object appCache) Store an Object with this Tree for the convenience of an application.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAX_WAIT_TIME

public static final long DEFAULT_MAX_WAIT_TIME

Default maximum time to wait for access to this resource. Methods throw an InUseException when this time is exceeded.

See Also:

Constant Field Values

_persistit

protected final Persistit _persistit

Method Detail

isDeleted

public boolean isDeleted()
                  throws TimeoutException,
                         PersistitInterruptedException

Throws:

TimeoutException

PersistitInterruptedException

getVolume

public Volume getVolume()

Returns:

The volume containing this Tree.

getName

public String getName()

Returns:

This Tree's name

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

getRootPageAddr

public long getRootPageAddr()

Returns the page address of the root page of this Tree. The root page will be a data page if the Tree has only one page, or will be the top index page of the B-Tree.

Returns:

The page address

getDepth

public int getDepth()

Returns:

the number of levels of the Tree.

getGeneration

public long getGeneration()

getStatistics

public TreeStatistics getStatistics()

Returns:

a TreeStatistics object containing approximate counts of records added, removed and fetched from this Tree

toString

public String toString()

Returns:

a displayable description of the Tree, including its name, its internal tree index, its root page address, and its depth.

setAppCache

public void setAppCache(Object appCache)

Store an Object with this Tree for the convenience of an application.

Parameters:

appCache - the object to be cached for application convenience.

getAppCache

public Object getAppCache()

Returns:

the object cached for application convenience

getHandle

public int getHandle()

Returns:

The handle value used to identify this Tree in the journal

getSumAccumulator

public Accumulator.SumAccumulator getSumAccumulator(int index)
                                             throws PersistitException

Return a SumAccumulator for this Tree and the specified index value between 0 and 63, inclusive. If the Tree does not yet have an Accumulator with the specified index, this method creates one. Otherwise the previously created Accumulator, which must be a SumAccumulator, is returned.

Parameters:

index - Application-controlled value between 0 and 63, inclusive.

Returns:

The Accumulator

Throws:

IllegalStateException - if the previously created instance is not a SumAccumulator

PersistitException

getSeqAccumulator

public Accumulator.SeqAccumulator getSeqAccumulator(int index)
                                             throws PersistitException

Return a SeqAccumulator for this Tree and the specified index value between 0 and 63, inclusive. If the Tree does not yet have an Accumulator with the specified index, this method creates one. Otherwise the previously created Accumulator, which must be a SeqAccumulator, is returned.

Parameters:

index - Application-controlled value between 0 and 63, inclusive.

Returns:

The Accumulator

Throws:

IllegalStateException - if the previously created instance is not a SeqAccumulator

PersistitException

getMinAccumulator

public Accumulator.MinAccumulator getMinAccumulator(int index)
                                             throws PersistitException

Return a MinAccumulator for this Tree and the specified index value between 0 and 63, inclusive. If the Tree does not yet have an Accumulator with the specified index, this method creates one. Otherwise the previously created Accumulator, which must be a MinAccumulator, is returned.

Parameters:

index - Application-controlled value between 0 and 63, inclusive.

Returns:

The Accumulator

Throws:

IllegalStateException - if the previously created instance is not a MinAccumulator

PersistitException

getMaxAccumulator

public Accumulator.MaxAccumulator getMaxAccumulator(int index)
                                             throws PersistitException

Return a MaxAccumulator for this Tree and the specified index value between 0 and 63, inclusive. If the Tree does not yet have an Accumulator with the specified index, this method creates one. Otherwise the previously created Accumulator, which must be a MaxAccumulator, is returned.

Parameters:

index - Application-controlled value between 0 and 63, inclusive.

Returns:

The Accumulator

Throws:

IllegalStateException - if the previously created instance is not a MaxAccumulator

PersistitException

isAvailable

public boolean isAvailable(boolean writer)

isValid

public boolean isValid()

isTemporary

public boolean isTemporary()

getStatusCode

public String getStatusCode()

getStatusDisplayString

public String getStatusDisplayString()

getStatusCode

public static String getStatusCode(int state)

getWriterThread

public Thread getWriterThread()