This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-invoker.git
The following commit(s) were added to refs/heads/master by this push:
new d1ab45e Migrate site to Doxia 2 and Markdown
d1ab45e is described below
commit d1ab45efd37360f059afe08f857c6d6a40075c22
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Dec 30 16:26:32 2025 +0100
Migrate site to Doxia 2 and Markdown
---
src/site/apt/index.apt.vm | 110 --------------
src/site/apt/usage.apt.vm | 158 ---------------------
src/site/markdown/index.md | 54 +++++++
src/site/markdown/usage.md | 124 ++++++++++++++++
src/site/site.xml | 8 +-
.../maven/shared/invoker/DefaultInvokerTest.java | 2 +-
.../java/org/apache/maven/shared/invoker/App.java | 8 +-
.../java/org/apache/maven/shared/invoker/App.java | 7 +-
.../java/org/apache/maven/shared/invoker/App.java | 7 +-
.../org/apache/maven/shared/invoker/AppTest.java | 15 +-
10 files changed, 197 insertions(+), 296 deletions(-)
diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm
deleted file mode 100644
index b4cf515..0000000
--- a/src/site/apt/index.apt.vm
+++ /dev/null
@@ -1,110 +0,0 @@
- ---
- Introduction
- ---
- John Casey
- ---
- 2013-07-24
- ---
-
- ~~ 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
-
-${project.name}
-
- In many cases, tools (including Maven itself) may want to fire off a Maven
- build in a clean environment. Why? Perhaps you want to avoid polluting the
- current system environment with side-effects produced by Maven plugins. Maybe
- you want to run the build from a different working directory than the current
- <<<$\{user.dir\}>>>. Maybe you want to retain the ability to surgically kill
one
- of many Maven builds if it hangs for some reason.
-
- This API is concerned with firing a Maven build in a new JVM. It accomplishes
- its task by building up a conventional Maven command line from options given
- in the current request, along with those global options specified in the
- invoker itself. Once it has the command line, the invoker will execute it,
and
- capture the resulting exit code or any exception thrown to signal a failure
to
- execute. Input/output control can be specified using an <<<InputStream>>> and
- up to two <<<InvocationOutputHandler>>>s.
-
-* Features
-
- * Tracking of exit code and exception resulting from an invocation
-
- * Global Options:
-
- * Maven-Home Location (location of Maven application directory)
-
- * Local Repository Location
-
- * API Logger
-
- * Maven Executable
-
- []
-
- * Request Options:
-
- * Global Checksum Policy (fail/warn, global across defined repositories)
-
- * Local Repository Location
-
- * Project Base Directory
-
- * POM File
-
- * POM File-Name (used in conjunction with Base Directory)
-
- * Interactive/Batch Mode (determines whether Maven prompts for input)
-
- * Offline Mode
-
- * Update-Snapshots Flag
-
- * Debug Flag (show debug-level output)
-
- * Quiet Flag (only show errors)
-
- * Show-Errors Flag (show exception stacktraces, but not full debug output)
-
- * No-Transfer-Progress Flag (Do not display transfer progress when
downloading or uploading)
-
- * Inherit-Shell-Environment Flag (inherit envars from the shell used to
- start the current JVM)
-
- * Reactor-Failure Behavior (fail-at-end, fail-never, etc.)
-
- * Input/Output Handlers
-
- * Build Properties (-D switches)
-
- * Build Goals
-
- * Settings Location (<<<settings.xml>>> file path)
-
- * Threadcount ( since Maven3 with -T )
-
- * Toolchains location ( since Maven3 with -t )
-
- * Additional raw cli options at the start or the end of command line
-
- []
-
- []
-
diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm
deleted file mode 100644
index 5ca62ea..0000000
--- a/src/site/apt/usage.apt.vm
+++ /dev/null
@@ -1,158 +0,0 @@
- ---
- Usage
- ---
- John Casey
- ---
- 2008-08-02
- ---
-
- ~~ 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
-
-Usage
-
- This page documents the basic usage of the Maven invocation API.
-
-* Hello, World
-
- The simplest possible way to use the invocation API is to construct the
- invoker and request at the same time, and simply call
- <<<invoker.execute(request)>>>. In this example, we don't care about the
build
- result:
-
-+---+
-InvocationRequest request = new DefaultInvocationRequest();
-request.setPomFile( new File( "/path/to/pom.xml" ) );
-request.setGoals( Collections.singletonList( "install" ) );
-
-Invoker invoker = new DefaultInvoker();
-invoker.execute( request );
-+---+
-
- This code will execute a new Maven build to the <<<install>>> lifecycle phase
- for the project defined at <<</path/to/pom.xml>>>. If the build fails, we
will
- remain blissfully ignorant...
-
-* Checking the Exit Code
-
- If we wanted to detect a build failure in the above example, we could simply
- add the following lines:
-
-+---+
-InvocationResult result = invoker.execute( request );
-
-if ( result.getExitCode() != 0 )
-{
- throw new IllegalStateException( "Build failed." );
-}
-+---+
-
- This will retrieve the exit code from the invocation result, and throw
- an exception if it's not <<<0>>> (the traditional all-clear code). Note that
- we could capture the build output by adding an <<<InvocationOutputHandler>>>
- instance to the <<<request>>>.
-
-* Caching the Invoker
-
- Since you can specify global options for Maven invocations via the
- <<<Invoker>>> configuration, it will often make sense to configure a single
- <<<Invoker>>> instance, and reuse it over multiple method calls:
-
-+---+
-// we will always call the same goals...
-private static final List<String> PUBLISH_GOALS = Arrays.asList( "clean",
"site-deploy" );
-
-// define a field for the Invoker instance.
-private final Invoker invoker;
-
-// now, instantiate the invoker in the class constructor...
-public SomeClass( File localRepositoryDir )
-{
- Invoker newInvoker = new DefaultInvoker();
- newInvoker.setLocalRepositoryDirectory( localRepositoryDir );
-
- this.invoker = newInvoker;
-}
-
-// this method will be called repeatedly, and fire off new builds...
-public void publishSite( File siteDirectory ) throws PublishException
-{
- InvocationRequest request = new DefaultInvocationRequest();
- request.setBaseDirectory( siteDirectory );
- request.setInteractive( false );
- request.setGoals( PUBLISH_GOALS );
-
- InvocationResult result = invoker.execute( request );
-
- if ( result.getExitCode() != 0 )
- {
- if ( result.getExecutionException() != null )
- {
- throw new PublishException( "Failed to publish site.",
- result.getExecutionException() );
- }
- else
- {
- throw new PublishException( "Failed to publish site. Exit code: "
+
- result.getExitCode() );
- }
- }
-}
-+---+
-
- As you can see, we're using the same local repository location (since the
- site-generation artifacts will most likely be common to most sites), the same
- invoker instance (it's configured, we may as well reuse it), and the same set
- of goals per build. We can actually accommodate a fairly complex
configuration
- of the Invoker without adding complexity to the <<<publishSite>>> method in
this manner.
-
-* Configuring the Maven Home Directory
-
- You can use the method <<<Invoker.setMavenHome()>>> to specify which Maven
executable it should use.
- If you don't provide an explicit value for this setting, the <<<Invoker>>>
will automatically try to detect
- a Maven installation by evaluating the system property <<<maven.home>>>.
-
- <<Note:>> If you use the invocation API in tests run by the
{{{../../plugins/maven-surefire-plugin}Maven Surefire Plugin}},
- you need to tell Surefire to pass the system property <<<maven.home>>> to
the tests in order for the automatic Maven
- detection to work:
-
-+---+
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>$context.get("version.maven-surefire")</version> <!-- see
surefire-page for available versions -->
- <configuration>
- <systemPropertyVariables>
- <maven.home>${maven.home}</maven.home>
- </systemPropertyVariables>
- </configuration>
- </plugin>
- </plugins>
- ...
- </build>
- ...
-</project>
-+---+
-
-
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 0000000..918e033
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -0,0 +1,54 @@
+<!--
+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.
+-->
+# Apache Maven Invoker
+
+In many cases, tools (including Maven itself) may want to fire off a Maven
build in a clean environment. Why? Perhaps you want to avoid polluting the
current system environment with side-effects produced by Maven plugins. Maybe
you want to run the build from a different working directory than the current
`${user.dir}`. Maybe you want to retain the ability to surgically kill one of
many Maven builds if it hangs for some reason.
+
+This API is concerned with firing a Maven build in a new JVM. It accomplishes
its task by building up a conventional Maven command line from options given in
the current request, along with those global options specified in the invoker
itself. Once it has the command line, the invoker will execute it, and capture
the resulting exit code or any exception thrown to signal a failure to execute.
Input/output control can be specified using an `InputStream` and up to two
`InvocationOutputHandler`s.
+
+## Features
+
+- Tracking of exit code and exception resulting from an invocation
+- Global Options:
+ - Maven-Home Location (location of Maven application directory)
+ - Local Repository Location
+ - API Logger
+ - Maven Executable
+- Request Options:
+ - Global Checksum Policy (fail/warn, global across defined repositories)
+ - Local Repository Location
+ - Project Base Directory
+ - POM File
+ - POM File-Name (used in conjunction with Base Directory)
+ - Interactive/Batch Mode (determines whether Maven prompts for input)
+ - Offline Mode
+ - Update-Snapshots Flag
+ - Debug Flag (show debug-level output)
+ - Quiet Flag (only show errors)
+ - Show-Errors Flag (show exception stacktraces, but not full debug output)
+ - No-Transfer-Progress Flag (Do not display transfer progress when
downloading or uploading)
+ - Inherit-Shell-Environment Flag (inherit envars from the shell used to
start the current JVM)
+ - Reactor-Failure Behavior (fail-at-end, fail-never, etc.)
+ - Input/Output Handlers
+ - Build Properties (-D switches)
+ - Build Goals
+ - Settings Location (`settings.xml` file path)
+ - Threadcount (since Maven3 with -T)
+ - Toolchains location (since Maven3 with -t)
+ - Additional raw cli options at the start or the end of command line
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
new file mode 100644
index 0000000..173d091
--- /dev/null
+++ b/src/site/markdown/usage.md
@@ -0,0 +1,124 @@
+<!--
+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.
+-->
+# Usage
+
+This page documents the basic usage of the Maven invocation API.
+
+## Hello, World
+
+The simplest possible way to use the invocation API is to construct the
invoker and request at the same time, and simply call
`invoker.execute(request)`. In this example, we don't care about the build
result:
+
+```java
+InvocationRequest request = new DefaultInvocationRequest();
+request.setPomFile(new File("/path/to/pom.xml"));
+request.setGoals(Collections.singletonList("install"));
+
+Invoker invoker = new DefaultInvoker();
+invoker.execute(request);
+```
+
+This code will execute a new Maven build to the `install` lifecycle phase for
the project defined at `/path/to/pom.xml`. If the build fails, we will remain
blissfully ignorant...
+
+## Checking the Exit Code
+
+If we wanted to detect a build failure in the above example, we could simply
add the following lines:
+
+```java
+InvocationResult result = invoker.execute(request);
+
+if (result.getExitCode()!= 0){
+ throw new IllegalStateException("Build failed.");
+}
+```
+
+This will retrieve the exit code from the invocation result, and throw an
exception if it's not `0` (the traditional all-clear code). Note that we
could capture the build output by adding an `InvocationOutputHandler` instance
to the `request`.
+
+## Caching the Invoker
+
+Since you can specify global options for Maven invocations via the `Invoker`
configuration, it will often make sense to configure a single `Invoker`
instance, and reuse it over multiple method calls:
+
+```java
+// we will always call the same goals...
+private static final List<String> PUBLISH_GOALS = Arrays.asList("clean",
"site-deploy");
+
+// define a field for the Invoker instance.
+private final Invoker invoker;
+
+// now, instantiate the invoker in the class constructor...
+public SomeClass(File localRepositoryDir) {
+ Invoker newInvoker = new DefaultInvoker();
+ newInvoker.setLocalRepositoryDirectory(localRepositoryDir);
+
+ this.invoker = newInvoker;
+}
+
+// this method will be called repeatedly, and fire off new builds...
+public void publishSite(File siteDirectory) throws PublishException {
+ InvocationRequest request = new DefaultInvocationRequest();
+ request.setBaseDirectory(siteDirectory);
+ request.setInteractive(false);
+ request.setGoals(PUBLISH_GOALS);
+
+ InvocationResult result = invoker.execute(request);
+
+ if (result.getExitCode() != 0)
+ {
+ if (result.getExecutionException() != null)
+ {
+ throw new PublishException("Failed to publish site.",
+ result.getExecutionException());
+ }
+ else
+ {
+ throw new PublishException("Failed to publish site. Exit code: " +
+ result.getExitCode());
+ }
+ }
+}
+```
+
+As you can see, we're using the same local repository location (since the
site-generation artifacts will most likely be common to most sites), the same
invoker instance (it's configured, we may as well reuse it), and the same
set of goals per build. We can actually accommodate a fairly complex
configuration of the Invoker without adding complexity to the `publishSite`
method in this manner.
+
+## Configuring the Maven Home Directory
+
+You can use the method `Invoker.setMavenHome()` to specify which Maven
executable it should use. If you don't provide an explicit value for this
setting, the `Invoker` will automatically try to detect a Maven installation by
evaluating the system property `maven.home`.
+
+**Note:** If you use the invocation API in tests run by the [Maven Surefire
Plugin](../../plugins/maven-surefire-plugin), you need to tell Surefire to pass
the system property `maven.home` to the tests in order for the automatic Maven
detection to work:
+
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>3.5.3</version> <!-- see surefire-page for available versions
-->
+ <configuration>
+ <systemPropertyVariables>
+ <maven.home>${maven.home}</maven.home>
+ </systemPropertyVariables>
+ </configuration>
+ </plugin>
+ </plugins>
+ ...
+ </build>
+ ...
+</project>
+```
diff --git a/src/site/site.xml b/src/site/site.xml
index 2ae2acd..3154d72 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -19,18 +19,16 @@ specific language governing permissions and limitations
under the License.
-->
-<project xmlns="http://maven.apache.org/DECORATION/1.8.1";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.1
https://maven.apache.org/xsd/decoration-1.8.1.xsd";>
+<site xmlns="http://maven.apache.org/SITE/2.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0
https://maven.apache.org/xsd/site-2.0.0.xsd";>
<body>
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<item name="Usage" href="usage.html"/>
<item name="JavaDocs" href="apidocs/index.html"/>
<item name="Source Xref" href="xref/index.html"/>
- <!--item name="FAQ" href="faq.html"/-->
- <!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
<item name="License" href="https://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>
</menu>
</body>
-</project>
+</site>
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..e705033 100644
--- a/src/test/java/org/apache/maven/shared/invoker/DefaultInvokerTest.java
+++ b/src/test/java/org/apache/maven/shared/invoker/DefaultInvokerTest.java
@@ -89,7 +89,7 @@ class DefaultInvokerTest {
// exitCode can't be used because in case of a timeout it's not
correctly
// set in DefaultInvoker. Need to think about this.
- // assertEquals( 1, result.getExitCode() );
+ // assertEquals(1, result.getExitCode());
}
@Test
diff --git
a/src/test/resources/test-build-should-fail/src/main/java/org/apache/maven/shared/invoker/App.java
b/src/test/resources/test-build-should-fail/src/main/java/org/apache/maven/shared/invoker/App.java
index 753a51c..8d1a703 100644
---
a/src/test/resources/test-build-should-fail/src/main/java/org/apache/maven/shared/invoker/App.java
+++
b/src/test/resources/test-build-should-fail/src/main/java/org/apache/maven/shared/invoker/App.java
@@ -23,10 +23,8 @@ package org.apache.maven.shared.invoker;
* Hello world!
*
*/
-public class App
-{
- public static void main( String[] args )
- {
- System.out.println( "Hello World!" );
+public class App {
+ public static void main(String[] args) {
+ System.out.println("Hello World!");
}
}
diff --git
a/src/test/resources/test-build-should-succeed/src/main/java/org/apache/maven/shared/invoker/App.java
b/src/test/resources/test-build-should-succeed/src/main/java/org/apache/maven/shared/invoker/App.java
index 753a51c..4092ced 100644
---
a/src/test/resources/test-build-should-succeed/src/main/java/org/apache/maven/shared/invoker/App.java
+++
b/src/test/resources/test-build-should-succeed/src/main/java/org/apache/maven/shared/invoker/App.java
@@ -23,10 +23,9 @@ package org.apache.maven.shared.invoker;
* Hello world!
*
*/
-public class App
+public class App
{
- public static void main( String[] args )
- {
- System.out.println( "Hello World!" );
+ public static void main(String[] args) {
+ System.out.println("Hello World!");
}
}
diff --git
a/src/test/resources/test-build-should-timeout/src/main/java/org/apache/maven/shared/invoker/App.java
b/src/test/resources/test-build-should-timeout/src/main/java/org/apache/maven/shared/invoker/App.java
index 753a51c..4092ced 100644
---
a/src/test/resources/test-build-should-timeout/src/main/java/org/apache/maven/shared/invoker/App.java
+++
b/src/test/resources/test-build-should-timeout/src/main/java/org/apache/maven/shared/invoker/App.java
@@ -23,10 +23,9 @@ package org.apache.maven.shared.invoker;
* Hello world!
*
*/
-public class App
+public class App
{
- public static void main( String[] args )
- {
- System.out.println( "Hello World!" );
+ public static void main(String[] args) {
+ System.out.println("Hello World!");
}
}
diff --git
a/src/test/resources/test-build-should-timeout/src/test/java/org/apache/maven/shared/invoker/AppTest.java
b/src/test/resources/test-build-should-timeout/src/test/java/org/apache/maven/shared/invoker/AppTest.java
index 27808ea..5bf7cc6 100644
---
a/src/test/resources/test-build-should-timeout/src/test/java/org/apache/maven/shared/invoker/AppTest.java
+++
b/src/test/resources/test-build-should-timeout/src/test/java/org/apache/maven/shared/invoker/AppTest.java
@@ -29,16 +29,13 @@ public class AppTest
/**
* Not ending test
- * @throws InterruptedException
+ * @throws InterruptedException
*/
- @Test( timeout = 7000 ) // should be killed in 4 sec by Invoker -
Workaround for Windows MSHARED-867
- public void testApp() throws InterruptedException
- {
- while ( true )
- {
- Thread.sleep( 1000L );
+ @Test(timeout = 7000) // should be killed in 4 sec by Invoker - Workaround
for Windows MSHARED-867
+ public void testApp() throws InterruptedException {
+ while (true) {
+ Thread.sleep(1000L);
}
-
-// assertTrue( true );
+// assertTrue( true);
}
}
