Coverage Report

Coverage Report - org.apache.commons.transaction.locking.MultiLevelLock2

Classes in this File

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.apache.commons.transaction.locking;
 
 /**
  * 
  * Extended multi level lock. Compared to basic {@link MultiLevelLock} allows for more flexible
  * locking including preference and more compatibility modes.
  * 
  * @version $Id: MultiLevelLock2.java 493628 2007-01-07 01:42:48Z joerg $
  * @see LockManager2
  * @see MultiLevelLock
  * @see GenericLock
  * @since 1.1
  */
 public interface MultiLevelLock2 extends MultiLevelLock {
 
     /**
      * Compatibility mode: none reentrant. Lock level by the same owner <em>shall</em>
      * affect compatibility.
      */
     public static final int COMPATIBILITY_NONE = 0;
 
     /**
      * Compatibility mode: reentrant. Lock level by the same owner <em>shall not</em>
      * affect compatibility.
      */
     public static final int COMPATIBILITY_REENTRANT = 1;
     
     /**
      * Compatibility mode: supporting. Lock levels that are the same as the
      * desired <em>shall not</em> affect compatibility, but lock level held by the same
      * owner <em>shall</em>.
      */
     public static final int COMPATIBILITY_SUPPORT = 2;
 
     /**
      * Compatibility mode: reentrant and supporting. Lock levels that are the same as the
      * desired and lock levels held by the same
      * owner <em>shall not</em> affect compatibility.
      */
     public static final int COMPATIBILITY_REENTRANT_AND_SUPPORT = 3;
     
     /**
      * Tests if a certain lock level is owned by an owner. 
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to check a
      *            certain lock level on this lock
      * @param lockLevel
      *            the lock level to test
      * @return <code>true</code> if the lock could be acquired at the time
      *         this method was called
      */
     public boolean has(Object ownerId, int lockLevel);
     
     /**
      * Tests if a certain lock level <em>could</em> be acquired. This method
      * tests only and does <em>not actually acquire</em> the lock.
      * 
      * @param ownerId
      *            a unique id identifying the entity that wants to test a
      *            certain lock level on this lock
      * @param targetLockLevel
      *            the lock level to acquire
      * @param compatibility
      *            {@link #COMPATIBILITY_NONE}if no additional compatibility is
      *            desired (same as reentrant set to false) ,
      *            {@link #COMPATIBILITY_REENTRANT}if lock level by the same
      *            owner shall not affect compatibility (same as reentrant set to
      *            true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
      *            are the same as the desired shall not affect compatibility, or
      *            finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
      *            a combination of reentrant and support
      * @return <code>true</code> if the lock could be acquired at the time
      *         this method was called
      */
     public boolean test(Object ownerId, int targetLockLevel, int compatibility);
     
     /**
      * Tries to acquire a certain lock level on this lock. Does the same as
      * {@link org.apache.commons.transaction.locking.MultiLevelLock#acquire(java.lang.Object, int, boolean, boolean, long)}
      * except that it allows for different compatibility settings. There is an
      * additional compatibility mode {@link #COMPATIBILITY_SUPPORT}that allows
      * equal lock levels not to interfere with each other. This is like an
      * additional shared compatibility and useful when you only want to make
      * sure not to interfer with lowe levels, but are fine with the same.
      * 
      * @param ownerId a unique id identifying the entity that wants to acquire a certain lock level on this lock
      * @param targetLockLevel the lock level to acquire
      * @param wait <code>true</code> if this method shall block when the desired lock level can not be acquired
      * @param compatibility
      *            {@link #COMPATIBILITY_NONE}if no additional compatibility is
      *            desired (same as reentrant set to false) ,
      *            {@link #COMPATIBILITY_REENTRANT}if lock level by the same
      *            owner shall not affect compatibility (same as reentrant set to
      *            true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
      *            are the same as the desired shall not affect compatibility, or
      *            finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
      *            a combination of reentrant and support
      * 
      * @param preferred
      *            in case this lock request is incompatible with existing ones
      *            and we wait, it shall be granted before other waiting requests
      *            that are not preferred
      * @param timeoutMSecs if blocking is enabled by the <code>wait</code> parameter this specifies the maximum wait time in milliseconds
      * @return <code>true</code> if the lock actually was acquired 
      * @throws InterruptedException when the thread waiting on this method is interrupted
      * 
      */
     public boolean acquire(Object ownerId, int targetLockLevel, boolean wait, int compatibility,
             boolean preferred, long timeoutMSecs) throws InterruptedException;
 
 }

