Javadoc (#135)

* some javadoc

* apply spotless

* more javadoc

* change class and constructor visibilities, add javadoc

* add more javadoc

* fix review round, apply spotless

src/main/java/com/teragrep/rlp_03/channel/buffer/BufferContainer.java

@@ -48,13 +48,22 @@
 import java.nio.ByteBuffer;
 
 /**
- * Interface for a buffer container object.
+ * BufferContainer is a decorator for {@link ByteBuffer} with an id.
  */
 public interface BufferContainer {
 
+    /**
+     * @return id of the buffer
+     */
     long id();
 
+    /**
+     * @return encapsulated {@link ByteBuffer}.
+     */
     ByteBuffer buffer();
 
+    /**
+     * @return is this a stub implementation.
+     */
     boolean isStub();
 }

src/main/java/com/teragrep/rlp_03/channel/buffer/BufferContainerImpl.java

@@ -51,16 +51,15 @@
 import java.nio.ByteBuffer;
 
 /**
- * Implementation of the BufferContainer interface. Contains the buffer with a synchronized (lock-free) way of accessing
- * it.
+ * Decorator for {@link ByteBuffer} with a synchronized access for it.
  */
-public class BufferContainerImpl implements BufferContainer {
+final class BufferContainerImpl implements BufferContainer {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(BufferContainerImpl.class);
     private final long id;
     private final ByteBuffer buffer;
 
-    public BufferContainerImpl(long id, ByteBuffer buffer) {
+    BufferContainerImpl(long id, ByteBuffer buffer) {
         this.id = id;
         this.buffer = buffer;
     }

src/main/java/com/teragrep/rlp_03/channel/buffer/BufferContainerStub.java

@@ -48,9 +48,13 @@
 import java.nio.ByteBuffer;
 
 /**
- * Buffer container stub object. Use isStub() to check. Other methods will result in an IllegalStateException.
+ * Stub implementation of the {@link BufferContainer}.
  */
-public class BufferContainerStub implements BufferContainer {
+final class BufferContainerStub implements BufferContainer {
+
+    BufferContainerStub() {
+
+    }
 
     @Override
     public long id() {

src/main/java/com/teragrep/rlp_03/channel/buffer/BufferLease.java

@@ -47,19 +47,43 @@
 
 import java.nio.ByteBuffer;
 
+/**
+ * BufferLease is a decorator for {@link BufferContainer} with reference counter
+ */
 public interface BufferLease {
 
+    /**
+     * @return identity of the decorated {@link BufferContainer}.
+     */
     long id();
 
+    /**
+     * @return current reference count.
+     */
     long refs();
 
+    /**
+     * @return encapsulated buffer of the {@link BufferContainer}.
+     */
     ByteBuffer buffer();
 
-    void addRef();
+    /**
+     * Add reference, throws {@link IllegalStateException} if lease has expired.
+     */
+    void addRef() throws IllegalStateException;
 
-    void removeRef();
+    /**
+     * Remove reference, throws {@link IllegalStateException} if lease has expired.
+     */
+    void removeRef() throws IllegalStateException;
 
+    /**
+     * @return status of the lease, {@code true} indicates that the lease has expired.
+     */
     boolean isRefCountZero();
 
+    /**
+     * @return is this a stub implementation.
+     */
     boolean isStub();
 }

src/main/java/com/teragrep/rlp_03/channel/buffer/BufferLeaseImpl.java

@@ -48,13 +48,18 @@
 import java.nio.ByteBuffer;
 import java.util.concurrent.Phaser;
 
-public class BufferLeaseImpl implements BufferLease {
+/**
+ * Decorator for {@link BufferContainer} that automatically clears (frees) the encapsulated {@link ByteBuffer} and
+ * returns the {@link BufferContainer} to {@link BufferLeasePool} when reference count hits zero. Starts with one
+ * initial reference. Internally uses a {@link Phaser} to track reference count in a non-blocking way.
+ */
+final class BufferLeaseImpl implements BufferLease {
 
     private final BufferContainer bufferContainer;
     private final Phaser phaser;
     private final BufferLeasePool bufferLeasePool;
 
-    public BufferLeaseImpl(BufferContainer bc, BufferLeasePool bufferLeasePool) {
+    BufferLeaseImpl(BufferContainer bc, BufferLeasePool bufferLeasePool) {
         this.bufferContainer = bc;
         this.bufferLeasePool = bufferLeasePool;
 

src/main/java/com/teragrep/rlp_03/channel/buffer/BufferLeasePool.java

@@ -59,8 +59,12 @@
 import java.util.concurrent.locks.ReentrantLock;
 import java.util.function.Supplier;
 
-// FIXME create tests
-public class BufferLeasePool {
+/**
+ * Non-blocking pool for {@link BufferContainer} objects. All objects in the pool are {@link ByteBuffer#clear()}ed
+ * before returning to the pool by {@link BufferLease}.
+ */
+public final class BufferLeasePool {
+    // TODO create tests
 
     private static final Logger LOGGER = LoggerFactory.getLogger(BufferLeasePool.class);
 
@@ -122,6 +126,10 @@ private BufferLease take() {
 
     }
 
+    /**
+     * @param size minimum size of the {@link BufferLease}s requested.
+     * @return list of {@link BufferLease}s meeting or exceeding the size requested.
+     */
     public List<BufferLease> take(long size) {
         if (close.get()) {
             return Collections.singletonList(bufferLeaseStub);
@@ -140,10 +148,17 @@ public List<BufferLease> take(long size) {
 
     }
 
+    // FIXME remove this, use BufferLease.removeRef() instead directly.
     public void offer(BufferLease bufferLease) {
         bufferLease.removeRef();
     }
 
+    /**
+     * return {@link BufferContainer} into the pool.
+     * 
+     * @param bufferContainer {@link BufferContainer} from {@link BufferLease} which has been
+     *                        {@link ByteBuffer#clear()}ed.
+     */
     void internalOffer(BufferContainer bufferContainer) {
         // Add buffer back to pool if it is not a stub object
         if (!bufferContainer.isStub()) {
@@ -169,6 +184,10 @@ void internalOffer(BufferContainer bufferContainer) {
         }
     }
 
+    /**
+     * Closes the {@link BufferLeasePool}, deallocating currently residing {@link BufferContainer}s and future ones when
+     * returned.
+     */
     public void close() {
         LOGGER.debug("close called");
         close.set(true);
@@ -178,6 +197,11 @@ public void close() {
 
     }
 
+    /**
+     * Estimate the pool size, due to non-blocking nature of the pool, this is only an estimate.
+     * 
+     * @return estimate of the pool size, counting only the residing buffers.
+     */
     public int estimatedSize() {
         return queue.size();
     }

src/main/java/com/teragrep/rlp_03/channel/buffer/BufferLeaseStub.java

@@ -47,7 +47,14 @@
 
 import java.nio.ByteBuffer;
 
-public class BufferLeaseStub implements BufferLease {
+/**
+ * Stub implementation of the {@link BufferLease}
+ */
+final class BufferLeaseStub implements BufferLease {
+
+    BufferLeaseStub() {
+
+    }
 
     @Override
     public long id() {

src/main/java/com/teragrep/rlp_03/channel/context/ConnectContext.java

@@ -45,8 +45,6 @@
  */
 package com.teragrep.rlp_03.channel.context;
 
-import com.teragrep.rlp_03.channel.InterestOps;
-import com.teragrep.rlp_03.channel.InterestOpsImpl;
 import com.teragrep.rlp_03.channel.socket.SocketFactory;
 import com.teragrep.rlp_03.frame.delegate.FrameDelegate;
 import org.slf4j.Logger;
@@ -58,7 +56,14 @@
 import java.util.concurrent.ExecutorService;
 import java.util.function.Consumer;
 
-public class ConnectContext implements Context {
+/**
+ * Initiate type {@link Context} that produces an EstablishedContext once it receives an OP_CONNECT type
+ * {@link SelectionKey} from {@link com.teragrep.rlp_03.EventLoop} and socketChannel.finishConnect() succeeds. Use
+ * {@link com.teragrep.rlp_03.EventLoop#register(Context)} to register it to the desired
+ * {@link com.teragrep.rlp_03.EventLoop},
+ */
+public final class ConnectContext implements Context {
+    // TODO should this be named InitiateContext?
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ConnectContext.class);
 
@@ -69,7 +74,7 @@ public class ConnectContext implements Context {
 
     private final Consumer<EstablishedContext> establishedContextConsumer;
 
-    public ConnectContext(
+    ConnectContext(
             SocketChannel socketChannel,
             ExecutorService executorService,
             SocketFactory socketFactory,

src/main/java/com/teragrep/rlp_03/channel/context/ConnectContextFactory.java

@@ -54,16 +54,32 @@
 import java.util.concurrent.ExecutorService;
 import java.util.function.Consumer;
 
-public class ConnectContextFactory {
+/**
+ * Factory for creating {@link ConnectContext}s for initiating new connections.
+ */
+public final class ConnectContextFactory {
 
     private final ExecutorService executorService;
     private final SocketFactory socketFactory;
 
+    /**
+     * @param executorService {@link ExecutorService} to handle connection's events with
+     * @param socketFactory   {@link SocketFactory} that produces the desired type
+     *                        {@link com.teragrep.rlp_03.channel.socket.Socket} for the connection.
+     */
     public ConnectContextFactory(ExecutorService executorService, SocketFactory socketFactory) {
         this.executorService = executorService;
         this.socketFactory = socketFactory;
     }
 
+    /**
+     * @param inetSocketAddress          {@link InetSocketAddress} to initiate connection to.
+     * @param frameDelegate              {@link FrameDelegate} for processing received data with.
+     * @param establishedContextConsumer {@link Consumer<EstablishedContext>} for handling the callback once connection
+     *                                   is established.
+     * @return {@link ConnectContext} to be registered with {@link com.teragrep.rlp_03.EventLoop#register(Context)}.
+     * @throws IOException if underlying {@link SocketChannel} is unable to initiate the connection.
+     */
     public ConnectContext create(
             InetSocketAddress inetSocketAddress,
             FrameDelegate frameDelegate,

src/main/java/com/teragrep/rlp_03/channel/context/Context.java

@@ -49,14 +49,34 @@
 import java.nio.channels.SelectionKey;
 import java.nio.channels.spi.AbstractSelectableChannel;
 
+/**
+ * Context is a network connection element, it may be one of the: initiate {@link ConnectContext}, listen
+ * {@link ListenContext} or established {@link EstablishedContext} types.
+ */
 public interface Context extends Closeable {
 
+    /**
+     * Handles this context's {@link SelectionKey} events. Providing a non-related key will result in non-foreseen
+     * issues, and this is a programming error.
+     * 
+     * @param selectionKey key of this context to handle an event for.
+     */
+    // TODO add checks for such programming error of providing non-related key
     void handleEvent(SelectionKey selectionKey);
 
+    /**
+     * Closes the underlying network connection element and frees resources attached to it.
+     */
     @Override
     void close(); // no exception is thrown
 
+    /**
+     * @return {@link AbstractSelectableChannel} of the network connection element.
+     */
     AbstractSelectableChannel socketChannel();
 
+    /**
+     * @return initial state of the {@link SelectionKey} which the network connection element starts with.
+     */
     int initialSelectionKey();
 }

src/main/java/com/teragrep/rlp_03/channel/context/EstablishedContext.java

@@ -45,14 +45,29 @@
  */
 package com.teragrep.rlp_03.channel.context;
 
-import com.teragrep.rlp_03.channel.InterestOps;
 import com.teragrep.rlp_03.channel.socket.Socket;
 
+import java.util.List;
+
+/**
+ * Established type of {@link Context}. It produces ingress data into the provided
+ * {@link com.teragrep.rlp_03.frame.delegate.FrameDelegate} via {@link RelpRead}. Egress data can be written via
+ * {@link RelpWrite#accept(List)}.
+ */
 public interface EstablishedContext extends Context {
 
+    /**
+     * @return current {@link InterestOps} of the underlying {@link java.nio.channels.SelectionKey}.
+     */
     InterestOps interestOps();
 
+    /**
+     * @return underlying {@link Socket} of the connection.
+     */
     Socket socket();
 
+    /**
+     * @return RelpWrite of the connection for sending egress data.
+     */
     RelpWrite relpWrite();
 }

src/main/java/com/teragrep/rlp_03/channel/context/EstablishedContextImpl.java

@@ -45,7 +45,6 @@
  */
 package com.teragrep.rlp_03.channel.context;
 
-import com.teragrep.rlp_03.channel.*;
 import com.teragrep.rlp_03.frame.delegate.FrameDelegate;
 import com.teragrep.rlp_03.channel.buffer.BufferLeasePool;
 import com.teragrep.rlp_03.channel.socket.Socket;
@@ -63,9 +62,9 @@
 import static java.nio.channels.SelectionKey.OP_WRITE;
 
 /**
- * A per connection object that handles reading and writing messages from and to the SocketChannel.
+ * Implementation of the {@link EstablishedContext}
  */
-public class EstablishedContextImpl implements EstablishedContext { // TODO make package-protected
+final class EstablishedContextImpl implements EstablishedContext { // TODO make package-protected
 
     private static final Logger LOGGER = LoggerFactory.getLogger(EstablishedContextImpl.class);
 
@@ -78,7 +77,7 @@ public class EstablishedContextImpl implements EstablishedContext { // TODO make
     private final RelpRead relpRead;
     private final RelpWrite relpWrite;
 
-    public EstablishedContextImpl(
+    EstablishedContextImpl(
             ExecutorService executorService,
             Socket socket,
             InterestOps interestOps,

src/main/java/com/teragrep/rlp_03/channel/context/EstablishedContextStub.java

@@ -45,13 +45,19 @@
  */
 package com.teragrep.rlp_03.channel.context;
 
-import com.teragrep.rlp_03.channel.InterestOps;
 import com.teragrep.rlp_03.channel.socket.Socket;
 
 import java.nio.channels.SelectionKey;
 import java.nio.channels.spi.AbstractSelectableChannel;
 
-public class EstablishedContextStub implements EstablishedContext {
+/**
+ * Stub implementation of {@link EstablishedContext}
+ */
+final class EstablishedContextStub implements EstablishedContext {
+
+    EstablishedContextStub() {
+
+    }
 
     @Override
     public void close() {