NamedCache

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.scaleoutsoftware.soss.client
Class NamedCache

java.lang.Object
  com.scaleoutsoftware.soss.client.NamedCache

public final class NamedCache
extends Object
extends Object

Provides access to a named collection of objects that can be shared globally across multiple clients.

The NamedCache class provides an API suitable for caching a group of objects within a single, named cache. The CacheFactory.getCache class must be used to instantiate a NamedCache.

Objects within a named cache are identified using IDs of type CachedObjectId. Object identifiers can be constructed from a variety of types such as strings, UUIDs, and byte arrays, and they are constrained to identify objects within a single named cache.

A number of advanced caching features are available through the NamedCache class. When inserting an object into a cache, an expiration time for the object can be specified, as well the expiration behavior (sliding vs. absolute). Dependencies between objects can also be defined, allowing a dependent object to be automatically removed when one of its parent objects is updated or removed.

ScaleOut StateServer allows an object to be locked across every server in the farm. This per-object lock can be used to ensure that other clients do not alter the object while the lock is being held. All clients' code should take care to acquire a lock prior to performing an operation that could disrupt (or be disrupted by) other clients. The NamedCache will automatically perform maxLockAttempts retries when trying to acquire a lock.

The NamedCache class offers two properties to simplify usage of the advanced features of a named cache. The useLocking property controls the default locking behavior for the get method, and the defaultCreatePolicy property controls the default policies that are used when adding items to the cache through add. Finer grained control over locking and caching policies can be achieved by using the more advanced insert, update, and retrieve methods.

Every object in the cache can have up to 8 index values associated with it. Users are responsible for setting and managing these index values using the setMetadata method, and, once set, these index values can be queried for by using the query method. The result of a Query operation is a collection of object identifiers that can be used to access the matching objects in the cache.

Under low-memory situations, ScaleOut StateServer can be configured to remove the least frequently used objects from the cache in order to free up room for newer ones. By default, all objects in the cache are subject to this reclamation, but this behavior can be overridden by setting the object's priority when the object is first added to the cache (see the CreatePolicy class used by insert and DefaultCreatePolicy). See the "Configuration Parameters" topic in the SOSS help file for details on how to enable object reclamation in the server with the lru_threshold parameter.

Method Summary

void acquireLock(byte[] id)
Locks the cached object in SOSS to prevent other clients from updating or removing it.

void acquireLock(CachedObjectId id)
Locks the cached object in SOSS to prevent other clients from updating or removing it.

void acquireLock(String id)
Locks the cached object in SOSS to prevent other clients from updating or removing it.

void acquireLock(UUID id)
Locks the cached object in SOSS to prevent other clients from updating or removing it.





<T extends Serializable> 


void

add(byte[] id,
    T value)

Deprecated. Use put(com.scaleoutsoftware.soss.client.CachedObjectId, T)





<T extends Serializable> 


void

add(CachedObjectId<T> id,
    T value)

Deprecated. Use put(com.scaleoutsoftware.soss.client.CachedObjectId, T)





<T extends Serializable> 


void

add(String id,
    T value)

Deprecated. Use put(com.scaleoutsoftware.soss.client.CachedObjectId, T)





<T extends Serializable> 


void

add(UUID id,
    T value)

Deprecated. Use put(com.scaleoutsoftware.soss.client.CachedObjectId, T)

void addAll(Map<?,? extends Serializable> objects)
Deprecated. Use putAll(java.util.Map)

void addListener(NamedCacheObjectExpirationListener listener)
Adds a listener for "object expired" events.

boolean allowClientCaching()
Deprecated. Use getAllowClientCaching()

void clear()
Clears the cache.

boolean contains(byte[] id)
Checks if the cache contains an object with the given ID.

boolean contains(CachedObjectId id)
Checks if the cache contains an object with the given ID.

boolean contains(String id)
Checks if the cache contains an object with the given ID.

boolean contains(UUID id)
Checks if the cache contains an object with the given ID.

CachedObjectId createKey(byte[] id)
Generates a CachedObjectId for an object identified by id.

static CachedObjectId createKey(com.scaleoutsoftware.soss.client.da.StateServerKey id)
Generates a CachedObjectId for an object identified by id.

CachedObjectId createKey(String id)
Generates a CachedObjectId for an object identified by id.

CachedObjectId createKey(UUID id)
Generates a CachedObjectId for an object identified by id.

void disableMethodInvocationEventHandling()
Disables this NamedCache instance for receiving StateServer method invocation events.

void disableObjectExpirationEventHandling()
Deprecated. the event handling will be automatically disabled when the last listener is unregistered removeListener(NamedCacheObjectExpirationListener)

void enableMethodInvocationEventHandling()
Enables this NamedCache instance for receiving StateServer method invocation events.

void enableObjectExpirationEventHandling()
Deprecated. the event handling will be automatically enabled when the listener is registered addListener(NamedCacheObjectExpirationListener)

Object get(byte[] id)
Gets a cached item using default parameters.





<T extends Serializable> 


T

get(CachedObjectId<T> id)
Gets a cached item using default parameters.

Object get(String id)
Gets a cached item using default parameters.

Object get(UUID id)
Gets a cached item using default parameters.

Map getAll(Collection ids)
Gets multiple objects from the cache based on a set of object identifiers.

boolean getAllowClientCaching()
Checks if client caching is enabled.

CreatePolicy getDefaultCreatePolicy()
Gets the CreatePolicy object used as parameters when adding objects to the cache using the add method.

GeoServerReadMode getDefaultReadMode()
Gets the default read mode (GeoServerReadMode) used by read operations.

int getLockRetryInterval()
Gets time between lock retries.

int getMaxLockAttempts()
Gets the number of lock attempts.

int getMaxReadThroughPendingAttempts()
Gets the number of read attempts made when another client has a backing store read-through operation pending.

ExtendedObjectMetadata getMetadata(byte[] id, boolean acquireLock)
Gets the index values for an object in the named cache.

ExtendedObjectMetadata getMetadata(byte[] id, ReadOptions options)
Gets the index values for an object in the named cache.

ExtendedObjectMetadata getMetadata(CachedObjectId id, boolean acquireLock)
Gets the index values for an object in the named cache.

ExtendedObjectMetadata getMetadata(CachedObjectId id, ReadOptions options)
Gets the index values for an object in the named cache.

ExtendedObjectMetadata getMetadata(String id, boolean acquireLock)
Gets the index values for an object in the named cache.

ExtendedObjectMetadata getMetadata(String id, ReadOptions options)
Gets the index values for an object in the named cache.

ExtendedObjectMetadata getMetadata(UUID id, boolean acquireLock)
Gets the index values for an object in the named cache.

ExtendedObjectMetadata getMetadata(UUID id, ReadOptions options)
Gets the index values for an object in the named cache.

Set<CachedObjectId> getObjectIds()
Returns IDs of all objects in cache.

int getReadPendingRetryInterval()
Gets milliseconds between read retries when backing store read-through operations are enabled.

com.scaleoutsoftware.soss.client.da.StateServerKey getStateServerKey(byte[] id)
Deprecated. CachedObjectId should be used instead of StateServerKey when performing cache operations. Use createKey(byte[]) to create CachedObjectIds

com.scaleoutsoftware.soss.client.da.StateServerKey getStateServerKey(CachedObjectId id)
Deprecated. CachedObjectId should be used instead of StateServerKey when performing cache operations. Use createKey(byte[]) to create CachedObjectIds

com.scaleoutsoftware.soss.client.da.StateServerKey getStateServerKey(String id)
Deprecated. CachedObjectId should be used instead of StateServerKey when performing cache operations. Use createKey(byte[]) to create CachedObjectIds

boolean getUseLocking()
Gets useLocking property which determines the locking behavior when using the NamedCache's get or add.

void insert(byte[] id, Serializable obj, CreatePolicy createPolicy, boolean updateIfExists, boolean lockAfterInsert)
Inserts a serializable object to a named cache.





<T extends Serializable> 


void

insert(CachedObjectId<T> id,
       T obj,
       CreatePolicy createPolicy,
       boolean updateIfExists,
       boolean lockAfterInsert)

Inserts a serializable object to a named cache.

void insert(String id, Serializable obj, CreatePolicy createPolicy, boolean updateIfExists, boolean lockAfterInsert)
Inserts a serializable object to a named cache.

void insert(UUID id, Serializable obj, CreatePolicy createPolicy, boolean updateIfExists, boolean lockAfterInsert)
Inserts a serializable object to a named cache.





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

invoke(Class<? extends Invokable<O,P,R>> processingClass,
       Class<O> clazz,
       Filter filter,
       P param,
       TimeSpan timeout)

Performs a parallel method invocation across the cache.The method invocations will occur on all hosts in parallel.





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

invoke(Class<? extends Invokable<O,P,R>> processingClass,
       NamedCacheFilter filter,
       P param,
       TimeSpan timeout)

Performs a parallel method invocation across the cache.





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

invoke(Invokable<O,P,R> processingClass,
       IndexCollection objects,
       P param,
       int timeout)

Deprecated. Use invoke(Class, NamedCacheFilter, java.io.Serializable, TimeSpan)





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

invoke(Invokable<O,P,R> processingClass,
       IndexCollection objects,
       P param,
       TimeSpan timeout)

Deprecated. Use invoke(Class, NamedCacheFilter, java.io.Serializable, TimeSpan)





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

invoke(Invokable<O,P,R> processingClass,
       NamedCacheFilter filter,
       P param,
       int timeout)

Deprecated. Use invoke(Class, NamedCacheFilter, java.io.Serializable, TimeSpan)

boolean isUseLocking()
Deprecated. Use getUseLocking()

void put(byte[] id, Serializable value)
Adds an item to the cache using default parameters.





<T extends Serializable> 


void

put(CachedObjectId<T> id,
    T value)

Adds an item to the cache using default parameters.

void put(String id, Serializable value)
Adds an item to the cache using default parameters.

void put(UUID id, Serializable value)
Adds an item to the cache using default parameters.

