LockMaster


1   /* LockMaster.java */
2   
3   package org.enhydra.shark.api.internal.processlocking;
4   
5   import java.util.List  ;
6   import org.enhydra.shark.api.RootException;
7   import org.enhydra.shark.api.SharkTransaction;
8   import org.enhydra.shark.api.internal.working.CallbackUtilities;
9   
10  /**
11   * LockMaster interface defines methods a lock master
12   * implementation must have.
13   * <p>
14   * Shark library allows multiple transactions/threads to be executed
15   * simultaneously. This introduces a problem when two client invoked threads
16   * want to change same process (or its contents), because one of their
17   * transactions is going to fail. Anyways, simultaneous modifications of
18   * the same data may induce other ambiguities, so Shark needs a tool to
19   * fend itself - a lock master.
20   * <p>
21   * SharkEngineManager will assure that there is one, and only one instance of
22   * lock master instantiated. This lock master will be asked for the exclusive
23   * lock of a process, before transaction starts to do anything about it. After
24   * transaction has finished (regardlessly on its own success) it releases
25   * the lock, so next transaction may go forward.
26   *
27   * @author Vladimir Puskas
28   * @version 1.0.3
29   */
30  public interface LockMaster {
31  
32     /**
33      * Method configure is called at Shark start up, to configure
34      * implementation of LockMaster.
35      *
36      * @param cbImpl an instance of CallbackUtilities used to get
37      *            properties for configuring LockMaster in Shark.
38      *
39      * @exception RootException Thrown if configuring doesn't succeed.
40      */
41     public void configure(CallbackUtilities cbImpl) throws RootException;
42     
43     /**
44      * Method lock ensures that nobody else (other threads) has same processId.
45      * This method may wait a while before acquiring lock requested.
46      * Implementation may set a timeout to limit the time spent waiting.
47      *
48      * @param t SharkTransaction during wich lock is required.
49      * @param processId lock identifier.
50      * @param timeout limits waiting for this specific lock:
51      *                  value < 0 means wait forever
52      *                  value >= 0 specifies number of miliseconds
53      *                  null value means use default.
54      * @return true if lock is acquired without waiting, false otherwise.
55      * @exception RootException Gets thrown if timeout expires.
56      */
57     public boolean lock(SharkTransaction t,
58                         String   processId,
59                         Long   timeout) throws RootException;
60  
61     /**
62      * Method lock ensures that nobody else (other threads) has same processId.
63      * This method may wait a while before acquiring lock requested.
64      * Implementation may set a timeout to limit the time spent waiting.
65      *
66      * @param t SharkTransaction during which lock is required.
67      * @param processId lock identifier.
68      * @return   true if lock is acquired without waiting, false otherwise.
69      * @exception RootException Gets thrown if timeout expires.
70      */
71     public boolean lock(SharkTransaction t, String   processId) throws RootException;
72  
73     /**
74      * Method unlock releases processId, for other threads to get it.
75      *
76      * @param t SharkTransaction during which lock is required.
77      * @param processId lock identifier.
78      * @exception   RootException If something unexpected happens.
79      */
80     public void unlock(SharkTransaction t, String   processId) throws RootException;
81  
82     /**
83      * Method unlock releases all locks SharkTransaction had acquired.
84      *
85      * @param t SharkTransaction during which locks had been obtained.
86      * @exception   RootException If something unexpected happens.
87      */
88     public void unlock(SharkTransaction t) throws RootException;
89  
90     /**
91      * Gets locks for the SharkTransaction.
92      *
93      * @param t SharkTransaction during which lock is required.
94      * @return List of processIds SharkTransaction had previously obtained.
95      * @exception RootException If something unexpected happens.
96      */
97     public List   getLocks(SharkTransaction t) throws RootException;
98  
99  }
100 /* End of LockMaster.java */
101 
102
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags