Intermediate Studio Tutorial

Intermediate Studio Tutorial

The Basic Studio Tutorial demonstrated how to build a simple spell checker application.

This intermediate tutorial demonstrates how to use the Studio drag-and-drop interface to build a more sophisticated Ajax spell checker application that incorporates the following:

1. the Spell Checker Web service
2. an HTML page
3. a sequence of pre-packaged Mule building blocks.

This tutorial covers the following tasks:

• Creating a flow that features an Ajax endpoint and an Ajax connector
• Translating data from a web page into the Mule message processing flow
• Using XSL and Mule Transformers to pre-process user input into an XML format that the Spell Checker API can understand
• Creating a connection to the Spell Checker API so it can process Web page input
• Returning XML data to the originating web page via the Ajax transport channel
• Implementing a Jetty HTTP server within the flow

This tutorial requires approximately 30 minutes to complete.  If you prefer a more guided approach to this tutorial, consider signing up for free Mule ESB Training, which uses this tutorial to demonstrate how to use Mule Studio.

Create a Studio Project

If you have taken the Basic Studio Tutorial, you can avoid potential confusion involving the similar resource tree structures in the two projects by closing the basic tutorial before you start the intermediate project. Do so by completing the following steps: In the Package Explorer, right click the project named spell_checker, or whatever alternate name you gave the basic tutorial project. Select Close Project from the drop-down menu.

The Ajax Spell Checker flow contains five Mule components plus a connector.

This section repeats the Mule project creation procedure, which was previously covered in slightly greater detail by the Basic Studio Tutorial.

1. In the Studio application menu, navigate to File, New, then click MuleProject.
2. In the Name field, type Ajax Spell Checker or some other description to help you differentiate this application-building project from your other Mule application projects. This project name, which can contain spaces when you enter it, will appear as a single string — with underscore characters ( _ ), rather than spaces, between the words — in the Package Explorer pane. To commit the name you just typed, click Next.
3. After the New Mule Flow panel appears, type ajax flow or some other description for your flow into the Name field. Once again, any spaces in the string you type are converted to underscores. For example, ajax flow is rendered asajax_flow.mflow. Click Finish to commit the name.

Add Components to the Flow

If the Ajax Spell Checker flow you just created is not already open, double-click ajax_flow.mflow, which resides under the flows node in the Package Explorer pane.

As you assemble your sequence of building blocks in the Message Flow pane, you can click theConfiguration XML tab to observe how the underlying XML code is updated each time you add a building block or populate an attribute field within the visual interface.

The following steps create an Ajax connector in the Global Elements view, and an Ajax endpoint in the Message Flow view. As demonstrated later in this tutorial, these two elements work together to implement a Jetty HTTP server with an Ajax transport channel.

Drag the following components onto the Canvas, sequencing them as illustrated in the diagram below. These components are found in the Endpoint, Transformer, and Component categories in the Palette.

1. Ajax Endpoint
2. Object-to-XML Transformer
3. XSLT Transformer
4. HTTP Endpoint
5. Echo Component

If you inadvertently misplace a building block within your growing sequence, simply delete it, then drag another copy of the building block from the Palette to the position place in the sequence.

You can find building blocks quickly by typing all or part of the name in the Filter field at the top of the palette.

Add and Configure a Connector

Next, add and configure the Ajax connector, which is a Global Element (i.e., template) that provides server connection information to the Ajax endpoint:

1. Click the Global Elements tab at the bottom of the canvas to open the Global Elements view. 
   
   
2. Click the Create button to open the Choose Global Type pane.
3. Click the arrow to the left of Connectors to expand that node.
4. Select Ajax, then click OK.
   
   1. Type AjaxConnector in the Name field.
   2. Type http://127.0.0.1:8090/Ajax in the Server URL field.
   3. Type src/main/app/docroot in the Resource Base field. 
      
      
5. Click OK to close the pane.

The Global Elements view now lists an Ajax connector.

Configure the Building Blocks

Now the Ajax Connector has been created, configure the resources needed by the Ajax endpoint to reference the Ajax Connector.

Configure the Ajax Endpoint

The Ajax endpoint serves as the Message Source (i.e., inbound endpoint) for the flow. Configure it by completing the following steps:

1. Click the Message Flow tab to display your application flow on the canvas.
2. Double-click the Ajax component to open its Properties panel.
3. For Display Name on the General tab, enter Ajax Channel.
4. For Channel, enter /services/echo. This is the path used for communication with the web page. 
   
   

5. Click the References tab and click the down arrow to the right of the Connector Ref field. Select AjaxConnector from the drop-down list. This represents the Ajax connector created earlier in the Global Elements view. 
   
   

   The Ajax Connector can also be created and edited directly within the References tab on the Ajax endpoint Properties pane. Click the Add or Edit links to the right of the Connector Ref field to create or modify connector. No matter where you create it, the Ajax Connector always displays when you open the Global Elements view.

6. Click the Documentation tab, enter a meaningful description for the connector in the Description field, then click OK to close the Endpoint Properties pane.

The Display Name, which is optional, renders as a label under each component in the flow. Any content you enter in the Description field displays when you hover the mouse over the component in the Message Flow view. Both fields are also recorded as building block attributes in the Configuration XML view, thus facilitating easy building block identification and debugging of projects in the XML editor.

Configure the Object-to-XML Transformer