void putAll(Map<?,? extends Serializable> objects)
Efficiently adds a large collection of objects to the cache.

Set<CachedObjectId> query(IndexCollection ic)
Deprecated. Use query(NamedCacheFilter), queryKeys(Class, Filter), or queryObjects(Class, Filter)

Set<CachedObjectId> query(NamedCacheFilter filter)
Queries the cache for objects that match NamedCacheFilter.





<T> Set<CachedObjectId<T>>

queryKeys(Class<T> clazz,
          Filter filter)

Queries objects in the StateServer within this NamedCache returning a set of typed, keys (Set<CachedObjectId<T>>) corresponding only to those objects that are instances of type T and its subtypes and satisfy the criteria specified by filter.





<T extends Serializable> 


Collection<T>

queryObjects(Class<T> clazz,
             Filter filter)

Queries objects in the StateServer within this NamedCache returning a collection of objects (Collection<T>) containing only those objects that are instances of type T and its subtypes and satisfy the criteria specified by filter.

void releaseLock(byte[] id)
Releases the lock on a cached object.

void releaseLock(CachedObjectId id)
Releases the lock on a cached object.

void releaseLock(String id)
Releases the lock on a cached object.

void releaseLock(UUID id)
Releases the lock on a cached object.

void remove(byte[] id)
Removes the object from the cache.

void remove(CachedObjectId id)
Removes the object from the cache.

void remove(String id)
Removes the object from the cache.

void remove(UUID id)
Removes the object from the cache.

void removeListener(NamedCacheObjectExpirationListener listener)
Removes a listener for "object expired" events.

Object retrieve(byte[] id, boolean acquireLock)
Retrieves an object from the named cache.

Object retrieve(byte[] id, ReadOptions options)
Retrieves an object from the named cache.





<T extends Serializable> 


T

retrieve(CachedObjectId<T> id,
         boolean acquireLock)

Retrieves an object from the named cache.





<T extends Serializable> 


T

retrieve(CachedObjectId<T> id,
         ReadOptions options)

Retrieves an object from the named cache.

Object retrieve(String id, boolean acquireLock)
Retrieves an object from the named cache.

Object retrieve(String id, ReadOptions options)
Retrieves an object from the named cache.

Object retrieve(UUID id, boolean acquireLock)
Retrieves an object from the named cache.

Object retrieve(UUID id, ReadOptions options)
Retrieves an object from the named cache.

void setAllowClientCaching(boolean allowClientCaching)
Sets an flag indicating whether (deserialized) objects accessed by this cache should be kept in a client-side cache when they are written to StateServer.

void setBackingStoreAdapter(BackingStore backingStore, BackingStorePolicy policy)
Specifies a class that can be used by the NamedCache to automatically interact with an external data source (a database, typically) for read-through, write-through, refresh-ahead, and write-behind operations.

void setCustomSerialization(CustomSerializer cs)
Sets the custom serializer used to serialize objects when writing them to the SOSS cache and to deserialize objects when reading them from the SOSS cache.

void setDefaultCreatePolicy(CreatePolicy defaultCreatePolicy)
Sets a new CreatePolicy to be used as a default when creating objects.

void setDefaultGeoServerReadMode(GeoServerReadMode defaultGeoServerReadMode)
Sets the default read mode (GeoServerReadMode) to be used by read operations.

void setLockRetryInterval(int lockRetryInterval)
Sets time between lock retries.

void setMaxLockAttempts(int maxLockAttempts)
Sets the number of lock attempts.

void setMaxReadThroughPendingAttempts(int value)
Sets the number of read attempts made when performing a read-through operation from a backing store or a remote read from another store using GeoServer pull replication.

void setMetadata(byte[] id, ObjectMetadata metadata, boolean unlock)
Creates and updates settable index values for a cached object and optionally unlocks the object.

void setMetadata(CachedObjectId id, ObjectMetadata metadata, boolean unlock)
Creates and updates settable index values for a cached object and optionally unlocks the object.

void setMetadata(String id, ObjectMetadata metadata, boolean unlock)
Creates and updates settable index values for a cached object and optionally unlocks the object.

void setMetadata(UUID id, ObjectMetadata metadata, boolean unlock)
Creates and updates settable index values for a cached object and optionally unlocks the object.

void setReadPendingRetryInterval(int value)
Sets milliseconds between read retries when backing store read-through operations are enabled.

void setRemoteStores(List<RemoteStore> remoteStores)
Configures a list of remote stores that this NamedCache should use to look for objects that are not found in the local store.

void setUseLocking(boolean useLocking)
Determines the locking behavior when using the NamedCache's indexer to get or set cached items.





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

singleObjectInvoke(Class<? extends Invokable<O,P,R>> processingClass,
                   byte[] object,
                   P param,
                   TimeSpan timeout)

Performs a method invocation on a single object(SMI).





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

singleObjectInvoke(Class<? extends Invokable<O,P,R>> processingClass,
                   CachedObjectId<O> object,
                   P param,
                   TimeSpan timeout)

Performs a method invocation on a single object(SMI).





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

singleObjectInvoke(Class<? extends Invokable<O,P,R>> processingClass,
                   String object,
                   P param,
                   TimeSpan timeout)

Performs a method invocation on a single object(SMI).





<P extends Serializable,R extends Serializable,O extends Serializable> 


InvokeResult<R>

singleObjectInvoke(Class<? extends Invokable<O,P,R>> processingClass,
                   UUID object,
                   P param,
                   TimeSpan timeout)

Performs a method invocation on a single object(SMI).

void update(byte[] id, Serializable obj, boolean unlockAfterUpdate)
Deprecated. Use update(byte[], java.io.Serializable, UpdateOptions).

void update(byte[] id, Serializable obj, UpdateOptions options)
Updates an object in the named cache.





<T extends Serializable> 


void

update(CachedObjectId<T> id,
       T obj,
       boolean unlockAfterUpdate)

Deprecated. Use update(CachedObjectId, java.io.Serializable, UpdateOptions).





<T extends Serializable> 


void

update(CachedObjectId<T> id,
       T obj,
       UpdateOptions options)

Updates an object in the named cache.

void update(String id, Serializable obj, boolean unlockAfterUpdate)
Deprecated. Use update(String, java.io.Serializable, UpdateOptions).

void update(String id, Serializable obj, UpdateOptions options)
Updates an object in the named cache.

void update(UUID id, Serializable obj, boolean unlockAfterUpdate)
Deprecated. Use update(UUID, java.io.Serializable, UpdateOptions).

void update(UUID id, Serializable obj, UpdateOptions options)
Updates an object in the named cache.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

getDefaultReadMode

public GeoServerReadMode getDefaultReadMode()

Gets the default read mode (GeoServerReadMode) used by read operations.

setDefaultGeoServerReadMode

public void setDefaultGeoServerReadMode(GeoServerReadMode defaultGeoServerReadMode)

Sets the default read mode (GeoServerReadMode) to be used by read operations. Default read mode can be overridden by specifying read mode in ReadOptions and passing it to retrieve(String, ReadOptions). The initial value for default read mode is GeoServerReadMode.None.

Parameters:: defaultGeoServerReadMode - new default read mode

enableMethodInvocationEventHandling

public void enableMethodInvocationEventHandling()
                                         throws NamedCacheException

Enables this NamedCache instance for receiving StateServer method invocation events. Method invocation event handling is implicitly enabled on any named cache instance whenever any of the invoke(...) methods are executed. Remote clients must explicitly enable method invocation event handling to be eligible to receive method invocation request

Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

disableMethodInvocationEventHandling

public void disableMethodInvocationEventHandling()
                                          throws NamedCacheException

Disables this NamedCache instance for receiving StateServer method invocation events. Method invocation event handling is implicitly enabled on any named cache instance whenever any of the invoke(...) methods are executed. Remote clients must explicitly enable method invocation event handling to be eligible to receive method invocation request

Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

enableObjectExpirationEventHandling

public void enableObjectExpirationEventHandling()
                                         throws NamedCacheException

Deprecated. the event handling will be automatically enabled when the listener is registered addListener(NamedCacheObjectExpirationListener)

Enables delivery of object expiration events.

Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

disableObjectExpirationEventHandling

public void disableObjectExpirationEventHandling()
                                          throws NamedCacheException

Deprecated. the event handling will be automatically disabled when the last listener is unregistered removeListener(NamedCacheObjectExpirationListener)

Disables delivery of object expiration events.

Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

getAllowClientCaching

public boolean getAllowClientCaching()

Checks if client caching is enabled.

Returns:: true if client-side cache is enabled, false otherwise.
See Also:: setAllowClientCaching(boolean)

setAllowClientCaching

public void setAllowClientCaching(boolean allowClientCaching)

Sets an flag indicating whether (deserialized) objects accessed by this cache should be kept in a client-side cache when they are written to StateServer. Default is true.

To maximize access performance, SOSS adds an internal cache for deserialized data objects within its .NET client libraries. When reading objects, this client-side cache reduces access response time by eliminating data motion and deserialization overhead for objects that have not been updated in the SOSS distributed store. The allowClientCaching property controls whether the NamedCache will take advantage of this behavior.

The contents of the deserialized cache will automatically be invalidated if the object is changed or removed by any of the servers in the farm, so it will never return a stale version of the shared object. The client libraries always check with the SOSS service prior to returning the object in order to make sure that the deserialized version is up-to-date. While this check does involve a round-trip to the service, it is still much faster than retrieving and deserializing the entire object.

By default, allowClientCaching is set to true. Set this property to false prior to adding or updating an object in the cache to prevent a deserialized copy of the object from being stored on the client. Setting allowClientCaching to false also ensures that any deserialized copies that were previously held by this client will no longer be used.

The size of the deserialized cache is determined by the max_client_cache parameter in the soss_params.txt file (located in the ScaleOut StateServer program directory). By default, the cache can consume up to 100000 KB (100 MB) of memory. Once the limit has been met, the least recently used items will be purged from the cache to make way for new items. Setting the max_client_cache to 0 will disable the deserialized cache entirely, even if allowClientCaching is true.

Guidelines for Using the Deserialized Cache

