Basic Studio Tutorial

You can build and run a simple Mule application in just a few steps.

The following demonstration leverages a Google Spell Checker API to process XML files and correct misspelled words.

Launching Studio

If you have already launched Studio as part of the installation process, and it is now running, skip the rest of this section and proceed directly to: Creating a New Project.

If Studio is not currently running, launch the application now by completing the following steps:

1. Navigate to the directory where you installed Studio
2. Run the executable muleStudio.exe
3. Click OK to accept the default workspace

Creating a New Project

1. If you see the various control elements of the application window (below, right), proceed directly to Step 2. If, instead, you see the First Steps pane (below, left) in your application window, this is the first time you have run Studio. Click Go to Mule Studio, then proceed to Step 2.
   
   
   
   
2. Using the Studio application menu, click File > New > Mule Project.
3. After the New Mule Project specification panel opens (below), type “Spell Checker” or some other meaningful string in the Name field.
4. Click anywhere in the Description text box, then type comments pertaining to the project, if you wish. Note that the Server Settings element shows the Mule Server Community Edition, which comes bundled with Studio.
   
   
   
   
5. Proceed to the New Mule Flow specification panel, by clicking Next.

"About Project Templates" This spell checker project does not use an existing template; however, the bottom pane of the Mule Project screen facilitates creation of template-based projects. These templates, which are working Mule projects with complete flows, provide insight into the power of Mule and can serve as robust foundations for developing complex Mule applications.

All projects contain at least one message flow. Since Spell Checker is a simple application incorporating only a single message flow, we'll use the application name as the flow name as well. For the purposes of illustration, type this exact string in the Name field on the New Mule Flow specification panel: Spell Checker, then click anywhere in the Description field.

Observe that Studio automatically changes uppercase letters to lowercase, replaces spaces between words with the underscore "_" character, and appends ".mflow" to the end of the string. The result appears in the File name field. When you build the Spell Checker application with the drag-and-drop interface, this .mflow file keeps track of your work.

Type whatever comments or notes you wish into the Description field, then click Finish to complete Flow specification.

A green completion percentage indicator appears at the bottom of the application window, and after a pause, the Canvas pane appears along with the Palette of Mule components. In the project directory tree within the Package Explorer pane, spell_checker.mflow appears under the flows directory (below, left), while mule-project.xml appears under the src directory. The .mflow file holds flow information used by the Canvas visual editor.

Folder Setup

The Spell Checker application requires a pair of special folders to facilitate data input and output. Create them by completing the following steps:

The following procedures is for Windows. Adjust OS-specific details for Linux and Mac systems.

1. Navigate to: Studio Application Menu > File > Open File >.
2. After the Open File window displays, navigate to: <your Studio installation folder, such as C:\MuleStudio > Examples > Spell Checker.
3. Right-click the Spell Checker folder, then select New > Folder.
4. In the highlighted name field, type InXML, then press Enter.
5. Right click the Spell Checker folder once again, then select New > Folder.
6. In the highlighted name field, type OutXML, then press Enter.

About Mule Flows

Inside a Typical Flow

Mule applications process messages according to sequences specified by Mule Flows. In our example (below), Web clients send HTTP messages to an Inbound Endpoint set for the "request-response" exchange pattern. In other words, users of our Mule application expect our application to reply to their requests.

A Filter determines whether the incoming message is valid, then discards it or passes it on to the next building block in the flow.

Next, a business logic Component written in Java processes the message, then generates an answer, which it passes to another Transformer, which, in turn, translates that answer from JMS back into HTTP, then dispatches the reply to the waiting Web client, thus completing the transaction.

Flows can be more complex than the example described above. For instance, you can create: branch flows that execute in parallel with your main flow flows with multiple inputs and outputs reusable subflows Furthermore, a Mule Expression can extract dynamic information from a message and use it on-the-fly to customize processing for the associated message during the course of a flow. All this is conveniently facilitated by Studio's powerful drag-and-drop interface.

Arranging Building Blocks

You build a Mule Flow by dragging building blocks from the Palette onto the Canvas. The Palette pane contains seven categories of components: Endpoints, Scopes, Components, Transformers, Filters, Flow Control, and Cloud Connectors. You can expand or collapse each category by clicking on the category header. To keep the category expanded, click the push pin on the right side of the category header.

To place a component on the Canvas, click and hold your mouse button over the component icon, drag the icon onto the canvas, then release the button. If the icon doesn't appear exactly where you want it within an existing sequence of icons, simply delete the icon, then drag another copy of the icon from the Palette to the Canvas.

Depending on the situation, a horizontal or vertical demarcation line may appear to guide your placement of the icon.

Building the Spell Checker Flow

1. Click and drag File, which resides in the Palette's Endpoints group, then release it anywhere over the Canvas.
   
   
   
   
2. Click and drag HTTP, which also resides in the Endpoints group, but make sure you place it just to the right of the File icon so that it lands within the flow's boundary box, which is indicated by a broken line. Just before you release your mouse button, the canvas should look like this:
   
   
   
   
3. After you release your mouse button, an arrow showing the direction of the message flow appears between the File component and the HTTP component.
   
   
   
   
4. Add another File component from the Endpoints group to the right side of your flow. Drag this icon (not pictured) to the right of the HTTP Endpoint, also taking care to place it within the flow’s boundary box.
5. Finally, drag Echo, which resides in the Palette's Component group, to the Canvas and place it between the first File Endpoint and the HTTP Endpoint. Your canvas now displays your complete flow!

Configuring the Flow Components

Nearly all Mule components provide configuration options, which you can set through dialog boxes, all without writing XML.

For your convenience, all the resources needed for this tutorial come bundled with Mule Studio. To inspect them, navigate to File > Open File > <the folder where you installed Mule Studio, such as C:\MuleStudio> > Examples > SpellChecker. In that folder, you will find the file spellchecker.xml and a pair of sub-folders named InXML and OutXML, respectively. When you are through inspecting these elements, close the Open File pane.

File Inbound Endpoint

1. Within the Canvas, double-click the left-most File Endpoint in your flow. The Endpoint Properties dialog box opens, displaying the General tab (below). Note that Studio has automatically identified this File component as an Inbound Endpoint.
2. In the Display Name field, you have the option to enter a strongly descriptive name such as Incoming Data File, which will appear directly under the File Endpoint icon on the Canvas.
3. In the Path Information panel, enter the Path of the InXML directory under the location (SpellChecker) where you unzipped the project archive. For our testbed, the entire path looks something like this: C:\MuleStudio\Examples\SpellChecker\InXML.
4. Click OK to complete the Incoming Endpoint configuration and return to the Canvas.

Later in this tutorial, after you deploy the application and place the sample XML data file into the InXML directory, that file is processed through the flow, then deleted from the InXML directory. If set, the Move to directory field on the General tab instructs Mule to save a copy of the data file to a new location. Optionally, you can save the data file by entering a unique name in the Move to pattern field.

Echo Component

The Echo Component, which displays messages in the Studio console when the application runs, requires no configuration.

1. Optionally, you can enter a Display Name on the General tab. On the Documentation tab, you can also enter descriptive comments, which will appear in a help balloon when you hover your mouse over the component icon in the Canvas.
2. Click OK to complete Echo configuration and return to the Canvas.

HTTP Endpoint

This outbound endpoint retrieves information from a back-end resource (in this case, the Google Spell Checker API).

1. In the Message Flow pane, double-click the HTTP Endpoint icon to open the General tab (below), then complete the following fields:
   • In the Host field, type the URL of the Google Spell Check API: www.google.com/tbproxy/spell?lang=en
   • In the Port field, type the port number used by the Google Spell Check server: 80
   • In the Method field, type the method for communicating with the Google Spell Check server:POST
     
     
     
     
2. Optionally, enter a Display Name in the General tab, and a Description under the Documentation tab.
3. Click OK to complete HTTP Endpoint configuration and return to the Canvas.

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... On the Message Flow canvas, double-click the HTTP endpoint to display the Endpoint Properties pane. Click the References tab. Click the "+" icon to the right of the Connector Reference tab. Click the Proxy Settings tab. In the Proxy Host Name field, type the URL of the proxy server, such as www.proxy.<your_company>.com. (You may need to ask your system administrator for these setting as well as log on credentials) In the Proxy Port field, type the port number used by the proxy, such as 80. In the Proxy User Name field, type the user name you use to log on to the proxy server. In the Proxy Password field, type the password you use to log on to the proxy server. Click OK to commit these proxy configuration settings.

File Outbound Endpoint

1. Configure the Outbound Endpoint by clicking the right-most File icon in the flow.
2. In the Path field (below), enter the location of the OutXML directory where you unzipped the project archive. It should look something like this: C:\MuleStudio\Examples\SpellChecker\OutXML.
3. For this Endpoint, also enter the following Output pattern: #[function:datestamp:dd-MM-yy]_#[function:systime].xml. This instructs Mule to combine a date stamp and a time stamp when creating a file name for the output data it writes to the OutXML directory.
4. Optionally, enter a Display Name in the General tab, and a Description in the Documentation tab.
5. Click OK to complete File Outbound Endpoint configuration and return to the Canvas.

You have just created and configured your first Studio application.

