From b082ceb5f1c86c6fb6c7d0eca6efd4d7fc63d4ca Mon Sep 17 00:00:00 2001
From: Benoit Foucher <benoit@zeroc.com>
Date: Tue, 2 Jul 2024 18:22:11 +0200
Subject: [PATCH] Added Java transceiver interface comments (#2373)

---
 .../com/zeroc/IceInternal/ReadyCallback.java  |  8 ++++++++
 .../com/zeroc/IceInternal/Transceiver.java    | 20 +++++++++++++++++--
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/java/src/Ice/src/main/java/com/zeroc/IceInternal/ReadyCallback.java b/java/src/Ice/src/main/java/com/zeroc/IceInternal/ReadyCallback.java
index 29a0a710e85..d74225e7a0a 100644
--- a/java/src/Ice/src/main/java/com/zeroc/IceInternal/ReadyCallback.java
+++ b/java/src/Ice/src/main/java/com/zeroc/IceInternal/ReadyCallback.java
@@ -5,5 +5,13 @@
 package com.zeroc.IceInternal;
 
 public interface ReadyCallback {
+  /**
+   * Sets the transceiver read or write readiness status. This method is used by a transceiver
+   * implementation to notify the thread pool that it's ready or not to write or read data.
+   *
+   * @param op The transceiver read or write operation
+   * @param value The status of the operation readiness, true if the transceiver operation is ready,
+   *     false otherwise.
+   */
   void ready(int op, boolean value);
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/IceInternal/Transceiver.java b/java/src/Ice/src/main/java/com/zeroc/IceInternal/Transceiver.java
index 3a8b80579df..1f2b661f14f 100644
--- a/java/src/Ice/src/main/java/com/zeroc/IceInternal/Transceiver.java
+++ b/java/src/Ice/src/main/java/com/zeroc/IceInternal/Transceiver.java
@@ -5,8 +5,24 @@
 package com.zeroc.IceInternal;
 
 public interface Transceiver {
+  /**
+   * Returns the selectable channel used by the thread pool's selector to wait for read or write
+   * readiness.
+   *
+   * @return The selectable channel that will be registered with the thread pool's selector or null
+   *     if the transceiver doesn't use a selectable channel.
+   */
   java.nio.channels.SelectableChannel fd();
 
+  /**
+   * Sets the transceiver ready callback. This method is called by the thread pool to provide a
+   * callback object that the transceiver can use to notify the thread pool's selector when more
+   * data is ready to be read or written by this transceiver. A transceiver implementation typically
+   * uses this callback when it buffers data read from the selectable channel if it doesn't use a
+   * selectable channel.
+   *
+   * @param callback The ready callback provided by the thread pool's selector.
+   */
   void setReadyCallback(ReadyCallback callback);
 
   int initialize(Buffer readBuffer, Buffer writeBuffer);
@@ -23,10 +39,10 @@ public interface Transceiver {
 
   /**
    * Checks if this transceiver is waiting to be read, typically because it has bytes readily
-   * available for reading.
+   * available for reading. The caller must ensure the transceiver is not closed when calling this
+   * method.
    *
    * @return true if this transceiver is waiting to be read, false otherwise.
-   * @remark The caller must ensure the transceiver is not closed when calling this method.
    */
   boolean isWaitingToBeRead();