Ajax2 - Best Practices by marko

K/SOT-5

Integration Architecture Building Web Services with Axis2

Version: Status: Date:

1.0 reviewed 2007-06-18

Contents 1

Preface ................................................................................................................ 4

Overview of Axis2................................................................................................ 4 2.1

What is axis2 ................................................................................................ 4

2.2

Axis2 modules .............................................................................................. 5

2.3

Message processing life cycle...................................................................... 6

Setting up the environment and tools .................................................................. 8 3.1

Tomcat setup ............................................................................................... 9

3.2

Axis2 setup................................................................................................... 9

Project structure of the template tool................................................................. 10

Overview of the build process ........................................................................... 11

Main build initialization....................................................................................... 12

Building and packaging web services................................................................ 13 7.1

Service builds initialization ......................................................................... 16

7.2

WSDL Code generation ............................................................................. 18

7.3

Web service source code compilation ........................................................ 19

7.4

Preparing and packaging the web service.................................................. 20

Building the web application .............................................................................. 23

Deployment ....................................................................................................... 24

Service implementation.................................................................................. 25

10.1

Implementation of the skeleton .................................................................. 26

10.2

Implementation of the stub ......................................................................... 31

ÂŠ Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 2 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

Revision History Version

Date

Author

Comment

1.0

2007-06-15

Yassin Naciri

Initially created

About This Document This document introduces a generic build process for developing axis2 based web applications. It provides also the description of a tool as template for building axis2 web applications and may be a help to quickly start developing web services using Axis2.

ÂŠ Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 3 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

1 Preface This build process uses the contract first approach for developing web services starting with descriptions of services. It targets the setup and the assembly of a web application including a generic number of web service components using axis2. Axis2 provides a raw web application that is used for this purpose as basic web services infrastructure. This provides the runtime environment libraries for web services as well as a set of web based user interfaces for configuration and service management. Examples of such features are the hot deployment and the hot update (installing or updating a web service during application runtime), activating and deactivating services, engaging modules for services and so on. The tool described here provides a building help for the development of - Single Axis2 based web services starting with a given WSDL file - The whole web application integrating a generic number of web services For each single web service to be integrated in the web application the definition description file of the service, the implementation classes as well as possibly needed third party libraries are provided and encapsulated in a generic predefined directory structure, which the build process operates onto. This structure is described more detailed later. For building the complete web application, the binary raw web application is provided as a resource. To help understanding the build process a basic knowledge of the axis2 architecture, the axis2 web application and the web services structure is required. Section 2 gives therefor an overview about this. For further information, please refer to the apache axis2 home page. Section 3 describes the environment setting used within the template tool. In section 4 the structure of the java project associated to the template is sketched. Section 5 abstracts the build phases driven by the template tool. Section 6 describes the directory structure used for the project build. Section 7 describes the steps followed by the project process to build and to package each web service. Section 8 introduces how the build of the web application is done. Section 9 introduces the deployment of the web application on tomcat. Section 10 describes how the implementation of the web service skeleton should be fulfilled using the Axis Data Binding Framework.

2 Overview of Axis2 2.1 What is axis2 Apache Axis2 is an open source java1 based implementation of SOAP. 1

Extract from the draft W3C specification:

There is also an Apache Axis2 C based implementation of SOAP

ÂŠ Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 4 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

"SOAP is a lightweight protocol for exchanging structured information in a decentralized, distributed environment. It is an XML based protocol that consists of three parts: an envelope that defines a framework for describing what is in a message and how to process it, a set of encoding rules for expressing instances of application-defined datatypes, and a convention for representing remote procedure calls and responses."

Extract from the Axis2 user guide: “It provides a complete object model and a modular architecture that makes its straight forward to add functionality and support for new Web services-related specifications and recommendations. Axis2 enables to easily perform the following tasks and many more: • • • • • • • •

•

Send SOAP messages Receive and process SOAP messages Create a Web service out of a plain Java class Create implementation classes for both server and client using WSDL Easily retrieve the WSDL for a service Send and receive SOAP messages with attachments Create or utilize a REST-based Web service Create or utilize services that take advantage of the WS-Security, WSReliableMessaging, WS-Addressing, WS-Coordination, and WS-Atomic Transaction recommendations Use Axis2's modular structure to easily add support for new recommendations as they emerge”

2.2 Axis2 modules As shown in Drawing 1 Axis2 provides a modular architecture with the following main components:

Drawing 1: Axis2 modular architecture

Axis2-BestPractices.doc / MS

Page 5 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

