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

Travel Agent Example

Enterprise Edition

This example application demonstrates Mule ESB’s ability to integrate Web services.

The Travel Agent SOAP Web service processes requests for both flight and hotel reservations. End users enter travel information into a Web browser form, then Mule accesses a database and RESTful Web services to determine flight and hotel room availability. Lastly, Mule charges a credit card to confirm all travel bookings.

In particular, this Web service performs four important actions:

  • it preserves original message payloads

  • it routes messages for processing according to variables Mule sets on messages

  • it handles errors with customized exception strategies

  • it tolerates faults and initiates compensatory actions, such as canceling charges and reservations if an error occurs)

This document will help you understand some of the ways you can integrate Web services in Mule ESB applications. To understand more about Mule ESB’s ability to integrate services and systems, access the Mule examples and see other applications in action.

Assumptions

The MuleSoft team built this Travel Agent example in Mule Studio, Mule ESB’s graphical user interface (GUI). This document describes the details of the example within the context of Mule Studio. Where appropriate, the XML configuration follows the Studio interface screenshot in an expandable section.

This document assumes that you are familiar with Mule ESB and the Mule Studio interface. To increase your familiarity with Mule Studio, consider completing one or more Mule Studio Tutorials.

Set Up

As with this Travel Agent example, you can create template applications straight out of the box in Mule Studio. You can tweak the configurations of these use case-based templates to create your own customized applications in Mule.

Follow the procedure below to create, then run the Travel Agent example application in Mule ESB.

  1. Complete the procedure in Examples and Exercises to create, then run, the Travel Agent template in Mule Studio.

  2. Open your Web browser.

  3. Type http://localhost:8787/populate in the address bar of your browser, then press enter to activate the Travel Agent application and elicit a response in your browser that reads db populated. (Refer to the DatabaseInitialisation Flow section below to learn why Mule populates this database.)

  4. Type http://localhost:8090/travelAgent/ into the address bar of your browser, then press enter to access the Travel Agent Web browser form (see image below).

    launch_page

How it Works

The Travel Agent Web Service example application consists of several flows which collaborate to process end user requests. Together, the flows in this application expose a SOAP Web service which accepts end user requests to reserve flights and book hotel rooms.

For the purposes of this example, the Travel Agent Web Service application establishes three conditions with its end users:

  1. The application need not consult the end user after reserving travel arrangements and before booking them. (i.e. The end user has blind confidence in the Travel Agent Web Service to reserve, and pay for, a return flight and hotel room for the duration of the stay.)

  2. The application stores the details of several end user credit cards in a database; it uses these credit cards to process payments.

  3. The end user expects to pay a commission for the service the application provides.

An end user — a travel agent — accesses the application through the Travel Agent’s website at http://localhost:8090/travelAgent/. The agent then enters travel information in the Form tab of the Web application’s GUI (see image below).

form

The agent clicks Submit to call the Mule ESB Travel Agent application. The application receives and processes the request, then responds with a confirmation. The browser displays the response details in the Web application’s Confirmation tab (see image below).

confirmation

This Web application’s GUI also includes a SOAP tab which developers can use to examine the contents of the Web service requests and responses.

Whenever a user submits information via the Form tab in the GUI, the Web application sends a JSON-formatted request to the Travel Agent Web service. The Mule ESB application (i.e. the server-side application) receives the request, converts the JSON to XML, then processes the message. Lastly, it converts the message from XML back into JSON to return a response to the GUI’s Confirmation tab.

Web services which must accept requests from various clients in different formats. A GUI-based Web service client, like the Travel Agent, may send requests in JSON; another Web service client — for example, a SOAP-based user interface (SOAP-UI) may send requests in XML.

The SOAP tab, therefore, exists only to illustrate the XML format of requests and responses as though the end user is interacting with the application via SOAP-UI. Thus, if you click Submit on the SOAP tab to send the pre-populated sample request in XML, Mule ESB returns a SOAP response in XML. The Travel Agent application accepts both JSON and XML requests (see image below).

soap

The Mule ESB Travel Agent application contains multiple flows and subflows which cooperate to expose a SOAP Web service. The sections below offer flow-by-flow details of the Travel Agent Web service’s actions as it processes end user requests.

For Mule Studio Users

