1. Overview
2. Requirements
1. Support multiple Axis versions
2. Support external Apache Axis installations
3. Extensible Axis emitter preference page
3. Conceptual Design
4. Detailed Design

The Web services wizards in the WTP currently contains Axis plugins that enables the user to create and consume Web services using the Apache Axis 1.1 Web services runtime. Rather then just supporting one version of Axis, there is increasing requirements to support multiple versions of Axis (e.g. 1.0, 1.1, 1.2RC3). This would enable the users to pick and choose the version of Axis best suited for their needs.

In addition, rather than embedding Axis JARs in Apache Axis plugins, we should let the users specify the install location of the different levels of Axis.

This document provides an overview of the direction that the Web Services Tools team is going with the design and implementation of supporting multiple versions of Axis.

The Web services tools in WTP includes support for Apache Axis 1.1. Although Axis 1.1 is the latest final release available from Apache Software Foundation, users have reported a desire to have Axis 1.2 supported also. Since Axis 1.2 is not final and many users would likely still to wish to remain on Axis 1.1 for some time, it is not advisable to simply replace Axis 1.1 by Axis 1.2RC3 (the latest available release candidate of Axis 1.2). Instead, the Web services tools should be able to support more than one version of Apache Axis at a time, with the effort to plug in new versions of Axis kept as minimal as possible.

In order to maximize code reuse and extensibility, a new internal Axis runtime extension point will be defined. So instead of duplicating the current set of Axis plugins and target each set for a different version of Axis, we would let the generic Axis plugins handle the general function of creating and consumming Axis Web service and delegate code that is specific to a particular Axis version to the Axis runtime extenders (i.e. new Axis1.1 and Axis1.2 plugins) through this new Axis runtime extension point.

This new Axis runtime extension point should allow the Axis runtime extenders define:

• pluggable Axis JAR manifests for Axis emitter and deployed service runtime use,
• pluggable Axis emitter Ant task facades,
• pluggable sets of Axis emitter options.

We should let the users specify the install location of the different levels of Axis rather than embedding Axis JARs in different plugins. When implementing this support, we should keep the user experience similar to using the Server Installed Runtime preference to pick a specific version of Apache Tomcat and then specify its install location.

We should let the users specify Axis emitter options through preference page. The Axis emitter preference page should be extensible by the Axis1.1 and Axis1.2 plugins so that the preference pages are tailored to the specific Axis version. The preferences should be grouped so that only the more common options would show up initially and the less common options only show up when the user asks to see the advance options.

The user would use the preference page to pick a version of Apache Axis, then specify the directory it is installed in. We would reuse code from server tooling for installing runtimes whenever possible to keep the user experience the same.

By allowing the user to specify external Axis installation location, the user would have more flexibility on using the different versions of Axis and we do not need to ship different plugins to hold the different versions of Axis JARs. This external install location would be used for:

1. the Axis plugins to call the Axis emitters and admin client.
2. the Axis plugins to copy the JARs to a deployed Web services' WEB-INF/lib directory for the generated code.

The wst.ws.apache.axis plugin would continue to hold the Axis 1.1 JARs and used strictly as an Axis Web service runtime transport for the Web Service Explorer, UDDI4J and Web Services Parser. This plugin should not be targetted as an external installation of Axis.

The various Axis runtime extenders would define the extensions to the Web Service runtime extension point. So instead of just one Axis runtime, the user can now choose between Axis 1.1 and Axis 1.2. When any of the Axis runtime is chosen, the generic Axis plugin is called to handle the scenario. It would delegate work to the Axis runtime extenders through the new Axis extension point when necessary.

When designing the new Axis extension point, we considered the possible differences between various Axis versions so that the Axis extenders can provide these information to the Axis extension point.

The differences between Axis versions are the following:

1. Install location
2. Java2WSDL emitter class name
3. WSDL2Java emitter class name
4. Axis admin client class name
5. List of JARs
• name
• usedByEmitter: true/false (for running emitters)
• usedByRuntime: true/false (for copying to WEB-INF/lib)
6. List of Java2WSDL options
   • name
   • commandlineOptionName: name of the command line option
   • description
   • type: String, boolean, int
   • getterMethodName: name of getter
   • setterMethodName: name of setter
   • visibleInPreference: true/false (option visible in preference or not, default to true)
   • advancePreference: true/false (option in advance preference or not, default to false)
   • visibleInWizard: true/false (option visible in wizard or not, default to true)
7. List of WSDL2Java options - similar to Java2WSDL options

These differences between Axis versions are obtained from the metadata in plugin.xml through the Axis runtime extension point and from the preference store (e.g. for install location).

Here's a sample fragment of the plugin.xml for the generic Axis plugin where the extension point is defined:

Here's a sample fragment of the plugin.xml for the Axis 1.1 plugin extending the Axis runtime extension:

The Web Services preference page would have a new extension to let the various Axis extenders plug in its emitter options. The Axis emitter preference page would be organized based on the Axis version. For each preference page for a particular version of Axis, the options specified as "visibleInPreference" in the Axis Runtime extension would show up.

The initial preference page would only show preference that are not marked as "advancePreference" in the plugin.xml. The intial preference page would have an Advance button. When the user press the Advance button, the preferences marked as "advancePreference" would show up as well.

The user could set the various emitter options in the preference page. When presenting the emitter options in the wizard (for options specified as "visibleInWizard"), this Axis emitter preference store would be consulting to set the defaults. If the user make any changes to the emitter options in the wizard, this updated option values will be used when calling the setter of that option. Otherwise, the original preference values will be used.

The AxisRuntime class will be used to represent the metadata from the plugin.xml. It will use a factory method to create an AxisEmitterContext object to capture the informaiton specific to a particular invocation of the emitter. The constructor for this factory method would take the emitter class name, the scenario mode and the URL of the WSDL file (only for w2j) as arguments.

The different scenario modes are:

• BUj2w - generate WSDL from Java
• BUw2j - generate Java from WSDL file created from bottom-up j2w scenario.
• TDw2j - generate Java from WSDL file for top-down skeleton scenario
• Cw2j - generate Java from WSDL file for client scenario

The AxisEmitterContext set different j2w and w2j emitter option in the preEmit() method based on the scenario mode given. For example in TDw2j, isSkeletonWanted() would be set. For BUw2j, certain w2j options flag would be overrided to support this bottom-up scenario (e.g. reversing the j2w package to namespace custom mapping and feed that into w2j namespace to package custom mapping rather than accepting the custom mapping provided by the user).

The AxisEmitterContext object would also have methods that calculates the name of generated artifacts based on namespace to package mapping algorithm specific to different Axis versions:

• Fully qualified name of SEI
• Fully qualified name of SI
• Fully qualified name of skeleton implementation bean

Here is a class diagram showing the relationship between the various classes:

Here is a sequence diagram showing interaction between AxisRuntime, Axis11Runtime and Axis11EmitterContext using the top down skeleton scenario as an example.

Note that after getting the list of JARs from Axis11Runtime, the AxisRuntime class uses those Axis JARs to load up the Axis emitter and admin client. The call to set emitter option, to call the emitter and to call Axis deploy would all be done via Java introspection.

For bottom-up scenario, the flow would be similar to the skeleton scenario except there will be a call to getJ2wEmitter() and getJ2wEmitterOption() first before calling getW2jEmitter(). The AxisEmitterContext would first be set to handle BUj2w context, then BUw2j context.

For client scenario, the flow would be again similar to above diagram except the AxisEmitterContext would be set to Cw2j and Axis deploy would not be called. After the Java files are generated, the Axis plugin calls getSeiName() to get the name of the generated SEI from Axis1.1. The Axis1.1 plugin calls the namespace to package algorithm in Axis to get the fully qualified name of the generated SEI. The Axis plugin then calls a utility method in the framework to generate the proxy bean. This proxy bean is used by the Sample JSP to test the Web service client.