oracle.kv
Class Key

java.lang.Object
  oracle.kv.Key

All Implemented Interfaces:

Comparable<Key>

public class Key
extends Object
implements Comparable<Key>

The Key in a Key/Value store.

A Key represents a path to a value in a hierarchical namespace. It consists of a sequence of string path component names, and each component name is used to navigate the next level down in the hierarchical namespace. The complete sequence of string components is called the Full Key Path.

The sequence of string components in a Full Key Path is divided into two groups or sub-sequences: The Major Key Path is the initial or beginning sequence and the Minor Key Path is the remaining or ending sequence. The Full Path is the concatenation of the Major and Minor Paths, in that order. The Major Path must have at least one component, while the Minor path may be empty (have zero components).

Each path component must be a non-null String. Empty (zero length) Strings are allowed, except that the first component of the major path must be a non-empty String.

Given a Key, finding the location of a Key/Value pair is a two step process:

1. The Major Path is used to locate the node on which the Key/Value pair can be found.
2. The Full Path is then used to locate the Key/Value pair within that node.

Therefore all Key/Value pairs with the same Major Path are clustered on the same node.

Keys which share a common Major Path are physically clustered by the KVStore and can be accessed efficiently via special multiple-operation APIs, e.g. multiGet. The APIs are efficient in two ways:

1. They permit the application to perform multiple-operations in single network round trip.
2. The individual operations (within a multiple-operation) are efficient since the common-prefix keys and their associated values are themselves physically clustered.

Multiple-operation APIs also support ACID transaction semantics. All the operations within a multiple-operations are executed within the scope of a single transaction.

Method Summary

int	compareTo(Key otherKey) Compares this Key with the specified Key for order.
static Key	createKey(List<String> majorPath) Creates a Key from a Major Path list; the Minor Path will be empty.
static Key	createKey(List<String> majorPath, List<String> minorPath) Creates a Key from a Major Path list and a Minor Path list.
static Key	createKey(List<String> majorPath, String minorComponent) Creates a Key from a Major Path list and a single component Minor Path.
static Key	createKey(String majorComponent) Creates a Key from a single component Major Path; the Minor Path will be empty.
static Key	createKey(String majorComponent, List<String> minorPath) Creates a Key from a single component Major Path and a Minor Path list.
static Key	createKey(String majorComponent, String minorComponent) Creates a Key from a single component Major Path and a single component Minor Path.
boolean	equals(Object other)
static Key	fromByteArray(byte[] keyBytes) Deserializes the given bytes that were returned earlier by toByteArray() and returns the resulting Key.
static Key	fromString(String pathString) Decodes a key path string and returns the resulting Key object.
List<String>	getFullPath() Returns the Full Path of the Key as new mutable list.
List<String>	getMajorPath() Returns the Major Path of the Key as an immutable list.
List<String>	getMinorPath() Returns the Minor Path of the Key as an immutable list.
int	hashCode()
boolean	isPrefix(Key otherKey) Returns true if this key is a prefix of the key supplied as the argument.
byte[]	toByteArray() Returns this Key as a serialized byte array, such that fromByteArray(byte[]) may be used to reconstitute the Key.
String	toString() Encodes the Key object and returns the resulting key path string, which may be used as a URI path or simply as a string identifier.

Methods inherited from class java.lang.Object

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

Method Detail

createKey

public static Key createKey(List<String> majorPath,
                            List<String> minorPath)

Creates a Key from a Major Path list and a Minor Path list.

WARNING: List instances passed as parameters are owned by the Key object after calling this method. To avoid unpredictable results, they must not be modified.

Parameters:

majorPath - may not be null or empty, and may not contain nulls.

minorPath - may be empty, but may not be null or contain nulls.

createKey

public static Key createKey(String majorComponent,
                            List<String> minorPath)

Creates a Key from a single component Major Path and a Minor Path list.

WARNING: List instances passed as parameters are owned by the Key object after calling this method. To avoid unpredictable results, they must not be modified.

Parameters:

majorComponent - may not be null.

minorPath - may be empty, but may not be null or contain nulls.

createKey

public static Key createKey(List<String> majorPath,
                            String minorComponent)

Creates a Key from a Major Path list and a single component Minor Path.

WARNING: List instances passed as parameters are owned by the Key object after calling this method. To avoid unpredictable results, they must not be modified.

Parameters:

majorPath - may not be null or empty, and may not contain nulls.

minorComponent - may not be null.

createKey

public static Key createKey(String majorComponent,
                            String minorComponent)

Creates a Key from a single component Major Path and a single component Minor Path.

Parameters:

majorComponent - may not be null.

minorComponent - may not be null.

createKey

public static Key createKey(List<String> majorPath)

Creates a Key from a Major Path list; the Minor Path will be empty.

WARNING: List instances passed as parameters are owned by the Key object after calling this method. To avoid unpredictable results, they must not be modified.

Parameters:

majorPath - may not be null or empty, and may not contain nulls.

createKey

public static Key createKey(String majorComponent)

Creates a Key from a single component Major Path; the Minor Path will be empty.

Parameters:

majorComponent - may not be null.

getFullPath

public List<String> getFullPath()

Returns the Full Path of the Key as new mutable list.

WARNING: The full path returned does not contain information about the division between the Major and Minor Paths. The user must take care to preserve this division when necessary.

getMajorPath

public List<String> getMajorPath()

Returns the Major Path of the Key as an immutable list.

getMinorPath

public List<String> getMinorPath()

Returns the Minor Path of the Key as an immutable list.

isPrefix

public boolean isPrefix(Key otherKey)

Returns true if this key is a prefix of the key supplied as the argument. That is, every component of this key is equal to the corresponding component (by position and whether it is in the Major or Minor Path) of the other key. Specifically:

• If the Minor Path of this Key is empty, this method returns true if the Major Path of this Key is a prefix of the Major Path of the other Key.
• If the Minor Path of this Key is non-empty, this method returns true if:
  • the Major Path of this Key equals the Major Path of the other Key, and
  • the the Minor Path of this Key is a prefix of the Minor Path of the other Key.

Parameters:

otherKey - the key being tested

compareTo

public int compareTo(Key otherKey)

Compares this Key with the specified Key for order.

The Major and Minor Paths are compared separately. The Major paths are compared first. If the Major Paths are unequal, then the result of their comparison is returned and the Minor Paths are not compared. If the Major Paths are equal, then the Minor Paths are compared and the result of their comparison is returned.

For each of the Major and Minor Paths, its components are compared as follows. First, for the number of components the paths have in common (the common prefix), the path components at each position are compared in sequence. If the components at one position are unequal, the result is determined by comparing the strings as if String.compareTo were called, and the result is returned. If all common components are equal, the path with less components is considered less than the other path with more components. If the paths have the same number of components and all components are equal, the paths are considered equal and zero is returned.

Specified by:

compareTo in interface Comparable<Key>

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Encodes the Key object and returns the resulting key path string, which may be used as a URI path or simply as a string identifier. The path string may be decoded, to recreate the Key object, using fromString(java.lang.String).

The key path string format is designed to work with URIs and URLs, and is intended to be used as a general purpose string identifier. The key path components are separated by slash (/) delimiters. A special slash-hyphen-slash delimiter (/-/) is used to separate the major and minor paths. Characters that are not allowed in a URI path are encoded using URI syntax (%XX where XX are hexadecimal digits). The string always begins with a leading slash to prevent it from begin treated as a URI relative path. Some examples are below.

1. /SingleComponentMajorPath
2. /MajorPathPart1/MajorPathPart2/-/MinorPathPart1/MinorPathPart2
3. /HasEncodedSlash:%2F,Zero:%00,AndSpace:%20

Example 1 demonstrates the simplest possible path. Note that a leading slash is always necessary.

Example 2 demonstrates the use of the /-/ separator between the major and minor paths. If a key happens to have a path component that is nothing but a hyphen, to distinguish it from that delimiter it is encoded as %2D. For example: /major/%2d/path/-/minor/%2d/path.

Example 3 demonstrates encoding of characters that are not allowed in a path component. For URI compatibility, characters that are encoded are the ASCII space and other Unicode separators (defined by Character.isSpaceChar(char)), the ASCII and Unicode control characters (defined by Character.isISOControl(char)), and the following 15 ASCII characters: (" # % / < > ? [ \ ] ^ ` { | }). The hyphen (-) is also encoded when it is the only character in the path component, as described above.

When using the Key path string in a URI, there are two special considerations.

• Although any Unicode character may be used in a Key path component and characters will be encoded as necessary by this method for URI compatibility, in practice it may be problematic to include control characters because web user agents, proxies, etc, may not be tolerant of all characters. Although it will be encoded, embedding a slash in a path component may also be problematic. It is the responsibility of the application to use characters that are compatible with other software that processes the URI.
• When using the URI class, be aware that this class has no constructor where the encoded (raw) path can be specified as a separate parameter. The path parameter of the URI constructor must not contain encoded characters, and therefore slashes may not be embedded in a path component. To create a URI from a Key object, the recommended approach is to create the URI with a predefined path token and then replace the token with the raw path derived from the Key, as shown below.

     Key key = ...;
     String rawPath = key.toString();
     URI uri = new URI(..., "/PATH_TOKEN", ...);
     uri = new URI(uri.toString().replace("/PATH_TOKEN", rawPath));

  The URL class, on the other hand, does not suffer from this limitation. The file parameter of the URL constructor is the raw path, so the Key path string may be passed directly as the file parameter.

Overrides:

toString in class Object

Returns:

the key path string.

fromString

public static Key fromString(String pathString)

Decodes a key path string and returns the resulting Key object. The path string should normally be created using toString(). See toString() for more information about the path string format.

Parameters:

pathString - a non-null path string, which should normally be created using toString().

Returns:

the resulting Key object.

Throws:

IllegalArgumentException - if pathString does not begin with a slash or contains invalid characters, for example, an invalid encoding sequence.

toByteArray

public byte[] toByteArray()

Returns this Key as a serialized byte array, such that fromByteArray(byte[]) may be used to reconstitute the Key.

The number of bytes in the returned array is the number of UTF-8 bytes needed to represent the component strings, plus the number of components, minus one.

fromByteArray

public static Key fromByteArray(byte[] keyBytes)

Deserializes the given bytes that were returned earlier by toByteArray() and returns the resulting Key.