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.apache.maven.api;
20  
21  import java.util.Map;
22  
23  import org.apache.maven.api.annotations.Experimental;
24  
25  /**
26   * Represents a toolchain in the Maven build system.
27   *
28   * <p>A toolchain is a set of tools that can be used to build a project.
29   * This interface allows users to define and configure various toolchains
30   * that can be utilized by Maven during the build process. Toolchains can
31   * include compilers, interpreters, and other tools that are necessary
32   * for building a project in a specific environment.</p>
33   *
34   * <p>Toolchains are defined in the Maven toolchains.xml file and can be
35   * referenced in the project's POM file. This allows for greater flexibility
36   * and control over the build environment, enabling developers to specify
37   * the exact versions of tools they wish to use.</p>
38   *
39   * <p>
40   * Toolchains can be obtained through the {@link org.apache.maven.api.services.ToolchainManager ToolchainManager}
41   * service. This service provides methods to retrieve and manage toolchains defined
42   * in the Maven configuration.
43   * </p>
44   *
45   * <p>
46   * The following are key functionalities provided by the Toolchain interface:</p><ul>
47   *   <li>Access to the type of the toolchain (e.g., JDK, compiler).</li>
48   *   <li>Retrieval of the specific version of the toolchain.</li>
49   *   <li>Configuration of toolchain properties to match the project's requirements.</li>
50   * </ul>
51   *
52   * <p>Example usage:</p>
53   * <pre>
54   * Toolchain toolchain = ...; // Obtain a Toolchain instance
55   * String type = toolchain.getType(); // Get the type of the toolchain
56   * String version = toolchain.getVersion(); // Get the version of the toolchain
57   * </pre>
58   *
59   *
60   * @since 4.0.0
61   * @see JavaToolchain
62   * @see org.apache.maven.api.services.ToolchainManager
63   */
64  @Experimental
65  public interface Toolchain {
66      /**
67       * Gets the type of toolchain.
68       *
69       * @return the toolchain type
70       */
71      String getType();
72  
73      /**
74       * Gets the platform tool executable.
75       *
76       * @param toolName the tool platform independent tool name
77       * @return file representing the tool executable, or null if the tool cannot be found
78       */
79      String findTool(String toolName);
80  
81      /**
82       * Let the toolchain decide if it matches requirements defined
83       * in the toolchain plugin configuration.
84       *
85       * @param requirements key value pair, may not be {@code null}
86       * @return {@code true} if the requirements match, otherwise {@code false}
87       */
88      boolean matchesRequirements(Map<String, String> requirements);
89  }