Axis System Integration Guide

1.0 Version

Table of Contents

Introduction
Pluggable APIs
  Components
  Logging/Tracing
  Configuration
  Handlers
  Internationalization
  Performance Monitoring
  Encoding
  WSDL Parser and Code Generator Framework

Introduction

The primary purpose of this guide is to present how AXIS can be integrated into an existing web application server, such as Tomcat or WebSphere, for example.  AXIS has a number of Pluggable APIs that are necessary for such an integration.

The reader may find useful background information in the Architecture Guide.

Pluggable APIs

The following are the points that are pluggable in order to integrate AXIS into a web application server. The first subsection details a number of pluggable components in general. More details are provided for other components in the remaining subsections.

Components

This section describes in general how to plug specializations of various components into AXIS.

General Strategy

To override the default behavior for a pluggable component:

Example 1

To override the default behavior for the Java Compiler:

Example 2

To override the default behavior for the SocketFactory in an environment that does not allow resources to be located/loaded appropriately, or where the behavior needs to be forced to a specific implementation:

Reference

Component/Package Factory Interface Optional System Property Default Implementation
org.apache.axis.components.compiler CompilerFactory.getCompiler() Compiler axis.Compiler Javac
org.apache.axis.components.image ImageIOFactory.getImageIO() ImageIO axis.ImageIO MerlinIO, JimiIO, JDK13IO
org.apache.axis.components.jms JMSVendorAdapterFactory.getJMSVendorAdapter() JMSVendorAdapter JNDIVendorAdapter
org.apache.axis.components.net SocketFactoryFactory.getFactory() SocketFactory axis.socketFactory DefaultSocketFactory
org.apache.axis.components.net SocketFactoryFactory.getSecureFactory() SocketFactory axis.socketSecureFactory JSSESocketFactory

Logging/Tracing

AXIS logging and tracing is based on the Logging component of the Jakarta Commons project, or the Jakarta Commons Logging (JCL) SPI. The JCL provides a Log interface with thin-wrapper implementations for other logging tools, including Log4J, Avalon LogKit, and JDK 1.4. The interface maps closely to Log4J and LogKit.

Justification/Rationale

A pluggable logging/trace facility enables AXIS to direct logging/trace messages to a host web application server's logging facility. A central logging facility with a single point of configuration/control is superior to distinct logging mechanisms for each of a multitude of middleware components that are to be integrated into a web application server.

Integration

The minimum requirement to integrate with another logger is to provide an implementation of the org.apache.commons.logging.Log interface. In addition, an implementation of the org.apache.commons.logging.LogFactory interface can be provided to meet specific requirements for connecting to, or instantiating, a logger.

Mechanism

Logger Configuration

Configuration


The internal data model used by AXIS is based on an AXIS specific data model: Web Services Deployment Descriptor (WSDD). AXIS initially obtains the WSDD information for a service from an instance of org.apache.axis.EngineConfiguration.

The EngineConfiguration is provided by an implementation of the interface org.apache.axis.EngineConfigurationFactory, which currently provides methods that return client and server configurations.

Our focus will be how to define the implementation class for EngineConfigurationFactory.

Handlers

See the Architecture Guide for current information on Handlers.

Internationalization

AXIS supports internationalization by providing both a property file of the strings used in AXIS, and an extension mechanism that facilitates accessing internal AXIS messages and extending the messages available to integration code based on existing AXIS code.

Translation

Extending Message Files

AXIS provides a Message file extension mechanism that allows AXIS-based code to use AXIS message keys, as well as new message keys unique to the extended code.

Performance Monitoring

AXIS does not yet include specific Performance Monitoring Plugs.

Encoding

AXIS does not yet include an Encoding Plug.

WSDL Parser and Code Generator Framework

WSDL2Java is AXIS's tool to generate Java artifacts from WSDL.  This tool is extensible.  If users of AXIS wish to extend AXIS, then they may also need to extend or change the generated artifacts.  For example, if AXIS is inserted into some product which has an existing deployment model that's different than AXIS's deployment model, then that product's version of WSDL2Java will be required to generate deployment descriptors other than AXIS's deploy.wsdd.

What follows immediately is a description of the framework.  If you would rather dive down into the dirt of examples, you could learn a good deal just from them.  Then you could come back up here and learn the gory details.

There are three parts to WSDL2Java:

  1. The symbol table
  2. The parser front end with a generator framework
  3. The code generator back end (WSDL2Java itself)

Symbol Table

The symbol table, found in org.apache.axis.wsdl.symbolTable, will contain all the symbols from a WSDL document, both the symbols from the WSDL constructs themselves (portType, binding, etc), and also the XML schema types that the WSDL refers to.

NOTE:  Needs lots of description here.

The symbol table is not extensible, but you can add fields to it by using the Dynamic Variables construct:

Parser Front End and Generator Framework

The parser front end and generator framework is located in org.apache.axis.wsdl.gen.  The parser front end consists of two files:

Code Generator Back End

The meat of the WSDL2Java back end generators is in org.apache.axis.wsdl.toJava.  Emitter extends Parser.  org.apache.axis.wsdl.WSDL2Java extends WSDL2.  JavaGeneratorFactory implements GeneratorFactory.  And the various JavaXXXWriter classes implement the Generator interface.

NOTE:  Need lots more description here...

WSDL Framework Extension Examples

Everything above sounds rather complex.  It is, but that doesn't mean your extension has to be.
Example 1 - Simple extension of WSDL2Java - additional artifact
The simplest extension of the framework is one which generates everything that WSDL2Java already generates, plus something new.  Example 1 is such an extension.  It's extra artifact is a file for each service that lists that service's ports.  I don't know why you'd want to do this, but it makes for a good, simple example.  See samples/integrationGuide/example1 for the complete implementation of this example.
 
Example 2 - Not quite as simple an extension of WSDL2Java - change an artifact
In this example, we'll replace deploy.wsdd with mydeploy.useless.  For brevity, mydeploy.useless is rather useless.  Making it useful is an exercise left to the reader.  See samples/integrationGuide/example2 for the complete implementation of this example.