Axis Java To Soap Function Component

The Axis Java-to-Soap Function Component (FC) is part of the TDI Web Services suite.

Due to limitations of the Axis library used by this component only WSDL (http://www.w3.org/TR/wsdl) version 1.1 documents are supported. Furthermore, the supported message exchange protocol is SOAP 1.1.

This component can be used both on the web service client and on the web service server side. This component receives an Entry or a Java object and produces the SOAP request (when on the client) or response (when on the server) message. It will provide the whole SOAP message, as well as separately the SOAP Header and the SOAP Body to facilitate processing and customization.

The component supports both RPC and Document style.

Configuration

Parameters

WSDL URL

The URL of the WSDL document describing the service

SOAP Operation

The name of the SOAP operation as described in the WSDL file

Return XML as

This drop-down list specifies whether the result is returned as a String or a DOM Element.

Complex Types

This parameter is optional; if specified, it should be a list of fully qualified Java class names (including the package name), where the different elements (Java classes) of this list are separated by one or more of the following symbols: a comma, a semicolon, a space, a carriage return or a new line.

Mode

A flag that indicates whether this FC should generate a SOAP request (when deployed on the client) or a SOAP response (when deployed on the server) message

Use Multi Refs

This parameter is taken into account only when RPC-style web services are used. When Document-style web services are used this parameter has no effect on the generated SOAP message.

If checked and the web service used is an RPC-style web service, the generated SOAP message will use multi-refs. If not checked and the web service used is an RPC-style web service, the generated SOAP message will not use multi-refs.

Operation Parameters

This parameter is a list of Attribute names, where different Attribute names are separated by one or more of the following symbols: a comma, a semicolon, a space, a carriage return or a new line.

Detailed Log

When checked, generates additional log messages.

Comment

Your own comments go here.

Function Component Input

Entry or Java Object. If anything else is passed, an Exception is thrown.

Function Component Output

An Entry object with 3 attributes - one for the whole SOAP message, one for the SOAP Header and one for the SOAP Body. The SOAP message, Body and Header will be either XML strings or DOM objects, as specified by the Return XML as parameter.

Using the FC

This Function Component (FC) serializes the Java representation of a SOAP message into the XML representation of that SOAP message.

• If this FC is passed (a) an Entry with a "soapFault" Attribute, whose value is an object of type org.apache.axis.AxisFault, or (b) a Java object of type org.apache.axis.AxisFault, then the FC generates a SOAP Fault message containing the information stored in the passed AxisFault object.

• If the value of the Return XML as FC parameter is String then the SOAP response message is stored in the "xmlString" Attribute, if an Entry was passed to the FC. However, If the value of the Return XML as FC parameter is DOMElement then the generated SOAP message is stored in the "xmlDOMElement" Attribute , if an Entry was passed to the FC. If a Java Object array (Object[]) was passed to this FC, then the return value of the FC is either a java.lang.String object (when the value of the Return XML as FC parameter is String) or an org.w3c.dom.Element object (when the value is DOMElement).

• If the value of the "soapFault" Attribute passed in is not of type org.apache.axis.AxisFault, then an Exception is thrown.

• Each item from the value of the Operation Parameters FC parameter is the name of an Attribute, which must be present in the Entry passed to the FC. If any of these Attributes is missing, an Exception is thrown.

• If this FC is passed a Java Object array (Object[]) then it passes the SOAP operation each Java Object from this array in the order in which the Objects are stored in the array. If this FC is passed an Entry, then the order and values of the parameters passed to the SOAP operation are determined by the value of the Operation Parameters FC parameter.

• The order of the items from the value of the Operation Parameters FC parameter determines the order in which the Attribute values are passed as parameters to the SOAP operation.

• This FC is capable of generating (a) Document style SOAP messages, (b) RPC style SOAP messages and (c) SOAP Fault messages. The style of the message generated is determined by the WSDL specified by the WSDL URL FC parameter.

• The FC is capable of generating SOAP messages encoded using both "literal" encoding and SOAP Section 5 encoding. The encoding of the message generated is determined by the WSDL specified by the WSDL URL FC parameter.

• The parameter Use Multi Refs can mean different things, but is applicable only for RPC-style messages; when Document-style web services are used this parameter has no effect on the generated SOAP message. If checked and the web service used is an RPC-style web service, the generated SOAP message will use multi-refs. If not checked and the web service used is an RPC-style web service, the generated SOAP message will not use multi-refs.

  The presence of the Use Multi Refs parameter is a consequence of using the Axis library to implement this FC. Currently when the Axis JavaToSoap FC serializes an RPC-style message it uses XML hrefs/multi-refs in the generated SOAP, and this breaks the Axis C++ library. That is why an Axis JavaToSoap FC configuration parameter is present to allow you to switch hrefs/multi-refs on and off.

• This FC is capable of generating SOAP messages containing values of complex types which are defined in the <types> section of a WSDL document. In order to do that this FC requires that (1) the Complex Types FC parameter contains the names all Java classes that implement the complex types used as parameters to the SOAP operation and (2) these Java classes' class files are located in the Java class path of TDI.

• If this FC was passed an Entry object, then the FC stores the generated SOAP message Header and SOAP message Body (apart from the entire generated SOAP message) as Attributes in the returned Entry. If the value of the Return XML as FC parameter is String then the SOAP Header and Body are stored in the "soapHeaderString" and "soapBodyString" Attributes respectively as java.lang.String objects. If the value of the Return XML as FC parameter is DOMElement then the SOAP Header and Body are stored in the "soapHeaderDOMElement" and "soapBodyDOMElement" Attributes respectively as org.w3c.dom.Element objects.

Custom serializers/deserializers

Serialization is the process of converting a Java object to an XML element. Deserialization is the process of converting an XML element to a Java object.

Both AxisJavaToSoap and AxisSoapToJava Function Components provide methods for registering XML type to Java type mappings with custom serializers/deserializers (by default all complex types are serialized/deserialized by Axis' org.apache.axis.encoding.ser.BeanSerializer/org.apache.axis.encoding.ser.BeanDeserializer).

/**
   * This method is analogous to the 'registerTypeMapping' method in org.apache.axis.client.Call.
   * It can be used for configuring serialization/deserialization of Java types, for which the 
   * default serializer/deserializer (org.apache.axis.encoding.ser.BeanSerializer/
   * org.apache.axis.encoding.ser.BeanDeserializer) is not suitable.
   */
    public void registerTypeMapping(Class javaType, 
                                  QName xmlType, 
                                  SerializerFactory serializerFactory, 
                                  DeserializerFactory deserializerFactory)

This method can be invoked on an FC in the "After Initialize" Prolog FC hook through JavaScript™ like this:

var myClass = java.lang.Class.forName("mypackage.MyClass");
var myQName = new javax.xml.namespace.QName("http://www.myserver.com", "MyClass");
var mySerializerFactory = new mypackage.MySerializerFactory();
var myDeserializerFactory = new mypackage.MyDeserializerFactory();

myFC.getFunction().registerTypeMapping(myClass, myQName, mySerializerFactory, myDeserializerFactory);

Serialization/deserialization problems

By default all complex types are serialized/deserialized by Axis’ org.apache.axis.encoding.ser.BeanSerializer/org.apache.axis.encoding.ser.BeanDeserializer. These default serializers and deserializers are not appropriate in certain rare cases. If you face a serialization/deserialization error, it is likely that we need to provide a custom serializer/deserializer.

Here is one of the known cases:

XML Schema list type

When the XML Schema of the WSDL document defines an element to be of the list type:

       <s:simpleType name="MyListType">         <s:list>
          <s:simpleType>
            <s:restriction base="s:string">               <s:enumeration value="One" />
              <s:enumeration value="Two" />
              <s:enumeration value="Three" />
            </s:restriction>
          </s:simpleType>
        </s:list>
      </s:simpleType>

... we will see an error like the following:

  at org.apache.axis.encoding.ser.ArrayDeserializer.characters(ArrayDeserializer.java:502)
    at org.apache.axis.encoding.DeserializationContext.characters(DeserializationContext.java:966)
    at org.apache.axis.message.SAX2EventRecorder.replay(SAX2EventRecorder.java:177)
    at org.apache.axis.message.MessageElement.publishToHandler(MessageElement.java:1141)
    at org.apache.axis.message.RPCElement.deserialize(RPCElement.java:236)
    at org.apache.axis.message.RPCElement.getParams(RPCElement.java:384)
    at org.apache.axis.client.Call.invoke(Call.java:2467)
    at org.apache.axis.client.Call.invoke(Call.java:2366)
    at org.apache.axis.client.Call.invoke(Call.java:1812)
    at com.ibm.di.fc.webservice.AxisEasyInvokeSoapWS.perform(Unknown Source)

The cause of the problem is that org.apache.axis.encoding.ser.ArrayDeserializer is not appropriate for xsd:list types. You should use the org.apache.axis.encoding.ser.SimpleListDeserializer deserializer instead. We can fix the problem using a script like the following in the After Initialize hook of the AxisJavaToSoap/AxisSoapToJava FC:

var javaType = java.lang.Class.forName("[Ljava.lang.String;");
var xmlType = new javax.xml.namespace.QName("http://www.example.com", "MyListType");;
var serializerFactory = new org.apache.axis.encoding.ser.SimpleListSerializerFactory(javaType, xmlType);
var deserializerFactory = new org.apache.axis.encoding.ser.SimpleListDeserializerFactory(javaType, xmlType);
thisConnector.getFunction().registerTypeMapping(javaType, xmlType, serializerFactory, deserializerFactory);

See also

Axis Soap To Java Function Component