The Simple Object Access Protocol (SOAP) defines the three parts described here to every message:

Figure 6-1 shows how Mule can interact with web services. On the left side of the diagram we can see that a third-party item (such as an application) is making a web service call, which refers to a service that is hosted in Mule. This web service call is nothing more than an inbound endpoint for the service. By using inbound web service endpoints Mule can host web services that are accessible to any other application.

On the right side of the diagram we can see that a service in Mule is making a web service call to a third-party item. This web service call is nothing more than an outbound endpoint for the service. By using outbound web service endpoints, Mule can connect to web services hosted by any other application.

In Mule you can configure a component to have a web service as an inbound endpoint. This will cause the component to be hosted as a web service; it will be visible to outside applications as a web service automatically. When a request is received, your component will be invoked.

A component can also be configured to have a web service as an outbound endpoint. This will cause Mule to transform the original request into a SOAP request and route it to a web service. The web service can be hosted either locally or remotely.

Figure 6.1. Mule and Web Services

The web service may also be hosted inside a Mule instance or it could be an external web service. External web services can be constructed using any technology that implements the web services standards, for example Axis, XFire, or .NET. These all require different configurations as we shall see.

Data is transferred through an XML packet across the HTTP transport, which is implicitly used when you define web service endpoints. SOAP can also be used across other transports such as JMS.

XFire is a Java SOAP framework that provides an easy-to-use API to build web services. It uses a low-memory model based on STaX (Streaming API for XML) that delivers high performance and can be used over HTTP, JMS, XMPP, and VM transports. An XFire transport is included with Mule 1, but as mentioned previously, for Mule 2 it has been moved to MuleForge.

In 2006, the Celtix and XFire communities merged to provide a single web service platform, CXF (the name is based on the merging of Celtix and XFire). The result is an Apache project that provides an easy-to-use API that lets you build services that can communicate using SOAP, RESTful HTTP, or CORBA over HTTP, JMS, VM, or JBI.

CXF uses the Java API for XML Web Services (JAX-WS) standard, which is a series of APIs and annotations that allow you to easily build web services. In Mule it normally operates over HTTP, but it can be used across the other transports too.

The required XML namespace and schema are listed here, and are available from the MuleSource site:

xmlns:cxf=
 "http://www.mulesource.org/schema/mule/cxf/2.0"
xsi:schemaLocation=
 "http://www.mulesource.org/schema/mule/cxf/2.0
  http://www.mulesource.org/schema/mule/cxf/2.0/
     mule-cxf.xsd"

One key attribute on the CXF connector is the defaultFrontend attribute, which allows you to specify that your CXF web services do not contain any JAX-WS annotations. By default this is set to jaxws, but you can change it to simple if your classes do not have annotations.

The endpoint attributes are as follows:

None of these attributes are required.

Services in Mule can become CXF web services provided they have an inbound CXF endpoint. The most significant consideration is whether you can, or want to, use annotations.

Simple Front-End Implementation

If your classes are POJOs that cannot use annotations, you will need to implement your web service via your Mule configuration. This approach means you do not need to modify any code and makes it the ideal approach for migration from XFire and previous Mule versions. The web service would be configuration-driven since every setting will be included in the Mule configuration file.

Here's an example of a simple front end to any CXF web service implemented in Mule:

<cxf:connector name="CXFConnector"
                defaultFrontend="simple"/>

The preceding code snippet shows how the CXF connector can be configured to use the defaultFrontend attribute so that it will not look for the annotations within the hosted classes. Setting this attribute here will enable it for all endpoints, but you can configure this on an endpoint-by-endpoint basis using the endpoint's frontend attribute as shown in the following example:

<service name="ticketStatus">
   <inbound>
      <cxf:inbound-endpoint frontend="simple"
           address="http://10.0.0.1/status"/>
   </inbound>
   <component class="com.ricstonairways.Ticket"/>
</service>

Using Annotations

You can also use JAX-WS annotations in your classes to describe the CXF web service. You will need to create an interface to the class that you wish to host as a web service and annotate this class according to the JAX-WS API. You can also include references to an existing WSDL if you develop by contract rather than let the CXF transport generate the WSDL for you.

A key benefit of annotations is that they provide you with a short and concise manner in which to describe your web service. This "shorthand" reduces the amount of code that is needed.

Our next example shows an interface to a class that we will then use as a web service. It has a single method that returns the status for an airline ticket represented by the passenger name record (PNR) identifier.

package com.ricstonairways;

import javax.jws.WebService;

@WebService

public interface StatusInterface
   { String getStatus(String paxRecord); }

The class that implements the previous interface is shown in the next example. It is annotated to show which interface is going to be used and the name of the web service.

package com.ricstonairways;

import javax.jws.WebService;