Optional: Clicking the Configuration XML tab immediately beneath the Canvas pane switches from the visual (Message Flow) representation of your flow to the XML view. You can add to or edit the XML listing directly, and your changes will appear as soon as you switch back to the Message Flow view. This is known as "round tripping." In XML view, your flow should look like this:

Running the Spell Checker

Now that you have configured your project, you are ready to run it!

1. In the Package Explorer pane, right-click on spell_checker.mflow, then click Run As > Mule Application.
   
   
   
   
2. If you haven't already saved your project, do so now through the Save and launch dialog box (not pictured). Click OK so that Studio will save your flow, then build and run your application.

After a series of deployment messages, the Console pane opens below the Canvas, displaying the following message: Started app 'spell_checker'.

Testing the Spell Checker

Your project is now running. Mule is watching the InXML directory for XML files. To start a flow process, you need to copy an XML file into this directory.

1. Navigate to the Spell Checker project directory, which should be something like: C:\MuleStudio\Examples\SpellChecker).
2. Identify the one file, spellcheck.xml, that is located in the SpellChecker folder. This file contains some purposefully misspelled text: "Creeating mi fiirst Mulle Studio aplication!"
3. Copy this file (don't simply move it, as the file you move will be deleted) into the InXML folder. Notice that as soon as you do this:
   • The Studio Console displays numerous messages, the last of which is "Writing file to..."
   • The spellcheck.xml file no longer resides in your InXML folder.
   • A new file has been produced in the OutXML folder.
   • The new file name includes the date-and-time stamp pattern we specified in the File Outbound Endpoint dialog (i.e., something like: 21-01-12_1327187012641.xml).
   • The new file contains suggested spelling corrections for the misspelled words the Google API found in the inbound XML file.
   • Your spell checker application continues to run, waiting for additional XML files in can process.

The following listing shows the content of the spellcheck.xml file you copied and placed into the InXML folder:

<?xml version="1.0" encoding="utf-8" ?>
  <spellrequest textalreadyclipped="0" ignoredups="0" ignoredigits="1" ignoreallcaps="1">
    <text>Creeating mi fiirst Mulle Studio aplication!</text>
  </spellrequest>

The listing below shows the suggested corrections returned by the Google API through the time-stamped file it placed in the OutXML folder.

<?xml version="1.0" encoding="UTF-8"?>
  <spellresult error="0" clipped="0" charschecked="44">
    <c o="0" l="9" s="0">Creating Crating Greeting Cremating Curating</c>
    <c o="13" l="6" s="0">first	foist fist fiesta fest</c>
    <c o="20" l="5" s="0">Muller Mlle Mule Mull	Miller</c>
    <c o="33" l="10" s="0">application applications allocation placation implication</c>
  </spellresult>

Running the Test Again

Simply copy spellcheck.XML once more and place it in the InXML folder.

If Something Goes Wrong . . . When the Studio Console shows error messages, or you want to run the test again – but your spellcheck.xml file disappeared because you placed the original file (rather than a copy) into the InXML folder, don't feel bad. Removing and re-installing Studio is fast, safe, and easy. Click here to expand... Shut down Studio by clicking the "X" in the upper right corner of the Studio application window. In the Confirm Exit dialog box, click OK to confirm that you wish to shut down Studio. Locate the zip file you downloaded and used to install Studio, which may reside somewhere such as C:\users\<your_name>\downloads. Navigate to the folder where you installed Studio, which may be something like C:\Studio. Delete everything in the Studio installation folder and all its subfolders (but in any case, don't delete the downloaded zip file you used to install Studio, if it happens to reside in your Studio install folder). Unzip the contents of the installation package into your Studio installation folder. Launch Studio by double-clicking the executable in the Studio installation folder. You're back in business! Take the tutorial again; it's fast, and everything will make greater sense the second time through!

Stopping the Spell Checker

To stop the application, click the square, red Terminate icon above the Console window.

That's it! You have created and run your first Mule application!

What's Next?

If you've got an extra half hour, now, or in the near future, Mulesoft strongly recommends that you try the Intermediate Studio Tutorial, which shows how to build a more complex spell checker application.

Other Destinations

• You can learn more about Mule concepts by navigating to the [Mule Studio Essentials] page.
• The [Studio Interface] page provides details and links for using the Studio IDE.
• If you're already familiar with the Mule environment and want to dive right into application development, see [Studio Building Blocks], which lists, by category, the prepackaged parts you can assemble into powerful Mule flows.
• If you've got questions about Studio, consult the [Studio FAQ] page.

To browse other documentation related to Studio, check out the [Mule Studio User's Guide].

Your Rating:

Thanks for voting!

Please Wait

Results:

23

rates