Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Publishing a SOAP API

The CXF Component facilitates the publication of SOAP APIs within a Mule flow.

Mule leverages Apache’s open-source [CXF framework] to build APIs. You can create a CXF API in Studio by configuring a CXF component in your Mule flow to perform any of the following CXF operations related to publishing a SOAP API:

  • publish a simple service

  • publish a JAX-WS service

  • proxy a published service

Using Mule’s CXF Component, you can also [enable WS-security], specify databindings, and add interceptors to your CXF API. For more information about how Mule leverages the CXF framework, consult [CXF Module Configuration Reference].

Assumptions

This document describes the details of example within the context of Anypoint Studio. Mule ESB’s graphical user interface (GUI). Where appropriate, the XML configuration accompanies the Studio interface screenshots. This document assumes that you are familiar with Mule ESB and the [Anypoint Studio interface].

Basic Anatomy

Exposing a SOAP API through a Mule application always requires a minimum of three elements:

  1. an endpoint that receives request and sends responses

  2. a CXF Component that references and exposes the WSDL file

  3. a component (or more likely a combination of components) that performs the operations the API supports (retrieving data, updating data in a databae, etc.)

    SOAP-flow1

    Element Description

    Endpoint

    The endpoint receives request and sends responses, both containing XML SOAP envelopes. Typically, the endpoint is HTTP, HTTPS, JMS, or VM.

    CXF component

    A SOAP API needs to expose its contract through a WSDL file. Access the contents of this file by adding ?wsdl to the API’s URL when performing a request.

    Through CXF, Mule allows you to present this WSDL contract using one of two [methods]

    1. WSDL-first: start with a WSDL file that you created yourself, import it into your Mule project, then reference its location from the CXF component.

    2. Code-fist: start with an annotated Java class, then have JAX-WS compile a WSDL file based upon it.

    Regardless of which method you use, you can instruct the CXF component to verify the validity of incoming requests against the WSDL.

    The CXF component also allows you to select an operation type:

    1. Proxy Service: Allows you to deal with XML directly in your flow. As it implies less transformations, it’s more efficient in terms of response time. Use it when:

      • You want to edit the XML directly

      • Are using XSLT

      • You will use DataMapper to map fields

    2. JAX-WS: Converts the payload into a POJO. Attributes in the POJO are easier to access in your flow. Use it when:

      • You are more comfortable working with Java objects

      • You need to construct POJO or JSON outputs

      • You are using Community runtime and can’t employ DataMapper

      • Want to present the WSDL through a Code-first approach (the proxy service only uses WSDL-first)

        CXF-1

        CXF-2

        The third option, Simple Service, can be used if you are using a simple service pattern, but is not covered here.

    Processing Component

    With the other two components in place, your flow is ready to process requests and perform the business logic that makes up your API. Your API could potentially fit into a single Java class, but will more likely include the use of several elements, such as flow controls, transformers, HTTP calls to Web services, etc.

Building a WSDL-First Proxy Service API

This process assumes that you have already created the WSDL you intended to use for SOAP API. For the purpose of exploring this functionality, you can use a [sample WSDL file].

  1. Import a WSDL file into your project.

    1. Select File>Import

    2. Select General > File System.

    3. Select the WSDL file from your file system, then, in the Into Folder field select src/main/resources.

    4. Click Finish.

  2. Drag and drop an HTTP connector and a CXF component into a new flow on your canvas.

    SOAPflow1

  3. Configure the CXF component as per the image and table below.

    CXF-3

    Field Value

    Operation

    Proxy Service

    Port

    Specify the port to which you wish to bind the WSDL

    Payload

    Body

    The output of this component is byte array who’s content depends upon the value you set in the Payload field.

    • If you select envelope, then the message remains wrapped within the envelope in which it was originally received.

    • If you selected body, then the message contains only the body, without its envelope.

  4. Configure the CXF component’s Advanced settings as per the image and table below. (Read more about Advance Settings of the CXF Componenet).

    CXFflow2

    Field Value

    WSDL Location

    Filepath of the WSDL in your Mule project.

    Soap 1.1

    OR

    Soap 1.2

    [Version of SOAP] you wish to use.

  5. Drop Flow Reference after your CXF component. This reference will redirect the requests to another flow, where the actual business logic of your API will be carried out. Keep in mind that whatever happens in this second flow, the returned output must match the output declared by the WSDL.

    CXFflow3

    As stated earlier, rather than fitting into a single Java class, your API’s business logic may involve the use of several elements, such as flow controls, transformer, HTTP calls to Web services, etc. Where this is the case, you do not need to include a Java class; you can model, then configure your flow to perform the operations you SOAP API must support.

  6. Create a new flow and configure the Flow Reference component so that the Flow Name matches the name of this new flow. Then use other mule components to build you business logic flow.

  7. If you want direct access to the payload in you business logic flow, you must pass the message through an XML-to-DOM transformer

    soapflow4

    Otherwise, you can use XPath expressions to parse parts of the payload when needed. For example, suppose that you only want to alter the message when a condition is met, you can implement a choice router that evaluates the condition based on XPath expression.

  8. Run you Mule project. Access the API by sending requests to the HTTP endpoint. Include a SOAP envelope in the body.

    To make SOAP requests to send to your SOAP API, use a free service such as [SOAPUI] which automatically provides the SOAP message structure you need for each kind of request to the API.

    Alternatively, you can use a browser extension such as [Postman] (Google Chrome), or the [curl] command line utility to send SOAP requests. To use these, you must know the required structure of the requests.

  1. Import a WSDL file into your project:

    1. Select File > Import

    2. Select General > File System

    3. Select the WSDL File from your file system, then, in the Into Folder field select src/main/resources.

  2. Create an http:inbound-endpoint in a new flow.

    
           
                   
                
    1
    
    <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="Endpoint"/>
    Attribute Value

    exchange-pattern

    request-response

    host

    localhost

    port

    8081

  3. Add a cxf:proxy-service element after the HTTP endpoint.

    
           
                   
                
    1
    
    <cxf:proxy-service doc:name="SOAP" payload="body" port="myAPI" service="myAPI" wsdlLocation="myAPI.wsdl"/>
    Attribute Value

    wsdlLocation

    The filepath of your WSDL in the Mule project

    service

    myAPI

    port

    myAPI

    payload

    body

    The output of this component is a byte array who’s content depends upon the value you set for the payload attribute.

    • If you select envelope, then the message remains wrapped within the envelope in which it was originally received.

    • If you selected body, then the message contains only the body, without its envelope.

  4. Create a flow-ref after your CXF component. This reference will redirect the requests to another flow, where the actual business logic of your APPI is carried out. Keep in mind that whatever happens in this second flow the returned output must match the output declared by the WSDL.

    
           
                   
                
    1
    
    <flow-ref name="business-logic_flow" doc:name="Flow Reference"/>
    Attribute Value

    name

    business_logic_flow

    doc:name

    Flow Reference

    As stated earlier, rather than fitting into a single Java class, your API’s business logic may involve the use of several elements, such as flow controls, transformers, HTTP calls to Web services, etc. Through these elements, you can model, then configure your flow to perform the operations your SOAP API must support.

    
           
                   
                
    1
    2
    3
    
    <flow name="business-logic_flow" doc:name="business-logic_flow">
         <!-- your business logic here -->
    </flow>
  5. Create a new flow and name it with the value you assigned to the flow-ref attribute Flow Name. Then use other mule components to build your business logic inside flow.

  6. If you want direct access to the payload in your business-logic-flow, you must pass the message through a mulexml:xml-to-dom-transformer.

    
           
                   
                
    1
    
    <mulexml:xml-to-dom-transformer doc:name="XML to DOM"/>

    Otherwise, you can use XPath expressions to parse parts of the payload when needed. For example, suppose that you only want to alter the message when a condition is met, you can implement a choice router that evaluates the condition based on an XPath expression.

  7. Run your Mule project. Access the API by sending requests to the HTTP endpoint. Include a SOAP envelope in the body.

    To make SOAP requests to send to your SOAP API, use a free service such as [SoapUI] which automatically provides the SOAP message structure you need for each kind of request to the API.

    Alternatively, you can use browser extension such as [Postman] (Google Chrome), or the [curl] command line utility to send SOAP requests. To use these, you must know the required structure of the requests.

Complete WSDL-Frist Example

For this code to be executable, you must include, in your project:

  • a WSDL file

  • your unique business logic in the business logic flow


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?xml version="1.0" encoding="UTF-8"?>
 
<mule xmlns:mulexml="http://www.mulesoft.org/schema/mule/xml" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:cxf="http://www.mulesoft.org/schema/mule/cxf" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:spring="http://www.springframework.org/schema/beans" version="EE-3.5.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/cxf http://www.mulesoft.org/schema/mule/cxf/current/mule-cxf.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
http://www.mulesoft.org/schema/mule/xml http://www.mulesoft.org/schema/mule/xml/current/mule-xml.xsd">
 
    <flow name="SOAP_flow" doc:name="SOAP_flow">
        <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="Endpoint"/>
        <cxf:proxy-service doc:name="SOAP" payload="body" port="myAPI" service="myAPI" wsdlLocation="myAPI.wsdl"/>
        <mulexml:dom-to-xml-transformer doc:name="DOM to XML"/>
        <flow-ref name="business-logic_flow" doc:name="Flow Reference"/>
    </flow>
    <flow name="business-logic_flow" doc:name="business-logic_flow">
         <!-- your business logic here -->
    </flow>
</mule>

Advanced Example

Create a Mule Example Project in Studio and select the template Service Orchestration and Choice Routing.

Building a WSDL-First JAX-WS API

This process assumes that you have already created the WSDL you intend to use for your SOAP API. For the purpose of exploring this functionality, you can use a [sample WSDL file].

  1. Import a WSDL file into your project.

    1. Select File > Import.

    2. Select General > File System.

    3. Select the WSDL file from your file system, then, in the Into Folder field, select src/main/resources.

    4. Click Finish.

  2. Drag and drop an HTTP connector and a CXF component into a new flow on your canvas.

    SOAPflow1

  3. Configure the CXF component as per the image and table below. At runtime, the output of this component is a POJO.

    CXFex2

    Field Value

    Operation

    JAX-WS service

    Port

    myAPI

    Service

    myAPI

  4. Configure the CXF component’s Advanced settings as per the image and table below.

    OrderAPIadv

    Field Value

    WSDL Location

    Filepath of the WSDL in your Mule project.

    Soap 1.1

    OR

    Soap 1.2

    [Version of SOAP] you wish to use.

  5. Drop a Flow Reference after your CXF component. This reference will redirect the requests to another flow, where the actual business logic of your API will be carried out. Keep in mind that whatever happens in this second flow, the returned output must match the output declared by the WSDL.

    OrderAPIflow

    As stated earlier, rather than fitting into a single Java class, your API’s business logic may involve the use of several elements, such as flow controls, transformers, HTTP calls to Web services, etc. Where this is the case, you do not need to include a Java class; you can model, then configure your flow to perform the operations your SOAP API must support.

  6. Create a new flow and configure the Flow Reference component so that the Flow Name matches the name of this new flow. Then use other mule elements to build your business logic inside this flow.

  7. Run your Mule project. Access the API by sending requests to the HTTP endpoint. Include a SOAP envelope in the body.

    To make SOAP requests to send to your SOAP API, use a free service such as [SoapUI] which automatically provides the SOAP message structure you need for each kind of request to the API.

    Alternatively, you can use a browser extension such as [Postman] (Google Chrome), or the [curl] command line utility to send SOAP requests. To use these, you must know the required structure of the requests.

  1. Import a WSDL file into your project:

    1. Select File > Import.

    2. Select General > File System.

    3. Select the WSDL File from your file system, then, in the Into Folder field, select src/main/resources.

    4. Click Finish.

  2. Add an http:inbound-endpoint in a new flow.

    
           
                   
                
    1
    
    &lt;http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="Endpoint"/&gt;
    Attribute Value

    exchange-pattern

    request-response

    host

    localhost

    port

    8081

    doc:name

    Endpoint

  3. Add a cxf:jaxws-service element after the HTTP endpoint. At runtime, the output of this component is a POJO.

    
           
                   
                
    1
    
    &lt;cxf:jaxws-service doc:name="SOAP"  port="myService" service="myService" wsdlLocation="myAPI.wsdl"/&gt;
    Attribute Value

    wsdlLocation

    The filepath of your WSDL in the Mule project

    service

    myService

    port

    myService

    doc:name

    SOAP

  4. Create a flow-ref after your CXF component. This reference will redirect the requests to another flow, where the actual business logic of your API is carried out. Keep in mind that whatever happens in this second flow, the returned output must match the output declared by the WSDL.

    
           
                   
                
    1
    
    &lt;flow-ref name="business-logic_flow" doc:name="Flow Reference"/&gt;
    Attribute Value

    name

    business-logic_flow

    doc:name

    Flow Reference

    As stated earlier, rather than fitting into a single Java class, your API’s business logic may involve the use of several elements, such as flow controls, transformers, HTTP calls to Web services, etc. Through these elements, you can model, then configure your flow to perform the operations your SOAP API must support.

    
           
                   
                
    1
    2
    3
    
    &lt;flow name="business-logic_flow" doc:name="business-logic_flow"&gt;
             &lt;!-- your business logic here --&gt;
        &lt;/flow&gt;
  5. Create a new flow and name it with the value you assigned to the flow-ref attribute Flow Name. Then use other mule components to build your business logic inside this flow.

  6. Run your Mule project. Access the API by sending requests to the HTTP endpoint. Include a SOAP envelope in the body.

    To make SOAP requests to send to your SOAP API, use a free service such as [SoapUI] which automatically provides the SOAP message structure you need for each kind of request to the API.

    Alternatively, you can use a browser extension such as [Postman] (Google Chrome), or the [curl] command line utility to send SOAP requests. To use these, you must know the required structure of the requests.

