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/02/09 09:54:10 UTC
[maven-surefire] 02/02: JavaDoc in ForkChannel
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 <ti...@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:tibordigana@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()
{