In Mule Studio, double-click a building blocks in the canvas to open its Properties Panel , then examine its configuration details. Alternatively, click the Configuration XML tab to examine the application’s XML configuration file.

config_tab

TravelAgentRequest Flow

This flow accepts messages from the Javascript form on the end user’s browser, calls the Web service to reserve and confirm flights and hotel rooms, and then responds to the end user.

travAgReq

Endpoints and Transformers

The end user’s Web browser submits a request in JSON format; the AJAX Endpoint receives the message, then passes it to the next message processor in the flow.

The TravelAgentRequest flow must, eventually, pass the message to the ConfirmReservations Flow flow via the request-response HTTP Endpoint. Because the Reservations flow only accepts XML messages, the TravelAgentRequest flow must first transform the data format of the message payload from JSON to XML. To perform the transformation, this flow uses an  Anypoint DataMapper.

This flow next employs an XSLT Transformer to wrap the message in a SOAP envelope. Then, it uses the HTTP endpoint to push the message to the Reservations flow for processing.

The Reservations flow completes its processing tasks, then passes the message back to the TravelAgentRequest flow in SOAP XML format. The TravelAgentRequest flow unwraps the envelope, passes the message through another DataMapper to transform the payload from XML back to JSON, and displays it to the end user.

RequestProxy Flow

The RequestProxy flow accepts XML requests that the end user submits via the SOAP tab on the GUI.

+ requestProxy

The Ajax inbound endpoint receives the SOAP request, then the HTTP endpoint passes the message to the Reservations flow for processing. When the HTTP endpoint receives a response from the Reservations flow, it passes the message to the Object to String transformer, which converts the payload from a Java object to a string. This transformation enables the end user’s browser to display the response.

Why the Proxy?

If a message’s payload is already in SOAP XML, then why must the RequestProxy flow exist at all? Why cannot the Reservations flow simply receive these messages directly?

The RequestProxy exists for two reasons:

  1. cross-site scripting security checks restrict direct, open communication between Web service callers and providers

  2. the HTTP inbound endpoint in the Reservations flow does not “listen” on the Ajax server’s port

This flow, therefore, receives external calls in XML and transfers them internally, within the Mule application.

Reservations flow

This flow orchestrates calls to other Web services and prepares a response for the end user.

+ resrevations_flow

Endpoint and SOAP Component

The message source — an HTTP inbound endpoint — receives, then directs messages to a SOAP Component configured as a JAX-WS service. Mule unmarshalls the SOAP envelope into JAXB-annotated Java objects; Mule references these objects as parameters. From this point in the Reservations flow and beyond, the data format of message payloads is Java. (Note that Mule does not change the content of a message’s payload, only its format.)

Flow References and Message Enricher

This flow invokes several subflows in the Travel Agent application to book reservations and charge a commission.

Using a Flow Reference Component, the Reservations flow invokes its first subflow to reserve seats on flights. The Reserve flight component sends the message to the ReserveFlight subflow to process, then enriches the message payload with the processing result.

Throughout this flow, Mule uses Message Enrichers to enrich message payloads with data (i.e. add to the payload), rather than changing payload contents. Mule enriches a message’s payload so that other message processors in the application can access the original payload.

The Reservations flow uses a second flow reference component to invoke the GetBestHotelRoom subflow. This subflow identifies the least expensive hotel room available for the traveller’s stay. Then Mule, once again, enriches the message payload with the result of the subflow’s processing.

Filter and Flow Reference

Next, the Reservations flow passes the message through a Message Filter to confirm that the preceding subflow identified a room. The message filter examines the message payload to determine whether Mule should process the message further.

  • If the message payload contains a variable which identifies a hotel room, the filter passes the message to the next message processor.

  • If the message payload reads NOT FOUND, the filter uses a Global Script Component to handle the message. The exceptionThrower script component sends a response to the end user that reads, Sorry, we could not process your request.

What is a Global Script Component?

Mule ESB uses Global Elements, like the exceptionThrower in the Travel Agent example, to specify transport details and set reusable configurations.

Rather than repeatedly write the same code to apply the same configuration to multiple message processors, you can create one global element that details your configurations or transport details. Then, you can instruct any number of message processors in your Mule application to reference that global element.

Learn more…​