Complete WSDL-First Example

For this code to be executable, you must include, in your project:

  • a WSDL file

  • your unique business logic in the business logic flow


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?xml version="1.0" encoding="UTF-8"?>
 
<mule xmlns:mulexml="http://www.mulesoft.org/schema/mule/xml" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:cxf="http://www.mulesoft.org/schema/mule/cxf" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:spring="http://www.springframework.org/schema/beans" version="EE-3.5.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/cxf http://www.mulesoft.org/schema/mule/cxf/current/mule-cxf.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
http://www.mulesoft.org/schema/mule/xml http://www.mulesoft.org/schema/mule/xml/current/mule-xml.xsd">
 
    <flow name="SOAP_flow" doc:name="SOAP_flow">
        <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="Endpoint"/>
        <cxf:jaxws-service doc:name="SOAP"  port="myService" service="myService" wsdlLocation="myAPI.wsdl"/>
        <flow-ref name="business-logic_flow" doc:name="Flow Reference"/>
    </flow>
    <flow name="business-logic_flow" doc:name="business-logic_flow">
         <!-- your business logic here -->
    </flow>
</mule>

Build a Code-First JAX-WS API

[tab,title="Studio Visual Editor"]
  1. Create the Java class that implements the API.

    1. In the Package Explorer, right click on the project name, then select New > Class.

    2. Enter the class name, then click Add. Then use the filter to display, then select the Interface Definition you wish to use.

    3. Click Finish to save your selection.

    4. In the new tab that appears in Studio, create the definition for your API in the Java class, adding annotations that follow the [JAX-WS] specification.

      If you already have a WSDL file for your API, you can import it, then automatically create a Java class based upon it.

      .. Select *File > Import*.
      .. Select *General > File System*.
      .. Select the WSDL File from your file system, then, in the *Into Folder* field, select `src/main/resources`.
      .. Click *Finish*.
  2. Build a flow with an HTTP connector and a CXF component.

    SOAPflow1+%281%29

  3. Configure the CXF component as per the image and table below. At runtime, the output of this component is a POJO.

    newCXForderapi

    Field Value

    Operation

    JAX-WS service

    Port

    myAPI

    Service

    myAPI

    Service Class

    Specify the Java class you created

    Instead of building a Java class, you can import an existing WSDL file into your project, then use CXF to automatically build a Java class based upon it.

    In the CXF component, click Generate from WSDL.

    newCXForderapi-genfromwsdl

    Then, select either the URL of the WSDL or the full filepath of the WSDL (including WSDL extension) within the project. After Mule generates the classes, ensure the Service Class field points to the actual Service Interface Definition, not the Implementation Class.

  4. Drop a Flow Reference after your CXF component. This reference will redirect the requests to another flow, where the actual business logic of your API will be carried out. Keep in mind that whatever happens in this second flow, the returned output must match the output declared by the WSDL.

    OrderAPIflow

    As stated earlier, rather than fitting into a single Java class, your API’s business logic may involve the use of several elements, such as flow controls, transformers, HTTP calls to Web services, etc. Where this is the case, you do not need to include a Java class; you can model, then configure your flow to perform the operations your SOAP API must support.

  5. Create a new flow and configure the Flow Reference component so that the Flow Name matches the name of this new flow. Then use other mule components to build your business logic inside this flow.

  6. Run your Mule project. Access the API by sending requests to the HTTP endpoint. Include a SOAP envelope in the body.

    To make SOAP requests to send to your SOAP API, use a free service such as [SoapUI] which automatically provides the SOAP message structure you need for each kind of request to the API.

    Alternatively, you can use a browser extension such as [Postman] (Google Chrome), or the [curl] command line utility to send SOAP requests. To use these, you must know the required structure of the requests.

