You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by ti...@apache.org on 2020/03/15 13:21:51 UTC
[maven-surefire] branch maven2surefire-jvm-communication updated:
documentation and Javadoc
This is an automated email from the ASF dual-hosted git repository.
tibordigana pushed a commit to branch maven2surefire-jvm-communication
in repository https://gitbox.apache.org/repos/asf/maven-surefire.git
The following commit(s) were added to refs/heads/maven2surefire-jvm-communication by this push:
new 62d0b0a documentation and Javadoc
62d0b0a is described below
commit 62d0b0ab7a3253b6ec0e8b96462229d349f9c64d
Author: tibordigana <ti...@apache.org>
AuthorDate: Sun Mar 15 14:21:43 2020 +0100
documentation and Javadoc
---
.../maven/plugin/failsafe/IntegrationTestMojo.java | 12 ++
.../maven/plugin/surefire/SurefirePlugin.java | 12 ++
.../src/site/apt/examples/process-communication.vm | 153 +++++++++++++++++++++
maven-surefire-plugin/src/site/site.xml | 1 +
4 files changed, 178 insertions(+)
diff --git a/maven-failsafe-plugin/src/main/java/org/apache/maven/plugin/failsafe/IntegrationTestMojo.java b/maven-failsafe-plugin/src/main/java/org/apache/maven/plugin/failsafe/IntegrationTestMojo.java
index a6771bc..0e6e26d 100644
--- a/maven-failsafe-plugin/src/main/java/org/apache/maven/plugin/failsafe/IntegrationTestMojo.java
+++ b/maven-failsafe-plugin/src/main/java/org/apache/maven/plugin/failsafe/IntegrationTestMojo.java
@@ -385,6 +385,18 @@ public class IntegrationTestMojo
@Parameter( property = "failsafe.useModulePath", defaultValue = "true" )
private boolean useModulePath;
+ /**
+ * This parameter configures the forked node. Currently, you can select the communication protocol, i.e. process
+ * pipes or TCP/IP sockets.
+ * The plugin uses process pipes by default which will be turned to TCP/IP in the version 3.0.0.
+ * Alternatively, you can implement your own factory and SPI.
+ * <br>
+ * See the documentation for more details:<br>
+ * <a href="https://maven.apache.org/plugins/maven-surefire-plugin/examples/process-communication.html">
+ * https://maven.apache.org/plugins/maven-surefire-plugin/examples/process-communication.html</a>
+ *
+ * @since 3.0.0-M5
+ */
@Parameter( property = "failsafe.forkNode" )
private ForkNodeFactory forkNode;
diff --git a/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java b/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java
index 5f6edea..b958f92 100644
--- a/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java
+++ b/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java
@@ -366,6 +366,18 @@ public class SurefirePlugin
@Parameter( property = "surefire.useModulePath", defaultValue = "true" )
private boolean useModulePath;
+ /**
+ * This parameter configures the forked node. Currently, you can select the communication protocol, i.e. process
+ * pipes or TCP/IP sockets.
+ * The plugin uses process pipes by default which will be turned to TCP/IP in the version 3.0.0.
+ * Alternatively, you can implement your own factory and SPI.
+ * <br>
+ * See the documentation for more details:<br>
+ * <a href="https://maven.apache.org/plugins/maven-surefire-plugin/examples/process-communication.html">
+ * https://maven.apache.org/plugins/maven-surefire-plugin/examples/process-communication.html</a>
+ *
+ * @since 3.0.0-M5
+ */
@Parameter( property = "surefire.forkNode" )
private ForkNodeFactory forkNode;
diff --git a/maven-surefire-plugin/src/site/apt/examples/process-communication.vm b/maven-surefire-plugin/src/site/apt/examples/process-communication.vm
new file mode 100644
index 0000000..75e553e
--- /dev/null
+++ b/maven-surefire-plugin/src/site/apt/examples/process-communication.vm
@@ -0,0 +1,153 @@
+------
+Using JUnit 5 Platform
+------
+Communication Channels in Surefire <us...@maven.apache.org>
+------
+2020-03-15
+------
+
+~~ 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
+
+Communication Channels used between the Maven Process and Surefire Process
+
+ There is one way to change the communication channel and two types of connection in the ${thisPlugin}.
+ The communication channel can be changed even by the user in the user's POM.
+ The physical layer of the channel can be switched from Process Pipes to TCP/IP.
+ The user select the default implementations in the POM or the user can implement his own channel without asking
+ the Apache Maven development team for a new support. This chapter will show you how this can be accomplished.
+
+* forkNode
+
+ The configuration is done by using only one configuration parameter <<<forkMode>>>.
+
+* The TCP/IP communication channel
+
+ The ${thisPlugin} plugin uses process pipes by default. The implementation class for default configuration
+ is <<<org.apache.maven.plugin.surefire.extensions.LegacyForkNodeFactory>>> and it does not have to be specified.
+ The TCP/IP channel can be selected as follows and the implementation class has to be specified:
+
++---+
+<project>
+ [...]
+ <build>
+ <plugins>
+ [...]
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <forkNode implementation="org.apache.maven.plugin.surefire.extensions.SurefireForkNodeFactory"/>
+ </configuration>
+ </plugin>
+ [...]
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
+
+* Custom implementation
+
+ The custom implementation involves two implementations. The first is used by the Maven process and there you
+ should implement the interface <<<org.apache.maven.surefire.extensions.ForkNodeFactory>>>, use the implementation
+ in a dependency <<<your-extension-api-impl-artifactid>>> declared below the plugin and configuration should
+ specify fully qualified class name of your custom <<<ForkNodeFactory>>> in the attribute <<<implementation>>>.
+
+ The second implementation is SPI which is utilized by the forked JVM. Implement the Java SPI interface
+ <<<org.apache.maven.surefire.spi.MasterProcessChannelProcessorFactory>>> in the artifact
+ <<<your-extension-spi-impl-artifactid>>>.
+
+
++---+
+<project>
+ [...]
+ <dependencies>
+ <dependency>
+ <groupId>your-extension-spi-impl-groupid</groupId>
+ <artifactId>your-extension-spi-impl-artifactid</artifactId>
+ <version>your-extension-spi-impl-version</version>
+ </dependency>
+ </dependencies>
+ [...]
+ <build>
+ <plugins>
+ [...]
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <dependencies>
+ <dependency>
+ <groupId>your-extension-api-impl-groupid</groupId>
+ <artifactId>your-extension-api-impl-artifactid</artifactId>
+ <version>your-extension-api-impl-version</version>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <forkNode implementation="your.extention.api.impl.CustomForkNodeFactory"/>
+ </configuration>
+ </plugin>
+ [...]
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
+
+ The project <<<your-extension-api-impl-artifactid>>> should have the following dependency as mandatory:
+
++---+
+<project>
+ [...]
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>surefire-extensions-api</artifactId>
+ <version>${project.version}</version>
+ <scope>provided</scope>
+ </dependency>
+ </dependencies>
+ [...]
+</project>
++---+
+
+ The project <<<your-extension-spi-impl-artifactid>>> should have the following dependency as mandatory:
+
++---+
+<project>
+ [...]
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>surefire-extensions-spi</artifactId>
+ <version>${project.version}</version>
+ <scope>provided</scope>
+ </dependency>
+ </dependencies>
+ [...]
+</project>
++---+
+
+ Your SPI implementation appears in
+ <<<src/main/resources/META-INF/services/org.apache.maven.surefire.spi.MasterProcessChannelProcessorFactory>>>
+ and contains one implementation class. Your POM already specified it, see
+ <<<your.extention.api.impl.CustomForkNodeFactory>>>.
diff --git a/maven-surefire-plugin/src/site/site.xml b/maven-surefire-plugin/src/site/site.xml
index 87efd78..2cec467 100644
--- a/maven-surefire-plugin/src/site/site.xml
+++ b/maven-surefire-plugin/src/site/site.xml
@@ -38,6 +38,7 @@
<item name="Download" href="../download.html"/>
</menu>
<menu name="Examples">
+ <item name="TCP/IP Communication between Forks" href="examples/process-communication.html"/>
<item name="Using TestNG" href="examples/testng.html"/>
<item name="Using JUnit" href="examples/junit.html"/>
<item name="Using JUnit 5 Platform" href="examples/junit-platform.html"/>