SCA Java binding.jsonrpc (TUSCANY) edited by Luciano Resende
Page:
http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+binding.jsonrpc
Changes:
http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=54462&originalVersion=19&revisedVersion=20
Content:
---------------------------------------------------------------------
{section:border=false}
{column:width=15%}
{include: SCA Java Subproject Menu}
{include: Java SCA Menu New}
{column}
{column:width=85%}
h3. <binding.jsonrpc>
Tuscany supports [JSON-RPC|http://json-rpc.org/] as a protcol for use with SCA
services by using the <binding.jsonrpc> SCDL extension. This enables remote web
browser clients to easily make RPC style calls to server-side SCA components.
h3.Using the Tuscany JSON-RPC binding
You could use this binding without any configuration, or by providing a
specific service URI.
To include it on a SCA service choose one of the SCDL examples below :
{code}
<binding.jsonrpc/>
{code}
{code}
<binding.jsonrpc uri="http://localhost:8080/store/catalog"/>
{code}
h3.Consuming JSON-RPC services on the client application
Any JSON-RPC client may be used to access SCA services which use
<binding.jsonrpc>, below we are going to describe different ways you could
consume the Tuscany JSON-RPC services in your client application.
h4. Utilizing Tuscany Implementation.widget
When your web client application is defined as an SCA component utilizing
[Tuscany Widgets|SCA+Java+implementation.widget], a JavaScript is generated
which may be included within an HTML document to properly inject services
references to SCA references defined on the same HTML document.
This script is used by simply including the following tag within the HTML page :
{code}
<script type="text/javascript" src="html-page-name.js" />
{code}
This initializes the proxys for the SCA services which can then be injected
into SCA references to make requests to the server-side components. For
example, if there was a service named "myService" which had operations
"aOnewayRequest" and "anRpcRequest" the scripts in the HTML page could now
invoke these operations with the following:
{code}
//@Reference
var myService = new Reference("myService");
myService.aOnewayRequest(args);
{code}
or
{code}
//@Reference
var myService = new JSONRpcClient("myService");
myService.anRpcRequest(args, responseFunction);
{code}
Also see [Tuscany Widgets|SCA+Java+implementation.widget] for more details.
h4. Utilizing a JavaScript Client Proxy
To simplify the task for web browsers developers Tuscany provides a
'binding-jsonrpc.js" JavaScript client proxy code that can be included in your
application.
After copying the script to your application, it can be used bu simply
including the following tag within the HTML page :
{code}
<script type="text/javascript" src="binding-jsonrpc.js" />
{code}
This initializes the proxys for the SCA services which can then be used make
requests to the server-side components. Based on the scenario described above,
below are the to invoke these operations.
{code}
var myService = new JSONRpcClient("Catalog").service;
myService.aOnewayRequest(args);
{code}
or
{code}
var myService = new JSONRpcClient("Catalog").service;
myService.anRpcRequest(args, responseFunction);
{code}
h4. Handling JSON-RPC Response with callbacks
In that example 'responseFunction' is the name of a function which is called to
process the response and which gets called asynchronously on another thread
when the response is avaialble. RPC requests are done this way instead of the
simpler "answer = myService.anRpcRequest(args)" to avoid hanging the browser
while the (potentially slow) request is being processed. An example of the
responseFunction for the previous example is:
{code}
function responseFunction(answer){
// do something with answer
}
{code}
h4. Handling errors
{code}
//initialization code
try{
myService.anRpcRequest(args, responseFunction);
} catch(e) {
//handle error
alert(e);
}
function responseFunction(answer, exception){
//handle exception information
if(exception){
alert(exception.message);
return;
}
// do something with answer
}
{code}
h4. Using SCA JSON-RPC services with Dojo
Apache Tuscany JSON-RPC services provide built-in support for [Dojo
RPC|http://manual.dojotoolkit.org/WikiHome/DojoDotBook/Book9]. The
[Dojo|http://dojotoolkit.org/] toolkit is a popular framework for writing
Ajax/Web 2.0 style browser client applications. Tuscany SCA services which use
<binding.jsonrpc> will by default support the [Simple Method Description (SMD)
|http://dojo.jot.com/SMD] protocol. SMD is similar to ?wsdl for Web services,
entering a service endpoint appended with ?smd will return a SMD descriptor for
the service.
Using Tuscany SCA services with Dojo can therefore be as simple as the
following:
{code}
var myService = new dojo.rpc.JsonService("myService?smd");
{code}
h4. Some examples:
There are two samples showing using <binding.jsonrpc>, one which uses the Dojo
Toolkit on the client, and another which uses the Tuscany scaDomain.js script.
The samples are
[helloworld-dojo|https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-dojo/]
and
[helloworld-jsonrpc|https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-jsonrpc/].
{info:title=Differences between <binding.jsonrpc> and <binding.dwr>}
The current Tuscany SCA runtime supports <binding.jsonrpc> and <binding.dwr>
which provide similar functionality. The differences are:
* <binding.jsonrpc> supports the SMD protocol enabling easy use with Dojo,
<binding.ajax> does not support SMD
* <binding.ajax> supports SCA references and using
[COMET|http://en.wikipedia.org/wiki/Comet_(programming)] style asynchronous
operation, <binding.jsonrpc> does not
* <binding.jsonrpc> uses the standard [JSON-RPC|http://json-rpc.org/] protocol,
<binding.dwr> uses a proprietry protocol using [DWR|http://getahead.org/dwr/]
These differences should be resolved by the Tuscany SCA 1.0 release.
{info}
{warning:title=Changes since 0.90 release}
The Tuscany JSON-RPC and Ajax binding's have had significant functional and
useability changes since the 0.90 release. It is recomended that if possible
the latest code is used (the description on this page is based on the latest
code).
{warning}
{column}
{section}
---------------------------------------------------------------------
CONFLUENCE INFORMATION
This message is automatically generated by Confluence
Unsubscribe or edit your notifications preferences
http://cwiki.apache.org/confluence/users/viewnotifications.action
If you think it was sent incorrectly contact one of the administrators
http://cwiki.apache.org/confluence/administrators.action
If you want more information on Confluence, or have a bug to report see
http://www.atlassian.com/software/confluence
