Essential Web Services: SOAP, WSDL, UDDI

What is Axis?

Axis is essentially a SOAP engine -- a framework for constructing SOAP processors such as clients, servers, gateways, etc. But Axis isn't just a SOAP engine -- it also includes:

• a simple stand-alone server,

• a server which plugs into servlet engines such as Tomcat,

• extensive support for the Web Service Description Language (WSDL),

• emitter tooling that generates Java classes from WSDL.

• some sample programs, and

• a tool for monitoring TCP/IP packets.

Preliminary security extensions, which can integrate with Servlet 2.2 security/roles

An EJB provider for accessing EJB's as Web Services

Standalone version of the server (with HTTP support)

org.apache.axis.client.Call->javax.xml.rpc.Call (1.1) -> SOAP 1.1 ? 

WSDL support

Axis supports the Web Service Description Language, version 1.1, which allows you to easily build stubs to access remote services, and also to automatically export machine-readable descriptions of your deployed services from Axis.

 

SOAP support

SOAP 1.1/1.2 compliant engine

Preliminary support for the SOAP with Attachments specification

SOAP Encoding Datatypes: Alongside the XSD datatypes are the SOAP 'Section 5' datatypes that are all nillable, and so only ever map to the wrapper classes. These types exist because they all support the "ID" and "HREF" attributes, and so will be used when in an RPC-encoded context to support multi-ref serialization.

 

Exceptions

This is an area which causes plenty of confusion, and indeed, the author of this section is not entirely sure how everything works, especially from an interop perspective. This means treat this section as incomplete and potentially inaccurate. See also section 5.5.5 and chapter 14 in the JAX-RPC specification

RemoteExceptions map to SOAP Faults

If the server method throws a java.rmi.RemoteException then this will be mapped into a SOAP Fault. The faultcode of this will contain the classname of the fault. The recipient is expected to deserialize the body of the fault against the classname.

Exceptions are represented as wsdl:fault elements

If a method is marked as throwing an Exception that is not an instance or a subclass of java.rmi.RemoteException, then things are subtly different. The exception is no longer a SOAP Fault, but described as a wsdl:fault in the WSDL of the method. According to the JAX-RPC specification, your subclass of Exception must have accessor methods to access all the fields in the object to be marshalled and a constructor that takes as parameters all the same fields (i.e, arguments of the same name and type). This is a kind of immutable variant of a normal JavaBean. The fields in the object must be of the datatypes that can be reliably mapped into WSDL.

If your exception meets this specification, then the WSDL describing the method will describe the exception too, enabling callers to create stub implementations of the exception, regardless of platform.

 

Query String Handlers

By default, Axis provides for three Axis servlet query string handlers (?list, ?method, and ?wsdl).

 

Some Default Handlers

JAXRPCHandler

Wrapper around JAX-RPC compliant handlers that exposes an Axis handler interface to the engine.

 

HTTPSender

A Handler which sends the request message to a remote server via HTTP, and collects the response message.

 

LocalSender

A Handler which sends the request message to a "local" AxisServer, which will process it and return a response message. This is extremely useful for testing, and is by default mapped to the "local:" transport. So, for instance, you can test the AdminClient by doing something like this:

% java org.apache.axis.client.AdminClient -llocal:// list

 

Service, Targeted Chain, and Provider

A service is a special kind of Targeted Chain in which the pivot Handler is known as a "provider".

 

Message Context

Each message context may be associated with a request Message and/or a response Message. Each Message has a SOAPPart and an Attachments object, both of which implement the Part interface. The typing of Message Contexts needs to be carefully considered in relation to the Axis architecture. Since a Message Context appears on the Handler interface, it should not be tied to or biassed in favour of  SOAP. The current implementation is marginally biassed towards SOAP in that the setServiceHandler method narrows the specified Handler to a SOAPService.
 

Integration with axis

