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
commit f67a727cb191c444741312732dd25793704ff016
Author: tibordigana <tibordig...@apache.org>
AuthorDate: Sun Feb 9 10:47:09 2020 +0100
JavaDoc in ForkChannel
---
.../maven/surefire/extensions/ForkChannel.java | 64 +++++++++++++++-------
1 file changed, 43 insertions(+), 21 deletions(-)
diff --git
a/surefire-extensions-api/src/main/java/org/apache/maven/surefire/extensions/ForkChannel.java
b/surefire-extensions-api/src/main/java/org/apache/maven/surefire/extensions/ForkChannel.java
index 5d9fbba..baeae00 100644
---
a/surefire-extensions-api/src/main/java/org/apache/maven/surefire/extensions/ForkChannel.java
+++
b/surefire-extensions-api/src/main/java/org/apache/maven/surefire/extensions/ForkChannel.java
@@ -29,14 +29,22 @@ import java.nio.channels.ReadableByteChannel;
import java.nio.channels.WritableByteChannel;
/**
+ * It's a session object used only by a particular Thread in ForkStarter
+ * and dedicated forked JVM {@link #getForkChannelId()}. It represents a
server.
+ * <br>
+ * <br>
+ * It opens the channel via {@link #openChannel()}, provides a connection
string {@link #getForkNodeConnectionString()}
+ * used by the client in the JVM, binds event and command handlers.
+ *
+ * @author <a href="mailto:tibordig...@apache.org";>Tibor Digana (tibor17)</a>
+ * @since 3.0.0-M5
*/
public abstract class ForkChannel implements Closeable
{
private final int forkChannelId;
/**
- *
- * @param forkChannelId
+ * @param forkChannelId the index of the forked JVM, from 1 to N.
*/
protected ForkChannel( int forkChannelId )
{
@@ -46,50 +54,62 @@ public abstract class ForkChannel implements Closeable
public abstract void openChannel() throws IOException;
/**
+ * This is server related class, which if binds to a TCP port, determines
the connection string for the client.
*
- * @return
+ * @return a connection string utilized by the client in the fork JVM
*/
public abstract String getForkNodeConnectionString();
/**
+ * Determines which one of the two <em>bindCommandReader-s</em> to call in
<em>ForkStarter</em>.
+ * Can be called anytime.
*
- * @return
+ * @return If {@code true}, calling {@link
#bindCommandReader(CommandReader, WritableByteChannel)} by
+ * <em>ForkStarter</em> and {@link #bindCommandReader(CommandReader)}
throws {@link UnsupportedOperationException}.
+ * If {@code false}, then opposite.
*/
public abstract boolean useStdIn();
/**
+ * Determines which one of the two <em>bindEventHandler-s</em> to call in
<em>ForkStarter</em>.
+ * Can be called anytime.
*
- * @return
+ * @return If {@code true}, the {@link #bindEventHandler(StreamConsumer,
ReadableByteChannel, CountdownCloseable)}
+ * is called in <em>ForkStarter</em> and {@link
#bindEventHandler(StreamConsumer)} throws
+ * {@link UnsupportedOperationException}.
+ * If {@code false}, then opposite.
*/
public abstract boolean useStdOut();
/**
+ * Binds command handler to the channel.
*
- * @param commands
- * @param stdIn
- * @return
- * @throws IOException
+ * @param commands command reader, see {@link
CommandReader#readNextCommand()}
+ * @param stdIn the standard input stream of the JVM to write the
encoded commands into it
+ * @return the thread instance to start up in order to stream out the data
+ * @throws IOException if an error in the fork channel
*/
public abstract CloseableDaemonThread bindCommandReader( @Nonnull
CommandReader commands,
@Nonnull
WritableByteChannel stdIn )
throws IOException;
/**
+ * Binds command handler to the channel.
*
- * @param commands
- * @return
- * @throws IOException
+ * @param commands command reader, see {@link
CommandReader#readNextCommand()}
+ * @return the thread instance to start up in order to stream out the data
+ * @throws IOException if an error in the fork channel
*/
public abstract CloseableDaemonThread bindCommandReader( @Nonnull
CommandReader commands )
throws IOException;
/**
*
- * @param consumer
- * @param stdOut
- * @param countdownCloseable
- * @return
- * @throws IOException
+ * @param consumer event consumer
+ * @param stdOut the standard output stream of the JVM
+ * @param countdownCloseable count down of the final call of {@link
Closeable#close()}
+ * @return the thread instance to start up in order to stream out the data
+ * @throws IOException if an error in the fork channel
*/
public abstract CloseableDaemonThread bindEventHandler( @Nonnull
StreamConsumer consumer,
@Nonnull
ReadableByteChannel stdOut,
@@ -97,17 +117,19 @@ public abstract class ForkChannel implements Closeable
throws IOException;
/**
+ * Binds event handler to the channel.
*
- * @param consumer
- * @return
- * @throws IOException
+ * @param consumer event consumer
+ * @return the thread instance to start up in order to stream out the data
+ * @throws IOException if an error in the fork channel
*/
public abstract CloseableDaemonThread bindEventHandler( @Nonnull
StreamConsumer consumer )
throws IOException;
/**
+ * The index of the fork.
*
- * @return
+ * @return the index of the forked JVM, from 1 to N.
*/
protected final int getForkChannelId()
{
