Package com.opencloud.rhino.facilities.replicatedstorage

Interface ReplicatedStorage

public interface ReplicatedStorage

A ReplicatedStorage instance represents a lookup table that is transparently shared between instances of a resource adaptor entity on all nodes of a Rhino cluster. Resource adaptors use this facility to share state about activities, so that any node can continue processing any activity in the event of a failure.

Resource adaptors specify replicated storage instances via extension deployment descriptor entries. Resource adaptors should specify an instance for each type of activity or state they are dealing with. Each instance represents a different "key space", so the keys used to lookup state must be unique within each instance.

Resource adaptor implementors should ensure that the ActivityHandle implementation contains enough information to retrieve activity state stored in the ReplicatedStorage instance. The ActivityHandle is automatically replicated by the SLEE, and in the event of a failover, the SLEE will inform each surviving resource adaptor object of the resource adaptor entity which activity handles it should adopt. See ReplicatingResourceAdaptor.adoptActivities().

All methods on ReplicatedStorage are mandatory transactional. That is, if a transaction is not already in progress, the resource adaptor must initiate a transaction before calling any methods on a replicated storage instance. The resource adaptor should use the SLEE transaction manager availble from ResourceAdaptorContext.getSleeTransactionManager() to check if a transaction is active and create one if required. The resource adaptor should register a Synchronization listener for the transaction so that it will continue processing only after the transaction committed successfully, so the replicated state is consistent across all nodes. Similarly if the transaction fails to commit, or an exception is thrown by one of the ReplicatedStorage methods, the resource adaptor should take appropriate action such as returning NACKs to the resource.

See Also:

ReplicatingResourceAdaptor

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ReplicatedStorage.Entry	Implemented by SLEE.
static interface	ReplicatedStorage.Key	RAs must implement this interface.
static class	ReplicatedStorage.LookupFlag	Optional flags that can be used to affect state lookup behaviour in a retrieve(Key, EnumSet) operation.
static interface	ReplicatedStorage.PartitionedKey	An optional extension interface to ReplicatedStorage.Key that allows a resource adaptor to provide a specific partition key with a regular key.
static class	ReplicatedStorage.UpdateFlag	Optional flags that can be used to affect state management behaviour in an update(Entry, byte[], EnumSet) operation.

Field Summary

Fields

Modifier and Type	Field	Description
static int	MODE_OPTIMISTIC	Optimistic locking strategy
static int	MODE_PESSIMISTIC	Pessimistic locking strategy

Method Summary

Modifier and Type	Method	Description
ReplicatedStorage.Entry	create(ReplicatedStorage.Key key, byte[] initialValue)	Create a new entry in the replicated storage
void	remove(ReplicatedStorage.Entry entry)	Remove an entry from replicated storage.
boolean	remove(ReplicatedStorage.Key key)	Remove an entry from replicated storage.
ReplicatedStorage.Entry	retrieve(ReplicatedStorage.Key key)	Retrieve an entry from replicated storage.
ReplicatedStorage.Entry	retrieve(ReplicatedStorage.Key key, EnumSet<ReplicatedStorage.LookupFlag> flags)	Retrieve an entry from replicated storage with optional additional flags that affect remote lookup behaviour.
void	update(ReplicatedStorage.Entry entry, byte[] newValue)	Update an existing entry.
void	update(ReplicatedStorage.Entry entry, byte[] newValue, EnumSet<ReplicatedStorage.UpdateFlag> flags)	Update an existing entry.

Field Detail

MODE_OPTIMISTIC

static final int MODE_OPTIMISTIC

Optimistic locking strategy

See Also:

Constant Field Values

MODE_PESSIMISTIC

static final int MODE_PESSIMISTIC

Pessimistic locking strategy

See Also:

Constant Field Values

Method Detail

create

ReplicatedStorage.Entry create(ReplicatedStorage.Key key,
                               byte[] initialValue)
                        throws ReplicatedStorageException

Create a new entry in the replicated storage

Parameters:

key - the ReplicatedStorage.Key that uniquely identifies the entry.

initialValue - the initial value of the data to be stored in the entry.

Returns:

a reference to the entry that can be used when updating or removing the entry. Only valid within the transaction that created the entry.

Throws:

ReplicatedStorageException - if an error occurs in the underlying replicated storage implementation.

remove

boolean remove(ReplicatedStorage.Key key)
        throws ReplicatedStorageException

Remove an entry from replicated storage.

This method allows an entry to be removed by key, thereby eliminating the two-step read-then-delete sequence that is otherwise necessary when using the remove(Entry) operation.

Parameters:

key - the ReplicatedStorage.Key that uniquely identifies the entry.

Returns:

true if an entry with the specified key was found and removed, false if an entry with the key was not found.

Throws:

ReplicatedStorageException - if an error occurs in the underlying replicated storage implementation.

Since:

Rhino 2.6.1

update

void update(ReplicatedStorage.Entry entry,
            byte[] newValue)
     throws ReplicatedStorageException

Update an existing entry.

This method is equivalent to updateEntry(entry, newValue, EnumSet.noneOf(UpdateFlag.class).

Parameters:

entry - a ReplicatedStorage.Entry that was obtained in the current transaction by calling retrieve(com.opencloud.rhino.facilities.replicatedstorage.ReplicatedStorage.Key) or create(com.opencloud.rhino.facilities.replicatedstorage.ReplicatedStorage.Key, byte[]).

newValue - the new value of the data to be stored in the entry.

Throws:

ReplicatedStorageException - if an error occurs in the underlying replicated storage implementation.

update

void update(ReplicatedStorage.Entry entry,
            byte[] newValue,
            EnumSet<ReplicatedStorage.UpdateFlag> flags)
     throws ReplicatedStorageException

Update an existing entry.

If the entry being updated was retrieved remotely, the ReplicatedStorage.LookupFlag.SUPPRESS_LOCAL_INSERT flag was used during the retrieve, and the entry does not already exist locally, then the ReplicatedStorage.UpdateFlag.ENABLE_LOCAL_UPDATE_INSERT flag must be used when calling this method in the first instance to allow the state to be added to the local store. Failing to do so will result in the method throwing a ReplicatedStorageException indicating that an attempt was made to update a non-existing entry.

If the entry already exists locally then the ReplicatedStorage.UpdateFlag.ENABLE_LOCAL_UPDATE_INSERT flag, if present, is ignored.

Parameters:

entry - a ReplicatedStorage.Entry that was obtained in the current transaction by calling retrieve(com.opencloud.rhino.facilities.replicatedstorage.ReplicatedStorage.Key) or create(com.opencloud.rhino.facilities.replicatedstorage.ReplicatedStorage.Key, byte[]).

newValue - the new value of the data to be stored in the entry.

flags - optional set of flags that affect update behaviour. May be null.

Throws:

ReplicatedStorageException - if an error occurs in the underlying replicated storage implementation.

Since:

Rhino 2.7.0

retrieve

ReplicatedStorage.Entry retrieve(ReplicatedStorage.Key key)
                          throws ReplicatedStorageException

Retrieve an entry from replicated storage.

This method is equivalent to retrieve(key, EnumSet.noneOf(LookupFlag.class).

Parameters:

key - the ReplicatedStorage.Key that uniquely identifies the entry.

Returns:

the ReplicatedStorage.Entry or null if not found.

Throws:

ReplicatedStorageException - if an error occurs in the underlying replicated storage implementation.

retrieve

ReplicatedStorage.Entry retrieve(ReplicatedStorage.Key key,
                                 EnumSet<ReplicatedStorage.LookupFlag> flags)
                          throws ReplicatedStorageException

Retrieve an entry from replicated storage with optional additional flags that affect remote lookup behaviour.

Parameters:

key - the ReplicatedStorage.Key that uniquely identifies the entry.

flags - optional set of flags that affect retrieval behaviour. May be null.

Returns:

the ReplicatedStorage.Entry or null if not found.

Throws:

ReplicatedStorageException - if an error occurs in the underlying replicated storage implementation.

Since:

Rhino 2.7.0

remove

void remove(ReplicatedStorage.Entry entry)
     throws ReplicatedStorageException

Remove an entry from replicated storage.

Parameters:

entry - the ReplicatedStorage.Entry to be removed.

Throws:

ReplicatedStorageException - if an error occurs in the underlying replicated storage implementation.