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.

Anypoint DataMapper is an exclusive feature of the Mule Enterprise runtime. However, MuleSoft welcomes users of the open-source Mule Community runtime to develop DataMapper-enabled applications, and to preview the data mapping capabilities.

To actually run DataMapper-enabled applications in a Mule production environment:

• download the trial version of Mule Studio with Enterprise runtime
  OR 
• obtain an Enterprise license from Mulesoft

 Contents

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

Skip to the code

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

1. In the Studio application menu, navigate to File > New > Mule Project.
2. In the Name field, type DataMapper Spell Checker or some other unique project name, then click Next.
3. 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.
4. Optional: Check the box to instruct Mule to Create POM file  for project and maintain with Maven. This action facilitates project management with Maven.
5. 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.
6. 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. 

1. Ajax endpoint
2. Anypoint DataMapper transformer
3. HTTP endpoint
4. Echo component

• Studio Visual Editor
• Studio XML Editor

 

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. 

• Studio Visual Editor
• Studio XML Editor

1. Click the Global Elements tab at the bottom of the canvas to open the Global Elements view (below). 
2. Click the Create button to open the Choose Global Type pane.
3. Click to expand the Connectors node, then select Ajax, and click OK. 
   
   
   
   

4. Configure the connector as per the table below.
   
   

   Field

   Value

   NameAjaxConnectorServer URLhttp://127.0.0.1:8090/AjaxResource Basesrc/main/app/docroot
5. Click OK to close the Global Elements Properties panel. The Global Elements view now lists an Ajax connector.
6. 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. 

• Studio Visual Editor
• Studio XML Editor

1. Double click the Ajax building block to open its Properties panel.

2. Configure the Ajax endpoint according to the table below, then click OK to save the configuration.
   
   

   FieldValueGeneral tabDisplay NameAjax ChannelChannel/services/echoReferences tabConnector ReferenceAjaxConnector

Although we created the Ajax Connector in the previous section so that it was already listed here, you can also create the Ajax Connector and edit it directly within the References tab on the Ajax endpoint by clicking the Add or Edit links to the right of the Connector Reference field (above, right). No matter where you create it, the Ajax Connector always displays when you open the Global Elements view.

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.

1. Double-click the DataMapper building block in your flow to open the New Data Mapping Flow wizard.
2. 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.
   
   
   
   
3. In the Input-Output screen, define the input that DataMapper should expect from the Ajax endpoint.
   
   1. In the Type field, use the drop-down to select Map <k,v> (below, left).
   2. Select User Defined.
   3. Click Edit Fields.
   4. In the Define the Map<kv> panel (below, right), enter a Name for the input map: HashMapToSpellCheckerXML
   5. Use the drop-down next to the Type field to select List<Element>
   6. Click the plus sign above the table to add a field. DataMapper adds a new field with a default value of field_0.
   7. Click the name, field_0, to customize it to read phrase, then hit enter to save.
   8. Click OK to close the Define the Map<k,v> panel.
      
      
      
      
4. In the Input-Output screen, define the output that DataMapper should prepare for the API.
   
   1. In the Type field, use the drop-down to select XML (below, top).
   2. Click the Generate schema from XML link below the XML Schema field.
   3. 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.  The sample.xml file is included as a resource in the standard Studio distribution.  For example, navigate to: 
      /Users/aaron/MuleStudio/examples/AjaxSpellChecker/TransformFile/sample.xml
   4. 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
      
      
      
      
   5. Click OK to save the schema location information.
   6. In the New Data Mapping Flow wizard, click Finish to save your input and output configurations.
5. 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.
   
   
   
   
6. 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). 
   
   
   
   
7. 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.

8. 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

9. The DataMapper is configured

HTTP endpoint

The HTTP endpoint sends XML requests to the Web Service and receives XML responses.

• Studio Visual Editor
• Studio XML Editor

1. Double click the HTTP building block to open its Properties panel.

2. Configure the HTTP endpoint according to the table below, then click OK to save the configuration.

   
   

   General TabFieldValueDisplay NameInvoke APIHostspellcheck-service.cloudhub.io/spellcheckPort80MethodPOSTHTTP Settings TabFieldValueContent Typetext/xml

 

 

If you intend to run this tutorial application from behind a corporate firewall . . .

... you need to create and configure an HTTP Connector to inter-operate with your company's proxy server.

 View Procedure

 

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.

• Studio Visual Editor
• Studio XML Editor

 

Complete Code

• Studio Visual Editor
• Studio XML Editor

 

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.

1. In the Package Explorer, click to expand folders to arrive at the app folder: src > main > app

2. Right-click the app folder, then select New > Folder.

3. In the New Folder panel, type docroot in the Folder name field, then click Finish.
4. Right-click the new docroot folder you just created, then select Import... > File System (under General), then click Next.
5. 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
6. 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. 
   
   
   
   
7. Verify that SpellChecker.html resides within the src/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.

1. Be sure to save your project by selecting File > Save on the Studio menu. 

2. 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'                         +

   ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3. Studio specified the following details when creating the project:
   
   1. 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.
   2. an HTML page named SpellChecker.html was created and placed in the docroot folder. The relative linksrc/main/app/docroot was specified as the resource base for the Jetty server in the Ajax connector.
   3. a combination of the two properties launches your application at http://127.0.0.1:8090/Ajax/SpellChecker.html.
4. 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). 
   
   
5. 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. 
   
   
   

6. 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.