Getting started with SwaggerSocket and Jersey

Getting started with SwaggerSocket and Jersey

The following dependencies are required to build a SwaggerSocket application (it is recommended to use Maven or SBT)

     <!-- Server side -->
     <dependency>
         <groupId>com.wordnik</groupId>
         <artifactId>swaggersocket-server</artifactId>
         <version>2.0.1</version>
      </dependency>

     <!-- Client side using jquery.swaggersocket.js -->
     <dependency>
         <groupId>com.wordnik</groupId>
         <artifactId>swaggersocket.jquery</artifactId>
         <version>2.0.1</version>
         <type>war</type>
      </dependency>

     <!-- Client side using swaggersocket.js -->
     <dependency>
         <groupId>com.wordnik</groupId>
         <artifactId>swaggersocket.js</artifactId>
         <version>2.0.1</version>
         <type>war</type>
      </dependency>

Next is to add, in your web.xml, the following

    <servlet>
        <description>SwaggerSocketServlet</description>
        <servlet-name>SwaggerSocketServlet</servlet-name>
        <servlet-class>com.wordnik.swaggersocket.server.SwaggerSocketServlet</servlet-class>
        <load-on-startup>0</load-on-startup>
    </servlet>

This configuration is required and will enable the SwaggerSocket Protocol for any existing REST application that was written using the Jersey Framework. It is important to note that any existing application will work as is, without any modifications. A REST resource usually looks like:

  1  // The Java or Scala class will be hosted at the URI path "/helloworld"
  2  @Path("/helloworld")
  3  class HelloWorld {
  4
  5  @Path("/sayHello")
  6  @GET
  7  def get(): String = {
  8     "Swagger Socket Hello World"
  9  }

Invoking that resource using the HTTP protocol would normally consist of doing

> curl http://127.0.0.1:8080/helloword/sayHello

or if you are using Javascript

  1  xmlHttp = new XMLHttpRequest(); 
  2  xmlHttp.onreadystatechange = // a Function to print the response;
  3  xmlHttp.open( "GET", "127.0.0.1:8080/helloword/sayHello", true );
  4  xmlHttp.send( null );

or using JQuery

  1  $.get("127.0.0.1:8080/helloword/sayHello",
  2    function(data) {
  3       // print the response
  4    }
  5  );

With SwaggerSocket.js, you open a SwaggerSocket connection and once the server accepted the handshake, you create a Request and send it.

  1 new jQuery.swaggersocket.SwaggerSocket()
  2         .open("http://127.0.0.1:8080/helloworld",
  3            function(swaggerSocket, r) {
  4
  5                 var ss = new jQuery.swaggersocket.SwaggerSocketListener();
  6                 ss.onResponse = function(r) {
  7                     // print the response
  8                 };
  9
 10                 var request = new jQuery.swaggersocket.Request()
 11                         .method("GET")
 12                         .path('/sayHello')
 13                         .listener(ss);
 14
 15                 swaggerSocket.send(request);
 16             } 
 17         }
 18  ); 

The difference between the HTTP protocol and the SwaggerSocket protocol is that under the hood, SwaggerSocket uses the websocket protocol for communicating with the server. With HTTP, sending two requests would consist of doing something like:

  1  $.get("127.0.0.1:8080/helloword/sayHello",
  2    function(data) {
  3       // print the response
  4    }
  5  );
  6  $.get("127.0.0.1:8080/helloword/sayHello",
  7    function(data) {
  8       // print the response
  9    }
 10  );

With SwaggerSocket, you can do

  1 new jQuery.swaggersocket.SwaggerSocket()
  2         .open("http://127.0.0.1:8080/hellworld",
  3            function(swaggerSocket, r) {
  4
  5                 var ss = new jQuery.swaggersocket.SwaggerSocketListener();
  6                 ss.onResponse = function(r) {
  7                     // print the response
  8                 };
  9
 10                 var request = new jQuery.swaggersocket.Request()
 11                         .method("GET")
 12                         .path('/sayHello')
 13                         .listener(ss);
 14
 15                 swaggerSocket.send(request).send(request);
 16             } 
 17         }
 18  );

e.g invoke the send method twice. But a better way would consist of using an array to batch requests

  1 new jQuery.swaggersocket.SwaggerSocket()
  2         .open("http://127.0.0.1:8080/hellworld",
  3            function(swaggerSocket, r) {
  4
  5                 var ss = new jQuery.swaggersocket.SwaggerSocketListener();
  6                 ss.onResponse = function(r) {
  7                     // print the response
  8                 };
  9                 var requests = new Array();
 10                 request[0] = new jQuery.swaggersocket.Request()
 11                         .method("GET")
 12                         .path('/sayhello')
 13                         .listener(ss);
 14                 request[1] = request[0];
 15
 16                 swaggerSocket.send(requests);
 16             } 
 18         }
 19  );

This time the two requests will be sent simultaneously and on the server side processed asynchronously.

You can also use our SwaggerSocket Scala Client to invoke REST resources. As simple as

  1  val ss = SwaggerSocket().open("http://127.0.0.1:8080/helloworld")
  2  ss.send(new Request.Builder()
  3   .path("/sayHello")
  4   .build(), new SwaggerSocketListener() {
  5  	override def message(r: Request, s: Response) {
  6        // print the response using response.getData()
  7     }
  8   })  

That's all! You can browse the code here or download the entire sample as distribution.zip