In this example, the code for the exceptionThrower script does not exist within the Reservations flow; rather, the code resides in a global element at the top of the application’s XML configuration file (and in the Global Elements tab in Mule Studio — see image below). The Filter on suitable room found filter uses the global exceptionThrower component to handle messages it cannot accept.

global_script_2

Using another flow reference component, the Reservations flow invokes a third subflow to determine the commission rate. The Get commission rate component sends the message to the GetCommissionRate subflow to process, then enriches the message payload with the processing result.

Transformers and Endpoint

Next, the Session Variable Transformer adds the flight and hotel costs, then appends the total travel cost to the message as a session variable.

Then, the VM Endpoint invokes the ConfirmReservations Flow flow to confirm all reservations and process the charges on a credit card.

The last element in the flow, the Create TravelResponse Expression Transformer, prepares a response to return to the SOAP component. Mule uses expressions to define the contents of the response (see image below); in this case, the expressions defines two:

  • confirmation number

  • total travel cost

    create_response

Finally, the response moves from the Create TravelResponse transformer through the SOAP component and HTTP endpoint to the TravelAgentRequest flow. The TravelAgentRequest flow sends the response to the end user.

Reservation Subflows

The main Reservations flow invokes several flows and subflows to perform specific tasks, or acquire data to enrich, or set as, the message payload. Mule uses flows and subflows to separate synchronous or asynchronous operations in an application. Mule also supports flow-specific exception strategies which apply error handling instructions.

To invoke flows and subflows, the Reservations flow uses Flow Reference Components. In fact, one of the subflows the Reservations flow invokes itself uses a flow reference component to invoke yet another subflow. The subsections below discuss the activities of the ReserveFlight, GetAvailableRooms, GetBestHotelRoom, and GetCommissionRate subflows.

ReserveFlight Subflow

This subflow calls a Web service to reserve seats on flights.

reserveFlight

Mule first uses an expression transformer to extract the following information from the Mule message payload:

  • flight departure date

  • flight return date

  • point of origin

  • destination

  • travel agent identifier

The transformer includes the above-listed information in a request it creates for the airlines’ Web service. The SOAP component in this flow — a JAX-WS client — sends the request to the Web service through the request-response HTTP endpoint.

The airlines’ Web service completes the reservation, then returns a response. The Reservations flow enriches the Mule message payload with the Web service’s response (seat reservations).

GetAvailableRooms Subflow

This subflow calls a Web service to acquire a list of hotel rooms available for the traveller.

get_available

Like the ReserveFlight subflow, this flow uses three building blocks to prepare and send a request to a SOAP Web service — this time, a hotels’ Web service.

The transformer uses expressions to extract the following data from the Mule message payload:

  • start date of stay

  • number of nights (i.e. stay duration)

  • travel agent identifier

  • city

The transformer includes the above-listed information in a request it creates for the hotels’ Web service. The SOAP component sends the request through the request-response HTTP endpoint to the Web service.

The hotels’ Web service completes the reservation, then returns a response. The GetBestHotelRoom flow enriches the Mule message payload with the Web service’s response (a list of available rooms).

Notice that, unlike the Reservations flow, both the ReserveFlight and GetAvailableRooms subflows act as clients of RESTful Web services; in other words, they consume Web services from other providers.

GetBestHotelRoom Subflow

This subflow determines which room, in the list of available hotel rooms, costs the least.

getBest_flow

First, this subflow uses a flow reference component to invoke the GetAvailableRooms subflow; then, it enriches the Mule message payload with the list of available hotel rooms.

Mule then subjects the message to a Variable Transformer which collaborates with a Foreach iterative processor to identify the least expensive room on the list.

The variable transformer consults the Double to set a variable on the message that represents the lowest price of an available hotel room; this is “the price to beat”. Foreach then processes each item in the collection — that is to say, each room in the list of available rooms — to determine if any of those rooms can “beat the lowest price”.

  1. First, foreach uses a filter to compare an item’s room type to the room preference in the message payload (i.e. double room, single room, etc.); an item that matches the room preference passes through the filter to the next message processor.. Foreach discards items which do not match the room preference.

  2. Next, foreach uses a filter to compare the item’s price to the variable the Initialize minPrice transformer set on the message; an item with a price lower than the minPrice variable passes through the filter to the next message processor. Foreach discards items with prices that cannot “beat the minimum price”.

  3. When an item in the collection passes through both filters, it qualifies as the new “price to beat”. The Update minPrice variable transformer sets a new value — room price of the item — on the minPrice variable; foreach passes the item to the next message processor.

  4. Foreach uses a second variable transformer, Update lowestPriceRoom, to set another variable on the message’s payload. The second variable records all of the details of the item (hotel name, room price, room type, etc.).

  5. Foreach iteratively repeats the process with each item in the collection to identify the least expensive, suitable room available.

