maven-surefire-plugin/src/site/apt/examples/process-communication.apt.vm

------
Using JUnit 5 Platform
------
Communication Channels in Surefire <users@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>>>.