water

Class Key<T extends Keyed>

java.lang.Object

water.Iced<Key<T>>

water.Key<T>

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable, Freezable<Key<T>>

public final class Key<T extends Keyed>
extends Iced<Key<T>>
implements java.lang.Comparable

Keys! H2O supports a distributed Key/Value store, with exact Java Memory Model consistency. Keys are a means to find a Value somewhere in the Cloud, to cache it locally, to allow globally consistent updates to a Value. Keys have a *home*, a specific Node in the Cloud, which is computable from the Key itself. The Key's home node breaks ties on racing updates, and tracks caching copies (via a hardware-like MESI protocol), but otherwise is not involved in the DKV. All operations on the DKV, including Gets and Puts, are found in DKV.

Keys are defined as a simple byte-array, plus a hashCode and a small cache of Cloud-specific information. The first byte of the byte-array determines if this is a user-visible Key or an internal system Key; an initial byte of <32 is a system Key. User keys are generally externally visible, system keys are generally limited to things kept internal to the H2O Cloud. Keys might be a high-count item, hence we care about the size.

System keys for Job, Vec, Chunk and Vec.VectorGroup have special initial bytes; Keys for these classes can be determined without loading the underlying Value. Layout for Vec and Chunk is further restricted, so there is an efficient mapping between a numbered Chunk and it's associated Vec.

System keys (other than the restricted Vec and Chunk keys) can have their home node forced, by setting the desired home node in the first few Key bytes. Otherwise home nodes are selected by pseudo-random hash. Selecting a home node is sometimes useful for Keys with very high update rates coming from a specific Node.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
byte[]	_kb
static byte	CHK
static byte	GRP
static byte	HIDDEN_USER_KEY
static byte	JOB
static byte	USER_KEY
static byte	VEC

Method Summary

Methods

Modifier and Type	Method and Description
int	compareTo(java.lang.Object o) Lexically ordered Key comparison, so Keys can be sorted.
boolean	equals(java.lang.Object o)
T	get() Convenience function to fetch key contents from the DKV.
Key	getVecKey() Returns the Vec Key from a Chunk Key.
int	hashCode()
H2ONode	home_node() The home node for this Key.
boolean	home() True if the home_node() is the current node.
boolean	isChunkKey() True is this is a Chunk Key.
boolean	isVec() True is this is a Vec Key.
static <P extends Keyed> Key<P>	make() Factory making a random Key
static <P extends Keyed> Key<P>	make(byte[] kb) Factory making a Key from a byte[]
static <P extends Keyed> Key<P>	make(byte[] kb, byte rf, byte systemType, boolean required, H2ONode... replicas)
static <P extends Keyed> Key<P>	make(byte rf, byte systemType, boolean hint, H2ONode... replicas) Factory making a homed system Key.
static <P extends Keyed> Key<P>	make(H2ONode node) Make a random key, homed to a given node.
static <P extends Keyed> Key<P>	make(java.lang.String s) Factory making a Key from a String
static <P extends Keyed> Key<P>	make(java.lang.String s, byte rf, byte systemType, boolean hint, H2ONode... replicas) Factory making a homed system Key.
static <P extends Keyed> Key<P>	makeSystem(java.lang.String s)
static <P extends Keyed> Key<P>	makeUserHidden(java.lang.String s)
static java.lang.String	rand() A random string, useful as a Key name or partial Key suffix.
static Key	read_impl(Key k, AutoBuffer ab)
void	remove() Remove a Key from the DKV, including any embedded Keys.
Futures	remove(Futures fs)
java.lang.String	toString() Converts the key to HTML displayable string.
int	type() System type/byte of a Key, or the constant USER_KEY
boolean	user_allowed() True if a USER_KEY and not a system key.
java.lang.String	valueClass() Return the classname for the Value that this Key points to, if any (e.g., "water.fvec.Frame").
java.lang.String	valueClassSimple() Return the base classname (not including the package) for the Value that this Key points to, if any (e.g., "Frame").
static AutoBuffer	write_impl(Key k, AutoBuffer ab)
static AutoBuffer	writeJSON_impl(Key k, AutoBuffer ab)

Methods inherited from class water.Iced

asBytes, clone, copyOver, frozenType, read, readExternal, readJSON, reloadFromBytes, toJsonString, write, writeExternal, writeJSON

Methods inherited from class java.lang.Object

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

Field Detail

_kb

public final byte[] _kb

JOB

public static final byte JOB

See Also:

Constant Field Values

VEC