XML Processing Model: Axis2 introduces its own object model AXIOM (Apache aXIs2 Object Model) based on the XML pull parsing technique (StAXParser). All soap messages inside the axis2 engine environment are represented in this model as AXION objects (OM objects) SOAP Processing Model: This module defines the processing phases for soap messages and controls their execution order. It contains also the axis2 engine and the handler framework, that should be used to implement new functionality and extends the predefined processing phases respectively Information Processing (Context and Description): It manages the runtime information for the deployed web services and modules in the web application. At the start of the axis2 engine, this information is collected from the global axis2 configuration file (axis2.xml) as well as from each deployed web services (services.xml) and modules (module.xml) and is maintained during runtime up to date Transports: Provides functionalities supporting many transport protocols such as http, https, stmp and tcp Client API: This module provides the client side API for soap clients to interact with web services. It supports also the One-Way and the In-Out message exchange pattern Deployment: The deployment module provides functionality support for the static and dynamic configuration of the axis2 engine as well as the deployment of web services and modules WSDL and code Generation: Provides tools for the processing of WSDL file and automatic code generation for web services

2.3 Message processing life cycle In the axis2 terminology, the notion of Flow is introduced. In simple terms, a flow represents a collection of processing phases. The order of the phases inside the flow is defined by the configuration file “axis2.xml”. In turn a phase represents a logical collection of so-called handlers. Handlers are logical components that should be invoked for the message processing inside the axis2 engine. The invocation order of the handlers inside the phase should be specified with so-called phase roles such as “phaseFirst”, “phaseLast”, “before”, “after” and so on. A flow can be also considered as a chain of handlers with a predefined order. As example, the following xml fragment is considered. There are two handlers defined (“myHandler” and “anotherHandler”). The handlers belong to the phase “mydefiniedPhase”. The phase “mydefiniedPhase” should be defined in the axis2 configuration file axis2.xml. When the phase “mydefiniedPhase” is invoked, the first invoked handler is the “myHandler” and the last invoked is the “anotherHandler”. <handler name="myHandler " class="myPackage.MyHandler"> <order phase="mydefinedPhase" phaseFirst="true" /> © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 6 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

</handler> <handler name="anotherHandler" class=" myPackage.AnOtherHandler"> <order phase="mydefinedPhase" phaseLast="true" /> </handler>

There are four types of flow in axis2: -

InFlow: Once a request message is intercepted by the transport layer, the inflow is invoked. The request message is embedded in a message context and passed to the in-flow pipe. All the handlers of this flow, i.e. the handlers of the phases, are invoked for the request in the specified chain order.

OutFlow: When a message response is going out from the server, the outflow is invoked. All handlers defined in this flow are invoked in the right order.

InFaultFlow: This flow will be invoked if any fault occurs while processing the request in the in flow.

OutFaultFlow: If any fault occurs while processing the response this flow will be invoked.

Drawing 2 outlines an example of the InFlow and the OutFlow of the axis2 engine.

In InFlow (in the drawing as the InPipe) there are the axis2 predefined phases “Transport”, “Predispatch”, “Dispatch” and “Postdispatch” and the in-flow part of the user defined phase “My defined Phase”, that consists of three handlers. The in-flow part of the user-defined phase is invoked at last in the pipeline. In OutFlow (in the drawing as the OutPipe) there are the axis2 predefined phases “MessageOut” and “Policydertermination” and the out-flow part of the user-defined phase “My defined Phase”, that consists also of three handlers. These handlers are invoked at first during response processing inside the output pipeline.

Axis2-BestPractices.doc / MS

Page 7 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

Drawing 2: Life cycle of a message processing

To get started developing a web service with axis2 using a contract first approach, three steps should be performed: -

Define the web service, i.e. provide a WSDL file of the web service

Execute the axis2 tool WSDL2Java that will generate source code and resources

Extend and implement the generated service and implement the backend logic

As shown in Drawing 2, the WSDL2Java task generates the required code for web service. The user should develop the green highlighted components on the right side of the drawing, i.e. the service skeleton and the backend logic implementation.

3 Setting up the environment and tools The environment and tools used in this project are as follows: - Windows / JRE 5.0 - The axis2 standard distribution binary release version1.2 and the axis2 war distribution - The ant version 1.7.1 For the deployment and the test of the web application, the apache tomcat was used: - The apache tomcat binary distribution core and admin release version 5.5.23 ÂŠ Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 8 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

Please note that the web application should be also deployed in other web container environments such as of Bea WebLogic, JBoss or WebSphere.

3.1 Tomcat setup -

Download the tomcat binary distributions apache-tomcat-5.5.23 and apachetomcat-5.5.23-admin.zip and unpack them in an installation directory (as example TOMCAT_HOME=C:\tools\apache-tomcat-5.5.23) A JRE 5.0 or higher must be installed. The JAVA_HOME environment variable home must be set and must point to the JRE 5 home directory Add a new tomcat account with a username and password and the assigned roles admin and manager in the file ${TOMCAT_HOME}/conf/tomcatusers.xml: <?xml version="1.0" encoding="utf-8" ?> <tomcat-users> <role rolename="tomcat" /> <role rolename="manager" /> <role rolename="admin" /> <user username="tomcat" password="tomcat" roles="tomcat" /> â&#x20AC;Ś <user username="admin" password="admin" roles="admin,manager" /> </tomcat-users>

Note that if using a J2SE 1.4 JRE, the compatibility package (apache-tomcat-5.5.23compat.zip) must be downloaded and expanded inside the folder where Tomcat was installed. To test the installation, execute the start script ${TOMCAT_HOME}/bin/startup.bat and type in a web browser the URL http://localhost:8080. To test the deployment management tool of tomcat use the URL http://localhost:8080/admin and logon with the new tomcat account.

3.2 Axis2 setup -

Download the Axis2 binary distribution package, release version 1.2 and install it as example in the directory C:\tools\ axis2-1.2 Set the environment variable AXIS2_HOME=C:\tools\ axis2-1.2. This variable is used during build runtime, to reference the axis2 libraries located in ${AXIS2_HOME}/lib. The axis2 war distribution for this version of Axis2 is provided in this project as resource

ÂŠ Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 9 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

4 Project structure of the template tool The project directory structure of the template tool described in this document is pictured in the Screenshot 3. In the block A there are the source folders of the implementation code of the web services. For each web service that will be integrated in the project, a source folder for the service implementation and probably another one for the client code should be provided. The statement on how source folders belong to a given web service is significant for the build process and is therefor described in the property file “./properties/services.xml”. The block B contains the property folder. It contains the services property file (“./properties/services.xml”) of the web services and some other optional property files. The property file contains all information needed for how to process the build of each single web service.

Screenshot 3: The project directory structure of the build template © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 10 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

In the block C there are folders that contain additional resources for the web application. The directory lib should contain third party libraries for each web service. That is each web service should have its own subfolder in the lib directory. If some libraries are needed for a web service, they must be located at this subdirectory. The web service specific lib-subfolder takes the service name “service-name” defined in the services property file “./properties/services.xml”. The block D consists of the main and common build files of the project and the project property file. The depiction of the build directory will be processed while describing the build process in the next sections.

5 Overview of the build process The build process driven by this template tool can be broken down in four major tasks: 1- The initial directory structure for the build is created 2- Each web service is built and packaged 3- The web services are integrated and the web application is packaged 4- An automatic deployment of the web application should be used(Optional) There are two build files: build.xml and common.xml. The First one is the main build file. It initializes the build folder structure and drives the build of all web services as well as the build of the whole web application. The second is common. It is imported in the main build file and is used for building each single web service. Targets of the common-build file are called from the main file with a set of user-specified parameters that characterize each web service. This set of properties instructs the common build targets about the information needed to build the single web service such as the name the web service and the source folder structure. In the main build file, three ant targets are involved: the “init” target, the “jar.all.services.aar” target and the “webapp.war” target. The “webapp.war” target depends on building all declared web services in the web application project. That is, it depends on the “jar.all.services.aar” target. The task elements of the “init” target initialize the build folder structure and are executed before the “jar.all.services.aar” target tasks. In the following xml fragment the targets of the main file build.xml are summarized: <project name="ws-template" basedir="." default="webapp.war"> <property file="project.properties" /> <property file="${project-base-dir}/properties/services.properties" /> <import file="common.xml" /> <target name="init" description="Prepare the common build structure"> … © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 11 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

</target> <target name="jar.all.services.aar" depends="init"> <antcall target="jar.service"> <param name="service-name" value="${service-name-1}" /> <param …" /> … </antcall> … </target> … <target name="webapp.war" depends="jar.all.services.aar" description="Build the web app war file"> </target> … </project>

6 Main build initialization In this phase, the build initializes a folder structure as shown in the Screenshot 3. This structure is generated by executing the init target of the main build file. It is specified and described in the project-property file “project.properties” (see the selfexplanatory extracts bellow). Extract from the build.xml: <target name="init" description="Prepare the build folder structure"> <mkdir dir="${build-dir}" /> <mkdir dir="${output-dir}" /> <mkdir dir="${dist-dir}" /> <mkdir dir="${log-dir}" /> <mkdir dir="${webapp-dir}" /> <mkdir dir="${classes-dir}" />  <tstamp /> <record name="${log-dir}/build-${DSTAMP}-${TSTAMP}.log" /> </target>

Extract from the property file project.properties: # The project base directory project-base-dir=. # Properties for init target # The root directory for the build build-dir=${project-base-dir}/build # Auto generated source code and resources from the wsdl2java tool # will be extracted to this directory output-dir=${build-dir}/src-generated # The directory for the build artifacts, that is, all the aar and war # files will be stored here dist-dir=${build-dir}/dist © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 12 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

# Log directory log-dir=${build-dir}/log # Root directory for the web services compiled classes classes-dir=${build-dir}/classes # Help directory for preparing and packaging the whole # web application webapp-dir=${build-dir}/webapp

Screenshot 4: build directory structure

Building and packaging web services

Once the top level build structure is initialized, the “jar.all.services.aar” target, i.e. the build of all web services is started. It calls for each web service the target element “jar.service“ of the common build file (common.xml). That is, for each single web service that should be involved and integrated in the build a characteristic task © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 13 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

