org.jgroups.blocks
Class ReplicationManager

java.lang.Object
  extended byorg.jgroups.blocks.ReplicationManager
All Implemented Interfaces:
RequestHandler

public class ReplicationManager
extends java.lang.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  MessageDispatcher disp
          Used to broadcast updates and receive responses (latter only in synchronous case)
 
Constructor Summary
ReplicationManager(Channel channel, MessageListener ml, MembershipListener l, ReplicationReceiver receiver)
          Creates an instance of ReplicationManager on top of a Channel
ReplicationManager(PullPushAdapter adapter, java.io.Serializable id, MessageListener ml, MembershipListener l, ReplicationReceiver receiver)
          Creates an instance of ReplicationManager on top of a PullPushAdapter
 
Method Summary
 Xid begin()
          Create a new transaction.
 Xid begin(int transaction_mode)
          Create a new transaction.
 void commit(Xid transaction)
          Commits all modifications sent to the receivers via send and releases all locks associated with this transaction.
 java.lang.Object handle(Message msg)
           
protected  void handleCommit(Xid transaction)
           
protected  void handleRollback(Xid transaction)
           
protected  java.lang.Object handleSend(ReplicationData data)
           
 void rollback(Xid transaction)
          Discards all modifications sent to the receivers via send and releases all locks associated with this transaction.
 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.
 void setMembershipListener(MembershipListener l)
           
 void setReplicationReceiver(ReplicationReceiver handler)
           
 void stop()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

disp

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

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,
                          java.io.Serializable id,
                          MessageListener ml,
                          MembershipListener l,
                          ReplicationReceiver receiver)
Creates an instance of ReplicationManager on top of a PullPushAdapter

Method Detail

stop

public void stop()

begin

public Xid begin()
          throws java.lang.Exception
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:
java.lang.Exception - Thrown when local_addr is null

begin

public Xid begin(int transaction_mode)
          throws java.lang.Exception
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:
java.lang.Exception - Thrown when local_addr is null

setReplicationReceiver

public void setReplicationReceiver(ReplicationReceiver handler)

setMembershipListener

public void setMembershipListener(MembershipListener l)

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.receive(org.jgroups.blocks.Xid, byte[], byte[], long, long, boolean). 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.

commit

public void commit(Xid transaction)
Commits all modifications sent to the receivers via send 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).


rollback

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


handle

public java.lang.Object handle(Message msg)
Specified by:
handle in interface RequestHandler

handleSend

protected java.lang.Object handleSend(ReplicationData data)
                               throws UpdateException,
                                      LockingException
Throws:
UpdateException
LockingException

handleCommit

protected void handleCommit(Xid transaction)

handleRollback

protected void handleRollback(Xid transaction)


Copyright © 2001,2002 www.jgroups.com . All Rights Reserved.