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  package org.eclipse.aether.named;
20  
21  import java.util.concurrent.TimeUnit;
22  
23  /**
24   * A named lock, functionally similar to existing JVM and other implementations. Must support boxing (reentrancy), but
25   * no lock upgrade is supported. The lock instance obtained from lock factory must be treated as a resource, best in
26   * try-with-resource block. Usual pattern to use this lock:
27   * <pre>
28   *   try (NamedLock lock = factory.getLock("resourceName")) {
29   *     if (lock.lockExclusively(10L, Timeunit.SECONDS)) {
30   *       try {
31   *         ... exclusive access to "resourceName" resource gained here
32   *       }
33   *       finally {
34   *         lock.unlock();
35   *       }
36   *     }
37   *     else {
38   *       ... failed to gain access within specified time, handle it
39   *     }
40   *   }
41   * </pre>
42   */
43  public interface NamedLock extends AutoCloseable {
44      /**
45       * Returns this instance key, never {@code null}.
46       */
47      NamedLockKey key();
48  
49      /**
50       * Tries to lock shared, may block for given time. If successful, returns {@code true}.
51       */
52      boolean lockShared(long time, TimeUnit unit) throws InterruptedException;
53  
54      /**
55       * Tries to lock exclusively, may block for given time. If successful, returns {@code true}.
56       */
57      boolean lockExclusively(long time, TimeUnit unit) throws InterruptedException;
58  
59      /**
60       * Unlocks the lock, must be invoked by caller after one of the {@link #lockShared(long, TimeUnit)} or {@link
61       * #lockExclusively(long, TimeUnit)}.
62       */
63      void unlock();
64  
65      /**
66       * Closes the lock resource. Lock MUST be unlocked using {@link #unlock()} in case any locking happened on it. After
67       * invoking this method, the lock instance MUST NOT be used anymore. If lock for same name needed, a new instance
68       * should be obtained from factory using {@link NamedLockFactory#getLock(java.util.Collection)}. Ideally,
69       * instances are to be used within try-with-resource blocks, so calling this method directly is not really
70       * needed, nor advised.
71       */
72      @Override
73      void close();
74  }