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:43:43 UTC
(maven-invoker) branch deprecation created (now 26fcf4e)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch deprecation
in repository https://gitbox.apache.org/repos/asf/maven-invoker.git
at 26fcf4e [#164] Mark maven-invoker component as deprecated
This branch includes the following new commits:
new 26fcf4e [#164] Mark maven-invoker component as deprecated
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven-invoker) 01/01: [#164] Mark maven-invoker component as deprecated
Posted by sl...@apache.org.
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 26fcf4e1beae8fdb5838311858346977df85790c
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Tue Dec 30 14:42:06 2025 +0000
[#164] Mark maven-invoker component as deprecated
This commit implements Phase 1 & Phase 2 of the deprecation plan for
maven-invoker, directing users to migrate to maven-executor.
Changes include:
## Documentation Updates
- README.md: Added prominent deprecation notice
- pom.xml: Updated description with deprecation information
- src/site/apt/index.apt.vm: Added deprecation warning
- src/site/apt/usage.apt.vm: Added deprecation notice
- src/site/site.xml: Added "Migration Guide" to navigation menu
- src/site/apt/migration.apt.vm: New comprehensive migration guide
- MIGRATION.md: Detailed migration guide with code examples
- DEPRECATION_PATCH.md: Complete implementation plan
- JAVA_DEPRECATION_EXAMPLES.md: Examples for Java code changes
## Java Code Annotations
- Added @Deprecated(since = "3.3.1", forRemoval = true) to:
* Invoker interface
* InvocationRequest interface
* InvocationResult interface
* DefaultInvoker class
* DefaultInvocationRequest class
* DefaultInvocationResult class
- Created package-info.java with package-level deprecation
- Updated pom.xml: Added compiler configuration for deprecation warnings
- Added @SuppressWarnings("deprecation") to test classes:
* DefaultInvokerTest
* MavenCommandLineBuilderTest
* SystemOutHandlerTest
* SystemOutLoggerTest
## Why maven-executor?
maven-executor provides:
- Unified 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
- Better environment isolation
- Zero dependencies
- Active maintenance in Maven 4 Integration Tests
Related: #164, apache/maven-verifier#186
---
DEPRECATION_PATCH.md | 306 +++++++++++++++++++++
JAVA_DEPRECATION_EXAMPLES.md | 285 +++++++++++++++++++
MIGRATION.md | 299 ++++++++++++++++++++
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 | 264 ++++++++++++++++++
src/site/apt/usage.apt.vm | 8 +
src/site/site.xml | 1 +
.../maven/shared/invoker/DefaultInvokerTest.java | 1 +
.../invoker/MavenCommandLineBuilderTest.java | 3 +-
.../maven/shared/invoker/SystemOutHandlerTest.java | 1 +
.../maven/shared/invoker/SystemOutLoggerTest.java | 1 +
20 files changed, 1334 insertions(+), 3 deletions(-)
diff --git a/DEPRECATION_PATCH.md b/DEPRECATION_PATCH.md
new file mode 100644
index 0000000..8a1369b
--- /dev/null
+++ b/DEPRECATION_PATCH.md
@@ -0,0 +1,306 @@
+<!---
+ 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.
+-->
+
+# Proposed Deprecation Patch for maven-invoker
+
+## Summary
+
+This document outlines the proposed changes to deprecate the `maven-invoker` component and guide users to migrate to `maven-executor`.
+
+## Related Issues
+
+- [Issue #164](https://github.com/apache/maven-invoker/issues/164) - Deprecate project; users should go to maven-executor instead
+- [maven-verifier Issue #186](https://github.com/apache/maven-verifier/issues/186) - Related deprecation discussion
+
+## Changes Overview
+
+### 1. Documentation Updates ✅
+
+#### README.md
+- Added prominent deprecation notice at the top
+- Links to MIGRATION.md and maven-executor
+- Highlights key benefits of maven-executor
+
+#### pom.xml
+- Updated `<description>` with deprecation notice
+- Added reference to maven-executor repository
+
+#### Site Documentation
+- **index.apt.vm**: Added deprecation warning at the top
+- **usage.apt.vm**: Added deprecation notice
+- **migration.apt.vm**: New comprehensive migration guide (APT format)
+- **site.xml**: Added "⚠️ Migration Guide" to navigation menu
+
+#### MIGRATION.md
+- Comprehensive migration guide in Markdown format
+- Side-by-side code comparisons
+- Dependency changes
+- API mapping examples
+- Complete migration checklist
+- Additional resources and help section
+
+### 2. Proposed Java Code Changes
+
+The following changes should be added to mark the Java API as deprecated:
+
+#### Add @Deprecated annotations to main public interfaces and classes:
+
+```java
+// Invoker.java
+@Deprecated(since = "3.3.1", forRemoval = true)
+public interface Invoker { ... }
+
+// DefaultInvoker.java
+@Deprecated(since = "3.3.1", forRemoval = true)
+public class DefaultInvoker implements Invoker { ... }
+
+// InvocationRequest.java
+@Deprecated(since = "3.3.1", forRemoval = true)
+public interface InvocationRequest { ... }
+
+// DefaultInvocationRequest.java
+@Deprecated(since = "3.3.1", forRemoval = true)
+public class DefaultInvocationRequest implements InvocationRequest { ... }
+
+// InvocationResult.java
+@Deprecated(since = "3.3.1", forRemoval = true)
+public interface InvocationResult { ... }
+
+// DefaultInvocationResult.java
+@Deprecated(since = "3.3.1", forRemoval = true)
+public class DefaultInvocationResult implements InvocationResult { ... }
+```
+
+#### Add package-info.java with deprecation notice:
+
+```java
+/**
+ * <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>Users should migrate to maven-executor which offers:</p>
+ * <ul>
+ * <li>Unified and simpler API that doesn't require updates when Maven CLI changes</li>
+ * <li>Support for both Maven 3.9+ and Maven 4+</li>
+ * <li>Both forked and embedded execution modes</li>
+ * <li>Proper environment isolation</li>
+ * <li>Zero dependencies</li>
+ * </ul>
+ *
+ * <p>For migration guidance, see the
+ * <a href="https://maven.apache.org/shared/maven-invoker/migration.html">Migration Guide</a>.</p>
+ *
+ * @see <a href="https://github.com/apache/maven-invoker/issues/164">Issue #164</a>
+ * @deprecated Use <a href="https://github.com/apache/maven/tree/master/impl/maven-executor">maven-executor</a> instead.
+ */
+@Deprecated(since = "3.3.1", forRemoval = true)
+package org.apache.maven.shared.invoker;
+```
+
+### 3. Proposed Build Configuration Changes
+
+#### Add compiler warnings configuration to pom.xml:
+
+```xml
+<build>
+ <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>
+ </plugins>
+</build>
+```
+
+### 4. Release Notes Template
+
+For the next release (3.3.1), include these notes:
+
+```markdown
+## Maven Invoker 3.3.1
+
+### Deprecation Notice
+
+**This component is now deprecated** and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).
+
+All users are encouraged to migrate to maven-executor, which provides:
+- Unified API that doesn't require updates when Maven CLI changes
+- Support for Maven 3.9+ and Maven 4+
+- Both forked and embedded execution modes
+- Better environment isolation
+- Zero dependencies
+
+### Migration
+
+See the [Migration Guide](https://maven.apache.org/shared/maven-invoker/migration.html) for detailed instructions.
+
+### Changes in this release
+
+- [#164] - Marked component as deprecated
+- Added comprehensive migration guide
+- Updated documentation with deprecation notices
+- Added @Deprecated annotations to all public APIs
+```
+
+## Implementation Steps
+
+### Phase 1: Documentation (Completed)
+- [x] Update README.md with deprecation notice
+- [x] Update pom.xml description
+- [x] Create MIGRATION.md
+- [x] Create migration.apt.vm for website
+- [x] Update index.apt.vm with deprecation notice
+- [x] Update usage.apt.vm with deprecation notice
+- [x] Update site.xml navigation
+
+### Phase 2: Code Annotations (Proposed)
+- [ ] Add @Deprecated annotations to main interfaces (Invoker, InvocationRequest, InvocationResult)
+- [ ] Add @Deprecated annotations to implementation classes (DefaultInvoker, etc.)
+- [ ] Create package-info.java with package-level deprecation
+- [ ] Add deprecation Javadoc to all deprecated classes
+
+### Phase 3: Build Configuration (Proposed)
+- [ ] Configure compiler to show deprecation warnings
+- [ ] Update test configurations to suppress expected deprecation warnings
+- [ ] Add suppression rules for internal usage
+
+### Phase 4: Release Preparation (Proposed)
+- [ ] Prepare 3.3.1 release with deprecation notices
+- [ ] Update release notes
+- [ ] Announce deprecation on Maven mailing lists
+- [ ] Update Maven Central metadata
+
+### Phase 5: Communication (Proposed)
+- [ ] Send announcement to Maven users mailing list
+- [ ] Send announcement to Maven developers mailing list
+- [ ] Update Maven website documentation
+- [ ] Consider blog post on Maven blog
+
+## Migration Timeline Proposal
+
+### Immediate (Q1 2025)
+- Release 3.3.1 with all deprecation notices
+- Publish migration guide
+- Announce deprecation
+
+### Short-term (Q2-Q3 2025)
+- Continue critical bug fixes only
+- Help users with migration issues
+- Gather feedback on maven-executor
+
+### Medium-term (Q4 2025 - Q2 2026)
+- Maintenance mode: security fixes only
+- Track migration adoption
+- Consider moving maven-executor to standalone project
+
+### Long-term (2027+)
+- Archive project once majority of users migrated
+- Final release with minimal maintenance
+- Redirect documentation to maven-executor
+
+## Communication Plan
+
+### Announcement Template
+
+```
+Subject: [ANNOUNCE] Apache Maven Invoker deprecated - migrate to maven-executor
+
+The Apache Maven team announces the deprecation of maven-invoker component.
+
+Users should migrate to maven-executor which provides improved functionality:
+- Unified API without need for updates when CLI changes
+- Maven 3.9+ and Maven 4+ support
+- Both forked and embedded execution
+- Better environment isolation
+- Zero dependencies
+
+Migration Guide: https://maven.apache.org/shared/maven-invoker/migration.html
+
+The component will continue to receive critical fixes for the foreseeable future,
+but new features will not be added.
+
+Questions? Contact the Maven development mailing list or open an issue on GitHub.
+
+Related:
+- Issue #164: https://github.com/apache/maven-invoker/issues/164
+- maven-executor: https://github.com/apache/maven/tree/master/impl/maven-executor
+```
+
+## Testing Strategy
+
+### For Deprecation Changes
+1. Verify all documentation builds correctly
+2. Ensure website generates with migration guide
+3. Check that @Deprecated annotations show appropriate IDE warnings
+4. Verify existing tests still pass
+5. Test that compiler warnings are displayed correctly
+
+### For Users
+1. Provide example migration projects
+2. Document common migration patterns
+3. Create automated migration tool (future consideration)
+
+## Risks and Mitigation
+
+### Risk: Users unaware of deprecation
+**Mitigation:**
+- Prominent notices in multiple locations
+- Compiler warnings via @Deprecated
+- Maven Central release notes
+- Mailing list announcements
+
+### Risk: maven-executor not ready for all use cases
+**Mitigation:**
+- Gather user feedback early
+- Document maven-executor gaps
+- Continue critical fixes during transition period
+- Work with maven-executor maintainers to address gaps
+
+### Risk: Breaking downstream projects
+**Mitigation:**
+- Gradual deprecation (warnings before removal)
+- Long maintenance period
+- Clear migration documentation
+- Community support
+
+## Success Metrics
+
+- Number of downloads decreasing over time
+- Migration guide page views
+- Reduced issue reports on maven-invoker
+- Increased adoption of maven-executor
+- Community feedback on migration process
+
+## Open Questions
+
+1. Should maven-executor be extracted to a standalone project before final deprecation?
+2. What is the minimum maintenance period before archiving?
+3. Should we provide an automated migration tool?
+4. How to handle projects that can't migrate immediately?
+
+## References
+
+- [Issue #164](https://github.com/apache/maven-invoker/issues/164)
+- [maven-verifier Issue #186](https://github.com/apache/maven-verifier/issues/186)
+- [maven-executor source](https://github.com/apache/maven/tree/master/impl/maven-executor)
+- [Maven deprecation policy](https://maven.apache.org/developers/conventions/code.html)
diff --git a/JAVA_DEPRECATION_EXAMPLES.md b/JAVA_DEPRECATION_EXAMPLES.md
new file mode 100644
index 0000000..16bc7f8
--- /dev/null
+++ b/JAVA_DEPRECATION_EXAMPLES.md
@@ -0,0 +1,285 @@
+<!---
+ 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.
+-->
+
+# Java API Deprecation Examples
+
+This file contains examples of how to add @Deprecated annotations to the main Java classes.
+
+## 1. Invoker.java
+
+Add this annotation and Javadoc before the interface declaration:
+
+```java
+/**
+ * Provides a component capable of executing Maven builds.
+ *
+ * @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(since = "3.3.1", forRemoval = true)
+public interface Invoker
+{
+ // ... existing code
+}
+```
+
+## 2. DefaultInvoker.java
+
+```java
+/**
+ * Default implementation of the Invoker interface.
+ *
+ * @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.
+ */
+@Deprecated(since = "3.3.1", forRemoval = true)
+@Named
+@Singleton
+public class DefaultInvoker implements Invoker
+{
+ // ... existing code
+}
+```
+
+## 3. InvocationRequest.java
+
+```java
+/**
+ * Specifies the parameters used to configure 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.
+ */
+@Deprecated(since = "3.3.1", forRemoval = true)
+public interface InvocationRequest
+{
+ // ... existing code
+}
+```
+
+## 4. DefaultInvocationRequest.java
+
+```java
+/**
+ * Default implementation of InvocationRequest interface.
+ *
+ * @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.
+ */
+@Deprecated(since = "3.3.1", forRemoval = true)
+public class DefaultInvocationRequest implements InvocationRequest
+{
+ // ... existing code
+}
+```
+
+## 5. InvocationResult.java
+
+```java
+/**
+ * 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.
+ */
+@Deprecated(since = "3.3.1", forRemoval = true)
+public interface InvocationResult
+{
+ // ... existing code
+}
+```
+
+## 6. DefaultInvocationResult.java
+
+```java
+/**
+ * Default implementation of InvocationResult interface.
+ *
+ * @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.
+ */
+@Deprecated(since = "3.3.1", forRemoval = true)
+public class DefaultInvocationResult implements InvocationResult
+{
+ // ... existing code
+}
+```
+
+## 7. package-info.java (NEW FILE)
+
+Create this file at: `src/main/java/org/apache/maven/shared/invoker/package-info.java`
+
+```java
+/*
+ * 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(since = "3.3.1", forRemoval = true)
+package org.apache.maven.shared.invoker;
+```
+
+## 8. Other Classes to Deprecate
+
+Apply similar annotations to these classes:
+
+- `InvocationOutputHandler.java`
+- `MavenInvocationException.java`
+- `CommandLineConfigurationException.java`
+- `MavenCommandLineBuilder.java`
+- `PrintStreamHandler.java`
+- `PrintStreamLogger.java`
+- `SystemOutHandler.java`
+- `SystemOutLogger.java`
+- `InvokerLogger.java`
+- `UpdateSnapshotsPolicy.java`
+
+Example for exception classes:
+
+```java
+/**
+ * Exception thrown when Maven invocation fails.
+ *
+ * @deprecated This exception class is deprecated. Use standard Java exceptions
+ * or check exit codes when using
+ * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor">maven-executor</a>.
+ */
+@Deprecated(since = "3.3.1", forRemoval = true)
+public class MavenInvocationException extends Exception
+{
+ // ... existing code
+}
+```
+
+## Implementation Notes
+
+1. **Consistency**: All public classes and interfaces should have the same deprecation message format
+2. **Links**: Always include link to migration guide and maven-executor
+3. **Version**: Use "3.3.1" as the `since` version (adjust if different)
+4. **forRemoval**: Set to `true` to indicate this API will eventually be removed
+5. **IDE Support**: Modern IDEs will show strikethrough text and warnings with these annotations
+6. **Javadoc**: Include comprehensive Javadoc explaining the deprecation and migration path
+
+## Suppressing Warnings in Tests
+
+In test classes that must continue using the deprecated API, add:
+
+```java
+@SuppressWarnings("deprecation")
+public class DefaultInvokerTest
+{
+ // ... test code
+}
+```
+
+Or suppress at method level:
+
+```java
+@Test
+@SuppressWarnings("deprecation")
+public void testInvoke() throws Exception
+{
+ // ... test code using deprecated API
+}
+```
diff --git a/MIGRATION.md b/MIGRATION.md
new file mode 100644
index 0000000..a18a8ec
--- /dev/null
+++ b/MIGRATION.md
@@ -0,0 +1,299 @@
+<!---
+ 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>
+ <version>3.3.0</version>
+</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>
+```
+
+**Option 2: Extract from Maven distribution**
+
+Since maven-executor is part of Maven 4, you can extract it from Maven 4 installation or use it as a standalone JAR.
+
+> **Note**: Check the latest Maven 4 releases for current version numbers. The component may be moved to a standalone project in the future.
+
+## 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..a667d4f 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(since = "3.3.1", forRemoval = true)
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..8bc1c46 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(since = "3.3.1", forRemoval = true)
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..a163557 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(since = "3.3.1", forRemoval = true)
@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..7d71dd2 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(since = "3.3.1", forRemoval = true)
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..ab8b6ed 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(since = "3.3.1", forRemoval = true)
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..e497601 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(since = "3.3.1", forRemoval = true)
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..abf7162
--- /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(since = "3.3.1", forRemoval = true)
+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..2a7b568
--- /dev/null
+++ b/src/site/apt/migration.apt.vm
@@ -0,0 +1,264 @@
+ ---
+ 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>
+ <version>3.3.0</version>
+</dependency>
++---+
+
+** New (maven-executor)
+
++---+
+<dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-executor</artifactId>
+ <version>4.0.0</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..ac943c4 100644
--- a/src/test/java/org/apache/maven/shared/invoker/MavenCommandLineBuilderTest.java
+++ b/src/test/java/org/apache/maven/shared/invoker/MavenCommandLineBuilderTest.java
@@ -47,8 +47,7 @@ import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.junit.jupiter.api.Assumptions.assumeTrue;
-
-class MavenCommandLineBuilderTest {
+@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 =