You 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.
About this task
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.
Procedure
- 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. You cannot run applications in product clusters if
the binding specifies an absolute URI, such as http://localhost:9080/newsService.
- Access the service from a web browser.
For
example, to access the EchoService service, use the
Dojo toolkit application programming interfaces in an HTML file or
JavaServer Pages (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:
- The JavaScript code in the filladdr() method
obtains the value that was entered in the first text box.
- The filladdr() method
instantiates a dojo.rpc.JsonService
object pointed to the URI "/EchoService?smd".
- The
JavaScript code runs the "echo(String)" method
on the JsonService object, causing a JSON-RPC request to be sent to "/EchoService?smd".
- 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.
- The
web client runs the designated callback method, "fillmsg(result)",
with the value returned from the service.
- 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:
{"params":["Testing..."],"method":"echo","id":1}
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:
{"id":1,"result":"echo: Testing..."}
Table 1. Supported data
types for JSON conversions. Conversion enables the Web
client and Java implementation to use the data.
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 |