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. Saving the server configuration and 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

Start the application server.

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

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

Start the server

  Plan to use the default server configuration file for this tutorial. Other configurations are available, including those that you customize.

  Starting the server from a system command prompt is a method available on all supported operating systems. There are other ways to start the server, as well as variations of the startServer command.

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. Ensure that the Web server is running on the machine containing the console.
  2. Ensure that the product (application server) is also running. Recall, you started it a while ago.
  3. In a Web browser, enter the URL:
     
    http://your_host_name:9090/admin
    
    where your_host_name is localhost if the Web console is on the local machine. On Windows 2000, it has been found that localhost is not always recognized. In such a case, use the actual host name.
  4. Enter an arbitrary login ID.

      Even if you have not secured the console yet, you will be prompted to log in. The login area explains this somewhat. For more information about the use of this ID, see the help for starting and logging into the console. It will also contain any additions, corrections, and details pertaining to the above instructions.

    Console login

  5. Wait for the console to load into the browser.

Starting the administrative console

Installing the EAR file into the server runtime

  1. In the tree view of the console, click:
    Nodes -> your_host_name -> Enterprise Applications
  2. When the application collections view is displayed, click Install.

    Application collections view

  3. Browse for stockquote.ear on your local machine.

    Installation wizard 1

  4. When the path to the .ear file is displayed in the Path field, click Next.
  5. On the Specifying Virtual Host names... panel, keep the default values.
  6. Click Next.
  7. Confirm the settings and click Finish to deploy (install) the application.

  Another method of installing an application is to use the command line application installer tool. If you try it instead, press Enter when prompted whether to use the default host.

Saving the server configuration and regenerating the plug-in configuration

  The administrative console is good at prompting you to take action when you need to do so. In this case, it will now remind you to save your server configuration file and regenerate the configuration of the WebSphere plug-in for the Web server you are using. The prompts are displayed directly below the console menu bar.

  1. Click the first prompt, "Configuration needs to be saved."

    Reminder to save configuration

  2. On the Save Configuration panel, click OK.
  3. Return to the Enterprise Applications collections view where the two prompts were displayed. You should be able to do so by clicking your browser's Back button twice.

    If that does not work, in the tree view of the console, click:
    Nodes -> your_host_name -> Enterprise Applications

  4. Now click the second prompt, "Plug-in configuration needs to be regenerated."
  5. On the Web Server Plug-In Configuration panel, click Generate.
  6. When returned to the Enterprise Applications page, confirm that the prompt now says: New plug-in configuration has been generated.
Stopping the application server and starting it again

  1. In the tree view of the console, click:
    Nodes -> your_host_name -> Application Servers to display the Application Servers collections view, including the Default Server.

    Application Server collection

  2. Click Stop.
  3. Click OK when the screen discussing the implications of stopping the server is displayed.
  4. Close the Web browser.
  5. Start the server, using the startServer script as described earlier in this tutorial.

    The server will issue a confirmation message in the launch window when it has started successfully.

    Confirming that the 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 -> your_server_name -> JVM Settings.

  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 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. Save the server configuration.

      After saving the configuration, you can check what the command line arguments will be, before you start the server. Run the startServer command with the -script argument. This will generate a startup script, from which you can check the accuracy of the command line arguments to ensure they are what you intended. See instructions for starting the server for more information about the -script option and others.

  6. Stop the application server and start it again, as described previously in this tutorial.