Author: chatra Date: Tue May 2 01:21:46 2006 New Revision: 398845 URL: http://svn.apache.org/viewcvs?rev=398845&view=rev Log: adding tools dir Added: webservices/axis2/trunk/java/xdocs/latest/tools/ webservices/axis2/trunk/java/xdocs/latest/tools/CodegenToolReference.html webservices/axis2/trunk/java/xdocs/latest/tools/idea/ Removed: webservices/axis2/trunk/java/xdocs/latest/CodegenToolReference.html webservices/axis2/trunk/java/xdocs/latest/ServiceArchiveToolReference.html Added: webservices/axis2/trunk/java/xdocs/latest/tools/CodegenToolReference.html URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/tools/CodegenToolReference.html?rev=398845&view=auto ============================================================================== --- webservices/axis2/trunk/java/xdocs/latest/tools/CodegenToolReference.html (added) +++ webservices/axis2/trunk/java/xdocs/latest/tools/CodegenToolReference.html Tue May 2 01:21:46 2006 @@ -0,0 +1,777 @@ + + + + Code Generator-Command Line Tool + + + +

Code Generator Tool- Command Line & Ant Task

+ +

The Code Generator tool consists of a command line version and an Ant +Task. This document will list the command line references and Ant task +references. Also in detail, this document shows how to build file using +custom Ant task and invoking the Code Generator from Ant.

+ +

Content

+ + + +

Introduction

+ +

This basic tool is implemented by the WSDL2Code class and just for the +convenience in the java case (which would be the majority) there is another +WSDL2Java class. One can choose to run the main classes directly or use one +of the scripts to run the WSDL2Code and WSDL2Java appropriately. (the scripts +are found in the bin directory of the binary distribution)

+ + +

Command Line Version

+ +

For those users who wish to use the command line version of the tool, this +section will be of value.

+ + +

Option Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Short OptionLong OptionDescription
-uri <Location of WSDL>NoneWSDL file location. This should point to a WSDL file in + the local file system
-o <output Location> :--outputoutput file location. This is where the files would be + copied once the code generation is done. If this option is omitted + the generated files would be copied to the working directory.
-l <language>--languageOutput language. Currently the code generator can + generate code in Java but it has the ability to be extended to + support other languages
-p <package name>--packageThe target package name. If omitted, a default package + (formed using the target namespace of the WSDL) will be used.
-a--asyncGenerate code only for async style . when this option + is used the generated stubs will have only the asynchronous + invocation methods. Switched off by default.
-s--syncGenerate code only for sync style . When this option is + used the generated stubs will have only the synchronous invocation + methods. Switched off by default. When used with the -a option, this + takes precedence.
-t--test-caseGenerates a test case. In the case of Java it would be + a junit test case.
-ss--server-sideGenerates server side code (i.e. skeletons). Default is + off
-sd--service-descriptionGenerates the service descriptor (i.e. server.xml). + Default is off. only valid with -ss, the server side code generation + option
-d--databinding-methodSpecifies the Databinding framework. valid values are + xmlbeans, adb, jibx, and none. Default is adb.
-g--generate-allGenerates all the classes. This option is valid only + with the -ss (server side code generation) option. When on, the + client code (stubs) will also be generated along with the + skeleton.
-u--unpack-classesUnpack classes. This option specifies whether to unpack + the classes and generate separate classes for the databinders.
-sn--service-nameSpecifies the service name to be code generated. If the + service name is is not specified, then the first service will be + picked
-pn--port-nameSpecifies the port name to be code generated. If the + port name is is not specified, then the first port (of the selected + service) will be picked
-ns2p--namespace2packageSpecifies a comma seperated list of namespaces and + packages where the given package will be used in the place of the + auto generated package for the relevant namespace. The list will be + the format of ns1=pkg1,ns2=pkg2.
+ +

Apart from these mentioned options one can pass extra option by prefixing +them with -E (uppercase). These extra options will be processed by the +extensions. The extra options that can be passed are documented separately +with the extensions documentation (For example with ADB)

+ + +

Ant Task

+ +

The code generator also comes bundled with an Ant task. The ant task is +implemented by the org.apache.axis2.tool.ant.AntCodegenTask class. Following +are the ant task attributes.

+ + +