Complete Code-First JAX-WS Example

For this code to be executable, you must include, in your project:

  • a Java class that constructs a WSDL

  • your unique business logic in the business logic flow


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?xml version="1.0" encoding="UTF-8"?>
 
<mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:cxf="http://www.mulesoft.org/schema/mule/cxf" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:spring="http://www.springframework.org/schema/beans" version="EE-3.5.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/cxf http://www.mulesoft.org/schema/mule/cxf/current/mule-cxf.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
 
    <flow name="SOAP_flow" doc:name="SOAP_flow">
        <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="Endpoint"/>
        <cxf:jaxws-service doc:name="SOAP"  port="myService" service="myService"  serviceClass="com.mulesoft.myService.myClass"/>
        <flow-ref name="business-logic_flow" doc:name="Flow Reference"/>
    </flow>
    <flow name="business-logic_flow" doc:name="business-logic_flow">
         <!-- your business logic here -->
    </flow>
</mule>

Advanced Examples

Download the following Studio project and then import it as a Mule Studio generated Deployable Archive (.zip):

Note that for the example to be deployable, you must add your own Kissmetrics API key in kissmetrics.properties and your own database reference and credentials in postgresql.properties. Without these, you can still examine the flow to get an idea of best practices.

For a different example, create a Mule Example Project in Studio and select the template Service Orchestration and Choice Routing.

Notice in these examples how the routing is being performed for different operations. Also notice how exceptions are being handled.

Adding Security (Enterprise)

To protect the SOAP API in your Mule flow, you can configure elements in the CXF component to apply WS-security. You can add [WS-Security] Configuration Elements (i.e. key-value pairs) to validate and/or authenticate information in the SOAP header of a message; you can also enable one or more of six Token Validators to ensure message security. The ability to add these security features is available only in the Enterprise version of Mule.

Consult the [Securing a SOAP API] document to configure the security elements of your API.

See Also

  • Consult the [CXF Component Reference].

  • Read this [blog post] about code-first SOAP implementation.

  • Read [another blog post] that explains the XML-only SOAP Web Service template.

  • Learn about the [JAX-WS] annotations you need to make your Java class into a WSDL.

  • Learn how to [proxy a SOAP API] with Mule.