Added java docs to common module.

Author: TVolden

ocpp-common/src/main/java/eu/chargetime/ocpp/Client.java

@@ -51,7 +51,7 @@ public abstract class Client
     private Session session;
 
     /**
-     * Constructor
+     * Handle required injections.
      *
      * @param   session     Inject session object
      * @see                 Session

ocpp-common/src/main/java/eu/chargetime/ocpp/Communicator.java

@@ -48,7 +48,7 @@ public abstract class Communicator {
      * @param   payload     the raw formatted payload.
      * @param   type        the expected return type.
      * @return the unpacked payload.
-     * @throws Exception   error occurred while converting.
+     * @throws Exception    error occurred while converting.
      */
     public abstract <T> T unpackPayload(String payload, Class<T> type) throws Exception;
 
@@ -61,9 +61,9 @@ public abstract class Communicator {
     public abstract String packPayload(Object payload);
 
     /**
-     * Create a call result envelope to transmit to the server.
+     * Create a call result envelope to transmit.
      *
-     * @param   uniqueId    the id the server expects.
+     * @param   uniqueId    the id the receiver expects.
      * @param   payload     packed payload.
      * @return a fully packed message ready to send.
      */
@@ -72,17 +72,17 @@ public abstract class Communicator {
     /**
      * Create a call envelope to transmit to the server.
      *
-     * @param   uniqueId    the id the server must reply with.
+     * @param   uniqueId    the id the receiver must reply with.
      * @param   action      action name of the feature.
      * @param   payload     packed payload.
      * @return a fully packed message ready to send.
      */
     protected abstract String makeCall(String uniqueId, String action, String payload);
 
     /**
-     * Create a call error envelope to transmit to the server.
+     * Create a call error envelope to transmit.
      *
-     * @param   uniqueId            the id the server expects.
+     * @param   uniqueId            the id the receiver expects.
      * @param   errorCode           an OCPP error code.
      * @param   errorDescription    an associated error description.
      * @return a fully packed message ready to send.
@@ -91,16 +91,16 @@ public abstract class Communicator {
 
     /**
      * Identify an incoming call and parse it into one of the following:
-     * {@link CallMessage} a request from the server.
-     * {@link CallResultMessage} a response from the server.
+     * {@link CallMessage} a request.
+     * {@link CallResultMessage} a response.
      *
-     * @param   message raw message from server
+     * @param   message     the raw message
      * @return CallMessage or {@link CallResultMessage}
      */
     protected abstract Message parse(String message);
 
     /**
-     * Constructore
+     * Handle required injections.
      *
      * @param   transmitter Injected {@link Transmitter}
      */
@@ -140,9 +140,9 @@ public void disconnected() {
     }
 
     /**
-     * Send a new {@link Request} to the server.
+     * Send a new {@link Request}.
      *
-     * @param   uniqueId    the id the server should use to reply.
+     * @param   uniqueId    the id the receiver should use to reply.
      * @param   action      action name of the {@link eu.chargetime.ocpp.feature.Feature}.
      * @param   request     the outgoing {@link Request}
      */
@@ -151,19 +151,19 @@ public void sendCall(String uniqueId, String action, Request request) {
     }
 
     /**
-     * Send a {@link Confirmation} reply to a server {@link Request}.
+     * Send a {@link Confirmation} reply to a {@link Request}.
      *
-     * @param   uniqueId        the id the server expects.
+     * @param   uniqueId        the id the receiver expects.
      * @param   confirmation    the outgoing {@link Confirmation}
      */
     public void sendCallResult(String uniqueId, Confirmation confirmation) {
         transmitter.send(makeCallResult(uniqueId, packPayload(confirmation)));
     }
 
     /**
-     * Send an error to the server.
+     * Send an error.
      *
-     * @param   uniqueId            the id the server expects a response to.
+     * @param   uniqueId            the id the receiver expects a response to.
      * @param   errorCode           an OCPP error Code
      * @param   errorDescription    a associated error description.
      */
@@ -172,7 +172,7 @@ public void sendCallError(String uniqueId, String errorCode, String errorDescrip
     }
 
     /**
-     * Disconnect from the server. Uses the {@link Transmitter}.
+     * Close down the connection. Uses the {@link Transmitter}.
      */
     public void disconnect() {
         transmitter.disconnect();

ocpp-common/src/main/java/eu/chargetime/ocpp/CommunicatorEvents.java

@@ -32,19 +32,43 @@ of this software and associated documentation files (the "Software"), to deal
  */
 public interface CommunicatorEvents {
     /**
-     * Handle call result from the server.
-     * Use the unique id to identify the confirmation type, you can choose to use the {@link Communicator}s unpackPayload feature.
+     * Handle call result.
+     * <p>
+     * Hint: Use the id to identify the confirmation type, you can then choose to use the {@link Communicator}s unpackPayload method.
      *
      * @param id      unique id used to identify the original request.
      * @param payload raw payload.
      */
     void onCallResult(String id, String payload);
 
+    /**
+     * Handle call.
+     * <p>
+     * Hint: Use the action name to identify the request, you can then choose to use {@link Communicator}s unpackPayload method.
+     *
+     * @param id      unique id used to reply to server.
+     * @param action  action name used to identify the feature.
+     * @param payload raw payload.
+     */
     void onCall(String id, String action, String payload);
 
+    /**
+     * Handle call error.
+     * <p>
+     * Hint: Use the id to identify the original call. You can use {@link Communicator}s unpackPayload method.
+     *
+     * @param id        unique id used to identify the original request.
+     * @param payload   raw error payload.
+     */
     void onError(String id, String payload);
 
+    /**
+     * The connection was disconnected.
+     */
     void onDisconnected();
 
+    /**
+     * A connection was established.
+     */
     void onConnected();
 }

ocpp-common/src/main/java/eu/chargetime/ocpp/PropertyConstraintException.java

@@ -1,6 +1,6 @@
 package eu.chargetime.ocpp;
 
-/**
+/*
  ChargeTime.eu - Java-OCA-OCPP
  Copyright (C) 2015-2016 Thomas Volden <[email protected]>
 
@@ -26,25 +26,34 @@ of this software and associated documentation files (the "Software"), to deal
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
  */
+
+/**
+ * Exception used when validating fields.
+ */
 public class PropertyConstraintException extends Exception {
     private final String fieldKey;
     private final Object fieldValue;
+    private final String message;
 
     @Override
     public String getMessage() {
         return message;
     }
 
+    /**
+     * @return value of the failing field.
+     */
     public Object getFieldValue() {
         return fieldValue;
     }
 
+    /**
+     * @return name of the failing field.
+     */
     public String getFieldKey() {
         return fieldKey;
     }
 
-    private final String message;
-
     public PropertyConstraintException(String fieldKey, Object fieldValue) {
         this(fieldKey, fieldValue, null);
     }

ocpp-common/src/main/java/eu/chargetime/ocpp/Queue.java

@@ -5,7 +5,7 @@
 import java.util.HashMap;
 import java.util.UUID;
 
-/**
+/*
  ChargeTime.eu - Java-OCA-OCPP
  Copyright (C) 2015-2016 Thomas Volden <[email protected]>
 
@@ -31,6 +31,10 @@ of this software and associated documentation files (the "Software"), to deal
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
  */
+
+/**
+ * Class to store and restore requests based on a unique id.
+ */
 public class Queue
 {
     private HashMap<String, Request> requestQueue;
@@ -39,12 +43,26 @@ public Queue () {
         requestQueue = new HashMap<>();
     }
 
+    /**
+     * Store a {@link Request} and get a unique identifier to fetch it later on.
+     *
+     * @param request the {@link Request}.
+     * @return a unique identifier used to fetch the request.
+     */
     public String store(Request request) {
         String ticket = UUID.randomUUID().toString();
         requestQueue.put(ticket, request);
         return ticket;
     }
 
+    /**
+     * Restore a {@link Request} using a unique identifier.
+     * The identifier can only be used once.
+     * If no Request was found, null is returned.
+     *
+     * @param ticket    unique identifier returned when {@link Request} was initially stored.
+     * @return the stored {@link Request}
+     */
     public Request restoreRequest(String ticket) {
         Request request = null;
         try {

ocpp-common/src/main/java/eu/chargetime/ocpp/Session.java

@@ -6,7 +6,7 @@
 
 import java.util.concurrent.CompletableFuture;
 
-/**
+/*
  ChargeTime.eu - Java-OCA-OCPP
  Copyright (C) 2015-2016 Thomas Volden <[email protected]>
 
@@ -32,38 +32,73 @@ of this software and associated documentation files (the "Software"), to deal
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
  */
+
+/**
+ * Unites outgoing {@link Request} with incoming {@link Confirmation}s or errors.
+ * Catches errors and responds with error messages.
+ */
 public class Session {
 
     private Communicator communicator;
     private Queue queue;
     private SessionEvents events;
 
+    /**
+     * Handles required injections.
+     *
+     * @param communicator send and receive messages.
+     * @param queue        store and restore requests based on unique ids.
+     */
     public Session(Communicator communicator, Queue queue) {
         this.communicator = communicator;
         this.queue = queue;
     }
 
+    /**
+     * Send a {@link Request}.
+     *
+     * @param action    action name to identify the feature.
+     * @param payload   the {@link Request} payload to send
+     * @return unique identification to identify the request.
+     */
     public String sendRequest(String action, Request payload) {
         String uuid = queue.store(payload);
         communicator.sendCall(uuid, action, payload);
         return uuid;
     }
 
+    /**
+     * Send a {@link Confirmation} to a {@link Request}
+     *
+     * @param uniqueId      the unique identification the receiver expects.
+     * @param confirmation  the {@link Confirmation} payload to send.
+     */
     public void sendConfirmation(String uniqueId, Confirmation confirmation) {
         communicator.sendCallResult(uniqueId, confirmation);
     }
 
-    private Class<? extends Confirmation> getConfirmationType(String uniqueId) {
+    private Class<? extends Confirmation> getConfirmationType(String uniqueId) throws UnsupportedFeatureException {
         Request request = queue.restoreRequest(uniqueId);
         Feature feature = events.findFeatureByRequest(request);
+        if (feature == null)
+            throw new UnsupportedFeatureException();
         return feature.getConfirmationType();
     }
 
+    /**
+     * Connect to a specific uri, provided a call back handler for connection related events.
+     *
+     * @param uri             url and port of the remote system.
+     * @param eventHandler    call back handler for connection related events.
+     */
     public void open(String uri, SessionEvents eventHandler) {
         this.events = eventHandler;
         communicator.connect(uri, new CommunicatorEventHandler());
     }
 
+    /**
+     * Close down the connection.
+     */
     public void close() {
         communicator.disconnect();
     }
@@ -83,6 +118,9 @@ public void onCallResult(String id, String payload) {
                 String message = "Field %s violates constraints with value: \"%s\". %s";
                 communicator.sendCallError(id, "TypeConstraintViolation", String.format(message, ex.getFieldKey(), ex.getFieldValue(), ex.getMessage()));
                 ex.printStackTrace();
+            } catch (UnsupportedFeatureException ex) {
+                communicator.sendCallError(id, "InternalError", "An internal error occurred and the receiver was not able to process the requested Action successfully");
+                ex.printStackTrace();
             } catch (Exception ex) {
                 communicator.sendCallError(id, "FormationViolation", "Unable to process action");
                 ex.printStackTrace();
@@ -123,13 +161,19 @@ public void onCall(String id, String action, String payload) {
         }
 
         @Override
-        public void onError(String id, String payload) { }
+        public void onError(String id, String payload) {
+            events.handleError(id);
+        }
 
         @Override
-        public void onDisconnected() { }
+        public void onDisconnected() {
+            events.handleConnectionClosed();
+        }
 
         @Override
-        public void onConnected() { }
+        public void onConnected() {
+            events.handleConnectionOpened();
+        }
 
         private CompletableFuture<Confirmation> handleIncomingRequest(Request request) {
             CompletableFuture<Confirmation> promise = new CompletableFuture<>();