com.scaleoutsoftware.soss.client.da

Class StateServerKey

java.lang.Object

com.scaleoutsoftware.soss.client.da.StateServerKey

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable

public class StateServerKey
extends java.lang.Object
implements java.io.Serializable, java.io.Externalizable

An immutable object used to identify objects in the StateServer store.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
StateServerKey() Create a new StateServerKey instance suitable for deserialization.
StateServerKey(byte[] keyValue) Initialize this StateServerKey from an array of bytes.
StateServerKey(byte[] keyValue, java.lang.String displayValue) Initialize this StateServerKey from an array of bytes and associate the key with a human-readable string for display purposes.
StateServerKey(int appId, byte[] keyValue, java.lang.String displayValue) Initialize this StateServerKey from an array of bytes and associate the key with a human-readable string for display purposes.
StateServerKey(int appId, int[] objId32, java.util.UUID extObjId) Initialize extended key from appId, objId, and extObjId.
StateServerKey(StateServerKeyAdapter adapter)
StateServerKey(java.lang.String appName, byte[] keyValue, java.lang.String displayValue) Initialize this StateServerKey from an array of bytes and associate the key with a human-readable string for display purposes.
StateServerKey(java.util.UUID uniqueId) Initialize this StateServerKey from a universally-unique identifier value.

Method Summary

Modifier and Type	Method and Description
static int	appNameToId(java.lang.String appName) Return the application ID corresponding to the application name appName and optionally register with StateServer for event callbacks for the specified application name.
static int	appNameToId(java.lang.String appName, boolean registerForEvents) Return the application ID corresponding to the application name appName and optionally register with StateServer for event callbacks for the specified application name.
void	copyBytesTo(int srcPos, byte[] dest, int destPos, int count)
boolean	equals(java.lang.Object obj)
int	getAppId()
static int	getDefaultAppId()
int	getKeySize()
java.lang.String	getKeyString() Gets a key string for a SSK.
int	hashCode()
boolean	hasKeyString() Checks whether this SSK has an associated key string
static boolean	isAppIdValid(int appId) Checks whether an application id is valid.
boolean	isChunkObject()
void	readExternal(java.io.ObjectInput in)
void	setChunkObject(boolean chunkObject)
static void	setDefaultAppId(int defaultAppId)
void	setKeyString(java.lang.String keyString) Associates a keystring to the key.
void	setUseKeyHashing(boolean keyHashing)
byte[]	toByteArray()
java.lang.String	toString()
static void	unregisterForEvents(int appId) Unregister for StateServer event notifications for objects associated with the application ID appId.
static void	unregisterForEvents(java.lang.String appName)
boolean	useKeyHashing()
void	writeExternal(java.io.ObjectOutput out)

Methods inherited from class java.lang.Object

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

Constructor Detail

StateServerKey

public StateServerKey(int appId,
                      int[] objId32,
                      java.util.UUID extObjId)
               throws StateServerException

Initialize extended key from appId, objId, and extObjId.

Parameters:

appId - application ID of the key

objId32 - objectID

extObjId - the extended obj id

Throws:

StateServerException - if an exception occurs when communicated with ScaleOut StateServer.

StateServerKey

public StateServerKey(java.util.UUID uniqueId)
               throws StateServerException

Initialize this StateServerKey from a universally-unique identifier value.

StateServerKeys created with this constructor are associated with a reserved, default application ID.

Parameters:

uniqueId - the UUID value from which this StateServerKey is to be initialized.

Throws:

java.lang.NullPointerException - if uniqueId is null.

StateServerException - if an exception occurs when communicated with ScaleOut StateServer.

StateServerKey

public StateServerKey(byte[] keyValue)
               throws StateServerException

Initialize this StateServerKey from an array of bytes.

Parameters:

keyValue - The byte array used to initialize the StateServerKey instance. The array's length must be between 0 (exclusive) 32 (inclusive).

Throws:

StateServerException - if an exception occurs when communicated with ScaleOut StateServer.

java.lang.NullPointerException - if bytes is null.

java.lang.IllegalArgumentException - if bytes.length is less than zero or greater than 32.

StateServerKey

public StateServerKey(byte[] keyValue,
                      java.lang.String displayValue)
               throws StateServerException

Initialize this StateServerKey from an array of bytes and associate the key with a human-readable string for display purposes.

Parameters:

keyValue - The byte array used to initialize the StateServerKey instance. The array's length must be between 0 (exclusive) 32 (inclusive).

displayValue - A human-readable string indicating the value of the key that is returned as the toString value for this key. If displayValue is null, a hex representation of keyValue will be used as this key's ToString value.

Throws:

StateServerException - if an exception occurs when communicated with ScaleOut StateServer.

java.lang.NullPointerException - if bytes is null.

java.lang.IllegalArgumentException - if bytes.length is less than zero or greater than 32.

StateServerKey

public StateServerKey(java.lang.String appName,
                      byte[] keyValue,
                      java.lang.String displayValue)
               throws StateServerException

Initialize this StateServerKey from an array of bytes and associate the key with a human-readable string for display purposes.

Parameters:

appName - the name of the application (representing a namespace of StateServer objects)

keyValue - The byte array used to initialize the StateServerKey instance. The array's length must be between 0 (exclusive) 32 (inclusive).

displayValue - A human-readable string indicating the value of the key that is returned as the toString value for this key. If displayValue is null, a hex representation of keyValue will be used as this key's ToString value.

Throws:

