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 Key	make() Factory making a random Key
static Key	make(byte[] kb) Factory making a Key from a byte[]
static Key	make(byte rf, byte systemType, boolean hint, H2ONode... replicas) Factory making a homed system Key.
static Key	make(H2ONode node) Make a random key, homed to a given node.
static Key	make(java.lang.String s) Factory making a Key from a String
static Key	make(java.lang.String s, byte rf, byte systemType, boolean hint, H2ONode... replicas) Factory making a homed system Key.
static Key	makeSystem(java.lang.String s)
static Key	makeUserHidden(Key orig)
static java.lang.String	rand() A random string, useful as a Key name or partial Key suffix.
Key	read_impl(AutoBuffer ab) Implementation of the Iced serialization protocol, only called by auto-genned code.
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").
AutoBuffer	write_impl(AutoBuffer ab) Implementation of the Iced serialization protocol, only called by auto-genned code.
DocGen.HTML	writeHTML_impl(DocGen.HTML ab) Implementation of the Iced serialization protocol, only called by auto-genned code.
AutoBuffer	writeJSON_impl(AutoBuffer ab) Implementation of the Iced serialization protocol, only called by auto-genned code.

Methods inherited from class water.Iced

clone, frozenType, read, readExternal, readJSON_impl, readJSON, toJsonString, write, writeExternal, writeHTML, 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 Key make(byte[] kb)

Factory making a Key from a byte[]

Returns:

Desired Key

make

public static Key make(java.lang.String s)

Factory making a Key from a String

Returns:

Desired Key

makeSystem

public static Key makeSystem(java.lang.String s)

make

public static Key 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 Key make()

Factory making a random Key

Returns:

Desired Key

make

public static Key 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 Key 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

remove

public void remove()

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

remove

public Futures remove(Futures fs)

makeUserHidden

public static Key makeUserHidden(Key orig)

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 final AutoBuffer write_impl(AutoBuffer ab)

Implementation of the Iced serialization protocol, only called by auto-genned code. Not intended to be called by user code.

Specified by:

write_impl in interface Freezable<Key<T extends Keyed>>

Overrides:

write_impl in class Iced<Key<T extends Keyed>>

Parameters:

ab - AutoBuffer to write this object to.

Returns:

Returns the original AutoBuffer for flow-coding.

read_impl

public final Key read_impl(AutoBuffer ab)

Implementation of the Iced serialization protocol, only called by auto-genned code. Not intended to be called by user code.

Specified by:

read_impl in interface Freezable<Key<T extends Keyed>>

Overrides:

read_impl in class Iced<Key<T extends Keyed>>

Parameters:

ab - AutoBuffer to read this object from.

Returns:

Returns a new instance of object reconstructed from AutoBuffer.

writeHTML_impl

public final DocGen.HTML writeHTML_impl(DocGen.HTML ab)

Implementation of the Iced serialization protocol, only called by auto-genned code. Not intended to be called by user code.

Specified by:

writeHTML_impl in interface Freezable<Key<T extends Keyed>>

Overrides:

writeHTML_impl in class Iced<Key<T extends Keyed>>

Parameters:

ab - html to write object to.

Returns:

Returns the instance of HTML object.

writeJSON_impl

public final AutoBuffer writeJSON_impl(AutoBuffer ab)

Implementation of the Iced serialization protocol, only called by auto-genned code. Not intended to be called by user code.

Specified by:

writeJSON_impl in interface Freezable<Key<T extends Keyed>>

Overrides:

writeJSON_impl in class Iced<Key<T extends Keyed>>

Parameters:

ab - AutoBuffer to write this object to.

Returns:

Returns the original AutoBuffer for flow-coding.