[MNG-8558] Switch toolchain support for v4 API

api/maven-api-core/src/main/java/org/apache/maven/api/Session.java

@@ -34,6 +34,7 @@
 import org.apache.maven.api.services.DependencyCoordinatesFactory;
 import org.apache.maven.api.services.VersionResolverException;
 import org.apache.maven.api.settings.Settings;
+import org.apache.maven.api.toolchain.ToolchainModel;
 
 /**
  * The session to install / deploy / resolve artifacts and dependencies.
@@ -60,6 +61,14 @@ public interface Session extends ProtoSession {
     @Nonnull
     Settings getSettings();
 
+    /**
+     * Retrieves toolchain models that have been explicitly configured.
+     *
+     * @return the toolchain models
+     */
+    @Nonnull
+    Collection<ToolchainModel> getToolchains();
+
     /**
      * Retrieves the local repository associated with this session.
      *

api/maven-api-core/src/main/java/org/apache/maven/api/Toolchain.java

@@ -21,6 +21,7 @@
 import java.util.Map;
 
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.toolchain.ToolchainModel;
 
 /**
  * Represents a toolchain in the Maven build system.
@@ -70,6 +71,13 @@ public interface Toolchain {
      */
     String getType();
 
+    /**
+     * Gets the underlying toolchain model.
+     *
+     * @return the toolchain model
+     */
+    ToolchainModel getModel();
+
     /**
      * Gets the platform tool executable.
      *

api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainFactory.java

@@ -18,14 +18,41 @@
  */
 package org.apache.maven.api.services;
 
+import java.util.Optional;
+
+import org.apache.maven.api.Toolchain;
 import org.apache.maven.api.annotations.Consumer;
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.toolchain.ToolchainModel;
 
 /**
+ * Factory interface for creating toolchain instances from configuration models.
+ *
+ * <p>This factory is responsible for instantiating concrete toolchain implementations
+ * based on toolchain model configurations or default settings.</p>
+ *
  * @since 4.0.0
  */
 @Experimental
 @Consumer
 public interface ToolchainFactory {
-    // TODO: implement ToolchainFactory
+    /**
+     * Creates a toolchain instance from the provided model configuration.
+     *
+     * @param model The toolchain configuration model
+     * @return A configured toolchain instance
+     * @throws ToolchainFactoryException if toolchain creation fails
+     */
+    @Nonnull
+    Toolchain createToolchain(@Nonnull ToolchainModel model) throws ToolchainFactoryException;
+
+    /**
+     * Creates a default toolchain instance using system defaults.
+     *
+     * @return Optional containing the default toolchain if available
+     * @throws ToolchainFactoryException if default toolchain creation fails
+     */
+    @Nonnull
+    Optional<Toolchain> createDefaultToolchain() throws ToolchainFactoryException;
 }

api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainFactoryException.java

@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.services;
+
+/**
+ * Exception thrown when toolchain factory operations fail.
+ *
+ * <p>This exception wraps errors that occur during toolchain creation or initialization.</p>
+ */
+public class ToolchainFactoryException extends MavenException {
+
+    public ToolchainFactoryException(String message) {
+        super(message);
+    }
+
+    public ToolchainFactoryException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    public ToolchainFactoryException(Throwable cause) {
+        super(cause);
+    }
+}

api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainManager.java

@@ -29,50 +29,63 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * Service to manage {@link Toolchain}s.
+ * Service interface for managing Maven toolchains, which provide abstraction for different
+ * build tools and environments.
+ *
+ * <p>A toolchain represents a specific build tool configuration (e.g., JDK, compiler) that can be
+ * used during the Maven build process. This service allows for retrieving, storing, and managing
+ * these toolchains.</p>
  *
  * @since 4.0.0
  */
 @Experimental
 public interface ToolchainManager extends Service {
 
     /**
+     * Retrieves toolchains matching the specified type and requirements.
      *
-     * @param session
-     * @param type
-     * @param requirements
-     * @return the selected {@link Toolchain}s
-     * @throws ToolchainManagerException if an exception occurs
+     * @param session The Maven session context
+     * @param type The type of toolchain (e.g., "jdk", "compiler")
+     * @param requirements Key-value pairs specifying toolchain requirements (e.g., "version": "11")
+     * @return List of matching toolchains, never null
+     * @throws ToolchainManagerException if toolchain retrieval fails
      */
     @Nonnull
     List<Toolchain> getToolchains(@Nonnull Session session, String type, Map<String, String> requirements);
 
     /**
+     * Retrieves all toolchains of the specified type without additional requirements.
      *
-     * @param session
-     * @param type
-     * @return the selected {@link Toolchain}
-     * @throws ToolchainManagerException if an exception occurs
+     * @param session The Maven session context
+     * @param type The type of toolchain to retrieve
+     * @return List of matching toolchains, never null
+     * @throws ToolchainManagerException if toolchain retrieval fails
      */
     @Nonnull
-    Optional<Toolchain> getToolchainFromBuildContext(@Nonnull Session session, String type)
-            throws ToolchainManagerException;
+    default List<Toolchain> getToolchains(@Nonnull Session session, @Nonnull String type)
+            throws ToolchainManagerException {
+        return getToolchains(session, type, null);
+    }
 
     /**
+     * Retrieves the currently active toolchain from the build context.
      *
-     * @param session
-     * @param type
-     * @return the selected {@link Toolchain}s
-     * @throws ToolchainManagerException if an exception occurs
+     * @param session The Maven session context
+     * @param type The type of toolchain to retrieve
+     * @return Optional containing the toolchain if found
+     * @throws ToolchainManagerException if toolchain retrieval fails
      */
     @Nonnull
-    List<Toolchain> getToolchainsForType(@Nonnull Session session, String type) throws ToolchainManagerException;
+    Optional<Toolchain> getToolchainFromBuildContext(@Nonnull Session session, @Nonnull String type)
+            throws ToolchainManagerException;
 
     /**
+     * Stores a toolchain in the build context for later retrieval.
      *
-     * @param session
-     * @param toolchain
-     * @throws ToolchainManagerException if an exception occurs
+     * @param session The Maven session context
+     * @param toolchain The toolchain to store
+     * @throws ToolchainManagerException if storing the toolchain fails
      */
-    void storeToolchainToBuildContext(@Nonnull Session session, Toolchain toolchain) throws ToolchainManagerException;
+    void storeToolchainToBuildContext(@Nonnull Session session, @Nonnull Toolchain toolchain)
+            throws ToolchainManagerException;
 }