element must be provided. This task executes an antcall to the target “jar.service” specified in the common-build file (common.xml). This “jar.service“ target is called with a set of parameters, that characterize the given web service and inform the build how to process its particular build. These parameters are described as follow: -

service-name: The name of the service to be considered. This build process to name the service, to reference the service specify the respective service build subfolders and control the execution for the service. In this document, I refer to the parameter as ${service-name}.

is used in the resources, to suitable build value of this

service-wsdl-file: This is the path to the WSDL file for the given web service. In this document, I refer to the value of this parameter as ${service-wsdl-file}. Service-impl-src-dir: The source folder that should contains implementation classes of the web service, e.g. the implementation of the skeleton class and the backend implementation. In this document, I refer to the value of this parameter as ${service-impl-src-dir}. client-impl-src-dir: The source folder that should contain client side classes. That is, for example classes that use the generated stub class to interact with the given web service for test purpose. In this document, I refer to the value of this parameter as ${client-impl-src-dir}. service-class: The implementation class of skeleton that should be used by the web service. In this document, I refer to the value of this parameter as ${service-class}.

The following extract from the file build.xml shows how the “jar.all.services.aar” target is defined: <target name="jar.all.services.aar" depends="init"> <!- - build vehicleBase web service - - > <antcall target="jar.service"> <param name="service-name" value="${service-name-1}" /> <param name="service-wsdl-file" value="${service-wsdl-file-1}" /> <param name="client-impl-src-dir" value="${client-impl-src-dir-1}" /> <param name="service-impl-src-dir" value="${service-impl-src-dir-1}" /> <param name="service-class" value="${service-class-1}" /> </antcall> <!- - build vehicleIdentification web service - - > <antcall target="jar.service"> <param name="service-name" value="${service-name-2}" /> <param name="service-wsdl-file" value="${service-wsdl-file-2}" /> <param name="client-impl-src-dir" value="${client-impl-src-dir-2}" /> <param name="service-impl-src-dir" value="${service-impl-src-dir-2}" /> <param name="service-class" value="${service-class-2}" /> </antcall> <!-- Adhoc new web service <antcall target="jar.service"> <param name="service-name" value="${service-name-3}" /> © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 14 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

name="service-wsdl-file" value="${service-wsdl-file-3}" /> name="client-impl-src-dir" value="${client-impl-src-dir-3}" /> name="service-impl-src-dir" value="${service-impl-src-3}" /> name="service-class" value="${service-class-3}" />

</target>

For each web service, the user should specify a record of properties in the file “./properties/services.xml” that maps the parameters described above. As example these properties are shown in the following properties extract for the web services “vehicleBase” and “vehicleIdentification”. Extract from the property file “./properties/services.xml”: # Properties for the web service VehicleBase service-name-1=vehicleBase service-wsdl-file-1=${resources-dir}/wsdl/VehicleBase/V1.4/VehicleBase.wsdl service-impl-src-dir-1=vb-service-impl-src client-impl-src-dir-1=vb-client-impl-src service-class-1=com.vw_group.xmldefs.retail.vehiclebase.v1_4.VehicleBaseSkeletonImpl

# Properties for the web service VehicleIdentification service-name-2=vehicleIdentification service-wsdl-file-2=${resources-dir}/wsdl/VehicleIdentification/V1.4/VehicleIdentification.wsdl service-impl-src-dir-2=vi-service-impl-src client-impl-src-dir-2=vi-client-impl-src service-class-2= com.vw_group.xmldefs.retail.vehicleidentification.v1_4.VehicleIdentificationSkeletonImpl

To build a single web service the “jar.service” target of the common build file (common.xml) is executed. The steps, that this target executes are summarized as follows: 1. Init a specific build substructure for the web service 2. Execute the WSDL2Java tool for the given WSDL file of the web service 3. Compile the generated source code and the source code localized in the service source folder 4. Prepare and package the web service as archive file (aar) A summary of the common build file common.xml and the targets that it contains is given in the following extract: <project name="common" basedir="." > <property environment="env" /> <property name="axis2.home" value="${env.AXIS2_HOME}" /> © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 15 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

The execution order of the targets used for building the jar package of a given web service is as bellow: 1. “service-init”: Initialize the build folder substructure for the web service 2. "wsdl2java": Execute the WSDL2Java tool for the WSDL of the web service 3. "compile.common_src": Compile the generated source code from the WSDL2Java tool 4. "compile.service_src": Compile the source code from the source folder of the web service 5. "add.external.libs": Add third party libraries for the web service if there are any 6. "jar.service": Prepare and Jar the web service package

7.1 Service builds initialization

Axis2-BestPractices.doc / MS

Page 16 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

The execution of the service-init target tasks creates the specific subdirectory that will be used for the build of the given web service. The parameter service-name is passed from the main build file (see the target “jar.all.services.aar”) and is used as a path label to reference the root build folder of the web service. <target name="service-init" description="Prepare the service build structure"> <mkdir dir="${classes-dir}/${service-name}/common" /> <mkdir dir="${classes-dir}/${service-name}/service" /> <mkdir dir="${classes-dir}/${service-name}/service/META-INF" /> <mkdir dir="${classes-dir}/${service-name}/client" /> </target>

