001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.named;
020
021import java.util.concurrent.TimeUnit;
022
023/**
024 * A named lock, functionally similar to existing JVM and other implementations. Must support boxing (reentrancy), but
025 * no lock upgrade is supported. The lock instance obtained from lock factory must be treated as a resource, best in
026 * try-with-resource block. Usual pattern to use this lock:
027 * <pre>
028 *   try (NamedLock lock = factory.getLock("resourceName")) {
029 *     if (lock.lockExclusively(10L, Timeunit.SECONDS)) {
030 *       try {
031 *         ... exclusive access to "resourceName" resource gained here
032 *       }
033 *       finally {
034 *         lock.unlock();
035 *       }
036 *     }
037 *     else {
038 *       ... failed to gain access within specified time, handle it
039 *     }
040 *   }
041 * </pre>
042 */
043public interface NamedLock extends AutoCloseable {
044    /**
045     * Returns this instance key, never {@code null}.
046     */
047    NamedLockKey key();
048
049    /**
050     * Tries to lock shared, may block for given time. If successful, returns {@code true}.
051     */
052    boolean lockShared(long time, TimeUnit unit) throws InterruptedException;
053
054    /**
055     * Tries to lock exclusively, may block for given time. If successful, returns {@code true}.
056     */
057    boolean lockExclusively(long time, TimeUnit unit) throws InterruptedException;
058
059    /**
060     * Unlocks the lock, must be invoked by caller after one of the {@link #lockShared(long, TimeUnit)} or {@link
061     * #lockExclusively(long, TimeUnit)}.
062     */
063    void unlock();
064
065    /**
066     * Closes the lock resource. Lock MUST be unlocked using {@link #unlock()} in case any locking happened on it. After
067     * invoking this method, the lock instance MUST NOT be used anymore. If lock for same name needed, a new instance
068     * should be obtained from factory using {@link NamedLockFactory#getLock(java.util.Collection)}. Ideally,
069     * instances are to be used within try-with-resource blocks, so calling this method directly is not really
070     * needed, nor advised.
071     */
072    @Override
073    void close();
074}