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
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
|
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE- 2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<!-- generateKeywords macro -->
<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">
<!-- generateKeywords macro end -->
<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/TUSCANY/$images/favicon.ico">
<TITLE>Apache Tuscany : SCA Java binding.jms</TITLE>
<META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
<BODY onload="init()">
<!-- topNav macro -->
<TABLE valign="top" border="0" cellspacing="0" cellpadding="0" width="100%" background="http://tuscany.apache.org/images/TuscanyLogoNEW_Text_120px_bg.jpg">
<TR>
<TD valing="top" align="left">
<A href="https://cwiki.apache.org/confluence/pages/viewpage.action?spaceKey=TUSCANY&title=$siteroot"><IMG src="http://tuscany.apache.org/images/TuscanyLogoNEW_Text_120px_bg.jpg" height="91" width="25" border="0"></A>
</TD>
<TD>
<A href="http://tuscany.apache.org/"><IMG src="http://tuscany.apache.org/images/TuscanyLogo.jpg" border="0"></A>
</TD>
<TD width="100%">
</TD>
<!-- Adds the edit page link to the top banner-->
<TD valign="bottom">
<DIV style="padding: 2px 10px; margin: 0px;">
<A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=57033">
<IMG src="http://tuscany.apache.org/images/notep_16.gif" height="16" width="16" border="0" align="absmiddle" title="Edit Page"></A>
</DIV>
</TD>
</TR>
</TABLE>
<!-- topNav macro end -->
<!-- breadCrumbs macro -->
<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="home.html" title="Apache Tuscany">Apache Tuscany</A> > <A href="home.html" title="Home">Home</A> > <A href="sca-overview.html" title="SCA Overview">SCA Overview</A> > <A href="sca-java.html" title="SCA Java">SCA Java</A> > <A href="java-sca-documentation-menu.html" title="Java SCA Documentation Menu">Java SCA Documentation Menu</A> > <A href="sca-java-user-guide.html" title="SCA Java User Guide">SCA Java User Guide</A> > <A href="" title="SCA Java binding.jms">SCA Java binding.jms</A>
</TD>
<TD align="right" valign="middle" class="topBarDiv" align="left" nowrap="true">
<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>
<!-- breadCrumbs macro end -->
<TABLE border="0" cellpadding="0" width="100%" bgcolor="#FFFFFF">
<TR>
<TD align="left" valign="top">
<!-- pageContent macro -->
<DIV id="PageContent">
<DIV class="pagecontent">
<DIV class="wiki-content">
<TABLE class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><TBODY><TR>
<TD class="confluenceTd" valign="top" width="15%">
<DIV class="panel" style="background-color: #ECF4D1;border-color: #C3CDA1;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #C3CDA1;background-color: #C3CDA1;"><B>General</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;">
<P><A href="home.html" title="Home">Home</A><BR>
<A href="http://www.apache.org/licenses/LICENSE-2.0.html" class="external-link" rel="nofollow">License </A><BR>
<A href="sca-java-get-involved.html" title="SCA Java Get Involved">Get Involved</A><BR>
<A href="sca-java-found-a-bug.html" title="SCA Java Found A Bug">Found a Bug?</A></P>
</DIV></DIV>
<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>SCA Java</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;">
<P><A href="sca-java.html" title="SCA Java">SCA Java Home</A><BR>
<A href="tuscany-dashboard.html" title="Tuscany Dashboard">SCA Dashboard</A><BR>
<A href="java-sca-tools.html" title="Java SCA Tools">Tools </A><BR>
<A href="tuscany-sca-java-faq.html" title="Tuscany SCA Java - FAQ">FAQ</A></P>
</DIV></DIV>
<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>SCA Java 1.x</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;">
<P><A href="sca-java-releases.html" title="SCA Java Releases">Downloads</A><BR>
<A href="java-sca-documentation-menu.html" title="Java SCA Documentation Menu">Documentation</A><BR>
<A href="https://svn.apache.org/repos/asf/tuscany/sca-java-1.x/trunk/" class="external-link" rel="nofollow">1.x Source Code</A><BR>
<A href="http://tinyurl.com/8rlxd3" class="external-link" rel="nofollow">Roadmap</A></P>
</DIV></DIV>
<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>SCA Java 2.x</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;">
<P><A href="sca-java-2x-releases.html" title="SCA Java 2.x Releases">Downloads</A><BR>
<A href="http://tuscany.apache.org/documentation-2x/" class="external-link" rel="nofollow">Documentation</A><BR>
<A href="https://svn.apache.org/repos/asf/tuscany/sca-java-2.x/trunk/" class="external-link" rel="nofollow">2.x Source Code</A><BR>
<A href="http://tinyurl.com/8rlxd3" class="external-link" rel="nofollow">Roadmap</A></P>
</DIV></DIV>
<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>Documentation</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;">
<P><A href="sca-java-user-guide.html" title="SCA Java User Guide">User Guide</A><BR>
<A href="sca-java-architecture-guide.html" title="SCA Java Architecture Guide">Architecture Guide</A><BR>
<A href="sca-java-development-guide.html" title="SCA Java Development Guide">Developer Guide</A><BR>
<A href="sca-java-extension-development-guide.html" title="SCA Java Extension Development Guide">Extension Developer Guide</A></P>
</DIV></DIV>
<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>Resources</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;">
<P><A href="tuscany-sca-java-faq.html" title="Tuscany SCA Java - FAQ">FAQ</A><BR>
<A href="https://svn.apache.org/repos/asf/incubator/tuscany/java/sca" class="external-link" rel="nofollow">Source Code</A></P>
</DIV></DIV>
</TD>
<TD class="confluenceTd" valign="top" width="85%">
<H3><A name="SCAJavabinding.jms-%3Cbinding.jms%3E"></A><binding.jms></H3>
<P>The Tuscany Java SCA runtime supports the Java Messaging Service using the <binding.jms> SCDL extension. New JMS based service endpoints can be provided using a <binding.jms> element within a SCA <service>, existing JMS queues can be accessed using a <binding.jms> element within a SCA <reference>.</P>
<P>The JMS binding is one of the SCA extensions which is being formalized in the OASIS Open Composite Services Architecture with a published <A href="http://www.oasis-opencsa.org/sca-bindings" class="external-link" rel="nofollow">specifications </A> document.</P>
<H4><A name="SCAJavabinding.jms-UsingtheJMSbinding"></A>Using the JMS binding</H4>
<P>The simplest way to use the JMS binding is to use the URI syntax to configure the binding, for example:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java"><binding.jms uri=<SPAN class="code-quote">"jms:RequestQueue"</SPAN>/></PRE>
</DIV></DIV>
<P>This tells the binding to use a JMS destination named "RequestQueue", with all the other configuration options using default values. </P>
<P>By default Tuscany will use a JMS connection factory named 'ConnectionFactory', this can be changed by using a query parameter in the URI, for example, to use a connection factory named 'myCF' can be done as follows:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java"><binding.jms uri=<SPAN class="code-quote">"jms:RequestQueue?connectionFactoryName=myCF"</SPAN>/></PRE>
</DIV></DIV>
<P><IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/lightbulb_on.gif" height="16" width="16" align="absmiddle" alt="" border="0"> When using a SCA reference for RPC style requests and no response destination is defined in the SCDL then a temporary replyTo queue will automatically be created and used. </P>
<P>When using the JMS binding with SCA services the syntax can be simplified even further by letting the destination name default to the service name. For example, the following SCDL snippet creates a JMS service listening on a JMS destination named "MyService":</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<service name=<SPAN class="code-quote">"MyService"</SPAN>>
<binding.jms />
</service>
</PRE>
</DIV></DIV>
<H3><A name="SCAJavabinding.jms-ValidationintheJMSBinding"></A>Validation in the JMS Binding</H3>
<P>Tuscany performs two types of validation of the JMS Binding specified in a composite file.</P>
<OL>
<LI>All XML is validated according to the schema to be valid XML. Elements are validated to be of the correct number<BR>
and order. URIs are validated to be of the correct form. Required attributes and elements are checked.</LI>
<LI>The model data for the JMS binding is validated. These are semantic issues such as the connection factory should not contradict destination type, connection factory and activation specification are mutually exclusive, and response connection must<BR>
either be a name attribute or a response element.</LI>
</OL>
<P>Validation rules are taken from the binding schema and the OSOA and OASIS specs:</P>
<UL>
<LI><A href="http://www.oasis-open.org/committees/documents.php?wg_abbrev=sca-bindings" class="external-link" rel="nofollow">http://www.oasis-open.org/committees/documents.php?wg_abbrev=sca-bindings</A> (sca-binding-jms-1.1-spec-cd01-rev4.pdf)</LI>
<LI><A href="http://www.osoa.org/display/Main/Service%20Component%20Architecture%20Specifications" class="external-link" rel="nofollow">http://www.osoa.org/display/Main/Service+Component+Architecture+Specifications</A> (SCA JMS Binding V1.00 )</LI>
</UL>
<P>Invalid JMS bindings usually result in a JMSBindingException with error message and specific context of the error. See the JMSBindingProcessor for a complete list of validation rules.</P>
<H3><A name="SCAJavabinding.jms-SomeExamples"></A>Some Examples</H3>
<H4><A name="SCAJavabinding.jms-HelloWorld"></A>HelloWorld</H4>
<P>The <A href="https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-jms-webapp/" class="external-link" rel="nofollow">helloworld-jms</A> sample demonstrates basic RPC style operations over JMS. The sample has one component exposing a JMS service on a queue name 'HelloWorldService' and another component which invokes the service by sending JMS messages to that queue. A temporary destination is used for the response messages. The .composite file for this is shown below, see the helloworld sample <A href="https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-jms-webapp/README" class="external-link" rel="nofollow">README</A> for full details.</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">//www.osoa.org/xmlns/sca/1.0"</SPAN>
</SPAN> targetNamespace=<SPAN class="code-quote">"http:<SPAN class="code-comment">//sample"</SPAN>
</SPAN> xmlns:sample=<SPAN class="code-quote">"http:<SPAN class="code-comment">//sample"</SPAN>
</SPAN> name=<SPAN class="code-quote">"HelloWorld"</SPAN>>
<component name=<SPAN class="code-quote">"HelloWorldClient"</SPAN>>
<implementation.java class=<SPAN class="code-quote">"helloworld.HelloWorldClient"</SPAN>/>
<reference name=<SPAN class="code-quote">"helloWorldRef"</SPAN>>
<binding.jms uri=<SPAN class="code-quote">"jms:HelloWorldService"</SPAN>/>
</reference>
</component>
<component name=<SPAN class="code-quote">"HelloWorldServiceComponent"</SPAN>>
<implementation.java class=<SPAN class="code-quote">"helloworld.HelloWorldServiceImpl"</SPAN> />
<service name=<SPAN class="code-quote">"HelloWorldService"</SPAN>>
<binding.jms />
</service>
</component>
</composite>
</PRE>
</DIV></DIV>
<H3><A name="SCAJavabinding.jms-OperationSelection"></A>Operation Selection</H3>
<P>Operation selection extensions allow you to choose how the JMS bindings determines which service operation to call based on the incoming MS message. </P>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TH class="confluenceTh"> operatiion selector </TH>
<TH class="confluenceTh"> description </TH>
</TR>
<TR>
<TD class="confluenceTd"> <opertionSelector.jmsdefault/> </TD>
<TD class="confluenceTd"> The default operations selector as described in the <A href="http://www.osoa.org/download/attachments/35/SCA_JMSBinding_V100.pdf?version=2" class="external-link" rel="nofollow">JMS Binding Specification 1.0</A>;
<UL>
<LI>If there is only one operation on the service interface then this operation is chosen.</LI>
<LI>Else If the property scaOperationName appears in the incoming JMS message then its value determines the service operation</LI>
<LI>Else the operation is assumed to be called onMessage</LI>
</UL>
</TD>
</TR>
<TR>
<TD class="confluenceTd"> <opertionSelector.jmsUserProp propertyName="somePropertyName"/> </TD>
<TD class="confluenceTd"> The named property, in this case somePropertyName, on the incoming JMS message holds name of the service operation that will be called </TD>
</TR>
</TBODY></TABLE>
</DIV>
<P>While you can specify the default operation selector there is no need to as in lieu of other operation selectors being specified this one it assumed to be in force. You can add new operation selectors by adding the appropriate model objects, processors and providers.</P>
<P>Following operation selection the actual operation that is called may be further affected by operationProperties configuration.</P>
<H3><A name="SCAJavabinding.jms-WireFormats"></A>Wire Formats</H3>
<P>Wire format extensions allow you to choose how message data is expected to appear inside the JMS message as it flows across the wire. </P>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TH class="confluenceTh"> wire format </TH>
<TH class="confluenceTh"> description </TH>
</TR>
<TR>
<TD class="confluenceTd"> <wireFormat.jmsdefault sendFormat="text or bytes"/> </TD>
<TD class="confluenceTd"> The default wire format as described in the <A href="http://www.osoa.org/download/attachments/35/SCA_JMSBinding_V100.pdf?version=2" class="external-link" rel="nofollow">JMS Binding Specification 1.0</A>;
<UL>
<LI>If the service operation has a single parameter of type javax.jms.Message then the incoming JMS message is passed in as is</LI>
<LI>Else the incoming message is a text message containing XML (we have added the sendFormat attribute to control whether the message type is actially text or bytes)
<UL>
<LI>If there is a single parameter in the service operation signature then the data in the JMS message is assumed to be a direct serialization of the data coming from/going to the service operation</LI>
<LI>Else there are multiple parameters in the servioce operation signature and the data in the JMS message is assumed to be a document literal wrapped serialization of the data coming from/going to the service operation</LI>
</UL>
</LI>
</UL>
</TD>
</TR>
<TR>
<TD class="confluenceTd"> <wireFormat.jmsBytes/> </TD>
<TD class="confluenceTd"> The data in the JMS message is the native bytes of the data coming from/going to the service operation. The service operation signature is expected to have a single byte[] parameter </TD>
</TR>
<TR>
<TD class="confluenceTd"> <wireFormat.jmsBytesXML/> </TD>
<TD class="confluenceTd">The data in the JMS message is an XML document literal wrapped representation of the parameters of the service operation presented as a series of bytes </TD>
</TR>
<TR>
<TD class="confluenceTd"> <wireFormat.jmsText/> </TD>
<TD class="confluenceTd"> The data in the JMS message is the string representation of data coming from/going to the service operation. The service operation signature is expected to have a single String parameter </TD>
</TR>
<TR>
<TD class="confluenceTd"> <wireFormat.jmsTextXML/> </TD>
<TD class="confluenceTd"> The data in the JMS message is an XML document literal wrapped representation of the parameters of the service operation presented as a String </TD>
</TR>
<TR>
<TD class="confluenceTd"> <wireFormat.jmsObject/> </TD>
<TD class="confluenceTd"> The data in the JMS message is the Java object serialization of data coming from/going to the service operation </TD>
</TR>
</TBODY></TABLE>
</DIV>
<P>While you can specify this wire format there is no need to as in lieu of other operation selectors being specified this one it assumed to be in force. You can add new wire formats by adding the appropriate model objects, processors and providers.</P>
<H3><A name="SCAJavabinding.jms-UsingSCAcallbackswiththeJMSbinding"></A>Using SCA callbacks with the JMS binding</H3>
<P>The Tuscany JMS binding supports using SCA callbacks for creating asynchronous clients and services.</P>
<P>This is done by using a <callback> element in the SCDL for the service or reference as shown in the following example. <BR>
See the <A href="https://svn.apache.org/repos/asf/tuscany/java/sca/samples/callbacks-jms/" class="external-link" rel="nofollow">callbacks-jms</A> sample for a complete example of using callbacks</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">//www.osoa.org/xmlns/sca/1.0"</SPAN>
</SPAN> targetNamespace=<SPAN class="code-quote">"http:<SPAN class="code-comment">//sample"</SPAN>
</SPAN> name=<SPAN class="code-quote">"CallbacksComposite"</SPAN>>
<component name=<SPAN class="code-quote">"ClientComponent"</SPAN>>
<implementation.java class=<SPAN class="code-quote">"callbacks.OrderServiceClient"</SPAN> />
<reference name=<SPAN class="code-quote">"orderService"</SPAN> target=<SPAN class="code-quote">"ServiceComponent/OrderService"</SPAN>>
<binding.jms uri=<SPAN class="code-quote">"jms:OrderService"</SPAN>/>
<callback>
<binding.jms />
</callback>
</reference>
</component>
<component name=<SPAN class="code-quote">"ServiceComponent"</SPAN>>
<implementation.java class=<SPAN class="code-quote">"callbacks.OrderServiceImpl"</SPAN> />
<service name=<SPAN class="code-quote">"OrderService"</SPAN>>
<binding.jms />
<callback>
<binding.jms />
</callback>
</service>
</component>
</composite>
</PRE>
</DIV></DIV>
<P><IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/lightbulb_on.gif" height="16" width="16" align="absmiddle" alt="" border="0"> When no destination is defined on the callback binding of a <reference> then a JMS temporary queue will be used.</P>
<H3><A name="SCAJavabinding.jms-SettingJMSheadersanduserproperties"></A>Setting JMS headers and user properties</H3>
<P>JMS headers and user properties can be set on JMS messages sent from Tuscany by using the <Headers> and <OperationProperties> elements of the JMS binding. The <Headers> element applies to all messages, the <OperationProperties> applies to individual operations and may override values set on the <Headers> element.</P>
<P>An example of using these is shown in the following snippet of SCDL:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<binding.jms uri=<SPAN class="code-quote">"jms:ServiceQueue"</SPAN>>
<headers JMSType=<SPAN class="code-quote">"someTypeValue"</SPAN> />
<operationProperties name=<SPAN class="code-quote">"op2"</SPAN>>
<headers JMSType=<SPAN class="code-quote">"op2SpecificTypeValue"</SPAN> />
</operationProperties>
</binding.jms>
</PRE>
</DIV></DIV>
<P>A complete working example of using <Headers> and <OperationProperties> can be seen in the <A href="https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms/src/test/java/org/apache/tuscany/sca/binding/jms/PropertiesTestCase.java" class="external-link" rel="nofollow">properties itest </A></P>
<H3><A name="SCAJavabinding.jms-UsingJMSmessageselectors"></A>Using JMS message selectors </H3>
<P>Services using the JMS binding to receive messages may only want a subset of the messages arriving on a queue or topic. This can be done by using the <SubscriptionHeaders> element which enables defining a <A href="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JMS4.html#wp79281" class="external-link" rel="nofollow">JMS message selector </A> to filter the messages that will be received. </P>
<P>An example of using these is shown in the following snippet of SCDL:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<binding.jms uri=<SPAN class="code-quote">"jms:ServiceTopic"</SPAN> >
<SubscriptionHeaders JMSSelector=<SPAN class="code-quote">"JMSType = 'type1'"</SPAN>/>
</binding.jms>
</PRE>
</DIV></DIV>
<P>A complete working example of using <SubscriptionHeaders> can be seen in the <A href="https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms-selectors" class="external-link" rel="nofollow">jms selectors itest </A>.</P>
<H3><A name="SCAJavabinding.jms-Usingadefinitions.xmlfileandtherequestConnection%2FresponseConnectionattributes"></A>Using a definitions.xml file and the requestConnection/responseConnection attributes</H3>
<P>It can be useful to define the details of the JMS resources separately from the SCA composite, to support this the SCA definitions.xml file can be used to define 'model' <binding.jms> elements which can then be referred to from the binding within the composite. </P>
<P>For example, the following shows a definitions.xml file defining a JMS queue and connection factory which are then used by a JMS binding within a composite.</P>
<P>The definitions.xml file:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<definitions xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.osoa.org/xmlns/sca/1.0"</SPAN>
</SPAN> xmlns:itest=<SPAN class="code-quote">"http:<SPAN class="code-comment">//jms"</SPAN>
</SPAN> targetNamespace=<SPAN class="code-quote">"http:<SPAN class="code-comment">//jms"</SPAN> >
</SPAN>
<binding.jms name=<SPAN class="code-quote">"itest:TestService"</SPAN> >
<destination name=<SPAN class="code-quote">"MyServiceQueue"</SPAN> create=<SPAN class="code-quote">"never"</SPAN>/>
<connectionFactory name=<SPAN class="code-quote">"MyConnectionFactory"</SPAN>/>
</binding.jms>
</definitions>
</PRE>
</DIV></DIV>
<P>and a binding which uses the definitions.xml binding:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java"><binding.jms requestConnection=<SPAN class="code-quote">"itest:TestService"</SPAN> /></PRE>
</DIV></DIV>
<P>A complete working example of using the requestConnection/responseConnection attributes can be seen in the <A href="https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms-definitions" class="external-link" rel="nofollow">jms definitions itest </A>.</P>
<H3><A name="SCAJavabinding.jms-ConfiguringJMSresources"></A>Configuring JMS resources</H3>
<P>Tuscany locates all JMS resources from JNDI so the environment where Tuscany is running needs to have JNDI and JMS correctly configured in order to use the Tuscany JMS binding. </P>
<P>The following describes how to configure JMS in some common environments:</P>
<H4><A name="SCAJavabinding.jms-TuscanyJ2SEstandaloneenvironmentwithActiveMQ"></A>Tuscany J2SE standalone environment with ActiveMQ</H4>
<P>The Tuscany standalone runtime can use an embedded <A href="http://activemq.apache.org/" class="external-link" rel="nofollow">Apache ActiveMQ</A> message broker. To use ActiveMQ the application needs to include the JMS API and ActiveMQ jars in the classpath and include a jndi.properties file to configure the ActiveMQ resources in JNDI. </P>
<P>An example of this can be seen in the Tuscany <A href="https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms/" class="external-link" rel="nofollow">JMS itest</A> which uses the <A href="http://repo1.maven.org/maven2/org/apache/activemq/activemq-core/4.1.1/activemq-core-4.1.1.jar" class="external-link" rel="nofollow">ActiveMQ 4.1.1</A> release and <A href="https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms/src/main/resources/jndi.properties" class="external-link" rel="nofollow">this</A> jndi.properties file. </P>
<P>For more information on using ActiveMQ see the Apache ActiveMQ website and specifically <A href="http://activemq.apache.org/jndi-support.html" class="external-link" rel="nofollow">this</A> page for information about configuring JNDI resources. </P>
<H4><A name="SCAJavabinding.jms-ApacheTomcat"></A>Apache Tomcat</H4>
<P>Tomcat does not include a JMS broker by default so you need to either embed one in each Tuscany application, install a broker into the tomcat installation, or use an external broker. Once that is done JNDI resources can be defined using the standard Tomcat facilities, see the Tomcat <A href="http://tomcat.apache.org/tomcat-6.0-doc/jndi-resources-howto.html" class="external-link" rel="nofollow">JNDI How-to</A>. </P>
<P>The Tuscany samples that use JMS and Tomcat demonstrate how to embed a JMS broker within the application by including ActiveMQ and its dependencies within the sample WAR, and using the webapp META-INF/context.xml file to define the JMS resources in JNDI. </P>
<H4><A name="SCAJavabinding.jms-JEEapplicationserverssuchasApacheGeronimo%2CWebSphereetc"></A>JEE application servers such as Apache Geronimo, WebSphere etc</H4>
<P>JEE Application servers such as Geronimo, WebSphere, WebLogic etc come with their own JMS broker that can be used by Tuscany. All the JMS resources used by a Tuscany application must be manually defined in the application server. Usually the application server has some sort of admin console where the resources can be defined using a web browser. </P>
<P>The Tuscany helloworld JMS sample <A href="https://svn.apache.org/repos/asf/tuscany/java/sca/samples/helloworld-jms-webapp/README" class="external-link" rel="nofollow">README</A> describes the specific details of how to do this for some common application servers.</P>
<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>ClassCastExceptions when using Tuscany applications in an Application Server</B><BR>Tuscany applications, specifically the JMS samples, are built to work out of-the-box on Tomcat by including a JMS broker embedded within the application. This causes incompatibilities with some Application Servers because the Java class of JMS resources may use different class loaders in the server and the application. The solution is to delete any JMS API jar included in the application WAR, for example, the geronimo-jms_1.1_spec-1.1.jar.</TD></TR></TABLE></DIV>
<H4><A name="SCAJavabinding.jms-%28%2F%29UsingJEEresourcereferences"></A><IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" height="16" width="16" align="absmiddle" alt="" border="0"> Using JEE resource references</H4>
<P>When running Tuscany in a JEE environment it can be useful to use JEE resource references to map local application resource names to global JNDI names. This can be done by using <resource-ref> elements in the application deployment descriptor. If a <resource-ref> exists for a JMS binding resource then Tuscany will use that instead of looking up the resource directly in the global JNDI.</P>
<P>For example, adding the following definitions to the helloworld JMS sample <A href="https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-jms-webapp/src/main/webapp/WEB-INF/web.xml" class="external-link" rel="nofollow">web.xml</A> will enable mapping the 'ConnectionFactory' and 'HelloWorldService' names used by the JMS binding into names for the actual resources used on the Application Server. This will normally occur when the application is dployed with the deploy tool asking what real resource names the resourecs should be mapped to.</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<resource-ref>
<res-ref-name>ConnectionFactory</res-ref-name>
<res-type>javax.jms.ConnectionFactory</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-ref>
<res-ref-name>HelloWorldService</res-ref-name>
<res-type>javax.jms.Queue</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
</PRE>
</DIV></DIV>
<H4><A name="SCAJavabinding.jms-UsinganexternalJMSbroker"></A>Using an external JMS broker</H4>
<P>When the Tuscany environment does not include a JMS broker then an external broker may be used by specifying the initialContextFactory and jndiURL attributes on the binding.jms element. Any JMS 1.1 compatible broker should work such as Apache ActiveMQ or any other proprietary broker. The Tuscany application classpath will need to include jars for the initial context factory and all of its dependencies.</P>
<P>An example of using the Tuscany JMS binding with an external ActiveMQ broker is as follows:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<binding.jms initialContextFactory=<SPAN class="code-quote">"org.apache.activemq.jndi.ActiveMQInitialContextFactory"</SPAN> jndiURL=<SPAN class="code-quote">"tcp:<SPAN class="code-comment">//localhost:61616"</SPAN>>
</SPAN> <destination name=<SPAN class="code-quote">"DestQueueA"</SPAN>/>
</binding.jms>
</PRE>
</DIV></DIV>
<H4><A name="SCAJavabinding.jms-UsingtheWebSphereclientforJMS"></A>Using the WebSphere client for JMS</H4>
<P>The Tuscany JMS binding now (post Tuscany SCA 1.2) works the <A href="http://www-1.ibm.com/support/docview.wss?uid=swg24012804" class="external-link" rel="nofollow">WebSphere client for JMS </A> which enables Tuscany applications running outside of WebSphere to use JMS resources defined within WebSphere. You need to include the JMS client jars in the Tuscany classpath and ensure that the JMS connection factory has the "endpoint providers" field configured in WebSphere. See this <A href="http://apache.markmail.org/message/qufruqdwxuvaagev" class="external-link" rel="nofollow">email thread </A> for more information.</P>
<H3><A name="SCAJavabinding.jms-JMSMessagetypesandmessagebodyformat"></A>JMS Message types and message body format</H3>
<P>The SCA JMS specification only defines how to use JMS TextMessages which contain XML in the message body, however it is a common requirement to use alternative message types and body formats. Currently Tuscany defines an additional "messageProcessor" attribute on the binding.jms element to support additional message types and payload formats. For the time being this should be considered an interim solution which will be changed in future Tuscany releases.</P>
<P>The messageProcessor attribute value may be "XMLTextMessage", "TextMessage", "ObjectMessage", or the name of a Java class that implements the org.apache.tuscany.sca.binding.jms.provider.JMSMessageProcessor interface. For example:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<reference name=<SPAN class="code-quote">"serviceA"</SPAN> promote=<SPAN class="code-quote">"HelloWorldClient/serviceA"</SPAN>>
<binding.jms messageProcessor=<SPAN class="code-quote">"my.TestMessageProcessor"</SPAN> />
</reference>
</PRE>
</DIV></DIV>
<P>For a complete example of using the messageProcessor attribute see the <A href="https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms/src/test/java/org/apache/tuscany/sca/binding/jms/MessageProcessorTestCase.java" class="external-link" rel="nofollow">MessageProcessorTestCase</A> itest. </P>
<H3><A name="SCAJavabinding.jms-UsingpolicytocontroltheJMSbinding"></A>Using policy to control the JMS binding</H3>
<P>The JMS binding is aware of the following policy implementations. </P>
<UL class="alternate" type="square">
<LI>org.apache.tuscany.sca.binding.jms.policy.header.JMSHeaderPolicy
<UL class="alternate" type="square">
<LI>Used to set various JMS message headers including JMSType, JMSCorrelationID, JMSDeliveryMode, JMSTimeToLive, JMSPriority and arbitrary user defined header properties</LI>
</UL>
</LI>
<LI>org.apache.tuscany.sca.binding.jms.policy.authentication.token.JMSTokenAuthenticationPolicy
<UL class="alternate" type="square">
<LI>Used to insert a user defined authentication property into the JMS header.</LI>
</UL>
</LI>
</UL>
<P>Intents and policy sets can be constructed to control the application of these policies. The following intents are defined by default</P>
<UL class="alternate" type="square">
<LI>pritority</LI>
<LI>deliveryMode</LI>
</UL>
<P>New intents and policy sets can be designed are required to provide the level of control you need over your application. </P>
<H4><A name="SCAJavabinding.jms-Intent%3Apriority"></A>Intent: priority</H4>
<P>The priority intent provides a coarse grained approach to setting message priority. For example,</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<reference name=<SPAN class="code-quote">"serviceA"</SPAN> promote=<SPAN class="code-quote">"HelloWorldClient/serviceA"</SPAN> requires=<SPAN class="code-quote">"priotiry.meduim"</SPAN>>
<binding.jms messageProcessor=<SPAN class="code-quote">"my.TestMessageProcessor"</SPAN> />
</reference>
</PRE>
</DIV></DIV>
<P>The values "priority.high", "priority.medium", "priority.low" are supported. It is the responsibility of the user to define a policy set to support these intents. The following policy set could be used to support these priority values.</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<policySet name=<SPAN class="code-quote">"JMSPolicySet1"</SPAN>
provides=<SPAN class="code-quote">"priority"</SPAN>
appliesTo=<SPAN class="code-quote">"sca:binding.jms"</SPAN>>
<intentMap provides=<SPAN class="code-quote">"priority"</SPAN> <SPAN class="code-keyword">default</SPAN>=<SPAN class="code-quote">"medium"</SPAN>>
<qualifier name=<SPAN class="code-quote">"high"</SPAN>>
<tuscany:jmsHeader JMSPriority=<SPAN class="code-quote">"9"</SPAN>/>
</qualifier>
<qualifier name=<SPAN class="code-quote">"medium"</SPAN>>
<tuscany:jmsHeader JMSPriority=<SPAN class="code-quote">"4"</SPAN>/>
</qualifier>
<qualifier name=<SPAN class="code-quote">"low"</SPAN>>
<tuscany:jmsHeader JMSPriority=<SPAN class="code-quote">"0"</SPAN>/>
</qualifier>
</intentMap>
</policySet>
</PRE>
</DIV></DIV>
<H4><A name="SCAJavabinding.jms-Intent%3AdeliveryMode"></A>Intent: deliveryMode</H4>
<P>The deliveryMode intent provides s simple way of specifying whether a message should be delivered persistently or non-persistently. For example, </P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<reference name=<SPAN class="code-quote">"serviceA"</SPAN> promote=<SPAN class="code-quote">"HelloWorldClient/serviceA"</SPAN> requires=<SPAN class="code-quote">"deliveryMode.persistent"</SPAN>>
<binding.jms messageProcessor=<SPAN class="code-quote">"my.TestMessageProcessor"</SPAN> />
</reference>
</PRE>
</DIV></DIV>
<P>The values "deliveryMode.persistent" and "deliveryMode.nonPersistent" are supported. It is the responsibility of the user to define a policy set to support these intents. The following policy set could be used to support these delivery mode values.</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<policySet name=<SPAN class="code-quote">"JMSPolicySet2"</SPAN>
provides=<SPAN class="code-quote">"deliveryMode"</SPAN>
appliesTo=<SPAN class="code-quote">"sca:binding.jms"</SPAN>>
<intentMap provides=<SPAN class="code-quote">"deliveryMode"</SPAN> <SPAN class="code-keyword">default</SPAN>=<SPAN class="code-quote">"nonPersistent"</SPAN>>
<qualifier name=<SPAN class="code-quote">"persistent"</SPAN>>
<tuscany:jmsHeader JMSDeliveryMode=<SPAN class="code-quote">"PERSISTENT"</SPAN>/>
</qualifier>
<qualifier name=<SPAN class="code-quote">"nonPersistent"</SPAN>>
<tuscany:jmsHeader JMSDeliveryMode=<SPAN class="code-quote">"NON_PERSISTENT"</SPAN>/>
</qualifier>
</intentMap>
</policySet>
</PRE>
</DIV></DIV>
<H4><A name="SCAJavabinding.jms-Otherheadervalues"></A>Other header values</H4>
<P>TBD</P>
<H3><A name="SCAJavabinding.jms-JMSbindingschema"></A>JMS binding schema</H3>
<P>The complete JMS binding SCDL schema has the following format:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<binding.jms correlationScheme=<SPAN class="code-quote">"string"</SPAN>?
initialContextFactory=<SPAN class="code-quote">"xs:anyURI"</SPAN>?
jndiURL=<SPAN class="code-quote">"xs:anyURI"</SPAN>?
requestConnection=<SPAN class="code-quote">"QName"</SPAN>?
responseConnection=<SPAN class="code-quote">"QName"</SPAN>?
operationProperties=<SPAN class="code-quote">"QName"</SPAN>?
... >
<destination name=<SPAN class="code-quote">"xs:anyURI"</SPAN> type=<SPAN class="code-quote">"string"</SPAN>? create=<SPAN class="code-quote">"string"</SPAN>?>
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</destination>?
<connectionFactory name=<SPAN class="code-quote">"xs:anyURI"</SPAN> create=<SPAN class="code-quote">"string"</SPAN>?>
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</connectionFactory>?
<activationSpec name=<SPAN class="code-quote">"xs:anyURI"</SPAN> create=<SPAN class="code-quote">"string"</SPAN>?>
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</activationSpec>?
<response>
<destination name=<SPAN class="code-quote">"xs:anyURI"</SPAN> type=<SPAN class="code-quote">"string"</SPAN>? create=<SPAN class="code-quote">"string"</SPAN>?>
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</destination>?
<connectionFactory name=<SPAN class="code-quote">"xs:anyURI"</SPAN> create=<SPAN class="code-quote">"string"</SPAN>?>
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</connectionFactory>?
<activationSpec name=<SPAN class="code-quote">"xs:anyURI"</SPAN> create=<SPAN class="code-quote">"string"</SPAN>?>
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</activationSpec>?
</response>?
<complexType name=<SPAN class="code-quote">"SubscriptionHeaders"</SPAN>>
<attribute name=<SPAN class="code-quote">"JMSSelector"</SPAN> type=<SPAN class="code-quote">"string"</SPAN>/>
</complexType>
<resourceAdapter name=<SPAN class="code-quote">"NMTOKEN"</SPAN>>?
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</resourceAdapter>?
<headers JMSType=<SPAN class="code-quote">"string"</SPAN>?
JMSCorrelationId=<SPAN class="code-quote">"string"</SPAN>?
JMSDeliveryMode=<SPAN class="code-quote">"string"</SPAN>?
JMSTimeToLive=<SPAN class="code-quote">"<SPAN class="code-object">int</SPAN>"</SPAN>?
JMSPriority=<SPAN class="code-quote">"string"</SPAN>?>
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</headers>?
<operationProperties name=<SPAN class="code-quote">"string"</SPAN> nativeOperation=<SPAN class="code-quote">"string"</SPAN>?>
<headers JMSType=<SPAN class="code-quote">"string"</SPAN>?
JMSCorrelationId=<SPAN class="code-quote">"string"</SPAN>?
JMSDeliveryMode=<SPAN class="code-quote">"string"</SPAN>?
JMSTimeToLive=<SPAN class="code-quote">"<SPAN class="code-object">int</SPAN>"</SPAN>?
JMSPriority=<SPAN class="code-quote">"string"</SPAN>?>
<property name=<SPAN class="code-quote">"NMTOKEN"</SPAN> type=<SPAN class="code-quote">"NMTOKEN"</SPAN>>*
</headers>?
</operationProperties>*
<opertionSelector.jmsdefault/>? | <opertionSelector.jmsUserProp propertyName=<SPAN class="code-quote">"somePropertyName"</SPAN>/>?
<wireFormat.jmsdefault sendFormat+<SPAN class="code-quote">"text|bytes"</SPAN>/>? | <wireFormat.jmsBytes/>? | <wireFormat.jmsBytesXML/>? | <wireFormat.jmsText/>? | <wireFormat.jmsTextXML/>? | <wireFormat.jmsObject/>?
</binding.jms>
</PRE>
</DIV></DIV>
<P><IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/help_16.gif" height="16" width="16" align="absmiddle" alt="" border="0"> See the <A href="http://www.osoa.org/download/attachments/35/SCA_JMSBinding_V100.pdf?version=2" class="external-link" rel="nofollow">JMS Binding Specification 1.0</A> for full details of each of these configuration options.</P>
<P><IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" height="16" width="16" align="absmiddle" alt="" border="0"> Not all these elements are supported by Tuscany. Specifically, the <activationSpec> and <resourceAdapter> elements are not supported as Tuscany does not use JCA or MDBs for its JMS support.</P>
<P><IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" height="16" width="16" align="absmiddle" alt="" border="0"> The create attribute on the destination element is not supported in most environments and all JMS resources (connection factories, queues and topics) need to be pre-configured. An exception to this is when using Apache ActiveMQ as the JMS broker then Tuscany may be able to dynamically create queue and topic resources. This is mainly only useful for unit testing and it is recommended that user applications are designed with the expectation that JMS resources need to be preconfigured.</P>
<P><IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" height="16" width="16" align="absmiddle" alt="" border="0"> the "operationSelector" and "wireFormat" elements are declared in the tuscany namespace (<A href="http://tuscany.apache.org/xmlns/sca/1.0" class="external-link" rel="nofollow">http://tuscany.apache.org/xmlns/sca/1.0</A>). The default operation selection and wire format behvaviour is defined in the <A href="http://www.osoa.org/download/attachments/35/SCA_JMSBinding_V100.pdf?version=2" class="external-link" rel="nofollow">JMS Binding Specification 1.0</A> but we have added a selection of other formats and selectors as alternatives. </P>
<H3><A name="SCAJavabinding.jms-ImplementationNotes"></A>Implementation Notes</H3>
<P>The JMS binding is the first binding where we have started to exploit the binding wire concept. This affects how the JMS binding is implemented.</P>
<P>The addition of a binding wire to the infrastructure allows interceptors to be added that operate on message data in the context of the binding. This allows wire formats to be specified. This is important for bindings like JMS where the data format on the wire does not necessarily follow a well known specification. The default wire format in the Tuscany JMS binding is as described in the SCA JMS specification, i.e. a JMS text message containing XML. However JMS messages using any arbitrary format can be supported by constructing new wire format extensions. </P>
<P>The following diagram shows an overview of how a reference JMS binding may be configured to talk to a service JMS binding using the Text XML wire format. </P>
<P><SPAN class="image-wrap" style=""><IMG src="sca-java-bindingjms.data/jmstextxml-invocation-chain.png" style="border: 0px solid black"></SPAN></P>
<P>In the above diagram, <BR>
1) databinding interceptor normalizes the data into an intermediate format that the binding can understand<BR>
2) wire format interceptor, that is called WireFormat.jmsTextXML, marshals the normalized data into the protocol-specific message, JMSMessage for binding.jms</P>
<P>An example of a composite file which results in this kind of configuration is as follows:</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">//www.osoa.org/xmlns/sca/1.0"</SPAN>
</SPAN> targetNamespace=<SPAN class="code-quote">"http:<SPAN class="code-comment">//helloworld"</SPAN>
</SPAN> xmlns:hw=<SPAN class="code-quote">"http:<SPAN class="code-comment">//helloworld"</SPAN>
</SPAN> name=<SPAN class="code-quote">"helloworld"</SPAN>>
<component name=<SPAN class="code-quote">"HelloWorldReferenceComponent"</SPAN>>
<implementation.java class=<SPAN class="code-quote">"org.apache.tuscany.sca.binding.jms.format.jmstextxml.helloworld.HelloWorldReferenceImpl"</SPAN> />
<reference name=<SPAN class="code-quote">"helloWorldService1"</SPAN> >
<binding.jms>
<destination name=<SPAN class="code-quote">"HelloWorldService1"</SPAN>/>
<wireFormat.jmsTextXML/>
</binding.jms>
</reference>
</component>
<component name=<SPAN class="code-quote">"HelloWorldServiceComponent1"</SPAN>>
<implementation.java class=<SPAN class="code-quote">"org.apache.tuscany.sca.binding.jms.format.jmstextxml.helloworld.HelloWorldServiceImpl"</SPAN> />
<service name=<SPAN class="code-quote">"HelloWorldService"</SPAN>>
<binding.jms>
<destination name=<SPAN class="code-quote">"HelloWorldService1"</SPAN>/>
</binding.jms>
</service>
</component>
</composite>
</PRE>
</DIV></DIV>
<P>Note that <wireFormat.jmsTextXML/> is explicitly specified on the reference binding. As this is the default wire format it can be omitted as is the case on the service binding. </P>
<P>Of course Tuscany already has a databinding framework that is able to transform between datatypes generically. So think of the wire format functionality as performing binding specific transformations. </P>
<P>The following diagram gives an overview of the difference between the databinding and wireformat transformations on the reference side: </P>
<P><SPAN class="image-wrap" style=""><IMG src="sca-java-bindingjms.data/DataFormatScenarios-2-reference.png" style="border: 0px solid black"></SPAN></P>
<P>The following diagram gives an overview of the difference between the databinding and wireformat transformations on the service side:</P>
<P><SPAN class="image-wrap" style=""><IMG src="sca-java-bindingjms.data/DataFormatScenarios-2-service.png" style="border: 0px solid black"></SPAN></P>
<P>When looking at the code itself you will see the following structure:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
binding-jms
The jms binding model
binding-jms-runtime
/org/apache/tuscany/sca/binding/jms/provider
The base JMS binding runtime implementation. Exploits the Tuscany provider pattern.
/org/apache/tuscany/sca/binding/jms/context
A structure that passes the binding context with the message and allows the wire format and operation selection interceptors to <SPAN class="code-keyword">do</SPAN> binding specific things
/org/apache/tuscany/sca/binding/jms/transport
JMS transport processing implmented as an interceptor
/org/apache/tuscany/sca/binding/jms/headers
JMS header processing implmented as an interceptor
/org/apache/tuscany/sca/binding/jms/wireformat
JMS wire format interceptors
/org/apache/tuscany/sca/binding/jms/operationselector
JMS operation selector interceptors
binding-jms-policy
Some base JMS policy implementations
</PRE>
</DIV></DIV>
<P>The providers can be replaced in order to change the way that the JMS binding is constructed. </P>
<P><SPAN class="image-wrap" style=""><IMG src="sca-java-bindingjms.data/providers.png" style="border: 0px solid black"></SPAN></P>
</TD></TR></TBODY></TABLE>
</DIV>
</DIV>
</DIV>
<!-- pageContent macro end -->
</TD>
</TR>
</TABLE>
<!-- footer macro -->
<SCRIPT src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</SCRIPT>
<SCRIPT type="text/javascript">
_uacct = "UA-1174707-5";
urchinTracker();
</SCRIPT>
<A href="http://www.statcounter.com/" target="_blank"><IMG src="http://c26.statcounter.com/counter.php?sc_project=2619156&java=0&security=94bd7e7d&invisible=0" alt="website stats" border="0"></A>
<DIV class="footer">
Copyright � 2003-2012, The Apache Software Foundation </BR>
Apache Tuscany and the Apache Tuscany project logo are trademarks of The Apache Software Foundation.
</DIV>
<!-- footer macro end -->
</BODY>
</HTML>
|