Ant Task Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
wsdlfilenameWSDL file location. Maps to the uri option of the command line + tool
outputoutput file location. This is where the files would be copied once + the code generation is done. If this option is omitted the generated + files would be copied to the working directory. . Maps to the -o + option of the command line tool
languageOutput language. Currently the code generator can generate code in + Java. Maps to the -l option of the command line tool
packagenameThe target package name. If omitted, a default package (formed + using the target namespace of the WSDL) will be used. Maps to the -p + option of the command line tool.
asynconlyGenerate code only for async style . when this option is used the + generated stubs will have only the asynchronous invocation methods. + Defaults to false if omitted Only true and false are applicable as + values. Maps to the -a option of the command line tool.
testcaseGenerates a test case
synconlyGenerate code only for sync style . when this option is used the + generated stubs will have only the synchronous invocation methods. + Defaults to false if omitted. Only true and false are applicable as + values. Maps to the -s option of the command line tool.
serversideGenerates server side code (i.e. skeletons). Only true and false + are applicable as values. Default is false. Maps to the -ss option of + the command line tool
generateserverxmlGenerates server side code (i.e. skeletons). Only true and false + are applicable as values. Default is false. Maps to the -sd option of + the command line tool.
unpackClassesUnpacks the generated classes. This forces the databinding classes + to be generated separately, which otherwise would have been generated + as inner classes.
serviceNameThe name of the service in the case of multiple services
portNameThe name of the port in the presence of multiple ports
namespaceToPackagesA list of namespace to package mappings
+ + +

Example Build File Using the Custom Ant Task

+ +

Following is an example ant build file that uses the custom Ant task.

+
<?xml version="1.0"?>
+<project name="CodegenExample" default="main" basedir=".">
+<target name="declare" >
+<taskdef name="codegen"
+ classname="org.apache.axis2.tool.ant.AntCodegenTask"
+ classpath="classes"/>
+</target>
+<target name="main" depends="declare">
+<codegen 
+ wsdlfilename="C:\test\wsdl\CombinedService.wsdl"
+ output="C:\"
+ serverside="true"
+ generateserverxml="true"/>
+</target>
+</project>
+ +

Notice the main target that uses the "codegen" task which will use the +org.apache.axis2.tool.ant.AntCodegenTask class and run the code generation +tool internally while passing the relevant arguments and do the proper +generation. If a user types

+ +

>ant or >ant main

+ +

it will generate the server side code and services.xml for the given WSDL +file(C:\test\wsdl\CombinedService.wsdl) and the generated code will be +written to C:\ directory.

+ +

For this Ant task to work the following jars need to be in the class +path.

+ + + +

Invoking the Code Generator From Ant

+ +

Since the users may find altering their ant class path a bit daunting they +can also follow an easier technique. The code generator main class can be +invoked directly through the build file.

+ +

Below is an example of a full build.xml needed to run WSDL2Java and +generate the Java source files, compile the sources, and build an AAR file +ready for deployment:

