jst/components/ws/designs/88684.html - www.eclipse.org/webtools - Git at Google

 <html>
 <head>
 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <link rel="stylesheet" href="../../../../..//default_style.css" type="text/css">
 <link rel="stylesheet" href="../../../../..//webtools/wtp.css" type="text/css">
 <title>JST Web Services Design Documents</title>
 </head>
 <body>
 <table width="100%" cellspacing="5" cellpadding="2" border="0">
 <tbody>
 <tr>
 <td width="60%" align="left"><font class="indextop">Supporting multiple Axis Versions</font>
 <br>
 <font class="indexsub">JST Web Services Design Documents</font></td><td width="40%"><img width="120" hspace="50" height="86" align="middle" src="../../../../..//images/Idea.jpg"></td>
 </tr>
 </tbody>
 </table>
 <table width="100%" cellspacing="5" cellpadding="2" border="0">
 <col width="16">
 <col width="*">
 <tbody>
 <tr>
 <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">Credits</font></b></td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <table cellspacing="5" cellpadding="2" border="1">

 <tr valign="top">

 <td>Enhancement</td>
 				<td>
 					<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=88684">
 						88684
 					</a>
 				</td>

 </tr>

 <tr valign="top">

 <td>Version</td>
 				<td>1.0 Draft</td>

 </tr>

 <tr valign="top">

 <td>Last Updated</td>
 				<td>2005.03.31</td>

 </tr>

 <tr valign="top">

 <td>Target Release</td>
 				<td>WTP 1.0</td>

 </tr>

 <tr valign="top">

 <td>Target Milestone</td>
 				<td>M4</td>

 </tr>

 <tr valign="top">

 <td>Contributors</td>
 				<td>
 					Chris Brealey
 					<br>
 					Kathy Chan
 					<br>

 </td>

 </tr>

 </table>
 </td>
 </tr>
 <tr>
 <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">Index</font></b></td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <ol>

 <li>

 <a href="#overview">Overview</a>

 </li>

 <li>

 <a href="#requirements">Requirements</a>

 </li>

 <ol>

 <li>

 <a href="#r1">Support multiple Axis versions</a>

 </li>

 <li>

 <a href="#r2">
 						Support external Apache Axis installations
 					</a>

 </li>

 <li>

 <a href="#r3">
 						Extensible Axis emitter preference page
 					</a>

 </li>

 </ol>

 <li>

 <a href="#concepts">Conceptual Design</a>

 </li>

 <li>

 <a href="#details">Detailed Design</a>

 </li>

 </ol>
 </td>
 </tr>
 <tr>
 <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">
 			<a name="overview"></a>
 			1.0 - Overview
 		</font></b></td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.

 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">
 			<a name="requirements"></a>
 			2.0 - Requirements
 		</font></b></td>
 </tr>
 <tr>
 <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>
 			<a name="r1"></a>
 			R1 - Enable Web service wizards to extensibly target
 			multiple versions of Apache Axis.
 		</td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.

 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			This new Axis runtime extension point should allow the Axis
 			runtime extenders define:
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <ul>

 <li>
 				pluggable Axis JAR manifests for Axis emitter and
 				deployed service runtime use,
 			</li>

 <li>pluggable Axis emitter Ant task facades,</li>

 <li>pluggable sets of Axis emitter options.</li>

 </ul>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>
 			<a name="r2"></a>
 			R2 - Support external Apache Axis installations (vs.
 			embedded as plugins).
 		</td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>
 			<a name="r3"></a>
 			R3 - Extensible Axis emitter preference page.
 		</td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">
 			<a name="concepts"></a>
 			3.0 - Conceptual Design
 		</font></b></td>
 </tr>
 <tr>
 <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>External Axis Installation</td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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:
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <ol>

 <li>
 				the Axis plugins to call the Axis emitters and admin
 				client.
 			</li>

 <li>
 				the Axis plugins to copy the JARs to a deployed Web
 				services' WEB-INF/lib directory for the generated code.
 			</li>

 </ol>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>Axis Runtime Extension Point</td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <table cellspacing="5" cellpadding="1" border="1">

 <tr valign="top">

 <td>
 					<img border="0" src="88684/AxisExtension.gif" height="400" width="500">
 				</td>

 </tr>

 </table>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top"><u>
 			<b>Differences between Axis versions</b>
 		</u></td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>The differences between Axis versions are the following:</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <ol>

 <li>Install location</li>

 <li>Java2WSDL emitter class name</li>

 <li>WSDL2Java emitter class name</li>

 <li>Axis admin client class name</li>

 <li>List of JARs</li>

 <ul>

 <li>name</li>

 <li>
 					usedByEmitter: true/false (for running emitters)
 				</li>

 <li>
 					usedByRuntime: true/false (for copying to
 					WEB-INF/lib)
 				</li>

 </ul>


 <li>
 				List of Java2WSDL options
 				<ul>

 <li>name</li>

 <li>
 						commandlineOptionName: name of the command line
 						option
 					</li>

 <li>description</li>

 <li>type: String, boolean, int</li>

 <li>getterMethodName: name of getter</li>

 <li>setterMethodName: name of setter</li>

 <li>
 						visibleInPreference: true/false (option visible
 						in preference or not, default to true)
 					</li>

 <li>
 						advancePreference: true/false (option in advance
 						preference or not, default to false)
 					</li>

 <li>
 						visibleInWizard: true/false (option visible in
 						wizard or not, default to true)
 					</li>

 </ul>

 </li>


 <li>
 				List of WSDL2Java options - similar to Java2WSDL options
 			</li>

 </ol>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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).
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			Here's a sample fragment of the plugin.xml for the generic
 			Axis plugin where the extension point is defined:
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <table cellspacing="5" cellpadding="1" border="1" width="75%">

 <tr valign="top">

 <td>
 					<tt>

 <pre>
 &lt;extension-point
 	id="axisRuntime"
 	name="Axis Runtime extension"
 	schema="schema/axisRuntime.exsd" /&gt;
 						</pre>

 </tt>
 				</td>

 </tr>

 </table>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>Here's a sample fragment of the
 			plugin.xml for the Axis 1.1 plugin extending the Axis runtime extension:
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <table cellspacing="5" cellpadding="1" border="1" width="75%">

 <tr valign="top">

 <td>
 					<tt>

 <pre>
 &lt;extension
 id="axis11Runtime"
 	name="Axis 11 runtime"
 	point="org.eclipse.jst.ws.axis.creation.axisRuntime"&gt;
 &lt;/extension&gt;
 &lt;axisRuntime
 	j2wEmitter="org.apache.axis.tools.ant.wsdl.Java2WsdlAntTask"
 	w2jEmitter="org.apache.axis.wsdl.toJava.Emitter"
 	adminClient="org.apache.axis.tools.ant.axis.AdminClientTask"&gt;
 	&lt;jar
 		name="axis"
 		usedByEmitter="true"
 		usedByRuntime="true"&gt;
 	&lt;/jar&gt;
 	&lt;jar
 		name="axis-ant"
 		usedByEmitter="true"
 		usedByRuntime="true"&gt;
 	&lt;/jar&gt;
 	&lt;!-- more jars --&gt;
 	&lt;j2wEmitterOption
 		name="style"
 		commandlineOptionName="-style"
 		description="style can be rpc or document"
 		type="string"
 		getterMethodName="getStyle"
 		setterMethodName="setStyle"
 		visibleInPreference="true"
 		advancePreference="false"
 		visibleInWizard="true"&gt;
 	&lt;/j2wEmitterOption&gt;
 	&lt;!-- more j2wEmitterOption --&gt;
 	&lt;w2jEmitterOption
 		name="verbose"
 		commandlineOptionName="-verbose"
 		description="verbose"
 		type="boolean"
 		getterMethodName="getVerbose"
 		setterMethodName="setVerbose"
 		visibleInPreference="true"
 		advancePreference="false"
 		visibleInWizard="true"&gt;
 	&lt;/w2jEmitterOption&gt;
 	&lt;!-- more j2wEmitterOption or w2jEmitterOption --&gt;
 &lt;/axisRuntime&gt;
 						</pre>

 </tt>
 				</td>

 </tr>

 </table>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>Emitter preference page</td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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
 			<b>Advance</b>
 			button. When the user press the
 			<b>Advance</b>
 			button, the preferences marked as "advancePreference" would
 			show up as well.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.

 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">
 			<a name="details"></a>
 			4.0 - Detailed Design
 		</font></b></td>
 </tr>
 <tr>
 <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>Axis Runtime Extension Point</td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>The different scenario modes are:</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <ul>

 <li>BUj2w - generate WSDL from Java</li>

 <li>
 				BUw2j - generate Java from WSDL file created from
 				bottom-up j2w scenario.
 			</li>

 <li>
 				TDw2j - generate Java from WSDL file for top-down
 				skeleton scenario
 			</li>

 <li>
 				Cw2j - generate Java from WSDL file for client scenario
 			</li>

 </ul>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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).
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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:
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <ul>

 <li>Fully qualified name of SEI</li>

 <li>Fully qualified name of SI</li>

 <li>
 					Fully qualified name of skeleton implementation bean
 				</li>

 </ul>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 				Here is a class diagram showing the relationship between
 				the various classes:
 			</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <table cellspacing="5" cellpadding="1" border="1">

 <tr valign="top">

 <td>
 					<img border="0" src="88684/AxisClassdiagram.jpg" height="600" width="900">
 				</td>

 </tr>

 </table>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			Here is a sequence diagram showing interaction between AxisRuntime,
 			Axis11Runtime and Axis11EmitterContext using the top down
 			skeleton scenario as an example.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <table cellspacing="5" cellpadding="1" border="1">

 <tr valign="top">

 <td>
 					<img border="0" src="88684/AxisSequencediagram.jpg" height="1000" width="900">
 				</td>

 </tr>

 </table>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>
 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>

 			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.
 		</p>
 </td>
 </tr>
 <tr>
 <td valign="top" align="right">&nbsp;</td><td valign="top">
 <p>

 			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.

 		</p>
 </td>
 </tr>
 </tbody>
 </table>
 </body>
 </html>
	<html>
	<head>
	<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<link rel="stylesheet" href="../../../../..//default_style.css" type="text/css">
	<link rel="stylesheet" href="../../../../..//webtools/wtp.css" type="text/css">
	<title>JST Web Services Design Documents</title>
	</head>
	<body>
	<table width="100%" cellspacing="5" cellpadding="2" border="0">
	<tbody>
	<tr>
	<td width="60%" align="left"><font class="indextop">Supporting multiple Axis Versions</font>
	<br>
	<font class="indexsub">JST Web Services Design Documents</font></td><td width="40%"><img width="120" hspace="50" height="86" align="middle" src="../../../../..//images/Idea.jpg"></td>
	</tr>
	</tbody>
	</table>
	<table width="100%" cellspacing="5" cellpadding="2" border="0">
	<col width="16">
	<col width="*">
	<tbody>
	<tr>
	<td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">Credits</font></b></td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<table cellspacing="5" cellpadding="2" border="1">

	<tr valign="top">

	<td>Enhancement</td>
	<td>
	<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=88684">
	88684
	</a>
	</td>

	</tr>

	<tr valign="top">

	<td>Version</td>
	<td>1.0 Draft</td>

	</tr>

	<tr valign="top">

	<td>Last Updated</td>
	<td>2005.03.31</td>

	</tr>

	<tr valign="top">

	<td>Target Release</td>
	<td>WTP 1.0</td>

	</tr>

	<tr valign="top">

	<td>Target Milestone</td>
	<td>M4</td>

	</tr>

	<tr valign="top">

	<td>Contributors</td>
	<td>
	Chris Brealey
	<br>
	Kathy Chan
	<br>

	</td>

	</tr>

	</table>
	</td>
	</tr>
	<tr>
	<td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">Index</font></b></td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<ol>

	<li>

	<a href="#overview">Overview</a>

	</li>

	<li>

	<a href="#requirements">Requirements</a>

	</li>

	<ol>

	<li>

	<a href="#r1">Support multiple Axis versions</a>

	</li>

	<li>

	<a href="#r2">
	Support external Apache Axis installations
	</a>

	</li>

	<li>

	<a href="#r3">
	Extensible Axis emitter preference page
	</a>

	</li>

	</ol>

	<li>

	<a href="#concepts">Conceptual Design</a>

	</li>

	<li>

	<a href="#details">Detailed Design</a>

	</li>

	</ol>
	</td>
	</tr>
	<tr>
	<td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">
	<a name="overview"></a>
	1.0 - Overview
	</font></b></td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.

	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">
	<a name="requirements"></a>
	2.0 - Requirements
	</font></b></td>
	</tr>
	<tr>
	<td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>
	<a name="r1"></a>
	R1 - Enable Web service wizards to extensibly target
	multiple versions of Apache Axis.
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.

	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	This new Axis runtime extension point should allow the Axis
	runtime extenders define:
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<ul>

	<li>
	pluggable Axis JAR manifests for Axis emitter and
	deployed service runtime use,
	</li>

	<li>pluggable Axis emitter Ant task facades,</li>

	<li>pluggable sets of Axis emitter options.</li>

	</ul>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>
	<a name="r2"></a>
	R2 - Support external Apache Axis installations (vs.
	embedded as plugins).
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>
	<a name="r3"></a>
	R3 - Extensible Axis emitter preference page.
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">
	<a name="concepts"></a>
	3.0 - Conceptual Design
	</font></b></td>
	</tr>
	<tr>
	<td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>External Axis Installation</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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:
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<ol>

	<li>
	the Axis plugins to call the Axis emitters and admin
	client.
	</li>

	<li>
	the Axis plugins to copy the JARs to a deployed Web
	services' WEB-INF/lib directory for the generated code.
	</li>

	</ol>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>Axis Runtime Extension Point</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<table cellspacing="5" cellpadding="1" border="1">

	<tr valign="top">

	<td>
	<img border="0" src="88684/AxisExtension.gif" height="400" width="500">
	</td>

	</tr>

	</table>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top"><u>
	<b>Differences between Axis versions</b>
	</u></td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>The differences between Axis versions are the following:</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<ol>

	<li>Install location</li>

	<li>Java2WSDL emitter class name</li>

	<li>WSDL2Java emitter class name</li>

	<li>Axis admin client class name</li>

	<li>List of JARs</li>

	<ul>

	<li>name</li>

	<li>
	usedByEmitter: true/false (for running emitters)
	</li>

	<li>
	usedByRuntime: true/false (for copying to
	WEB-INF/lib)
	</li>

	</ul>


	<li>
	List of Java2WSDL options
	<ul>

	<li>name</li>

	<li>
	commandlineOptionName: name of the command line
	option
	</li>

	<li>description</li>

	<li>type: String, boolean, int</li>

	<li>getterMethodName: name of getter</li>

	<li>setterMethodName: name of setter</li>

	<li>
	visibleInPreference: true/false (option visible
	in preference or not, default to true)
	</li>

	<li>
	advancePreference: true/false (option in advance
	preference or not, default to false)
	</li>

	<li>
	visibleInWizard: true/false (option visible in
	wizard or not, default to true)
	</li>

	</ul>

	</li>


	<li>
	List of WSDL2Java options - similar to Java2WSDL options
	</li>

	</ol>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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).
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	Here's a sample fragment of the plugin.xml for the generic
	Axis plugin where the extension point is defined:
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<table cellspacing="5" cellpadding="1" border="1" width="75%">

	<tr valign="top">

	<td>
	<tt>

	<pre>
	<extension-point
	id="axisRuntime"
	name="Axis Runtime extension"
	schema="schema/axisRuntime.exsd" />
	</pre>

	</tt>
	</td>

	</tr>

	</table>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>Here's a sample fragment of the
	plugin.xml for the Axis 1.1 plugin extending the Axis runtime extension:
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<table cellspacing="5" cellpadding="1" border="1" width="75%">

	<tr valign="top">

	<td>
	<tt>

	<pre>
	<extension
	id="axis11Runtime"
	name="Axis 11 runtime"
	point="org.eclipse.jst.ws.axis.creation.axisRuntime">
	</extension>
	<axisRuntime
	j2wEmitter="org.apache.axis.tools.ant.wsdl.Java2WsdlAntTask"
	w2jEmitter="org.apache.axis.wsdl.toJava.Emitter"
	adminClient="org.apache.axis.tools.ant.axis.AdminClientTask">
	<jar
	name="axis"
	usedByEmitter="true"
	usedByRuntime="true">
	</jar>
	<jar
	name="axis-ant"
	usedByEmitter="true"
	usedByRuntime="true">
	</jar>
	<!-- more jars -->
	<j2wEmitterOption
	name="style"
	commandlineOptionName="-style"
	description="style can be rpc or document"
	type="string"
	getterMethodName="getStyle"
	setterMethodName="setStyle"
	visibleInPreference="true"
	advancePreference="false"
	visibleInWizard="true">
	</j2wEmitterOption>
	<!-- more j2wEmitterOption -->
	<w2jEmitterOption
	name="verbose"
	commandlineOptionName="-verbose"
	description="verbose"
	type="boolean"
	getterMethodName="getVerbose"
	setterMethodName="setVerbose"
	visibleInPreference="true"
	advancePreference="false"
	visibleInWizard="true">
	</w2jEmitterOption>
	<!-- more j2wEmitterOption or w2jEmitterOption -->
	</axisRuntime>
	</pre>

	</tt>
	</td>

	</tr>

	</table>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>Emitter preference page</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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
	<b>Advance</b>
	button. When the user press the
	<b>Advance</b>
	button, the preferences marked as "advancePreference" would
	show up as well.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.

	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">
	<a name="details"></a>
	4.0 - Detailed Design
	</font></b></td>
	</tr>
	<tr>
	<td valign="top" align="right"><img width="16" height="16" border="0" src="../../../../..//images/Adarrow.gif"></td><td>Axis Runtime Extension Point</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>The different scenario modes are:</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<ul>

	<li>BUj2w - generate WSDL from Java</li>

	<li>
	BUw2j - generate Java from WSDL file created from
	bottom-up j2w scenario.
	</li>

	<li>
	TDw2j - generate Java from WSDL file for top-down
	skeleton scenario
	</li>

	<li>
	Cw2j - generate Java from WSDL file for client scenario
	</li>

	</ul>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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).
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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:
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<ul>

	<li>Fully qualified name of SEI</li>

	<li>Fully qualified name of SI</li>

	<li>
	Fully qualified name of skeleton implementation bean
	</li>

	</ul>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	Here is a class diagram showing the relationship between
	the various classes:
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<table cellspacing="5" cellpadding="1" border="1">

	<tr valign="top">

	<td>
	<img border="0" src="88684/AxisClassdiagram.jpg" height="600" width="900">
	</td>

	</tr>

	</table>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	Here is a sequence diagram showing interaction between AxisRuntime,
	Axis11Runtime and Axis11EmitterContext using the top down
	skeleton scenario as an example.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<table cellspacing="5" cellpadding="1" border="1">

	<tr valign="top">

	<td>
	<img border="0" src="88684/AxisSequencediagram.jpg" height="1000" width="900">
	</td>

	</tr>

	</table>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>
	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>

	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.
	</p>
	</td>
	</tr>
	<tr>
	<td valign="top" align="right"> </td><td valign="top">
	<p>

	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.

	</p>
	</td>
	</tr>
	</tbody>
	</table>
	</body>
	</html>