(mina) branch 2.0.X updated: Added some javadoc clarification on the IoSession#read() method

[elecharny]

This is an automated email from the ASF dual-hosted git repository.

elecharny pushed a commit to branch 2.0.X
in repository https://gitbox.apache.org/repos/asf/mina.git


The following commit(s) were added to refs/heads/2.0.X by this push:
     new 75121d6e3 Added some javadoc clarification on the IoSession#read() 
method
75121d6e3 is described below

commit 75121d6e3e81cd9b1c0334c8d78f614c3efdf2f8
Author: emmanuel lecharny <elecha...@apache.org>
AuthorDate: Wed Oct 16 09:47:05 2024 +0200

    Added some javadoc clarification on the IoSession#read() method
---
 .../src/main/java/org/apache/mina/core/session/IoSession.java    | 9 ++++++---
 .../org/apache/mina/transport/socket/nio/DIRMINA777Test.java     | 3 ++-
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git 
a/mina-core/src/main/java/org/apache/mina/core/session/IoSession.java 
b/mina-core/src/main/java/org/apache/mina/core/session/IoSession.java
index b1fd6ff4b..ddd72a198 100644
--- a/mina-core/src/main/java/org/apache/mina/core/session/IoSession.java
+++ b/mina-core/src/main/java/org/apache/mina/core/session/IoSession.java
@@ -114,18 +114,21 @@ public interface IoSession {
     TransportMetadata getTransportMetadata();
 
     /**
-     * TODO This javadoc is wrong. The return tag should be short.
-     * 
      * @return a {@link ReadFuture} which is notified when a new message is
      * received, the connection is closed or an exception is caught.  This
      * operation is especially useful when you implement a client application.
-     * TODO : Describe here how we enable this feature.
+     * 
      * However, please note that this operation is disabled by default and
      * throw {@link IllegalStateException} because all received events must be
      * queued somewhere to support this operation, possibly leading to memory
      * leak.  This means you have to keep calling {@link #read()} once you
      * enabled this operation.  To enable this operation, please call
      * {@link IoSessionConfig#setUseReadOperation(boolean)} with {@code true}.
+     * 
+     * Side note: the {@link IoSessionConfig#setUseReadOperation(boolean)} 
call 
+     * MUST be set before the session is opened, otherwise you might have a 
race 
+     * condition if you write a message in {@link 
IoHandler#sessionOpened(IoSession)}
+     * event, as this message could be written before the read hook can be set.
      *
      * @throws IllegalStateException if
      * {@link IoSessionConfig#setUseReadOperation(boolean) useReadOperation}
diff --git 
a/mina-core/src/test/java/org/apache/mina/transport/socket/nio/DIRMINA777Test.java
 
b/mina-core/src/test/java/org/apache/mina/transport/socket/nio/DIRMINA777Test.java
index 1e805700f..f37990f71 100644
--- 
a/mina-core/src/test/java/org/apache/mina/transport/socket/nio/DIRMINA777Test.java
+++ 
b/mina-core/src/test/java/org/apache/mina/transport/socket/nio/DIRMINA777Test.java
@@ -69,12 +69,13 @@ public class DIRMINA777Test {
                 throw connectFuture.getException();
             }
             
-            connectFuture.getSession().getConfig().setUseReadOperation(true);
             ReadFuture readFuture = connectFuture.getSession().read();
             readFuture.awaitUninterruptibly();
+            
             if (readFuture.getException() != null) {
                 throw readFuture.getException();
             }
+            
             IoBuffer message = (IoBuffer)readFuture.getMessage();
             assertEquals(1, message.remaining());
             assertEquals(125,message.get());