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