@WebService(endpointInterface ="com.ricstonairways.
StatusInterface", serviceName = "PNRStatus")

public class statusRetrieval implements StatusInterface
{
   public String getStatus (String paxRecord) {
      return paxList.find (paxRecord).status;
   }
}

The Mule configuration shown here allows us to host this annotated class as a CXF web service. It is similar to the configuration shown earlier but without the frontEnd attribute.

<model name="CxfExample">
   <service name="ticketStatus">
      <inbound>
         <cxf:inbound-endpoint address=
               "http://10.0.0.1/status"/>
      </inbound>
      <component class="com.ricstonairways.
                 statusRetrieval"/>
   </service>
</model>

You can invoke this web service from within a web browser by using the http://host/service/OPERATION/PARAM_NAME/PARAM_VALUE format, which would look like this URL: http://10.0.0.1/status/ticketStatus/flightStatus/flightCode/RA1234.

Programming by Contract

If the WSDL is defined before you start creating classes and services, then this is known as contract-first programming. In such cases, you would not want the CXF transport to generate a WSDL automatically but use an existing one. You also need to be sure that the classes in use match the descriptions in the WSDL file.

Using a WSDL-to-Java tool, you can create an interface based on the existing WSDL file and implement this interface in your class. Such a class can then be used in the same way we've just seen.

Alternatively, the external WSDL file can be referred to from within the JAX @WebService annotation or on a Mule endpoint directly. References can be made to a WSDL file that is located on the classpath, somewhere on the file system, or to a resource somewhere in a web application.

@WebService(endpointInterface =
   "com.ricstonairways.StatusInterface",
   serviceName = "PNRStatus",
   wsdlLocation="./Status.WSDL")

In the preceding example, the location of the WSDL file is defined within the @WebService annotation inside the Java class. The next example shows how you can achieve the same effect by referring to the WSDL file from the inbound endpoint of your Mule configuration:

<cxf:inbound-endpoint
   address="http://10.0.0.1/status"
   wsdlLocation="./Status.WSDL"/>

This can be a valid reference to the file system, a file on the classpath, or a resource within your web application.

The CXF transport allows you to use a CXF-generated client as an outbound endpoint. This client needs to be generated using the WSDL-to-Java tool mentioned earlier. The foreign web service can be local (on the same machine) or remote, and can be built using any web technology. As long as a valid WSDL is available, the CXF outbound endpoint can be used.

These are the attributes to configure on the endpoint:

In the following example the CXF outbound endpoint has a valid address as before, which refers to the web service to invoke. The clientClass attribute refers to the class generated by the WSDL-to-Java tool for the WSDL file specified in the wsdlLocation attribute. The operation to invoke on this web service is the getTicket method.

<outbound>
   <outbound-pass-through-router>
      <cxf:outbound-endpoint address=
         "http://www.ricstonairways.com/buyTicket"
         clientClass="com.travelagent.buyTicket"
         wsdlLocation=""http://www.ricstonairways.com/
               wsdl/MA_BuyTicket.wsdl"
         operation="getTicket"/>
   </outbound-pass-through-router>
</outbound></service>

This list of attributes is not exhaustive but these are the most commonly used ones:

The Axis connector has the following child element:

Unlike other transports, Axis allows you to set up properties on the endpoints that are not configurable at a connector level.

Axis endpoints also have child elements that refer to the options for this web service call.

Here we have a simple Mule service that hosts the com.ricstonairways. environment.weatherService component. It has a single inbound web service endpoint that exposes the component as a web service on http://localhost:81/WeatherService.

<service name="WeatherService">
   <inbound>
      <inbound-endpoint address=
             "axis:http://localhost:81"/>
   </inbound>
   <component class="com.ricstonairways.environment.
                      weatherService"/>
</service>

Clients can then retrieve the WSDL for the web service or invoke any of the methods within this class by adding ?WSDL to the URL as a parameter, as shown here:

http://localhost:81/WeatherService?WSDL

The required parameters can also be encoded on the URL, for example to specify the method to invoke and the location for which weather data is required.

http://localhost:81/WeatherService?method=getWeather&town=London

Mule applications can invoke Axis web services by using a web service outbound endpoint as shown here:

<service name="WeatherService">
   <inbound>
      <inbound-endpoint address="vm://fromClient"/>
   </inbound>
   <bridge-component/>
   <outbound>
      <outbound-pass-through-router>
         <outbound-endpoint address=
               "axis:http://10.0.0.1:81/
                  weatherService?method=getWeather"/>
         </outbound-pass-through-router>
   </outbound>
</service>

Here, a bridge component is used to forward the message received on the VM fromClient queue to the web service. While the endpoint needs to have the method name included on it, the MuleMessage payload will be used as the parameter for the web service.

In this case the web service may exist locally, that is on the same computer, or on another machine. You will only need to change the IP address or computer name.

If you want to invoke a web service that is not an Axis web service, you will need to adjust the outbound endpoint to handle this. The Axis transport cannot automatically handle non-Axis web services, so most of the properties need to be configured manually. You can get the information about the foreign web service by looking at the WSDL for it

You then need to configure the following:

This example demonstrates how to invoke a non-Axis web service by using an outbound router collection with a single outbound router that will pass the Mule message to an Axis endpoint:

<outbound>
   <outbound-pass-through-router>
      <axis:outbound-endpoint address=
         "axis:http://10.0.0.1:82/weatherService?
         method=getWeather"
         soapAction="http://localhost:82/${method}">
            <axis:soap-method method="getWeather">
               <axis:soap-parameter
                  parameter="city"
                  type="string"
                  mode="IN"/>
               <axis:soap-return type="string"/>
         </axis:soap-method>
      </axis:outbound-endpoint>
   </outbound-pass-through-router>
</outbound>

Because the web service being invoked is not an Axis web service we need to configure the following items: