This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch deprecation in repository https://gitbox.apache.org/repos/asf/maven-invoker.git
commit ed96130a8eb3519040e27c82d0b0d5340a8d2e6a Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Tue Dec 30 14:42:06 2025 +0000 Mark maven-invoker component as deprecated Related: #164, apache/maven-verifier#186 --- MIGRATION.md | 294 +++++++++++++++++++++ README.md | 15 ++ pom.xml | 12 +- .../shared/invoker/DefaultInvocationRequest.java | 7 + .../shared/invoker/DefaultInvocationResult.java | 7 + .../maven/shared/invoker/DefaultInvoker.java | 7 + .../maven/shared/invoker/InvocationRequest.java | 7 + .../maven/shared/invoker/InvocationResult.java | 7 + .../org/apache/maven/shared/invoker/Invoker.java | 7 + .../apache/maven/shared/invoker/package-info.java | 75 ++++++ src/site/apt/index.apt.vm | 24 ++ src/site/apt/migration.apt.vm | 263 ++++++++++++++++++ src/site/apt/usage.apt.vm | 8 + src/site/site.xml | 1 + .../maven/shared/invoker/DefaultInvokerTest.java | 1 + .../invoker/MavenCommandLineBuilderTest.java | 1 + .../maven/shared/invoker/SystemOutHandlerTest.java | 1 + .../maven/shared/invoker/SystemOutLoggerTest.java | 1 + 18 files changed, 737 insertions(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..d984103 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,294 @@ +<!--- + 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. +--> + +# Migration from maven-invoker to maven-executor + +## Overview + +The `maven-invoker` component is deprecated and replaced by [`maven-executor`](https://github.com/apache/maven/tree/master/impl/maven-executor), which provides a modern, unified API for programmatically invoking Maven builds. + +## Why Migrate? + +**maven-executor** offers several advantages: + +- **Unified API**: Simple, consistent API that doesn't require updates when Maven CLI changes +- **Maven 3.9+ and Maven 4+ Support**: Works seamlessly with both Maven versions +- **Multiple Execution Modes**: Supports both forked and embedded execution +- **Better Environment Isolation**: Proper isolation of environment variables and system properties +- **Zero Dependencies**: Completely standalone, no additional dependencies required +- **Maintained**: Actively used in Maven 4 Integration Tests + +## Dependency Changes + +### Old (maven-invoker) + +```xml +<dependency> + <groupId>org.apache.maven.shared</groupId> + <artifactId>maven-invoker</artifactId> +</dependency> +``` + +### New (maven-executor) + +**Option 1: Using Maven 4+ (recommended)** + +```xml +<dependency> + <groupId>org.apache.maven</groupId> + <artifactId>maven-executor</artifactId> + <version>4.0.0-rc5</version> +</dependency> +``` + +> **Note**: Check the latest Maven 4 releases for current version numbers. + +## API Comparison and Migration Examples + +### Basic Invocation + +#### Old Code (maven-invoker) + +```java +import org.apache.maven.shared.invoker.*; +import java.io.File; +import java.util.Collections; + +InvocationRequest request = new DefaultInvocationRequest(); +request.setPomFile(new File("/path/to/pom.xml")); +request.setGoals(Collections.singletonList("install")); + +Invoker invoker = new DefaultInvoker(); +InvocationResult result = invoker.execute(request); + +if (result.getExitCode() != 0) { + throw new IllegalStateException("Build failed."); +} +``` + +#### New Code (maven-executor) + +```java +import org.apache.maven.api.cli.*; +import org.apache.maven.cling.executor.*; +import java.nio.file.Path; +import java.nio.file.Paths; + +// Using forked executor +ExecutorRequest request = ExecutorRequest.builder() + .cwd(Paths.get("/path/to")) + .command("mvn") + .args(new String[]{"install"}) + .build(); + +ForkedExecutor executor = new ForkedExecutor(); +int exitCode = executor.execute(request); + +if (exitCode != 0) { + throw new IllegalStateException("Build failed."); +} +``` + +### Setting Goals and Options + +#### Old Code (maven-invoker) + +```java +InvocationRequest request = new DefaultInvocationRequest(); +request.setPomFile(new File("/path/to/pom.xml")); +request.setGoals(Arrays.asList("clean", "install")); +request.setBatchMode(true); +request.setOffline(true); +request.setDebug(true); +request.setProperties(properties); +``` + +#### New Code (maven-executor) + +```java +ExecutorRequest request = ExecutorRequest.builder() + .cwd(Paths.get("/path/to")) + .command("mvn") + .args(new String[]{ + "clean", "install", + "--batch-mode", + "--offline", + "--debug", + "-Dproperty1=value1", + "-Dproperty2=value2" + }) + .build(); +``` + +### Maven Home Configuration + +#### Old Code (maven-invoker) + +```java +Invoker invoker = new DefaultInvoker(); +invoker.setMavenHome(new File("/path/to/maven")); +``` + +#### New Code (maven-executor) + +```java +// Maven home is automatically detected from MAVEN_HOME or M2_HOME +// or can be specified via command path +ExecutorRequest request = ExecutorRequest.builder() + .command("/path/to/maven/bin/mvn") + .args(new String[]{"install"}) + .build(); +``` + +### Local Repository Configuration + +#### Old Code (maven-invoker) + +```java +InvocationRequest request = new DefaultInvocationRequest(); +request.setLocalRepositoryDirectory(new File("/path/to/local/repo")); +``` + +#### New Code (maven-executor) + +```java +ExecutorRequest request = ExecutorRequest.builder() + .args(new String[]{ + "install", + "-Dmaven.repo.local=/path/to/local/repo" + }) + .build(); +``` + +### Capturing Output + +#### Old Code (maven-invoker) + +```java +InvocationOutputHandler outputHandler = new InvocationOutputHandler() { + @Override + public void consumeLine(String line) { + System.out.println(line); + } +}; + +InvocationRequest request = new DefaultInvocationRequest(); +request.setOutputHandler(outputHandler); +``` + +#### New Code (maven-executor) + +```java +// Output handling through standard Java ProcessBuilder mechanisms +ProcessBuilder.Redirect redirect = ProcessBuilder.Redirect.PIPE; + +// Or use custom output streams +ExecutorRequest request = ExecutorRequest.builder() + .args(new String[]{"install"}) + .outputRedirect(yourOutputStream) + .build(); +``` + +### Embedded Execution + +#### Old Code (maven-invoker) + +```java +// maven-invoker only supports forked execution +``` + +#### New Code (maven-executor) + +```java +// maven-executor supports embedded execution! +import org.apache.maven.cling.executor.EmbeddedExecutor; + +EmbeddedExecutor executor = new EmbeddedExecutor(); +ExecutorRequest request = ExecutorRequest.builder() + .cwd(Paths.get("/path/to/project")) + .args(new String[]{"install"}) + .build(); + +int exitCode = executor.execute(request); +``` + +### Environment Variables + +#### Old Code (maven-invoker) + +```java +InvocationRequest request = new DefaultInvocationRequest(); +request.setShellEnvironmentInherited(true); +// or +request.addShellEnvironment("MY_VAR", "value"); +``` + +#### New Code (maven-executor) + +```java +Map<String, String> env = new HashMap<>(); +env.put("MY_VAR", "value"); + +ExecutorRequest request = ExecutorRequest.builder() + .args(new String[]{"install"}) + .environment(env) + .build(); +``` + +## Complete Migration Checklist + +- [ ] Update dependencies in `pom.xml` +- [ ] Replace `InvocationRequest` with `ExecutorRequest` +- [ ] Replace `Invoker` with `ForkedExecutor` or `EmbeddedExecutor` +- [ ] Convert file paths from `File` to `Path`/`Paths` +- [ ] Convert goals and options to command-line arguments array +- [ ] Update output handling mechanism +- [ ] Update environment variable handling +- [ ] Update system property handling +- [ ] Update test configurations +- [ ] Verify Maven home detection or configuration +- [ ] Test with both Maven 3.9+ and Maven 4+ if needed + +## Key Differences Summary + +| Feature | maven-invoker | maven-executor | +|---------|--------------|----------------| +| API Style | Request/Invoker objects | Builder pattern with args array | +| Maven Versions | Maven 2.x, 3.x | Maven 3.9+, 4+ | +| Execution Modes | Forked only | Forked and Embedded | +| Dependencies | Has dependencies | Zero dependencies | +| CLI Mapping | Manual mapping in code | Direct CLI args | +| Maintenance | Requires updates for CLI changes | No updates needed for CLI changes | + +## Additional Resources + +- [maven-executor source code](https://github.com/apache/maven/tree/master/impl/maven-executor) +- [maven-executor CLI API](https://github.com/apache/maven/tree/master/impl/maven-executor/src/main/java/org/apache/maven/api/cli) +- [maven-executor implementation](https://github.com/apache/maven/tree/master/impl/maven-executor/src/main/java/org/apache/maven/cling/executor) +- [Maven 4 Integration Tests using maven-executor](https://github.com/apache/maven/blob/master/its/core-it-support/maven-it-helper/src/main/java/org/apache/maven/it/Verifier.java) +- [Issue #164 - Deprecation announcement](https://github.com/apache/maven-invoker/issues/164) +- [Related discussion in maven-verifier](https://github.com/apache/maven-verifier/issues/186) + +## Need Help? + +If you encounter migration issues or have questions: + +1. Check the [maven-executor source code](https://github.com/apache/maven/tree/master/impl/maven-executor) for examples +2. Review [Maven 4 IT tests](https://github.com/apache/maven/tree/master/its) that use maven-executor +3. Open an issue on the [maven-invoker repository](https://github.com/apache/maven-invoker/issues) for migration-specific questions +4. Contact the [Maven developer mailing list](https://maven.apache.org/mailing-lists.html) + diff --git a/README.md b/README.md index 9ffe789..3bf6402 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,21 @@ Contributing to [Apache Maven Invoker](https://maven.apache.org/shared/maven-invoker/) ====================== +> **⚠️ DEPRECATION NOTICE** +> +> This project is **deprecated** and will be replaced by [**maven-executor**](https://github.com/apache/maven/tree/master/impl/maven-executor). +> +> **Users should migrate to maven-executor**, which offers: +> - Unified and simpler API that doesn't require updates when Maven CLI changes +> - Support for both Maven 3.9+ and Maven 4+ +> - Both forked and embedded execution modes +> - Proper environment isolation +> - Zero dependencies +> +> For migration guidance, see [MIGRATION.md](MIGRATION.md). +> +> **Related:** [Issue #164](https://github.com/apache/maven-invoker/issues/164) + [][license] [](https://search.maven.org/artifact/org.apache.maven.shared/maven-invoker) [](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/shared/maven-invoker/README.md) diff --git a/pom.xml b/pom.xml index 79a219c..0317945 100644 --- a/pom.xml +++ b/pom.xml @@ -31,7 +31,7 @@ under the License. <version>3.3.1-SNAPSHOT</version> <name>Apache Maven Invoker</name> - <description>A component to programmatically invoke Maven.</description> + <description>DEPRECATED: This component is deprecated and replaced by maven-executor (https://github.com/apache/maven/tree/master/impl/maven-executor). Please migrate to maven-executor for Maven 3.9+ and Maven 4+ support with improved API and features.</description> <contributors> <contributor> @@ -95,6 +95,16 @@ under the License. </testResources> <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-compiler-plugin</artifactId> + <configuration> + <!-- Show deprecation warnings during compilation --> + <compilerArgs> + <arg>-Xlint:deprecation</arg> + </compilerArgs> + </configuration> + </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> diff --git a/src/main/java/org/apache/maven/shared/invoker/DefaultInvocationRequest.java b/src/main/java/org/apache/maven/shared/invoker/DefaultInvocationRequest.java index f26f100..e4cf490 100644 --- a/src/main/java/org/apache/maven/shared/invoker/DefaultInvocationRequest.java +++ b/src/main/java/org/apache/maven/shared/invoker/DefaultInvocationRequest.java @@ -31,7 +31,14 @@ import java.util.Properties; /** * Specifies the parameters used to control a Maven invocation. * + * @deprecated This class is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> + * ExecutorRequest.builder() instead. + * See the <a href="https://maven.apache.org/shared/maven-invoker/migration.html";>Migration Guide</a> + * for details. + * @see <a href="https://github.com/apache/maven-invoker/issues/164";>Issue #164</a> */ +@Deprecated public class DefaultInvocationRequest implements InvocationRequest { private File basedir; diff --git a/src/main/java/org/apache/maven/shared/invoker/DefaultInvocationResult.java b/src/main/java/org/apache/maven/shared/invoker/DefaultInvocationResult.java index cc22f75..eff08a7 100644 --- a/src/main/java/org/apache/maven/shared/invoker/DefaultInvocationResult.java +++ b/src/main/java/org/apache/maven/shared/invoker/DefaultInvocationResult.java @@ -23,7 +23,14 @@ import org.apache.maven.shared.utils.cli.CommandLineException; /** * Describes the result of a Maven invocation. * + * @deprecated This class is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> + * instead. + * See the <a href="https://maven.apache.org/shared/maven-invoker/migration.html";>Migration Guide</a> + * for details. + * @see <a href="https://github.com/apache/maven-invoker/issues/164";>Issue #164</a> */ +@Deprecated public final class DefaultInvocationResult implements InvocationResult { /** diff --git a/src/main/java/org/apache/maven/shared/invoker/DefaultInvoker.java b/src/main/java/org/apache/maven/shared/invoker/DefaultInvoker.java index 80c5939..9d9375f 100644 --- a/src/main/java/org/apache/maven/shared/invoker/DefaultInvoker.java +++ b/src/main/java/org/apache/maven/shared/invoker/DefaultInvoker.java @@ -31,8 +31,15 @@ import org.apache.maven.shared.utils.cli.Commandline; /** * Class intended to be used by clients who wish to invoke a forked Maven process from their applications * + * @deprecated This class is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> + * ForkedExecutor or EmbeddedExecutor instead. + * See the <a href="https://maven.apache.org/shared/maven-invoker/migration.html";>Migration Guide</a> + * for details. * @author jdcasey + * @see <a href="https://github.com/apache/maven-invoker/issues/164";>Issue #164</a> */ +@Deprecated @Named @Singleton public class DefaultInvoker implements Invoker { diff --git a/src/main/java/org/apache/maven/shared/invoker/InvocationRequest.java b/src/main/java/org/apache/maven/shared/invoker/InvocationRequest.java index 0c41043..2c7be47 100644 --- a/src/main/java/org/apache/maven/shared/invoker/InvocationRequest.java +++ b/src/main/java/org/apache/maven/shared/invoker/InvocationRequest.java @@ -28,7 +28,14 @@ import java.util.Properties; /** * Specifies the parameters used to control a Maven invocation. * + * @deprecated This interface is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> + * ExecutorRequest instead, which uses a builder pattern and direct CLI arguments. + * See the <a href="https://maven.apache.org/shared/maven-invoker/migration.html";>Migration Guide</a> + * for details. + * @see <a href="https://github.com/apache/maven-invoker/issues/164";>Issue #164</a> */ +@Deprecated public interface InvocationRequest { /** diff --git a/src/main/java/org/apache/maven/shared/invoker/InvocationResult.java b/src/main/java/org/apache/maven/shared/invoker/InvocationResult.java index 062177a..8db839c 100644 --- a/src/main/java/org/apache/maven/shared/invoker/InvocationResult.java +++ b/src/main/java/org/apache/maven/shared/invoker/InvocationResult.java @@ -23,8 +23,15 @@ import org.apache.maven.shared.utils.cli.CommandLineException; /** * Describes the result of a Maven invocation. * + * @deprecated This interface is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> + * which returns exit codes directly. + * See the <a href="https://maven.apache.org/shared/maven-invoker/migration.html";>Migration Guide</a> + * for details. * @author jdcasey + * @see <a href="https://github.com/apache/maven-invoker/issues/164";>Issue #164</a> */ +@Deprecated public interface InvocationResult { /** diff --git a/src/main/java/org/apache/maven/shared/invoker/Invoker.java b/src/main/java/org/apache/maven/shared/invoker/Invoker.java index f5e1369..bb2263e 100644 --- a/src/main/java/org/apache/maven/shared/invoker/Invoker.java +++ b/src/main/java/org/apache/maven/shared/invoker/Invoker.java @@ -24,7 +24,14 @@ import java.io.InputStream; /** * Provides a facade to invoke Maven. * + * @deprecated This component is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> + * instead, which provides better Maven 3.9+ and Maven 4+ support with a unified API. + * See the <a href="https://maven.apache.org/shared/maven-invoker/migration.html";>Migration Guide</a> + * for details. + * @see <a href="https://github.com/apache/maven-invoker/issues/164";>Issue #164</a> */ +@Deprecated public interface Invoker { /** diff --git a/src/main/java/org/apache/maven/shared/invoker/package-info.java b/src/main/java/org/apache/maven/shared/invoker/package-info.java new file mode 100644 index 0000000..8722305 --- /dev/null +++ b/src/main/java/org/apache/maven/shared/invoker/package-info.java @@ -0,0 +1,75 @@ +/* + * 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. + */ + +/** + * <p><strong>DEPRECATED:</strong> This package is deprecated and will be replaced by + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a>.</p> + * + * <p>The {@code maven-invoker} component provides an API for programmatically invoking Maven builds. + * However, it is being replaced by {@code maven-executor} which offers significant improvements:</p> + * + * <h2>Why Migrate to maven-executor?</h2> + * <ul> + * <li><strong>Unified and Simpler API:</strong> No need for updates when Maven CLI changes</li> + * <li><strong>Modern Maven Support:</strong> Works with both Maven 3.9+ and Maven 4+</li> + * <li><strong>Flexible Execution:</strong> Supports both forked and embedded execution modes</li> + * <li><strong>Better Isolation:</strong> Proper environment and system property isolation</li> + * <li><strong>Zero Dependencies:</strong> Completely standalone library</li> + * <li><strong>Actively Maintained:</strong> Used in Maven 4 Integration Tests</li> + * </ul> + * + * <h2>Migration</h2> + * <p>For detailed migration instructions, including code examples and API comparisons, see the + * <a href="https://maven.apache.org/shared/maven-invoker/migration.html";>Migration Guide</a>.</p> + * + * <h2>Quick Example</h2> + * <p>Old code (maven-invoker):</p> + * <pre>{@code + * InvocationRequest request = new DefaultInvocationRequest(); + * request.setPomFile(new File("/path/to/pom.xml")); + * request.setGoals(Collections.singletonList("install")); + * + * Invoker invoker = new DefaultInvoker(); + * InvocationResult result = invoker.execute(request); + * }</pre> + * + * <p>New code (maven-executor):</p> + * <pre>{@code + * ExecutorRequest request = ExecutorRequest.builder() + * .cwd(Paths.get("/path/to")) + * .command("mvn") + * .args(new String[]{"install"}) + * .build(); + * + * ForkedExecutor executor = new ForkedExecutor(); + * int exitCode = executor.execute(request); + * }</pre> + * + * <h2>Support</h2> + * <ul> + * <li><a href="https://github.com/apache/maven-invoker/issues/164";>Issue #164 - Deprecation Announcement</a></li> + * <li><a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor Source Code</a></li> + * <li><a href="https://maven.apache.org/mailing-lists.html";>Maven Mailing Lists</a></li> + * </ul> + * + * @deprecated Use <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> + * instead. This package will be removed in a future version. + */ +@Deprecated +package org.apache.maven.shared.invoker; diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm index b4cf515..2a4b405 100644 --- a/src/site/apt/index.apt.vm +++ b/src/site/apt/index.apt.vm @@ -28,6 +28,30 @@ ${project.name} +%{color:red}*DEPRECATION NOTICE* + + *This project is deprecated and will be replaced by {{{https://github.com/apache/maven/tree/master/impl/maven-executor}maven-executor}}.* + + Users should migrate to maven-executor, which offers: + + * Unified and simpler API that doesn't require updates when Maven CLI changes + + * Support for both Maven 3.9+ and Maven 4+ + + * Both forked and embedded execution modes + + * Proper environment isolation + + * Zero dependencies + + See {{{./migration.html}Migration Guide}} for details. + + Related: {{{https://github.com/apache/maven-invoker/issues/164}Issue #164}} + +* * * + +* Overview + In many cases, tools (including Maven itself) may want to fire off a Maven build in a clean environment. Why? Perhaps you want to avoid polluting the current system environment with side-effects produced by Maven plugins. Maybe diff --git a/src/site/apt/migration.apt.vm b/src/site/apt/migration.apt.vm new file mode 100644 index 0000000..4c01ff3 --- /dev/null +++ b/src/site/apt/migration.apt.vm @@ -0,0 +1,263 @@ + --- + Migration to maven-executor + --- + --- + 2025-12-30 + --- + + ~~ 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. + + ~~ NOTE: For help with the syntax of this file, see: + ~~ http://maven.apache.org/doxia/references/apt-format.html + +Migration from maven-invoker to maven-executor + +* Overview + + The <<<maven-invoker>>> component is deprecated and replaced by + {{{https://github.com/apache/maven/tree/master/impl/maven-executor}maven-executor}}, + which provides a modern, unified API for programmatically invoking Maven builds. + +* Why Migrate? + + <<<maven-executor>>> offers several advantages: + + * Unified API: Simple, consistent API that doesn't require updates when Maven CLI changes + + * Maven 3.9+ and Maven 4+ Support: Works seamlessly with both Maven versions + + * Multiple Execution Modes: Supports both forked and embedded execution + + * Better Environment Isolation: Proper isolation of environment variables and system properties + + * Zero Dependencies: Completely standalone, no additional dependencies required + + * Maintained: Actively used in Maven 4 Integration Tests + + [] + +* Dependency Changes + +** Old (maven-invoker) + ++---+ +<dependency> + <groupId>org.apache.maven.shared</groupId> + <artifactId>maven-invoker</artifactId> +</dependency> ++---+ + +** New (maven-executor) + ++---+ +<dependency> + <groupId>org.apache.maven</groupId> + <artifactId>maven-executor</artifactId> + <version>4.0.0-rc5</version> +</dependency> ++---+ + + <<Note:>> Since maven-executor is part of Maven 4, check the latest Maven 4 releases for + current version numbers. The component may be moved to a standalone project in the future. + +* API Comparison + +** Basic Invocation + + Old Code (maven-invoker): + ++---+ +InvocationRequest request = new DefaultInvocationRequest(); +request.setPomFile(new File("/path/to/pom.xml")); +request.setGoals(Collections.singletonList("install")); + +Invoker invoker = new DefaultInvoker(); +InvocationResult result = invoker.execute(request); + +if (result.getExitCode() != 0) { + throw new IllegalStateException("Build failed."); +} ++---+ + + New Code (maven-executor): + ++---+ +ExecutorRequest request = ExecutorRequest.builder() + .cwd(Paths.get("/path/to")) + .command("mvn") + .args(new String[]{"install"}) + .build(); + +ForkedExecutor executor = new ForkedExecutor(); +int exitCode = executor.execute(request); + +if (exitCode != 0) { + throw new IllegalStateException("Build failed."); +} ++---+ + +** Setting Goals and Options + + Old Code (maven-invoker): + ++---+ +InvocationRequest request = new DefaultInvocationRequest(); +request.setPomFile(new File("/path/to/pom.xml")); +request.setGoals(Arrays.asList("clean", "install")); +request.setBatchMode(true); +request.setOffline(true); +request.setDebug(true); ++---+ + + New Code (maven-executor): + ++---+ +ExecutorRequest request = ExecutorRequest.builder() + .cwd(Paths.get("/path/to")) + .command("mvn") + .args(new String[]{ + "clean", "install", + "--batch-mode", + "--offline", + "--debug" + }) + .build(); ++---+ + +** Embedded Execution + + maven-invoker only supports forked execution, while maven-executor supports both! + ++---+ +import org.apache.maven.cling.executor.EmbeddedExecutor; + +EmbeddedExecutor executor = new EmbeddedExecutor(); +ExecutorRequest request = ExecutorRequest.builder() + .cwd(Paths.get("/path/to/project")) + .args(new String[]{"install"}) + .build(); + +int exitCode = executor.execute(request); ++---+ + +* Complete Migration Example + + Before (maven-invoker): + ++---+ +import org.apache.maven.shared.invoker.*; +import java.io.File; +import java.util.Arrays; +import java.util.Properties; + +public class MavenBuildRunner { + private final Invoker invoker; + + public MavenBuildRunner(File localRepo) { + Invoker newInvoker = new DefaultInvoker(); + newInvoker.setLocalRepositoryDirectory(localRepo); + this.invoker = newInvoker; + } + + public void runBuild(File projectDir) throws Exception { + InvocationRequest request = new DefaultInvocationRequest(); + request.setBaseDirectory(projectDir); + request.setGoals(Arrays.asList("clean", "install")); + request.setBatchMode(true); + + Properties props = new Properties(); + props.setProperty("skipTests", "false"); + request.setProperties(props); + + InvocationResult result = invoker.execute(request); + + if (result.getExitCode() != 0) { + throw new Exception("Build failed"); + } + } +} ++---+ + + After (maven-executor): + ++---+ +import org.apache.maven.api.cli.*; +import org.apache.maven.cling.executor.*; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.List; + +public class MavenBuildRunner { + private final ForkedExecutor executor; + private final Path localRepo; + + public MavenBuildRunner(Path localRepo) { + this.executor = new ForkedExecutor(); + this.localRepo = localRepo; + } + + public void runBuild(Path projectDir) throws Exception { + List<String> args = new ArrayList<>(); + args.add("clean"); + args.add("install"); + args.add("--batch-mode"); + args.add("-Dmaven.repo.local=" + localRepo.toString()); + args.add("-DskipTests=false"); + + ExecutorRequest request = ExecutorRequest.builder() + .cwd(projectDir) + .command("mvn") + .args(args.toArray(new String[0])) + .build(); + + int exitCode = executor.execute(request); + + if (exitCode != 0) { + throw new Exception("Build failed"); + } + } +} ++---+ + +* Additional Resources + + * {{{https://github.com/apache/maven/tree/master/impl/maven-executor}maven-executor source code}} + + * {{{https://github.com/apache/maven-invoker/issues/164}Issue #164 - Deprecation announcement}} + + * {{{https://github.com/apache/maven-verifier/issues/186}Related discussion in maven-verifier}} + + * {{{https://maven.apache.org/mailing-lists.html}Maven developer mailing list}} + + * {{{./MIGRATION.md}Detailed Migration Guide (MIGRATION.md)}} + + [] + +* Need Help? + + If you encounter migration issues or have questions: + + [[1]] Check the {{{https://github.com/apache/maven/tree/master/impl/maven-executor}maven-executor source code}} for examples + + [[2]] Review {{{https://github.com/apache/maven/tree/master/its}Maven 4 IT tests}} that use maven-executor + + [[3]] Open an issue on the {{{https://github.com/apache/maven-invoker/issues}maven-invoker repository}} + + [[4]] Contact the {{{https://maven.apache.org/mailing-lists.html}Maven developer mailing list}} + + [] diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm index 5ca62ea..bc3d1a5 100644 --- a/src/site/apt/usage.apt.vm +++ b/src/site/apt/usage.apt.vm @@ -28,6 +28,14 @@ Usage +%{color:red}*DEPRECATION NOTICE* + + *This project is deprecated.* Please migrate to {{{https://github.com/apache/maven/tree/master/impl/maven-executor}maven-executor}}. + + See {{{./migration.html}Migration Guide}} for details. + +* * * + This page documents the basic usage of the Maven invocation API. * Hello, World diff --git a/src/site/site.xml b/src/site/site.xml index 2ae2acd..d9dc7e0 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -24,6 +24,7 @@ under the License. <body> <menu name="Overview"> <item name="Introduction" href="index.html"/> + <item name="⚠️ Migration Guide" href="migration.html"/> <item name="Usage" href="usage.html"/> <item name="JavaDocs" href="apidocs/index.html"/> <item name="Source Xref" href="xref/index.html"/> diff --git a/src/test/java/org/apache/maven/shared/invoker/DefaultInvokerTest.java b/src/test/java/org/apache/maven/shared/invoker/DefaultInvokerTest.java index b6ca6dd..7bafb2a 100644 --- a/src/test/java/org/apache/maven/shared/invoker/DefaultInvokerTest.java +++ b/src/test/java/org/apache/maven/shared/invoker/DefaultInvokerTest.java @@ -36,6 +36,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertTrue; +@SuppressWarnings("deprecation") class DefaultInvokerTest { private final Invoker invoker = newInvoker(); diff --git a/src/test/java/org/apache/maven/shared/invoker/MavenCommandLineBuilderTest.java b/src/test/java/org/apache/maven/shared/invoker/MavenCommandLineBuilderTest.java index 881f8de..030ad41 100644 --- a/src/test/java/org/apache/maven/shared/invoker/MavenCommandLineBuilderTest.java +++ b/src/test/java/org/apache/maven/shared/invoker/MavenCommandLineBuilderTest.java @@ -48,6 +48,7 @@ import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assumptions.assumeTrue; +@SuppressWarnings("deprecation") class MavenCommandLineBuilderTest { @TempDir private Path temporaryFolder; diff --git a/src/test/java/org/apache/maven/shared/invoker/SystemOutHandlerTest.java b/src/test/java/org/apache/maven/shared/invoker/SystemOutHandlerTest.java index b1d896e..b023254 100644 --- a/src/test/java/org/apache/maven/shared/invoker/SystemOutHandlerTest.java +++ b/src/test/java/org/apache/maven/shared/invoker/SystemOutHandlerTest.java @@ -20,6 +20,7 @@ package org.apache.maven.shared.invoker; import org.junit.jupiter.api.Test; +@SuppressWarnings("deprecation") class SystemOutHandlerTest { @Test diff --git a/src/test/java/org/apache/maven/shared/invoker/SystemOutLoggerTest.java b/src/test/java/org/apache/maven/shared/invoker/SystemOutLoggerTest.java index 0e4ae3b..e03b8d9 100644 --- a/src/test/java/org/apache/maven/shared/invoker/SystemOutLoggerTest.java +++ b/src/test/java/org/apache/maven/shared/invoker/SystemOutLoggerTest.java @@ -26,6 +26,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertTrue; +@SuppressWarnings("deprecation") class SystemOutLoggerTest { private static final Throwable EXCEPTION =
