com.persistit

Class Key

java.lang.Object

com.persistit.Key

All Implemented Interfaces:

Comparable<Object>

public final class Key
extends Object
implements Comparable<Object>

Encapsulates the key used in storing, fetching or deleting a key/value pair from a Persistit™ database. A Key's state is represented by an array of bytes that are used to physically locate records in a Tree. The architectural maximum length of this byte array is 2,047 bytes. Thus a Key may be used to represent a significant, but not unlimited amount of information. Applications may use the Low-Level API methods to access and modify the key's backing byte array directly. However, Key provides a recommended higher-level API that simplifies encoding and decoding Java values.

Key Ordering

Within a Tree, keys are ordered in lexicographic order, by unsigned byte value. Thus keys encoded physically as shown will be stored in the following order:

   1st: {0x01, 0x01}
   2nd: {0x01, 0x01, 0x02, 0x01}
   3rd: {0x01, 0x01, 0x03, 0x01}
   4th: {0x01, 0x01, 0x03, 0x02}
   4th: {0x01, 0x02, 0x01}
   6th: {0x01, 0x02, 0x01, 0x01}
   7th: {0x01, 0x02, 0x04, 0xE3}
   8th: {0xF7, 0x03}
   9th: {0xF9}
 

The ordering is important because it governs the order in which the Exchange.traverse(com.persistit.Key.Direction, boolean) operations visit records, and the set of keys/value pairs that will be removed by the range Exchange.remove() operations. Key ordering also affects the physical proxmitity of items in the Tree's on-disk representation, which can affect performance.

Key provides methods to encode and decode logical values into and from the backing byte array. For example, the append(int) method encodes an int into the key in such a way that the natural ordering of integer values is preserved; that is, for integers u and v if u > v then the key encoded from u always follows that encoded from v in lexicographic order. The append method is overloaded to support each primitive Java type and Object. The ordering of key values within each primitive type follows the natural ordering for that type (see String Encoding for information on collation of Strings).

There is also an implicit ordering between different encoded types. The ordering of key values with differing types is as follows:

  BEFORE < null < boolean < byte < short < 
  char < int < long < float < double < 
  java.math.BigInteger < java.math.BigDecimal < 
  byte[] < java.lang.String < java.util.Date < 
  custom-encoded types < AFTER
 

(Note: BEFORE and AFTER are special pseudo-values that allow traversal from the first and last keys in a tree.)

Equivalence of Wrapped and Primitive Types

By default Key encodes objects of type Boolean, Byte, Short, Character, Integer, Long, Float and Double exactly the same as their primitive counterparts. Thus the decode() method, which returns an Object, can be used uniformly to decode values that were appended as either primitives or their wrapped equivalents.

String Encoding

By default Strings are encoded in a modified UTF-8 format. This encoding preserves alphabetic ordering of all 7-bit ASCII strings. Character codes above 128 are translated into two- or three-byte sequences according to the UTF-8 specification. The protocol is modified for the NUL character (code 0), because encoded key values are terminated by NUL. Persistit encodes a NUL embedded within a String with the two-byte sequence (0x01, 0x20), and encodes SOH (code 1) with the sequence (0x01, 0x21).

The default string-encoding algorithm does not support localized collation. TODO - add collation information here - TODO

Object Encoding

Persistit offers built-in support for encoding and decoding of a few commonly used Object types. These include:

      java.lang.String
      java.math.BigInteger
      java.math.BigDecimal
      java.util.Date
      byte[]
 

(Note that for byte array, a zero-valued bytes are converted to two-byte sequences, as described above for strings.)

The default encoding for these types, plus any additional Object types that are required to be used as key values, can be overridden by a custom KeyCoder. For consistency, the application should register all custom KeyCoder objects immediately after initializing Persistit, for example:

      Persistit.initialize();
      KeyCoder coder = new MyKeyCoder();
      Persistit.getInstance().getCoderManager()
          .registerKeyCoder(MyClass.class, coder);
 

All overridden object types sort after all other value types. Ordering among various custom types is determined by the custom encoding algorithm's implementation. See CoderManager for details.

Key Segments

An application may append multiple values to a Key, each of which is called a key segment. Applications use multiple segments to form concatenated keys. A concatenated key uniquely identifies a particular record by a combination of data values rather than one simple value. The number of segments in a Persistit concatenated key is bounded only by the architectural limitation on the length of the underlying byte array.

Each key segment is encoded as a sequence of non-zero bytes. Segments are separated by zero-valued bytes. A Key encodes strings, byte arrays, and all other data types that might naturally contain a zero- valued byte by inserting escape sequences in place of the zero values. Specifically, NUL (character code 0) in a string, or a zero in a byte array element is replaced by the two-byte sequence (0x01, 0x20). An SOH (character code 1) or a one in a byte array element is replaced by the two-byte sequence (0x01, 0x021). This scheme is handled automatically, and only those applications that manipulate the raw byte buffer using the low-level API need to be aware of it. This encoding ensures that the key orderering preserves the natural ordering of the underlying values. For example, the encoded forms of the two string "AB" and "ABC" are (0x80, 0x41, 0x42, 0x00) and (0x80, 0x41, 0x42, 0x43, 0x00), respectively. The two encodings differ in the third byte (the zero that terminates the shorter string) which correctly causes the shorter string to collate before the longer one.

Segments fall naturally into the ordering scheme. If two keys are different, then the first segment that differs between the two keys controls their ordering. For example, the code fragment

      key1.clear().append(1).append(1);
      key2.clear().append(1).append(2);
      key3.clear().append(2).append(1);
      key4.clear().append(2).append(1).append(0);
 

sets the four keys so that their ordering sequence is key1 < key2 < key3 < key4.

Logical Key Children and Siblings

The ability to append multiple key segments to a Key supports a method of grouping records logically by hierarchical key values. Much as a paper filing system uses cabinets, drawers, and folders to organize documents, segmented keys can be used to impose a hierarchical organization on data. For example, the key for a purchase order record might have a single segment representing the purchase order number. The purchase order's subsidiary line items might then be stored with keys that are logical children of the purchase order number, as suggested in this code snippet:

  PurchaseOrderSummary poSummary = ...
  List poLineItems = ...
  ...
  exchange.getValue().put(poSummary)
  exchange.clear().append(poSummary.getPurchaseOrderNumber()).store();
  ..
  exchange.append(Key.BEFORE);
  for (Iterator items = poLineItems.iterator();
       items.hasMore();)
  {
      LineItem item = (LineItem)lineItems.next();
      exchange.getValue().set(item);
      exchange.clear().to(item.getLineItemId()).store();
  }
  ...
 

This example would store the PurchaseOrderSummary under a key containing just the purchase order number, and then store each of the line items from the poLineItems List in a key containing the purchase order number and the line item number as separate segments. (The to(Object) method is a convenience method that replaces the final segment of the key with a new value.)

A key value is a logical child of another key value if it can be formed by appending one or more key segments to that other key. For example, the key value containing purchase order number and line item number is a logical child of the key for purchase order summary, which reflects the real-world concept that the line item is logically a child of the purchase order. A logical sibling of key value is one that can be formed by replacing the last segment of that key. For example, any two purchase order summary records are logical siblings. Any two line items are logical siblings only if they are logical children of key values formed from the same purchase order number.

Logical child relationships between keys are represented solely by the way in which keys are encoded and ordered within the physical tree; there is no direct physical representation of the logical hierarchy. However, because of the way keys are physically ordered within a Tree, logical child keys fall closer to their parents in key sort order than other keys, and are therefore more likely to be located on physical database pages that have already been read into the buffer pool.

Two families of methods of methods in Exchange incorporate logic to handle logical child keys in a special way:

• The Exchange.traverse(Key.Direction, boolean) method, and its variants Exchange.next(boolean) and Exchange.previous(boolean) are capable of either deep or shallow traversal. If deep traversal is requested then the result is the next (or previous) physical key in the Tree, regardless of whether it is a logical child key. However, if shallow traversal is requested, all logical children are skipped and the result is the next (or previous) logical sibling key value.
• The Exchange.remove(Key.Direction) method optionally removes the key/value pair specified by the current key value and/or the logical children of that key value. Continuing the purchase order example, the remove method can remove just the line items, just the purchase order summary, or both.

String Representation of a Key value

At times it is convenient to represent a Key value as a String, for example, to display it or enter it for editing. This class provides an implementation of toString() that creates a canonical String representation of a key. The KeyParser.parseKey(com.persistit.Key) method provides the inverse functionality, parsing a canonical string representation to create a key value.

The String representation is of the form:

  { segment,... }
 

where each segment value is one of the following:

• null
• false
• true
• a String literal, enclosed in quotes as in Java
• a numeric literal, interpreted as an int if no decimal point, otherwise as a double
• a cast segment value consisting of a parenthesized class name followed by a String representation of a value of that class.

For example, the following code excerpt

   Key key = new Key();
   key.append("xyz").append(1.23).append((long)456).append(new Date());
   System.out.println(key.toString());
 

would produce a string representation such as

 { "xyz", 1.23, (long) 456, (java.util.Date) 20040901114722.563 + 0500 }
 

All numeric types other than double and int use a cast segment representation so to permit exact translation to and from the String representation and the underlying internal key value. The canonical representation of a Date is designed to allow exact translation to and from the internal segment value while being somewhat legible.

Putting It All Together - How to Use the Key API

Applications do two fundamental things with Keys:

1. Applications construct key values when fetching, storing or removing key/value pairs.
2. Applications decode key values when traversing key/value pairs.

Methods used to construct key values are clear(), setDepth(int), cut(), append(boolean), append(byte), append(short) ... append(Object), to(boolean), to(byte) to(short) ... to(Object). These methods all modify the current state of the key. As a convenience, these methods all return the Key to support method call chaining.

Methods used to decode key values are reset(), indexTo(int), decodeBoolean(), decodeByte(), decodeShort() ... decode(). These methods do not modify the value represented by the key. Each decodeTTTT method returns a value of type TTTT. The decode() method returns a value of type Object. The reset and indexTo control which segment the next value will be decoded from.

Low-Level API

The low-level API allows an application to bypass the encoding and decoding operations described above and instead to operate directly on the byte array used as the physical B-Tree key. This might be appropriate for an existing application that has already implemented its own serialization mechanisms, for example, or to accommodate special key manipulation requirements. Applications should use these methods only if there is a compelling requirement.

The low-level API methods are:

      byte[] getEncodedBytes()
      int getEncodedSize()
      void setEncodedSize(int)
 

Version:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Key.Direction Enumeration of possible qualifiers for the traverse and remove methods.
static class	Key.EdgeValue Enumeration of special key segment values used to traverse from the first or last key.

Field Summary

Fields

Modifier and Type	Field and Description
static Key.EdgeValue	AFTER A Key segment value that collates after any actual key in a Tree.
static Key.EdgeValue	BEFORE A Key segment value that collates before any actual key in a Tree.
static Key.Direction[]	DIRECTIONS Used by journaling subsystem.
static Key.Direction	EQ
static Key.Direction	GT
static Key.Direction	GTEQ
static Key	LEFT_GUARD_KEY Key that always occupies the left edge of any Tree
static Key.Direction	LT
static Key.Direction	LTEQ
static int	MAX_KEY_LENGTH Absolute architectural maximum number of bytes in the encoding of a key.
static int	MAX_KEY_LENGTH_UPPER_BOUND
static String	PREFIX_BIG_DECIMAL Displayable prefix for BigDecimal values
static String	PREFIX_BIG_DECIMAL0
static String	PREFIX_BIG_INTEGER Displayable prefix for BigInteger values
static String	PREFIX_BIG_INTEGER0
static String	PREFIX_BOOLEAN Displayable prefix for boolean values (optional for input, implied and supressed on output)
static String	PREFIX_BYTE Displayable prefix for byte values
static String	PREFIX_BYTE_ARRAY Displayable prefix for byte array values
static String	PREFIX_CHAR Displayable prefix for char values
static String	PREFIX_DATE Displayable prefix for Date values
static String	PREFIX_DATE0
static String	PREFIX_DOUBLE Displayable prefix for double values (optional for input, implied and suppressed on output)
static String	PREFIX_FLOAT Displayable prefix for float values
static String	PREFIX_INT Displayable prefix for int values (optional for input, implied and supressed on output)
static String	PREFIX_LONG Displayable prefix for long values
static String	PREFIX_SHORT Displayable prefix for short values
static String	PREFIX_STRING Displayable prefix for String values (optional for input, implied and suppressed on output)
static String	PREFIX_STRING0
static Key	RIGHT_GUARD_KEY Key that always occupies the right edge of any Tree
static SimpleDateFormat	SDF The java.text.SimpleDateFormat used in formatting Date- valued keys in the decodeDisplayable(boolean) methods.

Constructor Summary

Constructors

Constructor and Description
Key(Key source) Constructs a Key which duplicates the state of the supplied Key.
Key(Persistit persistit) Construct a Key with a maximum length of 2047.
Key(Persistit persistit, int maxLength) Construct a Key with the specified maximum length.

Method Summary

