Mule : Configuring Axis

Often a service will not want to expose all it's methods to the outside world. One way to restrict the exposure is to set the serviceInterfaces property. This is a list of interface names that the service implements and that should be exposed.

<mule-descriptor name="testService"
    implementation="org.mule.providers.soap.TestServiceComponent"
    inboundEndpoint="axis:http://localhost:38009/mule/services">
    <properties>
        <list name="serviceInterfaces">
            <entry value="org.mule.providers.soap.EchoService"/>
            <entry value="org.mule.providers.soap.DateService"/>
        </list>
    </properties>
</mule-descriptor>

You can also specify one or more methods to expose in a comma separated list, using the axisOptions property (discussed in more detail later).

<mule-descriptor name="testService"
    implementation="org.mule.providers.soap.TestServiceComponent"
    inboundEndpoint="axis:http://localhost:38009/mule/services">
    <properties>
        <map name="axisOptions">
            <property name="allowedMethods" value="echo,getDate"/>
        </map>
    </properties>
</mule-descriptor>

Map as parameter

The AxisConnector treats a Map as container for named parameters, which eventually will be unpacked... This will result into a problem if your exposed service needs to take a Map as a parameter, because the actual Map will never reach the service intact.

There is one way though to configure the connector not to unpack Maps, so that these can be passed as parameters. The configuration of the connector looks as follows:

<connector name="axisConnector" className="org.mule.providers.soap.axis.AxisConnector">
   <properties>
      <property name="treatMapAsNamedParams" value="false" /> 
   </properties> 
</connector>

Setting SOAP Document Style

The style and Uses properties can be set for a service by setting the properties on the mule-descriptor. For example to make your service Document/Literal/Wrapped -

<mule-descriptor name="testService"
    implementation="org.mule.providers.soap.TestServiceComponent"
    inboundEndpoint="axis:http://localhost:38009/mule/services">
    <properties>
        <property name="style" value="Wrapped"/>
        <property name="use" value="Literal"/>
    </properties>
</mule-descriptor>

The style property can be on of: 'RPC' (default), 'Document', 'Message', or 'Wrapped'. And the use property can either be 'Encoded' (default) or 'Literal'.

Setting Service Properties

Service properties are attributes that are set on the Axis service object itself. The two useful properties to set here are scope and allowedMethods, through there may be others depending on your Axis server configuration.

<mule-descriptor name="testService"
    implementation="org.mule.providers.soap.TestServiceComponent"
    inboundEndpoint="axis:http://localhost:38009/mule/services">
    <properties>
        <map name="axisOptions">
            <property name="allowedMethods" value="*"/>
            <property name="scope" value="Application"/>
        </map>
    </properties>
</mule-descriptor>

Customising the soapAction format

By default Mule uses the axis endpoint as the soapAction when make WS calls. This is fine for Axis clients but may not work with .Net clients. In fact the soapAction can be different across different soap implementations so developers need a way to customise how the soap Action is formatted.

Mule users can set the soapAction on the outbound endpoint making the soap request i.e.

<endpoint address="axis:http://localhost:38011/mule/echoService?method=echo" synchronous="true">
    <properties>
        <property name="soapAction" value="http://localhost:38011/${method}"/>
    </properties>
</endpoint>

If using the Mule Client you can set the soapAction as a property when making the call.

The soap Action can be a static value or you can use template variables such as the method variable used above. The set of variables that can be used are listed below.

Setting Named Parameters

Some WebService clients require that all method parameters of a call should be named. You can do this in Mule in two ways.

1. In the Mule Xml the soap method parameters for a servie can be set on the endpoint using the soapMethods property map.

<endpoint address="axis:http://localhost:38011/mule/echoService?method=echo" synchronous="true">
    <properties>
        <map name="soapMethods">
            <property name="echo" value="value;string;in,return;string"/>
        </map>
    </properties>
</endpoint>

Within the map element you can define 1 or more property elements where the name attribute is the method name and the value is a string representation of the named parameters of the method and the return type. The parameter string is in the format of -

[paramName1];[type];[mode],[paramName2];[type]; ...,[return;type]

The parameterName is the name of the parameter. The type is an XSD string such as int, long, map, etc. and the parameter mode can be in, out or inout. The return type is also an XSD type string. You can also set the returnClass instead of return and provider a fuly qualified classname instead of an XSD type.

<endpoint address="axis:http://localhost:38011/mule/concatService?method=concat" synchronous="true">
    <properties>
        <map name="soapMethods">
           <list name="concat">
              <entry value="string1;string;in"/>
              <entry value="string2;string;in"/>
              <entry value="result;string;out"/>
         </list>
      </map>
    </properties>
</endpoint>

Controlling Namespaces

Namespaces for elements can be controled at the method and parameter level or declare a namespace on the method with a prefix of 'foo' with a uri of 'http://mycompany.com/foo' use the following -

<endpoint address="axis:http://localhost:38011/mule/echoService?method=echo" synchronous="true">
    <properties>
        <map name="soapMethods">
            <property name="qname{foo:echo:http://mycompany.com/foo}" value="value;string;in,result;string;out"/>
        </map>
    </properties>
</endpoint>

qname{[prefix]:[localname]:[namespace]}

You can supply either just a localname, localname and namespace or a prefix, localname and namesspace.

The namespace for the method will be applied to the parameters also, but you can set the namespace for each parameter explicitly also using an identical syntax i.e. -