As shown in the Screenshot 5 the specific build directories for the web services “vehicleBase” and “vehicleIdentification” are created.

Screenshot 5: Build subdirectory structure of a given web service

For each web service, the subdirectories “client”, “common” and “service” are created. The directory “common” contains compiled code that should be used in both of the service and the client. This is the code generated from the WSDL2Java tool. It contains among other things the code for the stub, the skeleton and the xml data binding types. The subdirectory “client” should contain as example code for building the web service client code or for a simple test code of the web service. The code contained in the ${client-impl-src-dir} will be compiled to this directory. The subdirectory “service” contains the code compiled from the source folder ${service-impl-src-dir}. As example the source code of the implementation of the © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 17 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

service skeleton. In further step of the build this subdirectory will serve also as a basic structure to package the web service.

7.2 WSDL Code generation The “wsdl2java” target generates resources and source code for a given web service. As shown in the following summary of the target, the service name of the web service and its WSDL file are passed as property parameters to the target task. <target name="wsdl2java" depends="service-init" description="Compiler task wsdl2java"> <java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true"> <classpath refid="axis2.class.path" /> … <arg value="-uri" /> <arg file="${service-wsdl-file}" /> <arg value="-o" /> <arg file="${output-dir}/${service-name}" /> … </java> </target>

The generated directory structure and its content are pictured in the Screenshot 6:

Axis2-BestPractices.doc / MS

Page 18 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

Screenshot 6: wsdl2java generated structure

The specific subdirectory that contains the generated source code and resources for the given web service takes the service name passed as parameter, i.e. “${servicename}”. In the screenshot above there are two such specific directories: “./build/srcgenerated/vehicleBase” and “./build/src-generated/vehicleIdentification”. They all have the same structure. The subfolder “src” contains the generated source code for the web service. The subfolder “resources” contains the WSDL file and the xml schemas used. A default build file “build.xml”2 is also generated for the web service.

7.3 Web service source code compilation In this phase of the build the generated source code, as well as the source code located in the source folder “${service-impl-src-dir}”, are compiled and output to the suitable build subfolder of the web service. The structure of these subfolders is introduced in section 7.1 and is highlighted in the Screenshot 5. The compilation is executed in two steps:

This build file is not deployed in this build process.

Axis2-BestPractices.doc / MS

Page 19 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

1. Compile the generated source code: This is achieved with the target "compile.common_src". The compiled code will be output in the folder “common” of the web service build specific subfolders 2. Compile the implementation source code: This is achieved with the target "compile.service_src". The compiled code will be output in the specific subfolder “service”. <target name="compile.common_src" depends=" wsdl2java" description="Compile the wsdl generated code" > <javac debug="on" destdir="${classes-dir}/${service-name}/common"> <src path="${output-dir}/${service-name}/src" /> … </javac> </target> <target name="compile.service_src" depends="compile.common_src" description="Compile service implementation code"> <javac debug="on" destdir="${classes-dir}/${service-name}/service"> <src path="${service-impl-src-dir}" /> … </javac> </target>

The important aspects of the two targets are also highlighted in the summarizing xml fragment above.

7.4 Preparing and packaging the web service As mentioned in section 7.1, the build subdirectory “service” of the web service serves as the basic structure to package the web service. In respect to Axis2, a web service structure looks like as shown in the Screenshot 7. Axis2 has its proper packaging and deployment mechanism. The structure that will be provided and packaged as an “.aar” file (AAR stands for Axis2 Archive) is shown in the Screenshot 7. This structure is described as follows: -

The directory “META-INF” contains the deployment descriptor file “services.xml”, the WSDL description file and the xml schemas for the web service. The directory “lib” contains additional libraries that are possibly needed by the web services. If these libraries are needed for a web service, they must be provided in the directory ${resources-dir}/lib/${service-name} for the build processing. All packages and classes including the source and generated code of the service are located at the root directory.

Axis2-BestPractices.doc / MS

Page 20 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

Screenshot 7: Axis2 web service directory structure

For each web service, an axis2 specific deployment descriptor must be provided. This descriptor provides the information needed to deploy the web service in the axis2 environment. Such information are the message exchange pattern used, the set of operations provided and the skeleton implementation class. The following xml fragment shows the important aspects of this deployment descriptor. <serviceGroup> <service name="VehicleBase"> <messageReceivers> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" class="com.vw_group.xmldefs.retail.vehiclebase.v1_4.VehicleBaseMessageReceiverInOut" ÂŠ Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 21 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

/> </messageReceivers> <parameter name="ServiceClass" locked="false"> com.vw_group.xmldefs.retail.vehiclebase.v1_4.VehicleBaseSkeletonImpl </parameter> <operation name="AliveTest" mep="http://www.w3.org/2004/08/wsdl/in-out"> <actionMapping> http://xmldefs.vw_group.com/retail/VehicleBase/V1.4/AliveTest </actionMapping> … </operation> … </service> </serviceGroup>