+
<!DOCTYPE project>
+
+<project name="wsdl2java-example" default="usage" basedir=".">
+
+  <property name="project-name" value="wsdl2java-example"/>
+  <property file="build.properties"/>
+  
+  <property name="build" value="build"/>
+  <property name="src" value="src"/>
+  <property name="build.classes"      value="build/classes" />
+
+  <path id="axis.classpath">
+     <pathelement location="build/classes" />
+     <fileset dir="${axis.home}/lib">
+       <include name="**/*.jar" />
+     </fileset>
+     <pathelement location="${build.classes}" />
+  </path>
+
+  <path id="axis_client.classpath">
+     <pathelement location="build/classes" />
+     <fileset dir="${axis.home}">
+       <include name="**/*.jar" />
+     </fileset>
+     <fileset dir="lib">
+       <include name="*.jar" />
+     </fileset>
+     <pathelement location="${build.classes}" />
+  </path>
+
+  <target name="usage" description="Build file usage info (default task)">
+    <echo message=" " />
+    <echo message="${project-name} " />
+    <echo message="-------------------------------------------------------" />
+    <echo message=" " />
+    <echo message="Available Targets:" />
+    <echo message=" " />
+    <echo message=" Compiling:" />
+    <echo message="  compile           - Compiles the WSDL2Java source code" />
+    <echo message=" " />
+    <echo message=" Compiling client:" />
+    <echo message="  compile_client           - Compiles the client source code" />
+    <echo message=" " />
+    <echo message=" Cleaning up:" />
+    <echo message="  clean             - Delete class files" />
+    <echo message=" " />
+    <echo message=" WSDL:" />
+    <echo message="  wsdl2java               - Generate source from WSDL" />
+    <echo message=" " />
+    <echo message=" AAR:" />
+    <echo message="  aar               - Generate an .aar for deployment into WEB-INF/services" />
+    <echo message=" " />
+    <echo message=" Executing:" />
+    <echo message="  runLogin               - Execute the runLogin client" />
+  </target>
+
+  <target name="prepare" >
+    <mkdir dir="${build.classes}" />
+  </target>
+
+  <target name="clean" >
+     <delete dir="${build}" />
+     <delete dir="${dist}" />
+  </target>
+
+  <target name="compile">
+    <echo message="Compiling wsdl2 files"/>
+
+    <javac
+     srcdir="output"
+     destdir="${build.classes}"
+     deprecation="true"
+     failonerror="true" debug="true"
+    >
+
+     <classpath refid="axis.classpath"/> 
+    </javac>
+
+  </target>
+
+  <target name="wsdl2java" depends="clean,prepare">
+      <delete dir="output" />
+      <java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true">
+          <classpath refid="axis.classpath"/> 
+          <arg value="-d"/>
+          <arg value="xmlbeans"/>
+          <arg value="-uri"/>
+          <arg file="wsdl/LoginEndpoint.wsdl"/>
+          <arg value="-ss"/>
+          <arg value="-g"/>
+          <arg value="-sd"/>
+          <arg value="-o"/>
+          <arg file="output"/>
+          <arg value="-p"/>
+          <arg value="org.example.types"/>
+      </java>
+
+      <!-- Move the schema folder to classpath-->
+      <move todir="${build.classes}">
+          <fileset dir="output/resources">
+              <include name="**/*schema*/**/*.class"/>
+              <include name="**/*schema*/**/*.xsb"/>
+          </fileset>
+      </move>
+
+  </target>
+
+  <target name="jar_wsdl" depends="compile">
+          <jar jarfile="lib/axis2_example_wsdl.jar" >
+              <fileset dir="${build.classes}" />
+          </jar>
+  </target>
+  
+  <!-- build an .aar file for axis2 web services -->
+  <target name="aar" depends="compile">
+     <delete dir="${build.classes}/META-INF" />
+     <mkdir dir="${build.classes}/META-INF" />
+     <copy todir="${build.classes}/META-INF" >
+       <fileset dir="output/resources" >
+         <!-- axis2 web services definitions file -->
+         <include name="services.xml"/>
+       </fileset>
+       <fileset dir="wsdl" >
+         <include name="LoginEndpoint.wsdl"/>
+       </fileset>
+     </copy>
+     <jar jarfile="dist/LoginEndpoint.aar" >
+       <fileset dir="${build.classes}" />
+     </jar>
+  </target>
+
+  <target name="compile_client">
+    <echo message="Compiling client files"/>
+
+    <javac
+     srcdir="src"
+     destdir="${build.classes}"
+     deprecation="true"
+     failonerror="true" debug="true"
+    >
+
+     <classpath refid="axis.classpath"/> 
+    </javac>
+
+  </target>
+
+  <target name="runLogin" depends="prepare,compile_client" description="run simple Login client">
+     <java classname="org.client.LoginClient" >
+     <classpath refid="axis_client.classpath"/>
+    </java>
+  </target>
+
+</project>
+ +

The above build.xml depends on a build.properties file which defines +'axis.home', such as:

+ +

axis.home=/home/username/axis2-1.0-bin/

+ +

The above build.xml example also assumes three empty directories exist, +'dist', 'lib', and 'src'.

+ +

Below is a validated WSDL Document following the Document/Literal Style. +The name of this file matches the name used in the WSDL2Java ant task above, +LoginEndpoint.wsdl

+
<?xml version="1.0" encoding="UTF-8"?>
+
+<definitions name="LoginService" targetNamespace="http://login" xmlns:tns="http://login" 
+xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
+xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns2="http://login/types">
+
+  <types>
+    <schema targetNamespace="http://login/types" xmlns:tns="http://login/types" 
+    xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
+    xmlns="http://www.w3.org/2001/XMLSchema">
+      <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
+      <element name="returnWebLoginElement">
+        <complexType>
+          <sequence>
+
+            <element ref="tns:soap_session_idElement"/>
+            <element ref="tns:web_user_nameElement"/>
+          </sequence>
+        </complexType>
+      </element>
+      <element name="webLoginElement">
+
+        <complexType>
+          <sequence>
+            <element ref="tns:user_nameElement"/>
+            <element ref="tns:user_passwordElement"/>
+          </sequence>
+        </complexType>
+
+      </element>
+      <element name="user_nameElement" type="xsd:string"/>
+      <element name="user_passwordElement" type="xsd:string"/>
+      <element name="soap_session_idElement" type="xsd:string"/>
+      <element name="web_user_nameElement" type="xsd:string"/>
+</schema></types>
+
+  <message name="LoginEndpoint_webLogin">
+     <part name="parameters" element="ns2:webLoginElement"/>
+  </message>
+  <message name="LoginEndpoint_webLoginResponse">
+    <part name="result" element="ns2:returnWebLoginElement"/>
+  </message>
+
+  <portType name="LoginEndpoint">
+    <operation name="webLogin">
+      <input message="tns:LoginEndpoint_webLogin" name="LoginEndpoint_webLogin"/>
+      <output message="tns:LoginEndpoint_webLoginResponse" name="LoginEndpoint_webLoginResponse"/>
+    </operation>
+  </portType>
+
+  <binding name="LoginEndpointBinding" type="tns:LoginEndpoint">
+    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
+    <operation name="webLogin">
+      <soap:operation soapAction="webLogin"/>
+      <input name="LoginEndpoint_webLogin">
+        <soap:body use="literal"/>
+
+      </input>
+      <output name="LoginEndpoint_webLoginResponse"> 
+        <soap:body use="literal"/>
+      </output>
+    </operation>
+  </binding>
+
+  <service name="LoginService">
+    <port name="LoginEndpointPort" binding="tns:LoginEndpointBinding">
+      <soap:address location="http://localhost:8080/axis2/services/LoginService"/></port>
+      </service></definitions>
+ +

Place the above file, named LoginEndpoint.wsdl, in the directory 'wsdl' +below the build.xml file. Run the WSDL2Java command via the ant task defined +above, and there will be a directory called 'output' created. This directory +contains the WSDL2Java generated source. An important detail is that an +XMLBean class file is also generated by WSDL2Java, TypeSystemHolder.class. +That file is placed into build/classes by the above ant task and will be +needed to compile the generated sources. A frequent problem is users get an +error such as:

+ +

ClassNotFoundException : Cannot load SchemaTypeSystem. Unable to load +class with name +schemaorg_apache_xmlbeans.system.s68C41DB812F52C975439BA10FE4FEE54.TypeSystemHolder. +Make sure the generated binary files are on the classpath.

+ +

The TypeSystemHolder.class generated by WSDL2Java must be placed in your +classpath in order to avoid this error.

+ +

The next step is to modify the generated Skeleton Java Source file - the +Web service. This file as generated returns null and needs to be updated to +contain the business logic.

+ +

After the WSDL2Java command runs the file LoginEndpoint.wsdl, edit the +following file:

+ +

output/org/example/types/LoginServiceSkeleton.java. You should see the +following code:

+
/**
+     * LoginServiceSkeleton.java
+     *
+     * This file was auto-generated from WSDL
+     * by the Apache Axis2 version: 1.0-RC4 Apr 28, 2006 (05:23:23 IST)
+     */
+    package org.example.types;
+    /**
+     *  LoginServiceSkeleton java skeleton for the axisService
+     */
+    public class LoginServiceSkeleton {
+     
+                 
+        /**
+         * Auto generated method signature
+         
+          * @param param0
+         
+         */
+        public  login.types.ReturnWebLoginElementDocument webLogin
+                  (login.types.WebLoginElementDocument param0 )
+         
+           {
+                //Todo fill this with the necessary business logic
+                throw new  java.lang.UnsupportedOperationException();
+        }
+     
+    }
+ +

Replace the contents of this file with the following, which uses the +complex types generated by WSDL2Java and the example wsdl file:

