KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > perseus > concurrency > distributed > globallock > api > GlobalLock


1 /**
2  * Copyright (C) 2003-2004
3  * - France Telecom R&D
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18  *
19  * Release: 1.0
20  *
21  * Authors: Olivier Lobry (olivier.lobry@rd.francetelecom.com)
22  * Date: 2 juin 2004
23  * Time: 17:01:42
24  */
25
26 package org.objectweb.perseus.concurrency.distributed.globallock.api;
27
28
29 /**
30  * This is the interface of global locks. Global locks are created and
31  * associated w/ resource identifiers using the <code>getGlobalLock</code>
32  * of the <code>GlobalLockManager</code> interface. Once created the lock
33  * can be upgraded/downgraded to a specified level. The initial value is
34  * implementation dependent.
35  * @see GlobalLockManager
36  */
37
38 public interface GlobalLock {
39
40     /**
41      * Request a lock upgrade. In synchronous mode the method returns when
42      * the lock has been granted. In asynchronous mode the method returns a
43      * waiter object if the request cannot be granted immediately. The caller
44      * must call the waitLock method of this object to effectively wait
45      * for the lock. It must also call the signalHandled method when the
46      * granting has been handled to let other waiters be unblocked. This scheme
47      * let the possibility to implement a FIFO handling of requests.
48      * @param lck the requested lock level
49      * @param sync if true the method blocks until the request is granted
50      * @param timeout specifies the the maximum time to wait in sync mode
51      * @return a waiter object in asynchronous mode (sync == false) if the
52      * request cannot be satisfied immediately.
53      * @throws DeadLockException if the timeout has expired
54      * @throws InterruptedException if the thread has been interrupted while waiting
55      * @see GlobalLockWaiter
56      */
57     public GlobalLockWaiter upgrade(byte lck, boolean sync, long timeout)
58             throws DeadLockException, InterruptedException JavaDoc;
59
60     /**
61      * Notifies a lock downgrade.
62      * @param lck the new level wanted for the lock
63      */
64     public void downgrade(byte lck);
65
66
67     /**
68      * Get the maximum lock level that can be granted immediately without
69      * contacting the global lock coordinator (and so without blocking).
70      * Note that this is just a hint. There is no guarantee that a subsequent
71      * call to upgrade will not block.
72      * @return the maximum grantable lock level
73      */
74     public byte getGrantable();
75
76     /**
77      * Uncache the lock level. The following call to upgrade will automatically
78      * generate a request to the coordinator.
79      */
80     public void uncache();
81
82 }
83
Popular Tags