Modifier and Type	Method and Description
Key	append(boolean v) Encodes and appends a boolean value to the key.
Key	append(byte v) Encodes and appends a byte value to the key.
Key	append(char v) Encodes and appends a char value to the key.
Key	append(double v) Encodes and appends a double value to the key.
Key	append(float v) Encodes and appends a float value to the key.
Key	append(int v) Encodes and appends an int value to the key.
Key	append(long v) Encodes and appends a long value to the key.
Key	append(Object object) Encodes and appends an Object value to the key.
Key	append(Object object, CoderContext context) Encodes and appends an Object value to the key.
Key	append(short v) Encodes and appends a short value to the key.
Key	appendByteArray(byte[] bytes, int offset, int size) Append a key segment that encodes a subarray from a supplied array of bytes.
Key	appendKeySegment(Key key) Append the next key segment of the supplied Key to this Key.
Key	clear() Sets the current location and size of this Key to zero, effectively removing any previously appended key segments.
int	compareKeyFragment(Key key, int fragmentStart, int fragmentSize) Compare a bounded subarray of the backing byte array for this Key with another Key.
int	compareKeySegment(Key key) Compare the next key segment of this key to the next key segment of the supplied Key.
int	compareTo(Object target) Returns a positive integer if this Key is larger than the supplied Key, a negative integer if it is smaller, or zero if they are equal.
void	copyTo(Key key) Copies all state information from this to the supplied Key.
Key	cut() Remove one key segment value from the end of this Key.
Key	cut(int count) Remove up to count key segment values from the end of this Key.
Object	decode() Decodes the next key segment as an Object, advances the index to the next key segment and returns the result.
Object	decode(Object target) Decodes the next key segment as an Object, advances the index to the next key segment and returns the result.
Object	decode(Object target, CoderContext context) Decodes the next key segment as an Object, advances the index to the next key segment and returns the result.
BigDecimal	decodeBigDecimal() Decodes the next key segment as a java.math.BigDecimal, advances the index to the next key segment and returns the result.
BigInteger	decodeBigInteger() Decodes the next key segment as a java.math.BigInteger, advances the index to the next key segment and returns the result.
boolean	decodeBoolean() Decodes the next key segment as a primitive boolean, advances the index to the next key segment and returns the result.
byte	decodeByte() Decodes the next key segment as a primitive byte, advances the index to the next key segment and returns the result.
byte[]	decodeByteArray() Decodes the next key segment as an array of bytes, advances the index to the next key segment and returns the result.
char	decodeChar() Decodes the next key segment as a primitive char, advances the index to the next key segment and returns the result.
Date	decodeDate() Decodes the next key segment as a java.util.Date, advances the index to the next key segment and returns the result.
String	decodeDisplayable(boolean quoted) Decodes the next key segment as a displayable String, advances the index to the next key segment and returns the result.
void	decodeDisplayable(boolean quoted, Appendable sb, CoderContext context) Decode the next key segment as a displayable String and advances the index to the next key segment.
double	decodeDouble() Decodess the next key segment as a primitive double, advance the index to the next key segment and returns the result.
float	decodeFloat() Decodes the next key segment as a primitive float, advances the index to the next key segment and returns the result.
int	decodeInt() Decodes the next key segment as a primitive int, advances the index to the next key segment and returns the result.
long	decodeLong() Decodes the next key segment as a primitive long, advances the index to the next key segment and returns the result.
short	decodeShort() Decodes the next key segment as a primitive short, advances the index to the next key segment and returns the result.
String	decodeString() Decodes the next key segment as a String, advances the index to the next key segment and returns the result.
Appendable	decodeString(Appendable sb) Decodes the next key segment as a String, appends the result to the supplied Appendable and advance the index to the next key segment.
Class<?>	decodeType() Decodes the Class of the next key segment.
boolean	equals(Object target) Compares this Key to another Key or KeyState.
int	firstUniqueByteIndex(Key key) Returns the index of the first encoded byte of this key that is different than the corresponding byte of the supplied Key.
int	firstUniqueSegmentDepth(Key key) Returns the depth of the first segment of this key that is different than the corresponding byte of the supplied Key.
int	getDepth() The number of key segments in this Key.
byte[]	getEncodedBytes() Returns the byte array that backs this Key.
int	getEncodedSize() Count of encoded bytes in the backing byte array.
long	getGeneration() An integer that is incremented every time the content of this Key changes.
int	getIndex() Returns the index from which the next invocation of decode() will decode a key segment.
int	getMaximumSize() Returns the maximum number of bytes permitting in the backing byte array for this Key.
int	hashCode() Computes a hash code for key value currently represented by this Key.
Key	indexTo(int depth) Sets the index to a specified depth.
boolean	isLeftEdge() Determine if this is the special Key value that is stored at the left edge of a Tree.
boolean	isNull() Determine if the current segment would return null if decode() were called.
boolean	isNull(boolean skipNull) Determine if the current segment would return null if decode() were called.
boolean	isRightEdge() Determine if this is the special Key value that is stored at the right edge of a Tree.
Key	reset() Sets the index to 0.
Key	setDepth(int depth) Truncates this Key to the specified depth.
void	setEncodedSize(int size) Sets the count of valid encoded bytes in the backing array for this Key.
Key	setIndex(int index) The index is the next position in the backing byte array from which a segment value will be decoded.
void	setMaximumSize(int size) Allocates a new backing byte array of the specified size.
Key	to(boolean v) Replaces the final key segment with the supplied boolean value.
Key	to(byte v) Replaces the final key segment with the supplied byte value.
Key	to(char v) Replaces the final key segment with the supplied char value.
Key	to(double v) Replaces the final key segment with the supplied double value.
Key	to(float v) Replaces the final key segment with the supplied float value.
Key	to(int v) Replaces the final key segment with the supplied int value.
Key	to(long v) Replaces the final key segment with the supplied long value.
Key	to(Object v) Replaces the final key segment with the supplied Object value.
Key	to(short v) Replaces the final key segment with the supplied short value.
String	toString() Returns a displayable String representation of the content of this Key

Methods inherited from class java.lang.Object

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

Field Detail

GT

public static final Key.Direction GT

GTEQ

public static final Key.Direction GTEQ

EQ

public static final Key.Direction EQ

LTEQ

public static final Key.Direction LTEQ

LT

public static final Key.Direction LT

LEFT_GUARD_KEY

public static final Key LEFT_GUARD_KEY

Key that always occupies the left edge of any Tree

RIGHT_GUARD_KEY

public static final Key RIGHT_GUARD_KEY

Key that always occupies the right edge of any Tree

MAX_KEY_LENGTH

public static final int MAX_KEY_LENGTH

Absolute architectural maximum number of bytes in the encoding of a key.

See Also:

Constant Field Values

MAX_KEY_LENGTH_UPPER_BOUND

public static final int MAX_KEY_LENGTH_UPPER_BOUND

See Also:

Constant Field Values

BEFORE

public static final Key.EdgeValue BEFORE

A Key segment value that collates before any actual key in a Tree. A Key may include an instance of this value as its final segment, but the store and fetch methods will not permit such a key as inputs. Use BEFORE to seed a traverse loop, as shown in this code fragment:

      key.to(BEFORE);
      while (exchange.next(key))
      {
          ... do actions
      }
 

AFTER

public static final Key.EdgeValue AFTER

A Key segment value that collates after any actual key in a Tree. A Key may include an instance of this value as its final segment, but the store and fetch methods will not permit such a key as inputs. Use AFTER to seed a traverse loop, as shown in this code fragment:

      key.to(AFTER);
      while (exchange.previous(key))
      {
          ... do actions
      }
 

SDF

public static final SimpleDateFormat SDF

The java.text.SimpleDateFormat used in formatting Date- valued keys in the decodeDisplayable(boolean) methods. This format also governs the conversion of dates for the toString method. This format provides millisecond resolution so that the precise stored representation of a date used as a key can be represented exactly, but readably, in the displayable version.

