During this tutorial, you will deploy a Java class as a Web service in WebSphere Application Server. You will use the Stock Quote sample, which is one of the SOAP samples included with the product. Specifically, you will assemble a J2EE application .ear file containing the Stock Quote JavaBean component. Then you will SOAP-enable the .ear file and deploy it in the server runtime. Finally, you will test the enterprise application.
The value of Web services and SOAP technology is that you can take code components that were not previously Web applications -- such as enterprise beans or your Stock Quote sample -- and expose them as services available to HTTP requests (Apache SOAP Remote Procedure Call uses HTTP as its transport). You can do so without rewriting the code, in most cases. For exceptions, see "Creating Type Mappings" in the Apache SOAP 2.2 documentation on the Apache ' Organization Web site. In other words, SOAP can be applied as a transparent wrapper to Web-enable the components.
Note, SOAP message services do have to be aware of SOAP. An option is to write your own SOAP provider to get the message and translate it to match the method expected by the code component (object) that you are calling. For example, this practice could be used for communication between SOAP Messaging and the JMS layer. For more information, see the Apache site.
Use these links to
expand your J2EE vocabulary. These terms are used throughout the
tutorial.
See also the SOAP coverage in the InfoCenter.
You might notice
small discrepancies between the graphics in this tutorial and the actual
product screens as this documentation ages and product fix packs
are issued.
Use the following steps to obtain the SOAP sample server and client code from the soapsamples.ear file provided with the product. Expand the contents of the .ear file into a temporary directory as described here.
product_installation_root\temp
product_installation_root\bin
In this case, it is important to issue the command from bin
because the arguments for the tool will be specified relative to the bin
directory. On other occasions, you can use the tool from any directory, provided
you specify the file paths in the arguments relative to that directory.
earexpander -ear ..\installableApps\soapsamples.ear -expandDir ..\temp\soapsamples -operation expand -expansionFlags war
When you finish, your temp directory will contain the contents of the expanded .ear file.
To learn more about the
tool syntax, type earexpander at a command prompt,
with no arguments. The -expansionFlags war argument is notable.
This tells the tool to expand the .war files, but not the .jar files. If you
see a directory named samples.jar in your temp/soapsamples directory, delete
the soapsamples directory and issue the command again. Pay special attention
to issuing the -expansionFlags war correctly.
For the example used in the tutorial, you can skip this step.
At this point, the code artifact
(in this case, the Stock Quote JavaBean component) is
typically compiled and then packaged into a JAR file. Because the Stock Quote sample is
already packaged into samples.jar, you can skip this step. The samples.jar file is part of
soapsamples.ear, as you will notice by viewing the contents of the expanded .ear file
from the previous step.
The next step is assemble an EAR file (enterprise application) containing the JAR file for the Stock Quote JavaBean component. To do so, you must start the Application Assembly Tool.
product_installation_root/bin
If
using Windows NT or 2000, and you do not see the graphical
interface of the tool right away, check for the minimized tool
on the Task Bar.
Now, create the enterprise application archive (EAR) with the Application Assembly Tool.
samples.jar
file in the list in
the upper right part of the screen.
samples.jar
in
the lower half of the screen.
Advancing
through each panel will give you a good idea of the types of
application characteristics you can configure with this wizard. To learn
more about the wizard, read the help file for the wizard.
The main assembly tool window will display a tree view containing the Stock Quote Sample EAR application.
Note, the context root value is arbitrary.
You will now be able to see the Stock Quote Sample if you expand the assembly tool tree view to show the contents of the Web Modules folder.
Why create a .war file
(Web module archive) if you are not enabling a servlet or JSP file? The Application
Assembly Tool requires the EAR file to contain at least one J2EE archive,
meaning a .war file or an EJB or application client .jar
file. In this case, you will create an empty .war file (Web module) to satisfy
the requirement.
For the example used in the tutorial, you can skip this step.
Before running the
SOAP EAR Enabler tool, typically you must create an Apache SOAP Deployment
Descriptor for each service to be enabled. For the Stock Quote sample,
the deployment descriptor was created for you. To view it:
See also the documentation about Apache SOAP deployment descriptors.
What are descriptors? Where do they originate?
Currently, you can use a text editor to create the descriptor, based on IBM documentation of
Apache SOAP descriptors. Basically, the descriptor is a service definition file
containing the information the SOAP runtime needs to understand how to invoke the service.
In a nutshell, it contains binding information such as:
Save your file and exit the assembly tool.
product_installation_root/temp
WebSphere Application Server provides a Java tool for enabling an interface in an EAR file. This Soap EAR Enabler tool takes as input the Apache SOAP Deployment Descriptor and the EAR file from the previous step.
product_installation_root\bin
In this case, it is important to
issue the command from bin
because the arguments for the tool will be specified relative to the bin
directory. On other occasions, you can use the tool from any directory, provided
you specify the file paths in the arguments relative to that directory.
..\temp\stockquote.ear
What if the tool replies that you should specify
a file that exists? Then your stockquote.ear is not in the temp
directory. Exit the tool, move the file, and try again.
The context root is important when invoking the router servlet from the client.
When the tool has received your answers for all of its questions, it will exit, and the system command prompt will return.
A little bit about the classpath requirement prompt --
the reason for selecting samples.jar is to ensure that the file will be put on the classpath
that the SOAP runtime will see. The samples.jar has to be at the root of the .ear file in order
to show up in the classpath requirements list presented by the EAR Enabler. During the assembly
phase, you might have wondered why, if you had to create an emtpy .war file to satisfy the
assembly tool requirements, that you did not just put the samples.jar inside the .war file. The
samples.jar has to be included outside of a Web module, EJB module, or application client module
in the .ear file, in order to be added to the classpath for the SOAP runtime.
First, start the product administrative server.
product_installation_root/bin
Leave the command window open, as you will use it again later to start the server.
Now it is time to deploy (install) the application in the server runtime. To do so, you will use the administrative console.
product_installation_root/bin
For more information about variations on starting and
stopping the administrative server, see see the corresponding InfoCenter
article.
The application will now be displayed in the console tree view:
Because adding a new application requires
a change to the server configuration, the server must be stopped and started
again to pick up the change. However, there are some types of changes you can
make to an installed application that do not require stopping the server and
starting it again. See the dynamic reloading and hot
deployment documentation for more information.
The SOAP samples come with a script to help you test the sample. The script is preconfigured with the URI of the SOAP router servlet. This URI is based on your specification of the context root when you ran the SOAP Ear Enabler tool (/soapsamples). If you specified a context root other than the default, then you must update the script.
product_installation_root\temp\soapsamples\ClientCode\
StockQuoteSample.bat|shwith the arguments "localhost IBM."
For example, on Windows NT, this would be:
StockQuoteSample localhost IBM
You should receive a current stock quote for IBM stock.
If you receive a connection refused error or connection timed out error, then there could be a problem with your external access to the internet.
If you experience a connection problem, it might have to do with your network's firewall. Try the following:
In the tree view, click Nodes -> your_host_name -> Application Servers. Click the JVM tabbed page of the application server properties.
If using a socks proxy server, add:
-DsocksProxyHost=The name of your socks proxy hostand
-DsocksProxyPort=The number of your socks proxy port
If using an HTTP proxy server, add:
-DproxyHost=The name of your HTTP proxy hostand
-DproxyPort=The number of your HTTP proxy port