The “messageReceiver” element defines through the attribute “mep” the message exchange pattern used by the web service and the implementation class for this purpose. In this example, the mep is the IN/OUT pattern. The implementation class of this pattern is here the “VehicleBaseMessageReceiverInOut”. This class also caries out also the mapping between the AXIOM and the used data binding objects and delegates further processing of the message requests to the skeleton implementation class. The “parameter” element with the attribute name “ServiceClass” defines therefor the skeleton class that should be used by the service. This class is specified in the xml fragment above with the class “VehicleBaseSkeletonImpl”. By executing the WSDL2Java tool, a default skeleton class (“ServicenameSkeleton.java”) and a default deployment descriptor are automatically generated for the web service. The default skeleton class must be extended and implemented in a new one. This new class of the skeleton that should be used by the web service must be defined in the deployment descriptor. The value of the passed parameter “${service-class}” serves this purpose. The default deployment descriptor is parsed and updated with this value. <target name="jar.service" depends="compile.service_src" description="Package the web service as an axis2 aar file"> <copy toDir="${classes-dir}/${service-name}/service/META-INF" failonerror="false"> <fileset dir="${output-dir}/${service-name}/resources"> <include name="*.xml" /> <include name="*.wsdl" /> <include name="*.xsd" /> </fileset> </copy> <replaceregexp …. /> <antcall target="add.external.libs" /> <jar destfile="${dist-dir}/${service-name}.aar"> <fileset dir="${classes-dir}//${service-name}/common" /> <fileset dir="${classes-dir}/${service-name}/service" /> </jar> </target> © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 22 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

At the end of this phase the web service is packaged as jar file in the form “${servicename}.aar” and output in the directory ${dist-dir}.

8 Building the web application When the web services are built and packaged, the whole web application should be prepared and packaged. The target “webapp.war” of the main build serves this purpose. An xml fragment summarizing this target is given bellow. The web application resources located at “${resources-dir}/webapp” are first copied to the build directory and subsequently the built web services, i.e. the “*.aar” files located at the distribution directory “${dist-dir}” are in turn copied to the directory “${webapp-dir}/WEB-INF/services” of the web application.

Screenshot 8: The web application structure

Axis2-BestPractices.doc / MS

Page 23 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

The structure of the web application is pictured in the Screenshot 8. The directory “lib” contains libraries that are needed to carries out the setup of the axis2 environment. The directory “axis2-web” contains the user web interfaces of the application. The directory “services” contains the web service archive files (“*.aar”). There is also the axis2 configuration file “axis2.xml” located at the directory conf. <target name="webapp.war" depends="jar.all.services.aar" description="Build the web app war file"> <copy todir="${webapp-dir}"> <fileset dir="${resources-dir}/webapp" /> </copy> <copy todir="${webapp-dir}/WEB-INF/services"> <fileset file="${dist-dir}/*.aar" /> </copy> <replace file="${webapp-dir}/WEB-INF/services/services.list" token="service1_name_holder" value="${service-name-1}.aar" /> <replace file="${webapp-dir}/WEB-INF/services/services.list" token="service2_name_holder" value="${service-name-2}.aar" /> <!-@TODO: modify the ${webapp-dir}/WEB-INF/web.xml to your own need --> <jar destfile="${dist-dir}/${ws-webapp-name}.war"> <fileset dir="${webapp-dir}" /> </jar> </target>

Note that once the web application is deployed, the provided web admin interface of the application should be used to manage the deployment and the update of single web services. To use this interface, a username and a password are required to log on to the management service of the web application. The username and password are defined in the axis2 configuration file “./conf/axis2.xml”.

9 Deployment The tool described here provides also some optional features for the deployment and the management of the web application on the tomcat web container. The automatic deployment provided by this tool is also tomcat specific. These features should be used without warranty. The update of an already deployed web application may not work properly. The user interface of the tomcat deployment manager should be used instead. Three files are therefor provided. Two self-described property files: •

“./properties/tomcatTask.properties” and

•

“./properties/tomcat.properties”.

Axis2-BestPractices.doc / MS

Page 24 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

10 Service implementation The implementation of the web service, i.e. the implementation of the skeleton depends on the kind the code generation were trigged. In all cases, the auto generated skeleton class must be extended and implemented. The WSDL and code generation module provides support for the engagement of different XML data binding frameworks to the Axis2 functional environment. In a short term, the objective of a XML data binding approach is to provide a well-defined set of mapping rules to represent xml data types as java object types and vice versa. A XML data binding Framework disposes typically of a compiler that consumes xml schema types and generates java source code according to the mapping rules of the framework. The XML data binding frameworks, which Axix2 support are as follows: -

Axis Data Binding (ADB)

XMLBeans

JibX

JaxMe (Experimental)

JaxBRI (Experimental)

