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
|
Qpid JCA Example
Overview
=======
The Qpid JCA example provides a sample JEE application that demonstrates how to
configure, install and run applications using the Qpid JCA adapter for EE
connectivity and the Apache Qpid C++ Broker. This example code can be used as a
convenient starting point for your own development and deployment
efforts. Currently the example is supported on JBoss EAP 5.x, JBoss 6.x and
Apache Geronimo 2.x.
Example Components
===================
Currently the example application consists of the following components:
Destinations and ConnectionFactories
Any messaging application relies on destinations (queues or topics )
in order to produce or consume messages.The Qpid JCA example provides
five destinations by default:
HelloTopic
GoodByeTopic
HelloGoodByeTopic
HelloQueue
GoodByeQueue
QpidResponderQueue
Similar to destinations, ConnectionFactories are a core component of both JMS
and JCA. ConnectionFactories provide the necessary starting point to make a connection,
establish a session and produce or consume (or both) messages from your JMS provider.
The Qpid JCA example provides three connection factories by default:
QpidJMSXA
QpidJMS
QpidConnectionFactory
Each of these ConnectionFactories varies in their capabilities and the context in which
they should be used. These concepts will be explained later in this document.
The deployment configuration for destinations, and ConnectionFactories varies by platform.
In JBossEAP, the configuration mechanism is a *-ds.xml file. Geronimo 2.2.x has the notion
of a deployment plan in the form of a geronimo-ra.xml file.
The Qpid JCA Example provides both a qpid-jca-ds.xml file as well as a geronimo-ra.xml deployment
plan. Both mechanisms provide a reasonable set of defaults to allow you to deploy the Qpid JCA
adapter in either environment and get up and running quickly.
EJB 3.x
There are a six EJB 3.x components provided as part of the example.
QpidHelloSubscriberBean - MessageDrivenBean (MDB)
QpidGoodByeSubscriberBean - (MDB)
QpidHelloListenerBean - (MDB)
QpidGoodByeListenerBean - (MDB)
QpidJMSResponderBean - (MDB)
QpidTestBean - Stateless Session Bean (SLSB)
Servlet 2.5
QpidTestServlet
A sample EE 2.5 servlet is provided allowing testing from a browser versus a JNDI
client
EE EAR archive
An EAR wrapper for the ejb and web components.
An RMI client used to excercise the EJB 3.x component.
Sample *-ds.xml file
A sample *-ds.xml file is provided to create destinations and ManagedConnectionFactories
in the JBoss environment.
Sample geronimo-ra.xml
A sample geronimo-ra.xml file is provided to create destinations and ManagedConnectionFactories
in the Geronimo environment. This file is semantically equivalent to the JBoss *-ds.xml artifact.
A build.xml file
An ant build.xml file to configure, install and deploy the aforementioned components.
Requirements
============
Depending upon your target platform (eg. JBoss EAP or Geronimo) you will need to set either
the JBOSS_HOME or GERONIMO_HOME property. By default, these properties are assumed to be
set from your environment. This can be modified in the build.xml file.
JBoss EAP 5.x, JBoss 6.x
To use the sample application you will need to have JBoss EAP 5.x or JBoss 6.x running.
Geronimo 2.x
To use the sample application you will need to have Geronimo 2.x running.
Apache Qpid Broker
To run the sample it is assumed you have an Apache Qpid C++ broker configured and running.
The example code assumes that the broker will run at localhost on port 5672. This can be
modified within the build.xml file if this does not suit your particular environment.
Quickstart
==========
After satifsying the above requirements you are ready to deploy and run the example application.
The steps to deploy and run in the supported application servers are largely the same, however,
if you are targeting JBoss you will either need to modify the property in the example build.xml file
<property name="target.platform" value="geronimo"/>
to be jboss
<property name="target.platform" value="jboss"/>
or set this property via the command line.
Example:
ant -Dtarget.platform=jboss <target>
**Note**
Any time you wish to change platforms, this property needs to be modified and a complete clean
and rebuild needs to be performed.
Step 1 -- Package, Deploy and configure the Qpid JCA adapter
The core component of the example is the Qpid JCA adapter. The following lists the steps
for the respective platforms
**Note**
Regardless of platform, if you are building the Qpid JCA adapter from source code
you will need to use to package the RAR file via the Ant build system. To do this, from
the example directory execute
ant deploy-rar
This task packages the adapter and includes the necessary dependent jar files.
JBoss
There are no additional steps to package the adapter for JBoss deployment. Simply copy
the qpid-ra-<qpid.version>rar to your JBoss deploy directory.
To configure the Qpid JCA Adapter in JBoss the *-ds.xml file mechanism is used. A sample
file is provided in the conf directory.
If the defaults are suitable, you can simply execute
ant deploy-ds
While any property can be modified in the qpid-jca-ds.xml file, typically you will want to
change the URL of the broker to which you are trying to connect. Rather than modifying
the qpid-jca-ds.xml file directly you can modify the
<property name="broker.url" value="amqp://anonymous:@client/test?brokerlist='tcp://localhost:5672?sasl_mechs='ANONYMOUS''"/>
line in the build.xml file. This will dynamically insert the broker.url value into the qpid-jca-ds.xml file.
Once this file is copied to your JBoss deploy directory and you received no exceptions, the adapter is now deployed, configured
and ready for use.
Geronimo
By default, the Qpid JCA adapter ships with the geronimo-ra.xml deployment plan embedded
in the RAR file. This file is located in the META-INF directory alongside the ra.xml file.
By default the adapter is configured to access a broker located at localhost with the
default port of 5672. The ANONYMOUS security mechanism is also in use. If this is not
desirable, you have two approaches to configure the adapter.
1) Extract the META-INF/ra.xml file from the RAR file, modify and recompress the RAR archive
with the updated contents.
2) Use the example build system to package the adapter. The example build.xml file includes
a target
package-rar
that can be used to package the RAR file as well as allowing changes to the geronimo-ra.xml
file without having to extract the RAR file by hand. The conf/geronimo-ra.xml file is used
when you use the example build system.
While any property can be modified in the geronimo-ra.xml file, typically you will want to
change the URL of the broker to which you are trying to connect. Rather than modifying
the geronimo-ra.xml file directly you can modify the
<property name="broker.url" value="amqp://anonymous:@client/test?brokerlist='tcp://10.0.1.44:5672?sasl_mechs='ANONYMOUS''"/>
line in the build.xml file. This will dynamically insert the broker.url value into the geronimo-ra.xml file.
Once you have made your modifications you can execute
ant clean package-rar deploy-rar
Note, your Geronimo server must be running and your GERONIMO_HOME environment variable must be set. Barring any exceptions, the
adapter is now deployed and ready for use in Geronimo.
Step 2 -- Deploy the application component(s).
As previously mentioned, the adapter comes with a variety of EE components for use in your respective application server. You can choose to deploy
these components individually, or as a single EAR archive. This document assumes that you will use the EAR to deploy and run the example.
The command to package and deploy the EAR archive is the same across application servers. Executing the following command
ant deploy-ear
will, depending upon platform, package the EAR and deploy the archive in your respective environment. Once this step is executed, the example
is ready for use.
Step 3 -- Test the Example
The Qpid JCA example provides an EJB application, as well as a Web application. Both can be used to test/run the example:
EJB
If you want to use the EJB application to test the example you can execute
ant run-client
Running this command will perform a JNDI lookup of the SLSB in either JBoss or Geronimo and send a simple string to the SLSB. The SLSB will receive
this string, construct a JMS message and place this message on a configured queue. The MDB will in turn receive this message and print the contents
to the console.
The main properties involved in this task are
server.host
jndi.context
These vary depending upon which application server you are runnning. These can be modified to suit your environment. Looking at the run-client task you
will see the following:
<sysproperty key="qpid.ejb.name" value="qpid-jcaex/QpidTestBean/remote"/>
This is the JNDI name of the SLSB component and it varies by application server. Typically you do not have to change this. Also, the task supports another property
<sysproperty key="qpid.message" value="insert-value-here"/>
You can set this property if you want to modify the message contents being routed through the system.
Web
The Qpid JCA Example comes with a web application. To access the web component, simply use a browser of your choice and navigate to
http://<server-host-name>:<server-port>/qpid-jca-web/qpid
where server-host and server-port are the host and port where you are running your application server. By default this is localhost:8080. Similar to the EJB component,
the web application supports a few options:
http://<server-host-name>:<server-port>/qpid-jca-web/qpid?messsage=<yourmessage>
will allow you to customize the message contents that are routed through the system. By default, the Web application posts to a configured queue in the system. If you want to
test XA functionality, or use an alternate approach, you can specify
http://<server-host-name>:<server-port>/qpid-jca-web/qpid?useEJB=true
instead of posting to a queue, the web application will use the local interface of the EJB component to send the message. This is functionally equivalent to running the
RMI client.
Summary
=======
While conceptually simple, the Qpid JCA example provides a majority of the component types and messaging patterns you are most likely to use your development efforts.
With the Web and EJB components, you can experiment with various aspects of JCA as well as EE development in general using the Qpid Broker as your messaging provider.
While this documentation highlights the major components and steps needed to take to get the example running, the possiblities for modifcation are numerous. You are
encouraged to experiment with the example as you develop your own messaging applications.
|
