com.scaleoutsoftware.soss.client.da

Class DataAccessor

java.lang.Object

com.scaleoutsoftware.soss.client.da.DataAccessor

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable

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

A StateServer accessor class providing Create, Read, Update, and Delete operations to the StateServer object whose key was specified when the DataAccessor instance was created.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DataAccessor.ObjectWithVersion An object-version pair for read call return type

Field Summary

Fields

Modifier and Type	Field and Description
static int	InfiniteTimeout

Constructor Summary

Constructors

Constructor and Description
DataAccessor() Create a new DataAccessor instance suitable for deserialization.
DataAccessor(StateServerKey key)
DataAccessor(StateServerKey key, boolean lockWhenReading)
DataAccessor(java.util.UUID uuid) Create a new DataAccessor instance to access the StateServer object identified by the provided unique identifier value.
DataAccessor(java.util.UUID uuid, boolean lockWhenReading)

Method Summary

Modifier and Type	Method and Description
StateServerResult	acquireOrUpdateLock(boolean throwOnError) Ensure that the StateServer is holding a lock for this DataAccessor's underlying object.
StateServerResult	acquireOrUpdateLock(boolean throwOnError, boolean remoteStore)
static void	addListener(ObjectExpirationListener listener)
boolean	allowCaching() Indicates whether (deserialized) objects corresponding to this DataAccessor are saved in the client-side cache when they are written to StateServer.
static void	clearAllObjects() Clears all of the objects from the SOSS store.
static void	clearObjects(int appId)
static void	clearObjects(java.lang.String appName)
void	create(CreatePolicy createInfo, byte[] bytes, int offset, int count, boolean lock)
void	create(CreatePolicy createInfo, java.lang.Object obj, boolean lock) Create a new object on StateServer by serializing the contents of the supplied object and writing the resulting byte stream to StateServer.
void	create(CreatePolicy createInfo, java.io.Serializable obj) Create a new object on StateServer by serializing the contents of the supplied object and writing the resulting byte stream to StateServer.
void	create(CreatePolicy createInfo, java.io.Serializable obj, byte[] bytes, int offset, int count, boolean lock) Create a new StateServer object with the provided contents.
void	create(int timeoutMinutes, byte[] bytes, int offset, int count)
void	create(int timeoutMinutes, byte[] bytes, int offset, int count, boolean lock)
void	create(int timeoutMinutes, java.io.Serializable obj) Create a new object on StateServer by serializing the contents of the supplied object and writing the resulting byte stream to StateServer.
StateServerFuture<?>	createAsync(CreatePolicy createInfo, byte[] bytes, int offset, int count, boolean lock)
StateServerFuture<?>	createAsync(CreatePolicy createInfo, java.io.Serializable obj, byte[] bytes, int offset, int count, boolean lock)
StateServerFuture<?>	createAsync(int timeoutMinutes, byte[] bytes, int offset, int count)
StateServerFuture<?>	createAsync(int timeoutMinutes, byte[] bytes, int offset, int count, boolean lock)
static DataAccessor	createDataAccessor(StateServerKey key)
static DataAccessor	createDataAccessor(StateServerKey key, boolean lockWhenReading)
void	delete() Remove the object this accessor refers to from StateServer.
void	delete(boolean enableAsyncWriteThrough)
StateServerFuture<?>	deleteAsync()
void	dispose()
int	doPutObjectArrayRequest(ObjectArray objArr, PutObjectRequestBuilder request)
int	doPutRequest(java.lang.Object obj, PutObjectRequestBuilder request)
CustomSerializer	getCustomSerializer()
StateServerKey	getKey() Return the StateServerKey that corresponds to this DataAccessor's identity.
int	getLockTicket()
static int	getMaxCacheKB() Gets the current maximum size of the client-side cache in kilobytes.
boolean	isLocked() Gets an indication as to whether the StateServer is holding a lock for this DataAccessor's underlying object.
boolean	isLockedWhenReading()
void	put(CreatePolicy createInfo, java.io.Serializable obj, ObjectMetadata metadata) Create or updates new StateServer object with the provided contents.
static QueryResult	query(IndexCollection indexCollection)
static QueryResult	query(int appId, boolean matchAll, IndexCollection indexCollection)
static QueryResult	query(int appId, IndexCollection indexCollection)
static QueryResult	query(int appId, Query query)
static QueryResult	query(java.lang.String appName, IndexCollection indexCollection)
static QueryResult	queryAllObjects(IndexCollection indexCollection)
static QueryResult	queryLocalObjects(int appId)
byte[]	read()
byte[]	read(boolean objectMustExist)
ReadResult	read(java.util.Set<ReadOptions> options) Read the data from StateServer corresponding to this DataAccessor's key value.
StateServerFuture<ReadResult>	readAsync(java.util.Set<ReadOptions> options)
void	readExternal(java.io.ObjectInput in)
ReadObjectReply	readIntoBuffer(byte[] buffer, boolean objectMustExist, boolean expandBuffer) Reads object into preallocated buffer, optionally allocating new buffer if necessary.
ReadMetadataResult	readMetadata(java.util.Set<ReadOptions> options)
java.lang.Object	readObject() Read the data from StateServer corresponding to this DataAccessor's key value and deserialize it using ObjectInputStream.
java.lang.Object	readObject(boolean objectMustExist) Read the data from StateServer corresponding to this DataAccessor's key value and deserialize it using ObjectInputStream.
java.lang.Object	readObject(boolean objectMustExist, boolean readThroughEnabled, boolean backingStorePresent, boolean readThroughPoll) Read the data from StateServer corresponding to this DataAccessor's key value and deserialize it using ObjectInputStream.
DataAccessor.ObjectWithVersion	readObjectWithVersion(boolean readImmediate, boolean objectMustExist, boolean readThroughEnabled, boolean remoteStoreEnabled, GeoServerReadMode mode, boolean synchronousReadThrough, boolean readThroughPoll)
DataAccessor.ObjectWithVersion	readObjectWithVersion(boolean objectMustExist, boolean readThroughEnabled, boolean remoteStoreEnabled, GeoServerReadMode mode, boolean synchronousReadThrough, boolean readThroughPoll)
java.lang.Object	readPotentiallyLockedObject(java.util.concurrent.atomic.AtomicInteger nonoptimisedReads, boolean knownVersion, int version) Reads a potentially locked object ignoring the lock.
static void	registerForEvents(int appId)
static void	registerForInvocationGridEvents(int invocationGridId)
void	releaseLock() Release any StateServer locks corresponding to this DataAccessor's underlying object.
static void	removeListener(ObjectExpirationListener listener)
void	setAllowCaching(boolean allowCaching) Sets a flag indicating whether (deserialized) objects corresponding to this DataAccessor should be saved in the client-side cache when they are written to StateServer.
static void	setCoherencyInterval(int appId, int coherencyInterval) Sets coherency interval in milliseconds for given application ID.
void	setCustomSerializer(CustomSerializer customSerializer)
void	setLockedWhenReading(boolean lockWhenReading)
static void	setMaxCacheKB(int maxCacheKB) Set the maximum size of the client-side cache in kilobytes.
void	setupUpdateRequest(PutObjectRequestBuilder request, boolean unlockAfterUpdate)
static void	unregisterForEvents(int appId)
void	update(byte[] bytes, int offset, int count)
void	update(byte[] bytes, int offset, int count, boolean unlockAfterUpdate)
void	update(java.lang.Object obj)
void	update(java.lang.Object obj, boolean unlockAfterUpdate)
void	update(java.io.Serializable cachedObject, byte[] bytes, int offset, int count, boolean unlockAfterUpdate)
StateServerFuture<?>	updateAsync(byte[] bytes, int offset, int count, boolean unlockAfterUpdate)
StateServerFuture<?>	updateAsync(java.lang.Object cachedObject, byte[] bytes, int offset, int count, boolean unlockAfterUpdate)
void	updateMetadata(ObjectMetadata metadata, boolean unlock)
void	writeExternal(java.io.ObjectOutput out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

InfiniteTimeout

public static final int InfiniteTimeout

See Also:

Constant Field Values

Constructor Detail

DataAccessor

public DataAccessor()

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

See Also:

Externalizable

DataAccessor

public DataAccessor(java.util.UUID uuid)
             throws StateServerException

Create a new DataAccessor instance to access the StateServer object identified by the provided unique identifier value.

Parameters:

uuid - a universally unique identifier value

Throws:

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

DataAccessor

public DataAccessor(java.util.UUID uuid,
                    boolean lockWhenReading)
             throws StateServerException

Throws:

StateServerException

DataAccessor

public DataAccessor(StateServerKey key)

DataAccessor

public DataAccessor(StateServerKey key,
                    boolean lockWhenReading)

Method Detail

addListener

public static void addListener(ObjectExpirationListener listener)
                        throws StateServerException

Throws:

StateServerException

removeListener

public static void removeListener(ObjectExpirationListener listener)
                           throws StateServerException

Throws:

StateServerException

registerForEvents

public static void registerForEvents(int appId)
                              throws StateServerException

Throws:

StateServerException

unregisterForEvents

public static void unregisterForEvents(int appId)
                                throws StateServerException

Throws:

StateServerException

registerForInvocationGridEvents

public static void registerForInvocationGridEvents(int invocationGridId)
                                            throws StateServerException

Throws:

StateServerException

doPutRequest

public int doPutRequest(java.lang.Object obj,
                        PutObjectRequestBuilder request)
                 throws StateServerException

Throws:

StateServerException

doPutObjectArrayRequest

public int doPutObjectArrayRequest(ObjectArray objArr,
                                   PutObjectRequestBuilder request)
                            throws StateServerException

Throws:

StateServerException

create

public void create(int timeoutMinutes,
                   java.io.Serializable obj)
            throws StateServerException

Create a new object on StateServer by serializing the contents of the supplied object and writing the resulting byte stream to StateServer. The StateServer entry will expire after timeoutMinutes of inactivity.

If AllowCaching is true, then subject to memory constraints, obj will be entered client-side object cache. If cached and not released due to memory pressure and not subsequently modified by any StateServer client, obj will be available for retrieval via subsequent Read operations without deserialization.

NOTE: The caller should not modify obj after calling this method or other readers will experience inconsistent results: if obj is returned from the cache, modifications to obj made after the object is stored in the cache will be visible to the reader. If the obj is removed from the cache due to insufficient cache memory, any modifications made after this method was called will be lost.

Parameters:

timeoutMinutes - the number of minutes of inactivity after which the object will be automatically removed from StateServer.

obj - a Serializable object to serialize and write to StateServer.

Throws:

StateServerException - if the StateServer cannot be accessed or if an object already exists in the StateServer with this DataAccessor's key.

create

public void create(CreatePolicy createInfo,
                   java.io.Serializable obj)
            throws StateServerException

Create a new object on StateServer by serializing the contents of the supplied object and writing the resulting byte stream to StateServer. The object expiration policy and any dependencies are specified via createInfo.

If AllowCaching is true, then subject to memory constraints, obj will be entered client-side object cache. If cached and not released due to memory pressure and not subsequently modified by any StateServer client, obj will be available for retrieval via subsequent Read operations without deserialization.

NOTE: The caller should not modify obj after calling this method or other readers will experience inconsistent results: if obj is returned from the cache, modifications to obj made after the object is stored in the cache will be visible to the reader. If the obj is removed from the cache due to insufficient cache memory, any modifications made after this method was called will be lost.

Parameters:

createInfo - Indicates the timeout, the type of timeout, whether the object may be removed from memory if memory availability becomes constrained, and any dependence this object has on other StateServer objects.

obj - a Serializable object to serialize and write to StateServer.

Throws:

StateServerException - if the StateServer cannot be accessed or if an object already exists in the StateServer with this DataAccessor's key.

create

public void create(CreatePolicy createInfo,
                   java.lang.Object obj,
                   boolean lock)
            throws StateServerException

Create a new object on StateServer by serializing the contents of the supplied object and writing the resulting byte stream to StateServer. The StateServer entry will expire after timeoutMinutes of inactivity.

The object to be written to StateServer as well as all objects it references must be Serializable. The supplied object is serialized using BinaryFormatter.

If allowCaching() is true, then subject to memory constraints, obj will be entered client-side object cache. If cached and not released due to memory pressure and not subsequently modified by any StateServer client, obj will be available for retrieval via subsequent Read operations without deserialization.

NOTE: The caller should not modify obj after calling this method or other readers will experience inconsistent results: if obj is returned from the cache, modifications to obj made after the object is stored in the cache will be visible to the reader. If the obj is removed from the cache due to insufficient cache memory, any modifications made after this method was called will be lost.

Parameters:

createInfo - Indicates the timeout, the type of timeout, whether the object may be removed from memory if memory availability becomes constrained, and any dependence this object has on other StateServer objects.

obj - a Serializable object to serialize and write to StateServer.

lock - If true, StateServer will atomically create and lock the object so that additional updates may be performed under a StateServer lock. If false, StateServer will create the object but leave it unlocked.

Throws:

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

create

public void create(int timeoutMinutes,
                   byte[] bytes,
                   int offset,
                   int count)
            throws StateServerException

Throws:

StateServerException

create

public void create(int timeoutMinutes,
                   byte[] bytes,
                   int offset,
                   int count,
                   boolean lock)
            throws StateServerException

Throws:

StateServerException

create

public void create(CreatePolicy createInfo,
                   byte[] bytes,
                   int offset,
                   int count,
                   boolean lock)
            throws StateServerException

Throws:

StateServerException

create

public void create(CreatePolicy createInfo,
                   java.io.Serializable obj,
                   byte[] bytes,
                   int offset,
                   int count,
                   boolean lock)
            throws StateServerException

Create a new StateServer object with the provided contents. Save cachedObject in the StateServer's client-side cache. Criteria regarding object expiration and object dependencies is supplied via createInfo.

Parameters:

createInfo - Indicates the timeout, the type of timeout, whether the object may be removed from memory if memory availability becomes constrained, and any dependence this object has on other StateServer objects.

obj - a (deserialized) object to associate with this DataAccessor's getKey() in a per-client cache. Assuming the serialized version of the object associated with this DataAccessor is not modified by any client and that appropriate ReadOptions are specified, then cachedObject will be returned on subsequent read() operations, subject to client-side memory constraints.

bytes - an array of bytes to persist to StateServer.

offset - the starting position within the array at which the data to be persisted begins.

count - the count of bytes within the array to persist.

lock - If true, StateServer will atomically create and lock the object so that additional updates may be performed under a StateServer lock. If false, StateServer will create the object but leave it unlocked.

Throws:

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

See Also:

setMaxCacheKB(int), getMaxCacheKB()

put

public void put(CreatePolicy createInfo,
                java.io.Serializable obj,
                ObjectMetadata metadata)
         throws StateServerException

Create or updates new StateServer object with the provided contents. Save cachedObject in the StateServer's client-side cache. Criteria regarding object expiration and object dependencies is supplied via createInfo. Object metadata can be optionally supplied.

Parameters:

createInfo - Indicates the timeout, the type of timeout, whether the object may be removed from memory if memory availability becomes constrained, and any dependence this object has on other StateServer objects.

obj - a (deserialized) object to associate with this DataAccessor's getKey() in a per-client cache. Assuming the serialized version of the object associated with this DataAccessor is not modified by any client and that appropriate ReadOptions are specified, then cachedObject will be returned on subsequent read() operations, subject to client-side memory constraints.

metadata - Object's metadata.Provide null for none

Throws:

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

createAsync

public StateServerFuture<?> createAsync(int timeoutMinutes,
                                        byte[] bytes,
                                        int offset,
                                        int count)
                                 throws StateServerException

Throws:

StateServerException

createAsync

public StateServerFuture<?> createAsync(int timeoutMinutes,
                                        byte[] bytes,
                                        int offset,
                                        int count,
                                        boolean lock)
                                 throws StateServerException

Throws:

StateServerException

createAsync

public StateServerFuture<?> createAsync(CreatePolicy createInfo,
                                        byte[] bytes,
                                        int offset,
                                        int count,
                                        boolean lock)
                                 throws StateServerException

Throws:

StateServerException

createAsync

public StateServerFuture<?> createAsync(CreatePolicy createInfo,
                                        java.io.Serializable obj,
                                        byte[] bytes,
                                        int offset,
                                        int count,
                                        boolean lock)
                                 throws StateServerException

Throws:

StateServerException

readObject

public java.lang.Object readObject()
                            throws StateServerException,
                                   java.io.IOException,
                                   java.lang.ClassNotFoundException

Read the data from StateServer corresponding to this DataAccessor's key value and deserialize it using ObjectInputStream.

If allowCaching() is true and if the size of the object returned from StateServer is less than getMaxCacheKB() then if the object is not already in the client-side cache, it will be added to the cache.

This overload throws an ObjectNotFoundException if StateServer has no entry corresponding to this accessor's key.

Returns:

The object resulting from deserializing the byte stream read from StateServer or null if the object doesn't exist and objectMustExist is false.

Throws:

StateServerException - if an error occurs when retrieving the object from StateServer

java.io.IOException - if an error occurs while deserializing the object

java.lang.ClassNotFoundException - if an object required for deserialization cannot be found

readObject

public java.lang.Object readObject(boolean objectMustExist)
                            throws StateServerException,
                                   java.io.IOException,
                                   java.lang.ClassNotFoundException

Read the data from StateServer corresponding to this DataAccessor's key value and deserialize it using ObjectInputStream.

If allowCaching() is true and if the size of the object returned from StateServer is less than getMaxCacheKB() then if the object is not already in the client-side cache, it will be added to the cache.

Parameters:

objectMustExist - If true, throw an ObjectNotFoundException if StateServer has no entry corresponding to this accessor's key. If false return null if the entry doesn't exist on StateServer.

Returns:

The object resulting from deserializing the byte stream read from StateServer or null if the object doesn't exist and objectMustExist is false.

Throws:

StateServerException - if an error occurs when retrieving the object from StateServer

java.io.IOException - if an error occurs while deserializing the object

java.lang.ClassNotFoundException - if an object required for deserialization cannot be found

readObject

public java.lang.Object readObject(boolean objectMustExist,
                                   boolean readThroughEnabled,
                                   boolean backingStorePresent,
                                   boolean readThroughPoll)
                            throws StateServerException,
                                   java.io.IOException,
                                   java.lang.ClassNotFoundException

Read the data from StateServer corresponding to this DataAccessor's key value and deserialize it using ObjectInputStream.

If allowCaching() is true and if the size of the object returned from StateServer is less than getMaxCacheKB() then if the object is not already in the client-side cache, it will be added to the cache.

This signature is to be used only by NamedCache

Parameters:

objectMustExist - If true, throw an ObjectNotFoundException if StateServer has no entry corresponding to this accessor's key. If false return null if the entry doesn't exist on StateServer.

readThroughEnabled - if true, readThrough is enabled on the calling cache

backingStorePresent - if true, the host has an access to the backingStore

readThroughPoll - if true, host is a polling reader during read-trough

Returns:

The object resulting from deserializing the byte stream read from StateServer or null if the object doesn't exist and objectMustExist is false.

Throws:

StateServerException - if an error occurs when retrieving the object from StateServer

java.io.IOException - if an error occurs while deserializing the object

java.lang.ClassNotFoundException - if an object required for deserialization cannot be found

readPotentiallyLockedObject

public java.lang.Object readPotentiallyLockedObject(java.util.concurrent.atomic.AtomicInteger nonoptimisedReads,
                                                    boolean knownVersion,
                                                    int version)
                                             throws StateServerException,
                                                    java.io.IOException,
                                                    java.lang.ClassNotFoundException

Reads a potentially locked object ignoring the lock. This method honors client cache in case allowCaching is turned on.

Parameters:

nonoptimisedReads - counter for cache misses

knownVersion - true/false if we know the version

version - the version we expect to read

Returns:

deserialized object

Throws:

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

java.io.IOException - if an IO error occurs.

java.lang.ClassNotFoundException - if the object class can't be found.

readObjectWithVersion

public DataAccessor.ObjectWithVersion readObjectWithVersion(boolean readImmediate,
                                                            boolean objectMustExist,
                                                            boolean readThroughEnabled,
                                                            boolean remoteStoreEnabled,
                                                            GeoServerReadMode mode,
                                                            boolean synchronousReadThrough,
                                                            boolean readThroughPoll)
                                                     throws StateServerException,
                                                            java.io.IOException,
                                                            java.lang.ClassNotFoundException

Throws:

StateServerException

java.io.IOException

java.lang.ClassNotFoundException

readObjectWithVersion

public DataAccessor.ObjectWithVersion readObjectWithVersion(boolean objectMustExist,
                                                            boolean readThroughEnabled,
                                                            boolean remoteStoreEnabled,
                                                            GeoServerReadMode mode,
                                                            boolean synchronousReadThrough,
                                                            boolean readThroughPoll)
                                                     throws StateServerException,
                                                            java.io.IOException,
                                                            java.lang.ClassNotFoundException

Throws:

StateServerException

java.io.IOException

java.lang.ClassNotFoundException

read

public byte[] read()
            throws StateServerException

Throws:

StateServerException

read

public byte[] read(boolean objectMustExist)
            throws StateServerException

Throws:

StateServerException

readIntoBuffer

public ReadObjectReply readIntoBuffer(byte[] buffer,
                                      boolean objectMustExist,
                                      boolean expandBuffer)
                               throws StateServerException

Reads object into preallocated buffer, optionally allocating new buffer if necessary.

Parameters:

buffer - byte buffer to read object into

objectMustExist - if true throw exception if object does not exists

expandBuffer - if true, new buffer is allocated in case the old one is not big enough

Returns:

read reply

Throws:

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

read

public ReadResult read(java.util.Set<ReadOptions> options)
                throws StateServerException

Read the data from StateServer corresponding to this DataAccessor's key value.

If isLockedWhenReading() returns true when this read(Set) method is called, this method will attempt to acquire a StateServer object lock when it reads the object.

If a lock has previously been acquired for the StateServer object that this DataAccessor represents, then the lock will be refreshed.

Parameters:

options - a Set (probably an EnumSet) of ReadOptions values that specify the options desired for this read request. A null value for options is interpreted the same as an empty set of ReadOptions. See ReadOptions.getEmptySet(), ReadOptions.getObjectMayNotExistSet(), ReadOptions.getLockObjectSet(), and ReadOptions.getReturnCachedObjectIfValidSet() for predefined, read-only versions of commonly-used options.

Returns:

a ReadResult that provides the results from this read request or any status returns as appropriate.

Throws:

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

readAsync

public StateServerFuture<ReadResult> readAsync(java.util.Set<ReadOptions> options)
                                        throws StateServerException

Throws:

StateServerException

update

public void update(java.lang.Object obj)
            throws StateServerException

Throws:

StateServerException

update

public void update(java.lang.Object obj,
                   boolean unlockAfterUpdate)
            throws StateServerException

Throws:

StateServerException

update

public void update(byte[] bytes,
                   int offset,
                   int count)
            throws StateServerException

Throws:

StateServerException

update

public void update(byte[] bytes,
                   int offset,
                   int count,
                   boolean unlockAfterUpdate)
            throws StateServerException

Throws:

StateServerException

update

public void update(java.io.Serializable cachedObject,
                   byte[] bytes,
                   int offset,
                   int count,
                   boolean unlockAfterUpdate)
            throws StateServerException

Throws:

StateServerException

updateAsync

public StateServerFuture<?> updateAsync(byte[] bytes,
                                        int offset,
                                        int count,
                                        boolean unlockAfterUpdate)
                                 throws StateServerException

Throws:

StateServerException

updateAsync

public StateServerFuture<?> updateAsync(java.lang.Object cachedObject,
                                        byte[] bytes,
                                        int offset,
                                        int count,
                                        boolean unlockAfterUpdate)
                                 throws StateServerException

Throws:

StateServerException

setupUpdateRequest

public void setupUpdateRequest(PutObjectRequestBuilder request,
                               boolean unlockAfterUpdate)

delete

public void delete()
            throws StateServerException

Remove the object this accessor refers to from StateServer.

If the StateServer object represented by this DataAccessor was previously locked via this DataAccessor, the lock will be released if this Delete operation completes successfully.

Throws:

StateServerException - if the StateServer cannot be accessed.

ObjectNotFoundException - if the object corresponding to this DataAccessor's key does not exist in the StateServer.

delete

public void delete(boolean enableAsyncWriteThrough)
            throws StateServerException

Throws:

StateServerException

deleteAsync

public StateServerFuture<?> deleteAsync()
                                 throws StateServerException

Throws:

StateServerException

readMetadata

public ReadMetadataResult readMetadata(java.util.Set<ReadOptions> options)
                                throws StateServerException

Throws:

StateServerException

updateMetadata

public void updateMetadata(ObjectMetadata metadata,
                           boolean unlock)
                    throws StateServerException

Throws:

StateServerException

queryAllObjects

public static QueryResult queryAllObjects(IndexCollection indexCollection)
                                   throws StateServerException

Throws:

StateServerException

query

public static QueryResult query(IndexCollection indexCollection)
                         throws StateServerException

Throws:

StateServerException

query

public static QueryResult query(java.lang.String appName,
                                IndexCollection indexCollection)
                         throws StateServerException

Throws:

StateServerException

query

public static QueryResult query(int appId,
                                IndexCollection indexCollection)
                         throws StateServerException

Throws:

StateServerException

query

public static QueryResult query(int appId,
                                Query query)
                         throws StateServerException

Throws:

StateServerException

query

public static QueryResult query(int appId,
                                boolean matchAll,
                                IndexCollection indexCollection)
                         throws StateServerException

Throws:

StateServerException

queryLocalObjects

public static QueryResult queryLocalObjects(int appId)
                                     throws StateServerException

Throws:

StateServerException

acquireOrUpdateLock

public StateServerResult acquireOrUpdateLock(boolean throwOnError)
                                      throws StateServerException

Ensure that the StateServer is holding a lock for this DataAccessor's underlying object. If the underlying object is already locked, the lock timeout will be refreshed.

Parameters:

throwOnError - If true, acquireOrUpdateLock(boolean) will throw an ObjectNotFoundException in the event the object does not exist on the StateServer or an ObjectLockedException if the object is already locked by some other StateServer client. If false, acquireOrUpdateLock(boolean) will return a StateServerResult to indicate object doesn't exist or object already locked conditions.

Returns:

A StateServerResult indicating the result status of the method. Note that if throwOnError is true, the only possible result value is StateServerResult.Success.

Throws:

StateServerException - if the StateServer cannot be accessed.

ObjectNotFoundException - if the object corresponding to this DataAccessor's key does not exist in the StateServer and throwOnError is true.

ObjectLockedException - if the object corresponding to this DataAccessor's key is already locked by some other StateServer client and throwOnError is true.

acquireOrUpdateLock

public StateServerResult acquireOrUpdateLock(boolean throwOnError,
                                             boolean remoteStore)
                                      throws StateServerException

Throws:

StateServerException

releaseLock

public void releaseLock()
                 throws StateServerException

Release any StateServer locks corresponding to this DataAccessor's underlying object.

If this DataAccessor does not currently hold a lock for the underlying object, calling this method is a nop.

Throws:

StateServerException - if the StateServer cannot be accessed.

ObjectNotFoundException - if no object corresponding to this DataAccessor's key exists in the StateServer.

ObjectLockedException - if the object corresponding to this DataAccessor's key is locked by some other StateServer client -- perhaps due to a lock timeout.

isLocked

public boolean isLocked()

Gets an indication as to whether the StateServer is holding a lock for this DataAccessor's underlying object.

If isLocked() returns true, the object was (at least at one time), locked on the StateServer. However, no communication with the StateServer occurs when retrieving this value. Consequently, it is possible that the lock has timed out and is no longer valid.

To assure that the StateServer is currently holding a lock for this DataAccessor's object you may call AcquireOrUpdateLock.

Returns:

true if the StateServer is holding a lock for this DataAccessor's underlying object. false otherwise.

getKey

public StateServerKey getKey()

Return the StateServerKey that corresponds to this DataAccessor's identity.

Returns:

the StateServerKey that corresponds to this DataAccessor's identity.

getLockTicket

public int getLockTicket()

allowCaching

public boolean allowCaching()

Indicates whether (deserialized) objects corresponding to this DataAccessor are saved in the client-side cache when they are written to StateServer.

By default, allowCaching returns true.

Returns:

If true, objects stored via this DataAccessor will be cached in a client-side cache subject to memory constraints. If false objects will not be cached.

See Also:

getMaxCacheKB(), setMaxCacheKB(int)

setAllowCaching

public void setAllowCaching(boolean allowCaching)

Sets a flag indicating whether (deserialized) objects corresponding to this DataAccessor should be saved in the client-side cache when they are written to StateServer.

allowCaching is initially true.

Parameters:

allowCaching - If true, objects stored via this DataAccessor will be cached in a client-side cache subject to memory constraints. If false objects will not be cached. Setting allowCaching to false also ensures that any object previously-cached via this DataAccessor is removed from the cache.

See Also:

getMaxCacheKB(), setMaxCacheKB(int)

getMaxCacheKB

public static int getMaxCacheKB()

Gets the current maximum size of the client-side cache in kilobytes.

When the (approximate) size of all cached objects exceeds the maximum client-side cache size value, the least recently used objects are removed from the cache until the cache consumes no more memory (approximately) than the desired cache size.

If the maximum cache size is not set programmatically, its initial value is the value of the max_cache parameter specified in the soss_params.txt configuration file.

Returns:

the maximum size of the client-side cache in kilobytes.

See Also:

setMaxCacheKB(int)

setMaxCacheKB

public static void setMaxCacheKB(int maxCacheKB)

Set the maximum size of the client-side cache in kilobytes.

When the (approximate) size of all cached objects exceeds the maximum client-side cache size value, the least recently used objects are removed from the cache until the cache consumes no more memory (approximately) than the desired cache size. When the cache size is set to a smaller value, the cache is adjusted synchronously. In particular, setting the cache size to 0 will immediately remove all entries in the client-side cache and disable the client-side cache from use until the cache size is reset to a larger value.

If the maximum cache size is not set programmatically, its initial value is the value of the max_cache parameter specified in the soss_params.txt configuration file.

Parameters:

maxCacheKB - the maximum size of the client-side cache in kilobytes.

Throws:

java.lang.IllegalArgumentException - if maxCacheKB is negative

isLockedWhenReading

public boolean isLockedWhenReading()

setLockedWhenReading

public void setLockedWhenReading(boolean lockWhenReading)

dispose

public void dispose()

clearObjects

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

Throws:

StateServerException

setCoherencyInterval

public static void setCoherencyInterval(int appId,
                                        int coherencyInterval)

Sets coherency interval in milliseconds for given application ID. Coherency interval is maximum age of the client cache entry at which it can be returned without verifying the version with the server. Coherency interval of 0 means that object version is always verified. This optimization allows to avoid version checking server roundtrips when full coherency is not necessary.

Parameters:

appId - application ID to set coherency interval

coherencyInterval - coherency interval in milliseconds

clearAllObjects

public static void clearAllObjects()
                            throws StateServerException

Clears all of the objects from the SOSS store. Expiration events are not fired for these objects.

Throws:

StateServerException - if the local StateServer cannot be accessed

clearObjects

public static void clearObjects(int appId)
                         throws StateServerException

Throws:

StateServerException

createDataAccessor

public static DataAccessor createDataAccessor(StateServerKey key)

createDataAccessor

public static DataAccessor createDataAccessor(StateServerKey key,
                                              boolean lockWhenReading)

getCustomSerializer

public CustomSerializer getCustomSerializer()

setCustomSerializer

public void setCustomSerializer(CustomSerializer customSerializer)

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