The ADB Framework provides a simple and lightweight schema compiler that could be also used outside of the WSDL2Java tool of Axis2. Based on the option “-d” passed, the WSDL2Java tool chooses and plugs in the right XML data binding compiler. The set of the available options comprises “adb”, “xmlbeans”, “jixb”, “jaxme” and “jaxbri”. By default the option “adb” is used, i.e. the ADB Framework. If no data binding framework should be used, the option “none” must be set. In this case, the developers have to get involved in the techniques of the AXIOM. <target name="wsdl2java" depends="service-init" description="Compiler task wsdl2java"> <java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true"> … <arg value="-d" /> <arg value="adb" /> … </java> </target>

For both web services introduced within this document, the ADB Framework (the option “adb”) is used.

Axis2-BestPractices.doc / MS

Page 25 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

10.1 Implementation of the skeleton To help understanding the implementation of the skeleton an overview of the mapping rules of the ADB Framework is introduced bellow. In the “Expanded Mode3” of the ADB code generation, the compiler produces code according to the following rules: 1. All named complex types “<xsd:complexType>” become bean classes. Any attribute or element encapsulated in this complex type will become a field in the generated class4 2. All top level elements become classes 3. Simple type “<xsd:simpleType>” restrictions are handled by replacing the relevant type with the base type The xml fragment bellow is an extract from the type definition of the WSDL file “vehicleBase.wsdl”. Following the rules mentioned above, the ADB compiler will generate one bean class for the complex type named “AliveTestResponse” and another for the element named “AliveTestResponse”. <xsd:complexType name="AliveTestResponse"> <xsd:sequence> <xsd:element name="AliveTestData" type="tns:AliveTestData" minOccurs="1" maxOccurs="1"/> </xsd:sequence> </xsd:complexType> <xsd:element name="AliveTestResponse" type="tns:AliveTestResponse"/>

Generally, the names used for the generated bean classes are mapped from the names of the xml complex types and the xml elements. However, if there are any name-collisions within the same xml namespace, the compiler modifies the mapping names of the bean classes in a suitable form to avoid the names conflict. For the case of the xml schema fragment above the compiler will generate three classes: -

“AliveTestResponse.java” “AliveTestResponse”

that

refers

“AliveTestResponse32.java” “AliveTestResponse”

“AliveTestData.java” that refers to xml element “AliveTestData” included inside the complex type

that

refers

the

xml

complex

the

xml

type

element

There are also two other mode the wrapped mode and the integrated mode, please refer to the ADB howto at the axis2 home page

Please note that the support for constructs other than the sequence and all is not yet implemented

Axis2-BestPractices.doc / MS

Page 26 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

“AliveTestResponse32” has a single field representing the “AliveTestResponse” object that it encapsulates. “AliveTestResponse” has in turn a single (minOccurs=1 / maxOccurs=1) field representing the “AliveTestData” object that it defines. The Drawing 9 pictures a shortcut of an UML reverse engineered model representing those generated classes.

Drawing 9: UML reverse enginered model for generated classes

A summary of source code of the generated for the beans and the skeleton is outlined below: Extract of the bean class generated for the xml element AliveTestData: /** * AliveTestData bean class */ public class AliveTestData implements org.apache.axis2.databinding.ADBBean { …. protected com.vw_group.xmldefs.retail.common.v1_4.Application localAPPLICATION; protected com.vw_group.xmldefs.retail.common.v1_4.Service[] localSERVICE; … }

