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) throws InterruptedException {
078            return acquire(ownerId, READ_LOCK, false, timeoutMSecs);
079        }
080    
081        /**
082         * Tries to acquire a blocking, reentrant write lock. A write lock is
083         * incompatible with any another read or write lock and is thus exclusive.
084         * 
085         * @param ownerId
086         *            a unique id identifying the entity that wants to acquire a
087         *            certain lock level on this lock
088         * @param timeoutMSecs
089         *            if blocking is enabled by the <code>wait</code> parameter
090         *            this specifies the maximum wait time in milliseconds
091         * @return <code>true</code> if the lock actually was acquired
092         * @throws InterruptedException
093         *             when the thread waiting on this method is interrupted
094         */
095        public boolean acquireWrite(Object ownerId, long timeoutMSecs) throws InterruptedException {
096            return acquire(ownerId, WRITE_LOCK, true, timeoutMSecs);
097        }
098    }