6.7.soap: Tutorial -- Deploying a Java class as a Web service using SOAP

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.

Paths through the tutorial

Overview of steps (requires 30 - 60 minutes)

  1. Expanding the enterprise application EAR file (soapsamples.ear)
  2. Assembling the JavaBean into a JAR file
  3. Starting the Application Assembly Tool
  4. Assembling the EAR file containing the JavaBean JAR
  5. Creating an Apache SOAP deployment descriptor
  6. Exiting the Application Assembly Tool, saving your EAR file
  7. SOAP-enabling the services in the EAR file
  8. Starting the server
  9. Starting the administrative console
  10. Installing the EAR file into the server runtime
  11. Regenerating the plug-in configuration
  12. Stopping the application server and starting it again
  13. Testing the Stock Quote service
Background

  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.

Expanding the enterprise application EAR file (soapsamples.ear)

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.

  1. Create a soapsamples subdirectory in the path:
    product_installation_root\temp
    
  2. Change directory to:
    product_installation_root\bin
    

    Note  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.

  3. Expand the EAR file, using the EAR expander tool.

    1. Open a system command prompt.
    2. Issue the command (on a single line, using the appropriate forward or backward slashes for your system):
      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.

Expanded .ear file

Note  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.

Assembling the JavaBean into a JAR file

For the example used in the tutorial, you can skip this step.

Note  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.

Starting the Application Assembly Tool

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.

  1. Open a system command prompt.
  2. Change directory to:
    product_installation_root/bin
    
  3. Enter: assembly

Start the assembly tool

Windows NT or 2000 note  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.

Assembling the EAR file containing the JavaBean JAR

Now, create the enterprise application archive (EAR) with the Application Assembly Tool.

  1. Create a new enterprise application archive (.ear file) containing the sample.jar.

    1. Select the Create Application Wizard.

      Initial screen of assembly tool

    2. In the Specifying Application Properties panel of the wizard, specify information:

      Display name
      Stock Quote Sample EAR
      File name
      stockquote.ear

      Specify EAR file properties

    3. Click Next.
    4. On the Adding Supplementary Files panel of the wizard, click Add.
    5. Browse for and select the directory containing the samples.jar file -- that is, select the temp/soapsamples directory.

      Browse for samples.jar

    6. When you return to the Add Files dialog window:

      • Select the samples.jar file in the list in the upper right part of the screen.
      • Click Add to display the samples.jar in the lower half of the screen.

      Add Files dialog

    7. Click OK to exit the Add Files dialog window and return to the main wizard.

      The samples.jar is listed as a generic file

    8. Click Next until you reach a panel on which you can click Finish. Do so, to exit the wizard.

      Note  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.

  2. As a formality, create a .war file for the enterprise application.

    The main assembly tool window will display a tree view containing the Stock Quote Sample EAR application.

    1. Expand the tree view until you can see the Web Modules folder.
    2. Right-click the folder and select New from the resulting menu.
    3. Specify the general Web module properties.

      File name
      stockquote.war
      Context root
      /stockquote
      Display name
      Stock Quote Sample
    4. Note, the context root value is arbitrary.

    5. Click OK.

    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.

    Note  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.

Creating an Apache SOAP deployment descriptor

For the example used in the tutorial, you can skip this step.

Note  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:

  1. Right-click the Stock Quote Sample EAR application in the assembly tool tree view.
  2. Select View Descriptor from the resulting menu.
  3. When finished viewing the descriptor, click Close.

See also the documentation about Apache SOAP deployment descriptors.

Note  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:

Exiting the Application Assembly Tool, saving your EAR file

Save your file and exit the assembly tool.

  1. Click File -> Save As on the menu bar of the tool.
  2. Save the stockquote.ear file to:
            product_installation_root/temp
            
  3. Click File -> Close on the menu bar of the tool.
  4. If prompted, specify to save your modifications. Then click OK when you receive the message that the "Archive was saved successfully."
  5. Click File -> Exit to exit the Application Assembly Tool.

SOAP-enabling the services in the EAR file

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.

  1. Open a system command prompt.
  2. Change directory to
    product_installation_root\bin
    

    Note  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.

  3. Start the SOAP EAR Enabler tool by typing soapearenabler.
  4. When the tool prompts you for the name of your .ear file, specify (using the correct forward or backward slashes for your system):
    ..\temp\stockquote.ear
    

    SOAP EAR Enabler prompts

      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.

  5. Answer the rest of the questions as you are prompted to do so. For readability, the following responses are shown on a separate line from the questions. When using the tool, you must enter your answer directly at the end of the question (on same line, with no spaces preceding your answer).

    How many services would you like your application to contain (1...n)?
    1
    Now prompting for info for service #1: Please enter the file name of the SOAP deployment descriptor xml file:
    ..\temp\soapsamples\ServerSamplesCode\src\stockquote\DeploymentDescriptor\stockquote.xml
    Is this service an EJB (y= yes/n= no)?
    n
    How many jar files are required for this service (0...n)?
    1
    Classpath requirement #1: Please choose a file ([1] samples.jar, [2] stockquote.war):
    1
    Should this service be secured (y/n)?
    n
    Please enter a context root for your non-secured services (e.g. /soap):
    /soapsamples

      The context root is important when invoking the router servlet from the client.

    Do you wish to install the administration client? Warning! You should not install this client in a production ear unless you intend to secure the URI to it. Install the administration client (y= yes/n= no)?
    y

When the tool has received your answers for all of its questions, it will exit, and the system command prompt will return.

SOAP EAR Enabler prompts

  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.

Starting the server

First, start the product administrative server.

  1. Open a system command prompt.
  2. Change directory to:
    product_installation_root/bin
    
  3. Enter: adminserver

Leave the command window open, as you will use it again later to start the server.

Start the server

Starting the administrative console

Now it is time to deploy (install) the application in the server runtime. To do so, you will use the administrative console.

  1. Open a system command prompt.
  2. Change directory to:
    product_installation_root/bin
    
  3. Enter: adminclient

Starting the console

  For more information about variations on starting and stopping the administrative server, see see the corresponding InfoCenter article.

Installing the EAR file into the server runtime

  1. Select Console -> Wizards -> Install Enterprise Application from the console menu bar to display the first panel of the wizard.
  2. In the Specifying the Application or Module panel of the wizard:

    1. Ensure that the Browse for file on node field is set to your current node.
    2. Ensure Install Application is selected.
    3. Click Browse, next to the Path field. Browse for the stockquote.ear file and select it. Verify that its name is displayed in the Path field now.
    4. Click Next.
    5. Continue clicking Next to proceed through the panels until you reach the Selecting Virtual Hosts for Web Modules panel.
    6. On the Selecting Virtual Hosts for Web Modules panel, verify that the Web modules are using the "default_host."

      Selecting Virtual Hosts for Web Modules panel

  3. Click Next to proceed until you are able to click Finish to exit the wizard.

The application will now be displayed in the console tree view:

New application in console tree view

Regenerating the plug-in configuration

  1. In the console tree view, right-click WebSphere Administrative Domain -> Nodes -> your_host_name.
  2. From the resulting menu, select Regen Webserver Plugin.
  3. In the area at the bottom of the console, look for the Event Message saying that the Plugin regeneration has been completed. It might take a moment before it is displayed.
Stopping the application server and starting it again

  1. In the console tree view, right-click WebSphere Administrative Domain -> Nodes -> your_host_name -> Application Servers -> Default Server.
  2. From the resulting menu, click Stop.
  3. Look for the message that the server was stopped successfully.

    Server stopped

  4. Now right-click Default Server again and click Start on the resulting menu.
  5. Again, wait for the confirmation message.

    Server started

  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.

Testing the Stock Quote service

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.

  1. Open a system command prompt.
  2. Change directory to:
    product_installation_root\temp\soapsamples\ClientCode\
    
  3. Change directory to where the scripts are located, for your operating system.

  4. Invoke the script:
    StockQuoteSample.bat|sh 
    
    with 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.

Successful reply of StockQuoteSample

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.

Workaround

If you experience a connection problem, it might have to do with your network's firewall. Try the following:

  1. Start the product.
  2. Open the administrative console.
  3. Access the JVM command line settings.

    In the tree view, click Nodes -> your_host_name -> Application Servers. Click the JVM tabbed page of the application server properties.

  4. At the front of the field for entering command line arguments, set the arguments for the socks or HTTP proxy hosts and ports. Enter the value in the Generic Command Line Arguments field.

    If using a socks proxy server, add:

    -DsocksProxyHost=The name of your socks proxy host
    
    and
    -DsocksProxyPort=The number of your socks proxy port
    

    If using an HTTP proxy server, add:

    -DproxyHost=The name of your HTTP proxy host
    
    and
    -DproxyPort=The number of your HTTP proxy port
    
  5. Stop the application server and start it again, as described previously in this tutorial.