[MRESOLVER-302] Introduce onSessionClose

maven-resolver-api/src/main/java/org/eclipse/aether/AbstractForwardingRepositorySystemSession.java

@@ -190,4 +190,9 @@ public SessionData getData() {
     public RepositoryCache getCache() {
         return getSession().getCache();
     }
+
+    @Override
+    public boolean addOnSessionEndedHandler(Runnable handler) {
+        return getSession().addOnSessionEndedHandler(handler);
+    }
 }

maven-resolver-api/src/main/java/org/eclipse/aether/DefaultRepositorySystemSession.java

@@ -21,6 +21,7 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.function.Function;
 
 import org.eclipse.aether.artifact.ArtifactType;
 import org.eclipse.aether.artifact.ArtifactTypeRegistry;
@@ -51,10 +52,9 @@
  * <strong>Note:</strong> This class is not thread-safe. It is assumed that the mutators get only called during an
  * initialization phase and that the session itself is not changed once initialized and being used by the repository
  * system. It is recommended to call {@link #setReadOnly()} once the session has been fully initialized to prevent
- * accidental manipulation of it afterwards.
+ * accidental manipulation of it afterward.
  */
 public final class DefaultRepositorySystemSession implements RepositorySystemSession {
-
     private boolean readOnly;
 
     private boolean offline;
@@ -113,11 +113,18 @@ public final class DefaultRepositorySystemSession implements RepositorySystemSes
 
     private RepositoryCache cache;
 
+    private final Function<Runnable, Boolean> onSessionEndedRegistrar;
+
     /**
      * Creates an uninitialized session. <em>Note:</em> The new session is not ready to use, as a bare minimum,
      * {@link #setLocalRepositoryManager(LocalRepositoryManager)} needs to be called but usually other settings also
      * need to be customized to achieve meaningful behavior.
+     *
+     * @deprecated This way of creating session should be avoided, is in place just to offer backward binary
+     * compatibility with Resolver 1.x using code, but offers reduced functionality.
+     * Use {@link RepositorySystem#createSessionBuilder()} instead.
      */
+    @Deprecated
     public DefaultRepositorySystemSession() {
         systemProperties = new HashMap<>();
         systemPropertiesView = Collections.unmodifiableMap(systemProperties);
@@ -130,6 +137,7 @@ public DefaultRepositorySystemSession() {
         authenticationSelector = NullAuthenticationSelector.INSTANCE;
         artifactTypeRegistry = NullArtifactTypeRegistry.INSTANCE;
         data = new DefaultSessionData();
+        onSessionEndedRegistrar = h -> false;
     }
 
     /**
@@ -168,6 +176,7 @@ public DefaultRepositorySystemSession(RepositorySystemSession session) {
         setDependencyGraphTransformer(session.getDependencyGraphTransformer());
         setData(session.getData());
         setCache(session.getCache());
+        this.onSessionEndedRegistrar = session::addOnSessionEndedHandler;
     }
 
     @Override
@@ -766,6 +775,17 @@ public DefaultRepositorySystemSession setCache(RepositoryCache cache) {
         return this;
     }
 
+    /**
+     * Registers onSessionEnded handler, if able to.
+     *
+     * @param handler The handler to register
+     * @return Return {@code true} if registration was possible, otherwise {@code false}.
+     */
+    @Override
+    public boolean addOnSessionEndedHandler(Runnable handler) {
+        return onSessionEndedRegistrar.apply(handler);
+    }
+
     /**
      * Marks this session as read-only such that any future attempts to call its mutators will fail with an exception.
      * Marking an already read-only session as read-only has no effect. The session's data and cache remain writable

maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystem.java

@@ -18,6 +18,7 @@
  */
 package org.eclipse.aether;
 
+import java.io.Closeable;
 import java.util.Collection;
 import java.util.List;
 
@@ -65,7 +66,7 @@
  * @noimplement This interface is not intended to be implemented by clients.
  * @noextend This interface is not intended to be extended by clients.
  */
-public interface RepositorySystem {
+public interface RepositorySystem extends Closeable {
 
     /**
      * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
@@ -277,7 +278,7 @@ List<RemoteRepository> newResolutionRepositories(
      * {@link #deploy(RepositorySystemSession, DeployRequest) deploy()} is used as is and expected to already carry any
      * required authentication or proxy configuration. This method can be used to apply the authentication/proxy
      * configuration from a session to a bare repository definition to obtain the complete repository definition for use
-     * in the deploy request.
+     * in the deployment request.
      *
      * @param session    The repository system session from which to configure the repository, must not be {@code null}.
      * @param repository The repository prototype from which to derive the deployment repository, must not be
@@ -295,6 +296,15 @@ List<RemoteRepository> newResolutionRepositories(
      */
     void addOnSystemEndedHandler(Runnable handler);
 
+    /**
+     * Creates a brand-new session builder instance that produces "top level" (root) session. Top level sessions are
+     * associated with its creator {@link RepositorySystem} instance, and may be used only with that given instance and
+     * only within the lifespan of it, and after use should be closed.
+     *
+     * @since TBD
+     */
+    RepositorySystemSession.SessionBuilder createSessionBuilder();
+
     /**
      * Signals to repository system to shut down. Shut down instance is not usable anymore.
      * <p>
@@ -308,4 +318,14 @@ List<RemoteRepository> newResolutionRepositories(
      * @since 1.9.0
      */
     void shutdown();
+
+    /**
+     * Closes this instance, invokes {@link #shutdown()}.
+     *
+     * @since TBD
+     */
+    @Override
+    default void close() {
+        shutdown();
+    }
 }