Finally, the transformer at the end of this subflow uses expressions (see below) to provide the best hotel room’s data to the Reservations flow. In some cases, the result of foreach’s processing is null — perhaps there were no rooms available at all, or none of the available rooms matched the end user’s room. In such cases, the lowestPriceRoom transformer provides a NOT FOUND result to the Reservations flow.


           
        
1
#[if (flowVars['lowestPriceRoom'] != null) { flowVars['lowestPriceRoom'] } else { 'NOT FOUND' }]

The following example illustrates the activity in this subflow.

Imagine the GetAvailableRooms subflow supplies the GetBestHotelRoom subflow with a collection that contains three items:

  • a single room for $100

  • a double room for $200

  • a double room for $220

The Initialize minPrice variable consults the double to set a variable on the message equivalent to double.MAX_VALUE. Then, foreach iteratively processes each item through the message processors within its scope.

  • The first item does not match the room preference in the message payload (a double room), so it does not pass through the first filter and foreach discards it.

  • The second item matches the room preference and passes through the first filter. The item’s room price is lower than the minPrice variable (double.MAX_VALUE) so it passes through the filter to become the new “one to beat”. The two variable transformers set a new minPrice variable of $200, and a new lowestPriceRoom variable on the message, respectively.

  • The third item matches the room preference and passes through the first filter. The item’s room price is higher than the minPrice variable ($200) so it does not pass through the second filter and foreach discards it.

Foreach passes the result of its iterative effort — the second room item in the collection — to the lowestPriceRoom transformer. The transformer identifies the ‘lowestPriceRoom’, then hands that result to the Reservations flow.

Enrich or Set as Variable?

In the Reservations flow, Mule uses Message Enrichers to add information to message payloads. Mule enriches message payloads, rather than _changing the contents, so that other message processors in the application can access the original payload.

In the GetBestHotelRoom subflow, Mule uses a Variable Transformer to store information as a property in the session scope of the message payload, rather than enriching its content.

Which should you use?

If other message processors in your application must be able to access the original message payload, use an enricher; if not, set a variable.

GetCommissionRate Subflow

This subflow determines the commission rate to charge for the service.

getCommissionRate

The subflow uses two building to determine the commission to charge for the Travel Agent service:

  1. a request-response HTTP endpoint to call the CommissionService Web service

  2. a Cache scope which saves the results of Web service calls for reuse. The first time it receives a request, the cache scope takes the time to send call the RESTful Web service, then stores the response. The second time it receives a request, the cache scope examines the request to determine the number of days between the current date and the travel date:

    • if less than 30 days, the cache scope sends the request to the Web service

    • if 30 days or more, the cache scope examines its stored responses to determine if has one that it can use to calculate the new request;

      • if yes, it sends its calculated response to the Object to String transformer

      • if no, it sends the request to the Web service

Cache passes the response — calculated from a stored value, or freshly returned from the Web service — to the Object to String transformer, which converts the payload from a Java object to a string. This transformation provides the Calculate Price session variable with data in a format it can use to perform a calculation.

ConfirmReservations Flow

This flow confirms flight and hotel reservations with credit card payments.

confirm_res

Endpoint and Flow Reference

This flow receives a message through a request-response VM Endpoint, then uses a flow reference component to invoke a subflow to authorize credit card payments. Once authorized to make payments, Mule passes the message to a set variable transformer. This transformer, Set Rollback = CREDIT_CARD, and the Set Rollback = FLIGHT transformer (further in the flow) collaborate with a Choice Exception Strategy to handle errors.

Transformers and Exception Strategy

The variable transformers in this flow each set a variable on the message. The variable value helps the choice exception strategy determine which transaction(s) Mule must cancel when an error occurs.

