[maven-resolver] 01/01: Document all named locks and name mappers

[mi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

michaelo pushed a commit to branch named-locks-documentation
in repository https://gitbox.apache.org/repos/asf/maven-resolver.git

commit e39cbabe219fd472b3d7c65b0f4bd0574236d570
Author: Michael Osipov <mi...@apache.org>
AuthorDate: Sun Sep 5 01:13:29 2021 +0200

    Document all named locks and name mappers
---
 .../src/site/markdown/index.md.vm                  |  4 ++--
 .../src/site/markdown/index.md.vm                  |  4 ++--
 .../src/site/markdown/index.md.vm                  | 26 +++++++++++++++++++---
 3 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/maven-resolver-named-locks-hazelcast/src/site/markdown/index.md.vm b/maven-resolver-named-locks-hazelcast/src/site/markdown/index.md.vm
index 886bcd4..cdd6ebd 100644
--- a/maven-resolver-named-locks-hazelcast/src/site/markdown/index.md.vm
+++ b/maven-resolver-named-locks-hazelcast/src/site/markdown/index.md.vm
@@ -22,7 +22,7 @@ under the License.
 This module implement named locks using Hazelcast. It provides two implementations, that are distributed and rely on
 Hazelcast 4.x ISemaphores.
 
-Out of the box "hazelcast" (distributed) named lock implementations are following:
+Out of the box "hazelcast" (distributed) named lock implementations are the following:
 
 - `semaphore-hazelcast` implemented in `org.eclipse.aether.named.hazelcast.HazelcastCPSemaphoreNamedLockFactory` that uses
   Hazelcast backed `com.hazelcast.cp.ISemaphore`. Full Hazelcast member is used here.
@@ -45,7 +45,7 @@ ${esc.hash}${esc.hash} Installation/Testing
   right after the `${maven.conf}/logging` line.
 - Copy the following dependency from Maven Central to `${maven.home}/lib/ext/hazelcast/`:
       <pre class="source">
-      ├── <a href="https://repo.maven.apache.org/maven2/com/hazelcast/hazelcast/4.1.1/hazelcast-4.1.1.jar">hazelcast-4.1.1.jar</a></pre>
+      └── <a href="https://repo.maven.apache.org/maven2/com/hazelcast/hazelcast/4.1.1/hazelcast-4.1.1.jar">hazelcast-4.1.1.jar</a></pre>
 - Optionally configure Hazelcast instance with `${maven.conf}/hazelcast.xml` or `${maven.conf}/hazelcast-client.xml`
   (see Hazelcast documentation for possibilities, or, see test resources of this project as starter).
 - Now start a multithreaded Maven build on your project and make sure `NamedSyncContextFactory` is being used.
diff --git a/maven-resolver-named-locks-redisson/src/site/markdown/index.md.vm b/maven-resolver-named-locks-redisson/src/site/markdown/index.md.vm
index 5bf4be8..092633d 100644
--- a/maven-resolver-named-locks-redisson/src/site/markdown/index.md.vm
+++ b/maven-resolver-named-locks-redisson/src/site/markdown/index.md.vm
@@ -22,7 +22,7 @@ under the License.
 This module implement named locks using Redisson. It provides two implementations, that are distributed and rely on
 Redisson distributed objects feature.
 
-Out of the box "redisson" (distributed) named lock implementations are following:
+Out of the box "redisson" (distributed) named lock implementations are are following:
 
 - `rwlock-redisson` implemented in `org.eclipse.aether.named.redisson.RedissonReadWriteLockNamedLockFactory`
   that uses Redisson backed `org.redisson.api.RReadWriteLock`.
@@ -60,6 +60,6 @@ ${esc.hash}${esc.hash} Installation/Testing
   ├── <a href="https://repo1.maven.org/maven2/io/netty/netty-resolver-dns/4.1.65.Final/netty-resolver-dns-4.1.65.Final.jar">netty-resolver-dns-4.1.65.Final.jar</a>
   ├── <a href="https://repo1.maven.org/maven2/io/netty/netty-transport/4.1.65.Final/netty-transport-4.1.65.Final.jar">netty-transport-4.1.65.Final.jar</a>
   ├── <a href="https://repo1.maven.org/maven2/org/redisson/redisson/3.15.6/redisson-3.15.6.jar">redisson-3.15.6.jar</a>
-  ├── <a href="https://repo1.maven.org/maven2/org/yaml/snakeyaml/1.27/snakeyaml-1.27.jar">snakeyaml-1.27.jar</a></pre>
+  └── <a href="https://repo1.maven.org/maven2/org/yaml/snakeyaml/1.27/snakeyaml-1.27.jar">snakeyaml-1.27.jar</a></pre>
 - Start your Redis instance on `localhost` or configure a remote instance with `${maven.conf}/maven-resolver-redisson.yaml`.
 - Now start a multithreaded Maven build on your project.
diff --git a/maven-resolver-named-locks/src/site/markdown/index.md.vm b/maven-resolver-named-locks/src/site/markdown/index.md.vm
index b8d47d8..68bc374 100644
--- a/maven-resolver-named-locks/src/site/markdown/index.md.vm
+++ b/maven-resolver-named-locks/src/site/markdown/index.md.vm
@@ -20,14 +20,34 @@ under the License.
 -->
 
 Named locks are essentially locks that are assigned to some given (opaque) ID. If you work with multiple
-resources that each can have unique ID assigned (file w/ file an absolute path, some entities with unique ID),
+resources that each can have unique ID assigned (e.e., file with an absolute path, some entities with unique ID),
 then you can use named locks to make sure they are being protected from concurrent read and write actions.
 
-Named locks provide support classes for implementations, and provide out of the box two named lock implementation.
+Named locks provide support classes for implementations, and provide out of the box seven named lock implementations and three name mappers.
 
-Out of the box "local" (local to JVM) named lock implementations are following:
+Out of the box "local" (local to JVM) named lock implementations are the following:
 
 - `rwlock-local` implemented in `org.eclipse.aether.named.providers.LocalReadWriteLockNamedLockFactory` that uses
   JVM `java.util.concurrent.locks.ReentrantReadWriteLock`.
 - `semaphore-local` implemented in `org.eclipse.aether.named.providers.LocalSemaphoreNamedLockFactory` that uses
   JVM `java.util.concurrent.Semaphore`.
+- `noop` implemented in `org.eclipse.aether.named.providers.NoopNamedLockFactory` that uses no locking.
+
+Out of the box "global" (global to network) named lock implementations are the following (separate modules which require additional dependencies):
+
+- `rwlock-redisson` implemented in `org.eclipse.aether.named.redisson.RedissonReadWriteLockNamedLockFactory`.
+- `semaphore-redisson` implemented in `org.eclipse.aether.named.redisson.RedissonSemaphoreNamedLockFactory`.
+- `semaphore-hazelcast-client` implemented in `org.eclipse.aether.named.hazelcast.HazelcastClientCPSemaphoreNamedLockFactory`.
+- `semaphore-hazelcast` implemented in `org.eclipse.aether.named.hazelcast.HazelcastCPSemaphoreNamedLockFactory`.
+
+Local named locks are only suited within one JVM with a multithreaded build.
+Sharing one local repository between multiple Maven processes requires a global named lock!
+
+
+The aforementioned (opaque) IDs need to be mapped from artifacts and metadata.
+
+Out of the box name mapper implementations are the following:
+
+- `static` implemented in `org.eclipse.aether.internal.impl.synccontext.named.StaticNameMapper`.
+- `gav` implemented in `org.eclipse.aether.internal.impl.synccontext.named.GAVNameMapper`.
+- `discriminating` implemented in `org.eclipse.aether.internal.impl.synccontext.named.DiscriminatingNameMapper`.