PREFIX_BOOLEAN

public static final String PREFIX_BOOLEAN

Displayable prefix for boolean values (optional for input, implied and supressed on output)

See Also:

Constant Field Values

PREFIX_BYTE

public static final String PREFIX_BYTE

Displayable prefix for byte values

See Also:

Constant Field Values

PREFIX_SHORT

public static final String PREFIX_SHORT

Displayable prefix for short values

See Also:

Constant Field Values

PREFIX_CHAR

public static final String PREFIX_CHAR

Displayable prefix for char values

See Also:

Constant Field Values

PREFIX_INT

public static final String PREFIX_INT

Displayable prefix for int values (optional for input, implied and supressed on output)

See Also:

Constant Field Values

PREFIX_LONG

public static final String PREFIX_LONG

Displayable prefix for long values

See Also:

Constant Field Values

PREFIX_FLOAT

public static final String PREFIX_FLOAT

Displayable prefix for float values

See Also:

Constant Field Values

PREFIX_DOUBLE

public static final String PREFIX_DOUBLE

Displayable prefix for double values (optional for input, implied and suppressed on output)

See Also:

Constant Field Values

PREFIX_STRING

public static final String PREFIX_STRING

Displayable prefix for String values (optional for input, implied and suppressed on output)

See Also:

Constant Field Values

PREFIX_STRING0

public static final String PREFIX_STRING0

See Also:

Constant Field Values

PREFIX_BIG_INTEGER

public static final String PREFIX_BIG_INTEGER

Displayable prefix for BigInteger values

See Also:

Constant Field Values

PREFIX_BIG_INTEGER0

public static final String PREFIX_BIG_INTEGER0

See Also:

Constant Field Values

PREFIX_BIG_DECIMAL

public static final String PREFIX_BIG_DECIMAL

Displayable prefix for BigDecimal values

See Also:

Constant Field Values

PREFIX_BIG_DECIMAL0

public static final String PREFIX_BIG_DECIMAL0

See Also:

Constant Field Values

PREFIX_DATE

public static final String PREFIX_DATE

Displayable prefix for Date values

See Also:

Constant Field Values

PREFIX_DATE0

public static final String PREFIX_DATE0

See Also:

Constant Field Values

PREFIX_BYTE_ARRAY

public static final String PREFIX_BYTE_ARRAY

Displayable prefix for byte array values

See Also:

Constant Field Values

DIRECTIONS

public static final Key.Direction[] DIRECTIONS

Used by journaling subsystem.

Constructor Detail

Key

public Key(Persistit persistit)

Construct a Key with a maximum length of 2047.

Parameters:

persistit -

Key

public Key(Persistit persistit,
           int maxLength)

Construct a Key with the specified maximum length. The specified length must be positive and less than or equal to 2047.

Parameters:

persistit - the Persistit instance

maxLength - The maximum length

Key

public Key(Key source)

Constructs a Key which duplicates the state of the supplied Key.

Parameters:

source - The Key to copy

Method Detail

copyTo

public void copyTo(Key key)

Copies all state information from this to the supplied Key. To create a new Key with state identical to this one, the preferred mechanism for use outside of this package is this the copy constructor:

     Key copiedKey = new Key(originalKey);
 

Parameters:

key - The Key to copy.

getMaximumSize

public int getMaximumSize()

Returns the maximum number of bytes permitting in the backing byte array for this Key.

Returns:

The maximum physical size

getEncodedBytes

public byte[] getEncodedBytes()

Returns the byte array that backs this Key. This method is part of the Low-Level API.

Returns:

The backing byte array

getEncodedSize

public int getEncodedSize()

Count of encoded bytes in the backing byte array. This method is part of the Low-Level API.

Returns:

The count

setEncodedSize

public void setEncodedSize(int size)

Sets the count of valid encoded bytes in the backing array for this Key. This method is part of the Low-Level API.

getDepth

public int getDepth()

The number of key segments in this Key. For example, the code

     key.clear().append("a").append("b").append("c");
 

results in a depth of 3.

Returns:

The number of key segments.

setIndex

public Key setIndex(int index)

The index is the next position in the backing byte array from which a segment value will be decoded. Applications should usually use the indexTo(int) method to set the index to a valid location.

Parameters:

index -

Returns:

This Key, to permit method call chaining

hashCode

public int hashCode()

Computes a hash code for key value currently represented by this Key. Changing the key will result in a different hashCode value. A KeyState holds an immutable copy of the state of a Key for use in maps. The hashCode and equals methods of Key and KeyState are compatible so that an application can perform a map lookup using a Key when the map's key is actually a KeyState.

Overrides:

hashCode in class Object

Returns:

The hash code

equals

public boolean equals(Object target)

Compares this Key to another Key or KeyState. A KeyState holds an immutable copy of the state of a Key for use in maps. The hashCode and equals methods of Key and KeyState are compatible so that an application can perform a map lookup using a Key when the map's key is actually a KeyState.

Overrides:

equals in class Object

Returns:

true if the target represents the same Key value

compareTo

public int compareTo(Object target)

Returns a positive integer if this Key is larger than the supplied Key, a negative integer if it is smaller, or zero if they are equal.

Specified by:

compareTo in interface Comparable<Object>

