Advanced Anypoint DataMapper Tutorial
The Basic Studio Tutorial demonstrated how to build a simple spell checker application. The Intermediate Studio Tutorial demonstrated how to use the Studio drag-and-drop interface to build a more sophisticated spell checker that leverages a Web-based spell-check service through a Jetty server.
This Advanced Tutorial revisits the Intermediate Tutorial, this time leveraging the Anypoint DataMapper Transformer to replace the pair of transformers in the Intermediate Tutorial's flow. Many of the steps covered will seem familiar, but these opportunities for iterative practice, often in just a slightly different context, will help you gain rapid mastery over both the Studio interface and the process for building Mule applications.
Tutorial Overview
The steps in the Advanced Tutorial enable you to complete the following tasks:
- create a flow that features an Ajax endpoint and an Ajax connector
- translate data from a web page into the Mule message processing flow
- convert a HashMap object into XML objects that the Spell Check API can understand
-
create a connection to the Spell Checker API so it can process Web page input
- return XML data to the originating web page via the Ajax transport channel
- implement a Jetty HTTP server within the flow
Creating a Studio Project
This advanced-level DataMapper Spell Checker flow contains four Mule building blocks and references a global connector.
This section repeats the Mule project creation procedure, which was first covered in slightly greater detail in the Basic Studio Tutorial
- In the Studio application menu, navigate to File > New > Mule Project.
- In the Name field, type
DataMapper Spell Checker
or some other unique project name, then click Next. - After the New Mule Flow panel appears, use the default value Mule uses to name your flow, or customize it according to your preference. Click Next.
- Optional: Check the box to instruct Mule to Create POM file for project and maintain with Maven. This action facilitates project management with Maven.
- Optional: Customize any of the Java Project-specific details according to your preferences. No changes are required for this project; the default values are perfectly acceptable.
- Click Finish to create your new project.
Building a Flow
Drag the following components onto the Message Flow canvas, sequencing them as illustrated in the diagram below.
- Ajax endpoint
- Anypoint DataMapper transformer
- HTTP endpoint
- Echo component
Configuring a Global Connector
This procedure creates an Ajax connector in the Global Elements view. The Ajax endpoint and global connector work together to implement a Jetty HTTP server with an Ajax transport channel.
- Click the Global Elements tab at the bottom of the canvas to open the Global Elements view (below).
- Click the Create button to open the Choose Global Type pane.
- Click to expand the Connectors node, then select Ajax, and click OK.
-
Configure the connector as per the table below.
FieldValueName AjaxConnector
Server URL http://127.0.0.1:8090/Ajax
Resource Base src/main/app/docroot
- Click OK to close the Global Elements Properties panel. The Global Elements view now lists an Ajax connector.
- Click the Message Flow tab at the bottom of the canvas to return to your flow.
Configuring the Building Blocks
Ajax endpoint
The Ajax endpoint serves as the Message Source (i.e., inbound endpoint) for the flow.
- Double click the Ajax building block to open its Properties panel.
-
Configure the Ajax endpoint according to the table below, then click OK to save the configuration.
Field Value General tab Display Name Ajax Channel
Channel /services/echo
References tab Connector Reference AjaxConnector
Anypoint DataMapper
Use the DataMapper wizard to configure the DataMapper building block so the latter will translate into XML code the incoming HashMap objects returned from the Ajax Inbound Endpoint. As DataMapper is a visual mapping tool, the instructions below refer only to Studio Visual Editor.
- Double-click the DataMapper building block in your flow to open the New Data Mapping Flow wizard.
- Enter a unique Name for the DataMapper building block in your flow. Notice that Studio automatically uses the name value to create the filename of the graph file (
.grf
) that stores all the mapping details. Click Next.
- In the Input-Output screen, define the input that DataMapper should expect from the Ajax endpoint.
- In the Type field, use the drop-down to select
Map <k,v>
(below, left). - Select User Defined.
- Click Edit Fields.
- In the Define the Map<kv> panel (below, right), enter a Name for the input map:
HashMapToSpellCheckerXML
- Use the drop-down next to the Type field to select
List<Element>
- Click the plus sign above the table to add a field. DataMapper adds a new field with a default value of
field_0
. - Click the name,
field_0
, to customize it to readphrase
, then hit enter to save. - Click OK to close the Define the Map<k,v> panel.
- In the Type field, use the drop-down to select
- In the Input-Output screen, define the output that DataMapper should prepare for the API.
- In the Type field, use the drop-down to select
XML
(below, top). - Click the Generate schema from XML link below the XML Schema field.
- In the XML file and Schema directory field, use the ellipsis buttons to navigate to, then select the
sample.xml
file on your local drive (below, bottom). DataMapper uses the content of this file as the model for defining the output fields. Thesample.xml
file is included as a resource in the standard Studio distribution. For example, navigate to:
/Users/aaron/MuleStudio/examples/AjaxSpellChecker/TransformFile/sample.xml
- In the Schema directory field, use the ellipsis buttons to navigate to the TransformFile folder in which your sample.xml folder resides. For example, navigate to:
/Users/aaron/MuleStudio/examples/AjaxSpellChecker/TransformFile
- Click OK to save the schema location information.
- In the New Data Mapping Flow wizard, click Finish to save your input and output configurations.
- In the Type field, use the drop-down to select
- DataMapper produces input and output fields in the Data Mapping console beneath the canvas (see below). Note that, at present, the input field is not mapped to any output field.
- Click the phrase : string field, then drag-and-drop it on top of the text : string field. This associates the two fields, which is indicated by a solid line between them (below).
- The fields in the Output section define the parameters for the Spell Check query. The fields appear in bold type, which indicates that they need to be mapped for the parameters to be set. To map pairs of fields, click a field name in the Outputsection.
-
In the input box that appears below the output fields (highlighted in yellow, below), type the value you want to assign to the field in the input box according to the able below, then click the next field to commit the value.
Field
Value
textalreadyclipped
0
ignoredups
0
ignoredigits
1
ignoreallcaps
1
- The DataMapper is configured
HTTP endpoint
The HTTP endpoint sends XML requests to the Web Service and receives XML responses.
- Double click the HTTP building block to open its Properties panel.
-
Configure the HTTP endpoint according to the table below, then click OK to save the configuration.
General Tab Field Value Display Name Invoke API
Host spellcheck-service.cloudhub.io/spellcheck
Port 80
Method POST
HTTP Settings Tab Field Value Content Type text/xml
Echo component
The Echo component, which sends the HTTP response to the Mule console, requires no specific configuration settings, but you can enter an optional display name.
Complete Code
Importing an HTML Page
This application task requires an HTML page that includes JavaScript code and a call to a Mule class, thus allowing communication with the flow.
-
In the Package Explorer, click to expand folders to arrive at the
app
folder:src
>main
>app
-
Right-click the
app
folder, then select New > Folder. - In the New Folder panel, type
docroot
in the Folder name field, then click Finish. - Right-click the new
docroot
folder you just created, then select Import... > File System (under General), then click Next. - Click Browse to the right of the From directory field, then navigate to the HTMLfile folder on your local instance of Studio, then click Next. For example, navigate to:
/Users/aaron/MuleStudio/examples/AjaxSpellChecker/HTMLfile
- In the left pane of the Import panel, click the check box to the left of
HTMLfile
; in the right pane, click the check box to the left ofSpellChecker.html
, then click Finish.
- Verify that
SpellChecker.html
resides within thesrc/main/app/docroot
node in the Package Explorer view).
Running the Project
Run the project from within Mule Studio to see your project in action.
- Be sure to save your project by selecting File > Save on the Studio menu.
-
To run the project, right click
datamapper_enabled.mflow
in the Package Explorer, then select Run As > Mule Application. Studio deploys the application on the embedded runtime and displays the message below when the application is running.++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Started app datamapper_spell_checker' +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- Studio specified the following details when creating the project:
http://127.0.0.1:8090/Ajax
was entered in the Ajax connector properties as the Server URL. This created a Jetty HTTP server on your local machine, which is accessible via the specified URL.- an HTML page named
SpellChecker.html
was created and placed in thedocroot
folder. The relative linksrc/main/app/docroot
was specified as the resource base for the Jetty server in the Ajax connector. - a combination of the two properties launches your application at
http://127.0.0.1:8090/Ajax/SpellChecker.html
.
- Open a web browser and navigate to
http://127.0.0.1:8090/Ajax/SpellChecker.html
. A web page appears with an empty form field (see below).
- Type heeello, to elicit a response from your Mule application (see below). Notice that as you type, the Responsedata updates for each character you enter. The Web service returns a series of spelling suggestions.
-
The Echo building block makes it possible for you to monitor the Studio Consoleview for output as you type. The Console should display something similar to the following:
Stopping the Application
To stop the Mule application from running, click the red Terminate icon in the Console.