The deserialized client cache, which is enabled by default, is a collection of object references retained by the SOSS client library to accelerate multiple retrieve accesses to an object stored in the SOSS service. Changes made by client code to an object held in the deserialized cache may cause the deserialized cache to return the changed object on a subsequent retrieve instead of the version that is stored in the SOSS service.

The deserialized cache is only intended to be used with either read-only access or in a locked retrieve/update usage pattern. In the retrieve/update usage pattern, an object stored in the SOSS service is retrieved and locked, optionally updated, and then unlocked (either by the update or by an explicit unlock access). This pattern enables multiple processes on the same or different servers to reliably update a shared object. No changes should be made to the retrieved object outside of the retrieve/update pair because these changes would not be propagated to the distributed cache.

Sometimes a client application may want to retrieve an object from SOSS, make some changes to the object, and then discard it after using it without persisting the changes to the SOSS service. This usage model can cause the deserialized cache to get out of sync with SOSS. If an application requires that changes be made to a retrieved object outside of the above read/update usage pattern, steps should be taken to avoid corrupting the deserialized cache. Either the cache should be disabled by setting the allowClientCaching property to false, or a deep copy of the retrieved object should be made with changes made only to this copy. Doing this will keep the locally cached object from getting out of sync with the authoritative object that is kept in the SOSS service.

Parameters:: allowClientCaching - true to enable client-side caching, false to disable it

getUseLocking

public boolean getUseLocking()

Gets useLocking property which determines the locking behavior when using the NamedCache's get or add. Default is false.

Returns:: useLocking property value
See Also:: setUseLocking(boolean)

setUseLocking

public void setUseLocking(boolean useLocking)

Determines the locking behavior when using the NamedCache's indexer to get or set cached items. Default is false.

The useLocking property causes the NamedCache's get(String)) accessor to lock the cached object in the SOSS server in order to prevent other clients from performing locked operations. Performing a get operation will cause the client to acquire a lock, and performing a put operation will cause the lock to be released.

This does not affect the locking behavior of the retrieve(String, ReadOptions), update(String, java.io.Serializable, UpdateOptions), or insert(String, java.io.Serializable, CreatePolicy, boolean, boolean) methods, which allow for fine-grained locking control.

If GeoServer pull replication is being used, performing a locking read operation on an object will cause the master copy of that object to migrate to the local store.

Parameters:: useLocking - useLocking property value

getDefaultCreatePolicy

public CreatePolicy getDefaultCreatePolicy()

Gets the CreatePolicy object used as parameters when adding objects to the cache using the add method.

Returns:: default CreatePolicy object
See Also:: setDefaultCreatePolicy(CreatePolicy)

setDefaultCreatePolicy

public void setDefaultCreatePolicy(CreatePolicy defaultCreatePolicy)

Sets a new CreatePolicy to be used as a default when creating objects.

Policies set by the setDefaultCreatePolicy property can be overridden on an object-by-object basis by adding those objects to the cache via the insert(string, object, CreatePolicy, bool, bool) method.

Objects added to the cache with a preemptionPriority of Normal will only be removed under low memory situations if LRU functionality is enabled in StateServer. Edit the soss_params.txt file in the StateServer installation directory to enable this feature: the lru_threshold parameter should be set to a percentage of the max_memory parameter. Eligible objects will be deleted using a least recently used algorithm once memory usage has passed the threshold.

Parameters:: defaultCreatePolicy - new default CreatePolicy object

getMaxLockAttempts

public int getMaxLockAttempts()

Gets the number of lock attempts. The default is 200 attempts.

Returns:: maxLockAttempts value
See Also:: setMaxLockAttempts(int)

setMaxLockAttempts

public void setMaxLockAttempts(int maxLockAttempts)

Sets the number of lock attempts.

The NamedCache will repeatedly attempt to acquire a lock in situations where another client already has a lock on the object. This property determines the number of times the NamedCache attempts to acquire a lock when a locking operation is performed before the method throws a NamedCacheObjectLockedException.

Parameters:: maxLockAttempts - new maxLockAttempts value

getLockRetryInterval

public int getLockRetryInterval()

Gets time between lock retries. Default is 500 milliseconds.

Returns:: lockRetryInterval value
See Also:: setLockRetryInterval(int)

setLockRetryInterval

public void setLockRetryInterval(int lockRetryInterval)

Sets time between lock retries. The NamedCache will repeatedly attempt to acquire a lock in situations where another client already has a lock on the object. The lockRetryInterval property gets or sets the amount of time (in milliseconds) between attempts to acquire an exclusive lock on the cached object using acquireLock, getting via get(when useLocking is true), and retrieve(CachedObjectId, boolean) property.

Parameters:: lockRetryInterval - new lockRetryInterval value in milliseconds

getMaxReadThroughPendingAttempts

public int getMaxReadThroughPendingAttempts()

Gets the number of read attempts made when another client has a backing store read-through operation pending. The default is 2400 attempts.

Returns:: number of read attempts
See Also:: setMaxReadThroughPendingAttempts(int)

setMaxReadThroughPendingAttempts

public void setMaxReadThroughPendingAttempts(int value)

Sets the number of read attempts made when performing a read-through operation from a backing store or a remote read from another store using GeoServer pull replication. The default is 2400 attempts.

When performing a read-through operation to a backing store, the NamedCache will repeatedly attempt to read an object from the SOSS server in situations where another client is concurrently performing a read-through operation from a database or other backing store. This property determines the number of times the NamedCache attempts to read the object from the cache before the method throws a NamedCacheReadThroughTimeoutException. The default is 2400 attempts.

Parameters to the setBackingStoreAdapter(BackingStore, BackingStorePolicy) method determine whether a NamedCache automatically tries to perform read-through operations.

When performing a remote read of an object from a another store via GeoServer pull replication, the NamedCache may need to repeatedly attempt to perform the remote read in a number of situations (for example, the master copy of the object may be in transit to a different remote store, or another thread in this client may already be trying to perform a remote read and is refreshing the local proxy of the object).

Use the setReadPendingRetryInterval(int) property to set the amount of time between retries.

Parameters:: value - new number of attempts
Throws:: IllegalArgumentException - if the property is set to a value less than 1.
See Also:: setReadPendingRetryInterval(int)

getReadPendingRetryInterval

public int getReadPendingRetryInterval()

Gets milliseconds between read retries when backing store read-through operations are enabled. Default is 10 milliseconds.

Returns:: pending retry interval
See Also:: setReadPendingRetryInterval(int)

setReadPendingRetryInterval

public void setReadPendingRetryInterval(int value)

Sets milliseconds between read retries when backing store read-through operations are enabled. Default is 10 milliseconds.

Parameters to the setBackingStoreAdapter(BackingStore, BackingStorePolicy) method determine whether a NamedCache automatically tries to perform read-through operations.

Use the setMaxReadThroughPendingAttempts(int) property to set the number of retries.

Parameters:: value - new pending retry interval in milliseconds
Throws:: IllegalArgumentException - if the property is set to a value less than 0.
See Also:: setMaxReadThroughPendingAttempts(int)

setCustomSerialization

public void setCustomSerialization(CustomSerializer cs)

Sets the custom serializer used to serialize objects when writing them to the SOSS cache and to deserialize objects when reading them from the SOSS cache. A custom serializer provides low level byte-by-byte control over serialization/deserialization.

Parameters:: cs - a custom serializer to use for this cache.
See Also:: CustomSerializer

addListener

public void addListener(NamedCacheObjectExpirationListener listener)
                 throws NamedCacheException

Adds a listener for "object expired" events. It receives only the events matching objects that are stored in this cache.

Parameters:: listener - new listener
Throws:: NamedCacheException

removeListener

public void removeListener(NamedCacheObjectExpirationListener listener)
                    throws NamedCacheException

Removes a listener for "object expired" events.

Parameters:: listener - listener to remove
Throws:: NamedCacheException

setBackingStoreAdapter

public void setBackingStoreAdapter(BackingStore backingStore,
                                   BackingStorePolicy policy)
                            throws NamedCacheException

Specifies a class that can be used by the NamedCache to automatically interact with an external data source (a database, typically) for read-through, write-through, refresh-ahead, and write-behind operations.

Use the setBackingStoreAdapter method to enable read-through, write-through, refresh-ahead, and write-behind behavior when ScaleOut StateServer is being used as cache for a persistent backing store (such as a database).

Use the enableAsyncOperations parameter to enable asynchronous refresh-ahead and write-behind operations.

If read-through operations are enabled, it is not desirable for every client process to simultaneously query the database when a cache miss occurs, so the enableReadThrough parameter will affect the behavior of the NamedCache's retrieve, and get methods when a cache miss occurs. The first client to perform a retrieval operation on an object that's missing from the cache will have its BackingStore.load implementation invoked. While the backing store is being queried, other clients requesting this object will repeatedly poll until the object has been inserted into the cache. The frequency of the polling behavior is controlled through the readPendingRetryInterval and maxReadThroughPendingAttempts properties. The enableWriteThrough parameter is used to indicate to the StateServer that the client will be performing write-through operations via an implementation of BackingStore.store.

In situations where the client does not have access to the database, the backingStore parameter may be null. If enableReadThrough or enableWriteThrough are true but the backingStore parameter is null, it indicates to the StateServer that the cache needs to be automatically populated (or its changes need to be automatically written to the database), but this client is not able to perform the database operation. The StateServer will then trigger an asynchronous read/write database operation on a different client that has registered itself as having a backing store adapter present. This method can be called repeatedly to change the API's behavior.

Parameters:: backingStore - a BackingStore instance that implements custom logic for the retrieval and storage of objects in a database or other persistent data store. Setting this parameter to null indicates that this client should not perform any read-through operations.; policy - contains options to control how a named cache interacts with a backing store.
Throws:: NamedCacheException

setRemoteStores

public void setRemoteStores(List<RemoteStore> remoteStores)
                     throws NamedCacheException

Configures a list of remote stores that this NamedCache should use to look for objects that are not found in the local store. Read calls will check remote stores in the order that they are listed. If a missing object is found in one of the specified remote stores then it will be replicated to the local store using GeoServer pull replication. Backing store operations cannot be used in conjunction with GeoServer pull replication.

Parameters:: remoteStores - list of RemoteStore objects or null to turn off remote store look up
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error while sending store list to the server.

get

public <T extends Serializable> T get(CachedObjectId<T> id)
                           throws NamedCacheException

Gets a cached item using default parameters.

If useLocking is true then a "get" operation will cause the object to be locked in the SOSS server, and no other clients will be able to acquire a lock until the lock from this instance of the NamedCache is released (either by setting the object to a new value or calling releaseLock) or update an existing item with the same ID. Passing a null value will cause an object to be removed from the cache. The useLocking property is honored when setting a cached item to null, so the API will attempt to acquire a lock on the object prior to removing it if useLocking is true.

If GeoServer pull replication is being used, the NamedCache's defaultGeoServerReadMode(setDefaultGeoServerReadMode(GeoServerReadMode)) property will determine this getter's GeoServer read behavior when accessing an object in a remote store.

Note that every get call will cause a round trip to the SOSS service and could result in the retrieval or update of a cached object across the network.

Parameters:: id - identifier of the object in the cache.
Returns:: the object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - if useLocking is true but the object is locked by another client.; NamedCacheReadThroughTimeoutException - if backing store read-through or GeoServer pull replication is used with this NamedCache and the retrieval of the object is delayed beyond the number of retries specified by maxReadThroughPendingAttempts; NamedCacheException - thrown if the NamedCache has experienced an internal error.

get

public Object get(byte[] id)
           throws NamedCacheException

Gets a cached item using default parameters.

Note that every get call will cause a round trip to the SOSS service and could result in the retrieval or update of a cached object across the network.

Parameters:: id - identifier of the object in the cache.
Returns:: the object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - if useLocking is true but the object is locked by another client.; NamedCacheReadThroughTimeoutException - if backing store read-through or GeoServer pull replication is used with this NamedCache and the retrieval of the object is delayed beyond the number of retries specified by maxReadThroughPendingAttempts; NamedCacheException - thrown if the NamedCache has experienced an internal error.

get

public Object get(String id)
           throws NamedCacheException

Gets a cached item using default parameters.

Note that every get call will cause a round trip to the SOSS service and could result in the retrieval or update of a cached object across the network.

Parameters:: id - identifier of the object in the cache.
Returns:: the object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - if useLocking is true but the object is locked by another client.; NamedCacheReadThroughTimeoutException - if backing store read-through or GeoServer pull replication is used with this NamedCache and the retrieval of the object is delayed beyond the number of retries specified by maxReadThroughPendingAttempts; NamedCacheException - thrown if the NamedCache has experienced an internal error.

get

public Object get(UUID id)
           throws NamedCacheException

Gets a cached item using default parameters.

Note that every get call will cause a round trip to the SOSS service and could result in the retrieval or update of a cached object across the network.

Parameters:: id - identifier of the object in the cache.
Returns:: the object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - if useLocking is true but the object is locked by another client.; NamedCacheReadThroughTimeoutException - if backing store read-through or GeoServer pull replication is used with this NamedCache and the retrieval of the object is delayed beyond the number of retries specified by maxReadThroughPendingAttempts; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getAll

public Map getAll(Collection ids)
           throws NamedCacheException

Gets multiple objects from the cache based on a set of object identifiers. No locking is performed by this overload.

Objects will not be locked upon retrieval through this method, even if useLocking is true. If there is no matching object for a specified key in the cache, it will have an entry in the returned map with a null value.

Parameters:: ids - Set of object identifiers. IDs must be of type String, byte[] (16 or 32 bytes long), UUID or CachedObjectId.
Returns:: a Map where keys in the collection are the supplied identifiers and whose values are the objects retrieved from the cache.
Throws:: NamedCacheObjectLockedException - if useLocking is true but the object is locked by another client.; NamedCacheReadThroughTimeoutException - if backing store read-through or GeoServer pull replication is used with this NamedCache and the retrieval of the object is delayed beyond the number of retries specified by maxReadThroughPendingAttempts; NamedCacheException - thrown if the NamedCache has experienced an internal error.

retrieve

public <T extends Serializable> T retrieve(CachedObjectId<T> id,
                                           boolean acquireLock)
                                throws NamedCacheException

Retrieves an object from the named cache.

This method optionally locks the object in SOSS to prevent other clients from updating or removing the object. The useLocking property is not taken into consideration by this method. If the acquireLock parameter is true, this call will block until the lock is acquired or the maxLockAttempts limit has been met. The lock affects both an object and its metadata, and it can be released through a call to releaseLock, update, remove, or setMetadata. If no subsequent call is made, the lock will automatically expire after approximately 90 seconds. Passing true to an object that is already locked by the same instance of the NamedCache will refresh the lock by resetting the 90 second lock timeout.

Parameters:: id - object identifier.; acquireLock - indicates that the method should attempt to acquire or refresh a lock when reading the object.
Returns:: Object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

retrieve

public Object retrieve(byte[] id,
                       boolean acquireLock)
                throws NamedCacheException

Retrieves an object from the named cache.

Parameters:: id - object identifier.; acquireLock - indicates that the method should attempt to acquire or refresh a lock when reading the object.
Returns:: Object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

retrieve

public Object retrieve(String id,
                       boolean acquireLock)
                throws NamedCacheException

Retrieves an object from the named cache.

Parameters:: id - object identifier.; acquireLock - indicates that the method should attempt to acquire or refresh a lock when reading the object.
Returns:: object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

retrieve

public Object retrieve(UUID id,
                       boolean acquireLock)
                throws NamedCacheException

Retrieves an object from the named cache.

Parameters:: id - object identifier.; acquireLock - indicates that the method should attempt to acquire or refresh a lock when reading the object.
Returns:: object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

retrieve

public <T extends Serializable> T retrieve(CachedObjectId<T> id,
                                           ReadOptions options)
                                throws NamedCacheException

Retrieves an object from the named cache.

Parameters:: id - object identifier.; options - a ReadOptions object, containing locking and remote store options.
Returns:: object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

retrieve

public Object retrieve(String id,
                       ReadOptions options)
                throws NamedCacheException

Retrieves an object from the named cache.

Parameters:: id - object identifier.; options - a ReadOptions object, containing locking and remote store options.
Returns:: object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

retrieve

public Object retrieve(byte[] id,
                       ReadOptions options)
                throws NamedCacheException

Retrieves an object from the named cache.

Parameters:: id - object identifier.; options - a ReadOptions object, containing locking and remote store options.
Returns:: object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

retrieve

public Object retrieve(UUID id,
                       ReadOptions options)
                throws NamedCacheException

Retrieves an object from the named cache.

Parameters:: id - object identifier.; options - a ReadOptions object, containing locking and remote store options.
Returns:: object stored in the cache, or null if the object is not in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

put

public <T extends Serializable> void put(CachedObjectId<T> id,
                                         T value)
         throws NamedCacheException

Adds an item to the cache using default parameters. If the object already exists in the cache then it will be updated.

The put method will use the cache policy settings from the defaultCreatePolicy property when adding an object to the cache. If an object with the specified id already exists in the cache then it will be updated. The insert method can be used instead of the put method if this automatic update behavior is not desired.

If an existing cached object is being updated instead of added then the current defaultCreatePolicy settings will not be applied to the updated object; the object will continue to use the CreatePolicy policies that were in effect when the object was originally added to the cache. The object must be explicitly removed and re-added to the cache for new CreatePolicy policies to take effect.

Use the insert method to add items with specific CreatePolicy parameters instead of the default ones.

This method can not be used to update an object when useLocking is set to true if the object is locked by another thread.

Parameters:: id - object identifier.; value - serializable object to store in the cache. If the argument is null then an object with the same id will be removed from the cache.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

put

public void put(byte[] id,
                Serializable value)
         throws NamedCacheException

Adds an item to the cache using default parameters. If the object already exists in the cache then it will be updated.

Use the insert method to add items with specific CreatePolicy parameters instead of the default ones.

This method can not be used to update an object when useLocking is set to true if the object is locked by another thread.

Parameters:: id - object identifier.; value - serializable object to store in the cache. If the argument is null then an object with the same id will be removed from the cache.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

put

public void put(String id,
                Serializable value)
         throws NamedCacheException

Adds an item to the cache using default parameters. If the object already exists in the cache then it will be updated.

Use the insert method to add items with specific CreatePolicy parameters instead of the default ones.

This method can not be used to update an object when useLocking is set to true if the object is locked by another thread.

Parameters:: id - object identifier.; value - serializable object to store in the cache. If the argument is null then an object with the same id will be removed from the cache.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

put

public void put(UUID id,
                Serializable value)
         throws NamedCacheException

Adds an item to the cache using default parameters. If the object already exists in the cache then it will be updated.

Use the insert method to add items with specific CreatePolicy parameters instead of the default ones.

This method can not be used to update an object when useLocking is set to true if the object is locked by another thread.

Parameters:: id - object identifier.; value - serializable object to store in the cache. If the argument is null then an object with the same id will be removed from the cache.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

putAll

public void putAll(Map<?,? extends Serializable> objects)
            throws NamedCacheException

Efficiently adds a large collection of objects to the cache.

The putAll method takes a Map of objects and adds them to the cache. Keys to objects in the hashtable must be of type CachedObjectId, String, UUID or byte[]. If the cache already contains items corresponding to keys in the map then they will be updated. If the Map contains a null value then the corresponding item in the SOSS cache will be removed.

The method leverages the distributed, multithreaded architecture of ScaleOut StateServer to reduce the total time needed to add a large number of objects. This method also can improve performance several times if a small number of large objects need to be added to the SOSS cache.

