diff --git a/.asf.yaml b/.asf.yaml index 3aacd23..3c49e13 100644 --- a/.asf.yaml +++ b/.asf.yaml @@ -1,13 +1,13 @@ -# +# # 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. @@ -16,7 +16,7 @@ # # see https://s.apache.org/asfyaml github: - description: "Apache Maven Verifier" + description: "Apache Maven Verifier (deprecated)" homepage: https://maven.apache.org/shared/maven-verifier/ labels: - java diff --git a/MIGRATION.md b/MIGRATION.md index d3c72f7..c3ed555 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -19,9 +19,9 @@ ## ⚠️ Deprecation Notice -**Apache Maven Verifier is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** +**Apache Maven Verifier is deprecated. [maven-executor](https://github.com/apache/maven-executor) was released and has its own repository.** -New projects should use maven-executor. Existing projects should plan migration to maven-executor. +New projects should use maven-executor. Existing projects should plan migration to maven-executor. This project will be retired soon. See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for more details. @@ -65,14 +65,14 @@ Both have issues: **Add:** ```xml - org.apache.maven + org.apache.maven.executor maven-executor - 4.0.0-rc-5 + x.y.z test ``` -> **Note**: maven-executor location may change as it might be moved out of Maven 4 core to become a standalone project. Check the latest documentation. +> **Note**: The externalized standalone maven-executor groupId is `org.apache.maven.executor` — different from the former Maven 4 core artifact `org.apache.maven:maven-executor`. Always check https://github.com/apache/maven-executor for the latest released version and coordinates. ### 2. Code Migration Examples @@ -87,20 +87,19 @@ public class MyTest { public void testBuild() throws Exception { String baseDir = "/path/to/project"; Verifier verifier = new Verifier(baseDir); - + // Configure verifier.setAutoclean(false); verifier.setMavenDebug(true); verifier.addCliArgument("-DskipTests=true"); - + // Execute verifier.addCliArgument("package"); verifier.execute(); - + // Verify verifier.verifyErrorFreeLog(); verifier.verifyFilePresent("target/my-app-1.0.jar"); - verifier.resetStreams(); } } ``` @@ -108,55 +107,68 @@ public class MyTest { #### After (maven-executor): ```java -import org.apache.maven.api.cli.Executor; -import org.apache.maven.api.cli.ExecutorRequest; -import org.apache.maven.cling.executor.forked.ForkedExecutor; -import org.apache.maven.cling.executor.embedded.EmbeddedExecutor; +import org.apache.maven.executor.ExecutorHelper; +import org.apache.maven.executor.ExecutorRequest; +import org.apache.maven.executor.ExecutorResult; +import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; -import java.util.Arrays; public class MyTest { @Test public void testBuild() throws Exception { + Path mavenHome = Paths.get(System.getProperty("maven.home")); Path baseDir = Paths.get("/path/to/project"); - - // Choose executor type: Forked or Embedded - Executor executor = new ForkedExecutor(); - // OR: Executor executor = new EmbeddedExecutor(); - - // Build request with CLI arguments - ExecutorRequest request = ExecutorRequest.builder() - .cwd(baseDir) - .arguments(Arrays.asList("package", "-DskipTests=true", "-X")) - .build(); - - // Execute - int exitCode = executor.execute(request); - - // Verify - assertEquals(0, exitCode, "Build should succeed"); - assertTrue(Files.exists(baseDir.resolve("target/my-app-1.0.jar")), - "JAR file should exist"); + + // ExecutorHelper selects embedded or forked automatically (Mode.AUTO), + // or use Mode.FORKED / Mode.EMBEDDED explicitly. + // It implements AutoCloseable — use try-with-resources. + try (ExecutorHelper executor = ExecutorHelper.forMavenInstallation(mavenHome, ExecutorHelper.Mode.AUTO)) { + ExecutorRequest request = ExecutorRequest.mavenBuilder() + .cwd(baseDir) + .arguments("package", "-DskipTests=true", "-X") + .build(); + + ExecutorResult result = executor.execute(request); + + // Verify + assertTrue(result.success(), "Build should succeed"); + assertTrue(Files.exists(baseDir.resolve("target/my-app-1.0.jar")), + "JAR file should exist"); + } } } ``` +If you need to choose the executor type explicitly: + +```java +import org.apache.maven.executor.forked.ForkedMavenExecutor; +import org.apache.maven.executor.embedded.EmbeddedMavenExecutor; + +// Forked: spawns a separate Maven process +try (ForkedMavenExecutor executor = new ForkedMavenExecutor(mavenHome)) { ... } + +// Embedded: runs Maven inside the same JVM +try (EmbeddedMavenExecutor executor = new EmbeddedMavenExecutor(mavenHome)) { ... } +``` + ### 3. Key API Mapping | maven-verifier Concept | maven-executor Equivalent | |------------------------|---------------------------| -| `new Verifier(baseDir)` | `ExecutorRequest.builder().cwd(baseDir).build()` | -| `verifier.addCliArgument(arg)` | Add to `arguments` list in ExecutorRequest | +| `new Verifier(baseDir)` | `ExecutorRequest.mavenBuilder().cwd(baseDir).build()` | +| `verifier.addCliArgument(arg)` | `.argument(arg)` or `.arguments(arg1, arg2, ...)` on the builder | | `verifier.setMavenDebug(true)` | Add `-X` to arguments | -| `verifier.setAutoclean(false)` | Manage manually or via arguments | -| `verifier.setForkJvm(true)` | Use `ForkedExecutor` | -| `verifier.setForkJvm(false)` | Use `EmbeddedExecutor` | -| `verifier.execute()` | `executor.execute(request)` | -| `verifier.verifyErrorFreeLog()` | Check `exitCode == 0` | -| `verifier.verifyFilePresent(path)` | Use `Files.exists(Paths.get(...))` | -| `verifier.verifyTextInLog(text)` | Capture and parse executor output | +| `verifier.setAutoclean(false)` | Manage clean goal manually in the arguments list | +| `verifier.setForkJvm(true)` | `new ForkedMavenExecutor(mavenHome)` or `Mode.FORKED` | +| `verifier.setForkJvm(false)` | `new EmbeddedMavenExecutor(mavenHome)` or `Mode.EMBEDDED` | +| `verifier.execute()` | `executor.execute(request)` → returns `ExecutorResult` | +| `verifier.verifyErrorFreeLog()` | `result.success()` returns `true` when exit code is 0 | +| `result exit code` | `result.exitCode()` returns `Optional` | +| `verifier.verifyFilePresent(path)` | `Files.exists(baseDir.resolve(path))` | +| `verifier.verifyTextInLog(text)` | `result.stdOutString().orElse("").contains(text)` (requires `.grabOutputAsString(true)`) | ### 4. Environment Variables @@ -168,40 +180,44 @@ verifier.setEnvironmentVariable("MAVEN_OPTS", "-Xmx1024m"); **After:** ```java -Map env = new HashMap<>(); -env.put("JAVA_HOME", "/path/to/java"); -env.put("MAVEN_OPTS", "-Xmx1024m"); - -ExecutorRequest request = ExecutorRequest.builder() - .cwd(baseDir) - .arguments(args) - .environmentVariables(env) - .build(); +ExecutorRequest request = ExecutorRequest.mavenBuilder() + .cwd(baseDir) + .arguments("package") + .environmentVariable("JAVA_HOME", "/path/to/java") + .environmentVariable("MAVEN_OPTS", "-Xmx1024m") + .build(); ``` ### 5. Verification Helpers -maven-verifier included many helper methods like `verifyFilePresent()`, `verifyTextInLog()`, etc. These are not part of maven-executor's core responsibility. Instead: +maven-verifier included many helper methods like `verifyFilePresent()`, `verifyTextInLog()`, etc. +These are not part of maven-executor's core responsibility. -**Extract verification to separate utilities:** +**Capturing output and verifying log content:** ```java -public class MavenTestUtils { - public static void assertFileExists(Path base, String relativePath) { - Path file = base.resolve(relativePath); - assertTrue(Files.exists(file), - "Expected file does not exist: " + file); - } - - public static void assertLogContains(String log, String expectedText) { - assertTrue(log.contains(expectedText), - "Log does not contain expected text: " + expectedText); - } - - public static void assertErrorFreeLog(String log) { - assertFalse(log.contains("[ERROR]"), - "Log contains errors"); - } -} +ExecutorRequest request = ExecutorRequest.mavenBuilder() + .cwd(baseDir) + .arguments("package") + .grabOutputAsString(true) // captures stdout as a String in ExecutorResult + .build(); + +ExecutorResult result = executor.execute(request); + +// Check build success +assertTrue(result.success(), "Build should succeed"); + +// Check log content +String output = result.stdOutString().orElse(""); +assertTrue(output.contains("BUILD SUCCESS"), "Expected BUILD SUCCESS in output"); +assertFalse(output.contains("[ERROR]"), "Expected no errors in output"); +``` + +**File existence checks:** +```java +assertTrue(Files.exists(baseDir.resolve("target/my-app-1.0.jar")), + "Expected JAR was not built"); +assertFalse(Files.exists(baseDir.resolve("target/should-not-exist.txt")), + "Unexpected file was created"); ``` ### 6. Settings and Local Repository @@ -214,14 +230,14 @@ verifier.setUserSettingsFile("/path/to/settings.xml"); **After:** ```java -ExecutorRequest request = ExecutorRequest.builder() - .cwd(baseDir) - .arguments(Arrays.asList( - "package", - "-Dmaven.repo.local=/custom/repo", - "-s", "/path/to/settings.xml" - )) - .build(); +ExecutorRequest request = ExecutorRequest.mavenBuilder() + .cwd(baseDir) + .arguments( + "package", + "-Dmaven.repo.local=/custom/repo", + "-s", "/path/to/settings.xml" + ) + .build(); ``` ## Migration Checklist @@ -230,7 +246,7 @@ ExecutorRequest request = ExecutorRequest.builder() - [ ] Update POM dependencies to use maven-executor - [ ] Replace Verifier instantiation with ExecutorRequest builder pattern - [ ] Convert `addCliArgument()` calls to arguments list -- [ ] Choose between ForkedExecutor and EmbeddedExecutor +- [ ] Choose between `ForkedMavenExecutor`, `EmbeddedMavenExecutor`, or `ExecutorHelper` (with `Mode.AUTO/FORKED/EMBEDDED`) - [ ] Replace verification methods with standard Java file checks or custom utilities - [ ] Update environment variable configuration - [ ] Update local repository and settings configuration @@ -248,56 +264,77 @@ For large codebases, consider a gradual approach: ## Example Adapter Pattern -For gradual migration, you can create an adapter: +For gradual migration, you can create an adapter that wraps maven-executor with a Verifier-like interface: ```java -public class MavenExecutorAdapter { +import org.apache.maven.executor.ExecutorException; +import org.apache.maven.executor.ExecutorHelper; +import org.apache.maven.executor.ExecutorRequest; +import org.apache.maven.executor.ExecutorResult; + +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +public class MavenExecutorAdapter implements AutoCloseable { private final Path baseDir; private final List arguments = new ArrayList<>(); private final Map env = new HashMap<>(); - private Executor executor = new ForkedExecutor(); - - public MavenExecutorAdapter(String baseDir) { + private final ExecutorHelper executor; + + public MavenExecutorAdapter(Path mavenHome, String baseDir) { this.baseDir = Paths.get(baseDir); + // Mode.AUTO selects embedded when possible, falls back to forked + this.executor = ExecutorHelper.forMavenInstallation(mavenHome, ExecutorHelper.Mode.AUTO); } - + + public MavenExecutorAdapter(Path mavenHome, String baseDir, ExecutorHelper.Mode mode) { + this.baseDir = Paths.get(baseDir); + this.executor = ExecutorHelper.forMavenInstallation(mavenHome, mode); + } + public void addCliArgument(String arg) { arguments.add(arg); } - + public void setEnvironmentVariable(String key, String value) { env.put(key, value); } - - public void setForkJvm(boolean fork) { - executor = fork ? new ForkedExecutor() : new EmbeddedExecutor(); - } - - public void execute() throws Exception { - ExecutorRequest request = ExecutorRequest.builder() - .cwd(baseDir) - .arguments(arguments) - .environmentVariables(env) - .build(); - - int exitCode = executor.execute(request); - if (exitCode != 0) { - throw new Exception("Maven execution failed with exit code: " + exitCode); + + /** Executes Maven; throws ExecutorException if the build fails. */ + public ExecutorResult execute() throws ExecutorException { + ExecutorRequest request = ExecutorRequest.mavenBuilder() + .cwd(baseDir) + .arguments(arguments) + .environmentVariables(env) + .build(); + + ExecutorResult result = executor.execute(request); + if (!result.success()) { + throw new ExecutorException( + "Maven execution failed with exit code: " + result.exitCode().orElse(-1)); } + return result; + } + + @Override + public void close() throws ExecutorException { + executor.close(); } - - // Add other adapter methods as needed } ``` ## Resources -- [maven-executor source](https://github.com/apache/maven/tree/master/impl/maven-executor) -- [Maven 4 IT Verifier implementation](https://github.com/apache/maven/blob/master/its/core-it-support/maven-it-helper/src/main/java/org/apache/maven/it/Verifier.java) +- [maven-executor project](https://github.com/apache/maven-executor) +- [maven-executor releases](https://github.com/apache/maven-executor/releases) - [Issue #186 discussion](https://github.com/apache/maven-verifier/issues/186) ## Support & Questions For migration questions or issues: - Post to [Maven Dev Mailing List](https://maven.apache.org/mailing-lists.html) -- Open issues on [maven-executor GitHub](https://github.com/apache/maven/issues) +- Open issues on [maven-executor GitHub](https://github.com/apache/maven-executor/issues) diff --git a/README.md b/README.md index 4ef0241..ac1a631 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,11 @@ Contributing to [Apache Maven Verifier](https://maven.apache.org/shared/maven-ve > **️ DEPRECATION NOTICE** > -> **This project is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** +> **This project is deprecated. [maven-executor](https://github.com/apache/maven-executor) is released and moved to its own repository.** > > - **New projects**: Please use maven-executor instead > - **Existing projects**: Please plan migration to maven-executor +> - **Retirement**: This project will be retired soon > - See [MIGRATION.md](MIGRATION.md) for migration guide > - See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for discussion diff --git a/pom.xml b/pom.xml index 5691d06..43ccef2 100644 --- a/pom.xml +++ b/pom.xml @@ -31,9 +31,9 @@ 2.0.0-M2-SNAPSHOT Apache Maven Verifier Component (Deprecated) - [DEPRECATED] This component is deprecated and will be replaced by maven-executor. - New projects should use maven-executor (https://github.com/apache/maven/tree/master/impl/maven-executor). - Existing projects should plan migration. See https://github.com/apache/maven-verifier/issues/186 + [DEPRECATED] This component is deprecated. + maven-executor was released as its own repository (https://github.com/apache/maven-executor). + Existing projects should migrate soon. This project will be retired soon. See https://github.com/apache/maven-verifier/issues/186 Provides a test harness for Maven integration tests. diff --git a/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java b/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java index ee69da1..23384e5 100644 --- a/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java @@ -40,9 +40,10 @@ * Launches an embedded Maven 3.x instance from some Maven installation directory. * * @author Benjamin Bentmann - * @deprecated This class is deprecated. Use - * maven-executor's - * {@code EmbeddedExecutor} instead. + * @deprecated This class is deprecated; this project will be retired soon. Use + * maven-executor's + * ({@code org.apache.maven.executor:maven-executor}) + * {@code EmbeddedMavenExecutor} instead. * See Migration Guide. */ @Deprecated diff --git a/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java b/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java index b5afd80..8c824d7 100644 --- a/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java @@ -44,9 +44,10 @@ * Launcher implementation that forks a new JVM process to execute Maven. * * @author Benjamin Bentmann - * @deprecated This class is deprecated. Use - * maven-executor's - * {@code ForkedExecutor} instead. + * @deprecated This class is deprecated; this project will be retired soon. Use + * maven-executor's + * ({@code org.apache.maven.executor:maven-executor}) + * {@code ForkedMavenExecutor} instead. * See Migration Guide. */ @Deprecated diff --git a/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java b/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java index 82fd217..b1b2334 100644 --- a/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java @@ -26,8 +26,9 @@ * Interface for Maven launcher implementations. * * @author Benjamin Bentmann - * @deprecated This interface is deprecated. Use - * maven-executor's + * @deprecated This interface is deprecated; this project will be retired soon. Use + * maven-executor's + * ({@code org.apache.maven.executor:maven-executor}) * {@code Executor} interface instead. * See Migration Guide. */ diff --git a/src/main/java/org/apache/maven/shared/verifier/VerificationException.java b/src/main/java/org/apache/maven/shared/verifier/VerificationException.java index 587d788..0a34e8c 100644 --- a/src/main/java/org/apache/maven/shared/verifier/VerificationException.java +++ b/src/main/java/org/apache/maven/shared/verifier/VerificationException.java @@ -22,9 +22,9 @@ * Exception thrown when Maven verification fails. * * @author Jason van Zyl - * @deprecated This exception is deprecated along with the Verifier class. - * When migrating to maven-executor, use standard Java exceptions - * and check executor exit codes directly. + * @deprecated This exception is deprecated along with the Verifier class; this project will be retired soon. + * When migrating to maven-executor ({@code org.apache.maven.executor:maven-executor}), handle + * {@code ExecutorException} and check {@code ExecutorResult.success()} directly. * See Migration Guide. */ @Deprecated diff --git a/src/main/java/org/apache/maven/shared/verifier/Verifier.java b/src/main/java/org/apache/maven/shared/verifier/Verifier.java index a7ac3a0..87551d6 100644 --- a/src/main/java/org/apache/maven/shared/verifier/Verifier.java +++ b/src/main/java/org/apache/maven/shared/verifier/Verifier.java @@ -81,9 +81,10 @@ /** * Maven test harness for integration tests. * - *

