Examples of com.persistit.Key

• com.persistit.Key
  etf.org/rfc/rfc3629.txt">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 {@link com.persistit.encoding.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 {@link com.persistit.encoding.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 {@link #to(Object)} method is aconvenience 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 {@link Exchange} incorporate logic tohandle logical child keys in a special way:

  • The {@link Exchange#traverse(Key.Direction,boolean)} method, and itsvariants {@link Exchange#next(boolean)} and{@link Exchange#previous(boolean)} are capable of either deep orshallow 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 {@link Exchange#remove(Key.Direction)} method optionally removes thekey/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 {@link #toString} that creates a canonical String representation of a key.The {@link KeyParser#parseKey} 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 {@link #clear}, {@link #setDepth}, {@link #cut}, {@link #append(boolean)}, {@link #append(byte)}, {@link #append(short)} ... {@link #append(Object)}, {@link #to(boolean)}, {@link #to(byte)} {@link #to(short)} ... {@link #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 {@link #reset}, {@link #indexTo}, {@link #decodeBoolean}, {@link #decodeByte}, {@link #decodeShort} ...{@link #decode}. These methods do not modify the value represented by the key. Each decodeTTTT method returns a value of type TTTT. The {@link #decode} method returns a value of typeObject. 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[]  {@link #getEncodedBytes}int  {@link #getEncodedSize}void  {@link #setEncodedSize(int)}

  @version 1.0

Related Classes of com.persistit.Key