This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/maven-invoker.git
commit c5537de9b26991ffe688a548973bd840c4997fc8 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 | 74 ++++++ src/site/markdown/index.md | 17 ++ src/site/markdown/migration.md | 231 ++++++++++++++++ src/site/markdown/usage.md | 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, 697 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 b9a80a3..23aea84 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..fc364ae --- /dev/null +++ b/src/main/java/org/apache/maven/shared/invoker/package-info.java @@ -0,0 +1,74 @@ +/* + * 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. + */ +package org.apache.maven.shared.invoker; diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 918e033..bd2b066 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -18,6 +18,23 @@ under the License. --> # Apache 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 + + See [Migration Guide](./migration.html) for details. + + Related: [Issue #164](https://github.com/apache/maven-invoker/issues/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 you want to run the build from a different working directory than the current `${user.dir}`. Maybe you want to retain the ability to surgically kill one of many Maven builds if it hangs for some reason. This API is concerned with firing a Maven build in a new JVM. It accomplishes its task by building up a conventional Maven command line from options given in the current request, along with those global options specified in the invoker itself. Once it has the command line, the invoker will execute it, and capture the resulting exit code or any exception thrown to signal a failure to execute. Input/output control can be specified using an `InputStream` and up to two `InvocationOutputHandler`s. diff --git a/src/site/markdown/migration.md b/src/site/markdown/migration.md new file mode 100644 index 0000000..4d4d9a9 --- /dev/null +++ b/src/site/markdown/migration.md @@ -0,0 +1,231 @@ +<!-- +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) + +```xml +<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. + +## API Comparison + +### Basic Invocation + +Old Code (maven-invoker): + +```java +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 +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); +``` + +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" + }) + .build(); +``` + +### Embedded Execution + +maven-invoker only supports forked execution, while maven-executor supports both. + +```java +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): + +```java +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): + +```java +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 + +- [maven-executor source code](https://github.com/apache/maven/tree/master/impl/maven-executor) +- [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) +- [Maven developer mailing list](https://maven.apache.org/mailing-lists.html) +- [Detailed Migration Guide (MIGRATION.md)](./MIGRATION.md) +## 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 +1. Review [Maven 4 IT tests](https://github.com/apache/maven/tree/master/its) that use maven-executor +1. Open an issue on the [maven-invoker repository](https://github.com/apache/maven-invoker/issues) +1. Contact the [Maven developer mailing list](https://maven.apache.org/mailing-lists.html) diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md index 173d091..96ad1c6 100644 --- a/src/site/markdown/usage.md +++ b/src/site/markdown/usage.md @@ -18,6 +18,14 @@ under the License. --> # Usage +## DEPRECATION NOTICE + +- This project is deprecated. Please migrate to [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor). + + See [Migration Guide](./migration.html) for details. + +## Overview + 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 3154d72..aa00b9a 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 e705033..7593445 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 =
