KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > transaction > locking > ReadWriteLock


1 /*
2  * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//transaction/src/java/org/apache/commons/transaction/locking/ReadWriteLock.java,v 1.3 2005/01/07 23:33:24 ozeigermann Exp $
3 <<<<<<< .mine
4  * $Revision: 1.3 $
5  * $Date: 2005-02-26 14:16:14 +0100 (Sa, 26 Feb 2005) $
6 =======
7  * $Revision$
8  * $Date: 2005-02-26 14:16:14 +0100 (Sa, 26 Feb 2005) $
9 >>>>>>> .r168169
10  *
11  * ====================================================================
12  *
13  * Copyright 2004 The Apache Software Foundation
14  *
15  * Licensed under the Apache License, Version 2.0 (the "License");
16  * you may not use this file except in compliance with the License.
17  * You may obtain a copy of the License at
18  *
19  * http://www.apache.org/licenses/LICENSE-2.0
20  *
21  * Unless required by applicable law or agreed to in writing, software
22  * distributed under the License is distributed on an "AS IS" BASIS,
23  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
24  * See the License for the specific language governing permissions and
25  * limitations under the License.
26  *
27  */
28
29 package org.apache.commons.transaction.locking;
30
31 import org.apache.commons.transaction.util.LoggerFacade;
32
33 /**
34  * Convenience implementation of a read/write lock based on {@link GenericLock}.
35  * <br>
36  * <br>
37  * Reads are shared which means there can be any number of concurrent read
38  * accesses allowed by this lock. Writes are exclusive. This means when there is
39  * a write access no other access neither read nor write are allowed by this
40  * lock. Additionally, writes are preferred over reads in order to avoid starvation. The idea
41  * is that there are many readers, but few writers and if things work out bad the writer would
42  * never be served at all. That's why it is preferred.<br>
43  * <br>
44  * Calls to both {@link #acquireRead(Object, long)}and
45  * {@link #acquireWrite(Object, long)}are blocking and reentrant. Blocking
46  * means they will wait if they can not acquire the descired access, reentrant means that a lock
47  * request by a specific owner will always be compatible with other accesses on this lock by the
48  * same owner. E.g. if you already have a lock for writing and you try to acquire write access
49  * again you will not be blocked by this first lock, while others of course will be. This is the
50  * natural way you already know from Java monitors and synchronized blocks.
51  *
52  * @version $Revision$
53  * @see GenericLock
54  */
55 public class ReadWriteLock extends GenericLock {
56
57     public static final int NO_LOCK = 0;
58
59     public static final int READ_LOCK = 1;
60
61     public static final int WRITE_LOCK = 2;
62
63     /**
64      * Creates a new read/write lock.
65      *
66      * @param resourceId
67      * identifier for the resource associated to this lock
68      * @param logger
69      * generic logger used for all kind of debug logging
70      */
71     public ReadWriteLock(Object JavaDoc resourceId, LoggerFacade logger) {
72         super(resourceId, WRITE_LOCK, logger);
73     }
74
75     /**
76      * Tries to acquire a blocking, reentrant read lock. A read lock is
77      * compatible with other read locks, but not with a write lock.
78      *
79      * @param ownerId
80      * a unique id identifying the entity that wants to acquire a
81      * certain lock level on this lock
82      * @param timeoutMSecs
83      * if blocking is enabled by the <code>wait</code> parameter
84      * this specifies the maximum wait time in milliseconds
85      * @return <code>true</code> if the lock actually was acquired
86      * @throws InterruptedException
87      * when the thread waiting on this method is interrupted
88      */
89     public boolean acquireRead(Object JavaDoc ownerId, long timeoutMSecs) throws InterruptedException JavaDoc {
90         return acquire(ownerId, READ_LOCK, false, timeoutMSecs);
91     }
92
93     /**
94      * Tries to acquire a blocking, reentrant write lock. A write lock is
95      * incompatible with any another read or write lock and is thus exclusive.
96      *
97      * @param ownerId
98      * a unique id identifying the entity that wants to acquire a
99      * certain lock level on this lock
100      * @param timeoutMSecs
101      * if blocking is enabled by the <code>wait</code> parameter
102      * this specifies the maximum wait time in milliseconds
103      * @return <code>true</code> if the lock actually was acquired
104      * @throws InterruptedException
105      * when the thread waiting on this method is interrupted
106      */
107     public boolean acquireWrite(Object JavaDoc ownerId, long timeoutMSecs) throws InterruptedException JavaDoc {
108         return acquire(ownerId, WRITE_LOCK, true, timeoutMSecs);
109     }
110 }
Popular Tags