By default, the method will use the default cache policy from the (defaultCreatePolicy) property when adding an object to the cache, and no metadata for the object will be set. Alternatively, each object in the map optionally can specify its own cache policy and associated metadata. To assign cache policy and metadata on an object-by-object basis, the associated value within the dictionary should contain SossObjectDescriptor objects instead of the data object to be stored in the SOSS cache. In this case, the SossObjectDescriptor's SossObjectDescriptor.getPolicy() and SossObjectDescriptor.getMetadata() properties will be used to assign the object's policy and metadata, and putAll will use this descriptor to obtain a reference to the data object. The map may contain a mix of simple data objects and SossObjectDescriptor objects.

Parameters:: objects - A map containing objects to store in the cache with keys of type CachedObjectId, String, UUID or byte[], and with values that are either data objects to be stored or SossObjectDescriptor objects.
Throws:: NamedCacheBulkAddException - if errors are encountered during the add operation. If the objects parameter is a collection of SossObjectDescriptor elements, those elements will contain specific exceptions in their SossObjectDescriptor.getInsertException() property (or null, if the associated object was added to the cache successfully) after the add operation is complete.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

insert

public <T extends Serializable> void insert(CachedObjectId<T> id,
                                            T obj,
                                            CreatePolicy createPolicy,
                                            boolean updateIfExists,
                                            boolean lockAfterInsert)
            throws NamedCacheException

Inserts a serializable object to a named cache. If an object with the same ID already exists in the cache then it can optionally be updated.

Passing null into the obj parameter is not allowed; use remove(CachedObjectId) to delete an object from the cache.

If updateIfExists is true, and a cache object is being updated instead of inserted, then the policy settings in the createPolicy parameter will not be applied to the updated object; instead, the object will continue use the CreatePolicy policies that were in effect when the object was originally added to the cache. The object must be explicitly removed and re-inserted into the cache for new CreatePolicy policies to take effect.

Objects added to the cache with a ObjectPreemptionPriority of Normal will only be removed under low memory situations if LRU functionality is enabled in StateServer. Edit the soss_params.txt file in the StateServer installation directory to enable this feature: the lru_threshold parameter should be set to a percentage of the max_memory parameter. Eligible objects will be deleted using a least recently used algorithm once memory usage has passed the threshold.

Parameters:: id - object identifier.; obj - serializable object to store in the cache. The argument cannot be null.; createPolicy - CreatePolicy instance containing extended cache policy information for the object.; updateIfExists - determines behavior if the object already exists in the cache. If true, the object will be updated; if false, a NamedCacheObjectAlreadyExistsException will be thrown if the object already exists.; lockAfterInsert - 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, allowing other clients to lock the object.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheObjectAlreadyExistsException - thrown if the object exists and the updateIfExists parameter is false.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

insert

public void insert(byte[] id,
                   Serializable obj,
                   CreatePolicy createPolicy,
                   boolean updateIfExists,
                   boolean lockAfterInsert)
            throws NamedCacheException

Inserts a serializable object to a named cache. If an object with the same ID already exists in the cache then it can optionally be updated.

Passing null into the obj parameter is not allowed; use remove(CachedObjectId) to delete an object from the cache.

Parameters:: id - object identifier.; obj - serializable object to store in the cache. The argument cannot be null.; createPolicy - CreatePolicy instance containing extended cache policy information for the object.; updateIfExists - determines behavior if the object already exists in the cache. If true, the object will be updated; if false, a NamedCacheObjectAlreadyExistsException will be thrown if the object already exists.; lockAfterInsert - 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, allowing other clients to lock the object.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheObjectAlreadyExistsException - thrown if the object exists and the updateIfExists parameter is false.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

insert

public void insert(String id,
                   Serializable obj,
                   CreatePolicy createPolicy,
                   boolean updateIfExists,
                   boolean lockAfterInsert)
            throws NamedCacheException

Inserts a serializable object to a named cache. If an object with the same ID already exists in the cache then it can optionally be updated.

Passing null into the obj parameter is not allowed; use remove(CachedObjectId) to delete an object from the cache.

Parameters:: id - object identifier.; obj - serializable object to store in the cache. The argument cannot be null.; createPolicy - CreatePolicy instance containing extended cache policy information for the object.; updateIfExists - determines behavior if the object already exists in the cache. If true, the object will be updated; if false, a NamedCacheObjectAlreadyExistsException will be thrown if the object already exists.; lockAfterInsert - 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, allowing other clients to lock the object.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheObjectAlreadyExistsException - thrown if the object exists and the updateIfExists parameter is false.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

insert

public void insert(UUID id,
                   Serializable obj,
                   CreatePolicy createPolicy,
                   boolean updateIfExists,
                   boolean lockAfterInsert)
            throws NamedCacheException

Inserts a serializable object to a named cache. If an object with the same ID already exists in the cache then it can optionally be updated.

Passing null into the obj parameter is not allowed; use remove(CachedObjectId) to delete an object from the cache.

Parameters:: id - object identifier.; obj - serializable object to store in the cache. The argument cannot be null.; createPolicy - CreatePolicy instance containing extended cache policy information for the object.; updateIfExists - determines behavior if the object already exists in the cache. If true, the object will be updated; if false, a NamedCacheObjectAlreadyExistsException will be thrown if the object already exists.; lockAfterInsert - 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, allowing other clients to lock the object.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheObjectAlreadyExistsException - thrown if the object exists and the updateIfExists parameter is false.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

update

public <T extends Serializable> void update(CachedObjectId<T> id,
                                            T obj,
                                            UpdateOptions options)
            throws NamedCacheException

Updates an object in the named cache.

This method updates an object in the named cache and allows for fine-grained control over locking of the object. Unlike the add accessor, the update method does not honor the useLocking property. The acquireLock or retrieve methods must be called prior to update if the object needs to be locked.

Care should be taken when performing unlocked updates on objects. An unlocked update will not block for locks held by another clients, so other clients may have the object data changed underneath them despite the locks they hold.

In situations where collisions are infrequent (for example, when objects in the cache are updated rarely), an optimistic locking approach can be taken with updates. Set the options parameter's locking mode property to UpdateLockingMode.UpdateIfSameVersion when performing the update. Objects that use optimistic locking must implement the OptimisticConcurrencyVersionHolder interface.

Parameters:: id - object identifier.; obj - the new value for the object in the shared cache. The argument cannot be null.; options - UpdateOptions used when performing the update operation. The lockingMode property controls locking behavior of the update call. If UpdateLockingMode.None and the object is locked, the lock will be retained by the caller. If the object is not locked by this instance of the NamedCache then the option is ignored. If UpdateLockingMode.UnlockAfterUpdate and the object is locked, the lock will be released by the caller upon completion of the update. If the object is not locked by this instance of the NamedCache then the option is ignored. If UpdateLockingMode.UpdateIfSameVersion, an optimistic locking update will be performed. The update will succeed only if the version sent by the client matches the current version in the StateServer - otherwise an NamedCacheOptimisticLockException will be thrown. If a pessimistic lock is being held by this instance of the NamedCache then this option will cause a NamedCacheException to be thrown. Objects that use the UpdateIfSameVersion option must implement the OptimisticConcurrencyVersionHolder interface.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the cache.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

update

public void update(byte[] id,
                   Serializable obj,
                   UpdateOptions options)
            throws NamedCacheException

Updates an object in the named cache.

Parameters:: id - object identifier.; obj - the new value for the object in the shared cache. The argument cannot be null.; options - UpdateOptions used when performing the update operation. The lockingMode property controls locking behavior of the update call. If UpdateLockingMode.None and the object is locked, the lock will be retained by the caller. If the object is not locked by this instance of the NamedCache then the option is ignored. If UpdateLockingMode.UnlockAfterUpdate and the object is locked, the lock will be released by the caller upon completion of the update. If the object is not locked by this instance of the NamedCache then the option is ignored. If UpdateLockingMode.UpdateIfSameVersion, an optimistic locking update will be performed. The update will succeed only if the version sent by the client matches the current version in the StateServer--otherwise an NamedCacheOptimisticLockException will be thrown. If a pessimistic lock is being held by this instance of the NamedCache then this option will cause a NamedCacheException to be thrown. Objects that use the UpdateIfSameVersion option must implement the OptimisticConcurrencyVersionHolder interface.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the cache.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

update

public void update(String id,
                   Serializable obj,
                   UpdateOptions options)
            throws NamedCacheException

Updates an object in the named cache.

Parameters:: id - object identifier.; obj - the new value for the object in the shared cache. The argument cannot be null.; options - UpdateOptions used when performing the update operation. The lockingMode property controls locking behavior of the update call. If UpdateLockingMode.None and the object is locked, the lock will be retained by the caller. If the object is not locked by this instance of the NamedCache then the option is ignored. If UpdateLockingMode.UnlockAfterUpdate and the object is locked, the lock will be released by the caller upon completion of the update. If the object is not locked by this instance of the NamedCache then the option is ignored. If UpdateLockingMode.UpdateIfSameVersion, an optimistic locking update will be performed. The update will succeed only if the version sent by the client matches the current version in the StateServer--otherwise an NamedCacheOptimisticLockException will be thrown. If a pessimistic lock is being held by this instance of the NamedCache then this option will cause a NamedCacheException to be thrown. Objects that use the UpdateIfSameVersion option must implement the OptimisticConcurrencyVersionHolder interface.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the cache.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

update

public void update(UUID id,
                   Serializable obj,
                   UpdateOptions options)
            throws NamedCacheException

Updates an object in the named cache.

Parameters:: id - object identifier.; obj - the new value for the object in the shared cache. The argument cannot be null.; options - UpdateOptions used when performing the update operation. The lockingMode property controls locking behavior of the update call. If UpdateLockingMode.None and the object is locked, the lock will be retained by the caller. If the object is not locked by this instance of the NamedCache then the option is ignored. If UpdateLockingMode.UnlockAfterUpdate and the object is locked, the lock will be released by the caller upon completion of the update. If the object is not locked by this instance of the NamedCache then the option is ignored. If UpdateLockingMode.UpdateIfSameVersion, an optimistic locking update will be performed. The update will succeed only if the version sent by the client matches the current version in the StateServer--otherwise an NamedCacheOptimisticLockException will be thrown. If a pessimistic lock is being held by this instance of the NamedCache then this option will cause a NamedCacheException to be thrown. Objects that use the UpdateIfSameVersion option must implement the OptimisticConcurrencyVersionHolder interface.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the cache.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