<endpoint address="axis:http://localhost:38011/mule/echoService?method=echo" synchronous="true">
    <properties>
        <map name="soapMethods">
           <list name="qname{foo:echo:http://mycompany.com/foo}">
              <entry value="qname{foo1:echo1:http://mycompany.com/foo1};string;in"/>
              <entry value="return;string"/>
         </list>
      </map>
    </properties>
</endpoint>

To set method parameter name using the MuleClient you need to create a SoapMethod object and set it on the properties when making the call. The example below shows how to do this.

MuleClient client = new MuleClient();
Map props = new HashMap();
//create the soap method passing in the method name and return type
SoapMethod soapMethod = new SoapMethod("echo", NamedParameter.XSD_STRING);
//add one or more parameters
soapMethod.addNamedParameter("value", NamedParameter.XSD_STRING, ParameterMode.IN);
//set the soap method as a property and pass the properties
//when making the call
props.put(MuleProperties.MULE_SOAP_METHOD, soapMethod);

UMOMessage result = client.send("axis:http://localhost:38011/mule/echoService?method=echo",
                                                                        "Hello", props);

Note that you can use the 'qname{}' notation for setting method and parameter names using the MuleClient.

Controlling WSDL Generation

Most commonly, you will want to set the namespace for your service. this can be done by setting the 'serviceNamespace' property on your service i.e.

<mule-descriptor name="testService"
    implementation="org.mule.providers.soap.TestServiceComponent">
    <inbound-router>
        <endpoint address="axis:[http://localhost:38009/mule/services]"/>
    </inbound-router>
    <properties>
        <property name="serviceNamespace" value="http://foo.namespace"/>
    </properties>
</mule-descriptor>

You can also set the 'wsdlFile' property to the location of a wsdl document to use for this service if you do not want an autogenerated WSDL document.

You can control the values used in Axis wsdl generation by setting wsdl specific Axis options. Not you do not need to changes these values, but if you want to you can. The options you can set are -

To change the wsdlServiceElement name attribute to MyService in the generated Wsdl for a service use the following -

<mule-descriptor name="testService"
    implementation="org.mule.providers.soap.TestServiceComponent">
    <inbound-router>
        <endpoint address="axis:http://localhost:38009/mule/services"/>
    </inbound-router>
    <properties>
        <map name="axisOptions">
            <property name="wsdlServiceElement" value="MyService"/>
        </map>
    </properties>
</mule-descriptor>

Type mappings

Note that as of Axis 1.2-RC3 it is no longer necessary to configure Type Mappings as bean serialisation is handled automatically by Axis. If you are using an older version of Axis Type Mappings may need to be configured.

Mule enables default type mappings for object serialisation between soap calls. This means, for the most part serialisation/deserialisation of call parameters and return objects is handled automatically by Axis. This works for most java types including primitives, Numbers, Strings, Arrays and Collections, it also works for JavaBeans whose attributes comprise of these types. However, it does not work where you have a bean that has as another bean as an attribute; Axis will complain that it doesn't know how to handle the bean attribute.

Mule handles this by allowing you to specify a list of beanTypes that Axis needs to understand in order to manage your service. For example, say you have a PersonService service that will get a Person object when passed the persons name. The Person object contains an Address object. The configuration will look like -

<mule-descriptor name="personService"
    implementation="org.foo.PersonServiceComponent"
    inboundEndpoint="axis:http://localhost:38009/mule/services">
    <properties>
        <list name="beanTypes">
            <entry value="org.foo.Address"/>
        </list>
    </properties>
</mule-descriptor>

It is important to note that only custom types should be listed. If any standard types are present, like java.util.ArrayList, Axis may produce serialization errors.

For convenience, the BeanTypes property can be set on an Axis connector configuration so that all services that use the connector will have the types registered in the TypeRegistry for the service.

<connector name="axisConnector"
   className="org.mule.providers.soap.axis.AxisConnector">
    <properties>
        <list name="beanTypes">
            <entry value="org.foo.Address"/>
        </list>
    </properties>
</connector>

By default, an axis connector is created (if one doesn't exist already) when the axis endpoint is processed. For more information about configuring Connectors and Providers see Configuring Endpoints.

Customising the Axis Service Component

The Axis Service component is a Mule managed component that handles axis service requests. This component is equivilent to the Axis Servlet used when running Axis in a servlet container. Being a Mule managed component you can configure how threading, pooling and queuing behaves for the component. By default, when the Axis Service component is created it will be assigned the default threading, pooling and queuing as defined in the MuleConfiguration object. If your Mule instance is receiving a high number of requests you may want to increase the compoent pool size. To customise the Axis Service component you need to configure a mule-descriptor with a name of _axisServiceComponent and set the relevant properties on it. For example -

<mule-descriptor
    name="_axisServiceComponent"
    implementation="org.mule.providers.soap.axis.AxisServiceComponent">
    <threading-profile maxBufferSize="100" threadTTL="600000"
         maxThreadsActive="30" maxThreadsIdle="20" />
    <pooling-profile exhaustedAction="GROW" maxActive="20"
         maxIdle="20"/>
</mule-descriptor>

Service Initialisation Callback

If you need further control over the Axis service created by Mule it is possible for your component to implement AxisInitialisable.

AxisInitialisable.java

public interface AxisInitialisable
{
    public void initialise(SOAPService service) throws InitialisationException;
}

This gets called when the service is initialised and allows you to customise the service configuration form your Mule component.

Quick Links

Configuring Mule Components As Axis Services

Controlling exposed methods