compat/maven-compat/src/main/java/org/apache/maven/toolchain/DefaultToolchainManager.java

@@ -0,0 +1,83 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.toolchain;
+
+import javax.inject.Inject;
+import javax.inject.Named;
+import javax.inject.Singleton;
+
+import java.util.List;
+import java.util.Map;
+
+import org.apache.maven.execution.MavenSession;
+import org.apache.maven.impl.MappedList;
+import org.apache.maven.toolchain.model.ToolchainModel;
+
+@Named
+@Singleton
+public class DefaultToolchainManager implements ToolchainManager {
+
+    private final org.apache.maven.internal.impl.DefaultToolchainManager delegate;
+
+    @Inject
+    public DefaultToolchainManager(org.apache.maven.internal.impl.DefaultToolchainManager delegate) {
+        this.delegate = delegate;
+    }
+
+    @Override
+    public Toolchain getToolchainFromBuildContext(String type, MavenSession session) {
+        return delegate.getToolchainFromBuildContext(session.getSession(), type)
+                .map(tc -> (Toolchain) new ToolchainWrapper(tc))
+                .orElse(null);
+    }
+
+    @Override
+    public List<Toolchain> getToolchains(MavenSession session, String type, Map<String, String> requirements) {
+        return new MappedList<>(
+                delegate.getToolchains(session.getSession(), type, requirements), tc -> new ToolchainWrapper(tc));
+    }
+
+    private static class ToolchainWrapper implements Toolchain, ToolchainPrivate {
+        private final org.apache.maven.api.Toolchain delegate;
+
+        ToolchainWrapper(org.apache.maven.api.Toolchain delegate) {
+            this.delegate = delegate;
+        }
+
+        @Override
+        public String getType() {
+            return delegate.getType();
+        }
+
+        @Override
+        public String findTool(String toolName) {
+            return delegate.findTool(toolName);
+        }
+
+        @Override
+        public boolean matchesRequirements(Map<String, String> requirements) {
+            return delegate.matchesRequirements(requirements);
+        }
+
+        @Override
+        public ToolchainModel getModel() {
+            return new ToolchainModel(delegate.getModel());
+        }
+    }
+}

compat/maven-compat/src/main/java/org/apache/maven/toolchain/DefaultToolchainManagerPrivate.java

@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.toolchain;
+
+import javax.inject.Inject;
+import javax.inject.Named;
+import javax.inject.Singleton;
+
+import java.util.List;
+import java.util.Map;
+
+import org.apache.maven.execution.MavenSession;
+import org.apache.maven.internal.impl.DefaultToolchainManager;
+import org.apache.maven.toolchain.model.ToolchainModel;
+
+@Named
+@Singleton
+public class DefaultToolchainManagerPrivate implements ToolchainManagerPrivate {
+
+    private final DefaultToolchainManager delegate;
+
+    @Inject
+    public DefaultToolchainManagerPrivate(DefaultToolchainManager delegate) {
+        this.delegate = delegate;
+    }
+
+    @Override
+    public ToolchainPrivate[] getToolchainsForType(String type, MavenSession session)
+            throws MisconfiguredToolchainException {
+        try {
+            List<org.apache.maven.api.Toolchain> toolchains = delegate.getToolchains(session.getSession(), type);
+            return toolchains.stream()
+                    .map(tc -> (ToolchainPrivate) new ToolchainWrapper(tc))
+                    .toArray(ToolchainPrivate[]::new);
+        } catch (org.apache.maven.api.services.ToolchainManagerException e) {
+            throw new MisconfiguredToolchainException(e.getMessage(), e);
+        }
+    }
+
+    @Override
+    public void storeToolchainToBuildContext(ToolchainPrivate toolchain, MavenSession session) {
+        delegate.storeToolchainToBuildContext(session.getSession(), ((ToolchainWrapper) toolchain).delegate);
+    }
+
+    private static class ToolchainWrapper implements ToolchainPrivate {
+        private final org.apache.maven.api.Toolchain delegate;
+
+        ToolchainWrapper(org.apache.maven.api.Toolchain delegate) {
+            this.delegate = delegate;
+        }
+
+        @Override
+        public String getType() {
+            return delegate.getType();
+        }
+
+        @Override
+        public ToolchainModel getModel() {
+            return new ToolchainModel(delegate.getModel());
+        }
+
+        @Override
+        public boolean matchesRequirements(Map<String, String> requirements) {
+            return delegate.matchesRequirements(requirements);
+        }
+
+        @Override
+        public String findTool(String toolName) {
+            return "";
+        }
+    }
+}