remove

public void remove(CachedObjectId id)
            throws NamedCacheException

Removes the object from the cache. No exception will be thrown and no action will be taken if the specified object does not exist in the cache.

If the cached object was previously locked via this NamedCache instance, the lock will be released if the remove operation completes successfully.

Care should be taken when performing unlocked removals of objects. An unlocked removal will not block for locks held by another clients, so other clients may have the object removed from the cache underneath them despite the locks they hold. Use the acquireLock method prior to calling remove to ensure that no other clients are holding a lock on the object.

Parameters:: id - object identifier.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

remove

public void remove(byte[] id)
            throws NamedCacheException

Removes the object from the cache. No exception will be thrown and no action will be taken if the specified object does not exist in the cache.

If the cached object was previously locked via this NamedCache instance, the lock will be released if the remove operation completes successfully.

Parameters:: id - object identifier.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

remove

public void remove(String id)
            throws NamedCacheException

Removes the object from the cache. No exception will be thrown and no action will be taken if the specified object does not exist in the cache.

If the cached object was previously locked via this NamedCache instance, the lock will be released if the remove operation completes successfully.

Parameters:: id - object identifier.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

remove

public void remove(UUID id)
            throws NamedCacheException

Removes the object from the cache. No exception will be thrown and no action will be taken if the specified object does not exist in the cache.

If the cached object was previously locked via this NamedCache instance, the lock will be released if the remove operation completes successfully.

Parameters:: id - object identifier.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

clear

public void clear()
           throws NamedCacheException

Clears the cache.

Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

setMetadata

public void setMetadata(CachedObjectId id,
                        ObjectMetadata metadata,
                        boolean unlock)
                 throws NamedCacheException

Creates and updates settable index values for a cached object and optionally unlocks the object. The setMetadata method does not honor the useLocking property. Use the acquireLock or retrieve methods prior to calling setMetadata if the object needs to be locked.

Care should be taken when performing unlocked metadata changes on objects. An unlocked setMetadata operation will not block for locks held by another clients, so other clients may have the object metadata changed underneath them despite the locks they hold.

Parameters:: id - object identifier.; metadata - the new metadata for the object, containing a collection of index values.; unlock - if the object was previously locked with the current named cache and value is true then the object will be unlocked after the operation completes.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the shared cache.; NamedCacheObjectLockedException - thrown if the lock on the cached object exceeded the 90 second timeout period and another client acquired the lock.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

setMetadata

public void setMetadata(byte[] id,
                        ObjectMetadata metadata,
                        boolean unlock)
                 throws NamedCacheException

Parameters:: id - object identifier.; metadata - the new metadata for the object, containing a collection of index values.; unlock - if the object was previously locked with the current named cache and value is true then the object will be unlocked after the operation completes.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the shared cache.; NamedCacheObjectLockedException - thrown if the lock on the cached object exceeded the 90 second timeout period and another client acquired the lock.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

setMetadata

public void setMetadata(String id,
                        ObjectMetadata metadata,
                        boolean unlock)
                 throws NamedCacheException

Parameters:: id - object identifier.; metadata - the new metadata for the object, containing a collection of index values.; unlock - if the object was previously locked with the current named cache and value is true then the object will be unlocked after the operation completes.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the shared cache.; NamedCacheObjectLockedException - thrown if the lock on the cached object exceeded the 90 second timeout period and another client acquired the lock.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

setMetadata

public void setMetadata(UUID id,
                        ObjectMetadata metadata,
                        boolean unlock)
                 throws NamedCacheException

Parameters:: id - object identifier.; metadata - the new metadata for the object, containing a collection of index values.; unlock - if the object was previously locked with the current named cache and value is true then the object will be unlocked after the operation completes.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the shared cache.; NamedCacheObjectLockedException - thrown if the lock on the cached object exceeded the 90 second timeout period and another client acquired the lock.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getMetadata

public ExtendedObjectMetadata getMetadata(CachedObjectId id,
                                          ReadOptions options)
                                   throws NamedCacheException

Gets the index values for an object in the named cache. This method optionally locks the object in SOSS to prevent other clients from updating or removing the object. The useLocking property is not taken into consideration by this method. If the acquireLock parameter is true, this call will block until the lock is acquired or the maxLockAttempts limit has been met. The lock affects the entire object, not just its metadata, and can be released through a call to releaseLock, update, remove, or setMetadata. If no subsequent call is made, the lock will automatically expire after approximately 90 seconds. Passing true to an object that is already locked by the same instance of the NamedCache will refresh the lock by resetting the 90 second lock timeout.

Parameters:: id - object identifier.; options - ReadOptions containing locking settings and remote store read mode
Returns:: ExtendedObjectMetadata instance for the object, or null if the object is not found in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getMetadata

public ExtendedObjectMetadata getMetadata(byte[] id,
                                          ReadOptions options)
                                   throws NamedCacheException

Parameters:: id - object identifier.; options - ReadOptions containing locking settings and remote store read mode
Returns:: ExtendedObjectMetadata instance for the object, or null if the object is not found in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getMetadata

public ExtendedObjectMetadata getMetadata(String id,
                                          ReadOptions options)
                                   throws NamedCacheException

Parameters:: id - object identifier.; options - ReadOptions containing locking settings and remote store read mode
Returns:: ExtendedObjectMetadata instance for the object, or null if the object is not found in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getMetadata

public ExtendedObjectMetadata getMetadata(UUID id,
                                          ReadOptions options)
                                   throws NamedCacheException

Parameters:: id - object identifier.; options - ReadOptions containing locking settings and remote store read mode
Returns:: ExtendedObjectMetadata instance for the object, or null if the object is not found in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getMetadata

public ExtendedObjectMetadata getMetadata(CachedObjectId id,
                                          boolean acquireLock)
                                   throws NamedCacheException

Parameters:: id - object identifier.; acquireLock - if true, indicates that the method should attempt to acquire a lock on the object when reading it from the server.
Returns:: ExtendedObjectMetadata instance for the object, or null if the object is not found in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getMetadata

public ExtendedObjectMetadata getMetadata(byte[] id,
                                          boolean acquireLock)
                                   throws NamedCacheException

Parameters:: id - object identifier.; acquireLock - if true, indicates that the method should attempt to acquire a lock on the object when reading it from the server.
Returns:: ExtendedObjectMetadata instance for the object, or null if the object is not found in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getMetadata

public ExtendedObjectMetadata getMetadata(String id,
                                          boolean acquireLock)
                                   throws NamedCacheException

Parameters:: id - object identifier.; acquireLock - if true, indicates that the method should attempt to acquire a lock on the object when reading it from the server.
Returns:: ExtendedObjectMetadata instance for the object, or null if the object is not found in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getMetadata

public ExtendedObjectMetadata getMetadata(UUID id,
                                          boolean acquireLock)
                                   throws NamedCacheException

Gets the index values for an object in the named cache. This method optionally locks the object in SOSS to prevent other clients from updating or removing the object. The useLocking property is not taken into consideration by this method. If the acquireLock) parameter is true, this call will block until the lock is acquired or the maxLockAttempts limit has been met. The lock affects the entire object, not just its metadata, and can be released through a call to releaseLock, update, remove, or setMetadata. If no subsequent call is made, the lock will automatically expire after approximately 90 seconds. Passing true to an object that is already locked by the same instance of the NamedCache will refresh the lock by resetting the 90 second lock timeout.

Parameters:: id - object identifier.; acquireLock - if true, indicates that the method should attempt to acquire a lock on the object when reading it from the server.
Returns:: ExtendedObjectMetadata instance for the object, or null if the object is not found in the cache.
Throws:: NamedCacheObjectLockedException - thrown if acquireLock is true but the object is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

queryKeys

public <T> Set<CachedObjectId<T>> queryKeys(Class<T> clazz,
                                            Filter filter)
                                 throws NamedCacheException

Type T and/or its supertypes should contain annotations, otherwise NamedCacheIndexAttributeException will be thrown. For being able to search for objects of specific class one should annotate this class or one of its superclasses with SossIndexAttribute. This will save type information to cache without saving any property attributes.

To construct the filter, use FilterFactory methods. If this field is null, the query will search for all objects of type T and its subtypes.

Type Parameters:: T - type of the objects to be found.
Parameters:: clazz - a class object representing type T of the objects to be found; filter - a Filter containing search criteria.
Returns:: a set containing keys corresponding to the found objects
Throws:: NamedCacheIndexAttributeException - thrown if filter contains illegal search criteria.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

queryObjects

public <T extends Serializable> Collection<T> queryObjects(Class<T> clazz,
                                                           Filter filter)
                                                throws NamedCacheException

To construct the filter, use FilterFactory methods. If this field is null, the query will search for all objects of type T and its subtypes.

Type Parameters:: T - type of the objects to be found.
Parameters:: clazz - a class object representing type T of the objects to be found; filter - a Filter containing search criteria.
Returns:: a set containing keys corresponding to the found objects
Throws:: NamedCacheIndexAttributeException - thrown if filter contains illegal search criteria.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

query

public Set<CachedObjectId> query(NamedCacheFilter filter)
                          throws NamedCacheException

Queries the cache for objects that match NamedCacheFilter.

Parameters:: filter - NamedCacheFilter containing filter criteria or null to query all objects.
Returns:: Set of matching CachedObjectId identifiers.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

invoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> invoke(Class<? extends Invokable<O,P,R>> processingClass,
                                                                                                     NamedCacheFilter filter,
                                                                                                     P param,
                                                                                                     TimeSpan timeout)
                                            throws NamedCacheException

Performs a parallel method invocation across the cache. The method invocations will occur on all hosts in parallel. All method invocations on a given host will share a single instance of the parameter object param. To define invoke operation supply a class implementing Invokable and avaliable on all client applications across the cache. During the invocations objects will be divided among clients. Invokable.eval(java.io.Serializable, java.io.Serializable, EvalArgs) method would be used to calculate the result for each object, then results would be merged pairwise with Invokable.merge(R, R).