DEPRECATION NOTICE: This class is deprecated and will be removed in a future version. + *

DEPRECATION NOTICE: This class is deprecated and this project will be retired soon. * Please migrate to - * maven-executor + * maven-executor + * ({@code org.apache.maven.executor:maven-executor}), * which provides a unified, modern API for programmatic Maven execution with support for both * Maven 3.9+ and Maven 4+.

* @@ -104,21 +105,25 @@ * verifier.execute(); * verifier.verifyErrorFreeLog(); * - * // New (maven-executor): - * Executor executor = new ForkedExecutor(); - * ExecutorRequest request = ExecutorRequest.builder() - * .cwd(Paths.get("/path/to/project")) - * .arguments(List.of("package")) - * .build(); - * int exitCode = executor.execute(request); - * assertEquals(0, exitCode); + * // New (maven-executor) — groupId: org.apache.maven.executor, artifactId: maven-executor: + * Path mavenHome = Paths.get(System.getProperty("maven.home")); + * try (ExecutorHelper executor = ExecutorHelper.forMavenInstallation(mavenHome, ExecutorHelper.Mode.AUTO)) { + * ExecutorRequest request = ExecutorRequest.mavenBuilder() + * .cwd(Paths.get("/path/to/project")) + * .arguments("package") + * .build(); + * ExecutorResult result = executor.execute(request); + * assertTrue(result.success()); + * } * } * * @see Migration Guide - * @see maven-executor + * @see maven-executor * @author Jason van Zyl * @author Brett Porter - * @deprecated Use maven-executor instead. + * @deprecated This project is deprecated and will be retired soon. + * Use maven-executor + * ({@code org.apache.maven.executor:maven-executor}) instead. * See Migration Guide. */ @Deprecated diff --git a/src/site/markdown/getting-started.md b/src/site/markdown/getting-started.md index 9c45f68..f5de43c 100644 --- a/src/site/markdown/getting-started.md +++ b/src/site/markdown/getting-started.md @@ -21,10 +21,11 @@ > **⚠️ DEPRECATION NOTICE** > -> **This project is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** +> **This project is deprecated. [maven-executor](https://github.com/apache/maven-executor) is released and externalized as its own repository.** > > - **New projects**: Please use maven-executor instead > - **Existing projects**: Please plan migration to maven-executor +> - **Retirement**: This project will be retired soon > - See [Migration Guide](https://github.com/apache/maven-verifier/blob/master/MIGRATION.md) > - See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for discussion diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 1c512cf..6781b08 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -21,10 +21,11 @@