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 <[email protected]> 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 =