Parameters:: processingClass - an Invokable-implementing class for processing items; filter - a NamedCacheFilter with filter criteria for objects to invoke on or null value for all objects in the cache; param - a parameters object, shared by all evaluations; timeout - a timeout to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

invoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> invoke(Class<? extends Invokable<O,P,R>> processingClass,
                                                                                                     Class<O> clazz,
                                                                                                     Filter filter,
                                                                                                     P param,
                                                                                                     TimeSpan timeout)
                                            throws NamedCacheException

Performs a parallel method invocation across the cache.The method invocations will occur on all hosts in parallel. All method invocations on a given host will share a single instance of the parameter object param. To define invoke operation supply a class implementing Invokable and avaliable on all client applications across the cache. During the invocations objects will be divided among clients. Invokable.eval(java.io.Serializable, java.io.Serializable, EvalArgs) method would be used to calculate the result for each object, then results would be merged pairwise with Invokable.merge(R, R).

Invocation is performed on objects that are instances of type T and its subtypes and satisfy the criteria specified by filter.

To construct the filter, use FilterFactory methods. If this field is null, the query will search for all objects of type T and its subtypes.

Parameters:: processingClass - an Invokable-implementing class for processing items; clazz - type of the objects to invoke on; filter - a Filter containing search criteria.; param - a parameters object, shared by all evaluations; timeout - a timeout to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

singleObjectInvoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> singleObjectInvoke(Class<? extends Invokable<O,P,R>> processingClass,
                                                                                                                 CachedObjectId<O> object,
                                                                                                                 P param,
                                                                                                                 TimeSpan timeout)
                                                        throws NamedCacheException

Performs a method invocation on a single object(SMI). Invokes the Ivokable.eval method on the StateServer object identified by its id within this named cache. Ivokable.merge method is ignored. The method invocation will be passed the parameter object param. The method invocation will occur at a host which currently has the object in its store.

Parameters:: processingClass - an Invokable-implementing class for processing items; object - an object to invoke on; param - a parameters object for this invoke; timeout - a timeout to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

singleObjectInvoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> singleObjectInvoke(Class<? extends Invokable<O,P,R>> processingClass,
                                                                                                                 byte[] object,
                                                                                                                 P param,
                                                                                                                 TimeSpan timeout)
                                                        throws NamedCacheException

Parameters:: processingClass - an Invokable-implementing class for processing items; object - an object to invoke on; param - a parameters object for this invoke; timeout - a timeout to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

singleObjectInvoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> singleObjectInvoke(Class<? extends Invokable<O,P,R>> processingClass,
                                                                                                                 String object,
                                                                                                                 P param,
                                                                                                                 TimeSpan timeout)
                                                        throws NamedCacheException

Parameters:: processingClass - an Invokable-implementing class for processing items; object - an object to invoke on; param - a parameters object for this invoke; timeout - a timeout to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

singleObjectInvoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> singleObjectInvoke(Class<? extends Invokable<O,P,R>> processingClass,
                                                                                                                 UUID object,
                                                                                                                 P param,
                                                                                                                 TimeSpan timeout)
                                                        throws NamedCacheException

Parameters:: processingClass - an Invokable-implementing class for processing items; object - an object to invoke on; param - a parameters object for this invoke; timeout - a timeout to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

acquireLock

public void acquireLock(CachedObjectId id)
                 throws NamedCacheException

Locks the cached object in SOSS to prevent other clients from updating or removing it. This call will block until the lock is acquired or the maxLockAttempts limit has been met. The lock is released through a call to releaseLock, update, setMetadata, or remove. Setting the object to a new value through add while useLocking is true will also cause the lock to be released. If no subsequent call is made, the lock will expire after approximately 90 seconds. Calling this method on an instance of CachedDataAccessor that already has a lock on the cached object will reset the 90 second lock timeout.

Parameters:: id - object identifier.
Throws:: NamedCacheObjectLockedException - thrown if the object is already locked by another client.; NamedCacheObjectNotFoundException - thrown if the object does not exist.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

acquireLock

public void acquireLock(byte[] id)
                 throws NamedCacheException

Parameters:: id - object identifier.
Throws:: NamedCacheObjectLockedException - thrown if the object is already locked by another client.; NamedCacheObjectNotFoundException - thrown if the object does not exist.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

acquireLock

public void acquireLock(String id)
                 throws NamedCacheException

Parameters:: id - object identifier.
Throws:: NamedCacheObjectLockedException - thrown if the object is already locked by another client.; NamedCacheObjectNotFoundException - thrown if the object does not exist.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

acquireLock

public void acquireLock(UUID id)
                 throws NamedCacheException

Parameters:: id - object identifier.
Throws:: NamedCacheObjectLockedException - thrown if the object is already locked by another client.; NamedCacheObjectNotFoundException - thrown if the object does not exist.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

releaseLock

public void releaseLock(CachedObjectId id)
                 throws NamedCacheException

Releases the lock on a cached object.

Calling releaseLock on an object that is not locked by this instance of the NamedCache has no effect.

Parameters:: id - object identifier.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

releaseLock

public void releaseLock(byte[] id)
                 throws NamedCacheException

Releases the lock on a cached object.

Calling releaseLock on an object that is not locked by this instance of the NamedCache has no effect.

Parameters:: id - object identifier.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

releaseLock

public void releaseLock(String id)
                 throws NamedCacheException

Releases the lock on a cached object.

Calling releaseLock on an object that is not locked by this instance of the NamedCache has no effect.

Parameters:: id - object identifier.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

releaseLock

public void releaseLock(UUID id)
                 throws NamedCacheException

Releases the lock on a cached object.

Calling releaseLock on an object that is not locked by this instance of the NamedCache has no effect.

Parameters:: id - object identifier.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

contains

public boolean contains(CachedObjectId id)
                 throws NamedCacheException

Checks if the cache contains an object with the given ID.

The result of the contains method is only accurate at the moment of the method's invocation; other clients may add or remove the object from the cache in the instant between the call to contains and any subsequent code. As such, the contains method is not well-suited for applications which require distributed synchronization and should only be used in a single-client scenario.

A safer, more reliable approach to distributed synchronization is to first attempt a retrieval of the cached object through a call to retrieve, which returns the object's data and optionally locks the object for exclusive use by the client. If the object does not exist then it can be added to the cache by using add, which are safe to use with other clients that may be trying to add the object at the same instant. See the example in the NamedCache overview for an illustration of this pattern.

Parameters:: id - object identifier.
Returns:: true if the object is in cache, otherwise false
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

contains

public boolean contains(byte[] id)
                 throws NamedCacheException

Checks if the cache contains an object with the given ID.

Parameters:: id - object identifier.
Returns:: true if the object is in cache, otherwise false
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

contains

public boolean contains(String id)
                 throws NamedCacheException

Checks if the cache contains an object with the given ID.

Parameters:: id - object identifier.
Returns:: true if the object is in cache, otherwise false
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

contains

public boolean contains(UUID id)
                 throws NamedCacheException

Checks if the cache contains an object with the given ID.

Parameters:: id - object identifier.
Returns:: true if the object is in cache, otherwise false
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

createKey

public CachedObjectId createKey(byte[] id)
                         throws NamedCacheException

Generates a CachedObjectId for an object identified by id.

Parameters:: id - object identifier.
Returns:: CachedObjectId for object identifier.
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

createKey

public CachedObjectId createKey(String id)
                         throws NamedCacheException

Generates a CachedObjectId for an object identified by id.

Parameters:: id - object identifier.
Returns:: CachedObjectId for object identifier.
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

createKey

public CachedObjectId createKey(UUID id)
                         throws NamedCacheException

Generates a CachedObjectId for an object identified by id.

Parameters:: id - object identifier.
Returns:: CachedObjectId for object identifier.
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

createKey

public static CachedObjectId createKey(com.scaleoutsoftware.soss.client.da.StateServerKey id)
                                throws NamedCacheException

Generates a CachedObjectId for an object identified by id.

Parameters:: id - object identifier.
Returns:: CachedObjectId for object identifier.
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

getObjectIds

public Set<CachedObjectId> getObjectIds()
                                 throws NamedCacheException

Returns IDs of all objects in cache.

Returns:: a Set containing IDs of all objects in cache.
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

invoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> invoke(Invokable<O,P,R> processingClass,
                                                                                                     IndexCollection objects,
                                                                                                     P param,
                                                                                                     TimeSpan timeout)
                                            throws NamedCacheException

Deprecated. Use invoke(Class, NamedCacheFilter, java.io.Serializable, TimeSpan)

Parameters:: processingClass - an Invokable-implementing class for processing items; objects - an IndexList for performing a query to determine the objects to invoke on; param - a parameters object, shared by all evaluations; timeout - a timeout to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

invoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> invoke(Invokable<O,P,R> processingClass,
                                                                                                     IndexCollection objects,
                                                                                                     P param,
                                                                                                     int timeout)
                                            throws NamedCacheException

Deprecated. Use invoke(Class, NamedCacheFilter, java.io.Serializable, TimeSpan)

Performs a parallel method invocation across the cache.The method invocations will occur on all hosts in parallel. All method invocations on a given host will share a single instance of the parameter object param. To define invoke operation supply a class implementing Invokable and avaliable on all client applications across the cache. During the invocations objects will be divided among clients. Invokable.eval(java.io.Serializable, java.io.Serializable, EvalArgs) method would be used to calculate the result for each object, then results would be merged pairwise with Invokable.merge(R, R).

Parameters:: processingClass - an Invokable-implementing class for processing items; objects - an IndexList for performing a query to determine the objects to invoke on; param - a parameters object, shared by all evaluations; timeout - a timeout in seconds to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

invoke

public <P extends Serializable,R extends Serializable,O extends Serializable> InvokeResult<R> invoke(Invokable<O,P,R> processingClass,
                                                                                                     NamedCacheFilter filter,
                                                                                                     P param,
                                                                                                     int timeout)
                                            throws NamedCacheException

Deprecated. Use invoke(Class, NamedCacheFilter, java.io.Serializable, TimeSpan)

Performs a parallel method invocation across the cache.The method invocations will occur on all hosts in parallel. All method invocations on a given host will share a single instance of the parameter object param. To define invoke operation supply a class implementing Invokable and avaliable on all client applications across the cache. During the invocations objects will be divided among clients. Invokable.eval(java.io.Serializable, java.io.Serializable, EvalArgs) method would be used to calculate the result for each object, then results would be merged pairwise with Invokable.merge(R, R).

Parameters:: processingClass - an Invokable-implementing class for processing items; filter - a NamedCacheFilter with filter criteria for objects to invoke on; param - a parameters object, shared by all evaluations; timeout - a timeout to wait for the invocation to complete
Returns:: InvokeResult containing the result object and information about errors (if any)
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

allowClientCaching

public boolean allowClientCaching()

Deprecated. Use getAllowClientCaching()

Checks if client caching is enabled.

Returns:: true if client-side cache is enabled, false otherwise.

add

public <T extends Serializable> void add(CachedObjectId<T> id,
                                         T value)
         throws NamedCacheException

Deprecated. Use put(com.scaleoutsoftware.soss.client.CachedObjectId, T)

Adds an item to the cache using default parameters. If the object already exists in the cache then it will be updated.

Parameters:: id - object identifier.; value - serializable object to store in the cache. If the argument is null then an object with the same id will be removed from the cache.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

add

public <T extends Serializable> void add(UUID id,
                                         T value)
         throws NamedCacheException

Deprecated. Use put(com.scaleoutsoftware.soss.client.CachedObjectId, T)

Adds an item to the cache using default parameters. If the object already exists in the cache then it will be updated.

Parameters:: id - object identifier.; value - serializable object to store in the cache. If the argument is null then an object with the same id will be removed from the cache.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

add

@Deprecated
public <T extends Serializable> void add(byte[] id,
                                                    T value)
         throws NamedCacheException

Deprecated. Use put(com.scaleoutsoftware.soss.client.CachedObjectId, T)

Adds an item to the cache using default parameters. If the object already exists in the cache then it will be updated.

Parameters:: id - object identifier.; value - serializable object to store in the cache. If the argument is null then an object with the same id will be removed from the cache.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

add

@Deprecated
public <T extends Serializable> void add(String id,
                                                    T value)
         throws NamedCacheException

Deprecated. Use put(com.scaleoutsoftware.soss.client.CachedObjectId, T)

Adds an item to the cache using default parameters. If the object already exists in the cache then it will be updated.

Parameters:: id - object identifier.; value - serializable object to store in the cache. If the argument is null then an object with the same id will be removed from the cache.
Throws:: NamedCacheObjectLockedException - thrown if the object is already in the cache and is locked by another client.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

isUseLocking

public boolean isUseLocking()

Deprecated. Use getUseLocking()

Gets useLocking property which determines the locking behavior when using the NamedCache's get or add. Default is false.

Returns:: useLocking property value
See Also:: setUseLocking(boolean)

addAll

public void addAll(Map<?,? extends Serializable> objects)
            throws NamedCacheException

Deprecated. Use putAll(java.util.Map)

Efficiently adds a large collection of objects to the cache.

Parameters:: objects - A map containing objects to store in the cache with keys of type CachedObjectId, String, UUID or byte[], and with values that are either data objects to be stored or SossObjectDescriptor objects.
Throws:: NamedCacheBulkAddException - if errors are encountered during the add operation. If the objects parameter is a collection of SossObjectDescriptor elements, those elements will contain specific exceptions in their SossObjectDescriptor.getInsertException() property (or null, if the associated object was added to the cache successfully) after the add operation is complete.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

update

public <T extends Serializable> void update(CachedObjectId<T> id,
                                            T obj,
                                            boolean unlockAfterUpdate)
            throws NamedCacheException

Deprecated. Use update(CachedObjectId, java.io.Serializable, UpdateOptions).

Updates an object in the named cache.

The update method updates an object in the named cache and allows for fine-grained control over locking of the object. Unlike the get accessor, the update method does not honor the useLocking property. The acquireLock or retrieve methods must be called prior to update if the object needs to be locked.

Parameters:: id - object identifier.; obj - the new value for the object in the shared cache. The argument cannot be null.; unlockAfterUpdate - if the NamedCache instance is not holding a lock for the specified object, this parameter is ignored.If value is true and the NamedCache is holding a lock for the object then the lock will be released when the update operation completes.If value is false and the NamedCache is holding a lock for the object then the lock will continue to be held when the update operation completes.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the cache.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

update

public void update(byte[] id,
                   Serializable obj,
                   boolean unlockAfterUpdate)
            throws NamedCacheException

Deprecated. Use update(byte[], java.io.Serializable, UpdateOptions).

Updates an object in the named cache.

The update method updates an object in the named cache and allows for fine-grained control over locking of the object. Unlike add, the update method does not honor the useLocking property. The acquireLock or retrieve methods must be called prior to update if the object needs to be locked.

Parameters:: id - object identifier.; obj - the new value for the object in the shared cache. The argument cannot be null.; unlockAfterUpdate - if the NamedCache instance is not holding a lock for the specified object, this parameter is ignored.If value is true and the NamedCache is holding a lock for the object then the lock will be released when the update operation completes.If value is false and the NamedCache is holding a lock for the object then the lock will continue to be held when the update operation completes.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the cache.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

update

public void update(String id,
                   Serializable obj,
                   boolean unlockAfterUpdate)
            throws NamedCacheException

Deprecated. Use update(String, java.io.Serializable, UpdateOptions).

Updates an object in the named cache.

Parameters:: id - object identifier.; obj - the new value for the object in the shared cache. The argument cannot be null.; unlockAfterUpdate - if the NamedCache instance is not holding a lock for the specified object, this parameter is ignored.If value is true and the NamedCache is holding a lock for the object then the lock will be released when the update operation completes.If value is false and the NamedCache is holding a lock for the object then the lock will continue to be held when the update operation completes.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the cache.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

update

public void update(UUID id,
                   Serializable obj,
                   boolean unlockAfterUpdate)
            throws NamedCacheException

Deprecated. Use update(UUID, java.io.Serializable, UpdateOptions).

Updates an object in the named cache.

Parameters:: id - object identifier.; obj - the new value for the object in the shared cache. The argument cannot be null.; unlockAfterUpdate - if the NamedCache instance is not holding a lock for the specified object, this parameter is ignored.If value is true and the NamedCache is holding a lock for the object then the lock will be released when the update operation completes.If value is false and the NamedCache is holding a lock for the object then the lock will continue to be held when the update operation completes.
Throws:: NamedCacheObjectNotFoundException - thrown if the object to update does not exist in the cache.; NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

query

public Set<CachedObjectId> query(IndexCollection ic)
                          throws NamedCacheException

Deprecated. Use query(NamedCacheFilter), queryKeys(Class, Filter), or queryObjects(Class, Filter)

Queries the cache for objects that match IndexCollection.

Parameters:: ic - IndexCollection containing filter criteria.
Returns:: Set of matching CachedObjectId identifiers.
Throws:: NamedCacheServerUnavailableException - thrown if ScaleOut StateServer is unavailable or has experienced an internal error.; NamedCacheException - thrown if the NamedCache has experienced an internal error.

getStateServerKey

public com.scaleoutsoftware.soss.client.da.StateServerKey getStateServerKey(CachedObjectId id)

Deprecated. CachedObjectId should be used instead of StateServerKey when performing cache operations. Use createKey(byte[]) to create CachedObjectIds

Generates the StateServerKey for a given object.

Parameters:: id - object identifier.
Returns:: StateServerKey for the given ID.

getStateServerKey

public com.scaleoutsoftware.soss.client.da.StateServerKey getStateServerKey(byte[] id)
                                                                     throws NamedCacheException

Deprecated. CachedObjectId should be used instead of StateServerKey when performing cache operations. Use createKey(byte[]) to create CachedObjectIds

Generates the StateServerKey for a given object.

Parameters:: id - object identifier.
Returns:: StateServerKey for the given ID.
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

getStateServerKey

public com.scaleoutsoftware.soss.client.da.StateServerKey getStateServerKey(String id)
                                                                     throws NamedCacheException

Deprecated. CachedObjectId should be used instead of StateServerKey when performing cache operations. Use createKey(byte[]) to create CachedObjectIds

Generates the StateServerKey for a given object.

Parameters:: id - object identifier.
Returns:: StateServerKey for the given ID.
Throws:: NamedCacheException - thrown if the NamedCache has experienced an internal error.

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.scaleoutsoftware.soss.client Class NamedCache

getDefaultReadMode

setDefaultGeoServerReadMode

enableMethodInvocationEventHandling

disableMethodInvocationEventHandling

enableObjectExpirationEventHandling

disableObjectExpirationEventHandling

getAllowClientCaching

setAllowClientCaching

getUseLocking

setUseLocking

getDefaultCreatePolicy

setDefaultCreatePolicy

getMaxLockAttempts

setMaxLockAttempts

getLockRetryInterval

setLockRetryInterval

getMaxReadThroughPendingAttempts

setMaxReadThroughPendingAttempts

getReadPendingRetryInterval

setReadPendingRetryInterval

setCustomSerialization

addListener

removeListener

setBackingStoreAdapter

setRemoteStores

get

get

get

get

getAll

retrieve

retrieve

retrieve

retrieve

retrieve

retrieve

retrieve

retrieve

put

put

put

put

putAll

insert

insert

insert

insert

update

update

update

update

remove

remove

remove

remove

clear

setMetadata

setMetadata

setMetadata

setMetadata

getMetadata

getMetadata

getMetadata

getMetadata

getMetadata

getMetadata

getMetadata

getMetadata

queryKeys

queryObjects

query

invoke

invoke

singleObjectInvoke

singleObjectInvoke

singleObjectInvoke

singleObjectInvoke

acquireLock

acquireLock

com.scaleoutsoftware.soss.client
Class NamedCache