In some start up method(): properties.put("axis.EngineConfigFactory", "com.our.ws.CustomFactory");

public class CustomFactory implements EngineConfigurationFactory {

    public EngineConfiguration getClientEngineConfig();

    public EngineConfiguration getServerEngineConfig();

    public static EngineConfigurationFactory newFactory(Object param);
}
 

Engine Configuration

The EngineConfiguration interface is the means of configuring the Handler factories and global options of an engine instance. An instance of a concrete implementation of EngineConfiguration must be passed to the engine when it is created and the engine must be notified if the EngineConfiguration contents are modified. The engine keeps a reference to the EngineConfiguration and then uses it to obtain Handler factories and global options.

The EngineConfiguration interface belongs to the Message Flow subsystem which means that the Message Flow subsystem does not depend on the Administration subsystem.

WSDD Configuration: Configuration based on wsdd, but not server-config.wsdd file, it can be dynamic/further configured by Admin.deploy()

 

Global Axis Configuration

The server is configured (by default) by values in the server-config.wsdd file, though a dedicated Axis user can write their own configuration handler, and so store configuration data in an LDAP server, database, remote web service, etc. Consult the source on details as to how to do that. You can also add options to the web.xml file and have them picked up automatically. We don't encourage that as it is nice to keep configuration stuff in one place.

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.

• Justification/Rationale
  While the default behaviour is sufficient for general use of Axis, integrating Axis into an existing application server may require an alternate deployment model. A customized implementation of the EngineConfigurationFactory would map from the hosts deployment model to Axis's internal deployment model.
   

• Mechanism
  The relevant sequence of instructions used to obtain configuration information and initialize Axis is as follows:

  
  EngineConfigurationFactory factory = EngineConfigurationFactoryFinder(someContext);
EngineCongfiguration config = factory.getClientEngineConfig();
AxisClient = new AxisClient(config);

  
  The details may vary (server versus client, whether other factories are involved, etc). Regardless, the point is that integration code is responsible for calling EngineConfigurationFactoryFinder(someContext) and ensuring that the results are handed to Axis.  someContext is key to how the factory finder locates the appropariate implementation of EngineConfigurationFactory to be used, if any.

  EngineConfigurationFactoryFinder works as follows:
   

  • Obtain a list of classes that implement org.apache.axis.EngineConfigurationFactory, in the following order:

    • The value of the system property axis.EngineConfigFactory.

    • The value of the system property org.apache.axis.EngineConfigurationFactory.

    • Locate all resources named META-INF/services/org.apache.axis.EngineConfigurationFactory. Each line of such a resource identifies the name of a class implementing the interface ('#' comments, through end-of-line).

    • org.apache.axis.configuration.EngineConfigurationFactoryServlet

    • org.apache.axis.configuration.EngineConfigurationFactoryDefault

    
     

  • Classes implementing EngineConfigurationFactory are required to provide the method
     

    public static EngineConfigurationFactory newFactory(Object)

    
    This method is called, passing someContext as the parameter.
     

  • The newFactory method is required to check the someContext parameter to determine if it is meaningfull to the class (at a minimum, verify that it is of an expected type, or class) and may, in addition, examine the overall runtime environment. If the environment can provide information required by an EngineConfigurationFactory, then the newFactory() may return in instance of that factory. Otherwise, newFactory() must return null.
     

  • EngineConfigurationFactoryFinder returns the first non-null factory it obtains.

  
   

• Default behavior
  The default behaviour is provided by the last two elements of the list of implementing classes, as described above:

  • org.apache.axis.configuration.EngineConfigurationFactoryServlet
