You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2025/12/30 14:48:51 UTC
(maven-invoker) 01/01: Mark maven-invoker component as deprecated
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 <sl...@apache.org>
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 =