The choice exception strategy catches an exception in the ConfirmReservations flow, then consults the variable on the message to decide where to route it. (Refer to image and code snippet below.)

  • If the variable contains a CREDIT_CARD value, the choice exception strategy directs the message through the first  Catch Exception Strategy which:

    • invokes the CancelPayment subflow to cancel the credit card transaction

    • invokes the ThrowException flow

  • If the variable contains a `FLIGHT`value, the choice exception strategy directs the message through the second catch exception strategy which:

    • invoke the CancelFlight subflow to cancel the flight confirmation

    • invoke the CancelPayment subflow to cancel the credit card transaction

    • invoke the ThrowException flow

choice_exception

For example, when the ConfirmHotelRoom subflow fails to confirm the reserved hotel room (perhaps the room’s availability changed at the last second), the message throws an exception, and the choice exception strategy catches it. The exception strategy consults the variable the message. It determines that because Mule has set a FLIGHT variable on the message, it must direct the message to the second catch exception strategy to cancel both transactions.

The ConfirmReservations flow is one of only two flows in the application which employ a customized exception strategy. All but one of the other flows and subflows use Mule’s implicitly-applied default exception strategy.

There’s No Rolling Back

In flows that conduct transactions, you would use a Rollback Exception Strategy to handle errors (i.e. rollback transactions).

However, because an HTTP-based Web service operates at the transport level, you cannot use it to conduct transactions. Within HTTP-based Web services, such as this Travel Agent example, you must instruct the application to initiate cancellations for completed tasks.

ThrowException Flow

This flow sends an error message to the end user.

Both catch exception strategies in the ConfirmReservations flow invoke this ThrowException flow. Containing only a Groovy Script Component, this flow follows a script to throw a RuntimeException and return a message that reads Unable to confirm reservations.

CommissionService Flow

The Reservations flow sends requests to this “in app” RESTful Web service to acquire a commission rate.

commission_service

The /commission Web service passes requests through a request-response HTTP endpoint to a Choice Flow Control. The flow control routes requests to one of two Set Payload Transformers to set a commission rate on the message.

  • If there are fewer than 30 days between the current date and travel date, the choice flow control routes the message to the Set Rate 0.2 message processor. This transformer sets the payload for the commission rate at 0.2.

  • if otherwise (i.e. there are more than 30 days between the current date and travel date), the choice flow control routes the message to the Set Rate 0.1 message processor. This transformer sets the payload for the commission rate at 0.1.

After setting the commission rate, the /commission Web service returns the response to the Reservations flow.

DatabaseInitialisation Flow

When you, as an end user, first started this Travel Agent application, you activated this DatabaseInitialisation flow. This flow creates and populates a table in a local, file-based database.

databaseInitialisation

First, the request-response HTTP endpoint receives end user requests. Next, Mule follows the script in a Groovy component to create a table in a database, then populate it with credit card data (see script below). The HTPP endpoint responds to the end user with a message that reads, db populated. The JDBC endpoint in the AuthorisePayment subflow can now fetch the credit card data in this table.

You need not create this flow in your customized application to publish a Web service; it exists in this example so you can examine a functional Web service.

The DatabaseInitialisation flow is one of only two in the application which uses a customized exception strategy to handle errors. All others, save one, use Mule’s implicitly-applied default exception strategy. If the Groovy component throws an error ---say, because you accidentally sent a request to this flow twice — the catch exception strategy handles the error. It sends a message to the end user that reads table is already populated.

Confirmation Subflows

Invoked upon demand by the ConfirmReservations flow, the following subflows either consume external Web services to complete transactions, or they cancel transactions.

ConfirmFlight Subflow

This subflow sends a request to a Web service to confirm flight reservations.

confirmFlight

The ConfirmFlight subflow uses three building blocks to prepare, then send a request to the airlines’ SOAP Web service.

The Create FlightConfirmationRequest transformer uses expressions to extract the following data from the Mule message payload:

  • flight reservation number from the session variable set by the Enrich with flightReservationResponse enricher in the Reservations flow (see image below, left)

  • credit card authorization number from the variable set by the Enrich with paymentResponse enricher in the ConfirmReservations flow (see image below, right)
    extract_variables

