+

Search Tips   |   Advanced Search

Use HTTP bindings in SCA applications

We can use an HTTP binding with a wire format of JSON-RPC in a Service Component Architecture (SCA) application to expose services to remote web browser clients. JSON-RPC is a remote procedure call (RPC) protocol encoded in the JavaScript Object Notation (JSON) format.

Use the HTTP binding to expose SCA services for consumption by remote web clients. This topic describes how to expose a Java implementation as a service to be consumed by a browser client using native Dojo interfaces and RPC libraries.

To use native SCA references in JavaScript code, see the topic on using Widget implementation in JavaScript with HTTP bindings.

  1. Configure the Java service in an SCA composite definition.

    Expose a Java service over the HTTP binding in the composite definition; for example: 

    <composite>
  <service name="EchoService" promote="EchoComponent">
    <interface.java interface="echo.Echo"/>
    <tuscany:binding.http uri="/EchoService"/>
      <tuscany:wireFormat.jsonrpc/>
    </tuscany:binding.http>
  </service>
   <component name="EchoComponent">
    <implementation.java class="echo.EchoComponentImpl"/>
  </component>
</composite>

    This example exposes the methods defined in the echo.Echo interface to web browser clients. The echo.EchoComponentImpl class implements the Echo interface and provides the implementation for the component. The service is exposed on the "/EchoService" relative uniform resource identifier (URI).

    The example HTTP binding URI, /EchoService, is a relative URI. To run applications that use an HTTP binding in product clusters, specify a relative URI. We cannot run applications in product clusters if the binding specifies an absolute URI, such as http://localhost:9080/newsService.

  2. Choose the serialization engine

    wireFormat.jsonrpc tells the binding to use the default IBM JSON RPCAdapter to serialize/deserialize the json data. Optionally, we can use Jackson to perform serialization/deserialization. To use Jackson, set the jvm custom property com.ibm.ws.soa.sca.json.serializer.jackson to true.

    The Jackson and RCPAdapter serializers have different performance characteristics that are dependent on a number of factors in the json payload. Try both to determine which works best for the payload.

  3. Access the service from a web browser.

    For example, to access the EchoService service, use the Dojo toolkit APIs in an HTML file or JSP file to access the service available at /EchoService: 

    <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Echo...</title>
<script type="text/javascript" src="./dojo/dojo.js"></script>
<script>
  dojo.require("dojo.io.script")
  dojo.require("dojo.rpc.RpcService")
  dojo.require("dojo.rpc.JsonService")
  dojo.require("dojo.rpc.JsonpService")
     function filladdr(){
    var nameElement=document.getElementById("name");
    var name=nameElement.value;
    var echo = new dojo.rpc.JsonService("/EchoService?smd");
    echo.echo(name).addCallback(fillmsg);
  }
     function fillmsg(result){
    var line=document.getElementById("line1");
    line.value=result;
  }
</script>
</head>
<body>
Enter a string: <input id="name" type="text">
<input type="submit" value="Echo String" onClick="filladdr()"><br>
<p>Echo </p><input id="line1" type="text" size="50"><br><br>
</body>
</html>

    The URI passed into the dojo.rpc.JsonService constructor "/EchoService?smd" contains the query string "smd" on the end of the URI specified in the <binding.http> definition in the composite. The query string "smd" on the end of the URI is required when using Dojo clients.


Results

The HTML output for the example output shows two text boxes and a "submit" button. When a user enters text in the first box and clicks the submit button, the following steps take place:

  1. The JavaScript code in the filladdr() method obtains the value that was entered in the first text box.

  2. The filladdr() method instantiates a dojo.rpc.JsonService object pointed to the URI "/EchoService?smd".

  3. The JavaScript code runs the "echo(String)" method on the JsonService object, causing a JSON-RPC request to be sent to "/EchoService?smd".

  4. The SCA run time handles the URI request by running the EchoComponentImpl.echo(String) method. The result is returned to the client as an HTTP response.

  5. The web client runs the designated callback method, "fillmsg(result)", with the value returned from the service.

  6. The JavaScript code in the fillmsg(result) method updates the second text box to contain the text returned from the service invocation.


What to do next

Consider the supported data types for the JSON conversion. Parameters for JSON-RPC requests are sent to the server in JSON format, and must be transformed by the SCA run time for use in the Java implementation. The response to the client is also in JSON format, so the SCA run time converts the value returned from the EchoComponentImpl.echo() method back into JSON. For example, echo("Testing...") might submit the following data to the server:

The Java method EchoComponentImpl.echo(String message) is invoked with the String parameter "Testing..." and returns the String object "echo: Testing...". The JSON response returned to the web client might look like:

types for JSON conversions. Conversion enables the Web
Data type
Primitive Type <==> JSON <==> Primitive Type
Array of Primitive Type <==> JSON <==> Array of Primitive Type
Java bean <==> JSON <==> Java bean
List <==> JSON <==> List
Map <==> JSON <==> Map
Set <==> JSON <==> Set


Subtopics


Related tasks

  • Use Widget implementation in JavaScript with Atom or HTTP bindings
  • Resolve SCA references
  • Route HTTP requests to an SCA service when using an external web server
  • Specify bindings in an SCA environment