apache · cstamas · Nov 19, 2025 · Nov 19, 2025 · Nov 19, 2025 · Nov 19, 2025
diff --git a/maven-resolver-api/src/main/java/org/eclipse/aether/repository/LocalRepository.java b/maven-resolver-api/src/main/java/org/eclipse/aether/repository/LocalRepository.java
@@ -31,19 +31,25 @@
  * the repository.
  */
 public final class LocalRepository implements ArtifactRepository {
+    public static final String ID = "local";
 
     private final Path basePath;
 
     private final String type;
 
+    private final int hashCode;
+
     /**
      * Creates a new local repository with the specified base directory and unknown type.
      *
      * @param basedir The base directory of the repository, may be {@code null}.
+     * @deprecated Use {@link LocalRepository(Path)} instead.
      */
+    @Deprecated
     public LocalRepository(String basedir) {
         this.basePath = Paths.get(RepositoryUriUtils.toUri(basedir)).toAbsolutePath();
         this.type = "";
+        this.hashCode = Objects.hash(this.basePath, this.type);
     }
 
     /**
@@ -99,6 +105,7 @@ public LocalRepository(File basedir, String type) {
     public LocalRepository(Path basePath, String type) {
         this.basePath = basePath;
         this.type = (type != null) ? type : "";
+        this.hashCode = Objects.hash(this.basePath, this.type);
     }
 
     @Override
@@ -108,7 +115,7 @@ public String getContentType() {
 
     @Override
     public String getId() {
-        return "local";
+        return ID;
     }
 
     /**
@@ -153,13 +160,6 @@ public boolean equals(Object obj) {
 
     @Override
     public int hashCode() {
-        int hash = 17;
-        hash = hash * 31 + hash(basePath);
-        hash = hash * 31 + hash(type);
-        return hash;
-    }
-
-    private static int hash(Object obj) {
-        return obj != null ? obj.hashCode() : 0;
+        return hashCode;
     }
 }
diff --git a/maven-resolver-api/src/main/java/org/eclipse/aether/repository/WorkspaceRepository.java b/maven-resolver-api/src/main/java/org/eclipse/aether/repository/WorkspaceRepository.java
@@ -18,6 +18,7 @@
  */
 package org.eclipse.aether.repository;
 
+import java.util.Objects;
 import java.util.UUID;
 
 /**
@@ -27,11 +28,14 @@
  * the contained artifacts is handled by a {@link WorkspaceReader}.
  */
 public final class WorkspaceRepository implements ArtifactRepository {
+    public static final String ID = "workspace";
 
     private final String type;
 
     private final Object key;
 
+    private final int hashCode;
+
     /**
      * Creates a new workspace repository of type {@code "workspace"} and a random key.
      */
@@ -58,14 +62,15 @@ public WorkspaceRepository(String type) {
     public WorkspaceRepository(String type, Object key) {
         this.type = (type != null) ? type : "";
         this.key = (key != null) ? key : UUID.randomUUID().toString().replace("-", "");
+        this.hashCode = Objects.hash(type, key);
     }
 
     public String getContentType() {
         return type;
     }
 
     public String getId() {
-        return "workspace";
+        return ID;
     }
 
     /**
@@ -99,9 +104,6 @@ public boolean equals(Object obj) {
 
     @Override
     public int hashCode() {
-        int hash = 17;
-        hash = hash * 31 + getKey().hashCode();
-        hash = hash * 31 + getContentType().hashCode();
-        return hash;
+        return hashCode;
     }
 }
diff --git a/...ver-demo-snippets/src/main/java/org/apache/maven/resolver/examples/resolver/Resolver.java b/...ver-demo-snippets/src/main/java/org/apache/maven/resolver/examples/resolver/Resolver.java
@@ -21,6 +21,7 @@
 import java.io.ByteArrayOutputStream;
 import java.io.PrintStream;
 import java.nio.charset.StandardCharsets;
+import java.nio.file.Path;
 
 import org.apache.maven.resolver.examples.util.Booter;
 import org.eclipse.aether.RepositorySystem;
@@ -55,7 +56,7 @@ public class Resolver {
 
     private final LocalRepository localRepository;
 
-    public Resolver(String[] args, String remoteRepository, String localRepository) {
+    public Resolver(String[] args, String remoteRepository, Path localRepository) {
         this.args = args;
         this.remoteRepository = remoteRepository;
         this.repositorySystem = Booter.newRepositorySystem(Booter.selectFactory(args));

diff --git a/...demo-snippets/src/main/java/org/apache/maven/resolver/examples/resolver/ResolverDemo.java b/...demo-snippets/src/main/java/org/apache/maven/resolver/examples/resolver/ResolverDemo.java
@@ -19,6 +19,7 @@
 package org.apache.maven.resolver.examples.resolver;
 
 import java.io.File;
+import java.nio.file.Paths;
 import java.util.List;
 
 import org.eclipse.aether.artifact.Artifact;
@@ -37,7 +38,8 @@ public static void main(String[] args) throws Exception {
         System.out.println("------------------------------------------------------------");
         System.out.println(ResolverDemo.class.getSimpleName());
 
-        Resolver resolver = new Resolver(args, "https://repo.maven.apache.org/maven2/", "target/resolver-demo-repo");
+        Resolver resolver =
+                new Resolver(args, "https://repo.maven.apache.org/maven2/", Paths.get("target/resolver-demo-repo"));
         ResolverResult result = resolver.resolve("junit", "junit", "4.13.2");
 
         System.out.println("Result:");
@@ -47,8 +49,8 @@ public static void main(String[] args) throws Exception {
     }
 
     public void resolve(String[] args) throws DependencyResolutionException {
-        Resolver resolver =
-                new Resolver(args, "http://localhost:8081/nexus/content/groups/public", "target/aether-repo");
+        Resolver resolver = new Resolver(
+                args, "http://localhost:8081/nexus/content/groups/public", Paths.get("target/aether-repo"));
 
         ResolverResult result = resolver.resolve("com.mycompany.app", "super-app", "1.0");
 
@@ -66,8 +68,8 @@ public void resolve(String[] args) throws DependencyResolutionException {
     }
 
     public void installAndDeploy(String[] args) throws InstallationException, DeploymentException {
-        Resolver resolver =
-                new Resolver(args, "http://localhost:8081/nexus/content/groups/public", "target/aether-repo");
+        Resolver resolver = new Resolver(
+                args, "http://localhost:8081/nexus/content/groups/public", Paths.get("target/aether-repo"));
 
         Artifact artifact = new DefaultArtifact("com.mycompany.super", "super-core", "jar", "0.1-SNAPSHOT");
         artifact = artifact.setFile(new File("jar-from-whatever-process.jar"));

diff --git a/...src/main/java/org/eclipse/aether/internal/impl/DefaultLocalPathPrefixComposerFactory.java b/...src/main/java/org/eclipse/aether/internal/impl/DefaultLocalPathPrefixComposerFactory.java
@@ -21,11 +21,12 @@
 import javax.inject.Named;
 import javax.inject.Singleton;
 
-import java.util.function.Function;
+import java.util.function.BiFunction;
 
 import org.eclipse.aether.RepositorySystemSession;
-import org.eclipse.aether.repository.ArtifactRepository;
-import org.eclipse.aether.util.repository.RepositoryIdHelper;
+import org.eclipse.aether.repository.RemoteRepository;
+
+import static org.eclipse.aether.internal.impl.EnhancedLocalRepositoryManagerFactory.repositoryKeyFunction;
 
 /**
  * Default local path prefix composer factory: it fully reuses {@link LocalPathPrefixComposerFactorySupport} class
@@ -48,7 +49,7 @@ public LocalPathPrefixComposer createComposer(RepositorySystemSession session) {
                 isSplitRemoteRepositoryLast(session),
                 getReleasesPrefix(session),
                 getSnapshotsPrefix(session),
-                RepositoryIdHelper.cachedIdToPathSegment(session));
+                repositoryKeyFunction(session));
     }
 
     /**
@@ -66,7 +67,7 @@ private DefaultLocalPathPrefixComposer(
                 boolean splitRemoteRepositoryLast,
                 String releasesPrefix,
                 String snapshotsPrefix,
-                Function<ArtifactRepository, String> idToPathSegmentFunction) {
+                BiFunction<RemoteRepository, String, String> repositoryKeyFunction) {
             super(
                     split,
                     localPrefix,
@@ -77,7 +78,7 @@ private DefaultLocalPathPrefixComposer(
                     splitRemoteRepositoryLast,
                     releasesPrefix,
                     snapshotsPrefix,
-                    idToPathSegmentFunction);
+                    repositoryKeyFunction);
         }
     }
 }
diff --git a/...r-impl/src/main/java/org/eclipse/aether/internal/impl/EnhancedLocalRepositoryManager.java b/...r-impl/src/main/java/org/eclipse/aether/internal/impl/EnhancedLocalRepositoryManager.java
@@ -27,12 +27,11 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Properties;
-import java.util.function.Function;
+import java.util.function.BiFunction;
 
 import org.eclipse.aether.RepositorySystemSession;
 import org.eclipse.aether.artifact.Artifact;
 import org.eclipse.aether.metadata.Metadata;
-import org.eclipse.aether.repository.ArtifactRepository;
 import org.eclipse.aether.repository.LocalArtifactRegistration;
 import org.eclipse.aether.repository.LocalArtifactRequest;
 import org.eclipse.aether.repository.LocalArtifactResult;
@@ -72,11 +71,11 @@ class EnhancedLocalRepositoryManager extends SimpleLocalRepositoryManager {
     EnhancedLocalRepositoryManager(
             Path basedir,
             LocalPathComposer localPathComposer,
-            Function<ArtifactRepository, String> idToPathSegmentFunction,
+            BiFunction<RemoteRepository, String, String> repositoryKeyFunction,
             String trackingFilename,
             TrackingFileManager trackingFileManager,
             LocalPathPrefixComposer localPathPrefixComposer) {
-        super(basedir, "enhanced", localPathComposer, idToPathSegmentFunction);
+        super(basedir, "enhanced", localPathComposer, repositoryKeyFunction);
         this.trackingFilename = requireNonNull(trackingFilename);
         this.trackingFileManager = requireNonNull(trackingFileManager);
         this.localPathPrefixComposer = requireNonNull(localPathPrefixComposer);

diff --git a/...src/main/java/org/eclipse/aether/internal/impl/EnhancedLocalRepositoryManagerFactory.java b/...src/main/java/org/eclipse/aether/internal/impl/EnhancedLocalRepositoryManagerFactory.java
@@ -22,11 +22,16 @@
 import javax.inject.Named;
 import javax.inject.Singleton;
 
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+import java.util.function.BiFunction;
+
 import org.eclipse.aether.ConfigurationProperties;
 import org.eclipse.aether.RepositorySystemSession;
 import org.eclipse.aether.repository.LocalRepository;
 import org.eclipse.aether.repository.LocalRepositoryManager;
 import org.eclipse.aether.repository.NoLocalRepositoryManagerException;
+import org.eclipse.aether.repository.RemoteRepository;
 import org.eclipse.aether.spi.localrepo.LocalRepositoryManagerFactory;
 import org.eclipse.aether.util.ConfigUtils;
 import org.eclipse.aether.util.repository.RepositoryIdHelper;
@@ -58,6 +63,25 @@ public class EnhancedLocalRepositoryManagerFactory implements LocalRepositoryMan
 
     public static final String DEFAULT_TRACKING_FILENAME = "_remote.repositories";
 
+    /**
+     * Make enhanced repository use "globally unique repository keys" (repository keys are used for designating
+     * cached metadata, artifact availability tracking and split repository prefix production). By default, this
+     * option is disabled. If enabled, repository keys produced by enhanced repository will be <em>way different
+     * that those produced with previous versions or without this option enabled</em>. Ideally, you may want to
+     * use empty local repository to populate with new repository key contained metadata, Interoperability between
+     * enabled and disabled affects only metadata and split repository (ie. split repository may not find existing
+     * caches, and may opt to re-download them).
+     *
+     * @since 2.0.14
+     * @configurationSource {@link RepositorySystemSession#getConfigProperties()}
+     * @configurationType {@link java.lang.Boolean}
+     * @configurationDefaultValue {@link #DEFAULT_GLOBALLY_UNIQUE_REPOSITORY_KEYS}
+     */
+    public static final String CONFIG_PROP_GLOBALLY_UNIQUE_REPOSITORY_KEYS =
+            CONFIG_PROPS_PREFIX + "globallyUniqueRepositoryKeys";
+
+    public static final boolean DEFAULT_GLOBALLY_UNIQUE_REPOSITORY_KEYS = false;
+
     private float priority = 10.0f;
 
     private final LocalPathComposer localPathComposer;
@@ -66,6 +90,32 @@ public class EnhancedLocalRepositoryManagerFactory implements LocalRepositoryMan
 
     private final LocalPathPrefixComposerFactory localPathPrefixComposerFactory;
 
+    /**
+     * Method that based on configuration returns the "repository key function". Used by {@link EnhancedLocalRepositoryManagerFactory}
+     * and {@link LocalPathPrefixComposerFactory}.
+     *
+     * @since 2.0.14
+     */
+    @SuppressWarnings("unchecked")
+    static BiFunction<RemoteRepository, String, String> repositoryKeyFunction(RepositorySystemSession session) {
+        if (ConfigUtils.getBoolean(
+                session, DEFAULT_GLOBALLY_UNIQUE_REPOSITORY_KEYS, CONFIG_PROP_GLOBALLY_UNIQUE_REPOSITORY_KEYS)) {
+            // this is expensive method; cache it in session (repo -> context -> ID)
+            return (repository, context) -> ((ConcurrentMap<RemoteRepository, ConcurrentMap<String, String>>)
+                            session.getData()
+                                    .computeIfAbsent(
+                                            EnhancedLocalRepositoryManagerFactory.class.getName()
+                                                    + ".repositoryKeyFunction",
+                                            ConcurrentHashMap::new))
+                    .computeIfAbsent(repository, k1 -> new ConcurrentHashMap<>())
+                    .computeIfAbsent(
+                            context == null ? "" : context,
+                            k2 -> RepositoryIdHelper.globallyUniqueRepositoryKey(repository, context));
+        } else {
+            return RepositoryIdHelper::simpleRepositoryKey;
+        }
+    }
+
     @Inject
     public EnhancedLocalRepositoryManagerFactory(
             final LocalPathComposer localPathComposer,
@@ -94,7 +144,7 @@ public LocalRepositoryManager newInstance(RepositorySystemSession session, Local
             return new EnhancedLocalRepositoryManager(
                     repository.getBasePath(),
                     localPathComposer,
-                    RepositoryIdHelper.cachedIdToPathSegment(session),
+                    repositoryKeyFunction(session),
                     trackingFilename,
                     trackingFileManager,
                     localPathPrefixComposerFactory.createComposer(session));

diff --git a/...src/main/java/org/eclipse/aether/internal/impl/LocalPathPrefixComposerFactorySupport.java b/...src/main/java/org/eclipse/aether/internal/impl/LocalPathPrefixComposerFactorySupport.java
@@ -18,12 +18,11 @@
  */
 package org.eclipse.aether.internal.impl;
 
-import java.util.function.Function;
+import java.util.function.BiFunction;
 
 import org.eclipse.aether.RepositorySystemSession;
 import org.eclipse.aether.artifact.Artifact;
 import org.eclipse.aether.metadata.Metadata;
-import org.eclipse.aether.repository.ArtifactRepository;
 import org.eclipse.aether.repository.RemoteRepository;
 import org.eclipse.aether.util.ConfigUtils;
 
@@ -244,7 +243,7 @@ protected abstract static class LocalPathPrefixComposerSupport implements LocalP
 
         protected final String snapshotsPrefix;
 
-        protected final Function<ArtifactRepository, String> idToPathSegmentFunction;
+        protected final BiFunction<RemoteRepository, String, String> repositoryKeyFunction;
 
         protected LocalPathPrefixComposerSupport(
                 boolean split,
@@ -256,7 +255,7 @@ protected LocalPathPrefixComposerSupport(
                 boolean splitRemoteRepositoryLast,
                 String releasesPrefix,
                 String snapshotsPrefix,
-                Function<ArtifactRepository, String> idToPathSegmentFunction) {
+                BiFunction<RemoteRepository, String, String> repositoryKeyFunction) {
             this.split = split;
             this.localPrefix = localPrefix;
             this.splitLocal = splitLocal;
@@ -266,7 +265,7 @@ protected LocalPathPrefixComposerSupport(
             this.splitRemoteRepositoryLast = splitRemoteRepositoryLast;
             this.releasesPrefix = releasesPrefix;
             this.snapshotsPrefix = snapshotsPrefix;
-            this.idToPathSegmentFunction = idToPathSegmentFunction;
+            this.repositoryKeyFunction = repositoryKeyFunction;
         }
 
         @Override
@@ -288,13 +287,13 @@ public String getPathPrefixForRemoteArtifact(Artifact artifact, RemoteRepository
             }
             String result = remotePrefix;
             if (!splitRemoteRepositoryLast && splitRemoteRepository) {
-                result += "/" + idToPathSegmentFunction.apply(repository);
+                result += "/" + repositoryKeyFunction.apply(repository, null);
             }
             if (splitRemote) {
                 result += "/" + (artifact.isSnapshot() ? snapshotsPrefix : releasesPrefix);
             }
             if (splitRemoteRepositoryLast && splitRemoteRepository) {
-                result += "/" + idToPathSegmentFunction.apply(repository);
+                result += "/" + repositoryKeyFunction.apply(repository, null);
             }
             return result;
         }
@@ -318,13 +317,13 @@ public String getPathPrefixForRemoteMetadata(Metadata metadata, RemoteRepository
             }
             String result = remotePrefix;
             if (!splitRemoteRepositoryLast && splitRemoteRepository) {
-                result += "/" + idToPathSegmentFunction.apply(repository);
+                result += "/" + repositoryKeyFunction.apply(repository, null);
             }
             if (splitRemote) {
                 result += "/" + (isSnapshot(metadata) ? snapshotsPrefix : releasesPrefix);
             }
             if (splitRemoteRepositoryLast && splitRemoteRepository) {
-                result += "/" + idToPathSegmentFunction.apply(repository);
+                result += "/" + repositoryKeyFunction.apply(repository, null);
             }
             return result;
         }