Returns:

The comparison result

compareKeyFragment

public int compareKeyFragment(Key key,
                              int fragmentStart,
                              int fragmentSize)

Compare a bounded subarray of the backing byte array for this Key with another Key. This method is intended for use within the library and is generally not useful for applications.

Parameters:

key - The Key to compare.

fragmentStart - Index of first byte to compare

fragmentSize - The number of bytes to compare.

Returns:

A positive value if this Key's fragment is larger than, a negative value if this Key's fragment is smaller than, or 0 if this Key's fragment is equal to the corresponding fragment of the supplied Key.

compareKeySegment

public int compareKeySegment(Key key)

Compare the next key segment of this key to the next key segment of the supplied Key. The next key segment is determined by the current index of the key and can be set using the setIndex(int) method. Returns a positive integer if the next segment of this Key is larger than the next segment of the supplied Key, a negative integer if it is smaller, or zero if the segments are equal.

Parameters:

key -

Returns:

the comparison result

firstUniqueByteIndex

public int firstUniqueByteIndex(Key key)

Returns the index of the first encoded byte of this key that is different than the corresponding byte of the supplied Key. If all bytes match, then returns the encoded length of the shorter key.

Parameters:

key - The code on which to count matching bytes

Returns:

The index of the first byte of this key that is unequal to the byte in the corresponding position of the supplied Key.

firstUniqueSegmentDepth

public int firstUniqueSegmentDepth(Key key)

Returns the depth of the first segment of this key that is different than the corresponding byte of the supplied Key. If all bytes match, then returns the depth of the shorter key.

Parameters:

key - The code on which to count matching bytes

Returns:

The depth of the first segment of this key that differs from that of the supplied Key.

clear

public Key clear()

Sets the current location and size of this Key to zero, effectively removing any previously appended key segments.

Returns:

This Key, to permit method call chaining

setMaximumSize

public void setMaximumSize(int size)

Allocates a new backing byte array of the specified size. This method is for specialized use cases in which it may be convenient to serialize long values into a Key for purposes other than storing them in a Tree. However, regardless of the size of the backing byte array, an encoded key value larger than the architectural maximum size of 2047 cannot be stored in a Tree.

The specified size must be between 0 and 4194304. As a side-effect, this method also calls the clear() method.

Parameters:

size -

Throws:

IllegalArgumentException - if the specified size is not valid.

setDepth

public Key setDepth(int depth)

Truncates this Key to the specified depth. If depth is 0 then this method is equivalent to clear(). If depth is positive, then this Key is truncated so that it has no more than depth key segments. If depth is negative, then up to -depth segments are removed from the end. For example,

     key.clear().append("a").append("b").append("c").setDepth(-1);
 

results in a key with two segment, "a" and "b".

Parameters:

depth - The depth, as defined above.

Returns:

This Key, to permit method call chaining

reset

public Key reset()

Sets the index to 0. (The index is the location within the backing byte array from which the next decode() operation will decode a segment value.) This method is equivalent to indexTo(0).

Returns:

This Key, to permit method call chaining

indexTo

public Key indexTo(int depth)

Sets the index to a specified depth. (The index is the location within the backing byte array from which the next decode() operation will decode a segment value.) If depth is 0 then this method is equivalent to reset(). If depth is positive, then the index is set to point to the depthth key segment. If depth is negative, then the index is set to point to a key segment -depth segments from the end. For example,

     key.clear().append("a").append("b").append("c");
     return key.indexTo(-1).decode();
 

returns "c".

Parameters:

depth - The depth, as defined above.

Returns:

This Key, to permit method call chaining

getIndex

public int getIndex()

Returns the index from which the next invocation of decode() will decode a key segment.

Returns:

The index

cut

public Key cut()

Remove one key segment value from the end of this Key. If the key is empty this method does nothing.

Returns:

This Key, to permit method call chaining

cut

public Key cut(int count)

Remove up to count key segment values from the end of this Key. For example, the code fragment

     key.clear();
     key.append("a").append("b").append("c");
     key.cut(2).append("d");
 

leaves a key with the just the segment values {"a","d"}.

Parameters:

count - The number of key segments to cut.

Returns:

This Key, to permit method call chaining

toString

public String toString()

Returns a displayable String representation of the content of this Key

Overrides:

toString in class Object

Returns:

A displayable String

append

public Key append(boolean v)

Encodes and appends a boolean value to the key.

Parameters:

v - The boolean value to append

Returns:

This Key, to permit method call chaining

append

public Key append(byte v)

Encodes and appends a byte value to the key.

Parameters:

v - The byte value to append

Returns:

This Key, to permit method call chaining

append

public Key append(short v)

Encodes and appends a short value to the key.

Parameters:

v - The short value to append

Returns:

This Key, to permit method call chaining

append

public Key append(char v)

Encodes and appends a char value to the key.

Parameters:

v - The char value to append

Returns:

This Key, to permit method call chaining

append

public Key append(int v)

Encodes and appends an int value to the key.

Parameters:

v - The int value to append

Returns:

This Key, to permit method call chaining

append

public Key append(long v)

Encodes and appends a long value to the key.

Parameters:

v - The long value to append

Returns:

This Key, to permit method call chaining

append

public Key append(float v)

Encodes and appends a float value to the key.

Parameters:

v - The float value to append

Returns:

This Key, to permit method call chaining

append

public Key append(double v)

Encodes and appends a double value to the key.

Parameters:

v - The double value to append

Returns:

This Key, to permit method call chaining

append

public Key append(Object object)

Encodes and appends an Object value to the key. Only objects of certain classes can be encoded in a Key (see Object Encoding for details). This method throws a ConversionException for unsupported types.

Parameters:

object - The object to append

Returns:

This Key, to permit method call chaining

Throws:

ConversionException - if the supplied object is not an implicitly supported type and does not have a KeyCoder.

append

public Key append(Object object,
                  CoderContext context)

Encodes and appends an Object value to the key. Only objects of certain classes can be encoded in a Key (see Object Encoding for details). This method throws a ConversionException for unsupported types.

Parameters:

object - The object to append

context - An application-specified value that may assist a KeyCoder. The context is passed to the KeyCoder.appendKeySegment(com.persistit.Key, java.lang.Object, com.persistit.encoding.CoderContext) method.

Returns:

This Key, to permit method call chaining

Throws:

ConversionException - if the supplied object is not an implicitly supported type and does not have a KeyCoder.

appendKeySegment

public Key appendKeySegment(Key key)

Append the next key segment of the supplied Key to this Key. The next key segment is determined by the current index of the key and can be set using the setIndex(int) method.

Parameters:

key -

to

public Key to(boolean v)

Replaces the final key segment with the supplied boolean value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(boolean).

Parameters:

v - The boolean value to append

Returns:

This Key, to permit method call chaining

to

public Key to(byte v)

Replaces the final key segment with the supplied byte value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(byte).

Parameters:

v - The byte value to append

Returns:

This Key, to permit method call chaining

to

public Key to(short v)

Replaces the final key segment with the supplied short value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(short).

Parameters:

v - The short value to append

Returns:

This Key, to permit method call chaining

to

public Key to(char v)

Replaces the final key segment with the supplied char value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(char).

Parameters:

v - The char value to append

Returns:

This Key, to permit method call chaining

to

public Key to(int v)

Replaces the final key segment with the supplied int value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(int).

Parameters:

v - The int value to append

Returns:

This Key, to permit method call chaining

to

public Key to(long v)

Replaces the final key segment with the supplied long value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(long).

Parameters:

v - The long value to append

Returns:

This Key, to permit method call chaining

to

public Key to(float v)

Replaces the final key segment with the supplied float value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(float).

Parameters:

v - The float value to append

Returns:

This Key, to permit method call chaining

to

public Key to(double v)

Replaces the final key segment with the supplied double value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(double).

Parameters:

v - The double value to append

Returns:

This Key, to permit method call chaining

to

public Key to(Object v)

Replaces the final key segment with the supplied Object value. If the key is currently empty, this method simply appends the value. This method is equivalent to invoking cut() and then append(Object). See append(Object) for restrictions on permissible Object values.

Parameters:

v - The Object value to append

Returns:

This Key, to permit method call chaining

decodeBoolean

public boolean decodeBoolean()

Decodes the next key segment as a primitive boolean, advances the index to the next key segment and returns the result.

Returns:

The boolean value

Throws:

ConversionException - if the next key segment value is not a boolean.

decodeByte

public byte decodeByte()

Decodes the next key segment as a primitive byte, advances the index to the next key segment and returns the result.

Returns:

The byte value

Throws:

ConversionException - if the next key segment value is not a byte.

decodeShort

public short decodeShort()

Decodes the next key segment as a primitive short, advances the index to the next key segment and returns the result.

Returns:

The short value

Throws:

ConversionException - if the next key segment value is not a short.

decodeChar

public char decodeChar()

Decodes the next key segment as a primitive char, advances the index to the next key segment and returns the result.

Returns:

The char value

Throws:

ConversionException - if the next key segment value is not a char.

decodeInt

public int decodeInt()

Decodes the next key segment as a primitive int, advances the index to the next key segment and returns the result.

Returns:

The int value

Throws:

ConversionException - if the next key segment value is not a int.

decodeLong

public long decodeLong()

Decodes the next key segment as a primitive long, advances the index to the next key segment and returns the result.

Returns:

The long value

Throws:

ConversionException - if the next key segment value is not a long.

decodeFloat

public float decodeFloat()

Decodes the next key segment as a primitive float, advances the index to the next key segment and returns the result.

Returns:

The float value

Throws:

ConversionException - if the next key segment value is not a float.

decodeDouble

public double decodeDouble()

Decodess the next key segment as a primitive double, advance the index to the next key segment and returns the result.

Returns:

The double value

Throws:

ConversionException - if the next key segment value is not a double.

decodeString

public String decodeString()

Decodes the next key segment as a String, advances the index to the next key segment and returns the result.

Returns:

The String value

Throws:

ConversionException - if the next key segment value is not a String.

decodeString

public Appendable decodeString(Appendable sb)

Decodes the next key segment as a String, appends the result to the supplied Appendable and advance the index to the next key segment.

Parameters:

sb - The Appendable

Returns:

The supplied Appendable to permit operation chaining.

Throws:

ConversionException - if the next key segment value is not a String.

decodeDate

public Date decodeDate()

Decodes the next key segment as a java.util.Date, advances the index to the next key segment and returns the result.

Returns:

The Date value

Throws:

ConversionException - if the next key segment value is not a Date.

decodeBigInteger

public BigInteger decodeBigInteger()

Decodes the next key segment as a java.math.BigInteger, advances the index to the next key segment and returns the result.

Returns:

The BigInteger value

Throws:

ConversionException - if the next key segment value is not a BigInteger.

decodeBigDecimal

public BigDecimal decodeBigDecimal()

Decodes the next key segment as a java.math.BigDecimal, advances the index to the next key segment and returns the result.

Returns:

The BigDecimal value

Throws:

ConversionException - if the next key segment value is not a BigDecimal.

decodeByteArray

public byte[] decodeByteArray()

Decodes the next key segment as an array of bytes, advances the index to the next key segment and returns the result.

Returns:

The boolean value

Throws:

ConversionException - if the next key segment value is not a boolean.

decode

public Object decode()

Decodes the next key segment as an Object, advances the index to the next key segment and returns the result.

Returns:

The Object value, or null if the encoded value is null.

Throws:

ConversionException - if the next key segment value is not a boolean.

decode

public Object decode(Object target)

Decodes the next key segment as an Object, advances the index to the next key segment and returns the result.

If the value encoded in this Value is null then this method returns null. Otherwise this method returns either (a) a new object instance, or (b) the target object. Specifically, if the supplied target is non-null, and if the class of the object encoded in the Value is supported by a registered KeyRenderer, then the target object will be returned after the KeyRenderer has populated its state. Otherwise the target object will be ignored and this method will return a newly created object instance.

Parameters:

target - A mutable object into which this method may attempt to decode the value

Returns:

An Object representing the key segment encoded in the Key, or null if the encoded value is null.

decode

public Object decode(Object target,
                     CoderContext context)

Decodes the next key segment as an Object, advances the index to the next key segment and returns the result.

If the value encoded in this Value is null then this method returns null. Otherwise this method returns either (a) a new object instance, or (b) the target object. Specifically, if the supplied target is non-null, and if the class of the object encoded in the Value is supported by a registered KeyRenderer, then the target object will be returned after the KeyRenderer has populated its state. Otherwise the target object will be ignored and this method will return a newly created object instance.

Parameters:

target - A mutable object into which this method may attempt to decode the value

context - An application-specified value that may assist a KeyCoder. The context is passed to the KeyCoder.decodeKeySegment(com.persistit.Key, java.lang.Class<?>, com.persistit.encoding.CoderContext) method.

Returns:

An Object representing the key segment encoded in the Key, or null if the encoded value is null.

decodeType

public Class<?> decodeType()

Decodes the Class of the next key segment.

Returns:

The Class of the next key segment

Throws:

ConversionException - if the encoded value is malformed.

decodeDisplayable

public String decodeDisplayable(boolean quoted)

Decodes the next key segment as a displayable String, advances the index to the next key segment and returns the result. This method is intended to generate a reasonably legible String representation for any type of key segment value.

Returns:

The boolean value

Throws:

ConversionException - if the next key segment value is not a boolean.

decodeDisplayable

public void decodeDisplayable(boolean quoted,
                              Appendable sb,
                              CoderContext context)

Decode the next key segment as a displayable String and advances the index to the next key segment. This method appends the decoded String value to the supplied StringBuilder. If quoted is true, and if the segment value is a String, then the String value is surrounded by quote (") characters, and backslashes are inserted into the display string to quote any embedded any backslash or quote characters. This method is intended to generate a human-readable, canonical String representation for any type of key segment value.

Parameters:

quoted - true if the resulting string is to be quoted.

sb - The StringBuilder to which the displayable string is to be appended.

Throws:

ConversionException - if the next key segment value is not a boolean.

getGeneration

public long getGeneration()

An integer that is incremented every time the content of this Key changes. If the generation number is unchanged after an operation this is a reliable indication that the Key's value did not change.

Returns:

The generation

isLeftEdge

public boolean isLeftEdge()

Determine if this is the special Key value that is stored at the left edge of a Tree. If so then there is no other Key before this one in the Tree.

Returns:

true if the content of this Key represents the special left edge key of a Tree

isRightEdge

public boolean isRightEdge()

Determine if this is the special Key value that is stored at the right edge of a Tree. If so then there is no other Key after this one in the Tree.

Returns:

true if the content of this Key represents the special right edge key of a Tree

isNull

public boolean isNull()

Determine if the current segment would return null if decode() were called. This is not only a fast test to perform but also allows for safe decoding of primitives, such as decodeInt(), without object creation.

Returns:

true if the current segment is null, false otherwise.

isNull

public boolean isNull(boolean skipNull)

Determine if the current segment would return null if decode() were called. As a side effect, if skipNull is true and the segment does encode a null value, then the index is advanced to the beginning of the next segment.

Parameters:

skipNull - whether to advance the index past a null segment value

Returns:

true if the current segment is null, false otherwise.

appendByteArray

public Key appendByteArray(byte[] bytes,
                           int offset,
                           int size)

Append a key segment that encodes a subarray from a supplied array of bytes. In the encoded form all NUL (0) and SOH (1) bytes are converted to escape sequences so that the entire array is recognized as a single key segment.

Parameters:

bytes - The byte array from which the key segment is created

offset - Offset of first byte of subarray

size - Size of subarray

Returns:

This Key, to permit method call chaining