This building block, which translates incoming messages into XML code, requires no specific configuration settings; however, populating the Display Name and Description fields can provide helpful information during troubleshooting sessions.

1. Double-click the Object-to-XML icon on the Message Flow canvas to open the Properties pane. 
2. On the General tab, type Convert JS Object to XML in the Display Name field.
   
   
3. Click the Documentation tab and type Convert JS Object to XML in the Description field, then click OK to close the Properties pane.

Configure the XSLT Transformer

Mule Studio includes most of the files you need to complete this tutorial and run the application after you have built it. Follow these steps to add one more file – transform.xml – to your local drive and then import this file into your Studio application. The transform.xsl file provides your application with instructions for extracting data from incoming messages and translating that data into a form the application can digest.

Download and Import the XSLT Translation File

1. To download the transform.xsl file which contains information that supports this tutorial, right click the link below, then select Download Linked File As... (or Save Linked File As...). 
   
   transform.xsl file


2. In the dialogue pop-up that appears, save the file to your hard drive. 
3. In Studio's Package Explorer pane, click the arrow to the left of the src/main/resources node to expand the branch.
4. Navigate to the location on your hard drive where you saved the transform.xsl file, then drag it into Studio into the src/main/resources folder.
5. In the dialog box that appears, click Copy.
6. Verify that Mule successfully imported the file: the transform.xsl file should now be present inside the src/main/resources folder.

Configure the XSLT Message Processor

This building block uses the instructions in transform.xsl to perform the actual transformation of messages so they can be processed by the rest of the flow. Configure it by completing the following steps:

1. Double-click the XSLT transformer component to open the Pattern Properties pane.
2. On the General tab, replace the Display Name with: Convert XML Structure.
3. In the XSL File field, type: src/main/resources/transform.xsl 
   
   
   
   
4. Click the Documentation tab, then type the following Description: Produces compliant XML for the API.
5. Click OK to close the Pattern Properties pane.

You can reference the .xsl file directly at its physical location on your computer. However, importing the file into the project directory and providing a relative link (through the XSLT component properties) instead of an absolute link creates a portable project, which you can export as a Mule archive and deploy to a different installation of Mule ESB or CloudHub, all without requiring further configuration.

Configure the HTTP Endpoint

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

1. Double-click the HTTP Endpoint component to open the Endpoint Properties pane.
2. On the General tab, type API in the Display Name field.
3. In the Host field, type spellcheck-service.cloudhub.io/spellcheck
4. In the Port field, type 80
   
   
5. In the Method field, type POST
6. Click the HTTP Settings tab, click the down arrow to the right of the Content type field, then select text/xml from the drop-down list.
7. Click the Documentation tab, then type Sends XML requests to the Web service and receives XML responses in theDescription field.

8. Click OK to commit the choices you made in the Endpoint Properties pane.

   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:   Click here to expand...

Configure the Echo Building Block

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 and description.

1. On the Message Flow canvas, double-click the Echo icon to open the Properties pane. 
   
   
2. On the General tab, type Echo to Console in the Display Name field.
3. Click the Documentation tab, then type Terminates the flow and logs results to the console in the Description field.
4. Click OK to close the Properties pane and commit your entries.

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

Create a docroot directory for the HTML file

1. In the Package Explorer create a new folder named docroot under the branch src/main/app
   1. Right-click the app folder, then select New > Folder. 
   2. In the New Folder dialog box, type docroot in the Folder name field, then click Finish.
2. Right-click the docroot node, which is now located under the branch src/main/app,  to open it.
3. Navigate to the folder on your hard drive where you installed MuleStudio, and find the SpellChecker.html file under MuleStudio > examples > AjaxSpellChecker > HTMLfile. 
4. Drag the SpellChecker.html file into Studio into the docroot folder in the Package Explorer.
5. In the dialog box that appears, click Copy.
6. Verify that SpellChecker.html resides within the src/main/app/docroot node in the Package Explorer view.
7. Double-click the docroot node, then double-click SpellChecker.html to open the file in the Mule Studio editor and view its contents.

Congratulations, you have now built an advanced Mule ESB project with Mule Studio!

Run the Project!

Run the project from within Mule Studio to observe exactly what it does.

1. Be sure to save your project by selecting File > Save on the Studio menu. (This saves all projects that are open in Studio, although for this tutorial, ajax-spell-checker should be your only open project).

2. To run the project, right-click ajax_flow.mflow in the Package Explorer pane, then select Run as Mule Application. This causes the Console to display the following message:

   ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + Started app 'ajax_spell_checker'                         + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

3. 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.
   • A 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.
   • Combining 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 will appear with an empty form field. Type heeello, and the following results will appear:

Notice that as you type, the Response: data updates for each character you enter. The Web Service returns a series of spelling suggestions. Usually, the first suggestion contains the correct spelling.

1. The Echo building block makes it possible for you to monitor the Studio Console view for output as you type. The Console should display something similar to the following:

******************************************************************************** * Message received in service: ajax_flow_Flow1. Content is: '<?xml             * * version= "1.0" encoding= "UTF-8" ?><spellresult error= "0" clipped= "0"           * * charschecked= "7" suggestedl...[ 100 of 175 ]'                                  * ********************************************************************************

If Something Goes Wrong . . . If the Studio Console shows error messages, don't feel bad. Removing and re-installing Studio is fast and easy.   Click here to expand...

Stopping the Ajax Spell Checker Application

To exit the Mule application you just created, click the red Terminate icon above the Console view.