From 1c4ee71f6c67b45ff545e7279cfa634de06d73fa Mon Sep 17 00:00:00 2001 From: fmoga Date: Mon, 25 Jul 2011 16:28:59 +0000 Subject: 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 --- .../binding/websocket/WebsocketBindingFactory.java | 2 +- .../sca/binding/websocket/runtime/JSONUtil.java | 33 ++++++++-------------- .../websocket/runtime/JavascriptGenerator.java | 14 +++++++++ .../runtime/JavascriptResourceServlet.java | 6 ++++ .../websocket/runtime/TuscanyWebsocket.java | 6 ++++ .../runtime/WebsocketBindingCallback.java | 3 ++ .../runtime/WebsocketBindingDispatcher.java | 5 +++- .../websocket/runtime/WebsocketBindingMessage.java | 3 ++ .../runtime/WebsocketBindingProviderFactory.java | 3 ++ .../runtime/WebsocketCallbackInvoker.java | 4 +++ .../runtime/WebsocketConnectionManager.java | 5 ++++ .../runtime/WebsocketReferenceBindingProvider.java | 6 ++++ .../binding/websocket/runtime/WebsocketServer.java | 4 +++ .../runtime/WebsocketServiceBindingProvider.java | 4 +++ .../websocket/runtime/WebsocketServiceInvoker.java | 4 +++ .../binding/websocket/runtime/WebsocketStatus.java | 4 +++ 16 files changed, 83 insertions(+), 23 deletions(-) (limited to 'sca-java-2.x/contrib/modules/binding-websocket/src/main/java') 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 objects = new ArrayList(); 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 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 invokers = new HashMap(); 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 { 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 activeConnections = new ConcurrentHashMap(); 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 } -- cgit v1.2.3