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;
20  
21  import java.io.Closeable;
22  import java.util.Collection;
23  
24  import org.eclipse.aether.artifact.Artifact;
25  import org.eclipse.aether.metadata.Metadata;
26  
27  /**
28   * A synchronization context used to coordinate concurrent access to artifacts or metadatas. The typical usage of a
29   * synchronization context looks like this:
30   *
31   * <pre>
32   * SyncContext syncContext = repositorySystem.newSyncContext( ... );
33   * try {
34   *     syncContext.acquire( artifacts, metadatas );
35   *     // work with the artifacts and metadatas
36   * } finally {
37   *     syncContext.close();
38   * }
39   * </pre>
40   *
41   * Within one thread, synchronization contexts may be nested which can naturally happen in a hierarchy of method calls.
42   * The nested synchronization contexts may also acquire overlapping sets of artifacts/metadatas as long as the following
43   * conditions are met. If the outer-most context holding a particular resource is exclusive, that resource can be
44   * reacquired in any nested context. If however the outer-most context is shared, the resource may only be reacquired by
45   * nested contexts if these are also shared.
46   * <p>
47   * A synchronization context is meant to be utilized by only one thread and as such is not thread-safe.
48   * <p>
49   * Note that the level of actual synchronization is subject to the implementation and might range from OS-wide to none.
50   *
51   * @see RepositorySystem#newSyncContext(RepositorySystemSession, boolean)
52   */
53  public interface SyncContext extends Closeable {
54  
55      /**
56       * Acquires synchronized access to the specified artifacts and metadatas. The invocation will potentially block
57       * until all requested resources can be acquired by the calling thread. Acquiring resources that are already
58       * acquired by this synchronization context has no effect. Please also see the class-level documentation for
59       * information regarding reentrancy. The method may be invoked multiple times on a synchronization context until all
60       * desired resources have been acquired.
61       *
62       * @param artifacts The artifacts to acquire, may be {@code null} or empty if none.
63       * @param metadatas The metadatas to acquire, may be {@code null} or empty if none.
64       */
65      void acquire(Collection<? extends Artifact> artifacts, Collection<? extends Metadata> metadatas);
66  
67      /**
68       * Releases all previously acquired artifacts/metadatas. If no resources have been acquired before or if this
69       * synchronization context has already been closed, this method does nothing.
70       */
71      void close();
72  }