Enabling Apache SOAP Web services in an enterprise application

The Simple Object Access Protocol (SOAP) EAR enabler tool is a Java application that enables a set of SOAP services within an enterprise archive file.

The SoapEAREnabler (SEE)tool guides you through the required steps to enable one or more services within an application. The tool makes a backup copy of your original EAR file in the event you need to remove or add services at a later time.

Before invoking the SEE tool, create an SOAP deployment descriptor for each service to be enabled.

Follow these steps to enable a Web service:

 

  1. Invoke the SEE tool from was_install/bin directory using one of the following commands:

    • Use the command SoapEarEnabler on the Windows platform

    • Use the command SoapEarEnabler.sh on UNIX platforms.

  2. Start with an existing EAR file, either one created with the Application Assembly Tool (AAT), or a previously-created, valid, J2EE-compliant EAR file.

    The SEE tool will not accept a SOAP-enabled EAR file as input.

  3. After you enable Web services, install the EAR file in WebSphere Application Server.

  4. You will be prompted as to whether you wish to add the administration client to the EAR. This is a Web-based client that will allow you to list all active services for a specific context from a browser window. With this interface, you can stop and start existing services. You might choose to not add this interface for security reasons, or you might want to secure the interface before making a service available.

 

What to do next

You have invoked the SEE from the WebSphere Application Server bin directory and now know how the tool operates and its prompts and commands.

The tool operates in two modes:

  1. Interactive

  2. Silent

Specify all required command line arguments to use the tool in silent mode.

In interactive mode, the SEE tool prompts all required information. The following dialog is an example of using the tool in interactive mode.

Note: In this dialog, user input is in italics, and tool output is in bold. 

SoapEarEnabler (On Windows NT)
SoapEarEnabler.sh (On UNIX platforms)

Please enter the name of your ear file:
 ..\work\stockquote.ear

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:

 ..\work\StockQuoteDD.xml
Is this service an EJB (y=yes / n=no)?
 n

If there are  additional jar files that need to be added to the classpath, specify the number to add (answer 0 for none) (0...n)?
 1

Classpath addition 1: Here are all the archive files found, please choose one to add to the classpath:   ([1] samples.jar, [2] stockquote.war):
         1

Should this service be secured ("y/n" versus "y= yes, n= no)?
n

Please enter a context root for your non-secured
services (e.g. /soap):
 /soapsamples

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/n" versus "y= yes, n= no)?
         y

In Silent mode, supply the arguments in the same order as for the interactive prompts.

Note: In silent mode, the SOAP administrative GUI will not install. Also, you will not be prompted for the SOAP administrative GUI.

The following example describes how to to use the tool in silent mode: 

soapearenabler [args]
 where the arguments
must be specified in the following order:
<ear-file-name>
<number-of-services>
The following block is repeated based on
the number of services specified.
<deployment-descriptor-file-name>
<service-is-an-ejb-(y/n)>
The following argument should be supplied
only if service-is-an-ejb-(y/n) is y.
<ejb-jar-file-uri-(already-in-ear)>
<number-of-additional-jar-files
(0, 1, 2...)>
The following argument is repeated number-of-additional-jar-files
times.
<classpath-entry-uri-(already-in-ear)>
<secure-this-service-(y/n)>
This following argument is supplied only
if secure-this-service-(y/n) is n for any
service.
<context-root-for-non-secured-services,
ex: /soap>
This following argument is supplied only
if secure-this-service-(y/n) is y for any
service.
<context-root-for-secured-services, ex:
/soapsec>

Examples

Silent mode example

The following is an example of deploying one enterprise bean as a non-secured service: 

soapearenabler soap.ear 1 
         d:\xml-soap\java\samples\ejbadder\deploymentdescriptor.xml
y adderservice-ejb.jar 1 samples.jar n /soap

The following is an example of deploying one enterprise bean as a non-secured service, and one Java class as a secured service: 

soapearenabler soap.ear 2 
          d:\xml-soap\java\samples\ejbadder\deploymentdescriptor.xml
y adderservice-ejb.jar 1 samples.jar n 
          d:\xml-soap\java\samples\stockquote\deploymentdescriptor.xml
n 1 samples.jar y /soap /soap-sec

Deploying two Java classes as non-secured services example 

soapearenabler soap.ear 2 
          d:\xml-soap\java\samples\stockquote\deploymentdescriptor.xml
n 1 samples.jar n 
          d:\xml-soap\java\samples\addressbook\deploymentdescriptor.xml
n 1 samples.jar n /soap

The line breaks in the above examples have been modified for this documentation. Typically, commands are issued on a single line.

Deploying Apache SOAP Web services applications
Assembling Apache SOAP Web services

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.