1		/*
2		* Licensed to the Apache Software Foundation (ASF) under one or more
3		* contributor license agreements. See the NOTICE file distributed with
4		* this work for additional information regarding copyright ownership.
5		* The ASF licenses this file to You under the Apache License, Version 2.0
6		* (the "License"); you may not use this file except in compliance with
7		* the License. You may obtain a copy of the License at
8		*
9		* http://www.apache.org/licenses/LICENSE-2.0
10		*
11		* Unless required by applicable law or agreed to in writing, software
12		* distributed under the License is distributed on an "AS IS" BASIS,
13		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14		* See the License for the specific language governing permissions and
15		* limitations under the License.
16		*/
17		package org.apache.commons.transaction.locking;
18
19		/**
20		*
21		* Extended multi level lock. Compared to basic {@link MultiLevelLock} allows for more flexible
22		* locking including preference and more compatibility modes.
23		*
24		* @version $Id: MultiLevelLock2.java 493628 2007-01-07 01:42:48Z joerg $
25		* @see LockManager2
26		* @see MultiLevelLock
27		* @see GenericLock
28		* @since 1.1
29		*/
30		public interface MultiLevelLock2 extends MultiLevelLock {
31
32		/**
33		* Compatibility mode: none reentrant. Lock level by the same owner <em>shall</em>
34		* affect compatibility.
35		*/
36		public static final int COMPATIBILITY_NONE = 0;
37
38		/**
39		* Compatibility mode: reentrant. Lock level by the same owner <em>shall not</em>
40		* affect compatibility.
41		*/
42		public static final int COMPATIBILITY_REENTRANT = 1;
43
44		/**
45		* Compatibility mode: supporting. Lock levels that are the same as the
46		* desired <em>shall not</em> affect compatibility, but lock level held by the same
47		* owner <em>shall</em>.
48		*/
49		public static final int COMPATIBILITY_SUPPORT = 2;
50
51		/**
52		* Compatibility mode: reentrant and supporting. Lock levels that are the same as the
53		* desired and lock levels held by the same
54		* owner <em>shall not</em> affect compatibility.
55		*/
56		public static final int COMPATIBILITY_REENTRANT_AND_SUPPORT = 3;
57
58		/**
59		* Tests if a certain lock level is owned by an owner.
60		*
61		* @param ownerId
62		* a unique id identifying the entity that wants to check a
63		* certain lock level on this lock
64		* @param lockLevel
65		* the lock level to test
66		* @return <code>true</code> if the lock could be acquired at the time
67		* this method was called
68		*/
69		public boolean has(Object ownerId, int lockLevel);
70
71		/**
72		* Tests if a certain lock level <em>could</em> be acquired. This method
73		* tests only and does <em>not actually acquire</em> the lock.
74		*
75		* @param ownerId
76		* a unique id identifying the entity that wants to test a
77		* certain lock level on this lock
78		* @param targetLockLevel
79		* the lock level to acquire
80		* @param compatibility
81		* {@link #COMPATIBILITY_NONE}if no additional compatibility is
82		* desired (same as reentrant set to false) ,
83		* {@link #COMPATIBILITY_REENTRANT}if lock level by the same
84		* owner shall not affect compatibility (same as reentrant set to
85		* true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
86		* are the same as the desired shall not affect compatibility, or
87		* finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
88		* a combination of reentrant and support
89		* @return <code>true</code> if the lock could be acquired at the time
90		* this method was called
91		*/
92		public boolean test(Object ownerId, int targetLockLevel, int compatibility);
93
94		/**
95		* Tries to acquire a certain lock level on this lock. Does the same as
96		* {@link org.apache.commons.transaction.locking.MultiLevelLock#acquire(java.lang.Object, int, boolean, boolean, long)}
97		* except that it allows for different compatibility settings. There is an
98		* additional compatibility mode {@link #COMPATIBILITY_SUPPORT}that allows
99		* equal lock levels not to interfere with each other. This is like an
100		* additional shared compatibility and useful when you only want to make
101		* sure not to interfer with lowe levels, but are fine with the same.
102		*
103		* @param ownerId a unique id identifying the entity that wants to acquire a certain lock level on this lock
104		* @param targetLockLevel the lock level to acquire
105		* @param wait <code>true</code> if this method shall block when the desired lock level can not be acquired
106		* @param compatibility
107		* {@link #COMPATIBILITY_NONE}if no additional compatibility is
108		* desired (same as reentrant set to false) ,
109		* {@link #COMPATIBILITY_REENTRANT}if lock level by the same
110		* owner shall not affect compatibility (same as reentrant set to
111		* true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
112		* are the same as the desired shall not affect compatibility, or
113		* finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
114		* a combination of reentrant and support
115		*
116		* @param preferred
117		* in case this lock request is incompatible with existing ones
118		* and we wait, it shall be granted before other waiting requests
119		* that are not preferred
120		* @param timeoutMSecs if blocking is enabled by the <code>wait</code> parameter this specifies the maximum wait time in milliseconds
121		* @return <code>true</code> if the lock actually was acquired
122		* @throws InterruptedException when the thread waiting on this method is interrupted
123		*
124		*/
125		public boolean acquire(Object ownerId, int targetLockLevel, boolean wait, int compatibility,
126		boolean preferred, long timeoutMSecs) throws InterruptedException;
127
128		}