The supplied example demonstrates the use of HTTP over SSL ( or https ) for communication between two Web Service end points on Apache Axis. Use of https protects the content exchanged and can also be used by one end point to authenticate the other.

The example consists of a simple Java class Hello with method String greet(String anme) and a client class client.Client. Class Hello is deployed as a Web Service and the client invokes the method greet() with the string specified in the command line parameter.

Note: The convention used in this readme file for pathnames, environment variables and script files is for Windows OS.

Configuration for https communication is a fairly involved process. Please refer to Web Services Over SSL - HOW TO guide for an overview and details of specific setup steps.

To run this example, perform following steps:

Details of next three steps can be found in Web Services Over SSL - HOW TO guide

1. If you have JDK1.2.x or 1.3.x, then Install Java Secure Socket Extension. You can skip this if you are using JDK1.4.0.
2. Create the keystores for client and the Servlet container.
3. Configure HP-AS 8.0 or Apache Jakarta TomCat 4.0.x for https connections.



4. Bring up the J2EE container HP-AS 8.0 or Servlet container TomCat. It is assumed that you have already deployed Axis to the container.
5. Change to the main directory of this example file. You should find this readme.html file in this directory.
6. Edit the script setAxisEnv.bat to reflect your setup. Here you need to specify following environment variables:
   
   • AXIS_CONTEXT_URL: the context url for the Axis servlet ( https://localhost:8443/axis if you are using Tomcat and followed the configuration steps in the HOW-TO guide ),
   • AXIS_HOME: Axis installation directory ( ex: c:\xml-axis-alpha3 ),
   • AXIS_SERVLET_DIR: Axis Servlet directory ( should be %AXIS_HOME%\webapps\axis unless you are using a WAR deployment and copying the WAR file to the webapps directory of the Servlet container ),
   • JAVA_OPTS: options for JVM. Setting System property java.protocol.handler.pkgs is required if you have installed JSSE but is optional for JDK1.4 onwards. Specifying System property javax.net.ssl.trustStore is required so that the client can verify the certificate presented by the server. Similarly, System properties javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword are required so that the client can present its certificate to the server.
7. Compile the service class and deploy it. You can do this by running the script deploy.bat in the current directory.
8. Generate the client side stubs and compile the client. You can do this by running the script compile-client.bat.
9. Run the client. You can do this by running the script run.bat with a string as argument. A sample session is shown below:

     >run "Pankaj Kumar"
     .. skipped output ..
     greet() returned: Hello, Pankaj Kumar!!
     >
     

10. If you are interested in finding out the average invocation time, then you should specify the no. of times to iterate as well. A sample session is shown below:

      >run "Pankaj Kumar" 100
      .. skipped output ..
      greet() returned: Hello, Pankaj Kumar!!
      [0] Avg. response time = 31 ms.
      [1] Avg. response time = 29 ms.
      [2] Avg. response time = 28 ms.
      [3] Avg. response time = 25 ms.
      >
      

    Note that the average response times are reported for four rounds of execution. This is to smooth out JIT compilation warm up overheads in initial cycles.
11. If you are interested in comparing https performance with http, then undeploy the service by running the script undeploy.bat, change AXIS_CONTEXT_URL in file setAxisEnv.bat to the http url, restart the container, and then go through the deploy, compile-client and run sequence.

1. At times the problem is due to improper setup of the environment. To make detection of such problems easy, I have enabled echo for most of the commands in scripts. Pay attention to those. Also, look at the supplied scripts to analyze problems.
2. If you are modifying the program sources and invoking deploy and compile-client multiple times then you should follow the following sequence: undeploy, edit file setAxisEnv.bat and/or other source files, deploy, compile-client and then run.
3. For any change in the container descriptor file ( hpas-deploy.xml for HP-AS 8.0 and server.xml for Tomcat 4.0.1 ) to become effective, you must restart the container.
4. Match the protocol ( http or https ) and port in the container descriptor file, AXIS_CONTEXT_URL env. variable and the generated client stub sources. Any descrepancy among these could cause problems.