Add some docs and bump version.

Author: js-labs

pom.xml

@@ -7,7 +7,7 @@
   <packaging>jar</packaging>
 
   <name>js-collider</name>
-  <version>0.2.1</version>
+  <version>0.2.2</version>
   <description>Java NIO framework</description>
   <url>https://github.com/js-labs/js-collider</url>
 

src/main/java/org/jsl/collider/Acceptor.java

@@ -21,6 +21,11 @@
 
 import java.net.InetSocketAddress;
 
+/**
+ * {@code Acceptor} is used to accepot inbound socket connections.
+ * See {@link Collider} for details.
+ */
+
 public abstract class Acceptor extends SessionEmitter
 {
     public Acceptor()
@@ -35,10 +40,10 @@ public Acceptor(InetSocketAddress addr)
 
     /**
      * Called by the framework to create <tt>Session.Listener</tt> instance
-     * to be linked with the session. METHOD IS NOT [MT] SAFE,
+     * to be linked with the session and underlying socket. METHOD IS NOT [MT] SAFE,
      * can be executed concurrently in a number of threads.
      * Connection and underlying socket will be closed if returns <tt>null</tt>,
-     * but any data scheduled with <tt>sendData</tt> call before return will be sent.
+     * but any data scheduled with <tt>sendData</tt> still will be sent.
      */
     public abstract Session.Listener createSessionListener(Session session);
 

src/main/java/org/jsl/collider/Collider.java

@@ -103,27 +103,34 @@ public final Config getConfig()
     public abstract void stop();
 
     /**
-     * Adds an <tt>Acceptor</tt> to the collider.
+     * Adds an <tt>Acceptor</tt> to the collider. User supposed to extend {@link Acceptor}
+     * class with handlers to be called by the collider when it will be ready to accept
+     * inbound socket connections and when new inbound socket connection appears.
      * Additionally to the server socket exceptions
      * throws an IOException in a case if collider already stopped.
+     * @param acceptor The acceptor instance to add
+     * @throws IOException if collider failed to create accepting socket or collider already stopped
      */
-    public abstract void addAcceptor( Acceptor acceptor ) throws IOException;
+    public abstract void addAcceptor(Acceptor acceptor) throws IOException;
 
     /**
      * Removes the <tt>Acceptor</tt> from the collider.
-     * On return guarantees that no one thread runs
+     * On return guarantees no one thread runs
      * <tt>Acceptor.onAcceptorStarted</tt> or <tt>Acceptor.createSessionListener</tt>.
+     * @param acceptor The acceptor instance to remove
+     * @throws InterruptedException if thread was interrupted on wait
      */
-    public abstract void removeAcceptor( Acceptor acceptor ) throws InterruptedException;
+    public abstract void removeAcceptor(Acceptor acceptor) throws InterruptedException;
 
     /**
      * Adds <tt>Connector</tt> to the collider.
      * Operation is asynchronous, socket operations can throw an exception,
      * Connector.onException will be called in this case in the collider thread pool,
      * better to handle it properly.
+     * @param connector The connector instance to add
      */
-    public abstract void addConnector( Connector connector );
-    public abstract void removeConnector( Connector connector ) throws InterruptedException;
+    public abstract void addConnector(Connector connector);
+    public abstract void removeConnector(Connector connector) throws InterruptedException;
 
     public abstract void addDatagramListener(
             DatagramListener datagramListener ) throws IOException;
@@ -139,14 +146,16 @@ public abstract void removeDatagramListener(
 
     /**
      * Create a Collider instance with default configuration.
+     * @return a new collider instance
+     * @throws IOException if selector I/O error occurs
      */
     public static Collider create() throws IOException
     {
-        return create( new Config() );
+        return create(new Config());
     }
 
-    public static Collider create( Config config ) throws IOException
+    public static Collider create(Config config) throws IOException
     {
-        return new ColliderImpl( config );
+        return new ColliderImpl(config);
     }
 }

src/main/java/org/jsl/collider/Connector.java

@@ -24,9 +24,9 @@
 
 public abstract class Connector extends SessionEmitter
 {
-    public Connector( InetSocketAddress addr )
+    public Connector(InetSocketAddress addr)
     {
-        super( addr );
+        super(addr);
     }
 
     /**
@@ -35,11 +35,12 @@ public Connector( InetSocketAddress addr )
      * Connection will be closed if returns <tt>null</tt>, but any data
      * scheduled with <tt>sendData</tt> call before return will be sent.
      */
-    public abstract Session.Listener createSessionListener( Session session );
+    public abstract Session.Listener createSessionListener(Session session);
 
     /**
      * Called by framework in a case if asynchronous operation
      * with underlying socket channel throws some exception.
+     * @param ex An exception thrown by asynchronous I/O operation
      */
-    public abstract void onException( IOException ex );
+    public abstract void onException(IOException ex);
 }

src/main/java/org/jsl/collider/DataBlock.java

@@ -21,7 +21,7 @@
 
 import java.nio.ByteBuffer;
 
-public class DataBlock
+class DataBlock
 {
     public DataBlock next;
     public final ByteBuffer wr;

src/main/java/org/jsl/collider/DataBlockCache.java

@@ -24,7 +24,7 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
-public class DataBlockCache
+class DataBlockCache
 {
     private final boolean m_useDirectBuffers;
     private final int m_blockSize;

src/main/java/org/jsl/collider/MessageQueue.java

@@ -218,8 +218,9 @@ public MessageQueue( DataBlockCache dataBlockCache )
     }
 
     /**
+     * @param msg the buffer to append
      * @return ByteBuffer instance to be processed (queue was empty),
-     * or <null> if queue was not empty.
+     * or {@code null} if queue was not empty.
      */
     public final ByteBuffer putAndGet( ByteBuffer msg )
     {
@@ -265,7 +266,7 @@ public final ByteBuffer putAndGet( ByteBuffer msg )
 
     /**
      * @return next data block to be processed,
-     * or <null> if queue become empty.
+     * or {@code null} if queue become empty.
      */
     public final ByteBuffer getNext()
     {

src/main/java/org/jsl/collider/Session.java

@@ -31,8 +31,9 @@ public interface Listener
          * Executed serially in a one thread, but not necessary always the same.
          * Position in the byte buffer can be greater than 0,
          * limit can be less than capacity.
+         * @param data the data received from the related socket
          */
-        public abstract void onDataReceived( RetainableByteBuffer data );
+        public abstract void onDataReceived(RetainableByteBuffer data);
 
         /**
          * Called by framework when underlying socket channel
@@ -42,17 +43,17 @@ public interface Listener
     }
 
     /**
-     * Returns Collider instance the session is linked with.
+     * @return Collider instance the session is linked with.
      */
     public Collider getCollider();
 
     /**
-     * Returns local socket address of the session.
+     * @return local socket address of the session.
      */
     public SocketAddress getLocalAddress();
 
     /**
-     * Returns remote socket address of the session.
+     * @return remote socket address of the session.
      */
     public SocketAddress getRemoteAddress();
 
@@ -62,8 +63,9 @@ public interface Listener
      * (even it's attributes like a position, limit etc)
      * so the buffer can be reused to send the same data
      * to the different sessions.
-     * @return >=0 - byte buffer is retained by the framework, will be sent as soon as possible
-     *          -1 - the session is closed
+     * @param data byte buffer with data to send
+     * @return value greater than 0 if byte buffer is retained by the framework,
+     * (data will be sent as soon as possible), or less than 0 if the session is closed.
      */
     public int sendData( ByteBuffer data );
     public int sendData( RetainableByteBuffer data );
@@ -72,9 +74,10 @@ public interface Listener
      * Method makes an attempt to write data synchronously to the underlying socket channel.
      * It can happen if it is the single thread calling the <em>sendData</em> or <em>sendDataSync</em>.
      * Otherwise data will sent as <em>sendData</em> would be called.
-     * @return  0 - data written to socket, byte buffer can be reused
-     *         >0 - byte buffer is retained by the framework, will be sent as soon as possible
-     *         -1 - the session is closed
+     * @param data byte buffer with data to send
+     * @return 0 if data has been written to the socket and byte buffer can be reused,
+     * greater than 0 if byte buffer is retained by the framework, will be sent as soon as possible,
+     * less than 0 if session is closed.
      */
     public int sendDataSync( ByteBuffer data );
 
@@ -87,8 +90,8 @@ public interface Listener
      * will be called after all received data will be processed.
      * All further <em>sendData</em>, <em>sendDataAsync</em> and
      * <em>closeConnection</em> calls will return -1.
-     * @return >0 - amount of data waiting to be sent
-     *         <0 - session already closed and has no data to be sent
+     * @return less than 0 if session already has been closed,
+     * otherwise amount of data waiting to be sent.
      */
     public int closeConnection();
 
@@ -97,8 +100,10 @@ public interface Listener
      * Supposed to be called only from the <tt>onDataReceived()</tt> callback.
      * Calling it not from the <tt>onDataReceived</tt> callback will result
      * in undefined behaviour.
+     * @param newListener the new listener to be used for the session
+     * @return the previous listener was used to the session
      */
-    public Listener replaceListener( Listener newListener );
+    public Listener replaceListener(Listener newListener);
 
-    public int accelerate( ShMem shMem, ByteBuffer message );
+    public int accelerate(ShMem shMem, ByteBuffer message);
 }

src/main/java/org/jsl/collider/SessionEmitter.java

@@ -22,7 +22,6 @@
 import java.net.InetSocketAddress;
 import java.nio.ByteOrder;
 
-
 public abstract class SessionEmitter
 {
     private final InetSocketAddress m_addr;
@@ -75,6 +74,8 @@ public InetSocketAddress getAddr()
      * Called by framework to create session listener instance.
      * See <tt>Acceptor.createSessionListener</tt> and
      * <tt>Connector.createSessionListener</tt> for detailed description.
+     * @param session session the listener will be used for
+     * @return A listener object for the given session
      */
-    public abstract Session.Listener createSessionListener( Session session );
+    public abstract Session.Listener createSessionListener(Session session);
 }

src/main/java/org/jsl/collider/TimerQueue.java

@@ -250,8 +250,9 @@ private void removeTimerLocked( TimerInfo timerInfo )
 
     /**
      * Public methods
+     * @param threadPool the thread pool to execute timer tasks in.
      */
-    public TimerQueue( ThreadPool threadPool )
+    public TimerQueue(ThreadPool threadPool)
     {
         m_threadPool = threadPool;
         m_lock = new ReentrantLock();
@@ -262,8 +263,12 @@ public TimerQueue( ThreadPool threadPool )
 
     /**
      * Schedules the specified task for execution after the specified delay.
+     * @param task the task to be executed
+     * @param delay the time to wait
+     * @param unit the time unot of the {@code delay} argument
+     * @return less than 0 if task already registered, 0 if task scheduled
      */
-    public int schedule( Task task, long delay, TimeUnit unit )
+    public int schedule(Task task, long delay, TimeUnit unit)
     {
         m_lock.lock();
         try
@@ -322,8 +327,12 @@ public int schedule( Task task, long delay, TimeUnit unit )
      * Cancel timer,
      * waits if timer is being firing at the moment,
      * so it guarantees that timer handler is not executed on return.
+     * @param task the task to cancel
+     * @return less than 0 if timer task was not registered or timer already fired,
+     * greater than 0 if task removed before the timer fired.
+     * @throws InterruptedException if thread interrupted on wait
      */
-    public int cancel( Task task ) throws InterruptedException
+    public int cancel(Task task) throws InterruptedException
     {
         m_lock.lock();
         try
@@ -384,11 +393,12 @@ else if (timerInfo.threadID == -2)
     }
 
     /**
-     * Cancel timer,
-     * do not wait if the task is being executed at that moment,
-     * return > 0 in this case.
+     * Cancel timer, do not wait if the task is being executed at that moment.
+     * @param task the task to cancel
+     * @return less than 0 if task not registered, 0 if timer task canceled,
+     * greater than 0 if timer task was executed at the call.
      */
-    public int cancelNoWait( Task task )
+    public int cancelNoWait(Task task)
     {
         m_lock.lock();
         try