1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<META name="description" content="Apache Tuscany">
<META name="keywords" content="apache, apache tuscany, tuscany, service, services, fabric, soa, service oriented architecture, sca, service component architecture, das, sdo, csa, ruby, opensource">
<LINK type="text/css" rel="stylesheet" href="http://tuscany.apache.org/stylesheets/default.css">
<LINK rel="SHORTCUT ICON" href="https://cwiki.apache.org/confluence/display/TUSCANYxDOCx2x/$images/favicon.ico">
<TITLE>SCA Java binding.jsonrpc : Apache Tuscany</TITLE>
<META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
<STYLE>
.spacetree * ul {
padding-left:0px;
margin-left: 0px;
}
.spacetree * li {
margin-left: 5px;
padding-left:5px;
}
</STYLE>
<BODY onload="init()">
<!-- topNav -->
<TABLE border="0" cellpadding="2" cellspacing="0" width="100%">
<TR class="topBar">
<TD align="left" valign="middle" class="topBarDiv" align="left" nowrap="">
<A href="https://cwiki.apache.org/geronimo"> Home</A> > <A href="index.html" title="Apache Tuscany Docs 2.x">Apache Tuscany Docs 2.x</A> > <A href="index.html" title="Index">Index</A> > <A href="sca-java-extensions-guide.html" title="SCA Java Extensions Guide">SCA Java Extensions Guide</A> > <A href="" title="SCA Java binding.jsonrpc">SCA Java binding.jsonrpc</A>
</TD>
<TD align="right" valign="middle" nowrap="">
<FORM name="search" action="http://www.google.com/search" method="get">
<INPUT type="hidden" name="ie" value="UTF-8">
<INPUT type="hidden" name="oe" value="UTF-8">
<INPUT type="hidden" name="domains" value="">
<INPUT type="hidden" name="sitesearch" value="">
<INPUT type="text" name="q" maxlength="255" value="">
<INPUT type="submit" name="btnG" value="Google Search">
</FORM>
</TD>
</TR>
</TABLE>
<TABLE border="0" cellpadding="2" cellspacing="0" width="100%">
<TR class="topBar">
<TD align="left" valign="middle" class="topBarDiv" nowrap="true" width="100%">
<A href="index.html" title="Apache Tuscany Docs 2.x">Apache Tuscany Docs 2.x</A> > <A href="index.html" title="Index">Index</A> > <A href="sca-java-extensions-guide.html" title="SCA Java Extensions Guide">SCA Java Extensions Guide</A> > <A href="" title="SCA Java binding.jsonrpc">SCA Java binding.jsonrpc</A>
</TD>
<TD align="right" valign="middle" class="topBarDiv" align="left" nowrap="true">
<A href="http://tuscany.apache.org/">Tuscany Home</A> | <A href="http://mail-archives.apache.org/mod_mbox/tuscany-user">User List</A> | <A href="http://mail-archives.apache.org/mod_mbox/tuscany-dev">Dev List</A> | <A href="http://issues.apache.org/jira/browse/Tuscany">Issue Tracker</A>
</TD>
</TR>
</TABLE>
<TABLE border="0" cellpadding="0" width="100%" bgcolor="#FFFFFF">
<TR>
<TD valign="top" align="left" width="22%" bgcolor="#F9F9F9" class="noprint">
<DIV class="tabletitle">Table of Contents</DIV>
<DIV class="spacetree">
</DIV>
</TD>
<TD align="left" valign="top" width="78%">
<!-- pageContent -->
<DIV id="PageContent">
<DIV class="pageheader" style="padding: 6px 0px 0px 0px;">
<!-- We'll enable this once we figure out how to access (and save) the logo resource -->
<!--img src="http://geronimo.apache.org/images/confluence_logo.gif" style="float: left; margin: 4px 4px 4px 10px;" border="0"-->
<DIV style="margin: 0px 10px 0px 10px" class="smalltext">Apache Tuscany Docs 2.x</DIV>
<DIV style="margin: 0px 10px 8px 10px" class="pagetitle">SCA Java binding.jsonrpc</DIV>
<DIV class="greynavbar" align="right" style="padding: 2px 10px; margin: 0px;">
<!-- -->
<A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=5964964">
<IMG src="http://geronimo.apache.org/images/icons/notep_16.gif" height="16" width="16" border="0" align="absmiddle" title="Edit Page"></A>
<A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=5964964">Edit Page</A>
<A href="https://cwiki.apache.org/confluence/pages/listpages.action?key=TUSCANYxDOCx2x">
<IMG src="http://geronimo.apache.org/images/icons/browse_space.gif" height="16" width="16" border="0" align="absmiddle" title="Browse Space"></A>
<A href="https://cwiki.apache.org/confluence/pages/listpages.action?key=TUSCANYxDOCx2x">Browse Space</A>
<A href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964964">
<IMG src="http://geronimo.apache.org/images/icons/add_page_16.gif" height="16" width="16" border="0" align="absmiddle" title="Add Page"></A>
<A href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964964">Add Page</A>
<A href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964964">
<IMG src="http://geronimo.apache.org/images/icons/add_blogentry_16.gif" height="16" width="16" border="0" align="absmiddle" title="Add News"></A>
<A href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964964">Add News</A>
<!-- -->
</DIV>
</DIV>
<DIV class="pagecontent">
<DIV class="wiki-content">
<H3><A name="SCAJavabinding.jsonrpc-%3Cbinding.jsonrpc%3E"></A><binding.jsonrpc></H3>
<P>Tuscany supports <A href="http://json-rpc.org/" class="external-link" rel="nofollow">JSON-RPC</A> as a protcol for use with SCA services by using the <binding.jsonrpc> element in your Application composite. This enables remote web browser clients to easily make RPC style calls to server-side SCA components.</P>
<H3><A name="SCAJavabinding.jsonrpc-UserStories"></A>User Stories</H3>
<UL>
<LI>A client application invoke a remote SCA Service using JSON-RPC and the invocation return business objects in JSON format. <IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" height="16" width="16" align="absmiddle" alt="" border="0">
<UL>
<LI>e.g. Retrieve catalog items</LI>
</UL>
</LI>
<LI>A SCA component can define a reference to a remote SCA Service and use JSON-RPC for the invocation. <IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" height="16" width="16" align="absmiddle" alt="" border="0">
<UL>
<LI>e.g. A catalog aggregator invoke various catalog services using JSON-RPC and aggregate the returned items into a single response</LI>
</UL>
</LI>
<LI>A client application invoke a SCA Service using JSON-RPC and the invocation returns a business exception. <IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" height="16" width="16" align="absmiddle" alt="" border="0">
<UL>
<LI>e.g. Empty catalog throws a Busines Exception. Business Exception should properly propagate and display nicely to client.</LI>
</UL>
</LI>
<LI>A client application invoke a SCA Service using JSON-RPC and the invocation returns a runtime exception. <IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" height="16" width="16" align="absmiddle" alt="" border="0">
<UL>
<LI>e.g. Try to retrieve catalog items from a catalog service that is un-available. Runtime exception properly propagate and display nicely to client.</LI>
</UL>
</LI>
<LI>A client application needs to access a service exposed trough JSON-RPC binding that requires authentication.
<UL>
<LI>e.g. make sure if nobody can get to the catalog if it's not authenticated</LI>
</UL>
</LI>
</UL>
<H3><A name="SCAJavabinding.jsonrpc-UsingtheTuscanyJSONRPCbinding"></A>Using the Tuscany JSON-RPC binding</H3>
<P>You could use this binding without any configuration, or by providing a specific service URI. <BR>
To include it on a SCA service or Reference, choose one of the examples below :</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<composite xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//docs.oasis-open.org/ns/opencsa/sca/200903"</SPAN>
</SPAN> xmlns:tuscany=<SPAN class="code-quote">"http:<SPAN class="code-comment">//tuscany.apache.org/xmlns/sca/1.1"</SPAN>
</SPAN> ...
<tuscany:binding.jsonrpc/>
</PRE>
</DIV></DIV>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<composite xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//docs.oasis-open.org/ns/opencsa/sca/200903"</SPAN>
</SPAN> xmlns:tuscany=<SPAN class="code-quote">"http:<SPAN class="code-comment">//tuscany.apache.org/xmlns/sca/1.1"</SPAN>
</SPAN> ...
<binding.jsonrpc uri=<SPAN class="code-quote">"http:<SPAN class="code-comment">//localhost:8080/store/catalog"</SPAN>/></SPAN>
</PRE>
</DIV></DIV>
<H3><A name="SCAJavabinding.jsonrpc-ConsumingJSONRPCservicesontheclientapplication"></A>Consuming JSON-RPC services on the client application</H3>
<P>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.</P>
<H4><A name="SCAJavabinding.jsonrpc-UtilizingTuscanyImplementation.widget"></A>Utilizing Tuscany Implementation.widget</H4>
<P>When your web client application is defined as an SCA component utilizing <A href="sca-java-implementationwidget.html" title="SCA Java implementation.widget">Tuscany Widgets</A>, 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.</P>
<P>This script is used by simply including the following tag within the HTML page :</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<script type=<SPAN class="code-quote">"text/javascript"</SPAN> src=<SPAN class="code-quote">"html-page-name.js"</SPAN> />
</PRE>
</DIV></DIV>
<P>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:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-comment">//@Reference
</SPAN><SPAN class="code-keyword">var</SPAN> myService = <SPAN class="code-keyword">new</SPAN> Reference(<SPAN class="code-quote">"myService"</SPAN>);
myService.aOnewayRequest(args);
</PRE>
</DIV></DIV>
<P>or</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-comment">//@Reference
</SPAN><SPAN class="code-keyword">var</SPAN> myService = <SPAN class="code-keyword">new</SPAN> JSONRpcClient(<SPAN class="code-quote">"myService"</SPAN>);
myService.anRpcRequest(args, responseFunction);
</PRE>
</DIV></DIV>
<P>Also see <A href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=TUSCANYxDOCx2x&title=SCA%2BJava%2Bimplementation.widget&linkCreation=true&fromPageId=5964964" class="createlink">Tuscany Widgets</A> for more details.</P>
<H4><A name="SCAJavabinding.jsonrpc-UtilizingaJavaScriptClientProxy"></A>Utilizing a JavaScript Client Proxy</H4>
<P>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. </P>
<P>After copying the script to your application, it can be used bu simply including the following tag within the HTML page :</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<script type=<SPAN class="code-quote">"text/javascript"</SPAN> src=<SPAN class="code-quote">"binding-jsonrpc.js"</SPAN> />
</PRE>
</DIV></DIV>
<P>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.</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-keyword">var</SPAN> myService = <SPAN class="code-keyword">new</SPAN> JSONRpcClient(<SPAN class="code-quote">"Catalog"</SPAN>).service;
myService.aOnewayRequest(args);
</PRE>
</DIV></DIV>
<P>or</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-keyword">var</SPAN> myService = <SPAN class="code-keyword">new</SPAN> JSONRpcClient(<SPAN class="code-quote">"Catalog"</SPAN>).service;
myService.anRpcRequest(args, responseFunction);
</PRE>
</DIV></DIV>
<H4><A name="SCAJavabinding.jsonrpc-HandlingJSONRPCResponsewithcallbacks"></A>Handling JSON-RPC Response with callbacks</H4>
<P>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:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
function responseFunction(answer){
<SPAN class="code-comment">// <SPAN class="code-keyword">do</SPAN> something with answer
</SPAN>}
</PRE>
</DIV></DIV>
<H4><A name="SCAJavabinding.jsonrpc-Handlingerrors"></A>Handling errors</H4>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-comment">//initialization code
</SPAN><SPAN class="code-keyword">try</SPAN>{
myService.anRpcRequest(args, responseFunction);
} <SPAN class="code-keyword">catch</SPAN>(e) {
<SPAN class="code-comment">//handle error
</SPAN> alert(e);
}
function responseFunction(answer, exception){
<SPAN class="code-comment">//handle exception information
</SPAN> <SPAN class="code-keyword">if</SPAN>(exception){
alert(exception.message);
<SPAN class="code-keyword">return</SPAN>;
}
<SPAN class="code-comment">// <SPAN class="code-keyword">do</SPAN> something with answer
</SPAN>}
</PRE>
</DIV></DIV>
<H4><A name="SCAJavabinding.jsonrpc-UsingSCAJSONRPCserviceswithDojo"></A>Using SCA JSON-RPC services with Dojo</H4>
<P>Apache Tuscany JSON-RPC services provide built-in support for <A href="http://manual.dojotoolkit.org/WikiHome/DojoDotBook/Book9" class="external-link" rel="nofollow">Dojo RPC</A>. The <A href="http://dojotoolkit.org/" class="external-link" rel="nofollow">Dojo</A> 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 <A href="http://dojo.jot.com/SMD" class="external-link" rel="nofollow">Simple Method Description (SMD) </A> protocol. SMD is similar to ?wsdl for Web services, entering a service endpoint appended with ?smd will return a SMD descriptor for the service. </P>
<P>Using Tuscany SCA services with Dojo can therefore be as simple as the following:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-keyword">var</SPAN> myService = <SPAN class="code-keyword">new</SPAN> dojo.rpc.JsonService(<SPAN class="code-quote">"myService?smd"</SPAN>);
</PRE>
</DIV></DIV>
<H4><A name="SCAJavabinding.jsonrpc-Supporteddatatypes"></A>Supported data types</H4>
<P>The JSON-RPC binding utilize the Databinding Framework to provide support for the following data transformations :</P>
<UL>
<LI>Primitive Type <==> JSON <==> Primitive Type</LI>
<LI>Array of Primitive Type <==> JSON <==> Array of Primitive Type</LI>
<LI>Java bean <==> JSON <==> Java bean</LI>
<LI>List <==> JSON <==> List</LI>
<LI>Map <==> JSON <==> Map</LI>
<LI>Set <==> JSON <==> Set</LI>
</UL>
<H4><A name="SCAJavabinding.jsonrpc-Someexamples%3A"></A>Some examples:</H4>
<P>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 <A href="https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-dojo/" class="external-link" rel="nofollow">helloworld-dojo</A> and <A href="https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-jsonrpc/" class="external-link" rel="nofollow">helloworld-jsonrpc</A>.</P>
</DIV>
</DIV>
</DIV>
</TD>
</TR>
</TABLE>
<!-- footer -->
<TABLE border="0" cellpadding="2" cellspacing="0" width="100%">
<TR>
<TD align="left" valign="middle" class="footer">
<IMG src="http://static.delicious.com/img/delicious.small.gif" height="10" width="10" alt="Delicious">
<A href="http://delicious.com/save" onclick="window.open('http://delicious.com/save?v=5&noui&jump=close&url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title),'delicious','toolbar=no,width=550,height=550'); return false;">Bookmark this on Delicious</A>
<IMG src="http://digg.com/img/badges/16x16-digg-guy.gif" width="16" height="16" alt="Digg!">
<A href="" onclick="window.open('http://digg.com/submit?url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)+'&topic=programming');">Digg this</A>
<!-- Slicker, but no text
<script type="text/javascript">
digg_skin = 'icon';
digg_window = 'new';
digg_title = 'Apache Geronimo v2.2 Documentation : SCA Java binding.jsonrpc';
digg_topic = 'programming';
</script>
<script src="http://digg.com/tools/diggthis.js" type="text/javascript"></script>
-->
</TD>
<TD align="right" valign="middle" class="footer">
<A href="http://cwiki.apache.org/GMOxPMGT/geronimo-privacy-policy.html">Privacy Policy</A> -
Copyright © 2003-2010, The Apache Software Foundation, Licensed under <A href="http://www.apache.org/licenses/LICENSE-2.0">ASL 2.0.</A>
</TD>
</TR>
</TABLE>
</BODY>
</HTML>
|
