|
Oracle NoSQL Database version 11gR2.2.0.26 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object oracle.kv.Key
public class 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:
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:
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 |
---|
public static Key createKey(List<String> majorPath, List<String> minorPath)
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.
majorPath
- may not be null or empty, and may not contain nulls.minorPath
- may be empty, but may not be null or contain nulls.public static Key createKey(String majorComponent, List<String> minorPath)
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.
majorComponent
- may not be null.minorPath
- may be empty, but may not be null or contain nulls.public static Key createKey(List<String> majorPath, String minorComponent)
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.
majorPath
- may not be null or empty, and may not contain nulls.minorComponent
- may not be null.public static Key createKey(String majorComponent, String minorComponent)
majorComponent
- may not be null.minorComponent
- may not be null.public static Key createKey(List<String> majorPath)
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.
majorPath
- may not be null or empty, and may not contain nulls.public static Key createKey(String majorComponent)
majorComponent
- may not be null.public List<String> getFullPath()
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.
public List<String> getMajorPath()
public List<String> getMinorPath()
public boolean isPrefix(Key otherKey)
otherKey
- the key being testedpublic int compareTo(Key otherKey)
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.
compareTo
in interface Comparable<Key>
public boolean equals(Object other)
equals
in class Object
public int hashCode()
hashCode
in class Object
public String toString()
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.
/SingleComponentMajorPath
/MajorPathPart1/MajorPathPart2/-/MinorPathPart1/MinorPathPart2
/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.
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.
toString
in class Object
public static Key fromString(String pathString)
toString()
. See
toString()
for more information about the path string format.
pathString
- a non-null path string, which should normally be
created using toString()
.
IllegalArgumentException
- if pathString does not begin with a
slash or contains invalid characters, for example, an invalid encoding
sequence.public byte[] toByteArray()
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.
public static Key fromByteArray(byte[] keyBytes)
toByteArray()
and returns the resulting Key.
|
Oracle NoSQL Database version 11gR2.2.0.26 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |