KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jgroups > blocks > ReplicationReceiver


1 // $Id: ReplicationReceiver.java,v 1.1.1.1 2003/09/09 01:24:08 belaban Exp $
2
3
4 package org.jgroups.blocks;
5
6
7 /**
8  * Implementation of this interface needs to register with ReplicationManager and will receive updates to be
9  * applied to its locally replicated data. If locks are used the implementation is resposible for lock acquisition
10  * and management. To do so, it probably needs to maintain a lock table (keys = resource objects, values = transactions)
11  * to associate resources with locks and possibly a transaction table (keys = transactions, values = locks) to keep
12  * track of all locks for a given transaction (to commit/release all modifications/locks for a given transaction).
13  *
14  * @author Bela Ban Nov 19 2002
15  */
16 public interface ReplicationReceiver {
17
18     /**
19      * Receives data sent by a sender to all group members and applies update to locally replicated data. This is
20      * the result of a {@link ReplicationManager#send} call.
21      *
22      * @param transaction The transaction under which all locks will be acquired. Will be null if no locks are used (e.g.
23      * <code>use_locks</code> is null).
24      * @param data The data to be modified. In case of a database, this data would have to be stored in stable storage,
25      * and would only be applied on a <code>commit()</code>. In case of a distributed replicated in-memory
26      * data structure, the update might be applied directly and the subsequent commit() or rollback() might
27      * be ignored. Note that this argument may contain the resource to be locked; in this case the <code>
28      * lock_info</code> parameter might be null.
29      * @param lock_info Information about the resource(s) to be locked. Will be null if no locks are used (e.g.
30      * <code>use_locks</code> is null). Can also be null even if locks are used, e.g. when the resource(s)
31      * to be locked are an implicit part of <code>data</code>.
32      * @param lock_acquisition_timeout If locks are used, the number of milliseconds to wait for a lock to be acquired.
33      * If this time elapses, a TimeoutException will be thrown. A value of 0 means
34      * to wait forever. If <code>use_locks</code> is false, this value is ignored.
35      * @param lock_lease_timeout The number of milliseconds to hold on to the lock, once it is acquired. A value of 0
36      * means to never release the lock until commit() or rollback() are called.
37      * @param use_locks Whether to use locking or not. If this value is false, all lock-related arguments will be
38      * ignored, regardless of whether they are non-null.
39      * @return Object A return value, the semantics of which are determined by caller of {@link ReplicationManager.send}
40      * and the receiver. If no special value should be returned, null can be returned. Note that in the
41      * latter case, null is still treated as a response (in the synchronous call).
42      * @exception LockingException Thrown when a lock on a resource cannot be acquired
43      * @exception UpdateException Thrown when the update fails (application semantics)
44      */
45     Object JavaDoc receive(Xid transaction,
46                    byte[] data,
47                    byte[] lock_info,
48                    long lock_acquisition_timeout,
49                    long lock_lease_timeout,
50                    boolean use_locks) throws LockingException, UpdateException;
51
52
53     /**
54      * Commit the modifications to the locally replicated data and release all locks. If the receive() call already
55      * applied the changes, then this method is a nop.
56      */
57     void commit(Xid transaction);
58
59
60     /**
61      * Discard all modifications and release all locks. If the receive() call already applied the changes,
62      * this method will not be able to rollback the modifications, but will only release the locks.
63      */
64     void rollback(Xid transaction);
65 }
66
Popular Tags