001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.commons.transaction.locking;
018:
019: import org.apache.commons.transaction.util.LoggerFacade;
020:
021: /**
022: * Convenience implementation of a read/write lock based on {@link GenericLock}.
023: * <br>
024: * <br>
025: * Reads are shared which means there can be any number of concurrent read
026: * accesses allowed by this lock. Writes are exclusive. This means when there is
027: * a write access no other access neither read nor write are allowed by this
028: * lock. Additionally, writes are preferred over reads in order to avoid starvation. The idea
029: * is that there are many readers, but few writers and if things work out bad the writer would
030: * never be served at all. That's why it is preferred.<br>
031: * <br>
032: * Calls to both {@link #acquireRead(Object, long)}and
033: * {@link #acquireWrite(Object, long)}are blocking and reentrant. Blocking
034: * means they will wait if they can not acquire the descired access, reentrant means that a lock
035: * request by a specific owner will always be compatible with other accesses on this lock by the
036: * same owner. E.g. if you already have a lock for writing and you try to acquire write access
037: * again you will not be blocked by this first lock, while others of course will be. This is the
038: * natural way you already know from Java monitors and synchronized blocks.
039: *
040: * @version $Id: ReadWriteLock.java 493628 2007-01-07 01:42:48Z joerg $
041: * @see GenericLock
042: */
043: public class ReadWriteLock extends GenericLock {
044:
045: public static final int NO_LOCK = 0;
046:
047: public static final int READ_LOCK = 1;
048:
049: public static final int WRITE_LOCK = 2;
050:
051: /**
052: * Creates a new read/write lock.
053: *
054: * @param resourceId
055: * identifier for the resource associated to this lock
056: * @param logger
057: * generic logger used for all kind of debug logging
058: */
059: public ReadWriteLock(Object resourceId, LoggerFacade logger) {
060: super (resourceId, WRITE_LOCK, logger);
061: }
062:
063: /**
064: * Tries to acquire a blocking, reentrant read lock. A read lock is
065: * compatible with other read locks, but not with a write lock.
066: *
067: * @param ownerId
068: * a unique id identifying the entity that wants to acquire a
069: * certain lock level on this lock
070: * @param timeoutMSecs
071: * if blocking is enabled by the <code>wait</code> parameter
072: * this specifies the maximum wait time in milliseconds
073: * @return <code>true</code> if the lock actually was acquired
074: * @throws InterruptedException
075: * when the thread waiting on this method is interrupted
076: */
077: public boolean acquireRead(Object ownerId, long timeoutMSecs)
078: throws InterruptedException {
079: return acquire(ownerId, READ_LOCK, false, timeoutMSecs);
080: }
081:
082: /**
083: * Tries to acquire a blocking, reentrant write lock. A write lock is
084: * incompatible with any another read or write lock and is thus exclusive.
085: *
086: * @param ownerId
087: * a unique id identifying the entity that wants to acquire a
088: * certain lock level on this lock
089: * @param timeoutMSecs
090: * if blocking is enabled by the <code>wait</code> parameter
091: * this specifies the maximum wait time in milliseconds
092: * @return <code>true</code> if the lock actually was acquired
093: * @throws InterruptedException
094: * when the thread waiting on this method is interrupted
095: */
096: public boolean acquireWrite(Object ownerId, long timeoutMSecs)
097: throws InterruptedException {
098: return acquire(ownerId, WRITE_LOCK, true, timeoutMSecs);
099: }
100: }
|