Improve source code documentation on the websocket binding.

git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@1150769 13f79535-47bb-0310-9956-ffa450edef68

16 files changed, 83 insertions, 23 deletions

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/WebsocketBindingFactory.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/WebsocketBindingFactory.java
index 52147b1fdb..1357bb5a7c 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/WebsocketBindingFactory.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/WebsocketBindingFactory.java
@@ -20,7 +20,7 @@
 package org.apache.tuscany.sca.binding.websocket;

 

 /**

- * Factory implementation to create Websocket Models

+ * Factory implementation to create Websocket models.

  */

 public class WebsocketBindingFactory {

 

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JSONUtil.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JSONUtil.java
index 30ad5a3ffe..80cbf6a6d9 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JSONUtil.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JSONUtil.java
@@ -27,32 +27,27 @@ import org.apache.tuscany.sca.interfacedef.Operation;
 import com.google.gson.Gson;
 
 /**
- * Helper class to facilitate JSON convertions.
+ * Utility class to handle JSON convertions.
  */
 public class JSONUtil {
 
     private static Gson gson = new Gson();
 
-    public static String encodeMessage(WebsocketBindingMessage request) {
-        return gson.toJson(request);
+    public static String encodeMessage(WebsocketBindingMessage message) {
+        return gson.toJson(message);
     }
 
-    public static WebsocketBindingMessage decodeMessage(String jsonRequest) {
-        return gson.fromJson(jsonRequest, WebsocketBindingMessage.class);
+    public static WebsocketBindingMessage decodeMessage(String jsonMessage) {
+        return gson.fromJson(jsonMessage, WebsocketBindingMessage.class);
     }
 
     public static String encodePayload(Object payload) {
         return gson.toJson(payload);
     }
-    
+
     /**
-     * Convert request parameters from JSON to operation parameter types.
-     * 
-     * @param jsonData
-     *            parameters in JSON array format
-     * @param operation
-     *            the operation to invoke
-     * @return an array of objects
+     * Convert opeartion parameters from JSON to the appropriate parameter
+     * types.
      */
     public static Object[] decodePayloadForOperation(String jsonData, Operation operation) {
         Object[] args = new Object[operation.getInputType().getLogical().size()];
@@ -66,14 +61,10 @@ public class JSONUtil {
     }
 
     /**
-     * Split the JSON array containing the arguments for the method call in
-     * order to avoid converting JSON to Object[]. Converting each object
-     * separately to it's corresponding type avoids type mismatch problems at
-     * service invocation.
-     * 
-     * @param jsonArray
-     *            the JSON array
-     * @return an array of JSON formatted strings
+     * Split the JSON array containing the arguments for the opeartion in order
+     * to avoid converting JSON to Object[]. Converting each object separately
+     * to it's corresponding data type avoids type mismatch problems at service
+     * invocation.
      */
     private static String[] parseArray(String jsonArray) {
         List<String> objects = new ArrayList<String>();
diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JavascriptGenerator.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JavascriptGenerator.java
index 04faf0113d..21b953151b 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JavascriptGenerator.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JavascriptGenerator.java
@@ -42,12 +42,20 @@ import java.util.List;
 

 import org.apache.tuscany.sca.interfacedef.Operation;

 

+/**

+ * Generates javascript service proxies using the websocket API. This enables

+ * simulating SCA on the client side javascript. This is a stateful singleton.

+ */

 public class JavascriptGenerator {

 

     private final static String CONTEXT = "this.WebsocketComponentContext";

     private static final String LF = "\n";

     private static StringBuilder builder = new StringBuilder();

 

+    /**

+     * Generate javascript code for one service and all it's operations. Add

+     * this to the state of the generator.

+     */

     public static void generateServiceProxy(String component, String service, List<Operation> operations, int port) {

         if (builder.length() == 0) {

             builder.append(CONTEXT).append("={};").append(LF);

@@ -85,10 +93,16 @@ public class JavascriptGenerator {
         return content;

     }

 

+    /**

+     * Get the state of the generator.

+     */

     public static String getServiceProxies() {

         return builder.toString();

     }

 

+    /**

+     * Reset the state of the generator.

+     */

     public static void clear() {

         builder.setLength(0);

     }

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JavascriptResourceServlet.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JavascriptResourceServlet.java
index 800b42b098..50d68a19bc 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JavascriptResourceServlet.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/JavascriptResourceServlet.java
@@ -49,6 +49,9 @@ import javax.servlet.http.HttpServlet;
 import javax.servlet.http.HttpServletRequest;

 import javax.servlet.http.HttpServletResponse;

 

+/**

+ * This servlet serves the generated javascript service proxies.

+ */

 public class JavascriptResourceServlet extends HttpServlet {

 

     private static final String WEBSOCKET_TOOLKIT_PATH = "js/TuscanyWebsocketToolkit.js";

@@ -76,6 +79,9 @@ public class JavascriptResourceServlet extends HttpServlet {
         return websocketToolkit;

     }

 

+    /**

+     * Read a resource from the disk by relative path.

+     */

     private String getResource(String path) {

         InputStream is = getClass().getClassLoader().getResourceAsStream(path);

         BufferedReader r = new BufferedReader(new InputStreamReader(is));

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/TuscanyWebsocket.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/TuscanyWebsocket.java
index b32949d2f4..b71ca27543 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/TuscanyWebsocket.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/TuscanyWebsocket.java
@@ -24,6 +24,12 @@ import java.util.UUID;
 
 import org.eclipse.jetty.websocket.WebSocket;
 
+/**
+ * A websocket connection handling communication between one browser client and
+ * *all* websocket services hosted by a server. The connection is persisted as
+ * long as the client is connected and communication with all services is
+ * multiplexed via a single websocket connection.
+ */
 public class TuscanyWebsocket implements WebSocket, WebSocket.OnTextMessage {
 
     private String id;
diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingCallback.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingCallback.java
index 877eda4027..3ece55aa00 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingCallback.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingCallback.java
@@ -20,6 +20,9 @@ package org.apache.tuscany.sca.binding.websocket.runtime;
 
 import org.oasisopen.sca.annotation.Remotable;
 
+/**
+ * Interface describing the websocket binding callback to a browser client.
+ */
 @Remotable
 public interface WebsocketBindingCallback {
 
diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingDispatcher.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingDispatcher.java
index ec7b249999..eda78de98a 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingDispatcher.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingDispatcher.java
@@ -24,12 +24,15 @@ import java.util.Map;
 import org.apache.tuscany.sca.interfacedef.Operation;
 import org.apache.tuscany.sca.runtime.RuntimeEndpoint;
 
+/**
+ * A dispatcher stores all service invokers for a servers and is used to
+ * determine which one of them should be used when a request comes in.
+ */
 public class WebsocketBindingDispatcher {
 
     private Map<String, WebsocketServiceInvoker> invokers = new HashMap<String, WebsocketServiceInvoker>();
 
     public void addOperation(String uri, RuntimeEndpoint endpoint, Operation operation) {
-        System.out.println("Adding " + uri);
         invokers.put(uri, new WebsocketServiceInvoker(operation, endpoint));
     }
 
diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingMessage.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingMessage.java
index 1e7abb2aba..f7ea1d1620 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingMessage.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingMessage.java
@@ -18,6 +18,9 @@
  */
 package org.apache.tuscany.sca.binding.websocket.runtime;
 
+/**
+ * The websocket binding message structure.
+ */
 public class WebsocketBindingMessage {
 
     private String operation;
diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingProviderFactory.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingProviderFactory.java
index 1f750234ae..5c5f96bd76 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingProviderFactory.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketBindingProviderFactory.java
@@ -29,6 +29,9 @@ import org.apache.tuscany.sca.provider.ServiceBindingProvider;
 import org.apache.tuscany.sca.runtime.RuntimeEndpoint;

 import org.apache.tuscany.sca.runtime.RuntimeEndpointReference;

 

+/**

+ * Factory for reference and service binding providers.

+ */

 public class WebsocketBindingProviderFactory implements BindingProviderFactory<WebsocketBinding> {

 

     private ServletHost servletHost;

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketCallbackInvoker.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketCallbackInvoker.java
index 5edd4c9a2d..ebd7f13081 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketCallbackInvoker.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketCallbackInvoker.java
@@ -26,6 +26,10 @@ import org.apache.tuscany.sca.interfacedef.Operation;
 import org.apache.tuscany.sca.invocation.Invoker;

 import org.apache.tuscany.sca.invocation.Message;

 

+/**

+ * The callback invoker is used to send asynchronous responses back to the

+ * browser client.

+ */

 public class WebsocketCallbackInvoker implements Invoker {

 

     protected Operation operation;

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketConnectionManager.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketConnectionManager.java
index b22fcbe9e3..ba95d77b7f 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketConnectionManager.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketConnectionManager.java
@@ -22,6 +22,11 @@ package org.apache.tuscany.sca.binding.websocket.runtime;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
+/**
+ * The connection manager stores all active websocket connections in order to be
+ * able to retrieve the appropriate communication channel when an asynchronous
+ * response is sent.
+ */
 public class WebsocketConnectionManager {
 
     private static ConcurrentMap<String, TuscanyWebsocket> activeConnections = new ConcurrentHashMap<String, TuscanyWebsocket>();
diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketReferenceBindingProvider.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketReferenceBindingProvider.java
index c5df6363b9..dfd632d330 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketReferenceBindingProvider.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketReferenceBindingProvider.java
@@ -25,6 +25,12 @@ import org.apache.tuscany.sca.interfacedef.Operation;
 import org.apache.tuscany.sca.invocation.Invoker;

 import org.apache.tuscany.sca.provider.ReferenceBindingProvider;

 

+/**

+ * The reference binding provider is used to initiate the necessary

+ * infrastructure on the reference side. As the binding only supports browser

+ * clients, the reference binding provider is used as a factory for callback

+ * invokers.

+ */

 public class WebsocketReferenceBindingProvider implements ReferenceBindingProvider {

 

     private EndpointReference endpoint;

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServer.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServer.java
index b1b8251edb..cde86b0575 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServer.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServer.java
@@ -28,6 +28,10 @@ import org.eclipse.jetty.server.nio.SelectChannelConnector;
 import org.eclipse.jetty.websocket.WebSocket;
 import org.eclipse.jetty.websocket.WebSocketHandler;
 
+/**
+ * The websocket server is an embedded Jetty instance which will be started on
+ * the port specified in the component definition.
+ */
 public class WebsocketServer extends Server {
 
     private WebsocketBindingDispatcher dispatcher;
diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServiceBindingProvider.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServiceBindingProvider.java
index c98399c8e8..328ca1de41 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServiceBindingProvider.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServiceBindingProvider.java
@@ -29,6 +29,10 @@ import org.apache.tuscany.sca.interfacedef.Operation;
 import org.apache.tuscany.sca.provider.ServiceBindingProvider;

 import org.apache.tuscany.sca.runtime.RuntimeEndpoint;

 

+/**

+ * The service binding provider initiates the necessary infrastructure to expose

+ * services via websockets.

+ */

 public class WebsocketServiceBindingProvider implements ServiceBindingProvider {

 

     private static final int DEFAULT_PORT = 9000;

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServiceInvoker.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServiceInvoker.java
index ca859e38f4..6c7a25c59e 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServiceInvoker.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketServiceInvoker.java
@@ -49,6 +49,10 @@ import org.apache.tuscany.sca.interfacedef.Operation;
 import org.apache.tuscany.sca.invocation.Message;

 import org.apache.tuscany.sca.runtime.RuntimeEndpoint;

 

+/**

+ * The service invoker is used to call an operation implementation in a

+ * synchronous or asynchronous way.

+ */

 public class WebsocketServiceInvoker {

 

     protected Operation operation;

diff --git a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketStatus.java b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketStatus.java
index c96685cedb..bb89761459 100644
--- a/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketStatus.java
+++ b/sca-java-2.x/contrib/modules/binding-websocket/src/main/java/org/apache/tuscany/sca/binding/websocket/runtime/WebsocketStatus.java
@@ -1,5 +1,9 @@
 package org.apache.tuscany.sca.binding.websocket.runtime;
 
+/**
+ * The websocket status indicates the state of a websocket connection when a
+ * send operation is performed.
+ */
 public enum WebsocketStatus {
     OPEN, CLOSED
 }