Exchange (org.openidentityplatform.commons.parent 2.2.3 Documentation)

java.lang.Object
- com.persistit.Exchange

All Implemented Interfaces:

ReadOnlyExchange
```
public class Exchange
extends Object
implements ReadOnlyExchange
```
The main facade for fetching, storing and removing records from a Persistit™ database.

Applications interact with Persistit through instances of this class. A Exchange has two important associated member objects, a Key and a Value. A Key is a mutable representation of a key, and a Value is a mutable representation of a value. Applications manipulate these objects and interact with the database through one of the following four general patterns:
1. Modify the Key, perform a fetch operation, and query the Value.
2. Modify the Key, modify the Value, and then perform a store operation to insert or replace data in the database.
3. Modify the Key, and then perform a remove to remove one or more key/value pairs.
4. Optionally modify the Key, perform a traverse operation, then query the resulting state of Key and/or Value to enumerate key/value pairs currently stored in the database.
Additional methods of Exchange include fetchAndStore and fetchAndRemove which atomically modify the database and return the former value associated with the current Key.

Exchange is Not Threadsafe
Important: an Exchange and its associated Key and Value instances are not thread-safe. Generally each Thread should allocate and use its own Exchange instances. Were it to occur, modification of the Key or Value objects associated with an Exchange by another thread could cause severe and unpredictable errors, including possible corruption of the underlying data storage. While the methods of one Exchange instance are not threadsafe, Persistit is designed to allow multiple threads, using multiple Exchange instances, to access and update the underlying database in a highly concurrent fashion.

Exchange Pools
Normally each thread should allocate its own Exchange instances. However, depending on the garbage collection performance characteristics of a particular JVM it may be desirable to maintain a pool of Exchanges available for reuse, thereby reducing the frequency with which Exchanges need to be constructed and then garbage collected. An application may get an Exchange using Persistit.getExchange(String, String, boolean) or Persistit.getExchange(Volume, String, boolean). These methods reuse a previously constructed Exchange if one is available in a pool; otherwise they construct methods construct a new one. Applications using the Exchange pool should call Persistit.releaseExchange(Exchange, boolean) to relinquish an Exchange once it is no longer needed, thereby placing it in the pool for subsequent reuse.
Version:

1.0

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Exchange.Sequence`
`static interface`	`Exchange.TraverseVisitor` A visitor used with the `traverse(Key.Direction, boolean, int, TraverseVisitor)` The `Exchange.TraverseVisitor.visit(ReadOnlyExchange)` method is called once for each `Key` traversed by the `traverse` method.

Constructor Summary

Constructors
Constructor and Description
`Exchange(Exchange exchange)` Construct a new `Exchange` to access the same `Volume` and `Tree` as the supplied `Exchange`.
`Exchange(Persistit persistit, String volumeName, String treeName, boolean create)` Construct a new `Exchange` object to create and/or access the `Tree` specified by treeName within the `Volume` specified by `volumeName`.
`Exchange(Persistit persistit, Volume volume, String treeName, boolean create)` Construct a new `Exchange` object to create and/or access the `Tree` specified by treeName within the specified `Volume`.
`Exchange(Tree tree)` Construct a new `Exchange` to access the specified `Tree`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Exchange`	`append(boolean item)` Delegate to `Key.append(boolean)` on the associated `Key` object.
`Exchange`	`append(byte item)` Delegate to `Key.append(byte)` on the associated `Key` object.
`Exchange`	`append(char item)` Delegate to `Key.append(char)` on the associated `Key` object.
`Exchange`	`append(double item)` Delegate to `Key.append(double)` on the associated `Key` object.
`Exchange`	`append(float item)` Delegate to `Key.append(float)` on the associated `Key` object.
`Exchange`	`append(int item)` Delegate to `Key.append(int)` on the associated `Key` object.
`Exchange`	`append(long item)` Delegate to `Key.append(long)` on the associated `Key` object.
`Exchange`	`append(Object item)` Delegate to `Key.append(Object)` on the associated `Key` object.
`Exchange`	`append(short item)` Delegate to `Key.append(short)` on the associated `Key` object.
`Exchange`	`clear()` Delegate to `Key.clear()` on the associated `Key` object.
`KeyHistogram`	`computeHistogram(Key start, Key end, int sampleSize, int keyDepth, KeyFilter keyFilter, int requestedTreeDepth)`
`Exchange`	`cut()` Delegate to `Key.cut()` on the associated `Key` object.
`Exchange`	`cut(int level)` Delegate to `Key.cut(int)` on the associated `Key` object.
`Exchange`	`fetch()` Fetches the value associated with the current `Key` into the `Exchange`'s `Value`.
`Exchange`	`fetch(int minimumBytes)` Fetches or partially fetches the value associated with the current `Key` into the `Exchange`'s `Value`.
`Exchange`	`fetch(Value value)` Fetches the value associated with the current `Key` into the supplied `Value` object (instead of the `Exchange` 's assigned `Value`).
`Exchange`	`fetch(Value value, int minimumBytes)` Fetches or partially fetches the value associated with the current `Key` into the supplied `Value` object (instead of the `Exchange`'s assigned `Value`).
`boolean`	`fetchAndRemove()` Remove a single key/value pair from this `Exchange`'s `Tree` and return the removed value in the `Exchange`'s `Value`.
`Exchange`	`fetchAndStore()` Fetches the value associated with the `Key`, then inserts or updates the value.
`Buffer`	`fetchBufferCopy(int level)` Returns a copy of either the data page or a page on the index path to the data page containing the current key.
`Object`	`getAppCache()`
`long`	`getChangeCount()` Return the count of structural changes committed to the `Tree` on which this `Exchange` operates.
`Key`	`getKey()` Return the `Key` associated with this `Exchange`.
`Persistit`	`getPersistitInstance()` Return the Persistit instance from which this Exchange was created.
`long`	`getTimeoutMillis()`
`Transaction`	`getTransaction()` The transaction context for this Exchange.
`Tree`	`getTree()` Return the `Tree` on which this `Exchange` operates.
`Value`	`getValue()` Return the `Value` associated with this `Exchange`.
`Volume`	`getVolume()` Return the `Volume` containing the data accessed by this `Exchange`.
`boolean`	`hasChildren()` Return true if there is at least one key stored in this `Exchange` 's `Tree` that is a logical child of the current `Key`.
`boolean`	`hasNext()` Determines whether the current key has a logical sibling successor, without changing the state of `Key` or `Value`.
`boolean`	`hasNext(boolean deep)` Determines whether the current key has a logical sibling successor, without changing the state of `Key` or `Value`.
`boolean`	`hasNext(KeyFilter filter)` Determines whether the current key has a successor within the subset of all keys defined by a `KeyFilter`.
`boolean`	`hasPrevious()` Determines whether the current key has a logical sibling predecessor, without changing the state of `Key` or `Value`.
`boolean`	`hasPrevious(boolean deep)` Determines whether the current key has a logical sibling predecessor, without changing the state of `Key` or `Value`.
`boolean`	`hasPrevious(KeyFilter filter)` Determines whether the current key has a predecessor within the subset of all keys defined by a `KeyFilter`.
`void`	`initCache()` Drop all cached optimization information
`boolean`	`isValueDefined()` Determines whether the current key has an associated value - that is, whether a `fetch()` operation would return a defined value - without actually changing the state of either the `Key` or the `Value`.
`void`	`lock()` Invoke `lock(Key, long)` with the current key and a default timeout value of 60000L milliseconds.
`void`	`lock(Key key)` Invoke `lock(Key, long)` with the supplied key and a default timeout value of 60000L milliseconds.
`void`	`lock(Key lockKey, long timeout)` Within a transaction, enforces a constraint that no other concurrent transaction also successfully locks the same key.
`boolean`	`next()` Traverses to the next logical sibling key value.
`boolean`	`next(boolean deep)` Traverses to the next key with control over depth.
`boolean`	`next(KeyFilter filter)` Traverses to the next key value within the subset of all keys defined by the supplied KeyFilter.
`boolean`	`previous()` Traverses to the previous logical sibling key value.
`boolean`	`previous(boolean deep)` Traverses to the previous key with control over depth.
`boolean`	`previous(KeyFilter filter)` Traverses to the previous key value within the subset of all keys defined by the supplied KeyFilter.
`boolean`	`remove()` Remove a single key/value pair from the this `Exchange`'s `Tree`.
`boolean`	`remove(Key.Direction direction)` Depending on the value of the selection parameter, remove the record associated with the current key, its logical children, or both.
`boolean`	`removeAll()` Remove all keys in this `Exchange`'s `Tree`.
`boolean`	`removeKeyRange(Key key1, Key key2)` Removes all records with keys falling between `key1` and `key2`, left-inclusive.
`void`	`removeTree()` Remove the entire `Tree` that this `Exchange` is based on.
`Exchange`	`reset()` Delegate to `Key.reset()` on the associated `Key` object.
`void`	`setAppCache(Object appCache)` Store an Object with this Exchange for the convenience of an application.
`Exchange`	`setDepth(int depth)` Delegate to `Key.setDepth(int)` on the associated `Key` object.
`void`	`setJoinPolicy(JoinPolicy policy)`
`void`	`setMaximumValueSize(int size)` Modifies the maximum size to which the value backing buffer can grow and trims the current backing buffer to be no larger than the new maximum.
`void`	`setSplitPolicy(SplitPolicy policy)`
`void`	`setTimeoutMillis(long timeout)` Set the standard timeout for this `Exchange`.
`Exchange`	`store()` Insert the current `Key` and `Value` pair into this `Exchange`'s `Tree`.
`Exchange`	`to(boolean item)` Delegate to `Key.to(boolean)` on the associated `Key` object.
`Exchange`	`to(byte item)` Delegate to `Key.to(byte)` on the associated `Key` object.
`Exchange`	`to(char item)` Delegate to `Key.to(char)` on the associated `Key` object.
`Exchange`	`to(double item)` Delegate to `Key.to(double)` on the associated `Key` object.
`Exchange`	`to(float item)` Delegate to `Key.to(float)` on the associated `Key` object.
`Exchange`	`to(int item)` Delegate to `Key.to(int)` on the associated `Key` object.
`Exchange`	`to(long item)` Delegate to `Key.to(long)` on the associated `Key` object.
`Exchange`	`to(Object item)` Delegate to `Key.to(Object)` on the associated `Key` object.
`Exchange`	`to(short item)` Delegate to `Key.to(short)` on the associated `Key` object.
`String`	`toString()` Return a displayable String containing the volume name, tree name and current key state for this `Exchange`.
`boolean`	`traverse(Key.Direction direction, boolean deep)` Performs generalized tree traversal.
`boolean`	`traverse(Key.Direction direction, boolean deep, int minimumBytes)` Performs generalized tree traversal.
`boolean`	`traverse(Key.Direction direction, boolean deep, int minimumBytes, Exchange.TraverseVisitor visitor)` Performs generalized tree traversal using a `Exchange.TraverseVisitor`.
`boolean`	`traverse(Key.Direction direction, KeyFilter keyFilter, int minBytes)` Performs generalized tree traversal constrained by a supplied `KeyFilter`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Exchange
```
public Exchange(Persistit persistit,
                String volumeName,
                String treeName,
                boolean create)
         throws PersistitException
```
    Construct a new Exchange object to create and/or access the Tree specified by treeName within the Volume specified by volumeName. This constructor optionally creates a new Tree. If the create parameter is false and a Tree by the specified name does not exist, this constructor throws a TreeNotFoundException.
    
    The volumeNameVolume. The name matches if either (a) the Volume has an optional alias that is equal to the supplied name, or (b) if the supplied name matches a substring of the Volume's pathname. If there is not unique match for the name you supply, this method throws a VolumeNotFoundException.
    
    Parameters:
    
    volumeName - The volume name that either matches the alias or a partially matches the pathname of exactly one open Volume.
    
    treeName - The tree name
    
    create - true to create a new Tree if one by the specified name does not already exist.
    
    Throws:
    
    PersistitException
  - Exchange
```
public Exchange(Persistit persistit,
                Volume volume,
                String treeName,
                boolean create)
         throws PersistitException
```
    Construct a new Exchange object to create and/or access the Tree specified by treeName within the specified Volume. This constructor optionally creates a new Tree. If the create parameter is false and a Tree by the specified name does not exist, this constructor throws a TreeNotFoundException.
    
    Parameters:
    
    volume - The Volume
    
    treeName - The tree name
    
    create - true to create a new Tree if one by the specified name does not already exist.
    
    Throws:
    
    PersistitException
  - Exchange
```
public Exchange(Exchange exchange)
```
    Construct a new Exchange to access the same Volume and Tree as the supplied Exchange. The states of the supplied Exchange's Key and Value objects are copied to new the Key and new Value associated with this Exchange so that operations on the two Exchanges initially behave identically.
    
    Parameters:
    
    exchange - The Exchange to copy from.
  - Exchange
```
public Exchange(Tree tree)
```
    Construct a new Exchange to access the specified Tree.
    
    Parameters:
    
    tree - The Tree to access.
    
    Throws:
    
    BufferSizeUnavailableException
- Method Detail
  - initCache
```
public void initCache()
```
    Drop all cached optimization information
  - reset
```
public Exchange reset()
```
    Delegate to Key.reset() on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - clear
```
public Exchange clear()
```
    Delegate to Key.clear() on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - setDepth
```
public Exchange setDepth(int depth)
```
    Delegate to Key.setDepth(int) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - cut
```
public Exchange cut(int level)
```
    Delegate to Key.cut(int) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - cut
```
public Exchange cut()
```
    Delegate to Key.cut() on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(boolean item)
```
    Delegate to Key.append(boolean) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(byte item)
```
    Delegate to Key.append(byte) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(short item)
```
    Delegate to Key.append(short) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(char item)
```
    Delegate to Key.append(char) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(int item)
```
    Delegate to Key.append(int) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(long item)
```
    Delegate to Key.append(long) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(float item)
```
    Delegate to Key.append(float) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(double item)
```
    Delegate to Key.append(double) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - append
```
public Exchange append(Object item)
```
    Delegate to Key.append(Object) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(boolean item)
```
    Delegate to Key.to(boolean) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(byte item)
```
    Delegate to Key.to(byte) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(short item)
```
    Delegate to Key.to(short) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(char item)
```
    Delegate to Key.to(char) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(int item)
```
    Delegate to Key.to(int) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(long item)
```
    Delegate to Key.to(long) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(float item)
```
    Delegate to Key.to(float) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(double item)
```
    Delegate to Key.to(double) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - to
```
public Exchange to(Object item)
```
    Delegate to Key.to(Object) on the associated Key object.
    
    Returns:
    
    This Exchange to permit method call chaining.
  - getKey
```
public Key getKey()
```
    Return the Key associated with this Exchange.
    
    Specified by:
    
    getKey in interface ReadOnlyExchange
    
    Returns:
    
    This Key.
  - getValue
```
public Value getValue()
```
    Return the Value associated with this Exchange.
    
    Specified by:
    
    getValue in interface ReadOnlyExchange
    
    Returns:
    
    The Value.
  - getVolume
```
public Volume getVolume()
```
    Return the Volume containing the data accessed by this Exchange.
    
    Specified by:
    
    getVolume in interface ReadOnlyExchange
    
    Returns:
    
    The Volume.
  - getTree
```
public Tree getTree()
```
    Return the Tree on which this Exchange operates.
    
    Specified by:
    
    getTree in interface ReadOnlyExchange
    
    Returns:
    
    The Tree
  - getPersistitInstance
```
public Persistit getPersistitInstance()
```
    Return the Persistit instance from which this Exchange was created.
    
    Specified by:
    
    getPersistitInstance in interface ReadOnlyExchange
    
    Returns:
    
    The Persistit instance.
  - getChangeCount
```
public long getChangeCount()
```
    Return the count of structural changes committed to the Tree on which this Exchange operates. This count includes changes committed by all Threads, including the current one. A structural change is one in which at least one key is inserted or deleted. Replacement of an existing value is not counted.
    
    Specified by:
    
    getChangeCount in interface ReadOnlyExchange
    
    Returns:
    
    The change count
  - toString
```
public String toString()
```
    Return a displayable String containing the volume name, tree name and current key state for this Exchange.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    The displayable String
  - traverse
```
public boolean traverse(Key.Direction direction,
                        boolean deep)
                 throws PersistitException
```
    Performs generalized tree traversal. The direction value indicates whether to traverse forward or backward in collation sequence, whether to descend to child nodes, and whether the key being sought must be strictly greater than or less then the supplied key.
    
    The direction value must be one of:
    
    Key.GT:
    
    Find the next key that is strictly greater than the supplied key. If there is none, return false.
    
    Key.GTEQ:
    
    If the supplied key exists in the database, return that key; otherwise find the next greater key and return it.
    
    Key.EQ:
    
    Return true iff the specified key exists in the database. Does not update the Key.
    
    Key.LT:
    
    Find the next key that is strictly less than the supplied key. If there is none, return false.
    
    Key.LTEQ:
    
    If the supplied key exists in the database, return that key; otherwise find the next smaller key and return it.
    
    Parameters:
    
    direction - One of Key.GT, Key.GTEQ, Key.EQ, Key.LT or Key.LTEQ.
    
    deep - Determines whether the result should represent the next (or previous) physical key in the Tree or should be restricted to just the logical siblings of the current key. (See Logical Key Children and Siblings).
    
    Returns:
    
    true if there is a key to traverse to, else false.
    
    Throws:
    
    PersistitException
  - traverse
```
public boolean traverse(Key.Direction direction,
                        boolean deep,
                        int minimumBytes)
                 throws PersistitException
```
    Performs generalized tree traversal. The direction value indicates whether to traverse forward or backward in collation sequence and whether the key being sought must be strictly greater than or less than the supplied key.
    
    This method normally modifies both the Key and Value fields of this Exchange: the Key is modified to reflect the key found through traversal, and the Value field is modified to contain the value associated with that key. However, this behavior can be modified by the minimumBytes parameter. If minimumBytes is less than 0 then this method modifies neither the Key nor the Value field. If it is equal to zero then only the Key is modified.
    
    The direction value must be one of:
    
    Key.GT:
    
    Find the next key that is strictly greater than the supplied key. If there is none, return false.
    
    Key.GTEQ:
    
    If the supplied key exists in the database, return that key; otherwise find the next greater key and return it.
    
    Key.EQ:
    
    Return true iff the specified key exists in the database. Does not update the Key.
    
    Key.LT:
    
    Find the next key that is strictly less than the supplied key. If there is none, return false.
    
    Key.LTEQ:
    
    If the supplied key exists in the database, return that key; otherwise find the next smaller key and return it.
    
    Parameters:
    
    direction - One of Key.GT, Key.GTEQ, Key.EQ, Key.LT or Key.LTEQ.
    
    deep - Determines whether the result should represent the next (or previous) physical key in the Tree or should be restricted to just the logical siblings of the current key. (See Logical Key Children and Siblings).
    
    minimumBytes - The minimum number of bytes to fetch. See fetch(int).
    
    Returns:
    
    true if there is a key to traverse to, else false.
    
    Throws:
    
    PersistitException
  - traverse
```
public boolean traverse(Key.Direction direction,
                        boolean deep,
                        int minimumBytes,
                        Exchange.TraverseVisitor visitor)
                 throws PersistitException
```
    Performs generalized tree traversal using a Exchange.TraverseVisitor. The direction value indicates whether to traverse forward or backward in collation sequence and whether the key being sought must be strictly greater than or less than the supplied key.
    
    Unlike traverse(Key.Direction, boolean, int), this method does not return each time a new key is encountered in the traversal. Instead, the Exchange.TraverseVisitor.visit(ReadOnlyExchange) method is called once for each key. This method avoids performing initial verification of the key value and usually avoids locking a Buffer for every record returned. It may offer better performance in circumstances where a long sequence of keys is being examined. Note that ReadOnlyExchange is an interface implemented by this class which supplies the subset of methods that may be used safely within the visitor.
    
    During the call the Buffer containing the key is locked with a non-exclusive claim, and any thread attempting to update records in the same Buffer will block. Therefore the visit method must be written carefully. See Exchange.TraverseVisitor.visit(ReadOnlyExchange) for guidelines.
    
    This method normally modifies both the Key and Value fields of this Exchange: the Key is modified to reflect the key found through traversal, and the Value field is modified to contain the value associated with that key. However, this behavior can be modified by the minimumBytes parameter. If minimumBytes is less than or equal to zero then only the Key is modified. If it is greater than zero, then the traverse method may choose to populate only the specified number of bytes of the Value.
    
    The direction value must be one of:
    
    Key.GT:
    
    Find the next key that is strictly greater than the supplied key. If there is none, return false.
    
    Key.GTEQ:
    
    If the supplied key exists in the database, return that key; otherwise find the next greater key and return it.
    
    Key.EQ:
    
    Return true iff the specified key exists in the database. Does not update the Key.
    
    Key.LT:
    
    Find the next key that is strictly less than the supplied key. If there is none, return false.
    
    Key.LTEQ:
    
    If the supplied key exists in the database, return that key; otherwise find the next smaller key and return it.
    
    Parameters:
    
    direction - One of Key.GT, Key.GTEQ, Key.EQ, Key.LT or Key.LTEQ.
    
    deep - Determines whether the result should represent the next (or previous) physical key in the Tree or should be restricted to just the logical siblings of the current key. (See Logical Key Children and Siblings).
    
    minimumBytes - The minimum number of bytes to fetch. See fetch(int).
    
    visitor - The application-supplied TraverseVisitor.
    
    Returns:
    
    true if additional keys remaining in the traversal set, or false to indicate that keys are exhausted.
    
    Throws:
    
    PersistitException
  - traverse
```
public boolean traverse(Key.Direction direction,
                        KeyFilter keyFilter,
                        int minBytes)
                 throws PersistitException
```
    Performs generalized tree traversal constrained by a supplied KeyFilter. The direction value indicates whether to traverse forward or backward in collation sequence, and whether the key being sought must be strictly greater than or less than the supplied key.
    
    The direction value must be one of:
    
    Key.GT:
    
    Find the next key that is strictly greater than the supplied key. If there is none, return false.
    
    Key.GTEQ:
    
    If the supplied key exists in the database, return that key; otherwise find the next greater key and return it.
    
    Key.EQ:
    
    Return true if the specified key exists in the database. Does not update the Key.
    
    Key.LT:
    
    Find the next key that is strictly less than the supplied key. If there is none, return false.
    
    Key.LTEQ:
    
    If the supplied key exists in the database, return that key; otherwise find the next smaller key and return it.
    
    Parameters:
    
    direction - One of Key.GT, Key.GTEQ, Key.EQ, Key.LT or Key.LTEQ.
    
    keyFilter - A KeyFilter that constrains the keys returned by this operation.
    
    minBytes - The minimum number of bytes to fetch. See fetch(int). If minBytes is less than or equal to 0 then this method does not update the Key and Value fields of the Exchange.
    
    Returns:
    
    true if there is a key to traverse to, else null.
    
    Throws:
    
    PersistitException
  - next
```
public boolean next()
             throws PersistitException
```
    Traverses to the next logical sibling key value. Equivalent to traverse(Key.GT, false).
    
    Returns:
    
    true if there is a key to traverse to, else null.
    
    Throws:
    
    PersistitException
  - previous
```
public boolean previous()
                 throws PersistitException
```
    Traverses to the previous logical sibling key value. Equivalent to traverse(Key.LT, false).
    
    Returns:
    
    true if there is a key to traverse to, else null.
    
    Throws:
    
    PersistitException
  - next
```
public boolean next(boolean deep)
             throws PersistitException
```
    Traverses to the next key with control over depth. Equivalent to traverse(Key.GT, deep).
    
    Parameters:
    
    deep - Determines whether the result should represent the next (or previous) physical key in the Tree or should be restricted to just the logical siblings of the current key. (See Logical Key Children and Siblings).
    
    Returns:
    
    true if there is a key to traverse to, else null.
    
    Throws:
    
    PersistitException
  - previous
```
public boolean previous(boolean deep)
                 throws PersistitException
```
    Traverses to the previous key with control over depth. Equivalent to traverse(Key.LT, deep).
    
    Parameters:
    
    deep - Determines whether the result should represent the next (or previous) physical key in the Tree or should be restricted to just the logical siblings of the current key. (See Logical Key Children and Siblings).
    
    Returns:
    
    true if there is a key to traverse to, else null.
    
    Throws:
    
    PersistitException
  - next
```
public boolean next(KeyFilter filter)
             throws PersistitException
```
    Traverses to the next key value within the subset of all keys defined by the supplied KeyFilter. Whether logical children of the current key value are included in the result is determined by the KeyFilter.
    
    Returns:
    
    true if there is a key to traverse to, else null.
    
    Throws:
    
    PersistitException
  - previous
```
public boolean previous(KeyFilter filter)
                 throws PersistitException
```
    Traverses to the previous key value within the subset of all keys defined by the supplied KeyFilter. Whether logical children of the current key value are included in the result is determined by the KeyFilter.
    
    Returns:
    
    true if there is a key to traverse to, else null.
    
    Throws:
    
    PersistitException
  - hasNext
```
public boolean hasNext()
                throws PersistitException
```
    Determines whether the current key has a logical sibling successor, without changing the state of Key or Value. This method is equivalent to next() except that no state is changed.
    
    Returns:
    
    true if the key has a successor
    
    Throws:
    
    PersistitException
  - hasNext
```
public boolean hasNext(KeyFilter filter)
                throws PersistitException
```
    Determines whether the current key has a successor within the subset of all keys defined by a KeyFilter. This method does not change the state of Key or Value.
    
    Returns:
    
    true if the key has a successor
    
    Throws:
    
    PersistitException
  - hasNext
```
public boolean hasNext(boolean deep)
                throws PersistitException
```
    Determines whether the current key has a logical sibling successor, without changing the state of Key or Value. This method is equivalent to next(boolean) except that no state is changed.
    
    Parameters:
    
    deep - Determines whether the predecessor may be of any logical depth (true, or must be a restricted logical siblings ( false) of the current key. (See Logical Key Children and Siblings).
    
    Returns:
    
    true if the key has a successor
    
    Throws:
    
    PersistitException
  - hasPrevious
```
public boolean hasPrevious()
                    throws PersistitException
```
    Determines whether the current key has a logical sibling predecessor, without changing the state of Key or Value. This method is equivalent to previous() except that no state is changed.
    
    Returns:
    
    true if the key has a predecessor
    
    Throws:
    
    PersistitException
  - hasPrevious
```
public boolean hasPrevious(boolean deep)
                    throws PersistitException
```
    Determines whether the current key has a logical sibling predecessor, without changing the state of Key or Value. This method is equivalent to previous(boolean) except that no state is changed.
    
    Parameters:
    
    deep - Determines whether the predecessor may be of any logical depth (true, or must be a restricted logical siblings ( false) of the current key. (See Logical Key Children and Siblings).
    
    Returns:
    
    true if the key has a predecessor
    
    Throws:
    
    PersistitException
  - hasPrevious
```
public boolean hasPrevious(KeyFilter filter)
                    throws PersistitException
```
    Determines whether the current key has a predecessor within the subset of all keys defined by a KeyFilter. This method does not change the state of Key or Value.
    
    Returns:
    
    true if the key has a successor
    
    Throws:
    
    PersistitException
  - isValueDefined
```
public boolean isValueDefined()
                       throws PersistitException
```
    Determines whether the current key has an associated value - that is, whether a fetch() operation would return a defined value - without actually changing the state of either the Key or the Value.
    
    Returns:
    
    true if the key has an associated value
    
    Throws:
    
    PersistitException
  - store
```
public Exchange store()
               throws PersistitException
```
    Insert the current Key and Value pair into this Exchange's Tree. If there already is a value associated with the current key, then replace it.
    
    Returns:
    
    This Exchange to permit method call chaining
    
    Throws:
    
    PersistitException
  - lock
```
public void lock()
          throws PersistitException
```
    Invoke lock(Key, long) with the current key and a default timeout value of 60000L milliseconds.
    
    Throws:
    
    PersistitException
  - lock
```
public void lock(Key key)
          throws PersistitException
```
    Invoke lock(Key, long) with the supplied key and a default timeout value of 60000L milliseconds.
    
    Parameters:
    
    key - The key to lock
    
    Throws:
    
    PersistitException
  - lock
```
public void lock(Key lockKey,
                 long timeout)
          throws PersistitException
```
    Within a transaction, enforces a constraint that no other concurrent transaction also successfully locks the same key. This method must run within the scope of an active transaction.
    
    This method is designed to help applications overcome problems with "write skew" which is a type of isolation anomaly permitted by Snapshot Isolation. See, for example, http://wikipedia.org/wiki/Snapshot_isolation for a concise explanation of Snapshot Isolation and the write skew anomaly.
    
    To use this facility an application specifies a key which may or may not be associated with an actual storage location, but which is designed to conflict with any other transaction that could participate in a write skew. Thus the operation serves as a way of ensuring serializable execution of transactions that could otherwise experience write skew. A key specified in this method is local to the Exchange's current Tree. Two concurrent threads locking the same key in different trees do not have a write-write dependency.
    
    This method does not actually use any locking mechanism; rather, it creates a write-write conflict with another transaction when both transactions are concurrent and when both transactions attempt to lock the same key. The result in that case is that one of the transactions receives a RollbackException. An application using this facility simply retries the transaction, at which point it is likely to successfully execute the call to lock().
    
    This method works by writing a short value associated with the provided key into a temporary volume (accessible through the Persistit.getLockVolume() method). The value is removed through the normal pruning process soon after the all potentially conflicting transactions have either rolled back or committed.
    
    All of these interactions are performed through the normal MVCC transaction mechanism. This method differs from the store() method only in that the Tree to which a value is written is located in a reserved temporary volume and is therefore normally not written to disk. The key is removed by pruning once there is are no longer any concurrent transactions that could conflict with it.
    
    As part of the normal MVCC process, if this method detects a potentially conflicting lock written by another active concurrent transaction, this transaction waits until the other transaction either commits or aborts, or until the timeout interval expires. To prevent an unbounded wait time this method accepts a timeout value in milliseconds. If the potentially conflicting transaction neither commits nor aborts during the timeout interval, this method throws a RollbackException. In the event this method attempts to enter a deadlock state with another current transaction; the potential deadlock is detected immediately and this method immediately throws a RollbackException.
    
    Parameters:
    
    lockKey - the source Key
    
    timeout - timeout interval in milliseconds, zero for default timeout
    
    Throws:
    
    PersistitException
    
    RollbackException - in the specific case that another concurrent transaction has also locked the same key
    
    IllegalStateException - if this Thread does not have an active transaction scope
    
    See Also:
    
    Transaction
  - fetchAndStore
```
public Exchange fetchAndStore()
                       throws PersistitException
```
    Fetches the value associated with the Key, then inserts or updates the value. Effectively this swaps the content of Value with the database record associated with the current key. It is equivalent to the code:
    Value tempValue = new Value(); exchange.fetch(tempValue); exchange.store(); tempValue.copyTo(exchange.getValue()); return exchange;
    except that this operation is performed atomically, without need for external synchronization.
    Returns:
    
    This Exchange to permit method call chaining
    
    Throws:
    
    PersistitException
  - fetch
```
public Exchange fetch()
               throws PersistitException
```
    Fetches the value associated with the current Key into the Exchange's Value. The Value object reflects the fetched state. If there is no value associated with the key then Value.isDefined() is false. Otherwise the value may be retrieved using Value.get() and other methods of Value .
    
    Returns:
    
    This Exchange to permit method call chaining
    
    Throws:
    
    PersistitException
  - fetch
```
public Exchange fetch(int minimumBytes)
               throws PersistitException
```
    Fetches or partially fetches the value associated with the current Key into the Exchange's Value. The Value object reflects the fetched state. If there is no value associated with the key then Value.isDefined() is false. Otherwise the value may be retrieved using Value.get() and other methods of Value.
    
    This method sets a lower bound on the number of bytes to be fetched. In particular, it may be useful to retrieve only a small fraction of a very long record such as the serialization of an image. Upon successful completion of this method, at least minimumBytes of the Value object will accurately reflect the value stored in the database. This might allow an application to determine whether to retrieve the rest of the value.
    
    Parameters:
    
    minimumBytes - specifies a length at which Persistit will truncate the returned value.
    
    Returns:
    
    This Exchange to permit method call chaining
    
    Throws:
    
    PersistitException
  - fetch
```
public Exchange fetch(Value value)
               throws PersistitException
```
    Fetches the value associated with the current Key into the supplied Value object (instead of the Exchange 's assigned Value). The Value object reflects the fetched state. If there is no value associated with the key then Value.isDefined() is false. Otherwise the value may be retrieved using Value.get() and other methods of Value.
    
    Parameters:
    
    value - the Value into which the database value should be fetched.
    
    Returns:
    
    This Exchange to permit method call chaining
    
    Throws:
    
    PersistitException
  - fetch
```
public Exchange fetch(Value value,
                      int minimumBytes)
               throws PersistitException
```
    Fetches or partially fetches the value associated with the current Key into the supplied Value object (instead of the Exchange's assigned Value). The Value object reflects the fetched state. If there is no value associated with the key then Value.isDefined() is false. Otherwise the value may be retrieved using Value.get() and other methods of Value.
    
    This method sets an lower bound on the number of bytes to be fetched. In particular, it may be useful to retrieve only a small fraction of a very long record such as the serialization of an image. Upon successful completion of this method, at least minimumBytes of the Value object will accurately reflect the value stored in the database. This might allow an application to determine whether to retrieve the rest of the value using the fetch() operation.
    
    Parameters:
    
    value - the Value into which the database value should be fetched.
    
    minimumBytes - specifies a length at which Persistit will truncate the returned value.
    
    Returns:
    
    This Exchange to permit method call chaining
    
    Throws:
    
    PersistitException
  - hasChildren
```
public boolean hasChildren()
                    throws PersistitException
```
    Return true if there is at least one key stored in this Exchange 's Tree that is a logical child of the current Key. A logical child is a key that can be formed by appending a value to the parent. (See Logical Key Children and Siblings).
    
    Returns:
    
    true if the current Key has logical children
    
    Throws:
    
    PersistitException
  - fetchAndRemove
```
public boolean fetchAndRemove()
                       throws PersistitException
```
    Remove a single key/value pair from this Exchange's Tree and return the removed value in the Exchange's Value. This method atomically fetches the former value then deletes it. If there was no value formerly associated with the key then Value becomes undefined - that is, the value of Value.isDefined() becomes false.
    
    Returns:
    
    true if there was a key/value pair to remove
    
    Throws:
    
    PersistitException
  - removeTree
```
public void removeTree()
                throws PersistitException
```
    Remove the entire Tree that this Exchange is based on. Subsequent to successful completion of this method, the Exchange will no longer be usable. Attempts to perform operations on it will result in an IllegalStateException.
    
    Throws:
    
    PersistitException
  - remove
```
public boolean remove()
               throws PersistitException
```
    Remove a single key/value pair from the this Exchange's Tree.
    
    Returns:
    
    true if there was a key/value pair to remove
    
    Throws:
    
    PersistitException
  - removeAll
```
public boolean removeAll()
                  throws PersistitException
```
    Remove all keys in this Exchange's Tree.
    
    Returns:
    
    true if there were key/value pairs removed
    
    Throws:
    
    PersistitException
  - remove
```
public boolean remove(Key.Direction direction)
               throws PersistitException
```
    Depending on the value of the selection parameter, remove the record associated with the current key, its logical children, or both.
    
    Following are valid values for selection:
    
    Key.EQ
    
    Remove the record associated with the current key if it exists.
    
    Key.GT
    
    Remove the records associated with logical children of the current key.
    
    Key.GTEQ
    
    Remove the record associated with the current key AND its logical children.
    
    Parameters:
    
    direction - One of Key.EQ, Key.GT, Key.GTEQ
    
    Returns:
    
    true if one or more records were actually removed, else false.
    
    Throws:
    
    PersistitException
  - removeKeyRange
```
public boolean removeKeyRange(Key key1,
                              Key key2)
                       throws PersistitException
```
    Removes all records with keys falling between key1 and key2, left-inclusive.
    
    Parameters:
    
    key1 - Start of the deletion range. No record with a key smaller than key1 will be removed. key1 may be empty, in which case all records having keys less than key2 will be removed.
    
    key2 - End of the deletion range. No record with a key greater than or equal to key2 will be removed. key2 may be empty, in which case all records having keys equal to or greater than key1 will be removed.
    
    Returns:
    
    true if one or more records were actually removed, else false.
    
    Throws:
    
    PersistitException - if there are any internal errors
    
    IllegalArgumentException - if key1 is equal to or greater than key2
  - getTransaction
```
public Transaction getTransaction()
```
    The transaction context for this Exchange. By default, this is the transaction context of the current thread, and by default, all Exchanges created by a thread share the same transaction context.
    
    Specified by:
    
    getTransaction in interface ReadOnlyExchange
    
    Returns:
    
    The Transaction context for this thread.
  - setSplitPolicy
```
public void setSplitPolicy(SplitPolicy policy)
```
  - setJoinPolicy
```
public void setJoinPolicy(JoinPolicy policy)
```
  - computeHistogram
```
public KeyHistogram computeHistogram(Key start,
                                     Key end,
                                     int sampleSize,
                                     int keyDepth,
                                     KeyFilter keyFilter,
                                     int requestedTreeDepth)
                              throws PersistitException
```
    Throws:
    
    PersistitException
  - setAppCache
```
public void setAppCache(Object appCache)
```
    Store an Object with this Exchange 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
  - getTimeoutMillis
```
public long getTimeoutMillis()
```
    Returns:
    
    The standard timeout setting in milliseconds for this Exchange
    
    See Also:
    
    setTimeoutMillis(long)
  - setTimeoutMillis
```
public void setTimeoutMillis(long timeout)
```
    Set the standard timeout for this Exchange. The timeout value represents an approximate upper bound on the wait time for various methods that wait for actions by other threads. For example, if a thread needs to read a value from a Buffer that is currently being updated by another thread, the read operation waits up to timeout milliseconds for the other thread to release the Buffer.
    
    The timeout value is advisory, and some operations may stall for a longer period of time than specified. Setting a timeout does not guarantee real-time behavior.
    
    The supplied value must be greater than or equal to zero. Zero means do not wait.
    
    Parameters:
    
    timeout - Standard timeout setting, in milliseconds, for operations that wait.
  - fetchBufferCopy
```
public Buffer fetchBufferCopy(int level)
                       throws PersistitException
```
    Returns a copy of either the data page or a page on the index path to the data page containing the current key. This method looks up the current key, then copies and returns the page at the specified tree level in a new Buffer. The resulting Buffer object is not part of the BufferPool and can simply be discarded when the caller is finished with it.
    
    Parameters:
    
    level - The tree level, starting at zero for the data page.
    
    Returns:
    
    copy of page on the key's index tree at that level.
    
    Throws:
    
    PersistitException
  - setMaximumValueSize
```
public void setMaximumValueSize(int size)
```
    Modifies the maximum size to which the value backing buffer can grow and trims the current backing buffer to be no larger than the new maximum.
    
    Parameters:
    
    size - The maximum size
    
    Throws:
    
    IllegalArgumentException - If the backing buffer is already larger than size, this method

Class Exchange

Exchange is Not Threadsafe

Exchange Pools

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Exchange

Exchange

Exchange

Exchange

Method Detail

initCache

reset

clear

setDepth

cut

cut

append

append

append

append

append

append

append

append

append

to

to

to

to

to

to

to

to

to

getKey

getValue

getVolume

getTree

getPersistitInstance

getChangeCount

toString

traverse

traverse

traverse

traverse

next

previous

next

previous

next

previous

hasNext

hasNext

hasNext

hasPrevious

hasPrevious

hasPrevious

isValueDefined

store

lock

lock

lock

fetchAndStore

fetch

fetch

fetch

fetch

hasChildren

fetchAndRemove

removeTree

remove

removeAll

remove

removeKeyRange

getTransaction

setSplitPolicy

setJoinPolicy