Started adding java docs.

Author: TVolden

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

@@ -8,8 +8,7 @@
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.concurrent.CompletableFuture;
-
-/**
+/*
  ChargeTime.eu - Java-OCA-OCPP
  Copyright (C) 2015-2016 Thomas Volden <[email protected]>
 
@@ -35,24 +34,51 @@ 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.
  */
+
+/**
+ * Abstract class.
+ * Handles basic client logic:
+ * Hold s list of supported features.
+ * Keeps track of outgoing request.
+ * Calls back when a confirmation is received.
+ * <p>
+ * Must be overloaded in order to support specific protocols and formats.
+ */
 public abstract class Client
 {
     private HashMap<String, CompletableFuture<Confirmation>> promises;
     private ArrayList<Feature> featureList;
     private Session session;
 
+    /**
+     * Constructor
+     *
+     * @param   session     Inject session object
+     * @see                 Session
+     */
     public Client(Session session) {
         this.promises = new HashMap<>();
         this.featureList = new ArrayList<>();
         this.session = session;
     }
 
+    /**
+     * Add {@link Profile} to support a group of features.
+     *
+     * @param   profile     supported feature {@link Profile}
+     * @see                 Profile
+     */
     public void addFeatureProfile(Profile profile) {
         Feature[] features = profile.getFeatureList();
         for (Feature feature: features)
             featureList.add(feature);
     }
 
+    /**
+     * Connect to server
+     *
+     * @param   uri     url and port of the server
+     */
     public void connect(String uri)
     {
         session.open(uri, new SessionEvents() {
@@ -79,6 +105,9 @@ public Confirmation handleRequest(Request request) {
         });
     }
 
+    /**
+     * Disconnect from server
+     */
     public void disconnect()
     {
         try {
@@ -88,6 +117,18 @@ public void disconnect()
         }
     }
 
+    /**
+     * Search for supported features added with the addProfile.
+     * If no supported feature is found, null is returned
+     *
+     * Can take multiple inputs:
+     * {@link String}, search for the action name of the feature.
+     * {@link Request}/{@link Confirmation}, search for a feature that matches.
+     * Anything else will return null.
+     *
+     * @param   needle  Object supports {@link String}, {@link Request} or {@link Confirmation}
+     * @return Instance of the supported Feature
+     */
     private Feature findFeature(Object needle) {
         Feature output = null;
 
@@ -101,6 +142,18 @@ private Feature findFeature(Object needle) {
         return output;
     }
 
+    /**
+     * Tries to match {@link Feature} with an {@link Object}.
+     * Different outcome based on the type:
+     * {@link String}, matches the action name of the feature.
+     * {@link Request}, matches the request type of the feature.
+     * {@link Confirmation}, matches the confirmation type of the feature.
+     * Other wise returns false.
+     *
+     * @param   feature to match
+     * @param   object  to match with, supports {@link String}, {@link Request} or {@link Confirmation}
+     * @return true if the {@link Feature} matches the {@link Object}
+     */
     private boolean featureContains(Feature feature, Object object) {
         boolean contains = false;
         contains |= object instanceof String && feature.getAction().equals(object);
@@ -109,6 +162,15 @@ private boolean featureContains(Feature feature, Object object) {
         return contains;
     }
 
+    /**
+     * Send a {@link Request} to the server.
+     * Can only send {@link Request} that the client supports, see {@link #addFeatureProfile(Profile)}
+     *
+     * @param   request                         outgoing request
+     * @return call back object, will be fulfilled with confirmation when received
+     * @throws UnsupportedFeatureException     trying to send a request from an unsupported feature
+     * @see                                     CompletableFuture
+     */
     public CompletableFuture<Confirmation> send(Request request) throws UnsupportedFeatureException {
         Feature feature = findFeature(request);
         if (feature == null)
@@ -119,6 +181,12 @@ public CompletableFuture<Confirmation> send(Request request) throws UnsupportedF
         return promise;
     }
 
+    /**
+     * Creates call back {@link CompletableFuture} for later use
+     *
+     * @param   uniqueId    identification for the {@link Request}
+     * @return call back {@link CompletableFuture}
+     */
     private CompletableFuture<Confirmation> createPromise(String uniqueId) {
         CompletableFuture<Confirmation> promise = new CompletableFuture<>();
         promises.put(uniqueId, promise);

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

@@ -2,7 +2,7 @@
 
 import eu.chargetime.ocpp.model.*;
 
-/**
+/*
  ChargeTime.eu - Java-OCA-OCPP
  Copyright (C) 2015-2016 Thomas Volden <[email protected]>
 
@@ -28,22 +28,91 @@ 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.
  */
+
+/**
+ * Abstract class.
+ * Handles basic communication:
+ * Pack and send messages.
+ * Receive and unpack messages.
+ * <p>
+ * Requires a {@link Transmitter} to send and receive messages.
+ * Must be overloaded to implement a specific format.
+ */
 public abstract class Communicator {
     protected Transmitter transmitter;
 
+    /**
+     * Convert a formatted string into a {@link Request}/{@link Confirmation}.
+     * This is useful for call results, where the  confirmation type isn't given.
+     *
+     * @param   payload     the raw formatted payload.
+     * @param   type        the expected return type.
+     * @return the unpacked payload.
+     * @throws Exception   error occurred while converting.
+     */
     public abstract <T> T unpackPayload(String payload, Class<T> type) throws Exception;
+
+    /**
+     * Convert a {@link Request}/{@link Confirmation} into a formatted string.
+     *
+     * @param   payload     the payload model.
+     * @return the payload in the form of a formatted string.
+     */
     public abstract String packPayload(Object payload);
+
+    /**
+     * Create a call result envelope to transmit to the server.
+     *
+     * @param   uniqueId    the id the server expects.
+     * @param   payload     packed payload.
+     * @return a fully packed message ready to send.
+     */
     protected abstract String makeCallResult(String uniqueId, String payload);
+
+    /**
+     * Create a call envelope to transmit to the server.
+     *
+     * @param   uniqueId    the id the server 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);
-    protected abstract String makeCallError(String uniqueId, String errorCode, String errorDescription);
 
+    /**
+     * Create a call error envelope to transmit to the server.
+     *
+     * @param   uniqueId            the id the server expects.
+     * @param   errorCode           an OCPP error code.
+     * @param   errorDescription    an associated error description.
+     * @return a fully packed message ready to send.
+     */
+    protected abstract String makeCallError(String uniqueId, String errorCode, String errorDescription);
 
+    /**
+     * 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.
+     *
+     * @param   message raw message from server
+     * @return CallMessage or {@link CallResultMessage}
+     */
     protected abstract Message parse(String message);
 
+    /**
+     * Constructore
+     *
+     * @param   transmitter Injected {@link Transmitter}
+     */
     public Communicator(Transmitter transmitter) {
         this.transmitter = transmitter;
     }
 
+    /**
+     * Use the injected {@link Transmitter} to connect to server.
+     * @param   uri     the url and port of the server.
+     * @param   events  handler for call back events.
+     */
     public void connect(String uri, CommunicatorEvents events) {
         transmitter.connect(uri, new TransmitterEvents() {
             @Override
@@ -70,18 +139,41 @@ public void disconnected() {
         });
     }
 
+    /**
+     * Send a new {@link Request} to the server.
+     *
+     * @param   uniqueId    the id the server should use to reply.
+     * @param   action      action name of the {@link eu.chargetime.ocpp.feature.Feature}.
+     * @param   request     the outgoing {@link Request}
+     */
     public void sendCall(String uniqueId, String action, Request request) {
         transmitter.send(makeCall(uniqueId, action, packPayload(request)));
     }
 
+    /**
+     * Send a {@link Confirmation} reply to a server {@link Request}.
+     *
+     * @param   uniqueId        the id the server 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.
+     *
+     * @param   uniqueId            the id the server expects a response to.
+     * @param   errorCode           an OCPP error Code
+     * @param   errorDescription    a associated error description.
+     */
     public void sendCallError(String uniqueId, String errorCode, String errorDescription) {
         transmitter.send(makeCallError(uniqueId, errorCode, errorDescription));
     }
 
+    /**
+     * Disconnect from the server. Uses the {@link Transmitter}.
+     */
     public void disconnect() {
         transmitter.disconnect();
     }

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

@@ -1,6 +1,6 @@
 package eu.chargetime.ocpp;
 
-/**
+/*
  ChargeTime.eu - Java-OCA-OCPP
  Copyright (C) 2015-2016 Thomas Volden <[email protected]>
 
@@ -26,10 +26,25 @@ 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.
  */
+
+/**
+ * Call back handler for communicator events.
+ */
 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.
+     *
+     * @param id      unique id used to identify the original request.
+     * @param payload raw payload.
+     */
     void onCallResult(String id, String payload);
+
     void onCall(String id, String action, String payload);
+
     void onError(String id, String payload);
+
     void onDisconnected();
+
     void onConnected();
 }