HP OpenVMS Systems

SOAP Toolkit (based on Apache Axis)

Simple Object Access Protocol (SOAP) toolkit

May 2003
Version 1.1
Based on Apache SOAP Version 2.3.1

Contents:
» before installing the SOAP toolkit

» hardware prerequisites
» software prerequisites -- client
» software prerequisites -- server

» downloading and installing the SOAP toolkit

» downloading the kit
» expanding the kit
» removing the previous version
» installing the kit

» after installing the SOAP toolkit
» release notes

» support for SSL in the SOAP toolkit
» proxy setup

» support

Before Installing the SOAP toolkit

Hardware Prerequisites

The SOAP Toolkit for OpenVMS is available only on the Alpha platform.
Disk Space Requirements
Downloading the SOAP Toolkit for OpenVMS Java archive (JAR) file requires approximately 7500 blocks (3.3 Mb) of disk space. Expanding the JAR file requires an additional 8000 blocks.
The installation procedure allows you to choose to install some or all of the SOAP components. The total disk space required is approximately 16,000 to 30,000 blocks, depending on the installation options you choose.

Software Prerequisites - Client

The following software is required to configure a SOAP Client:
OpenVMS Alpha Version 7.2-2 (or higher)
» Software Development Kit (SDK) for the Java™ Platform Version 1.3.1 (or higher)
» All patches required for SDK for the Java™ Platform. Check the SDK documentation for the version of Java you are installing to be sure that you have all prerequisite OpenVMS Alpha patches.
Installing on an ODS-5 enabled disk is recommended. Because of long file names and directory depth issues, the installed code base and the accompanying documentation cannot be guaranteed to function properly in a non-ODS5 environment.

Software Prerequisites - Server

The following software is required to configure a SOAP Server.
» all of the SOAP client prerequisites
» HP Secure Web Server (SWS) version 1.2 (or higher) for OpenVMS Alpha
» CSWS_JAVA version 2.0 (or higher) for Secure Web Server for OpenVMS Alpha, with MOD_JK enabled

Downloading and Installing the SOAP toolkit

Downloading the kit

The SOAP Toolkit for OpenVMS software is available for the Alpha platform as a Java archive (JAR) file.
Please fill out and submit the SOAP Toolkit for OpenVMS registration form. You will receive an email message with the URL of the location of the kit to download.

See Disk Space Requirements for required disk space.

Expanding the kit

To expand the SOAP Toolkit for OpenVMS JAR file, perform the following steps:
Invoke the appropriate Java setup procedure for the installed version of Java, if this has not already been done. See SYS$MANAGER:JAVA$*SETUP.COM (for example, SYS$MANAGER:JAVA$131_SETUP.COM).
Set default to a directory on the ODS-5 disk where the installation files can be extracted. (This can be the directory that you want to be the base directory for the SOAP kit, or you can extract the files to a different directory. The installation procedure verifies that this is the correct directory used for the extraction, and will ask you if you want to install in a different directory.)
For example:
  $ SET DEFAULT ODS5_DISK:[TEMP]
Enter the following command to extract relevant files from the SOAP kit. In this example, the JAR file was downloaded to TEMP_DISK:[DOWNLOADS].
  $ jar -xvf TEMP_DISK:[DOWNLOADS]SOAP-tools-1_1.jar
This command extracts INSTALL_SOAP-1_1.COM, UNINSTALL_SOAP-1_1.COM, INSTALL_SOAP-1_1.TXT, and a number of other files needed to complete the installation.
Removing the previous version

Before you install the SOAP Toolkit Version 1.1 for OpenVMS, you must remove the SOAP Toolkit Version 1.0 for OpenVMS. To remove the Version 1.0 kit, invoke the uninstall procedure by entering the following command:
  $ @SOAP$ROOT:[SOAP_Tools-1_0]UNINSTALL_SOAP-1_0
Note: You should preserve any changes and additions you have made to Soap and any SOAP applications before removing the Version 1.0 Toolkit. The uninstall procedure will show which directories will be affected before the kit is removed.
If you have upgraded or made other changes to CSWS_JAVA after installing SOAP V1.0, the uninstall procedure may warn you that certain files have changed since SOAP was installed and it cannot restore the original files. The uninstall procedure will also display the differences between the original files, the current set of files, and the files as modified by the SOAP Version 1.0 installation. Unless SOAP or CSWS_JAVA are not functioning properly, the current set of files should be correct and you can ignore the differences.

Installing the kit

To install the SOAP Toolkit for OpenVMS kit, enter a command similar to the following:
  $ @ODS5_DISK:[TEMP.SOAP_Tools-1_1]INSTALL_SOAP-1_1
INSTALL_SOAP-1_1.COM and UNINSTALL_SOAP-1_1.COM serve as general purpose installation/deinstallation procedures for SOAP. However, because environments vary, these procedures may need to be tailored to your specific needs. If you prefer to manually install the SOAP Toolkit for OpenVMS, follow the installation instructions in INSTALL_SOAP-1_1.TXT.
To install a second time, you must expand the original JAR file again, or download it again if you deleted the JAR file.
Following is an example of an installation log, which includes configuring a SOAP server.
  $ @SYS$MANAGER:JAVA$131_SETUP

  Setting up symbols for foreign command line usage...
  JAVA$FILENAME_CONTROLS now set to: -1

  $ CREATE/DIR TEMPDISK$:[EXTRACT]
  $ SET DEFAULT TEMPDISK$:[EXTRACT]
  $ jar -xvf TEMP_DISK$:[DOWNLOADS]SOAP-tools-1_1.jar

  created: META-INF/
extracted: META-INF/MANIFEST.MF
  created: SOAP_Tools-1_1/
extracted: SOAP_Tools-1_1/BSF-docs-1_0.jar
extracted: SOAP_Tools-1_1/BSF-samples-1_0.jar
extracted: SOAP_Tools-1_1/BSF-src-1_0.jar
  created: SOAP_Tools-1_1/install/
extracted: SOAP_Tools-1_1/install/DOC_DESCRIPS-1_1.TXT
extracted: SOAP_Tools-1_1/install/INDEX.HTML_TEMPLATE
extracted: SOAP_Tools-1_1/install/INDEX.HTML_TEMPLATE2
  created: SOAP_Tools-1_1/install/org/
extracted: SOAP_Tools-1_1/install/SRC_DESCRIPS-1_1.TXT
extracted: SOAP_Tools-1_1/INSTALL_SOAP-1_1.COM
extracted: SOAP_Tools-1_1/INSTALL_SOAP-1_1.TXT
extracted: SOAP_Tools-1_1/JS-docs-1_1.jar
extracted: SOAP_Tools-1_1/JS-samples-1_1.jar
extracted: SOAP_Tools-1_1/JS-src-1_1.jar
extracted: SOAP_Tools-1_1/JSSE-docs-1_1.jar
  created: SOAP_Tools-1_1/new/
  created: SOAP_Tools-1_1/org/
extracted: SOAP_Tools-1_1/RELEASE_NOTES.TXT
extracted: SOAP_Tools-1_1/SOAP-docs-1_1.jar
extracted: SOAP_Tools-1_1/SOAP-samples-1_1.jar
extracted: SOAP_Tools-1_1/SOAP-src-1_1.jar
extracted: SOAP_Tools-1_1/SOAP-tools-bin-1_1.jar
extracted: SOAP_Tools-1_1/SOAP-webapps-1_1.jar
extracted: SOAP_Tools-1_1/STP.COM
extracted: SOAP_Tools-1_1/UNINSTALL_SOAP-1_1.COM

$ @[.SOAP_TOOLS-1_1]install_soap-1_1


              SOAP Tools Kit V1.1 Installation Procedure
             --------------------------------------------

Before installing this kit, please make sure that the following prerequisites have been met.
If they have not been met, the installation procedure may be unable to complete and may terminate:

	1) The installed operating system is OpenVMS Alpha V7.2-2 or later.
	2) Software Development (SDK) for the Java Platform Version
	   1.3.1 (or higher) is installed, including any required OpenVMS
	   patches.
	3) An ODS-5 enabled disk is available and mounted.

If you wish to configure this system as a Soap server, the following additional
prerequisites must be met:

	4) The Secure Web Server (SWS) for OpenVMS Alpha V1.2 (or
            higher) is installed.
	5) CSWS_JAVA for Secure Web Server for OpenVMS Alpha V2.0 (or
	    higher) is installed.

	***********************************************************
				 Note
		Questions, where indicated, accept a response of
		 "H" to request additional Help and information.
	***********************************************************


WORK3$:[EXTRACT] is assumed to contain the extracted installation files from Step 3 of the release notes.
If this is incorrect, please enter the correct device and directory. [ WORK3$:[EXTRACT] ] :

Please enter the ODS-5 target destination device and directory or logical name indicating
the location where you would like to install the SOAP kit. This location will become
the base directory for SOAP: (H) [ WORK3$:[EXTRACT] ] : work3$:[SOAP]

Would you like to install the SOAP Server support? (Y, N, H) [N] : Y

Would you like to install Java Scripting support? (Y, N, H) [N] : Y

Upon completion of the installation, CSWS_JAVA should be restarted.
Would you like this procedure to restart CSWS_JAVA for you?
If you are not sure, enter H. (Y, N, H) [Y] : Y

  Documentation
------------------

The documentation included in the Soap Toolkit consists of documentation for
SOAP itself (User's Guide and API reference) as well as documentation for
other components required to install SOAP.

Most documentation is in the form of HTML files, which you can serve locally and/or
access with a web browser.  Installing documentation is optional. Even if you decide
to install none of the documentation, it will still be available to you online.
A web page with links to the local and online documents will be provided.

You can choose to install all of the documentation, or none of it, or you can
select the documentation for specific components you would like to install.

    -----------------------------------------------------------------
      1.    [ ]        Soap V2.3.1                            ~ 7893 blocks
      2.    [ ]        Bean Scripting Framework V2.1          ~ 3778 blocks
      3.    [ ]        Java Script V1.5R4                     ~ 1741 blocks
      4.    [ ]        Java Secure Socket Extension V1.0.3_1  ~ 1783 blocks
    -----------------------------------------------------------------
	    [x] = Selected,  [ ] = Not Selected

				Note
The Java Secure Socket Extension (JSSE) documentation is included and may
be installed, however, the JSSE binaries must be downloaded separately.
See the SOAP release notes for additional information.


Enter:  1 through 4 - To toggle a selection
	A	    - To select All documentation
	N	    - To select No  documentation
	Y	    - To proceed with the installation

A, N, 1-4, or Y : 1

    -----------------------------------------------------------------
      1.    [x]        Soap V2.3.1                            ~ 7893 blocks
      2.    [ ]        Bean Scripting Framework V2.1          ~ 3778 blocks
      3.    [ ]        Java Script V1.5R4                     ~ 1741 blocks
      4.    [ ]        Java Secure Socket Extension V1.0.3_1  ~ 1783 blocks
    -----------------------------------------------------------------
	    [x] = Selected,  [ ] = Not Selected

				Note
The Java Secure Socket Extension (JSSE) documentation is included and may be
installed, however, the JSSE binaries must be downloaded separately. See the
SOAP release notes for additional information.


Enter:  1 through 4 - To toggle a selection
	A	    - To select All documentation
	N	    - To select No  documentation
	Y	    - To proceed with the installation

A, N, 1-4, or Y : Y

If you are planning to share documentation files with Secure Web Server,
it is recommended that you change the directory tree's ownership for all
documentation files to APACHE$WWW.

Would you like this procedure to change the ownership for you? (Y, N, H) [Y] :

  Sources
------------

The sources included in the Soap Toolkit consist of source files that will
allow you to build SOAP itself, as well as sources for some of the associated
components required to install SOAP.

SOAP and the associated components are implemented entirely in Java.
It is not necessary to install the sources or to build them.  The sources
are provided for those that may wish build them in order to do
development work in this area.

You can choose to install all of the sources, or none of them, or you can
select the sources for specific components you would like to install.

    -----------------------------------------------------------------
      1.    [ ]        Soap                          ~ 2767 blocks
      2.    [ ]        Bean Scripting Framework      ~ 1024 blocks
      3.    [ ]        Java Script                   ~ 4072 blocks
    -----------------------------------------------------------------
	    [x] = Selected,  [ ] = Not Selected

Enter:  1 through 3 - To toggle a selection
	A	    - To select All sources
	N	    - To select No  sources
	Y	    - To proceed with the installation

A, N, 1-3, or Y : Y

No further questions will be asked.


Installing binaries...
This will take a minute or so...

Installing example files...
	SOAP...
	BSF...
	JS...

Installing SOAP web archive...


Aliases will be created for all documentation so that you can reference
the documentation using a URL in the form:

	http://<yourhost.yourdomain>/alias/

Note that links to all documentation are provided on the "soaptools" page,
so http://<yourhost.yourdomain>/soaptools/ may be the only alias
you need to make note of.

Installing documentation and creating aliases...

	soap-1_1      alias: soapdocs

Added alias soaptools

The file SOAP$ROOT:[SOAP_Tools-1_1]index.html has been created. This page
describes the available SOAP documentation. You may want to create a
link to this page in the form:

  http://<yourhost.yourdomain>/soaptools/index.html


The file SOAP$ROOT:[SOAP_Tools-1_1]SOAP_KIT.CONF has been created.
This file provides aliases and access information for Apache. You may
want to modify the access rights.

Include /SOAP$ROOT/SOAP_Tools-1_1/SOAP_KIT.CONF has been appended
to APACHE$COMMON:[CONF]HTTPD.CONF

Updating WORK3$:[000000.APACHE.JAKARTA.TOMCAT.conf]server.xml

The following changes have been made to:

	WORK3$:[000000.APACHE.JAKARTA.TOMCAT.conf]server.xml

************
File WORK3$:[000000.APACHE.JAKARTA.TOMCAT.conf]server.xml;4
  301   
  302
  303            <Context path="/soap" docBase="soap.war" debug="0"
  304                  reloadable="true" crossContext="true">
  305            <Listener className="org.apache.ajp.tomcat4.config.ApacheConfig"
  306                  append="true" />
  307            <Logger className="org.apache.catalina.logger.FileLogger"
  308                      prefix="localhost_soap_log." suffix=".txt"
  309                  timestamp="true"/>
  310           </Context>
  311
  312
  313            <Context path="/myapp" docBase="myapp" debug="0"
******
File WORK3$:[000000.APACHE.JAKARTA.TOMCAT.conf]server.xml;3
  301            <Context path="/myapp" docBase="myapp" debug="0"
************

Number of difference sections found: 1
Number of difference records found: 12

DIFFERENCES /IGNORE=()/MATCH=20/MERGED=1-
    WORK3$:[000000.APACHE.JAKARTA.TOMCAT.conf]server.xml;4-
    WORK3$:[000000.APACHE.JAKARTA.TOMCAT.conf]server.xml;3


Setting file ownership to APACHE$WWW...
	SOAP_Tools-1_1
	SOAP-1_1      webapps
	soap-1_1      documents

The file SOAP$ROOT:[SOAP_Tools-1_1]Soap-1_1_SetClassPath.com has been created.
This file is needed to run the SOAP Test Procedure. It may also be useful
to retain for your own SOAP applications

APACHE$ROOT:[000000].TOMCATRC has been created.


SOAP: Stopping CSWS-JAVA...
  Using CATALINA_BASE  : /$6$dka100/apache/jakarta/tomcat/
  Using CATALINA_HOME  : /$6$dka100/apache/jakarta/tomcat/
  Using CATALINA_TMPDIR: /$6$dka100/apache/jakarta/tomcat/temp
Using Java 1.3.1 setup
Setting up symbols for foreign command line usage... JAVA$FILENAME_CONTROLS
now set to: -1 Stopping initiated Tomcat Logicals and Classpaths are cleared
SOAP: Waiting for CSWS_JAVA process (APACHE$TOMCAT) to exit

SOAP: Starting CSWS-JAVA...
  Using CATALINA_BASE  : /$6$dka100/apache/jakarta/tomcat/
  Using CATALINA_HOME  : /$6$dka100/apache/jakarta/tomcat/
  Using CATALINA_TMPDIR: /$6$dka100/apache/jakarta/tomcat/temp
Using Java 1.3.1 setup
Setting up symbols for foreign command line usage... JAVA$FILENAME_CONTROLS
now set to: -1 Starting Tomcat... Starting APACHE$TOMCAT as a detached
network process %APACHE-S-PROC_ID, identification of created process is
204007AA Tomcat Logicals and Classpaths are cleared
SOAP: Waiting for CSWS_JAVA process (APACHE$TOMCAT) startup to complete
SOAP: Waiting for CSWS_JAVA process (APACHE$TOMCAT) startup to complete


Performing graceful restart of CSWS...

SOAP Toolkit V1.1 Installation complete.

--------------------------------------------------------------------------
    SOAP$ROOT has been defined.  The following line to must be added to
    SYS$MANAGER:SYLOGICALS.COM so that it will be defined each time the
    system is rebooted.  Failure to do so will prevent CSWS from starting.

      $ define/sys/nolog/trans=concealed SOAP$ROOT WORK3$:[SOAP.]
--------------------------------------------------------------------------

Press the <Enter> key to continue:

 Post Installation Checkout
----------------------------

Point your browser to the following URL:

	http://<yourhost.yourdomain>/soaptools/

You should find a list of links to the documentation you elected to install,
as well as links to external documentation that was available at the time
of this kit was packaged (these may require updating over time).

At the top of the page is a link to the SOAP applications page.
Here you will find two more links.  Click on the "Visit the SOAP RPC
router URL for this SOAP server" link.  It should respond with:

"Sorry, I don't speak via HTTP GET - you have to use HTTP POST to talk to me."

This is normal and expected.

Now go back and click on the "Run the Admin client" link.  It should display
"List". "Deploy", and "Un-deploy" options.  Selecting "List" should show
that there are no currently deployed services.


Further verification of the installation can be performed using the
SOAP Test Procedure, which will deploy several services.  This procedure,
however, requires manual intervention and therefore will not be run automatically.

To run the SOAP Test Procedure, enter the command:

	$ @SOAP$ROOT:[SOAP_Tools-1_1]STP.COM
After Installing the SOAP toolkit

After the installation is complete, perform the following tasks.
Add the following line to SYS$MANAGER:SYLOGICALS.COM so that it will be defined each time the system is rebooted.
  $ define/sys/nolog/trans=concealed SOAP$ROOT disk:[SOAP_Tools-1_1.]
where disk:[SOAP_Tools-1_1.] is the location where you installed the SOAP Toolkit for OpenVMS.
Optionally run the SOAP Test Procedure. To run the test procedure, enter the command:
  $ @SOAP$ROOT:[SOAP_Tools-1_1]STP.COM
STP.COM accepts three optional arguments, as follows:

The node against which you want to run the test procedure. The default is localhost. You can specify host.domain. For example, node1.zko.dec.com.
The proxy, if required. For example, www-proxy.zko.dec.com:8080.
The test to run. If you do not specify a test, STP.COM runs all of the tests. You can look in STP.COM to see a list of tests if you want to specify one test; for example, addressbook.

The following example shows the STP.COM command specifying all three optional arguments:
  $ @SOAP$ROOT:[SOAP_Tools-1_1]STP.COM node1.zko.dec.com www-proxy.zko.dec.com:8080 addressbook
Note: Some of the tests attempt to access the internet. If your configuration requires a proxy:port specification, you must add it to the command line.
If you did not choose to have the SOAP installation procedure restart CSWS_JAVA, you should manually restart CSWS_JAVA and HP Secure Web Server before accessing the web application in Step 4.
To restart CSWS_JAVA, enter the following command:
  $ @SYS$STARTUP:APACHE$JAKARTA_SHUTDOWN 
Wait until the APACHE$TOMCAT process has exited. Then enter:
  $ @SYS$STARTUP:APACHE$JAKARTA_STARTUP 
Wait until the APACHE$TOMCAT process has entered the HIB state. Then, to restart HP SWS without interruption of service, enter the following command:
  $ @SYS$STARTUP:APACHE$STARTUP GRACEFUL
To access the SOAP web application, point your browser to the following URL:
  http://<yourhost.yourdomain>/soaptools/
You will find a list of links to the documentation you elected to install, as well as links to external documentation.
At the top of the page is a link to the SOAP applications page. Here you will find two more links. Click on the "Visit the SOAP RPC router URL for this SOAP server" link.
Go back to the following URL:
  http://<yourhost.yourdomain>/soaptools/
Click on the "Run the Admin client" link. It should display "List". "Deploy", and "Un-deploy" options. Selecting "List" should show that there are no currently deployed services.
Release Notes

This section contains notes on the current release of the SOAP Toolkit for OpenVMS Alpha.

Support for SSL in the SOAP toolkit

You can create SOAP clients and servers that use Secure Socket Layer (SSL) communication.
To use SSL with SOAP the Toolkit, you must download the JSSE binaries.
The Java Secure Socket Extension (JSSE) documentation is included with this kit. Instructions for setting up JSSE to work with SOAP is also included in the SOAP documentation.

Proxy Setup

If you plan to deploy a SOAP service that needs to access other Internet sites and this access requires the use of a proxy server, you can configure CSWS_JAVA to do the proxying for you by setting up a parameter file. To set up a parameter file, perform the following steps:
Create a file that specifies the "proxyHost" and "proxyPort" options as in the following example:
  -DproxyHost=www-my_proxyhost.com -DproxyPort=8080
Make sure the protection on this file is world:RE.
Define/system APACHE$JAKARTA_JAVA_PARAMETERS_FILE to equate to this file.
Restart CSWS_JAVA.
STP.COM contains an example of setting up such a parameter file, as well as examples of using proxies with SOAP clients. To find this information, search STP.COM for "proxy", "stockquote" and "APACHE$JAKARTA_JAVA_PARAMETERS_FILE".

Support

V1.1 Customer Release Version
Support for the SOAP Toolkit Version 1.1 for OpenVMS Alpha is provided by the Hewlett-Packard Company under existing OpenVMS service agreements through standard support channels.
See HP support for worldwide support center telephone numbers.
If you do not have a support contract and are not interested in acquiring one, you can informally exchange information with other users in the OpenVMS newsgroup comp.os.vms.
HP is committed to protecting your privacy. Learn more.

Send technical feedback to the SOAP Toolkit for OpenVMS engineering team

» return to the SOAP toolkit home page