public static final byte VEC

See Also:

Constant Field Values

CHK

public static final byte CHK

See Also:

Constant Field Values

GRP

public static final byte GRP

See Also:

Constant Field Values

HIDDEN_USER_KEY

public static final byte HIDDEN_USER_KEY

See Also:

Constant Field Values

USER_KEY

public static final byte USER_KEY

See Also:

Constant Field Values

Method Detail

isVec

public final boolean isVec()

True is this is a Vec Key.

Returns:

True is this is a Vec Key

isChunkKey

public final boolean isChunkKey()

True is this is a Chunk Key.

Returns:

True is this is a Chunk Key

getVecKey

public final Key getVecKey()

Returns the Vec Key from a Chunk Key.

Returns:

Returns the Vec Key from a Chunk Key.

get

public final T get()

Convenience function to fetch key contents from the DKV.

Returns:

null if the Key is not mapped, or an instance of Keyed

home

public boolean home()

True if the home_node() is the current node.

Returns:

True if the home_node() is the current node

home_node

public H2ONode home_node()

The home node for this Key.

Returns:

The home node for this Key.

rand

public static java.lang.String rand()

A random string, useful as a Key name or partial Key suffix.

Returns:

A random short string

make

public static <P extends Keyed> Key<P> make(byte[] kb)

Factory making a Key from a byte[]

Returns:

Desired Key

make

public static <P extends Keyed> Key<P> make(java.lang.String s)

Factory making a Key from a String

Returns:

Desired Key

makeSystem

public static <P extends Keyed> Key<P> makeSystem(java.lang.String s)

makeUserHidden

public static <P extends Keyed> Key<P> makeUserHidden(java.lang.String s)

make

public static <P extends Keyed> Key<P> make(H2ONode node)

Make a random key, homed to a given node.

Parameters:

node - a node at which the new key is homed.

Returns:

the new key

make

public static <P extends Keyed> Key<P> make()

Factory making a random Key

Returns:

Desired Key

make

public static <P extends Keyed> Key<P> make(java.lang.String s,
                            byte rf,
                            byte systemType,
                            boolean hint,
                            H2ONode... replicas)

Factory making a homed system Key. Requires the initial system byte but then allows a String for the remaining bytes. Requires a list of exactly one H2ONode to home at. The hint specifies if it is an error to name an H2ONode that is NOT in the Cloud, or if some other H2ONode can be substituted. The rf parameter and passing more than 1 H2ONode are both depreciated.

Returns:

the desired Key

make

public static <P extends Keyed> Key<P> make(byte rf,
                            byte systemType,
                            boolean hint,
                            H2ONode... replicas)

Factory making a homed system Key. Requires the initial system byte and uses rand() for the remaining bytes. Requires a list of exactly one H2ONode to home at. The hint specifies if it is an error to name an H2ONode that is NOT in the Cloud, or if some other H2ONode can be substituted. The rf parameter and passing more than 1 H2ONode are both depreciated.

Returns:

the desired Key

make

public static <P extends Keyed> Key<P> make(byte[] kb,
                            byte rf,
                            byte systemType,
                            boolean required,
                            H2ONode... replicas)

remove

public void remove()

Remove a Key from the DKV, including any embedded Keys.

remove

public Futures remove(Futures fs)

user_allowed

public boolean user_allowed()

True if a USER_KEY and not a system key.

Returns:

True if a USER_KEY and not a system key

type

public int type()

System type/byte of a Key, or the constant USER_KEY

Returns:

Key type

valueClass

public java.lang.String valueClass()

Return the classname for the Value that this Key points to, if any (e.g., "water.fvec.Frame").

valueClassSimple

public java.lang.String valueClassSimple()

Return the base classname (not including the package) for the Value that this Key points to, if any (e.g., "Frame").

toString

public java.lang.String toString()

Converts the key to HTML displayable string. For user keys returns the key itself, for system keys returns their hexadecimal values.

Overrides:

toString in class java.lang.Object

Returns:

key as a printable string

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

compareTo

public int compareTo(java.lang.Object o)

Lexically ordered Key comparison, so Keys can be sorted. Modestly expensive.

Specified by:

compareTo in interface java.lang.Comparable

write_impl

public static final AutoBuffer write_impl(Key k,
                    AutoBuffer ab)

read_impl

public static final Key read_impl(Key k,
            AutoBuffer ab)

writeJSON_impl

public static final AutoBuffer writeJSON_impl(Key k,
                        AutoBuffer ab)