+
/**
+ * LoginServiceSkeleton.java
+ *
+ * This file was auto-generated from WSDL
+ * by the Apache Axis2 version: 1.0-RC4 Apr 28, 2006 (05:23:23 IST)
+ */
+package org.example.types;
+import login.types.ReturnWebLoginElementDocument;
+import login.types.ReturnWebLoginElementDocument.*;
+import login.types.WebLoginElementDocument;
+import login.types.WebLoginElementDocument.*;
+
+/**
+ *  Auto generated java skeleton for the service by the Axis code generator
+ */
+public class LoginServiceSkeleton {
+ 
+    /**
+     * Auto generated method signature
+     
+      * @param webLoginElementDocument changed from param0
+     
+     */
+    public ReturnWebLoginElementDocument webLogin
+       (WebLoginElementDocument webLoginElementDocument ){
+
+            //Todo fill this with the necessary business logic
+            System.out.println("LoginServiceSkeleton.webLogin reached successfully!");
+
+            // Get parameters passed in 
+            WebLoginElement webLoginElement = webLoginElementDocument.getWebLoginElement();
+            String userName = webLoginElement.getUserNameElement();
+            String password = webLoginElement.getUserPasswordElement();
+            System.out.println("LoginServiceSkeleton.webLogin userName: " + userName);
+            System.out.println("LoginServiceSkeleton.webLogin password: " + password);
+     
+            // input paramaters would be used here 
+    
+            // prepare output
+            ReturnWebLoginElementDocument retDoc =
+                ReturnWebLoginElementDocument.Factory.newInstance();
+            
+            ReturnWebLoginElement retElement = ReturnWebLoginElement.Factory.newInstance();
+            
+            retElement.setWebUserNameElement("joe sixpack");
+            retElement.setSoapSessionIdElement("some_random_string");
+            System.out.println("validate retElement: " + retElement.validate());
+
+            retDoc.setReturnWebLoginElement(retElement);
+            System.out.println("validate retDoc: " + retDoc.validate());
+            
+            System.out.println("LoginServiceSkeleton.webLogin returning...");
+    
+            return retDoc; 
+
+    }
+}
+ +

The next steps assume the axis2.war has been deployed and has expanded in +a servlet container.

+ +

Run the 'jar_wsdl' ant task from the example build.xml, which generates a +jar file lib/axis2_example_wsdl.jar in the 'lib' directory under the +build.xml . This jar will be used to compile the client, and also will be +placed in the servlet container. Next, run the 'aar' ant task from the +example build.xml, which generates the deployable axis2 Web service. Place +dist/LoginEndpoint.aar into axis2/WEB-INF/services . Place +lib/axis2_example_wsdl.jar into axis2/WEB-INF/lib . Verify the happy axis +page loaded the services correctly - there should be the service +'LoginEndpoint' with the available operation 'webLogin' displayed.

+ +

The last step is to create and run the client. In the src directory create +the file org.client.LoginClient.java, with the contents below:

+
package org.client;
+
+import org.apache.axis2.AxisFault;
+
+import login.types.ReturnWebLoginElementDocument;
+import login.types.ReturnWebLoginElementDocument.*;
+import login.types.WebLoginElementDocument;
+import login.types.WebLoginElementDocument.*;
+import org.example.types.LoginServiceStub;
+
+/**
+ * Login.
+ *
+ */
+public class LoginClient {
+
+    public static void main(String[] args) {
+        try {
+
+            System.out.println("webLogin, firing...");
+            LoginServiceStub stub = new LoginServiceStub();
+                    
+            WebLoginElementDocument webLoginElementDocument 
+                = WebLoginElementDocument.Factory.newInstance();
+            WebLoginElement webLoginElement = 
+                WebLoginElement.Factory.newInstance();
+            webLoginElement.setUserNameElement("joe");
+            webLoginElement.setUserPasswordElement("sixpack");
+            
+            webLoginElementDocument.setWebLoginElement(webLoginElement);
+            
+            System.out.println("validate: " +  webLoginElement.validate());
+             stub.webLogin(webLoginElementDocument);
+ 
+            ReturnWebLoginElementDocument returnWebLoginElementDocument = 
+                stub.webLogin(webLoginElementDocument);
+
+            System.out.println("Client returned");
+
+            ReturnWebLoginElementDocument.ReturnWebLoginElement
+                retElement = returnWebLoginElementDocument.getReturnWebLoginElement();
+
+            System.out.println("WebUserName: " + retElement.getWebUserNameElement());
+            System.out.println("SOAPSessionId: " + retElement.getSoapSessionIdElement());
+            System.out.println("webLogin, completed!!!");
+
+        } catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+        } catch (Exception ex) {
+            ex.printStackTrace();
+        }
+    }
+}
+ +

Now run the ant task 'ant runLogin' . The following output should +appear:

+
runLogin:
+     [echo] running the webLogin client
+     [java] webLogin, firing...
+     [java] validate: true
+     [java] Client returned
+     [java] WebUserName: joe sixpack
+     [java] SOAPSessionId: some_random_string
+     [java] webLogin, completed!!!
+ + +

Appendix

+ + +

+ +

+ +

+ +

+ +

+ +