The transformer includes the above-listed information in a request it creates for the airlines’ Web service. The SOAP component in this flow — a JAX-WS client — sends the request to the Web service through the request-response HTTP endpoint.

The airlines’ Web service processes the request, then returns a confirmation response. The ConfirmReservations flow enriches the Mule message payload with the Web service’s response.

ConfirmHotelRoom Subflow

This subflow sends a request to a Web service to confirm hotel reservations.

confirmHotelRoom

Rather than use an expression transformer like the ConfirmFlight subflow, this subflow uses an Anypoint DataMapper transformer to prepare a request for the hotels’ SOAP Web service.

The TravelRequest to ConfirmationRequest transformer maps data from the Mule message payload to the payload of a request it is creating for the Web service. Refer to the table below to examine the data it maps.

Data Extracted From Set on Web service Request

nights : integer

session variable set by the Enrich with suitableRoom enricher in the Reservations flow

numberOfNights : integer

roomID : string

session variable set by the Enrich with suitableRoom enricher in the Reservations flow

roomID : string

beginDate : date

session variable set by the Enrich with suitableRoom enricher in the Reservations flow

startDate : date

Notice that Mule extracts all the data it needs from the same session variable. Rather than use three expressions in an expressions transformer to extract three pieces of information from the same variable, Mule uses a DataMapper to extract three pieces of information from one input argument. In such cases, Anypoint DataMapper is a more efficient transformer.

In Mule Studio, click the DataMapper transformer in the canvas to select it. Then, click the Data Mapping tab in Mule Studio’s console to see a graphical representation of the data it maps (see below).

mapped_data

The SOAP component in this flow sends the request to the Web service through the request-response HTTP endpoint. The hotels’ Web service processes the request, then returns a confirmation response. The ConfirmReservations flow enriches the Mule message payload with the Web service’s confirmation response.

AuthorisePayment Subflow

This subflow sends a request to a Web service to pay for the trip with a credit card.

authorisePayment

Mule uses a credit card to pay for the total cost of the hotel room and flight bookings. This subflow uses a JDBC Endpoint to retrieve credit card information from a database. Mule uses an SQL query (see image and code snippet below) to determine which credit card to use, and which data to retrieve.

SQL_query


           
        
1
<jdbc-ee:query key="findCreditCard" value="select cc_number, expiration_date, security_code from credit_cards where user_id = #[payload.userId]"/>

The enricher adds a creditCard variable to the Mule message payload that includes the following data:

  • the credit card number

  • the expiration date

  • the credit card security code

The Create PaymentRequest transformer uses expressions to extract the following data from the Mule message payload:

  • the total cost for the hotel room and flight from the price session variable set by the Calculate Price transformer in the Reservations flow

  • the credit card number, expiration date and security code from the creditCard variable set by the Enrich with creditCard enricher in the AuthorisePayment subflow

The transformer includes the above-listed information in a request it creates for the CreditCardService Web service. The SOAP component in this flow sends the request to the Web service through the request-response HTTP endpoint.

The credit cards’ Web service processes the payment, then returns a confirmation response. Mule enriches the message payload with the Web service’s response.

CancelFlight and CancelPayment Subflows

These subflows send requests to Web services to cancel the confirmed flights and the credit card payment.

cancelFlight

cancelPayment

Both subflows use three building blocks to prepare, then send a cancellation request to the airlines’, or the credit cards’, SOAP Web service.

Each employs:

  1. an expression transformer to extract data from the Mule message payload and prepare a request for the Web service

  2. a SOAP component and a request-response HTTP endpoint to send, then receive cancellation requests

The Web services process the requests, then return confirmation responses. The subflows notify the catch exception strategies that they have completed the cancellation activities.

Drill Down

The following subsection offers detailed information about the client-side user interface.

About the Client-side User Interface

Clients of this Travel Agent example consume the Web service via a jQuery user interface client on a Web browser. The interface submits data as either a JSON request, or a raw SOAP envelope.

To examine the code of the client-side interface, access the index.html file in the src/main/app/docroot folder in Mule.

How Do I Access the Index File?

  1. In the Package Explorer, click to expand the src folder.

  2. Click to expand folders to navigate to main > app > docroot.

  3. Double-click the index.html file to open the file in a new canvas pane in Studio.