nmukhi 2003/01/16 10:07:28
Modified: java/samples/jms README.html ServiceAvailability.wsdl
java/samples/jms/client/dynamic README.html
java/samples/jms/client/stub README.html
java/samples/jms/service README.html
Added: java/samples/jms/client/jboss_setup README.html
java/samples/jms/service/deploy/jboss README.html
Log:
Changed JMS sample docs to separate JBoss-specific instructions
Revision Changes Path
1.4 +1 -1 xml-axis-wsif/java/samples/jms/README.html
Index: README.html
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/samples/jms/README.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- README.html 27 Dec 2002 17:52:06 -0000 1.3
+++ README.html 16 Jan 2003 18:07:27 -0000 1.4
@@ -13,7 +13,7 @@
<p>In this sample shows how we can invoke systems implemented using
message-oriented middleware (MoM) using JMS through the WSIF API. As always, the WSIF
API hides all the protocol-specific (in this case, JMS) details; we use the same,
WSDL-driven consistent view of the software. The key here is the WSIF defines a <a
href="../../doc/wsdl_extensions/jms_bindings.htm">JMS binding</a> that lets us maps
abstract messages to JMS messages, use JMS headers, properties, etc. The
<tt><port></tt> section of the WSDL will then refer to a message queue as the
target of the request messages, along with the required JNDI information to locate the
queue dynamically.</p>
<p>Our particular example is a very simple service. The purpose of the service is
to inform users whether DSL service is available at a particular zip code or not. It
exposes a single port type which offers one operation called
<tt>checkAvailability</tt>. This operation takes as input a message with a single part
(a string), representing the zip code, and returns as output a string whose value will
be either true or false, depending on whether DSL service is available or not.</p>
<p>The JMS binding for the service uses JMS text messages for communication. The
WSIF JMS provider handles conversion of the abstract invocation to the sending of a
JMS message to the desired destination queue, as specified in the WSDL. The return
message is received over a temporary queue and returned to the application that made
the invocation. From the application's viewpoint, it looks like a synchronous
invocation; at the lower (JMS) level, it is really asynchronous.</p>
-<p><a href="ServiceAvailability.wsdl">Here</a> is the service WSDL. Note the JMS
binding and the endpoint details for the service. The endpoint information specifies
that the service will listen for messages sent to a queue; the queue can be looked up
using the JNDI name <tt>queue/A</tt>. The initial context factory specified is
vendor-specific. So you may need to edit these fields dependong on how you deploy your
service.</p>
+<p><a href="ServiceAvailability.wsdl">Here</a> is the service WSDL. Note the JMS
binding and the endpoint details for the service. The endpoint information specifies
that the service will listen for messages sent to a queue; the queue can be looked up
using the JNDI name <tt>queue/A</tt>. The initial context factory specified is
vendor-specific, see intructions in the service README below that tell you how to fill
in these fields for particular app server environments.</p>
<p><a href="service/README.html">Here</a> are details on how the service is
implemented and deployed so that it is accessible using JMS. These details include
instructions on how to deploy the service in your favorite J2EE server.</p>
<p>Once your service is deployed and available using JMS, you can use WSIF's
dynamic invocation API to use it, as described <a
href="client/dynamic/README.html">here</a>.</p>
<p><a href="client/stub/README.html">Here</a> is how you can pregenerate stubs to
access the same service using a stub API, resulting in a client application that deals
with a simple service interface instead of WSIF-specific code.</p>
1.2 +3 -2 xml-axis-wsif/java/samples/jms/ServiceAvailability.wsdl
Index: ServiceAvailability.wsdl
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/samples/jms/ServiceAvailability.wsdl,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ServiceAvailability.wsdl 27 Dec 2002 17:52:06 -0000 1.1
+++ ServiceAvailability.wsdl 16 Jan 2003 18:07:27 -0000 1.2
@@ -44,10 +44,11 @@
<service name='CheckServiceAvailability'>
<port name='CheckAvailabilityPort'
binding='tns:CheckAvailabilityJMSBinding'>
+ <!-- vendor-specific deployment information needs to be entered here -->
<jms:address destinationStyle="queue"
jndiDestinationName="queue/A"
- jndiConnectionFactoryName="ConnectionFactory"
- initialContextFactory="org.jnp.interfaces.NamingContextFactory"
+ jndiConnectionFactoryName=""
+ initialContextFactory=""
jndiProviderURL="localhost"/>
</port>
</service>
1.3 +6 -1 xml-axis-wsif/java/samples/jms/client/dynamic/README.html
Index: README.html
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/samples/jms/client/dynamic/README.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- README.html 27 Dec 2002 20:47:21 -0000 1.2
+++ README.html 16 Jan 2003 18:07:27 -0000 1.3
@@ -10,7 +10,12 @@
<h2>
Web Services Invocation Framework:<br>
Invoking the JMS Sample using WSIF's dynamic invocation interface</h2>
-<p>First you need to <a href="../../../../doc/samples.html">set up the CLASSPATH in
your environment</a>. Beyond the standard classpath setting, you also need to add the
J2EE client jar files to your classpath. The set of J2EE client JARs is vendor
specific; refer to the documentation in your application server on how to set up the
environment for an EJB client, and add the JAR files specified. For JBoss users, we
have included a script to set up the client environment. To run this script, make sure
you are in your base WSIF directory (the one that contains the <tt>classpath.bat</tt>
script. Set the variable <tt>JBOSS_HOME</tt> to point to your JBoss installation. From
there, run the command <tt>samples\ejb\client\jboss_setup\jboss.bat</tt>. This sets up
the entire client classpath required to run the sample using JBoss client JAR
files.</p>
+<p>First you need to <a href="../../../../doc/samples.html">set up the CLASSPATH in
your environment</a>. Beyond the standard classpath setting, you also need to add the
J2EE client jar files to your classpath. The set of J2EE client JARs is vendor
specific. We have included below instructions for some app servers, follow that link
if you happen to be using one of those, otherwise refer to the documentation in your
application server on how to set up the environment for a JMS client.</p>
+<p><b>Setting up the client on some app servers</b>
+<ul>
+ <li><a href="../jboss_setup/README.html">JBoss setup</a></li>
+</ul></p>
+<p><b>Running the client</b>
<p>To invoke this sample using WSIF's DII, run the DynamicInvoker class. Specify as
command line arguments the location of the WSDL file for the jms sample followed by
the operation you wish to invoke and the zip code you are interested in. For example,
<br><tt>java clients.DynamicInvoker samples/jms/ServiceAvailability.wsdl
checkAvailability 10050</tt></p>
<p>To see details of how the WSIF API is used to make invocations dynamically, take
a look at the code for the <a
href="../../../clients/DynamicInvoker.java">DynamicInvoker class</a>.</p>
<hr width="100%">
1.1 xml-axis-wsif/java/samples/jms/client/jboss_setup/README.html
Index: README.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Nirmal Mukhi">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: Samples</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2"
marginheight="2">
<h2>
Web Services Invocation Framework:<br>
Setting up the EJB Sample in a JBoss client environment</h2>
<ul>
<li>Setting up the classpath: We have written a script to set up the client
environment. To run this script, make sure you are in your base WSIF directory (the
one that contains the <tt>classpath.bat</tt> script. Set the variable
<tt>JBOSS_HOME</tt> to point to your JBoss installation. From there, run the command
<tt>samples\ejb\client\jboss_setup\jboss.bat</tt>. This sets up the entire client
classpath required to run the sample using JBoss client JAR files.</li>
</ul>
</body>
</html>
1.3 +6 -1 xml-axis-wsif/java/samples/jms/client/stub/README.html
Index: README.html
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/samples/jms/client/stub/README.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- README.html 27 Dec 2002 20:47:22 -0000 1.2
+++ README.html 16 Jan 2003 18:07:27 -0000 1.3
@@ -10,7 +10,12 @@
<h2>
Web Services Invocation Framework:<br>
Invoking the JMS Sample through a high level stub interface</h2>
-<p>First you need to <a href="../../../../doc/samples.html">set up the CLASSPATH in
your environment</a>. Beyond the standard classpath setting, you also need to add the
J2EE client jar files to your classpath. The set of J2EE client JARs is vendor
specific; refer to the documentation in your application server on how to set up the
environment for an EJB client, and add the JAR files specified. For JBoss users, we
have included a script to set up the client environment. To run this script, make sure
you are in your base WSIF directory (the one that contains the <tt>classpath.bat</tt>
script. Set the variable <tt>JBOSS_HOME</tt> to point to your JBoss installation. From
there, run the command <tt>samples\ejb\client\jboss_setup\jboss.bat</tt>. This sets up
the entire client classpath required to run the sample using JBoss client JAR
files.</p>
+<p>First you need to <a href="../../../../doc/samples.html">set up the CLASSPATH in
your environment</a>. Beyond the standard classpath setting, you also need to add the
J2EE client jar files to your classpath. The set of J2EE client JARs is vendor
specific. We have included below instructions for some app servers, follow that link
if you happen to be using one of those, otherwise refer to the documentation in your
application server on how to set up the environment for a JMS client.</p>
+<p><b>Setting up the client on some app servers</b>
+<ul>
+ <li><a href="../jboss_setup/README.html">JBoss setup</a></li>
+</ul></p>
+<p><b>Running the client</b>
<p>This directory contains a file called <tt>Run.java</tt> that contains the
<tt>main</tt> method. This is the logic that uses the generated stub interface to run
the sample. So you can run this class, specifying on the command line the location of
the WSDL file for the sample and the zip code you are interested in. For example, <br>
<tt>java jms.client.stub.Run samples/jms/ServiceAvailability.wsdl 10050</tt></p>
<p>To generate the stub interface, you can use any tool that generates Java
interfaces for WSDL services using their port type descriptions. WSDL2Java, which is
packaged with Axis, unfortunately does not work since the presence of a JMS binding in
the WSDL confuses it, so we actually wrote our stub interface by hand. It is available
<a href="org/apache/xml/CheckAvailabilityPortType.java">here</a>. Note that WSIF
assumes a correspondence between the generated Java interface and the WSDL port type
that has its abstract description as specified in the JAX-RPC specification.<br>
1.2 +1 -2 xml-axis-wsif/java/samples/jms/service/README.html
Index: README.html
===================================================================
RCS file: /home/cvs/xml-axis-wsif/java/samples/jms/service/README.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- README.html 27 Dec 2002 17:52:07 -0000 1.1
+++ README.html 16 Jan 2003 18:07:28 -0000 1.2
@@ -12,7 +12,6 @@
Implementing the JMS service</h1>
<p>The JMS service is implemented as a message driven bean (MDB). In case you need
to learn more about MDBs, you can refer to various guides and tutorials available for
free online; I found <a
href="http://www.onjava.com/pub/a/onjava/excerpt/ejb3_ch13/index.html";>this excerpt
from Richard Monson-Haefel's EJB book</a> useful.</p>
<p>The bean implementation is very simple. It acts as a message listener (the queue
is determined by the deployment files). When a message is delivered, it extracts the
body (recall that we are using JMSTextMessages to communicate back and forth since we
are just exchanging strings). This is presumably a valid zip code, so the bean makes
it an integer in an unsafe and intrepid manner. Here is applies some logic to
determine whether DSL service is available at this zip code or not. A real-world
implementation would invariably refer to some backend database using JDBC or do
something similarly smart. Our implementation, being just a sample, returns true for
all zip codes < 5000, and false otherwise. The return message is sent to the queue
specified in the <tt>replyTo</tt> field of the request message. Note that the bean
must encode the correct <tt>JMSCorrelationID</tt> in the return message in order for
it to be picked up by WSIF. <a href="ServiceAvailabilityBean.java">Here</a> is the
code for our MDB.</p>
-<p>The <tt><a href="deploy">deploy</a></tt> subdirectory contains the things
necessary to deploy this MDB to your favorite application server. Generally to deploy
your MDB you will need to compile the code for this sample, then package it into a JAR
along with the <tt><a href="deploy/jboss/ejb-jar.xml">ejb-jar.xml</a></tt> file. Your
application server may need other files. We have included under the
<tt>deploy/jboss</tt> directory a pre-packaged jar that contains the compiled beans
and the configuration files required by JBoss. All you need to deploy to JBoss is to
drop this <a href="deploy/jboss/serviceavailability.jar">serviceavailability JAR file
for JBoss</a> (assuming you use the default server configuration) into
server/default/deploy under your JBoss server installation, and start your server.
This has been tested with JBoss version 3.0.4 running on Windows 2000, with the sample
client running on Windows 2000 and using WSIF in a Java 1.4.1 environment.</p>
-<p>Remember that you may need to modify the <a
href="../ServiceAvailability.wsdl">service WSDL</a> once you have completed your
deployment so that the endpoint information settings correspond to your deployment
(this is not necessary if you use JBoss in its default configuration).</p>
+<p>The <tt><a href="deploy">deploy</a></tt> subdirectory contains the things
necessary to deploy this MDB to your favorite application server. Generally to deploy
your MDB you will need to compile the code for this sample, then package it into a JAR
along with the <tt><a href="deploy/jboss/ejb-jar.xml">ejb-jar.xml</a></tt> file. Your
application server may need other files, take a look at app server specific
instructions under the deploy directory. You will also need to fill in the vendor
specific deployment information in the sevice WSDL, instructions for which you will
also find under the deploy directory.
<hr width="100%">
</body></html>
1.1 xml-axis-wsif/java/samples/jms/service/deploy/jboss/README.html
Index: README.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Nirmal Mukhi">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Web Services Invocation Framework: Samples</title>
<link rel="stylesheet" href="wsif.css" type="text/css"></head>
<body alink="#0000ff" bgcolor="#ffffff" leftmargin="2" topmargin="2" marginwidth="2"
marginheight="2">
<h2>
Web Services Invocation Framework:<br>
Deploying the EJB Sample in a JBoss environment</h2>
<ul>
<li>Deploying the sample:
We have included in this directory a pre-packaged jar that contains the compiled
beans and the configuration files required by JBoss. All you need to deploy to JBoss
is to drop this <a href="serviceavailability.jar">serviceavailability JAR file for
JBoss</a> (assuming you use the default server configuration) into
<tt>server/default/deploy</tt> under your JBoss server installation, and start your
server. This has been tested with JBoss version 3.0.4 running on Windows 2000, with
the sample client running on Windows 2000 and using WSIF in a Java 1.4.1
environment.</li>
<li>Configuring the WSDL: Under the <tt><port></tt> section of the <a
href="../../../ServiceAvailability.wsdl">ServiceAvailability WSDL</a> file, stick in
the following deployment information, which is specific to deployment in a JBoss
environment:
<p><tt><pre>
<!-- JBoss specific JMS endpoint -->
<jms:address destinationStyle="queue"
jndiDestinationName="queue/A"
jndiConnectionFactoryName="ConnectionFactory"
initialContextFactory="org.jnp.interfaces.NamingContextFactory"
jndiProviderURL="localhost"/>
</pre></tt></p></li></ul></body>
</html>
