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.
ReplicatingResourceAdaptor
Modifier and Type | Interface and Description |
---|---|
static interface |
ReplicatedStorage.Entry
Implemented by SLEE.
|
static interface |
ReplicatedStorage.Key
RAs must implement this interface.
|
Modifier and Type | Field and Description |
---|---|
static int |
MODE_OPTIMISTIC
Optimistic locking strategy
|
static int |
MODE_PESSIMISTIC
Pessimistic locking strategy
|
Modifier and Type | Method and 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.
|
void |
update(ReplicatedStorage.Entry entry,
byte[] newValue)
Update an existing entry.
|
static final int MODE_OPTIMISTIC
Optimistic locking strategy
static final int MODE_PESSIMISTIC
Pessimistic locking strategy
ReplicatedStorage.Entry create(ReplicatedStorage.Key key, byte[] initialValue) throws ReplicatedStorageException
Create a new entry in the replicated storage
key
- the ReplicatedStorage.Key
that uniquely identifies the entry.initialValue
- the initial value of the data to be stored in the entry.ReplicatedStorageException
- if an error occurs in the underlying replicated storage implementation.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.
key
- the ReplicatedStorage.Key
that uniquely identifies the entry.true
if an entry with the specified key was found and removed, false
if an entry with the key was not found.ReplicatedStorageException
- if an error occurs in the underlying replicated storage implementation.void update(ReplicatedStorage.Entry entry, byte[] newValue) throws ReplicatedStorageException
Update an existing entry.
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.ReplicatedStorageException
- if an error occurs in the underlying replicated storage implementation.ReplicatedStorage.Entry retrieve(ReplicatedStorage.Key key) throws ReplicatedStorageException
Retrieve an entry from replicated storage.
key
- the ReplicatedStorage.Key
that uniquely identifies the entry.ReplicatedStorage.Entry
or null
if not found.ReplicatedStorageException
- if an error occurs in the underlying replicated storage implementation.void remove(ReplicatedStorage.Entry entry) throws ReplicatedStorageException
Remove an entry from replicated storage.
entry
- the ReplicatedStorage.Entry
to be removed.ReplicatedStorageException
- if an error occurs in the underlying replicated storage implementation.