newFactory(obj) is called. If obj instanceof javax.servlet.ServletContext is true, then an instance of this class is returned.

    The default Servlet factory is expected to function as a server (as a client it will incorrectly attempt to load the WSDD file client-config.wsdd from the current working directory!).

    The default Servlet factory will open the Web Application resource /WEB-INF/server-config.wsdd (The name of this file may be changed using the system property axis.ServerConfigFile):

    • If it exists as an accessible file (i.e. not in a JAR/WAR file), then it opens it as a file. This allows changes to be saved, if changes are allowed & made using the Admin tools.

    • If it does not exist as a file, then an attempt is made to access it as a resource stream (getResourceAsStream), which works for JAR/WAR file contents.

    • If the resource is simply not available, an attempt is made to create it as a file.

    • If all above attempts fail, a final attempt is made to access org.apache.axis.server.server-config.wsdd as a data stream.

    
     

  • org.apache.axis.configuration.EngineConfigurationFactoryDefault
newFactory(obj) is called. If obj is null then an instance of this class is returned. A non-null obj is presumed to require a non-default factory.

    The default factory will load the WSDD files client-config.wsdd or server-config.wsdd, as appropriate, from the current working directory. The names of these files may be changed using the system properties axis.ClientConfigFile and axis.ServerConfigFile, respectively.

     

Thirdparty Cooperation

Tomcat 4.x and Java 1.4

Java 1.4 changed the rules as to to how packages beginning in java.* and javax.* get loaded. Specifically, they only get loaded from endorsed directories. jaxrpc.jar and saaj.jar contain javax packages, so they may not get picked up. If happyaxis.jsp (see below) cannot find the relevant packages, copy them from axis/WEB-INF/lib to CATALINA_HOME/common/lib and restart Tomcat.

WebLogic 8.1

WebLogic 8.1 ships with webservices.jar that conflicts with Axis' saaj.jar and prevents Axis 1.2 from working right out of the box. This conflict exists because WebLogic uses an older definition of javax.xml.soap.* package from Java Web Services Developer Pack Version 1.0 , whereas Axis uses a newer revision from J2EE 1.4.

However, there are two alternative configuration changes that enable Axis based web services to run on Weblogic 8.1.

• In a webapp containing Axis, set <prefer-web-inf-classes> element in WEB-INF/weblogic.xml to true. An example of weblogic.xml is shown below:

  <weblogic-web-app>
   <container-descriptor>
    <prefer-web-inf-classes>true</prefer-web-inf-classes>
   </container-descriptor>
  </weblogic-web-app>
  

  If set to true, the <prefer-web-inf-classes> element will force WebLogic's classloader to load classes located in the WEB-INF directory of a web application in preference to application or system classes. This is a recommended approach since it only impacts a single web module.

• In a script used to start WebLogic server, modify CLASSPATH property by placing Axis's saaj.jar library in front of WeLlogic's webservices.jar. NOTE: This approach impacts all applications deployed on a particular WebLogic instance and may prevent them from using WebLogic's webservices.

For more information on how WebLogic's class loader works, see WebLogic Server Application Classloading .

 

Invoke

Normally, a client program would not instantiate a stub directly. It would instead instantiate a service locator and call a get method which returns a stub. This locator is derived from the service clause in the WSDL.

 

Authenticating the caller

The new Web Service security proposals offer to authenticate your callers to your end point, and vice-versa. Axis does not yet implement these, but we do support XML signatures via a sister project.

The other approach is to validate at the transport level, using HTTPS. Configuring your web server to support https is definitely beyond the scope of Axis documentation: consult your server docs. To support https in the Axis client, you need to ensure the client has https support in the runtime. This is automatic for Java1.4+; older versions need to add JSSE support through Sun or an alternate provider.

Once you have HTTPS working at both ends you need to have the client trust the server certificate -usually automatic for those signed by central certification authorities, a manual process for home rolled certificates.

Clients can authenticate themselves with client certificates, or HTTP basic authentication. The latter is too weak to be trustable on a non-encrypted channel, but works over HTTPS. The MessageContext class will be configured with the username and password of the sender when SOAP messages are posted to the endpoint; use the appropriate getters to see these values. Note that Axis does not yet integrate with the servlet API authentication stuff. Although the forms authentication is literally off-axis when it comes to SOAP calls, the UserPrincipal notion and integration with server configuration gives some incentive for integration. (this is a hint to developers out there)

[When Server do not need "Client Authentication" in a HTTPS session at transport level, but we need authenticate client at application level, then we can use HTTP basic authentication over HTTPS session. see <<Essential SSL>>]

Axis does not (yet) support HTTP1.1 Digest Authentication; if it does get added it will be via the HttpClient libraries.

 

WSDL2Java

This tool takes a description of a web service written in WSDL and emits Java artefacts used to access the web service.

There are three layers inside the tool:

• framework: SymbolTable, Emitter, WriterFactory

• WSDL2Java plugin to the framework: WSDL2Java (the main), JavaWriterFactory, and all the WSDL-relative writers: JavaPortTypeWriter, JavaBindingWriter, etc.

• The actual WSDL2Java emitters, one for each file generated: JavaInterfaceWriter, JavaStubWriter, etc.

• So: public class WSDL2Java extends org.apache.axis.wsdl.WSDL2Java{
          public WSDL2Java() {
              super();
              getParser().setFactory(new CustomizedJavaGeneratorFactory(getParser()));
          }

-T, --typeMappingVersion:

indicate 1.1 or 1.2. The default is 1.1 (SOAP 1.1 JAX-RPC compliant. 1.2 indicates SOAP 1.1 encoded.) http://issues.apache.org/jira/browse/AXIS-2467

-W, --noWrapped

This turns off the special treatment of what is called "wrapped" document/literal style operations.  By default, WSDL2Java will recognize the following conditions:

• If an input message has is a single part.

• The part is an element.

• The element has the same name as the operation

• The element's complex type has no attributes

 

Wrapped Style

"document" style means the messages in and out of the service are exactly as they are describe by the XML Schema in the WSDL. "wrapped" is a subset of the document style. The arguments to the operation are wrapped up in and element that has the same name as the operation. This is the style of service .NET generates by default. The generated WSDL specifies document style (and literal use) but Axis will 'unwrapped' the parts of the message for the Axis service at the back end.

When it sees this, WSDL2Java will 'unwrap' the top level element, and treat each of the components of the element as arguments to the operation. This type of WSDL is the default for Microsoft .NET web services, which wrap up RPC style arguments in this top level schema element.

 

sendMultiRefs

One item that just breaks, is that .NET can't handle multiRef's, so to make sure you are being a good client do the following:

YourNameWebServiceLocator locator = new YourNameWebServiceLocator();

locator.getEngine().setOption("sendMultiRefs", Boolean.FALSE);
 

No more multiRefs. .NET is happy. (http://www.almaer.com/blog/archives/000872.html)

 

Open Issues:

1. Whether Individual Service Configuration can override the <globalConfiguration>? for example:

<globalConfiguration>
    ...
    <parameter name="sendMultiRefs" value="true"/>
    ...
</globalConfiguration>

then 

<service name=...>
 <parameter name="className" value="org.apache.mystuff.MyService"/>
 <parameter name="sendMultiRefs" value="false"/>
 <operation ... />

 <typeMapping ... />  
 <beanMapping ... />  
</service>

Will it work? Thanks.

 

2. wrapArrays:

I found even you specified the "wrapArrays" option, axis will not generate wrap class always

WSDL2Java

wrapArrays = false

wrapArrays = true

return value wrapped?

param wrapped?

exception wrapped?

return value wrapped?

param wrapped?

exception wrapped?

Document/Literal

no

no

sometimes no?

no

no

Yes

Document/LitWrap

//TODO...

         

RPC/Literal

           

RPC/Encoded

           

 

 

By default, axis will use the value of a system property "axis.ServerConfigFile" to overwrite the default "server-config.wsdd" file for server engine (and "axis.ClientConfigFile" for client engine).