org.jgroups.blocks

Class ReplicationManager

public class ReplicationManager extends Object implements RequestHandler

Class to propagate updates to a number of nodes in various ways:
  1. Asynchronous
  2. Synchronous
  3. Synchronous with locking

Note: This class is experimental as of Oct 2002

Author: Bela Ban Oct 2002

Field Summary
protected MessageDispatcherdisp
Used to broadcast updates and receive responses (latter only in synchronous case)
protected Loglog
Constructor Summary
ReplicationManager(Channel channel, MessageListener ml, MembershipListener l, ReplicationReceiver receiver)
Creates an instance of ReplicationManager on top of a Channel
ReplicationManager(PullPushAdapter adapter, Serializable id, MessageListener ml, MembershipListener l, ReplicationReceiver receiver)
Creates an instance of ReplicationManager on top of a PullPushAdapter
Method Summary
Xidbegin()
Create a new transaction.
Xidbegin(int transaction_mode)
Create a new transaction.
voidcommit(Xid transaction)
Commits all modifications sent to the receivers via ReplicationManager and releases all locks associated with this transaction.
Objecthandle(Message msg)
protected voidhandleCommit(Xid transaction)
protected voidhandleRollback(Xid transaction)
protected ObjecthandleSend(ReplicationData data)
voidrollback(Xid transaction)
Discards all modifications sent to the receivers via ReplicationManager and releases all locks associated with this transaction.
RspListsend(Address dest, byte[] data, boolean synchronous, long synchronous_timeout, Xid transaction, byte[] lock_info, long lock_acquisition_timeout, long lock_lease_timeout, boolean use_locks)
Sends a request to all members of the group.
voidsetMembershipListener(MembershipListener l)
voidsetReplicationReceiver(ReplicationReceiver handler)
voidstop()

Field Detail

disp

protected MessageDispatcher disp
Used to broadcast updates and receive responses (latter only in synchronous case)

log

protected final Log log

Constructor Detail

ReplicationManager

public ReplicationManager(Channel channel, MessageListener ml, MembershipListener l, ReplicationReceiver receiver)
Creates an instance of ReplicationManager on top of a Channel

ReplicationManager

public ReplicationManager(PullPushAdapter adapter, Serializable id, MessageListener ml, MembershipListener l, ReplicationReceiver receiver)
Creates an instance of ReplicationManager on top of a PullPushAdapter

Method Detail

begin

public Xid begin()
Create a new transaction. The transaction will be used to send updates, identify updates in the same transaction, and eventually commit or rollback the changes associated with the transaction.

Returns: Xid A unique transaction

Throws: Exception Thrown when local_addr is null

begin

public Xid begin(int transaction_mode)
Create a new transaction. The tracsion will be used to send updates, identify updates in the same transaction, and eventually commit or rollback the changes associated with the transaction.

Parameters: transaction_mode Mode in which the transaction should run. Possible values are Xid.DIRTY_READS, Xid.READ_COMMITTED, Xid.REPEATABLE_READ and Xid.SERIALIZABLE

Returns: Xid A unique transaction

Throws: Exception Thrown when local_addr is null

commit

public void commit(Xid transaction)
Commits all modifications sent to the receivers via ReplicationManager and releases all locks associated with this transaction. If modifications were made to stable storage (but not to resource), those modifications would now need to be transferred to the resource (e.g. database).

handle

public Object handle(Message msg)

handleCommit

protected void handleCommit(Xid transaction)

handleRollback

protected void handleRollback(Xid transaction)

handleSend

protected Object handleSend(ReplicationData data)

rollback

public void rollback(Xid transaction)
Discards all modifications sent to the receivers via ReplicationManager and releases all locks associated with this transaction.

send

public RspList send(Address dest, byte[] data, boolean synchronous, long synchronous_timeout, Xid transaction, byte[] lock_info, long lock_acquisition_timeout, long lock_lease_timeout, boolean use_locks)
Sends a request to all members of the group. Sending is asynchronous (return immediately) or synchronous (wait for all members to respond). If use_locking is true, then locking will be used at the receivers to acquire locks before accessing/updating a resource. Locks can be explicitly set using lock_info or implicitly through data. In the latter case, locks are induced from the data sent, e.g. if the data is a request for updating a certain row in a table, then we need to acquire a lock for that table.

In case of using locks, if the transaction associated with update already has a lock for a given resource, we will return. Otherwise, we will wait for lock_acquisition_timeout milliseconds. If the lock is not granted within that time a LockingException will be thrown. (We hope to replace this timeout with a distributed deadlock detection algorithm in the future.)

We have 3 main use case for this method:

  1. Asynchronous: sends the message and returns immediately. Argument asynchronous needs to be true. All other arguments except data are ignored and can be null. Will call update() on the registered ReplicationReceiver at each receiver.
  2. Synchronous without locks: sends the message, but returns only after responses from all members have been received, or synchronous_timeout milliseconds have elapsed (whichever comes first). Argument asynchronous needs to be false. Argument synchronous_timeout needs to be >= 0. If it is null the call will not time out, but wait for all responses. All other arguments (besides data are ignored).
  3. Synchronous with locks: sends the message, but returns only after responses from all members have been received, or synchronous_timeout milliseconds have elapsed (whichever comes first). At the receiver's side we have to acquire a lock for the resource to be updated, if the acquisition fails a LockingException will be thrown. The resource to be locked can be found in two ways: either data contains the resource(c) to be acquired implicitly, or lock_info lists the resources explicitly, or both. All the locks acquired at the receiver's side should be associated with transaction. When a commit() is received, the receiver should commit the modifications to the resource and release all locks. When a rollback() is received, the receiver should remove all (temporary) modifications and release all locks associated with transaction.
In both the synchronous cases a List of byte[] will be returned if the data was sent to all receivers successfully, cointaining byte buffers. The list may be empty.

Parameters: dest The destination to which to send the message. Will be sent to all members if null. data The data to be sent to all members. It may contain information about the resource to be locked. synchronous If false the call is asynchronous, ie. non-blocking. If true, the method will wait until responses from all members have been received (unless a timeout is defined, see below) synchronous_timeout In a synchronous call, we will wait for responses from all members or until synchronous_timeout have elapsed (whichever comes first). 0 means to wait forever. transaction The transaction under which all locks for resources should be acquired. The receiver will probably maintain a lock table with resources as keys and transactions as values. When an update is received, the receiver checks its lock table: if the resource is not yet taken, the resource/transaction pair will be added to the lock table. Otherwise, we check if the transaction's owner associated with the resource is the same as the caller. If this is the case, the lock will be considered granted, otherwise we will wait for the resource to become available (for a certain amount of time). When a transaction is committed or rolled back, all resources associated with this transaction will be released. lock_info Information about resource(s) to be acquired. This may be null, e.g. if this information is already implied in data. Both data and lock_info may be used to define the set of resources to be acquired. lock_acquisition_timeout The number of milliseconds to wait until a lock acquisition request is considered failed (causing a LockingException). If 0 we will wait forever. (Note that this may lead to deadlocks). lock_lease_timeout The number of milliseconds we want to keep the lock for a resource. After this time has elapsed, the lock will be released. If 0 we won't release the lock(s) use_locks If this is false, we will ignore all lock information (even if it is specified) and not use locks at all.

Returns: RspList A list of Rsps (Rsp), one for each member. Each one is the result of ReplicationReceiver. If a member didn't send a response, the received field will be false. If the member was suspected while waiting for a response, the suspected field will be true. If the receive() method in the receiver returned a value it will be in field retval. If the receiver threw an exception it will also be in this field.

setMembershipListener

public void setMembershipListener(MembershipListener l)

setReplicationReceiver

public void setReplicationReceiver(ReplicationReceiver handler)

stop

public void stop()
Copyright ? 1998-2005 Bela Ban. All Rights Reserved.