Hello World Example

This page describes the configuration and behavior of the Hello World example provided with the Mule ESB distribution. This sample uses two services to create a "hello world" message. When the application starts, it prompts you to type your name, which is received by the first service. The service component adds some text to the string before passing it on to the second service, which also adds text before writing the results back to the console. There are easier ways to achieve this same result, but this example provides a nice demonstration of how a message flows in a Mule application.

Running the Application

If you are using the Mule IDE, you can simply create a new project based on the Hello World example and run it from Eclipse as described in Quick Start.

If you are not using the Mule IDE, do the following:

1. Make sure you have met the prerequisites and installed Mule according to the Installing Mule instructions.
2. At the command line, navigate to the examples/hello directory under your Mule home directory.
3. Type hello.bat on Windows or ./hello on UNIX.
4. Follow the on-screen prompts. If you choose the simple configuration, you will be prompted to enter your name. If you choose to receive events via HTTP, you can invoke the service by pointing your browser to http://localhost:8888?name=yourName.
5. To stop Mule, type 'CTRL-C' in the Mule console window.

How it Works

The Hello World application is configured in the hello-config.xml file in examples/hello/conf under your Mule home directory. This section walks through the configuration and the source Java files it calls.

The Prompt

The STDIO connector is configured to display a prompt when the application starts:

<stdio:connector name="SystemStreamConnector"
        promptMessageCode="3"
        resourceBundle="messages.hello-example-messages"
        messageDelayTime="1000"/>

The prompt is taken from the hello-example-messages.properties file in the examples\hello\src\main\resources\messages folder, which has the following entries:

1=, how are you?
2=Hello 
3=Please enter your name: 
4=Please provide a valid name with at least one character!

There are translated versions of this property file in the same folder that you could specify instead, such as if you wanted to display the strings in German instead of English.

The Classes

The Mule configuration file calls out to two Java classes to process the message. The first is the Greeter class, which uses a method from the LocalMessage class to pull the string "Hello" from the properties file. The Greeter class's method greet() then appends "Hello" to the person's name.

public class Greeter
{
    private String greeting = "";

    public Greeter()
    {
        greeting = LocaleMessage.getGreetingPart1();
    }

    public Object greet(NameString person)
    {
        Object payload = person;
        if (person.isValid())
        {
            person.setGreeting(greeting);
        }
        else
        {
            payload = new Exception(LocaleMessage.getInvalidUserNameError());
        }
        return payload;
    }
}

The second class is ChitChatter, which appends ", how are you?" to the string.

public class ChitChatter
{
    private String chitchat = "";

    public ChitChatter()
    {
        chitchat = LocaleMessage.getGreetingPart2();
    }

    public void chat(ChatString string)
    {
        string.append(chitchat);
    }

}

Wiring the Classes Together

The Mule configuration file calls these classes from within services, which are defined using the <service> element. There are two services configured in the Hello World application: GreeterUMO and ChitChatUMO.

The GreeterUMO service accepts the input the user types at the prompt, calls the Greeter class, and forwards the message to the internal queue on which the ChitChatUMO service is listening. It also performs some transformations along the way:

<service name="GreeterUMO">
  <inbound>
    <stdio:inbound-endpoint system="IN" transformer-refs="StdinToNameString"/>
  </inbound>
  <component class="org.mule.example.hello.Greeter"/>
  <outbound>
    <filtering-router>
      <vm:outbound-endpoint path="chitchatter"/>
      <payload-type-filter expectedType="org.mule.example.hello.NameString"/>
    </filtering-router>
    <filtering-router>
      <vm:outbound-endpoint path="userErrorHandler"/>
      <payload-type-filter expectedType="java.lang.Exception"/>
    </filtering-router>
  </outbound>
  <default-service-exception-strategy>
    <vm:outbound-endpoint path="systemErrorHandler"/>
  </default-service-exception-strategy>
</service>

The <inbound-endpoint> element receives inbound messages using the STDIO transport. The transformer-refs property specifies the inbound transformer to invoke before the GreeterUMO receives the message. The transformer is defined earlier in the configuration file as follows:

<custom-transformer name="StdinToNameString" class="org.mule.example.hello.StdinToNameString"/>

This transformer converts the String it receives from the STDIO connector into a NameString object, which is the data type expected by the greet() method in the Greeter class. Note that when you specify the component, you do not need to specify a specific method to call in the class--Mule can determine the appropriate method based on the data type of the message.

After the Greeter class returns the message with the text appended, Mule dispatches the message on the endpoint vm://chitchatter. This sends the message to an in-memory queue called chitchatter, which is the queue on which the ChitChatUMO service is listening (see below). The GreeterUMO service also specifies some exception handlers to handle user errors and system errors. These are defined as services later in the configuration file.

After the GreeterUMO service has prepended "Hello" to the input user name, the ChitChatUMO service appends its text to the message. Its configuration looks like this:

<service name="ChitChatUMO">
  <inbound>
    <vm:inbound-endpoint path="chitchatter" transformer-refs="NameStringToChatString"/>
  </inbound>
  <component class="org.mule.example.hello.ChitChatter"/>
  <outbound>
    <pass-through-router>
      <stdio:outbound-endpoint system="OUT" transformer-refs="ChatStringToString" />
    </pass-through-router>
  </outbound>
</service>

To demonstrate transformers further, the ChitChatter class expects a ChatString object, so we have a NameStringToChatString transformer that converts the message's payload from the NameString to a ChatString before the component receives the message. The message is received on vm://chitchatter, the endpoint on which the GreeterUMO dispatched its message.

The Output

After processing the message, the message is sent on the STDIO endpoint System.out. There is one more transformer, ChatStringToString, which converts the payload from a ChatString to a plain string so that it can be handled by the STDIO transport and displayed in the console as follows:

Hello Ross, How are you?

Please enter your name:

Note that the Java classes have no routing logic whatsoever and that they were wired together solely through the Mule configuration file, which can take any existing Java classes, web services, etc. and pass messages among them.

Related Topics

For more information on configuring Mule, using transformers, and all other topics, browse the home page of the Mule User's Guide (login required). Additionally, the following topics in the User's Guide provide more information on concepts covered above:

• For information on configuring various types of components, see Configuring Components.
• For information on controlling the method to call in a class (the entry point) and working with component lifecycles, see Developing Service Components.
• For information on the types of transports you can use, see Available Transports.
• For information on using translated strings, see Internationalizing Strings.