java.lang.IllegalArgumentException - if bytes is null or if appName is null. Or if bytes.length is less than zero or greater than 32. Or if the appName's length is zero or greater than 280 characters.

StateServerException - if appName conflicts with a previously registered application name.

StateServerKey

public StateServerKey(int appId,
                      byte[] keyValue,
                      java.lang.String displayValue)
               throws StateServerException

Initialize this StateServerKey from an array of bytes and associate the key with a human-readable string for display purposes.

Parameters:

appId - a value obtained by looking up an application name via a call to appNameToId(String). Allocation of application ID's is coordinated by the StateServer across all StateServer clients

keyValue - The byte array used to initialize the StateServerKey instance. The array's length must be between 0 (exclusive) 32 (inclusive).

displayValue - A human-readable string indicating the value of the key that is returned as the toString value for this key. If displayValue is null, a hex representation of keyValue will be used as this key's ToString value.

Throws:

java.lang.IllegalArgumentException - if bytes is null or if appName is null. Or if bytes.length is less than zero or greater than 32. Or, if the appName's length is zero or greater than 280 characters.

StateServerException - if appName conflicts with a previously registered application name.

StateServerKey

public StateServerKey(StateServerKeyAdapter adapter)
               throws StateServerException

Throws:

StateServerException

StateServerKey

public StateServerKey()

Create a new StateServerKey instance suitable for deserialization. Until this StateServerKey is deserialized, it is not usable for StateServer operations.

See Also:

Externalizable

Method Detail

appNameToId

public static int appNameToId(java.lang.String appName)
                       throws StateServerException

Return the application ID corresponding to the application name appName and optionally register with StateServer for event callbacks for the specified application name.

Application names are used to group StateServer keys into distinct namespaces of keys. Identical key values refer to distinct objects if the objects are associated with different appNames. An AppID (the value returned from this method), is a handle to the namespace of objects represented by the appName.

Application ID's are managed by the StateServer across all StateServer clients. They survive client restarts.

Parameters:

appName - The name of the application to look up.

Returns:

The ID that StateServer assigns to correspond to appName.

Throws:

StateServerException - if an exception occurs when communicated with ScaleOut StateServer.

appNameToId

public static int appNameToId(java.lang.String appName,
                              boolean registerForEvents)
                       throws StateServerException

Return the application ID corresponding to the application name appName and optionally register with StateServer for event callbacks for the specified application name.

Application names are used to group StateServer keys into distinct namespaces of keys. Identical key values refer to distinct objects if the objects are associated with different appNames. An AppID (the value returned from this method), is a handle to the namespace of objects represented by the appName.

Application ID's are managed by the StateServer across all StateServer clients. They survive client restarts.

Application names also form a grouping for StateServer's event notification facility. By setting registerForEvents to true you indicate that the currently executing application wants to be a potential recipient of StateServer event notifications for object with the collection identified by appName. To receive notifications, you must also register a handler for the DataAccessor.ObjectExpired event.

Parameters:

appName - The name of the application to look up.

registerForEvents - If true, ensure that this client is registered with the StateServer to receive event notifications (e.g. object expiration notifications) for objects associated with appName. If false, do not alter the existing event notification status: if event notifications were previously enabled, they remain enabled; if event notifications had never been enabled or were previously disabled, they remain disabled. To unregister for event notifications, see unregisterForEvents(int).

Returns:

The ID that StateServer assigns to correspond to appName.

Throws:

StateServerException - if registerForEvents is true and StateServer is inaccessible

getDefaultAppId

public static int getDefaultAppId()
                           throws StateServerException

Throws:

StateServerException

setDefaultAppId

public static void setDefaultAppId(int defaultAppId)

unregisterForEvents

public static void unregisterForEvents(int appId)
                                throws StateServerException

Unregister for StateServer event notifications for objects associated with the application ID appId.

If the current application is not registered to receive event notifications for appId then this method is a nop.

Parameters:

appId - the id of the application namespace to be unregistered. Notifications on objects in that namespace will no longer be received by this host.

Throws:

StateServerException - if StateServer is inaccessible

unregisterForEvents

public static void unregisterForEvents(java.lang.String appName)
                                throws StateServerException

Throws:

StateServerException

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

getAppId

public int getAppId()

getKeySize

public int getKeySize()

toByteArray

public byte[] toByteArray()

copyBytesTo

public void copyBytesTo(int srcPos,
                        byte[] dest,
                        int destPos,
                        int count)

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException

Specified by:

readExternal in interface java.io.Externalizable

Throws:

java.io.IOException

java.lang.ClassNotFoundException

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException

Specified by:

writeExternal in interface java.io.Externalizable

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

isAppIdValid

public static boolean isAppIdValid(int appId)

Checks whether an application id is valid.

Parameters:

appId - an application id

Returns:

whether the application id is valid

getKeyString

public java.lang.String getKeyString()
                              throws StateServerException

Gets a key string for a SSK.

Returns:

a key string

Throws:

StateServerException - reading a key string from server failed

setKeyString

public void setKeyString(java.lang.String keyString)

Associates a keystring to the key. This key string will enter server-side cache as soon as object with this key is created.

Parameters:

keyString - a key string to associate with this SSK

hasKeyString

public boolean hasKeyString()

Checks whether this SSK has an associated key string

Returns:

true if key string is present

useKeyHashing

public boolean useKeyHashing()

setUseKeyHashing

public void setUseKeyHashing(boolean keyHashing)

isChunkObject

public boolean isChunkObject()

setChunkObject

public void setChunkObject(boolean chunkObject)