Add README files to present websocket samples. Add Jetty plugin to enable jetty:run.

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

7 files changed, 304 insertions, 2 deletions

diff --git a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/autocomplete-webapp/README b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/autocomplete-webapp/README
index 7e721af2aa..a0b90cdf2f 100644
--- a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/autocomplete-webapp/README
+++ b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/autocomplete-webapp/README
@@ -15,8 +15,10 @@ runtime will use port 9000 as a default.
 
 The websocket binding uses embedded Jetty instances as websocket servers. At the
 moment, Jetty 8.0.0-M3 is used which has support for the 00, 01, 06 and 07 
-versions of the websocket protocol drafts. You should check if the browser of
-your choice supports one of these protocol versions.
+versions of the websocket protocol drafts.
+
+IN ORDER TO RUN THIS SAMPLE SUCCESSFULLY PLEASE CHECK IF YOUR BROWSER SUPPORTS 
+THE ABOVE WEBSOCKET PROTOCOL VERSIONS AND THAT THE WEBSOCKET SUPPORT IS ENABLED.
 
 The websocket binding also features a javascript API to simulate SCA in the 
 browser. In order to use it, the following script has to be included in the
diff --git a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/chat-webapp/README b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/chat-webapp/README
new file mode 100644
index 0000000000..5a9381f980
--- /dev/null
+++ b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/chat-webapp/README
@@ -0,0 +1,88 @@
+Tuscany - Learning More - Binding Websocket - Chat Webapp
+-----------------------------------------------------------------
+
+This sample demonstrates how Tuscany can expose services via websockets as well
+as how to interact with them using Tuscany's javascript API. It also demonstrates
+how to push multiple responses from the server to the client for a single request
+using SCA callbacks.
+
+This project contains a service (ChatService) that handles chat operations like
+register and postMessage. Once a client is registered it will receive messages
+that are sent to the chat room.
+
+By adding <tuscany:binding.websocket port="8090"/> to a service definition, the 
+Tuscany runtime will start a websocket server listening for requests coming
+in for the exposed service at the specified port. If no port is specified, the
+runtime will use port 9000 as a default.  
+
+The websocket binding uses embedded Jetty instances as websocket servers. At the
+moment, Jetty 8.0.0-M3 is used which has support for the 00, 01, 06 and 07 
+versions of the websocket protocol drafts.
+
+IN ORDER TO RUN THIS SAMPLE SUCCESSFULLY PLEASE CHECK IF YOUR BROWSER SUPPORTS 
+THE ABOVE WEBSOCKET PROTOCOL VERSIONS AND THAT THE WEBSOCKET SUPPORT IS ENABLED.
+
+In order to enable callbacks to push multiple responses, you need to declare the 
+WebsocketBindingCallback in the service definition as follows:
+
+    <interface.java interface="sample.ChatService"
+                    callbackInterface="org.apache.tuscany.sca.binding.websocket.runtime.WebsocketBindingCallback" />
+    <tuscany:binding.websocket />
+    <callback>
+        <tuscany:binding.websocket />
+    </callback>
+    
+The callback object has methods that facilitate sending messages back to the 
+calling client. It can be injected in the service implementation using the @Callback
+annotation. However, the service implementation for this sample has the COMPOSITE
+scope so the callback reference has to be obtained from the ComponentContext.
+
+One requirement that service methods have to meet to enable multiple response 
+support is that they have to be annotated with @OneWay to enable non-blocking 
+support. Without it, methods are treated synchronously sending a single response
+which is the object returned by the method call.  
+
+The websocket binding also features a javascript API to simulate SCA in the 
+browser. In order to use it, the following script has to be included in the
+client page: 
+    <script type="text/javascript" 
+            src="org.apache.tuscany.sca.WebsocketComponentContext.js">
+    </script>
+	
+This will inject proxies for all services defined in the composite that are 
+using binding.websocket. All invocation and connection management is handled
+under the hood so in order to invoke a websocket service, the following should
+be called:
+	Tuscany.WebsocketComponentContext.<component name>.<service name>.<operation name>(<parameters>);
+
+Given the asynchornous nature of websockets, a function should be defined in
+order to handle responses received for a certain service operation. This should
+be done as follows:
+    Tuscany.WebsocketComponentContext.<component name>.<service name>.<operation name>.responseHandler = function(response) {
+        // handle response
+    };
+	
+Note that the data exchange is automatically handled by the binding, so parameters 
+will be mapped to the data types defined in the method definition. Also, the response 
+will have the same data type as the server side object used to wrap the response. 
+Objects are passed over the wire in JSON format.
+
+Another detail worth mentioning is that the binding will use a single persistent 
+websocket connection to handle communication between a browser client and all services 
+defined using binding.websocket on the same port. Requests and responses will get
+multiplexed via the same channel and get routed to the appropriate service 
+implementation, respectively javascript function.
+
+In order to run the sample, you can execute "mvn jetty:run" which will start a Jetty
+instance automatically or use "mvn package" and deploy the resulting war to the
+application server of your choice.
+
+Next, point your browser at 
+    http://localhost:8080/sample-binding-websocket-chat-webapp/
+	
+You can now chat using multiple tabs or browsers. You can see the persistent websocket 
+connection using the developer tools provided by your browser.
+
+The websocket binding is an experimental binding so community feedback is much 
+appreciated. Feel free to send comments or suggestions on the Apache Tuscany 
+dev mailing list (dev@tuscany.apache.org).
\ No newline at end of file
diff --git a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/chat-webapp/pom.xml b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/chat-webapp/pom.xml
index 03127731e9..ba8cc0c26f 100644
--- a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/chat-webapp/pom.xml
+++ b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/chat-webapp/pom.xml
@@ -54,5 +54,15 @@
 		</dependency>

 	</dependencies>

 	

+	<build>

+		<plugins>

+			<plugin>

+				<groupId>org.mortbay.jetty</groupId>

+				<artifactId>maven-jetty-plugin</artifactId>

+				<version>6.1.26</version>

+			</plugin>

+		</plugins>

+	</build>

+	

 </project>

 

diff --git a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/pubsub-webapp/README b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/pubsub-webapp/README
new file mode 100644
index 0000000000..1ec7d6b807
--- /dev/null
+++ b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/pubsub-webapp/README
@@ -0,0 +1,93 @@
+Tuscany - Learning More - Binding Websocket - PubSub Webapp
+-----------------------------------------------------------------
+
+This sample demonstrates how Tuscany can expose services via websockets as well
+as how to interact with them using Tuscany's javascript API. It also demonstrates
+how to push multiple responses from the server to the client for a single request
+using SCA callbacks.
+
+This project contains a component that registers browser clients' interest in a 
+certain event type. When an event of that type comes in, it notifies all registered
+clients. The event processor exposes a service via the websocket binding which 
+enables server push to clients. Note that Tuscany 2.x doesn't have any conversational
+support so this has to be handled at application level by passing ids back and forth
+between the client and the server. 
+
+By adding <tuscany:binding.websocket port="8090"/> to a service definition, the 
+Tuscany runtime will start a websocket server listening for requests coming
+in for the exposed service at the specified port. If no port is specified, the
+runtime will use port 9000 as a default.  
+
+The websocket binding uses embedded Jetty instances as websocket servers. At the
+moment, Jetty 8.0.0-M3 is used which has support for the 00, 01, 06 and 07 
+versions of the websocket protocol drafts.
+
+IN ORDER TO RUN THIS SAMPLE SUCCESSFULLY PLEASE CHECK IF YOUR BROWSER SUPPORTS 
+THE ABOVE WEBSOCKET PROTOCOL VERSIONS AND THAT THE WEBSOCKET SUPPORT IS ENABLED.
+
+In order to enable callbacks to push multiple responses, you need to declare the 
+WebsocketBindingCallback in the service definition as follows:
+
+    <interface.java interface="sample.ChatService"
+                    callbackInterface="org.apache.tuscany.sca.binding.websocket.runtime.WebsocketBindingCallback" />
+    <tuscany:binding.websocket />
+    <callback>
+        <tuscany:binding.websocket />
+    </callback>
+    
+The callback object has methods that facilitate sending messages back to the 
+calling client. It can be injected in the service implementation using the @Callback
+annotation. However, the service implementation for this sample has the COMPOSITE
+scope so the callback reference has to be obtained from the ComponentContext.
+
+One requirement that service methods have to meet to enable multiple response 
+support is that they have to be annotated with @OneWay to enable non-blocking 
+support. Without it, methods are treated synchronously sending a single response
+which is the object returned by the method call.  
+
+The websocket binding also features a javascript API to simulate SCA in the 
+browser. In order to use it, the following script has to be included in the
+client page: 
+    <script type="text/javascript" 
+            src="org.apache.tuscany.sca.WebsocketComponentContext.js">
+    </script>
+	
+This will inject proxies for all services defined in the composite that are 
+using binding.websocket. All invocation and connection management is handled
+under the hood so in order to invoke a websocket service, the following should
+be called:
+	Tuscany.WebsocketComponentContext.<component name>.<service name>.<operation name>(<parameters>);
+
+Given the asynchornous nature of websockets, a function should be defined in
+order to handle responses received for a certain service operation. This should
+be done as follows:
+    Tuscany.WebsocketComponentContext.<component name>.<service name>.<operation name>.responseHandler = function(response) {
+        // handle response
+    };
+	
+Note that the data exchange is automatically handled by the binding, so parameters 
+will be mapped to the data types defined in the method definition. Also, the response 
+will have the same data type as the server side object used to wrap the response. 
+Objects are passed over the wire in JSON format.
+
+Another detail worth mentioning is that the binding will use a single persistent 
+websocket connection to handle communication between a browser client and all services 
+defined using binding.websocket on the same port. Requests and responses will get
+multiplexed via the same channel and get routed to the appropriate service 
+implementation, respectively javascript function.
+
+In order to run the sample, you can execute "mvn jetty:run" which will start a Jetty
+instance automatically or use "mvn package" and deploy the resulting war to the
+application server of your choice.
+
+Next, point your browser at 
+    http://localhost:8080/sample-binding-websocket-chat-webapp/
+	
+You can now register or unregister for any of a number of events. When an event is fired
+on the server side, the browser client will receive a notification which will be displayed 
+in the page. You can see the persistent websocket connection using the developer tools 
+provided by your browser.
+
+The websocket binding is an experimental binding so community feedback is much 
+appreciated. Feel free to send comments or suggestions on the Apache Tuscany 
+dev mailing list (dev@tuscany.apache.org).
\ No newline at end of file
diff --git a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/pubsub-webapp/pom.xml b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/pubsub-webapp/pom.xml
index 294ff5fcad..00867bd6eb 100644
--- a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/pubsub-webapp/pom.xml
+++ b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/pubsub-webapp/pom.xml
@@ -54,5 +54,15 @@
 		</dependency>

 	</dependencies>

 	

+	<build>

+		<plugins>

+			<plugin>

+				<groupId>org.mortbay.jetty</groupId>

+				<artifactId>maven-jetty-plugin</artifactId>

+				<version>6.1.26</version>

+			</plugin>

+		</plugins>

+	</build>

+	

 </project>

 

diff --git a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/weather-webapp/README b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/weather-webapp/README
new file mode 100644
index 0000000000..eb195bc4dc
--- /dev/null
+++ b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/weather-webapp/README
@@ -0,0 +1,89 @@
+Tuscany - Learning More - Binding Websocket - Weather Monitor Webapp
+-----------------------------------------------------------------
+
+This sample demonstrates how Tuscany can expose services via websockets as well
+as how to interact with them using Tuscany's javascript API. It also demonstrates
+how to push multiple responses for a single request using SCA callbacks.
+
+This project contains multiple services that once called will push notifications
+to the client regarding certain weather parameters according to the location of
+the user. Of course, the service implementation is a mock that generates random
+numbers at a fixed interval of time as weather parameters.
+
+By adding <tuscany:binding.websocket port="8090"/> to a service definition, the 
+Tuscany runtime will start a websocket server listening for requests coming
+in for the exposed service at the specified port. If no port is specified, the
+runtime will use port 9000 as a default.  
+
+The websocket binding uses embedded Jetty instances as websocket servers. At the
+moment, Jetty 8.0.0-M3 is used which has support for the 00, 01, 06 and 07 
+versions of the websocket protocol drafts. 
+
+IN ORDER TO RUN THIS SAMPLE SUCCESSFULLY PLEASE CHECK IF YOUR BROWSER SUPPORTS 
+THE ABOVE WEBSOCKET PROTOCOL VERSIONS AND THAT THE WEBSOCKET SUPPORT IS ENABLED.
+
+In order to enable callbacks to push multiple responses, you need to declare the 
+WebsocketBindingCallback in the service definition as follows:
+
+    <interface.java interface="sample.ChatService"
+                    callbackInterface="org.apache.tuscany.sca.binding.websocket.runtime.WebsocketBindingCallback" />
+    <tuscany:binding.websocket />
+    <callback>
+        <tuscany:binding.websocket />
+    </callback>
+    
+The callback object has methods that facilitate sending messages back to the 
+calling client. It can be injected in the service implementation using the @Callback
+annotation.
+
+One requirement that service methods have to meet to enable multiple response 
+support is that they have to be annotated with @OneWay to enable non-blocking 
+support. Without it, methods are treated synchronously sending a single response
+which is the object returned by the method call.  
+
+The websocket binding also features a javascript API to simulate SCA in the 
+browser. In order to use it, the following script has to be included in the
+client page: 
+    <script type="text/javascript" 
+            src="org.apache.tuscany.sca.WebsocketComponentContext.js">
+    </script>
+	
+This will inject proxies for all services defined in the composite that are 
+using binding.websocket. All invocation and connection management is handled
+under the hood so in order to invoke a websocket service, the following should
+be called:
+	Tuscany.WebsocketComponentContext.<component name>.<service name>.<operation name>(<parameters>);
+
+Given the asynchornous nature of websockets, a function should be defined in
+order to handle responses received for a certain service operation. This should
+be done as follows:
+    Tuscany.WebsocketComponentContext.<component name>.<service name>.<operation name>.responseHandler = function(response) {
+        // handle response
+    };
+	
+Note that the data exchange is automatically handled by the binding, so parameters 
+will be mapped to the data types defined in the method definition. Also, the response 
+will have the same data type as the server side object used to wrap the response. 
+Objects are passed over the wire in JSON format.
+
+Another detail worth mentioning is that the binding will use a single persistent 
+websocket connection to handle communication between a browser client and all services 
+defined using binding.websocket on the same port. Requests and responses will get
+multiplexed via the same channel and get routed to the appropriate service 
+implementation, respectively javascript function.
+
+In order to run the sample, you can execute "mvn jetty:run" which will start a Jetty
+instance automatically or use "mvn package" and deploy the resulting war to the
+application server of your choice.
+
+Next, point your browser at 
+    http://localhost:8080/sample-binding-websocket-weather-webapp/
+	
+You can now set a location and register for various weather parameters. Notifications 
+will be pushed to the browser when weather parameters change. You can see the persistent 
+websocket connection handling all the communication using the developer tools provided 
+by your browser.
+
+The websocket binding is an experimental binding so community feedback is much 
+appreciated. Feel free to send comments or suggestions on the Apache Tuscany 
+dev mailing list (dev@tuscany.apache.org).
\ No newline at end of file
diff --git a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/weather-webapp/pom.xml b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/weather-webapp/pom.xml
index dba90f8a14..2a75266934 100644
--- a/sca-java-2.x/contrib/samples/learning-more/binding-websocket/weather-webapp/pom.xml
+++ b/sca-java-2.x/contrib/samples/learning-more/binding-websocket/weather-webapp/pom.xml
@@ -47,5 +47,15 @@
 		</dependency>

 	</dependencies>

 	

+	<build>

+		<plugins>

+			<plugin>

+				<groupId>org.mortbay.jetty</groupId>

+				<artifactId>maven-jetty-plugin</artifactId>

+				<version>6.1.26</version>

+			</plugin>

+		</plugins>

+	</build>

+	

 </project>