org.jgroups.blocks

Interface ReplicationReceiver

Known Implementing Classes:
TransactionalHashtable

public interface ReplicationReceiver

Implementation of this interface needs to register with ReplicationManager and will receive updates to be applied to its locally replicated data. If locks are used the implementation is resposible for lock acquisition and management. To do so, it probably needs to maintain a lock table (keys = resource objects, values = transactions) to associate resources with locks and possibly a transaction table (keys = transactions, values = locks) to keep track of all locks for a given transaction (to commit/release all modifications/locks for a given transaction).
Author:
Bela Ban Nov 19 2002

Method Summary

void
commit(Xid transaction)
Commit the modifications to the locally replicated data and release all locks.
Object
receive(Xid transaction, byte[] data, byte[] lock_info, long lock_acquisition_timeout, long lock_lease_timeout, boolean use_locks)
Receives data sent by a sender to all group members and applies update to locally replicated data.
void
rollback(Xid transaction)
Discard all modifications and release all locks.

Method Details

commit

public void commit(Xid transaction)
Commit the modifications to the locally replicated data and release all locks. If the receive() call already applied the changes, then this method is a nop.

receive

public Object receive(Xid transaction,
                      byte[] data,
                      byte[] lock_info,
                      long lock_acquisition_timeout,
                      long lock_lease_timeout,
                      boolean use_locks)
            throws LockingException,
                   UpdateException
Receives data sent by a sender to all group members and applies update to locally replicated data. This is the result of a ReplicationManager.send(Address,byte[],boolean,long,Xid,byte[],long,long,boolean) call.
Parameters:
transaction - The transaction under which all locks will be acquired. Will be null if no locks are used (e.g. use_locks is null).
data - The data to be modified. In case of a database, this data would have to be stored in stable storage, and would only be applied on a commit(). In case of a distributed replicated in-memory data structure, the update might be applied directly and the subsequent commit() or rollback() might be ignored. Note that this argument may contain the resource to be locked; in this case the lock_info parameter might be null.
lock_info - Information about the resource(s) to be locked. Will be null if no locks are used (e.g. use_locks is null). Can also be null even if locks are used, e.g. when the resource(s) to be locked are an implicit part of data.
lock_acquisition_timeout - If locks are used, the number of milliseconds to wait for a lock to be acquired. If this time elapses, a TimeoutException will be thrown. A value of 0 means to wait forever. If use_locks is false, this value is ignored.
lock_lease_timeout - The number of milliseconds to hold on to the lock, once it is acquired. A value of 0 means to never release the lock until commit() or rollback() are called.
use_locks - Whether to use locking or not. If this value is false, all lock-related arguments will be ignored, regardless of whether they are non-null.
Returns:
Object A return value, the semantics of which are determined by caller of ReplicationManager.send and the receiver. If no special value should be returned, null can be returned. Note that in the latter case, null is still treated as a response (in the synchronous call).
Throws:
LockingException - Thrown when a lock on a resource cannot be acquired
UpdateException - Thrown when the update fails (application semantics)

rollback

public void rollback(Xid transaction)
Discard all modifications and release all locks. If the receive() call already applied the changes, this method will not be able to rollback the modifications, but will only release the locks.

Copyright B) 2001,2002 www.jgroups.com . All Rights Reserved.