Extract of the bean class generated for the xml complex type “AliveTestResponse”: /** * AliveTestResponse.java * * This file was auto-generated from WSDL */ public class AliveTestResponse implements org.apache.axis2.databinding.ADBBean { © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 27 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

/** * field for AliveTestData */ protected com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestData localAliveTestData; /** * Auto generated getter method * * @return com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestData */ public com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestData getAliveTestData() { return localAliveTestData; } /** * Auto generated setter method * * @param param * AliveTestData */ public void setAliveTestData( com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestData param) { this.localAliveTestData = param; } â&#x20AC;Ś }

Extract of the bean class generated for the xml element AliveTestResponse: /** * AliveTestResponse32.java * * This file was auto-generated from WSDL */ /** * AliveTestResponse32 bean class */ public class AliveTestResponse32 implements org.apache.axis2.databinding.ADBBean { public static final javax.xml.namespace.QName MY_QNAME = new javax.xml.namespace.QName( "http://xmldefs.vw-group.com/retail/VehicleBase/V1.4", "AliveTestResponse", "ns6"); /** * field for AliveTestResponse */ protected com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestResponse localAliveTestResponse; /** * Auto generated getter method * * @return com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestResponse */ public com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestResponse getAliveTestResponse() { return localAliveTestResponse; } /** * Auto generated setter method * * @param param * AliveTestResponse ÂŠ Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 28 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

*/ public void setAliveTestResponse( com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestResponse param) { this.localAliveTestResponse = param; } … }

For each method declared in the WSDL file a representing java method is included within the generated skeleton. The parameters of those methods conform to the java type system generated for the xml types of the WSDL file, according to the XML data binding strategy used. The methods of the skeleton do no things. They just encapsulate some default behaviour as throwing unsupported operation exceptions.

Extract of the generated skeleton: /** VehicleBaseSkeleton java skeleton for the axisService */ public class VehicleBaseSkeleton { /** * Auto generated method signature * @param aliveTest */ public com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestResponse32 AliveTest (com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTest21 aliveTest) throws ErrorException { // Todo fill this with the necessary business logic throw new java.lang.UnsupportedOperationException("Please implement " + this.getClass().getName() + "#AliveTest"); } … }

import com.vw_group.xmldefs.retail.common.v1_4.Application; import com.vw_group.xmldefs.retail.common.v1_4.Method; import com.vw_group.xmldefs.retail.common.v1_4.Service; …

To implement the web service, an implementing class that extends the generated skeleton must be provided. Each method of the skeleton should be re-implemented. The implementation pattern of each method is simple: -

extract the request data

call the back end logic

if the method returns then construct and replay the response data

Axis2-BestPractices.doc / MS

Page 29 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

Extract of a protype implementation of the skeleton: /** Implementation of the VehicleBaseSkeleton */ public class VehicleBaseSkeletonImpl extends VehicleBaseSkeleton { public com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestResponse32 AliveTest (com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTest21 aliveTest) throws ErrorException { try { /** Extract the request data */ /** Call the back end logic */ /** Construct and return the response data */ InetAddress addr = InetAddress.getLocalHost(); String hostname = addr.getCanonicalHostName(); Application app = new Application(); app.setHOSTNAME(hostname); app.setNAME("DMS-BB"); app.setVENDOR("Volkswagen Group"); app.setVERSION("4.0.0.0"); Service[] services = new Service[1]; services[0] = new Service(); services[0].setDTD("VehicleBase"); services[0].setNAME("VehicleBase"); services[0].setTYPE("unknown"); services[0].setVERSION("1.4.0.0"); Method[] methods = new Method[1]; methods[0] = new Method(); methods[0].setString("GetEquipment"); methods[0].setSTATUS("failure"); methods[0].setTYPE("unknown"); methods[0].setVERSION("1.4.0.1"); services[0].setMETHOD(methods); AliveTestData aliveTestData = new AliveTestData(); aliveTestData.setAPPLICATION(app); aliveTestData.setSERVICE(services); AliveTestResponse aliveTestResponse = new AliveTestResponse(); aliveTestResponse.setAliveTestData(aliveTestData); AliveTestResponse32 aliveTestResponse32 = new AliveTestResponse32(); aliveTestResponse32.setAliveTestResponse(aliveTestResponse); return aliveTestResponse32; } catch (Exception e2) { e2.printStackTrace(); } return null ; } … }

Axis2-BestPractices.doc / MS

Page 30 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD

10.2 Implementation of the stub In this subsection a prototype test-client for the synchronous operation “AliveTest” of the service “vehicleBase” is demonstrated. The test-client uses the auto generated stub “VehicleBaseStub” to connect and to interact with the web service. The generated bean class “AliveTest21” is used to wrap the request data. Since the header elements are optional within the service definition (WSDL) they are all here set to null (AliveTestResponse32 response = stub.AliveTest(aliveTest,null,null,null);). After the call to the web service returns, the AXIOM object representing the response is used to print the retrieved data from the service. import org.apache.axiom.om.OMFactory; import com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTest; import com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTest21; import com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestResponse32; import com.vw_group.xmldefs.retail.vehiclebase.v1_4.VehicleBaseStub; /* * VehicleBaseTest Junit test case */ public class VehicleBaseServiceTest extends junit.framework.TestCase { public static String endpoint = "http://localhost:8080/wswebapp1.4/services/VehicleBase"; public void testAliveTest() throws java.lang.Exception { try { VehicleBaseStub stub = new VehicleBaseStub(endpoint); AliveTest21 aliveTest = AliveTest21.class.newInstance(); AliveTest test = AliveTest.class.newInstance(); aliveTest.setAliveTest(test); /** org.apache.axiom.om.OMElement reqData = aliveTest.getOMElement(com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTest21.MY_QNAME, org.apache.axiom.om.OMAbstractFactory.getOMFactory()); System.out.println(reqData.toString()); */ AliveTestResponse32 response = stub.AliveTest(aliveTest,null,null,null); org.apache.axiom.om.OMElement responseData = response.getOMElement( com.vw_group.xmldefs.retail.vehiclebase.v1_4.AliveTestResponse32.MY_QNAME, org.apache.axiom.om.OMAbstractFactory.getOMFactory()); System.out.println("Response data:"); System.out.println(responseData.toString()); System.out.println("---------------------------------------"); assertNotNull(response); } catch (Exception e) { e.printStackTrace(); } } } © Copyright Volkswagen AG

Axis2-BestPractices.doc / MS

Page 31 of 31

Created: Reviewed: Released:

Y. Naciri, 2007-06-18 J. Hantke <>, YYYY-MM-DD