View Javadoc

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