Added JavaDoc and re-added the callback functionality to fix #101

Added more comments to the sample

Author: neutralleiter

core/src/main/java/eu/bittrade/libs/steemj/SteemJ.java

@@ -77,7 +77,7 @@
 import eu.bittrade.libs.steemj.communication.BlockAppliedCallback;
 import eu.bittrade.libs.steemj.communication.CallbackHub;
 import eu.bittrade.libs.steemj.communication.CommunicationHandler;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCRequest;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCRequest;
 import eu.bittrade.libs.steemj.configuration.SteemJConfig;
 import eu.bittrade.libs.steemj.enums.AssetSymbolType;
 import eu.bittrade.libs.steemj.enums.DiscussionSortType;

core/src/main/java/eu/bittrade/libs/steemj/apis/follow/FollowApi.java

@@ -14,7 +14,7 @@
 import eu.bittrade.libs.steemj.base.models.AccountName;
 import eu.bittrade.libs.steemj.base.models.Permlink;
 import eu.bittrade.libs.steemj.communication.CommunicationHandler;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCRequest;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCRequest;
 import eu.bittrade.libs.steemj.enums.RequestMethods;
 import eu.bittrade.libs.steemj.enums.SteemApiType;
 import eu.bittrade.libs.steemj.exceptions.SteemCommunicationException;

core/src/main/java/eu/bittrade/libs/steemj/apis/market/history/MarketHistoryApi.java

@@ -10,7 +10,7 @@
 import eu.bittrade.libs.steemj.apis.market.history.model.OrderBook;
 import eu.bittrade.libs.steemj.base.models.TimePointSec;
 import eu.bittrade.libs.steemj.communication.CommunicationHandler;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCRequest;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCRequest;
 import eu.bittrade.libs.steemj.enums.RequestMethods;
 import eu.bittrade.libs.steemj.enums.SteemApiType;
 import eu.bittrade.libs.steemj.exceptions.SteemCommunicationException;

core/src/main/java/eu/bittrade/libs/steemj/apis/network/broadcast/NetworkBroadcastApi.java

@@ -2,7 +2,7 @@
 
 import eu.bittrade.libs.steemj.base.models.SignedTransaction;
 import eu.bittrade.libs.steemj.communication.CommunicationHandler;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCRequest;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCRequest;
 import eu.bittrade.libs.steemj.enums.RequestMethods;
 import eu.bittrade.libs.steemj.enums.SteemApiType;
 import eu.bittrade.libs.steemj.exceptions.SteemCommunicationException;

core/src/main/java/eu/bittrade/libs/steemj/communication/AbstractClient.java

@@ -3,8 +3,8 @@
 import java.io.IOException;
 import java.net.URI;
 
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCRequest;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCResponse;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCRequest;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCResponse;
 import eu.bittrade.libs.steemj.exceptions.SteemCommunicationException;
 import eu.bittrade.libs.steemj.exceptions.SteemResponseException;
 
@@ -15,27 +15,41 @@
  */
 public abstract class AbstractClient {
     /**
+     * Use this method to send a <code>requestObject</code> to the
+     * <code>endpointUri</code> and to receive an answer.
      * 
      * @param requestObject
+     *            The object to send.
      * @param endpointUri
+     *            The endpoint to connect and send to.
      * @param sslVerificationDisabled
-     * @return The response
+     *            Define if the SSL verification should be disabled.
+     * @return The response returned by the Steem Node wrapped in a
+     *         {@link JsonRPCResponse} object.
      * @throws SteemCommunicationException
+     *             In case of communication problems.
      * @throws SteemResponseException
      *             If the answer received from the node is no valid JSON.
      */
     public abstract JsonRPCResponse invokeAndReadResponse(JsonRPCRequest requestObject, URI endpointUri,
             boolean sslVerificationDisabled) throws SteemCommunicationException, SteemResponseException;
 
     /**
+     * Use this method to handle callbacks.
      * 
      * @param rawJsonResponse
+     *            A {@link JsonRPCResponse} instance wrapping a potential
+     *            callback.
+     * @throws SteemCommunicationException
+     *             If the <code>rawJsonResponse</code> is not a callback.
      */
-    protected abstract void handleCallback(JsonRPCResponse rawJsonResponse);
+    protected abstract void handleCallback(JsonRPCResponse rawJsonResponse) throws SteemCommunicationException;
 
     /**
+     * Use this method to close the connection of this client.
      * 
      * @throws IOException
+     *             If the connection can't be closed.
      */
     public abstract void closeConnection() throws IOException;
 }

core/src/main/java/eu/bittrade/libs/steemj/communication/CommunicationHandler.java

@@ -18,8 +18,8 @@
 import com.fasterxml.jackson.databind.module.SimpleModule;
 
 import eu.bittrade.libs.steemj.base.models.serializer.BooleanSerializer;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCRequest;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCResponse;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCRequest;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCResponse;
 import eu.bittrade.libs.steemj.configuration.SteemJConfig;
 import eu.bittrade.libs.steemj.exceptions.SteemCommunicationException;
 import eu.bittrade.libs.steemj.exceptions.SteemResponseException;
@@ -34,11 +34,14 @@
 public class CommunicationHandler {
     private static final Logger LOGGER = LoggerFactory.getLogger(CommunicationHandler.class);
 
-    /** */
+    /**
+     * A preconfigured mapper instance used for de-/serialization of Json
+     * objects.
+     */
     private static ObjectMapper mapper = getObjectMapper();
-    /** */
+    /** A counter for failed connection tries. */
     private int numberOfConnectionTries = 0;
-    /** */
+    /** The client used to send requests. */
     private AbstractClient client;
 
     /**
@@ -53,9 +56,12 @@ public CommunicationHandler() throws SteemCommunicationException {
     }
 
     /**
-     * @throws SteemCommunicationException
-     * 
+     * Initialize a new <code>client</code> by selecting one of the configured
+     * endpoints.
      * 
+     * @throws SteemCommunicationException
+     *             If no {@link AbstractClient} implementation for the given
+     *             schema is available.
      */
     public void initializeNewClient() throws SteemCommunicationException {
         if (client != null) {

core/src/main/java/eu/bittrade/libs/steemj/communication/HttpClient.java

@@ -16,8 +16,8 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCRequest;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCResponse;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCRequest;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCResponse;
 import eu.bittrade.libs.steemj.configuration.SteemJConfig;
 import eu.bittrade.libs.steemj.exceptions.SteemCommunicationException;
 

core/src/main/java/eu/bittrade/libs/steemj/communication/WebsocketClient.java

@@ -18,8 +18,8 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCRequest;
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCResponse;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCRequest;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCResponse;
 import eu.bittrade.libs.steemj.configuration.SteemJConfig;
 import eu.bittrade.libs.steemj.exceptions.SteemCommunicationException;
 import eu.bittrade.libs.steemj.exceptions.SteemResponseException;
@@ -34,15 +34,18 @@
 public class WebsocketClient extends AbstractClient {
     private static final Logger LOGGER = LoggerFactory.getLogger(WebsocketClient.class);
 
-    /** */
+    /** The client. */
     private ClientManager client;
-    /** */
+    /** A {@link CountDownLatch} used to indicate that a message is expected. */
     private CountDownLatch responseCountDownLatch;
-    /** */
+    /** The current session. */
     private Session session;
-    /** */
+    /**
+     * The {@link WebsocketEndpoint} instance that will handle the incoming
+     * messages.
+     */
     private WebsocketEndpoint websocketEndpoint;
-    /** */
+    /** The endpoint this client instance is currently connected to. */
     private URI currentEndpointUri;
 
     /**
@@ -109,18 +112,8 @@ public JsonRPCResponse invokeAndReadResponse(JsonRPCRequest requestObject, URI e
     }
 
     @Override
-    protected void handleCallback(JsonRPCResponse response) {
-      //  try {
-        //    NotificationDTO response = mapper.readValue(message, NotificationDTO.class);
-
-            // Make sure that the inner result object is a BlockHeader.
-        //    CallbackHub.getInstance().getCallbackByUuid(Integer.valueOf(response.getParams()[0].toString()))
-       //             .onNewBlock(mapper.convertValue(((ArrayList<Object>) (response.getParams()[1])).get(0),
-        //                    SignedBlockHeader.class));
-       // } catch (IOException e) {
-            // TODO Auto-generated catch block
-        //    LOGGER.error("Could not parse callback {}.", e);
-        //}
+    protected void handleCallback(JsonRPCResponse response) throws SteemCommunicationException {
+        response.handleCallback();
     }
 
     @Override
@@ -132,23 +125,29 @@ public void closeConnection() throws IOException {
     }
 
     /**
+     * Get the {@link CountDownLatch} used by this instance to change its
+     * counter.
      * 
-     * @return
+     * @return The {@link CountDownLatch} used by this instance.
      */
     protected CountDownLatch getResponseCountDownLatch() {
         return this.responseCountDownLatch;
     }
 
     /**
-     * @return the session
+     * Get the current {@link Session}.
+     * 
+     * @return The session used by this instance.
      */
     protected Session getSession() {
         return session;
     }
 
     /**
+     * Update the {@link Session} this instance should use.
+     * 
      * @param session
-     *            the session to set
+     *            The session to set.
      */
     protected void setSession(Session session) {
         this.session = session;

core/src/main/java/eu/bittrade/libs/steemj/communication/WebsocketEndpoint.java

@@ -11,7 +11,8 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import eu.bittrade.libs.steemj.communication.dto.JsonRPCResponse;
+import eu.bittrade.libs.steemj.communication.jrpc.JsonRPCResponse;
+import eu.bittrade.libs.steemj.exceptions.SteemCommunicationException;
 import eu.bittrade.libs.steemj.exceptions.SteemResponseException;
 
 /**
@@ -22,23 +23,30 @@
 public class WebsocketEndpoint extends Endpoint implements MessageHandler.Whole<String> {
     private static final Logger LOGGER = LoggerFactory.getLogger(WebsocketEndpoint.class);
 
-    /** */
+    /** The latest response received from a Steem Node. */
     private String latestResponse;
-    /** */
+    /** The {@link WebsocketClient} whose session object should be updated. */
     private WebsocketClient websocketClient;
 
     /**
+     * Create a new {@link WebsocketEndpoint} instance.
      * 
      * @param websocketClient
+     *            The @link WebsocketClient} whose session object should be
+     *            updated.
      */
     public WebsocketEndpoint(WebsocketClient websocketClient) {
         this.websocketClient = websocketClient;
     }
 
     /**
+     * Pull the latest response.
      * 
-     * @return
+     * @return In case a response has already been received a new
+     *         {@link JsonRPCResponse} instance that wraps the response,
+     *         otherwise the method will return <code>null</code>.
      * @throws SteemResponseException
+     *             In case the response can not be parsed as a tree.
      */
     protected JsonRPCResponse getLatestResponse() throws SteemResponseException {
         try {
@@ -74,6 +82,24 @@ public void onOpen(Session session, EndpointConfig config) {
     public void onMessage(String message) {
         latestResponse = message;
 
-        this.websocketClient.getResponseCountDownLatch().countDown();
+        if (this.websocketClient.getResponseCountDownLatch().getCount() > 0) {
+            this.websocketClient.getResponseCountDownLatch().countDown();
+        } else {
+            /*
+             * The client does not wait for an answer so this is probably a
+             * callback.
+             */
+            try {
+                JsonRPCResponse response = getLatestResponse();
+
+                if (response.isCallback()) {
+                    this.websocketClient.handleCallback(response);
+                }
+            } catch (SteemCommunicationException | SteemResponseException e) {
+                // Sadly it is not possible to throw an exception here, so the
+                // only useful thing we can do is to log it.
+                LOGGER.error("Tried to handle a potential callback and failed.", e);
+            }
+        }
     }
 }

core/src/main/java/eu/bittrade/libs/steemj/communication/dto/NotificationDTO.java

@@ -1,4 +1,4 @@
-package eu.bittrade.libs.steemj.communication.dto;
+package eu.bittrade.libs.steemj.communication.jrpc;
 
 import java.util.Random;