Mule Getting Started Guide

Mule Getting Started Guide Mule Enterprise Edition Version 2.2.6 August 2010 For a quick start, see page 7

Confidential The ideas contained in this publication are subject to use and disclosure restrictions as set forth in the license agreement. Copyright Copyright 2003-2010, MuleSoft, Inc. All rights reserved. No part of this publication may be copied or distributed, transmitted, transcribed, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, manual, optical, chemical or otherwise; or disclosed to third parties without the express written permission of MuleSoft, Inc. Disclaimer Information in this document is subject to change without notice and does not represent a commitment on the part of MuleSoft, Inc. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the agreement. In addition, MuleSoft, Inc makes no representation or warranties either express or implied, with respect to this manual and accompanying software and specifically disclaim any implied warranties of merchantability or fitness for any particular purpose. This manual and accompanying software are sold as is and MuleSoft, Inc will in no event be liable for direct, indirect, incidental or consequential damages resulting from any defect, error or failure to perform except as expressly set forth in the license agreement. Trademarks MuleSoft, Mule and MuleForge are among the trademarks of MuleSoft. All other product names are trademarks of their respective companies. Part number: 223en_us2009.11.1

Table of Contents Preface.............................................. 6 Who Should Read This Guide?............................... 6 What s the Fastest Way Through This Guide?.................... 7 Existing Users......................................... 8 Typographic Conventions................................... 8 Mule Technical Support..................................... 8 Chapter 1 Introduction to Mule ESB................................ 9 What is Mule ESB?....................................... 10 Understanding the Messaging Framework...................... 11 Understanding the Mule ESB Architecture...................... 12 About SOA.......................................... 13 Processing the Data.................................... 13 Routing Messages Between Service Components.............. 14 Separating Business Logic from Messaging.................. 15 Wiring Everything Together............................. 17 Understanding the Logical Data Flow......................... 18 Integrating Mule ESB into Your Environment................... 21 Administering Mule....................................... 23 Managing Your Deployments with the Management Console.... 23 Controlling the Infrastructure with the Service Registry........ 23 Monitoring Mule Instances Using JMX.................... 24 Compatible Technologies................................... 24 Operating Systems.................................... 24 Application Servers.................................... 24 Containers.......................................... 25 JMS Servers......................................... 25 Developer Tools...................................... 25 Transports........................................... 26 Security............................................. 27 Databases........................................... 27 Web Service Technologies............................... 27 Mule Getting Started Guide 3

Table of Contents Languages........................................... 27 Data Formats........................................ 28 Deployment Topologies................................ 28 Event Handling....................................... 29 Summary............................................... 29 Chapter 2 Installing and Running Mule............................. 30 Installing Mule........................................... 30 Distribution Types.................................... 31 Compatible Platforms.................................. 32 Installing Third-Party Software........................... 32 Setting Up Your Environment............................ 33 Installing Mule Enterprise............................... 35 Installing the Community or Snapshot Release............... 36 Installing Multiple Instances............................. 37 Setting Up Eclipse........................................ 38 Prerequisites......................................... 39 Build the Hello Application............................. 39 Generate the Eclipse Project............................. 39 Configure Eclipse..................................... 39 Import the Eclipse Project............................... 41 Configure the Eclipse Build Path......................... 41 Create a Run Configuration and Run the Application......... 42 Installing and Configuring Mule IDE......................... 43 Prerequisites......................................... 43 Installing Mule IDE................................... 44 Configuring the Mule Distribution........................ 45 Troubleshooting...................................... 45 Running Mule........................................... 46 Basic Usage............................................. 47 Create a Service Component............................. 48 Configure the Mule Instance............................. 48 Configure the Service.................................. 48 Extend Mule......................................... 49 Where Do I Go Next?..................................... 49 Chapter 3 Tutorial.............................................. 51 Lesson 1: Creating an Application Using Mule IDE............... 51 4 Mule Getting Started Guide

Table of Contents Lesson 2: Creating an Application Manually.................... 54 Lesson 3: Modifying an Application........................... 60 About the Stock Quote Example.......................... 60 How it Works........................................ 60 The Web Service Version............................... 62 Adding a Service and Transformers to the Example............ 63 Example Files........................................ 67 Lesson 4: Introduction to Message Routing..................... 75 Overview........................................... 75 Selecting a Message Style................................ 75 Lesson 5: Advanced Message Routing.......................... 80 Filtering Messages..................................... 80 Chaining Outbound Endpoints Together................... 81 Splitting Messages..................................... 82 Processing a Message Only Once......................... 84 Summary........................................... 85 Chapter 4 Using Mule IDE....................................... 86 Creating a New Mule Project................................ 86 Creating a New Mule Configuration File....................... 88 Testing the Application.................................... 89 Debugging the Application................................. 93 Switching Mule Distributions............................... 93 Appendix A Distribution Contents.................................. 94 Appendix B Third-party Software................................... 95 Glossary........................................... 100 Index.............................................. 106 Mule Getting Started Guide 5

Preface The Mule Getting Started Guide introduces Mule and related products from MuleSoft. It provides the conceptual information and context that everyone from decision makers to programmers need to get started with planning and implementing Mule. Who Should Read This Guide? This guide is intended for the following audiences: Decision makers who need to evaluate and understand Mule Architects who need to plan how they will implement Mule Business analysts who will design the business processes supported by Mule Developers who will customize and extend Mule Integration developers who will integrate Mule with other applications Administrators who will maintain and troubleshoot Mule 6 Mule Getting Started Guide

Preface What s the Fastest Way Through This Guide? What s the Fastest Way Through This Guide? This section describes what you should read based on your role. Getting a Quick Start If your role is... Decision maker such as CIO, Director of Software Architecture, or IT manager Architect responsible for designing the system Business analyst responsible for designing the business processes Developer responsible for customizing or extending Mule Integration developer responsible for wiring everything together Administrator responsible for maintaining Mule Read... Chapter 1, Introduction to Mule ESB Appendix B, Third-party Software Chapter 1, Introduction to Mule ESB Chapter 2, Installing and Running Mule Appendix B, Third-party Software Chapter 1, Introduction to Mule ESB Glossary on page 100 Chapter 1, Introduction to Mule ESB Chapter 2, Installing and Running Mule Chapter 3, Tutorial Chapter 1, Introduction to Mule ESB Chapter 2, Installing and Running Mule Chapter 3, Tutorial Administering Mule on page 23 Mule Getting Started Guide 7

Typographic Conventions Preface Existing Users If you are an existing user, go to http://mule.mulesource.org/x/j4h8 to learn about the new features and how to migrate your configuration files to this release. Mule Enterprise customers can use the migration tool and follow the instructions in the Migration Guide, both available from the Downloads page on the MuleSoft customer portal (log in at http://mulesupport.mulesource.com/portal/login.mule. Typographic Conventions The following table describes the typographic conventions used in the Mule documentation: Typeface Meaning Example AaBbCc123 Files and directory names, parameters, command lines, and code examples. Edit the information in struts-config.xml AaBbCc123 Placeholder text that you change. http://servername/mule AaBbCc123 AaBbCc123 A live link to a web site, email address, or another section in the document The names of user interface controls, menus, and menu items. See page 8 Choose File > Edit. Mule Technical Support If you have a paid subscription to MuleSoft, you can view the Mule knowledge base and get assistance with Mule products at http://support.mulesoft.com. For information on purchasing a subscription, contact MuleSoft by phone at 1-877-MULE-OSS or by email at info@mulesoft.com. 8 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB This chapter describes Mule ESB, its architecture, and how it is useful to your enterprise. It contains the following sections: What is Mule ESB? on page 10 Understanding the Messaging Framework on page 11 Understanding the Mule ESB Architecture on page 12 Understanding the Logical Data Flow on page 18 Integrating Mule ESB into Your Environment on page 21 Administering Mule on page 23 Compatible Technologies on page 24 Summary on page 29 Mule Getting Started Guide 9

What is Mule ESB? Chapter 1 Introduction to Mule ESB What is Mule ESB? Mule ESB is a lightweight Java-based messaging framework that allows you to quickly and easily connect your applications and enable them to exchange data. Mule ESB uses a service-oriented architecture (SOA), enabling easy integration of your existing systems. Regardless of the different technologies the applications use, including JMS, Web Services, JDBC, HTTP, and more, Mule ESB seamlessly handles interactions among them all. The Mule framework is highly scalable, allowing you to start small and connect more applications over time. Mule ESB manages all the interactions between applications and components transparently, regardless of whether they exist in the same virtual machine or over the Internet, and regardless of the underlying transport protocol used. Mule ESB is based on ideas from Enterprise Service Bus (ESB) architectures. The key advantage of an ESB is that it allows different applications to communicate with each other by acting as a transit system for carrying data between applications within your intranet or across the Internet. There are currently several commercial ESB implementations on the market. However, many of these provide limited functionality or are built on top of an existing application server or messaging server, locking you into that specific vendor. Mule ESB is vendor-neutral, so different vendor implementations can plug in to it. You are never locked in to a specific vendor when you use Mule ESB. 10 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Understanding the Messaging Framework Mule ESB provides many advantages over competitors, including: Mule ESB components can be any type you want. You can easily integrate anything from a plain old Java object (POJO) to a component from another framework. Mule ESB and the ESB model enable significant component reuse. Unlike other frameworks, Mule ESB allows you to use your existing components without any changes. Components do not require any Mule ESB-specific code to run in Mule ESB, and there is no programmatic API required. The business logic is kept completely separate from the messaging logic. Messages can be in any format from SOAP to binary image files. Mule ESB does not force any design constraints on the architect, such as XML messaging or WSDL service contracts. You can deploy Mule ESB in a variety of topologies, not just ESB. Because it is lightweight and embeddable, Mule ESB can dramatically decrease time to market and increases productivity for projects to provide secure, scalable applications that are adaptive to change and can scale up or down as needed. MuleSoft also provides administration tools that allow you to manage your deployments (Mule Management Console) and control your infrastructure (Mule Galaxy). These tools are described in more detail in Administering Mule on page 23. The next section provides more detail on the messaging framework and how Mule ESB exchanges data among applications. Understanding the Messaging Framework The advantage of networking your applications is that one application can send data to another application. However, many applications don't have the ability to read or process data coming from another application. Mule ESB solves this problem by providing a messaging framework that reads, transforms, and sends data as messages between applications. A message is simply a packet of data that can be handled and sent between applications on a specific channel (also called a queue). Message Application 1 Application 2 Data Channel Mule Getting Started Guide 11

Understanding the Mule ESB Architecture Chapter 1 Introduction to Mule ESB At the simplest level, when you connect applications to Mule ESB, it reads data from one application, transforms it as needed so it can be read by the target application, and sends it to that application. This allows you to integrate all types of applications, even those that were not built to be integrated. Mule ESB is a messaging framework based on ideas from Enterprise Service Bus (ESB) architectures. The key advantage of an ESB is that it allows different applications to communicate with each other by acting as a transit system for carrying data between applications within your intranet or across the Internet. The heart of the system is the message bus, which routes messages between applications. One difference between Mule ESB and a traditional ESB is that Mule ESB only converts data as needed. With a typical ESB, you have to create an adapter for every application you connect to the bus and convert the application s data into a single common messaging format. The development of these adapters and the time required to process every message requires a lot of time and effort. Mule ESB eliminates the need for a single message format. The information is sent on any communication channel, such as HTTP or JMS, and is translated only as needed along the way. Therefore, Mule ESB increases performance and reduces development time over a traditional ESB. The Mule ESB architecture and terminology use the principles described in the book Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions by Gregor Hohpe and Bobby Woolf. This book is highly recommended reading for anyone involved in working with enterprise messaging solutions. For more information, see http://www.enterpriseintegrationpatterns.com. Understanding the Mule ESB Architecture This section describes the different parts of the Mule ESB architecture and how they handle messages and their data. For the sake of illustration, it uses the example of a company that needs to generate invoices for customer orders, perform some processing on those invoices, and then send them to the shipping department for order fulfillment. Order Entry Application Message Invoice Process Invoice Message Updated Invoice Order Fulfillment Application 12 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Understanding the Mule ESB Architecture About SOA Mule ESB is based on the concept of a service-oriented architecture (SOA). The SOA approach to development allows IT organizations to create applications by bringing together components of application functionality, or services. Services are discrete sets of functionality that are completely separate from each other but can work together on the same objects. For example, if you need to process invoices, you might have one service that merges customer data from a database into the invoice and another service that checks the inventory database to see if the items on the invoice are in stock. Because each service stands alone, services can be used as building blocks for multiple processes and do not have to be recreated for each type of process or message. For example, the service that merges customer data onto the invoice could also be used to merge customer data onto statements, letters, or other documents. This modular approach allows you to create functionality once and re-use it as many times as needed, streamlining development. Using SOA, businesses can realize dramatic savings on development costs and can rapidly adapt to changing business conditions by reusing and reconfiguring existing services in developing new applications. SOA also enables better integration of enterprise IT resources, including previously isolated application silos and legacy systems. Mule ESB fully supports the SOA approach and orchestrates communication among the services, allowing you to easily tie all these applications together. Processing the Data When a message is sent from an application (such as the invoice from an order entry system), Mule ESB picks up the message, sends it to a service that processes it using some specific business logic (such as checking the customer and inventory databases), and then routes it to the correct application (such as the order fulfillment system). Mule ESB contains many individual parts that handle the processing and routing of the message. The key part of the Mule Getting Started Guide 13

Understanding the Mule ESB Architecture Chapter 1 Introduction to Mule ESB service is the service component. The service component executes business logic on messages, such as reading the invoice object, adding information to it from the customer database, and then forwarding it to the order fulfillment application. Customer Database Order Entry Application Message Invoice Customer Data Service Component Configuration Settings Message Updated Invoice Order Fulfillment Application Service An important feature of the service component is that it doesn t have to have any Mule ESB-specific code; it can simply be a POJO, Spring bean, Java bean, or web service containing the business logic for processing data in a specific way. Mule ESB manages the service component, bundles it with configuration settings and exposes it as a service, and ensures that the right information is passed to and from it based on the settings you specified for the service in the Mule ESB configuration file. You can have many different service components that perform different business logic, such as one that verifies whether the items on the invoice are in stock and one that updates a separate customer database with the order history. The invoice, which is encapsulated in a message, can flow from one service component to the next until all the required processing is complete. Routing Messages Between Service Components As stated previously, the service component contains business logic for processing the data in the message. It does not contain any information about how to receive or send messages themselves. To ensure that the service component receives the right messages and routes them properly after processing, you specify an inbound router and an outbound router for the component s wrapping service when you are configuring Mule ESB. 14 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Understanding the Mule ESB Architecture Inbound routers specify which messages the service component will process. They can filter incoming messages, aggregate them, and resequence them before routing them to a service component. For example, if a service component subscribes to an RSS feed, the inbound router could filter which messages it receives from that feed. After a service component has processed a message, the outbound router specifies where to dispatch the message. For example, it might route invoices for in-state addresses to one shipping department and route all other invoices to another shipping department. You can define multiple inbound and outbound routing constraints and even chain routers together so that a service component receives and routes messages exactly as required. Customer Data Service Component Message Domestic Order Fulfillment Application Inbound Router Outbound Router Outbound Router Message Updated Invoice Updated Invoice Inbound Router International Order Fulfillment Application Inbound Router Separating Business Logic from Messaging One of the many advantages of Mule ESB is that it can handle messages that are sent via a variety of protocols. For example, an invoice might always be in XML format, but it might arrive over HTTP in one situation and as a JMS message in another depending on which application created the invoice. If the service component handles only business logic and works with the data, not the message itself, how does it know how to read the various formats in which the message might arrive? The answer is that service components don t know how to read the messages, because by default, service components are completely shielded from the message format. Instead, a transport carries the message along, and transformers change the message s payload (such as the invoice) as needed to a format the service component can read before the router passes the message to the service component. For example, if an XML invoice is sent over HTTP, the HTTP transport carries the message along, routers direct the message to each service Mule Getting Started Guide 15

Understanding the Mule ESB Architecture Chapter 1 Introduction to Mule ESB component that needs to process it, and transformers change the invoice along the way (such as from XML to a Java object) as required by each service component. All the transporting, transforming, and routing of the message are completely transparent to the service component. Service Customer Data Service Component Inbound Router Outbound Router XML to Java Object Transformer Message JMS Transport Message HTTP Transport Transformers are the key to exchanging data, as they allow Mule ESB to convert the data to a format that another component or application can understand. Most importantly, data is transformed only as needed. Instead of converting every message to a single common messaging format, messages and their data are transformed only as needed for the target component or application where the message is being sent. Lastly, you can use multiple types of transports to handle different channels, such as sending the message over HTTP and then forwarding it as a JMS message after it has been processed by the Customer Data service component. The separation of the business logic from the sending and transformation of messages allows for great flexibility in how you set up your architecture and makes it much simpler to customize the business logic without having to worry about the various formats in which a message might arrive. Your service component can work with the raw data of the message if desired, but it is not required. 16 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Understanding the Mule ESB Architecture Wiring Everything Together Endpoints are configuration elements that are the key to wiring together all the services. You specify endpoints in the inbound and outbound routers to tell Mule ESB which transport to use, where to send messages, and which messages a service component should receive. The primary part of an endpoint is the address, expressed as a uniform resource indicator (URI), which indicates the transport to use, the location (a transport-specific resource), and any additional parameters. For example, if a service s inbound router specifies the endpoint http://myfirm.com/mule, the HTTP transport will dispatch to that service any messages that have been sent to that URL. If the inbound router specifies file://myserver/files/, the File transport, which is watching that directory, dispatches any new files created in that directory to the service. The endpoint you specify on the outbound router indicates where the message will go next it goes to the service with the same inbound endpoint as the previous component s outbound endpoint, as shown in the following illustration. Endpoint: http:// myfirm.com/mule Service Customer Data Service Component Endpoint: jms://myqueue Service Order Fulfillment Service Component Endpoint: jms://myqueue Inbound Router Outbound Router Inbound Router Message sent to http:// myfirm.com/mule HTTP message HTTP Transport JMS Transport JMS message A service can receive messages using different transports. For each type of transport that a service will use, you must specify one or more separate endpoints. For example, if you want one of your services to handle messages coming in on both the HTTP and JMS channels, you would specify at least one HTTP endpoint and at least one JMS endpoint in the inbound router for that service. Mule ESB registers these endpoints with the service, and the transport uses this registry information at runtime to configure itself and determine where to send and receive messages. Mule Getting Started Guide 17

Understanding the Logical Data Flow Chapter 1 Introduction to Mule ESB The router or endpoint can include filters that further specify which messages to send or receive. For example, you can specify that the service component only receives RSS messages by a specific author. Specifying routers and endpoints for your services simply requires editing an XML file. You do not have to write any Java code. As stated previously, your service components code remains completely separate from messaging and routing, which you handle through the Mule ESB configuration. In summary, Mule ESB provides a simple and lightweight way to write service components that do something to data without needing to worry about the sender or recipient of the data, the format of the data, or the technology being used to send/receive the data. Although many brokering and integration technologies offer the ability to connect to disparate data sources, they often require extra coding to get messages to behave the way you want and to deliver the data where you want it to go. Mule ESB allows you to quickly develop service components and then change the way they behave through simple XML configuration instead of writing Java code. Understanding the Logical Data Flow The previous sections introduced each of the parts of the Mule ESB instance from a conceptual view point. Now, using the invoice example again, let s take a look at how data flows logically through each part of a Mule ESB instance. Throughout the process, Mule ESB uses the Mule ESB configuration file to determine which components, routers, transports, and transformers to use along the way. The diagram that follows illustrates these steps. 1 The customer places an order on the company web site, and an invoice is created as an XML form and submitted to http://myfirm.com/orders. 2 The HTTP transport receives the XML invoice and wraps it in a Mule message. The Customer Data service s inbound endpoint is set to http://myfirm.com/orders, and its inbound router specifies that the message must contain a Java object, so the HTTP transport prepares to transform the XML invoice and dispatch the message to the service. 3 The XML to Object transformer converts the XML invoice into a Java object. Note that the next service and the final application also expect Java objects, so no further transformers are used in this scenario. 4 The transport passes the message with its transformed payload to the Customer Data service. 5 The Customer Data service component queries the master customer database to pull additional data about the customer and updates the invoice with the data. 18 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Understanding the Logical Data Flow 6 The HTTP transport uses the outbound router configuration to determine that it must now dispatch the message to http://myfirm.com/verify. 7 The HTTP transport uses the inbound router configuration of the Inventory Verification service to receive the message and pass it to the service component. 8 The service component updates the invoice with an ID code of the warehouse that has all the items on the invoice in stock. 9 The outbound endpoint specifies a JMS address, so the JMS transport dispatches the message to the order fulfillment application, which picks up orders on that address. Mule Getting Started Guide 19

Understanding the Logical Data Flow Chapter 1 Introduction to Mule ESB Customer Data Service Customer Data Service Component 5 Data http:// myfirm.com/ orders Inbound Router http:// myfirm.com/ verify Outbound Router 4 XML to Java Object Transformer 1 2 POJO 3 POJO w/customer data 6 Order Entry Sends messages to http://myfirm.com/orders 9 Order Fulfillment Receives messages on jms://myqueue XML HTTP Transport JMS message JMS Transport POJO includes warehouse ID HTTP Transport Outbound Router jms://myqueue 8 Inventory Verification Service Component Inbound Router http:// myfirm.com/ verify Inventory Verification Service 7 20 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Integrating Mule ESB into Your Environment Integrating Mule ESB into Your Environment As mentioned at the beginning of this chapter, Mule ESB is based on ideas from the ESB architecture. The messaging backbone of the ESB is usually implemented using JMS, but any other message server implementation could be used, such as MSMQ, IBM WebSphere MQ (and earlier versions know as MQSeries), or TIBCO Rendezvous. Additionally, there are no strict rules on how your integration service layer should behave when using Mule ESB. You can connect Enterprise JavaBean components (EJBs), mainframe applications, messaging, web services, sockets, and file systems and interact with them all in a simple consistent way. Mule ESB also supports other topologies beyond ESB, including pipeline, peer network, client/server, hub-and-spoke, and more. These topologies can be mixed and matched in an enterprise service network to model complex enterprise messaging and service requirements, as shown in the following illustration. When integrating with Mule ESB, you can start with just a few applications and connect more applications to Mule ESB over time. For example, one Mule ESB customer started by integrating six systems. Three years later, they had a total of 71 systems connected using Mule ESB. Mule ESB allows you to start as small as needed and easily scale over time. Mule Getting Started Guide 21

Integrating Mule ESB into Your Environment Chapter 1 Introduction to Mule ESB You can have multiple instances of Mule ESB distributed across your network, as shown in the following illustration. This approach is useful for failover (if one Mule ESB instance becomes unavailable because the server stops, another Mule ESB instance can take over its messages) as well as for load-balancing (you can send some messages to one instance and other messages to another instance to balance the load). You can deploy each instance of Mule ESB as a stand-alone application, in a web container (such as Apache Tomcat), or in an application server. You can use proprietary J2EE application servers such as BEA WebLogic, IBM WebSphere, Oracle Application Server, and SunOne, as well as in open source products like Geronimo or JBoss. Designing your system is both an art and a science. It must be done correctly to ensure scalability. MuleSoft Professional Services can help you by reviewing your architecture, designing components, or doing the full implementation for you. For more information, contact your MuleSoft Professional Services representative. 22 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Administering Mule Administering Mule MuleSoft provides additional tools for monitoring and managing your Mule deployment, as shown in the following illustration. This section describes these tools and how they can help you administer Mule. Managing Your Deployments with the Management Console The management console for Mule ESB provides a centralized way to manage all of your standalone Mule deployments as well as all of the disparate systems and services in your SOA infrastructure. For example, a typical stack that the management console monitors might include Redhat Enterprise Linux, MySQL, JBoss Application Server, OpenMQ, and Mule. The management console provides integrated log, configuration, and server event tracking. It can detect Mule ESB servers and associated software and hardware, and report real-time and historical details of events. The management console is available with Mule Enterprise Edition only. It can monitor both Community Edition and Enterprise Edition instances of Mule 2.x servers (to monitor Mule 1.x, download the previous release, Mule HQ 3.5). The management console fully supports standalone Mule ESB deployments and provides some monitoring data for embedded Mule ESB instances. Controlling the Infrastructure with the Service Registry The service registry for Mule ESB helps you get control over your infrastructure by providing the following features: Registry: automatically detects and displays dependencies among services and manages service lifecycles. Repository: stores and manages artifacts (including Mule configuration files, web services frameworks, and any other artifact), providing version management and collaborative comments, and allows you to publish the artifacts in a web browser using the Atom Publishing Protocol. Governance: provides a centralized control point for policy management and compliance, ensuring that your SOA adheres to your firm's policies. Mule Getting Started Guide 23

Compatible Technologies Chapter 1 Introduction to Mule ESB The service registry can be deployed either alongside Mule or as a standalone component in an enterprise's SOA infrastructure. The service registry is available with Mule ESB Enterprise. It is based on the open-source Mule Galaxy project, which can be used with the community edition of Mule ESB. Monitoring Mule Instances Using JMX JMX is a simple and standard way to manage applications, devices, services, and other resources. JMX is dynamic, so you can use it to monitor and manage resources as they are created, installed, and implemented. You can also use JMX to monitor and manage the Java Virtual Machine (JVM). The JMX agent is useful for integrating Tivoli or HP OpenView with Mule. Compatible Technologies Following are the technologies that are known to work with Mule. Operating Systems Linux Windows Solaris AIX HP-UX Mac OS X Application Servers Standalone Tomcat WebLogic WebSphere Geronimo JBoss Jetty 24 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Compatible Technologies Resin Containers EJB 3 jbpm Spring JMS Servers ActiveMQ FioranoMQ JBossMQ OpenJMS OpenMQ Oracle AQ SeeBeyond SonicMQ Sun JMS Grid SwiftMQ TIBCO EMS WebLogic JMS Developer Tools Ant Data Mapper (Eclipse IDE, Oakland) Eclipse Japex Maven Mule IDE Profiler Mule Getting Started Guide 25

Compatible Technologies Chapter 1 Introduction to Mule ESB Transports Abdera Amazon SQS Axis BPM CICS CTG CXF Email FTP Hibernate HTTP/S IMAP/S JCR JDBC Jersey Jetty/Jetty SSL JMS LDAP Multicast POP3/S Quartz Restlet RMI SalesForce SAP Servlet SMTP/S SOAP STDIO TCP UDP VM XMPP WSDL 26 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Compatible Technologies Security WS-Security Acegi Jaas PGP Spring Security Databases Derby MySQL Oracle Web Service Technologies Axis Atom CXF.NET Web Servces REST SOAP WS-Addressing WS-Policy WS-Security WS-I BasicProfile WS-I SecurityProfile WSDL Languages Groovy Java JavaScript Jaxen JRuby Mule Getting Started Guide 27

Compatible Technologies Chapter 1 Introduction to Mule ESB JXPath Jython (Python) OGNL RegEx SXC XPath XQuery Data Formats Atom Base 64 encoded Byte arrays CSV EDI Encrypted GZIP Hex strings HTML / XHTML Java objects JAXB JSON Streaming Strings XHTML XML XML entity encoded Deployment Topologies ESB Client/Server Peer-to-Peer Enterprise Service Network Hub and Spoke Pipeline 28 Mule Getting Started Guide

Chapter 1 Introduction to Mule ESB Summary Event Handling Asynchronous Routing Patterns SEDA Streaming Synchronous Transactions Summary Mule ESB provides a messaging framework that enables exchange of data among applications. The application functionality is wrapped as a service, which includes a service component (the business logic that processes the data), routers (which use endpoints to specify where to send the message), and other configuration settings. Transports carry the messages on different channels from service to service, and transformers convert the messages and data as needed along the way. Mule ESB is not a replacement for existing application frameworks. Instead, Mule ESB leverages many open source projects such as Apache CXF, Spring, and ActiveMQ and fills a void in enterprise Java development where an application requires complex interactions with a variety of systems on a variety of platforms. Mule ESB makes light work of wiring systems together in a robust, decoupled environment with little to no code and provides the necessary support to route, transport, and transform data to and from these systems. This chapter provided an introduction to the Mule ESB architecture. Now, read Chapter 2, Installing and Running Mule, for more detailed information on how to download, install, and get started using Mule. Mule Getting Started Guide 29

Chapter 2 Installing and Running Mule This chapter describes how to get started using Mule. For full details, see the Mule User Guide at: http://mule.mulesource.org/documentation/display/mule2user/home This chapter contains the following sections: Installing Mule on page 30 Setting Up Eclipse on page 38 Installing and Configuring Mule IDE on page 43 Running Mule on page 46 Basic Usage on page 47 Where Do I Go Next? on page 49 Installing Mule This section describes how to download and install the three types of Mule distributions. Install the third-party software and set up your environment first, and then follow the installation instructions for the distribution type you are downloading. Note If you need to upgrade from a previous release of Mule, see Existing Users on page 8. 30 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Installing Mule Distribution Types There are three types of Mule distributions. The distribution you choose depends on your business needs and current phase of development. MuleSoft supported release (Mule Enterprise): the latest, fully tested release of Mule ESB created by MuleSoft that includes premium features not found in the community release. Mule Enterprise provides access to technical support, maintenance patches, and the MuleSoft knowledge base and is suitable for development, pre-production, and production environments alike. If you have purchased a license for Mule Enterprise, log in to the customer portal at http://mulesupport.mulesource.com/portal/login.mule, and then click Downloads. If you are evaluating Mule, you can download the 30-day trial of Mule Enterprise at http://www.mulesoft.com/mule-esb-enterprise-trial-download. Latest stable community release: the latest stable release of the community release of Mule ESB. This distribution is suitable for people who are evaluating Mule ESB in development or pre-production environments. (Mule Enterprise is the best choice for production environments.) To download the community release, go to http://www.mulesource.org/display/mule/download Snapshot release: the latest Mule distribution built against the very latest code base ( the bleeding edge ). Snapshot releases may be unstable, so they are intended for development environments only, not for production environments. Additionally, snapshot releases do not include any documentation. To download a snapshot release, go to http://www.mulesource.org/display/mule/download You can also download the source code and build Mule yourself. For complete information, see Setting Up the Development Environment (http://www.mulesoft.org/documentation/display/mulecdev/setting+up+the+ Development+Environment) and Building from Source (http://www.mulesoft.org/documentation/display/mulecdev/building+from+s ource). Note If you download one of the compressed distributions, you will need a compression tool such as WinZip (Windows) or GZip (Linux/UNIX) to decompress the ZIP or TAR file. Mule Getting Started Guide 31

Installing Mule Chapter 2 Installing and Running Mule Compatible Platforms Users run Mule on many different operating systems with a variety of messaging platforms and application servers. The following table lists the platforms that members of the community have reported are compatible with Mule. Technology Operating Systems Application Servers Messaging Platforms Java JDK 1.5 and 1.6 Windows XP SP2, Windows 2000, Windows 2003 Server (32-bit if using the Java Service Wrapper), Linux, Solaris, AIX, HP-UX, and Mac OSX Tomcat, JBoss, WebSphere, WebLogic, and Jetty Any JMS vendor; users have reported integration with Active MQ, Open MQ, TIBCO EMS, TIBCO Rendezvous, Oracle AQ, and IBM WebSphere MQ Installing Third-Party Software Before you install and run Mule ESB, you must install Java and Maven. Note If you are using UNIX, log in as a non-root user before you proceed. This will ensure that your environment and Mule installation can support Mule HQ if you decide to install it later, as Mule HQ requires that you log in as a non-root user before you install it. Compression Tool: If you will be downloading one of the compressed Mule distributions, make sure you have a compression tool installed such as WinZip (Windows) or GZip (Linux/UNIX) to decompress the ZIP or TAR file. Java: Install Java Developer Kit (JDK) 1.5. Note that JDK 1.4.x will work if you are not using CXF or building Mule from the source code, but JDK 1.5.x is highly recommended. Run the installer, following the instructions that appear on the screen. You can download JDK 1.5 from http://java.sun.com/javase/downloads/index_jdk5.jsp If you are using the Mule IDE, you must also endorse the JDK with a proper JAXP (Java API for XML Processing) implementation. To do this, download Apache Xerces and Xalan and drop the JARs into your JVM's jre/lib/endorsed directory. If that directory does not yet exist, create it. 32 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Installing Mule Mule IDE: If you are installing the Mule IDE, install it immediately after installing Mule see I Installing Mule on page 30. Maven: If you do not want to use the Mule IDE, or if you will be using the Maven archetypes to create a new transport or module, install Maven. Download the Maven distribution from the Maven web site (http://maven.apache.org/) and unpack it to any folder (for example, c:\apache). Since there were some critical bugs in earlier versions, Maven 2.0.9 is recommended. If you are using a Macintosh, you must use Maven 2.0.9. Create a Maven repository directory with no spaces in the path, such as c:\.m2\repository on Windows. (If Windows Explorer does not allow you to create the.m2 folder name, use the mkdir command in a console window instead.) Open the settings.xml file in your Maven conf directory (e.g., c:\apache-maven-2.0.9\conf) and specify the repository directory. For example: <localrepository>c:/.m2/repository</localrepository> Ensure that this entry is not commented out in this file. Ant: If you want to use Ant to build the examples instead of Maven, download and install it if you have not done so already. You can download Ant from http://ant.apache.org/bindownload.cgi. Setting Up Your Environment Before you can use Mule, you must create environment variables for Java, Maven, Ant (optional), and Mule, and update your path to point to their bin directories. If you intend to run Mule as a Windows service, you must create system environment variables instead of user environment variables. 1 Create an environment variable called JAVA_HOME and set it to the directory where the JDK is installed. 2 Create an environment variable called MAVEN_HOME and set it to the directory where you unpacked Maven. 3 Create an environment variable called MAVEN_OPTS and set it to -Xmx512m -XX:MaxPermSize=256 4 If you will use Ant, create an environment variable called ANT_HOME and set it to your Ant home directory. Mule Getting Started Guide 33

Installing Mule Chapter 2 Installing and Running Mule 5 Create the MULE_HOME environment variable and set it to the location where you will install Mule. If you are running Windows, the installation path must not contain any spaces (for example, you cannot use C:\Program Files). A good workaround is to create a root directory called Mule (for example, C:\Mule). This step is not required if you will use the Mule IDE. 6 Update the PATH environment variable so that it includes the path to the JDK, Maven, and Mule binaries. If you are using Windows, you can use the System utility in the Control Panel to add the environment variables and edit your path. Alternatively, you can use the export or set commands (depending on your operating system) at the command prompt, as shown in the following examples: Linux/UNIX export JAVA_HOME=/opt/java/jdk export MAVEN_HOME=/opt/apache/maven-2.0.9 export MAVEN_OPTS='-Xmx512m -XX:MaxPermSize=256m' export MULE_HOME=/opt/mule export PATH=$PATH:$JAVA_HOME/bin:$MAVEN_HOME/bin:$MULE_HOME/bin Windows set JAVA_HOME=C:\Program Files\Java\jdk set MAVEN_HOME=C:\Apache\maven-2.0.9 set MAVEN_OPTS='-Xmx512m -XX:MaxPermSize=256m' set MULE_HOME=C:\Mule set PATH=%PATH%;%JAVA_HOME%/bin;%MAVEN_HOME%/bin;MULE_HOME/bin You are now ready to install Mule. If you are installing Mule Enterprise, read the next section. If you are installing the community or snapshot release, skip ahead to Installing the Community or Snapshot Release on page 36. 34 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Installing Mule Installing Mule Enterprise Note These instructions are for Mule Enterprise only. For the community or snapshot releases, skip to the next section. This section describes installation of Mule Enterprise on Windows or Linux/UNIX. Follow the instructions for the version of the file you downloaded, and then set up your Maven repository. To install the TAR.GZ: 1 If you downloaded the TAR.GZ version of Mule Enterprise, simply decompress the files into the Mule home directory you specified above. You must use a decompression utility like WinZip, not just the built-in Windows extractor. 2 When you have finished, do one of the following: If you will use the Mule IDE, see Installing and Configuring Mule IDE on page 43. If you will use Maven, skip ahead to Setting Up the Maven Repository on page 36. Otherwise, go to the section on Running Mule on page 46. To install the JAR 1 If you downloaded the JAR version of Mule Enterprise onto Windows, double-click the file to launch the installer. If you do not have Java associated with JAR files by default, open a command prompt, navigate to the directory where you downloaded the JAR file, and then enter the following command: java -jar mule-enterprise-standalone-installer-version.jar where version is the version number in the file name. 2 Follow the instructions in the installer to install Mule. You will also be given options for installing the Profiler pack, which helps you identify memory leaks in your custom Mule extensions, and the scripting module, which provides facilities for using scripting languages in Mule. 3 When you are prompted to specify the installation directory, be sure to specify the same directory as you specified for the MULE_HOME environment variable. 4 Do one of the following: If you will use the Mule IDE, see Installing and Configuring Mule IDE on page 43. Mule Getting Started Guide 35

Installing Mule Chapter 2 Installing and Running Mule If you will use Maven, skip ahead to Setting Up the Maven Repository on page 36. Otherwise, go to the section on Running Mule on page 46. Setting Up the Maven Repository You are now ready to set up your Maven repository as follows. These steps are not required if you will use the Mule IDE to configure Mule (see Installing and Configuring Mule IDE on page 43), but they are required if you will use the Maven archetypes to create new projects, transports, and modules. 1 Open a command prompt and navigate to the Mule bin directory. 2 Type populate_m2_repo.cmd followed by the location of the Maven repository directory (the same directory you specified in the settings.xml file when you installed Maven). For example: cd c:\mule\bin populate_m2_repo.cmd c:\.m2\repository This step is required to populate the Maven repository with the local Mule Enterprise JAR files from the distribution. Note that when you add Mule Enterprise-only features to your code, you must add the correct dependencies to your POM before building your project with Maven. For more information, see Dependencies on the Using Maven page at http://www.mulesoft.org/documentation/display/mulecdev/using+maven#us ingmaven-dependencies. You have completed the Mule installation and setup. You can now skip the next section and go to Setting Up Eclipse on page 38. Installing the Community or Snapshot Release This section describes installation of the community or snapshot release on Windows or Linux/UNIX. 1 If you have a previous release already installed, you should delete the directory where it is installed before installing the later release. 2 Go to the Mule download page at: http://www.mulesource.org/display/mule/download 36 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Installing Mule 3 Click the link next to the release you want to download. Use the.zip links for installing on Windows and the.tar.gz links for installing on Linux/UNIX. The latest releases are at the top of the page. 4 On Linux/UNIX, if you prefer to download through a shell instead of a browser or need to download to a remote computer without X-Windows, you can download the distribution using your download tool. For example to download the Mule 2.0.1 snapshot using wget, you would enter the following command all on one line: wget http://snapshots.dist.codehaus.org/mule/org/mule/distributions /mule-full/2.0.1-snapshot/mule-full-2.0.1-snapshot.tar.gz 5 After the distribution is downloaded, extract its files into the MULE_HOME directory you specified when setting up the environment variables (see page 33). For example, on Linux/UNIX, you would switch to your MULE_HOME directory, and then enter a command like this to extract the files: tar -xvzf mule-full-2.0.1-snapshot.tar.gz Installing Multiple Instances After installing Mule, you can install multiple secondary instances on the same machine, allowing users to set up their own directories for configuration files, logs, and JAR files that interact with the primary Mule installation. On UNIX machines, you can use the setup_local_instance.sh script in the Mule bin directory to set up these secondary instances. If you are installing on Windows, or if you want to configure the secondary instances manually, take the following steps: 1 Run Mule from the primary instance so that the license acceptance and third-party libraries will be properly configured and available for secondary instances. If you are running the enterprise version of Mule, also apply the license to the primary instance before setting up the secondary instance. 2 Log in as the user who will use a secondary instance. 3 Create a directory for the secondary instance with the following subdirectories: /bin - Startup scripts /conf - Local configuration files /examples - Examples (optional) /lib/user - User JARs /logs - Local logs Mule Getting Started Guide 37

Setting Up Eclipse Chapter 2 Installing and Running Mule 4 Copy the files from these subdirectories in the primary Mule instance to the corresponding subdirectories in the secondary instance directory. For example, if your primary Mule instance is in C:\Mule and your secondary instance is in C:\Mule2, you'd copy C:\Mule\bin to C:\Mule2\bin, copy C:\Mule\conf to C:\Mule2\conf, and so on. 5 Create an environment variable called MULE_BASE that points to the secondary instance directory, and create an environment variable called MULE_HOME that points to the location of the primary Mule installation. Using the previous example, you would set MULE_BASE to C:\Mule2 and set MULE_HOME to C:\Mule. 6 Add the MULE_BASE/bin directory to the system path so that the Mule startup script is launched from MULE_BASE instead of MULE_HOME. 7 Repeat these steps for each user who will use a secondary Mule instance. Each secondary instance must be in its own directory, and you must set the MULE_BASE and MULE_HOME environment variables separately for each user. When users run Mule, the files from their secondary instance (MULE_BASE directory) will be loaded first, allowing users to put updated JARs in their MULE_BASE directory and test different scenarios without affecting the primary instance. Setting Up Eclipse When you work with Mule, you can make configuration and development much easier by using an IDE. This section describes how to set up Eclipse, an open-source IDE, to enable easy configuration of Mule and development of new functionality. This section describes using Eclipse 3.4 (Ganymede), which you can download from http://www.eclipse.org/downloads/packages/ (download the Eclipse IDE for Java EE Developers). It contains the following sections: Prerequisites on page 39 Build the Hello Application on page 39 Generate the Eclipse Project on page 39 Configure Eclipse on page 39 Import the Eclipse Project on page 41 Configure the Eclipse Build Path on page 41 Create a Run Configuration and Run the Application on page 42 38 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Setting Up Eclipse Prerequisites Before you continue, be sure you have installed Mule and the prerequisites as described earlier in this chapter. You must also have Internet access to build the example application and generate the Eclipse project, as each of those steps downloads dependencies. Build the Hello Application The first step is to build the application you want to work with in Eclipse. This will download the dependencies in preparation for generating an Eclipse project. For the sake of illustration, we will build and import the Hello example application into Eclipse. To build the example, navigate to the MULE_HOME\examples\hello directory, and then type mvn at the command prompt. Generate the Eclipse Project After building the Hello application, you can generate the Eclipse project by typing the following command: mvn eclipse:eclipse You can now configure Eclipse and import the project. Configure Eclipse You only need to configure Eclipse once. With subsequent projects, you can skip these steps. 1 Start Eclipse. 2 In the Workspace Launcher, specify the location of the examples directory under your Mule home directory (such as C:\mule\examples), and click OK. 3 Click the Workbench icon on the right to display the workbench. 4 Choose Window > Preferences. Mule Getting Started Guide 39

Setting Up Eclipse Chapter 2 Installing and Running Mule 5 Expand Java in the navigation tree, click Compiler, and then change the compiler compliance level to 1.5. 6 Click Installed JREs. If the JRE is not version 1.5, click Edit, click Directory and navigate to your JDK1.5 directory, and then change the JRE name to jdk5. Click Finish, and then click OK. 7 When prompted to rebuild, click No. 40 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Setting Up Eclipse Import the Eclipse Project 1 In the Workbench window of Eclipse, choose File > Import. 2 Expand General, click Existing Projects into Workspace, and then click Next. 3 In the Import dialog box, click Browse, navigate to the Mule examples directory again, and click OK. The hello project should be listed and selected. 4 Click Finish. The hello project is now listed in the Project Explorer on the left. You will notice some errors at the bottom of the screen, which are caused by your build path needing to be configured. Configure the Eclipse Build Path You only need to take these steps once. Future Mule projects will use the same build path. Mule Getting Started Guide 41

Setting Up Eclipse Chapter 2 Installing and Running Mule 1 In the Project Explorer, right-click the hello project and choose Build Path > Configure Build from the popup menu. 2 In the Properties dialog box, click the Libraries tab, and then click Add Library. 3 Click User Library and click Next. 4 Click User Libraries, and then in the Preferences dialog box, click New. 5 In the New User Library dialog box, enter MULE_LIB and click OK. 6 Click Add JARs, navigate to the \lib\mule directory under your Mule home directory, select all the JARs, and click Open. 7 Click OK and then Finish. 8 Click Add Variable, click Configure Variables, and then in the Preferences dialog box, click New. 9 In the New Variable Entry dialog box, create a variable called M2_REPO that points to your Maven repository (such as C:\.m2\repository), which you created when you installed Maven. Click OK. 10 In the Preferences dialog box, click OK, and this time when you're prompted to rebuild, click Yes. Click OK in the open dialog boxes to close them and rebuild the project. Create a Run Configuration and Run the Application This step defines your configuration settings. You only have to do this once per project, and thereafter your settings are stored and used each time your run the application. 1 Choose Run > Run Configurations. 2 In the left window, double-click Java Application, and then change the name to hello and specify org.mule.muleserver for the main class. 42 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Installing and Configuring Mule IDE 3 Click the Arguments tab, and then enter -config conf\hello-config.xml (for Windows) or -config conf/hello-config.xml (for Linux/UNIX) in the Program Arguments box. 4 Click Apply and then Run. The Hello application runs in the Console tab at the bottom of the window, prompting you to enter your name. You can type your name and press Enter to see the application continue. Congratulations! You have successfully built and run your first Mule example from within Eclipse. You can now add services to the configuration, write POJOs as needed, debug your code, and compile and run your examples all within the IDE. If you want to import another example into Eclipse, repeat the instructions to generate an Eclipse project for that example, import the project into the workspace, and then just run the example by choosing Run > Run. You do not have to repeat the steps for configuring Eclipse. Installing and Configuring Mule IDE Mule IDE is a development and testing environment based on Eclipse. It allows you to easily create or edit a Mule project or configuration file in Eclipse. If you want to use Mule IDE and Eclipse, follow the instructions in this section. Prerequisites Before you install Mule IDE, ensure that you have installed the following software: Eclipse 3.4 (Ganymede) or later (see Setting Up Eclipse on page 38). Java 5 or later. You can download Java from http://java.sun.com/javase/downloads/index_jdk5.jsp. Mule 2.2 or later (see Installing Mule on page 30). Note that you do not have to install and configure Maven or Ant if you are using Mule IDE, but you must install Maven if you want to use the Maven archetypes to create transports and other projects. You can ignore the information on that page about running Mule, as you will run Mule from within Eclipse instead of at the command prompt. Mule Getting Started Guide 43

Installing and Configuring Mule IDE Chapter 2 Installing and Running Mule You must also endorse the JDK with a proper JAXP (Java API for XML Processing) implementation. To do this, download Apache Xerces (http://xerces.apache.org/xerces2-j/) and Xalan (http://xml.apache.org/xalan-j/) and drop the JARs into your JVM s jre/lib/endorsed directory. If that directory does not yet exist, create it. Installing Mule IDE You are now ready to install Mule IDE. Use the set of instructions that apply to your version of Eclipse. Before installing, you should first ensure that your existing Eclipse plug-ins are up to date, as Mule IDE depends on specific versions of the Eclipse libraries and the installation will not complete if these are not present. Installing Mule IDE (Eclipse Galileo) 1 Start Eclipse, and set up a workspace for your installation of Mule if you haven't already. (Make sure your workspace does not have a space in the directory path) 2 In the workbench view, choose Help > Install New Software. 3 Click Add next to the Work with text box, enter http://dist.muleforge.org/mule-ide/updates/3.4/, and click Enter. 4 Click the Mule IDE check box and click Next, and after Eclipse processes for a moment, click Next again. 5 Review the IDE license, select the option to accept the license, and then click Finish. 6 Click Yes to restart Eclipse. You are now ready to configure the Mule distribution as described in Configuring the Mule Distribution on page 45. Installing Mule IDE (Eclipse Ganymede) 1 Start Eclipse, and set up a workspace for your installation of Mule if you haven't already. (Make sure your workspace does not have a space in the directory path) 2 In the workbench view, choose Help > Software Updates, and then click the Available Software tab. 3 If you previously installed a preview release of Mule IDE 2.0, click Manage Sites, select the Mule IDE update site, click Remove, and then click OK. 4 On the Available Software tab, click Add Site. 44 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Installing and Configuring Mule IDE 5 Specify http://dist.muleforge.org/mule-ide/updates/3.4/ for the location and click OK. It now appears in your list of available software. 6 Expand it in the list until you see Mule IDE. Click Mule IDE and click Install. 7 If you are installing an update of Mule IDE, a screen appears saying that an update will be performed instead. Click Next, read and accept the license agreement terms, and click Finish. You should restart Eclipse before you continue. You are now ready to configure the Mule distribution as described in the next section. Configuring the Mule Distribution You specify the location of a Mule 2.x distribution in Eclipse so that Mule and third-party libraries will be automatically added to Mule project classpaths. This distribution will also be used when launching a Mule server instance to test and debug your application. To configure a Mule distribution: 1 In the Eclipse workbench, choose Window > Preferences. 2 Click Mule, and then click Add. 3 Specify the root directory where the Mule distribution is installed, and then click OK. 4 Click the distribution s check box, and then click Apply. This distribution is now the default Mule distribution. You can configure multiple Mule directories, but only one can be the default. You are now ready to start Eclipse and start using Mule IDE as described in Chapter 3, Tutorial and Chapter 4, Using Mule IDE. Troubleshooting If you have difficulty installing or using Mule IDE, verify the following: You have the correct update site and have uninstalled any developer preview releases. Does your workspace directory or project name have a space in it? Mule runs from the workspace folder, and if it has a space in the name (like Documents and Settings), Mule cannot locate the configuration file to start. Mule Getting Started Guide 45

Running Mule Chapter 2 Installing and Running Mule If you cannot successfully complete the installation steps, remove and recreate the update site. To remove a site in Eclipse, choose Help > Software Updates, on the Available Software tab click Manage Sites, select Mule IDE, and then click Remove. You can now recreate the Mule IDE site following the steps above. Have you updated the other libraries in your eclipse installation? Make sure all of your existing standard Eclipse plug-ins are up to date. Ensure you followed the documented steps to register the endorsed XML libraries and have also previously installed Mule. You will need to configure the location of Mule the first time you create a Mule project. Running Mule Now that you have installed and configured Mule, you are ready to get started! This section describes how to run Mule. If you installed Eclipse, see Create a Run Configuration and Run the Application on page 42 instead. Note If you are using the 30-day trial version of Mule Enterprise, you will not be able to run the trial version after the 30 days has expired unless you purchase a license. (This does not affect the community release of Mule.) For information on purchasing Mule Enterprise, go to http://www.mulesource.com/buynow/. The simplest way to run Mule is to enter the following command at the command prompt: mule [-config your-config.xml] where your-config.xml is the Mule configuration file you want to use. For a quick start, use one of the configuration files in the Examples subdirectories to see how this works. For more information on examples, see http://mule.mulesource.org/x/wam7. To get up and running quickly with developing a Mule application using an example application, see Chapter 3, Tutorial. If you are running the community release of Mule, the MuleSoft Public License is displayed page by page when you first run Mule. To advance a page, press Enter. At the end of the license display, type y to accept the license file and proceed with startup. For more information on ways you can run Mule, see http://mule.mulesource.org/x/gqi7. 46 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Basic Usage Basic Usage When you look at how a message flows through Mule, you can see that there are three layers in the architecture: the application layer, the integration layer, and the transport layer. Service Customer Data Service Component Application Layer Inbound Router Outbound Router XML to Java Object Transformer Integration Layer Message HTTP Transport HTTP Channel JMS Transport JMS Channel Message Transport Layer Likewise, there are three general types of tasks you can perform to configure and customize your Mule deployment: Service component development: developing POJOs, services, or beans that contain the business logic and will be used as service components in a Mule deployment. Integration: developing routers, transformers, and filters, and configuring everything in the Mule configuration file. Extending Mule: developing new transports, connectors, and other modules used by Mule. This section provides a high-level overview of the steps you take to perform these tasks. Mule Getting Started Guide 47

Basic Usage Chapter 2 Installing and Running Mule Create a Service Component A service component is a class, web service, or other application that contains the business logic you want to plug in to the Mule framework. You can use any existing application, or create a new one. Your service component does not need to contain any Mule-specific code. All the Mule-specific instructions will be configured on the service that wraps the service component. To assist development, you should use an IDE such as Eclipse. For a tutorial on setting up Eclipse and creating a new service, see Chapter 3, Tutorial. For more information on developing service components, see: http://mule.mulesource.org/x/2idr Configure the Mule Instance The Mule configuration file allows you to configure all the elements you need in your Mule instance. You use the <configuration> element to set global configuration options such as the threading profile. You then configure the connectors, transformers, and endpoints you'll use in different services. Lastly, you configure models, which act as containers for services and apply settings such as the queue profile to all the services in that model. For complete information, see http://mule.mulesource.org/x/w4lr. Configure the Service You configure a service within a <model> element in the Mule configuration file. The service points to the service component, routers, filters, and transformers. It also specifies the endpoint on which this service will receive messages and the outbound endpoint where messages will go next. For more information, see: http://mule.mulesource.org/x/xakv Following is more information on configuring routers, filters, and transformers for the service. Routers Inbound routers specify how messages are routed to a service, and outbound routers specify how messages are routed after the service has finished processing them. There are several default routers that come with Mule that you can use, or you can create your own routers. For more information, see: http://mule.mulesource.org/x/nakv 48 Mule Getting Started Guide

Chapter 2 Installing and Running Mule Where Do I Go Next? Filters Filters specify conditions that must be met for a message to be routed to a service. There are several default filters that come with Mule that you can use, or you can create your own filters. For more information, see: http://mule.mulesource.org/x/7agv Transformers Transformers convert incoming payload data to the type required by the service component. After the service has finished processing the message, they can also convert the message to a different type as needed by the outbound transport. There are several default transformers you can use, or create your own. For more information, see: http://mule.mulesource.org/x/igkv Extend Mule Mule provides transports for many different channels, including File, FTP, HTTP, JMS, JDBC, Quartz, and many more. There are also community-created transports on MuleForge (http://muleforge.org/). If you need to send messages on a channel other than those provided, you can create a new transport. You can also create a custom connector for a transport. A connector is the Java class in the transport that contains the actual logic for sending and receiving messages on that channel. For more information, see: http://mule.mulesource.org/x/zodr You can also use Maven to create new Mule projects (transports and other types of modules). For more information, see: http://mule.mulesource.org/x/ygi Where Do I Go Next? This chapter has provided a brief overview of getting started with Mule. Following is information about where to go next. For a tutorial on running Mule in an IDE, walking through a configuration, and adding a service to a Mule application, see Chapter 3, Tutorial. For complete information on using Mule, go to the Mule User Guide at: http://www.mulesoft.org/documentation/display/mule2user/home If you need assistance and are a Mule Enterprise customer, see the support page at: http://www.mulesource.org/display/mule/support Mule Getting Started Guide 49

Where Do I Go Next? Chapter 2 Installing and Running Mule If you are evaluating Mule and want to find out about subscription options, you can submit a request for MuleSoft to contact you by going to http://www.mulesource.com/buynow/, or call us at 877-MULE-OSS. All Mule users can subscribe to the Mule mailing lists. You can find these lists at: http://www.mulesource.org/display/mule/mailing+lists If you experience problems with the Mule software or documentation, please log an issue in the MuleSoft issue-tracking system, located at: http://www.mulesource.org/jira/browse/mule 50 Mule Getting Started Guide

Chapter 3 Tutorial This chapter provides a tutorial for running an example, walking through its configuration, and adding a service to an existing Mule application. This chapter contains the following sections: Lesson 1: Creating an Application Using Mule IDE on page 51 Lesson 2: Creating an Application Manually on page 54 Lesson 3: Modifying an Application on page 60 Lesson 4: Introduction to Message Routing on page 75 Lesson 5: Advanced Message Routing on page 80 Lesson 1: Creating an Application Using Mule IDE The simplest way to create an application in Mule is to use Mule IDE with Eclipse. Mule IDE allows you to quickly start a new project, which you can base on one of the existing examples, or just create a new configuration file by selecting the transports you want to use. This lesson walks you through creating a new application called myhelloapp, which will be based on the Hello example, and creating a new configuration file for the project. For more information on using Mule IDE, see Chapter 4, Using Mule IDE. To create the application: 1 In Eclipse Workbench, choose File > New > Project, expand the Mule folder and select Mule Project, and then click Next. 2 Enter the name myhelloapp, ensuring that there is no space in the project name. 51 Mule Getting Started Guide

Lesson 1: Creating an Application Using Mule IDE Chapter 3 Tutorial 3 Click Add sample project content and select the Hello example. 4 Click Next, and then click the Libraries tab and verify that the Java 5 or later library is installed and available on the build path. 5 Click Finish to have Mule IDE generate your project. You will now see the myhelloapp project in the navigation pane on the left. You can expand its folders to see the source code, configuration files, and more. Now, let s create a new configuration file for this application using the System I/O (also called STDIO) and VM transports. 52 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 1: Creating an Application Using Mule IDE To create the configuration file: 1 Choose File > New > Other, expand the Mule folder and select Mule Configuration, and then click Next. 2 Click Browse..., expand the myhelloapp project, select the conf directory, and then click OK. 3 Change the default name from mule-config.xml to my-hello-config.xml. You can use any name you like, as long as it is unique within the project and has an.xml extension. If you use the name of an existing file, it will overwrite that file. 4 Select the System I/O and VM transports, leave Spring Config selected, and then click Finish. Mule IDE creates the configuration file in the conf directory of the myhelloapp project. It adds the namespaces for the STDIO and VM transports. Mule Getting Started Guide 53

Lesson 2: Creating an Application Manually Chapter 3 Tutorial You can now add global elements below the namespace declarations, add services within a <model> element, and add local routers, filters, endpoints, and transformers to the services. Eclipse provides a fast and error-proof method for entering these elements. Simply click somewhere between the opening and closing tags of an element and click Ctrl+space to see the available elements. Double-click the element you want, and Eclipse enters the opening and closing tags for that element. You can also hover over a tag to see a description of the element and its supported attributes. Now that you know how to set up a Mule project and configuration file, the next lesson walks you through the configuration file in detail to help you understand the elements you add. You can continue on with the next lesson from within the Mule IDE and just skip past the first two steps, as you have already declared your XML namespaces. Lesson 2: Creating an Application Manually Creating a Mule application is as simple as creating a configuration file and pointing to a Java class that performs any required custom logic on the messages that come through. This section walks through creating a configuration file for the Hello World application. You can then run Mule using this file and the compiled Java classes. Although the easiest way to create a Mule configuration file is to use the Mule IDE, this lesson walks you through creating the file manually in any XML editor or IDE to help you understand all the elements involved. First, add the XML declaration at the top of the file: <?xml version="1.0" encoding="utf-8"?> Next, in the <mule> element, declare the namespaces for the core Mule schema, XSI, Spring, and the transports and modules you want to use. In this example, we'll use the STDIO and VM transports. You then use the XSI namespace to declare the locations of the schemas. For example: <mule xmlns="http://www.mulesource.org/schema/mule/core/2.2" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:spring="http://www.springframework.org/schema/beans" xmlns:stdio="http://www.mulesource.org/schema/mule/stdio/2.2" xmlns:vm="http://www.mulesource.org/schema/mule/vm/2.2" xsi:schemalocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd 54 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 2: Creating an Application Manually http://www.mulesource.org/schema/mule/core/2.2 http://www.mulesource.org/schema/mule/core/2.2/mule.xsd http://www.mulesource.org/schema/mule/stdio/2.2 http://www.mulesource.org/schema/mule/stdio/2.2/mule-stdio.xsd http://www.mulesource.org/schema/mule/vm/2.2 http://www.mulesource.org/schema/mule/vm/2.2/mule-vm.xsd"> Optionally, add the <description> element with a description of this configuration file. If you are creating only one configuration file for your entire application, the description could be about the entire application. <description>the Hello World sample application has two components - 1. The Greeter component that adds a greeting to the message it receives 2. The ChitChatter component that adds some additional conversation to the message it receives. A message is triggered by input through the system console and the outbound message is also written out through the system console. This configuration also demonstrates user and system error handling. User error handling returns an error message to the end user. System error handling logs errors. </description> While there are several ways in Mule to configure a transport, the best practice is to use the <connector> element to define a global connector configuration, which you can then reference in multiple places. The <connector> element must be prefixed by the namespace of its transport. For example, the following connector will be available to endpoints that use the STDIO transport: <stdio:connector name="systemstreamconnector" promptmessagecode="3" resourcebundle="messages.hello-example-messages" messagedelaytime="1000"/> Because we have only one connector defined for the STDIO transport, this connector will be used by default whenever we create an STDIO transport. If we defined multiple STDIO connectors, you would use the connector-ref attribute on the endpoint to specify the one you want to use. To see which attributes you can set for a connector, go to the transport s reference page by clicking its name on the Available Transports page at: http://www.mulesource.org/x/3ohr Mule Getting Started Guide 55

Lesson 2: Creating an Application Manually Chapter 3 Tutorial Similarly, if you want to configure custom transformers that you can reference from multiple places, add them to the configuration now. For example, the Hello World example uses several transformers that format the message payload and convert it to the datatype expected by each component: <custom-transformer name="stdintonamestring" class="org.mule.example.hello.stdintonamestring"/> <custom-transformer name="namestringtochatstring" class="org.mule.example.hello.namestringtochatstring"/> <custom-transformer name="chatstringtostring" class="org.mule.example.hello.chatstringtostring"/> <custom-transformer name="exceptiontostring" class="org.mule.example.hello.exceptiontostring"/> You are now ready to add your services, which is where you specify your components that do the actual work. Services are contained within models, so you add the <model> tag first: <model name="hellosample">...services will go here Now, start configuring your services by adding <service> tags with a name attribute that contains a unique name for the service. The Hello World example has four services, each of which has an <inbound> section, a <component>, and an <outbound> section in that order. For details on the elements you can configure in a service, see the Service Configuration Reference page at http://www.mulesource.org/x/p5hr. Let s add the inbound section for the GreeterUMO service first: <service name="greeterumo"> <inbound> <stdio:inbound-endpoint system="in" transformer-refs="stdintonamestring"/> </inbound> Notice that within the inbound section, we ve specified the inbound endpoint. The inbound endpoint defines which messages this service will handle by specifying the following: The transport. In this case, it s STDIO. Where the message originates. In this case, it s system.in because the user is typing the information at the command prompt. The transformer to use. Here we reference one of the global transformers we defined earlier in the configuration. 56 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 2: Creating an Application Manually If there is more than one connector configured for the transport, you specify the connector to use. As mentioned earlier, we have only one STDIO connector, so we don t have to specify it explicitly on the endpoint. This inbound endpoint specifies that only messages that are received on system.in at the command line will be received by this service, and they will be transformed by the StdinToNameString transformer before they are passed to the component. There is no inbound router specified, so all messages received on this endpoint will be processed by the service. The component is the next element to configure. The component can be a Java class, web service, or anything that can perform logic on the messages. For information on creating a component, see Developing Service Components at http://www.mulesource.org/x/2idr. In this example, our component is a POJO, so you specify the class in the <component> tag: <component class="org.mule.example.hello.greeter"/> By default, Mule automatically discovers the correct method in the Java class to execute (the entry point) by matching the return type on the transformer (in this case, NameString) to the methods in the component. For information on other ways of resolving the entry point, see Entry Point at http://www.mulesource.org/x/2idr. Now we need to specify what the service will do after the component has finished with it. We specify this in the outbound section. In this case, we want to use an outbound router to send the message to one service if the message was processed successfully and to a different service if the message had errors. To do this, we use filtering routers, each of which specifies a) the outbound endpoint where the message will go next, and b) the criteria the message must meet to be routed there. If a message does not meet the criteria of the first router, it s checked against the second router s criteria, and so on until there s a match. <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> Mule Getting Started Guide 57

Lesson 2: Creating an Application Manually Chapter 3 Tutorial In this case, if the message payload was transformed correctly into a NameString object, the first router sends it to the chitchatter path using the VM transport. If the message was not transformed correctly and the payload contains an exception, the message is routed to the usererrorhandler path using the VM transport. When you configure the services that will handle the message in each of these cases, you must ensure that they specify chitchatter or usererrorhandler as the path on their inbound endpoints. Mule provides support for error handling for unexpected errors. Exception strategies allow you to handle messages when there is a system error: <!-- Route unexpected errors to separate error handler --> <default-service-exception-strategy> <vm:outbound-endpoint path="systemerrorhandler"/> </default-service-exception-strategy> </service> In the Hello World example, user errors are routed to system.out and system errors are routed to system.err. These error-handling services are defined below: <!-- This error handler returns user error messages to caller. Errors could also be routed elsewhere, e.g. into an error file, send via email to a list, stored in a database, etc. --> <service name="usererrorhandler"> <inbound> <vm:inbound-endpoint path="usererrorhandler" transformer-refs="exceptiontostring"/> </inbound> <outbound> <pass-through-router> <stdio:outbound-endpoint system="out"/> </pass-through-router> </outbound> </service> <!-- Handle any unexpected errors. Errors could also be routed elsewhere, e.g. into an error file, send via email to a list, stored in a database, etc. --> <service name="systemerrorhandler"> <inbound> <vm:inbound-endpoint path="systemerrorhandler"/> </inbound> <outbound> <pass-through-router> <stdio:outbound-endpoint system="err"/> 58 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 2: Creating an Application Manually </pass-through-router> </outbound> </service> Notice that these services do not configure components, because they simply route the messages using the pass-through router and do not need to perform any extra logic on the messages. There is one last service in the example: the ChitChatUMO service. This service transforms the message, adds text to it, and writes it to system.out: <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> Lastly, end the file with the closing </model> and </mule> tags:... </model> </mule> To see the entire configuration file for this example, navigate to the examples/hello/conf directory under your Mule home directory and open the hello-config.xml file. The custom classes referenced in the configuration file are included with the example under the examples/hello/src/main/java directory. To run the application, the custom classes must be compiled and available on the Java classpath when Mule starts. If you created your project in the Mule IDE, it handles this for you, and you can execute your application by selecting the Mule configuration file you created (my-hello-config.xml) and running it as a Mule Server. Mule Getting Started Guide 59

Lesson 3: Modifying an Application Chapter 3 Tutorial Lesson 3: Modifying an Application This lesson shows you how to modify the Stock Quote example to call the Stock Quote service from a web page instead of the console. You'll create an HTML page that accepts a stock symbol as input, configure a new HTTP service that receives the input from that page, and configure transformers that will transform the message along the way. This lesson uses Eclipse to build, modify, and run the example. To see a demo of this lesson, go to http://www.mulesource.com/demos/building-service/ This section contains the following information: About the Stock Quote Example on page 60 How it Works on page 60 The Web Service Version on page 62 Adding a Service and Transformers to the Example on page 63 Example Files on page 67 About the Stock Quote Example The Stock Quote example demonstrates how to invoke an ASPX web service from Mule, transform the result using XSLT, and deserialize the result to a StockQuote Java bean. The example demonstrates using REST and Web Services to invoke the service. The configuration uses the STDIO transport to receive a stock symbol from a user (System.in), invokes the StockQuote service, transforms the result using the XSLT transformer, and then uses the XmlToObject transformer to convert the result into a StockQuote Java bean. The quote is then sent to the output console (System.out). How it Works This section walks through the configuration of the REST version of the Stock Quote example, but the Web Service configuration is very similar. Because you've already walked through the Hello example, this section will discuss the configuration without going into step-by-step detail. First, because the proxy settings are in an external properties file, we specify the file in the Mule context: 60 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 3: Modifying an Application <context:property-placeholder location="proxy.properties"/> Next, we configure the HTTP connector with the properties whose values are defined in the proxy.properties file: <http:connector name="httpconnector" proxyhostname="${proxyhostname}" proxypassword="${proxypassword}" proxyport="${proxyport}" proxyusername="${proxyusername}"/> The next section is the configuration for the transformers. There are four transformers, which will be chained together. Note that the XSLT transformer references the XSLT file in the xsl subdirectory under the stockquote directory. The XSLT file can be anywhere on your classpath. <xm:xml-to-object-transformer name="xmltoobject"/> <xml-entity-decoder-transformer name="xmldecoder"/> <xm:xslt-transformer name="xslt" xsl-file="xsl/rest-stock.xsl"/> <object-to-string-transformer name="tostring"/> Next, we set up a model as a container for the one service in this example: HTTPPostSample. This service receives messages sent to vm://stockquote and transforms them using all four transformers before passing them to the component. <model name="sample-rest"> <service name="httppostsample"> <inbound> <vm:inbound-endpoint path="stockquote" responsetransformer-refs="tostring XmlDecoder Xslt XmlToObject"/> </inbound> <http:rest-service-component serviceurl="http://www.webservicex.net/stockquote.asmx/getquote" httpmethod="post"> <http:payloadparametername value="symbol"/> </http:rest-service-component> </service> </model> The component is the REST service component, which uses the REST service wrapper to proxy a REST service to act like a local Mule component. The REST service wrapper has a number of properties configured. The serviceurl is the URL of the REST service to Mule Getting Started Guide 61

Lesson 3: Modifying an Application Chapter 3 Tutorial invoke. The payloadparametername is the name of the parameter to associate with the message payload. In this case, we have only one parameter name, symbol. The httpmethod can either be GET or POST. The Web Service Version The Web Service version works very similarly to the REST version but has different service configuration. The Web Service version explicitly configures an outbound pass-through router that takes the input from one endpoint and passes it directly to the outbound Axis endpoint with no component in the middle. Instead, the outbound endpoint is configured with parameters that map to the Stock Quote service. <model name="sample-soap"> <service name="serviceproxy"> <inbound> <vm:inbound-endpoint path="stockquote" responsetransformer-refs="tostring XmlDecoder Xslt XmlToObject"/> </inbound> <outbound> <outbound-pass-through-router> <axis:outbound-endpoint address="http://www.webservicex.net/stockquote.asmx?method=getquote" responsetransformer-refs="xmldecoder Xslt XmlToObject" soapaction="[methodnamespace][method]"> <axis:soap-method method="qname{getquote:http://www.webservicex.net/}"> <axis:soap-parameter parameter="symbol" type="string" mode="in"/> <axis:soap-parameter parameter="getquoteresult" type="string" mode="out"/> </axis:soap-method> </axis:outbound-endpoint> </outbound-pass-through-router> </outbound> </service> </model> 62 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 3: Modifying an Application Adding a Service and Transformers to the Example Now that you have run the example and walked through the configuration, this tutorial shows you how to modify the example to call the Stock Quote service from a web page instead of the console. You'll create an HTML page that accepts a stock symbol as input, configure a new HTTP service that receives the input from that page, and configure transformers that will transform the message along the way. This tutorial uses Eclipse to build, modify, and run the example. Set Up Eclipse To use the Stock Quote example in Eclipse, you take the following steps as described in Setting Up Eclipse on page 38: 1 Build the Stock Quote example using the mvn command 2 Generate the Eclipse project using mvn eclipse:eclipse 3 Import the project into Eclipse 4 Create a run configuration for the project (see the following illustration) 5 Ensure that the application runs successfully from the Console tab These steps are described in detail in Setting Up Eclipse on page 38. Follow the instructions replacing hello with stockquote, and set the run configuration program arguments to: -config "conf\stdio-config.xml,conf\stockquote-wsdl-config.xml" Mule Getting Started Guide 63

Lesson 3: Modifying an Application Chapter 3 Tutorial Create the HTML Page First, create an HTML page that accepts a stock symbol as input and posts it to the URL http://localhost:8888/getquote. For example: <form action="http://localhost:8888/getquote" method="post" name="myform"> Stock Symbol: <input name='symbol'/> <input type="submit" value="get Quotes" class="form-submit"/> </form> You can create your own HTML page using the complete sample file getquote.html on page 67. Configure the HTTP Service To handle the input from the HTML page and pass it to the proxy service, you modify the configuration file for the Stock Quote service and create a service with an HTTP inbound endpoint and a VM outbound endpoint. The HTTP endpoint must be the same as you configured in the HTML page. The VM outbound endpoint must have the same address as the VM inbound endpoint of the serviceproxy service in stockquote-wsdl-config.xml. For example: <service name="httpservice"> <inbound> <inbound-endpoint address="http://localhost:8888/getquote" synchronous="true"/> </inbound> <outbound> <pass-through-router> <vm:outbound-endpoint path="stockquote" synchronous="true"/> </pass-through-router> </outbound> </service> The file stockquote-http-config.xml on page 69 provides the complete configuration with these settings. 64 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 3: Modifying an Application Create the Transformers Because the serviceproxy service expects messages in a specific format, you must create a transformer that converts the HTTP request to a format that the serviceproxy service expects. The file HttpRequestToStockSymbol.java on page 70 contains sample code for this transformer. Likewise, you must create a transformer that transforms the output of the serviceproxy service back into an HTML string to send as a response to the HTTP request. The file StockQuoteToHTMLString.java on page 72 contains sample code for this transformer. Configure the Transformers After creating the transformers, you declare them in the configuration file and add them to your endpoint, as shown in the following snippets: <custom-transformer name="httprequesttostocksymbol" class="org.mule.example.stockquote.httprequesttostocksymbol"/> <custom-transformer name="stockquotetohtmlstring" class="org.mule.example.stockquote.stockquotetohtmlstring"/> Additionally, we need to set the content type to HTML, so we can define a simple transformer right in the XML file that does this: <message-properties-transformer name="sethtmlcontenttype"> <add-message-property key="content-type" value="text/html"/> </message-properties-transformer> Now, you reference the transformers from the endpoint: <inbound-endpoint address="http://localhost:8888/getquote" synchronous="true" transformer-refs="httprequesttostocksymbol" responsetransformer-refs="stockquotetohtmlstring SetHtmlContentType"/> The configuration file stockquote-http-config.xml on page 69 has these settings already configured. Mule Getting Started Guide 65

Lesson 3: Modifying an Application Chapter 3 Tutorial Copy the Files to Your Project 1 In Eclipse, copy and paste the transformer Java files that you created (or downloaded from this page) to the src/main/java > org.mule.example.stockquote folder of your stockquote project. The two classes should compile without errors. 2 Copy and paste stockquote-http-config.xml to the conf folder of your stockquote project. 3 Copy and paste the HTML file you created (or downloaded) to the root folder of the stockquote project. Modify the Run Configuration You will now modify the run configuration to use the new configuration file. 1 Choose Run > Run Configurations. 2 Click the stockquote run configuration, and then click the Arguments tab. 3 Replace the conf\stdio-config.xml entry with conf\stockquote-http-config.xml and leave the WSDL version intact. The configuration should now look like this: -config "conf\stockquote-http-config.xml,conf\stockquote-wsdl-config.xml" 4 Click Apply and then Run. 66 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 3: Modifying an Application The Mule server should start without errors. Run the Application 1 In Eclipse, right-click the HTML file you added, and then choose Open With > Web Browser. The web page runs right in Eclipse. 2 Enter a stock symbol such as IBM and click Get Quotes. The results of the Stock Quote web service appear on the page. Congratulations! You have successfully added a new service and transformers to the Stock Quote example and configured it to capture and display information on a web page instead of the console. For more information on using Mule, including basic and advanced configuration, working with transformers and filters, configuring transports, and more, see the Mule User Guide at: http://mule.mulesource.org/x/vgkv You can also use the Mule IDE, an Eclipse plug-in that provides additional functionality for developing Mule applications in Eclipse. The Mule IDE is in beta and is available for download on the MuleForge at: http://www.mulesource.org/display/ide/home Example Files This section contains the files used in this tutorial. You can copy and paste them from this section, or download them using the links. getquote.html You can download this file from: http://www.mulesource.org/download/attachments/12257709/getquote.html <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/tr/xhtml1/dtd/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title>get Quotes</title> </head> <script type="text/javascript" src="jquery-1.2.3.js"></script> <body> <!-- Layout --> <div id="wrapper"> <div id="container" class="clear-block"> Mule Getting Started Guide 67

Lesson 3: Modifying an Application Chapter 3 Tutorial <div id="header-region" class="clear-block"><span style='float: right; padding-right: 25px;'><font color='#660000'><b>welcome to Stock Query System :: </b></font><font color='#ff3333'><b><i>guest</i></b></font></span> </div> <br /> <br /> <div id="wrapper"> <div id="header"> <div id="logo-floater"> <div class='center'> <div class='squeeze'> <div id='tabs-wrapper' style='border: none; float: right; position: relative; padding-right: 25px; padding-top: 10px;' class='clear-block'></div> </div> </div> </div> </div> <!-- /header --> <div id="center"> <div id="mycontent"> <form action="http://localhost:8888/getquote" method="post" name="myform" id="myform"> <div>stock Symbol: <input name='symbol' /> <input type="submit" value="get Quotes" class="form-submit" /> <div> </form> <span class="clear"></span> <br /> <br /> <div id='footer' style='text-align: center;'> <div>powered By <b><a href="http://www.mulesoft.com">mulesoft</a></b></div> </div> </div> </div> <!-- /.left-corner, /.right-corner, /#squeeze, /#center --></div> <!-- /container --></div> <!-- /layout --> </body> </html> 68 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 3: Modifying an Application stockquote-http-config.xml You can download this file from: http://www.mulesource.org/download/attachments/12257709/stockquote-http -config.xml <mule xsi:schemalocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd http://www.mulesource.org/schema/mule/core/2.2 http://www.mulesource.org/schema/mule/core/2.2/mule.xsd http://www.mulesource.org/schema/mule/http/2.2 http://www.mulesource.org/schema/mule/http/2.2/mule-http.xsd http://www.mulesource.org/schema/mule/vm/2.2 http://www.mulesource.org/schema/mule/vm/2.2/mule-vm.xsd http://www.mulesource.org/schema/mule/stdio/2.2 http://www.mulesource.org/schema/mule/stdio/2.2/mule-stdio.xsd http://www.mulesource.org/schema/mule/xml/2.2 http://www.mulesource.org/schema/mule/xml/2.2/mule-xml.xsd"> <description> The StockQuote HTTP example listens for http requests and Uses the VM transport to call the stockquote proxy service and returns results to enduser as a html page. </description> <custom-transformer name="httprequesttostocksymbol" class="org.mule.example.stockquote.httprequesttostocksymbol"/> <custom-transformer name="stockquotetohtmlstring" class="org.mule.example.stockquote.stockquotetohtmlstring"/> <message-properties-transformer name="sethtmlcontenttype"> <add-message-property key="content-type" value="text/html"/> </message-properties-transformer> <model name="sample-http"> <!-- This component can proxy external web service calls over Jms, tcp, ssl or any other transport. For this example we use Vm. --> <service name="httpservice"> <inbound> <inbound-endpoint address="http://localhost:8888/getquote" synchronous="true" transformer-refs="httprequesttostocksymbol" responsetransformer-refs="stockquotetohtmlstring SetHtmlContentType"/> </inbound> the Mule Getting Started Guide 69

Lesson 3: Modifying an Application Chapter 3 Tutorial <outbound> <pass-through-router> <vm:outbound-endpoint path="stockquote" synchronous="true" /> </pass-through-router> </outbound> </service> </model> </mule> HttpRequestToStockSymbol.java You can download this file from: http://www.mulesource.org/download/attachments/12257709/httprequestto StockSymbol.java. package org.mule.example.stockquote; import org.mule.transformer.abstracttransformer; import org.mule.util.ioutils; import org.mule.api.transformer.transformerexception; import java.io.inputstream; import java.io.unsupportedencodingexception; import java.net.urldecoder; public class HttpRequestToStockSymbol extends AbstractTransformer { public HttpRequestToStockSymbol() { super(); this.registersourcetype(string.class); this.registersourcetype(byte[].class); this.registersourcetype(inputstream.class); this.setreturnclass(string.class); } /* * (non-javadoc) * * @see * org.mule.transformers.abstracttransformer#dotransform(java.lang.object) */ public Object dotransform(object src, String encoding) throws TransformerException { String srcasstring; if (src instanceof byte[]) { 70 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 3: Modifying an Application if (encoding!= null) { try { srcasstring = new String((byte[]) src, encoding); } catch (UnsupportedEncodingException ex) { srcasstring = new String((byte[]) src); } } else { srcasstring = new String((byte[]) src); } } else if (src instanceof InputStream) { InputStream input = (InputStream) src; try { srcasstring = IOUtils.toString(input); } finally { IOUtils.closeQuietly(input); } }else { srcasstring = src.tostring(); } System.out.println("http post string:" + srcasstring); String request = srcasstring; String symbol = extractvalue("symbol", request); if (symbol == null symbol.trim().length() == 0) { throw new TransformerException(this, new Exception( "Invalid Stock Symbol specified")); } return symbol; } private String extractvalue(string name, String requestquery) throws TransformerException { String namevalue = null; if (requestquery!= null && requestquery.length() > 0) { int nameparameterpos = requestquery.indexof(name + "="); if (nameparameterpos!= -1) { int nextparametervaluepos = requestquery.indexof('&', nameparameterpos); if (nextparametervaluepos == -1 nextparametervaluepos < nameparameterpos) { Mule Getting Started Guide 71

Lesson 3: Modifying an Application Chapter 3 Tutorial nextparametervaluepos = requestquery.length(); } namevalue = requestquery.substring(nameparameterpos + name.length() + 1, nextparametervaluepos); } if (namevalue!= null && namevalue.length() > 0) { try { namevalue = URLDecoder.decode(nameValue, "UTF-8"); } catch (UnsupportedEncodingException uee) { System.err.println("USER ERROR: " + uee.getmessage()); } } } if (namevalue == null) { namevalue = ""; } return namevalue; } } StockQuoteToHTMLString.java You can download this file from: http://www.mulesource.org/download/attachments/12257709/stockquotetoh TMLString.java package org.mule.example.stockquote; import java.util.arraylist; import org.mule.requestcontext; import org.mule.transformer.abstracttransformer; import org.mule.api.transformer.transformerexception; public class StockQuoteToHTMLString extends AbstractTransformer { public StockQuoteToHTMLString() { super(); this.registersourcetype(org.mule.example.stockquote.stockquote.class); this.registersourcetype(string.class); this.setreturnclass(string.class); 72 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 3: Modifying an Application } /* * (non-javadoc) * * @see org.mule.transformers.abstracttransformer#dotransform(java.lang.object) */ public Object dotransform(object src, String encoding) throws TransformerException { ArrayList list; //RequestContext.getEventContext().getMessage().setProperty("Content-Ty pe", "text/html"); //StockQuote quote; System.out.println("StockQuote Instance of: '" + src.getclass().getname() + "'"); System.out.println("StockQuote: " + src); if (src instanceof String) { return src; } StringBuffer sb = new StringBuffer(); sb.append("<!doctype html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'"); sb.append("'http://www.w3.org/tr/xhtml1/dtd/xhtml1-strict.dtd'>"); sb.append("<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'><body>"); if (src instanceof StockQuote) { list = new ArrayList(); list.add((stockquote)src); StockQuote quote = (StockQuote)src; for (int i=0; i< list.size(); i++) { quote = (StockQuote)list.get(i); sb.append("<table cellspacing='0' cellpadding='3' bquote='1' width='300'><tbody><tr bgcolor='#ccccff'>"); sb.append("<td colspan='2'><font size='+2'>"); sb.append("<b>stock Details</b></font></td></tr>"); sb.append("<tr bgcolor='white'>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>stock Symbol</td>"); Mule Getting Started Guide 73

Lesson 3: Modifying an Application Chapter 3 Tutorial sb.append("<td align='left' valign='top' width='50%'><font size='-1'>" + quote.getsymbol() + "</td>"); sb.append("</tr><tr bgcolor='white'>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>company Name</td>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>" + quote.getname() + "</td>"); sb.append("</tr><tr bgcolor='white'>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>last Trade</td>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>" + quote.getlast() + "</td>"); sb.append("</tr><tr bgcolor='white'>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>trade Time</td>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>" + quote.getdate() + "</td>"); sb.append("</tr><tr bgcolor='white'>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>change</td>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>" + quote.getchange() + "</td>"); sb.append("</tr><tr bgcolor='white'>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>high</td>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>" + quote.gethigh() + "</td>"); sb.append("</tr><tr bgcolor='white'>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>low</td>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>" + quote.getlow() + "</td>"); sb.append("</tr><tr bgcolor='white'>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>volume</td>"); sb.append("<td align='left' valign='top' width='50%'><font size='-1'>" + quote.getvolume() + "</td>"); sb.append("</tr>"); sb.append("</tbody></table>"); } } sb.append("<br><a href='javascript:history.go(-1)'>go BACK</a>"); sb.append("</body></html>"); return sb.tostring(); } } 74 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 4: Introduction to Message Routing Lesson 4: Introduction to Message Routing This lesson provides an introduction to message routing and describes when to use the different message styles. Overview Message routers control how messages are routed among the services in your Mule application. Following is a description of the key concepts: Inbound routers control how a service handles incoming messages, such as selectively consuming only those messages that meet specific criteria or grouping messages together that share a group ID before forwarding them on. Outbound routers control how a message is dispatched after the service has processed it, such as sending it to a list of recipients or splitting up the message and sending the parts to different endpoints. Asynchronous reply routers are used in request/response scenarios where message traffic is triggered by a request and the traffic needs to be consolidated before a response is given. The classic example of this is where a request is made and tasks are executed in parallel. Each task must finish executing and the results processed before a response can be sent back. Catch-all strategies are invoked if no routing path can be found for the current message. An inbound or outbound endpoint can be associated with a catch-all strategy so that any orphaned messages can be caught and routed to a common location. Filters provide the logic used to invoke a particular router. Filters can be combined using the logic filters AndFilter, OrFilter, and NotFilter. Not all routers need to use filters, but all routers support them. Selecting a Message Style When wiring your Mule services together, new users sometimes get confused about when to use an outbound router and when it's sufficient to simply get a reply. Following is a description of the message styles you can use in Mule. Mule Getting Started Guide 75

Lesson 4: Introduction to Message Routing Chapter 3 Tutorial Asynchronous If you simply want to put a message on a SEDA queue after processing it, and no response to the caller is required, you can use the asynchronous message style. For example: <model name="asynchronous_message_pattern"> <service name="asynchronousservice"> <inbound> <jms:inbound-endpoint queue="test.in" synchronous="false"/> </inbound> <component class="org.myorg.widgethandler" /> <outbound> <pass-through-router> <jms:outbound-endpoint queue="test.out"> <pass-through-router> </outbound> </service> </model> Request-Response In simple scenarios that require a response, a service receives a request on a synchronous inbound endpoint, processes the request, and then sends it back to the caller as a reply. For example, if a user enters a value in an HTML form, and you want to transform that value 76 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 4: Introduction to Message Routing and display the results in the same page, you can simply configure a synchronous inbound endpoint on the service that does the transformation. This scenario does not use an outbound router. This is the request-response message style. For example: <model name="request-response_message_pattern"> <service name="synchronousservice"> <inbound> <http:inbound-endpoint host="localhost" port="8080" path="/mule/services" synchronous="true"/> </inbound> <component class="org.myorg.widgethandler" /> </service> </model> Synchronous If you need to pass the message to a second service for additional processing, you would configure an outbound router on the first service to pass the message to the second service. After the second service processes the message, the first service sends it back to the caller as a Mule Getting Started Guide 77

Lesson 4: Introduction to Message Routing Chapter 3 Tutorial reply. Note that setting the synchronous inbound endpoint on the first service means that the message is treated synchronously throughout all subsequent services, so you do not need to set the synchronous flag on the second service. This is the synchronous message style. For example: <model name="synchronous_message_pattern"> <service name="synchronousservice"> <inbound> <jms:inbound-endpoint queue="test.in" synchronous="true"/> </inbound> <component class="org.myorg.widgethandler" /> <outbound> <chaining-router> <jms:outbound-endpoint queue="test.out"/> </chaining-router> </outbound> </service> <service> <inbound> <jms:inbound-endpoint queue="test.out"/> </inbound> <component class="org.myorg.widgetpackager" /> </service> </model> Asynchronous Request-Response In the most complex scenario, you can enable request-response messaging and allow the back-end process to be forked to invoke other services, returning a reply asynchronously based on the results of multiple service invocations. You can set the inbound endpoint's 78 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 4: Introduction to Message Routing synchronous flag to false, since the response will be handled by the asynchronous reply router, unless you also want to send a response to the caller. This is the asynchronous request-response message style. In the following example, a request comes in on an HTTP endpoint, is broadcast to two endpoints using the Multicast router, and the results are sent asynchronously to a JMS endpoint. <model name="async_request-response_message_pattern"> <service name="asyncrequestresponseservice"> <inbound> <http:inbound-endpoint host="localhost" port="8080" path="/mule/services" synchronous="false"/> </inbound> <component class="org.myorg.widgethandler" /> <async-reply timeout="5000"> <collection-async-reply-router/> <jms:inbound-endpoint queue="reply.queue"/> </async-reply> <outbound> <multicasting-router> <reply-to address="jms://reply.queue"/> <jms:outbound-endpoint queue="service1" synchronous="false"/> <jms:outbound-endpoint queue="service2" synchronous="false"/> </multicasting-router> </outbound> </service> </model> Summary This lesson described the different message styles you can use. For complete information, see the appendix on Mule messaging styles in the Mule Configuration Guide. Now that you understand which message styles to use for routing in different scenarios, Lesson Five describes several routers you can use for achieving finer control over message routing. Mule Getting Started Guide 79

Lesson 5: Advanced Message Routing Chapter 3 Tutorial Lesson 5: Advanced Message Routing This lesson builds on Lesson Four and shows you how to use specific message routers to control how a message is routed through your application. Filtering Messages You can control which messages a service handles by using filters. The Selective Consumer Router works on inbound endpoints to control which messages that service will process. The Filtering Router works on outbound endpoints to control which messages the service sends along to the next endpoint. You can use a combination of these approaches to control the message flow. For example, if you only want to process messages that don't have errors, you can use a selective consumer to ensure that only those with the result code success are processed. You can then use a Catch-all Strategy to forward all other messages to another endpoint for error handling: <inbound> <selective-consumer-router> <mulexml:jxpath-filter expression="msg/header/resultcode = 'success'"/> </selective-consumer-router> <forwarding-catch-all-strategy> <jms:endpoint topic="error.topic"/> </forwarding-catch-all-strategy> </inbound> If you want the service to process all messages but then want to specify criteria to determine where the message is sent next, you can use filtering outbound routers. In the following example, messages that contain an exception are sent to the system administrator s email address, messages whose payload contains a specific string are sent to the string queue, and all other messages are picked up by the forwarding catch-all router and sent to an error queue: <outbound> <forwarding-catch-all-strategy> <jms:outbound-endpoint queue="error.queue"/> </forwarding-catch-all-strategy> 80 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 5: Advanced Message Routing <filtering-router> <smtp:outbound-endpoint to="ross@muleumo.org"/> <payload-type-filter expectedtype="java.lang.exception"/> </filtering-router> <filtering-router> <jms:outbound-endpoint queue="string.queue"/> <and-filter> <payload-type-filter expectedtype="java.lang.string"/> <regex-filter pattern="the quick brown (.*)"/> </and-filter> </filtering-router> </outbound> Similar routers are the forwarding router, which allows you to process some messages and selectively forward others, and the wiretap router, which allows you to process all messages and send them on as normal but also send a copy to another endpoint. For more information, see the section on inbound routers in the Mule Configuration Guide. Chaining Outbound Endpoints Together Let s assume we have a validation service, and if the message fails validation, the message and its exception are forwarded to another service AND the message and its exception are returned to the caller. You could achieve this using the chaining router, which is a fast and lightweight configuration for sending a message to an endpoint and then sending the result of that endpoint to another endpoint. For example: <chaining-router> <vm:outbound-endpoint path="validationservice" synchronous="true"/> <vm:outbound-endpoint path="validationerror" synchronous="true"> <exception-type-filter expectedtype="java.lang.exception"/> </vm:outbound-endpoint> </chaining-router> You can also use the chaining router to perform protocol bridging to a single outbound endpoint. Unlike the pass-through router, the chaining router always returns a response. For example: Mule Getting Started Guide 81

Lesson 5: Advanced Message Routing Chapter 3 Tutorial <service name="httpproxyservice"> <inbound> <!-- WSDL URL: http://localhost:8888/stockquote.asmx?wsdl --> <inbound-endpoint address="http://localhost:8888" synchronous="true"/> </inbound> <outbound> <chaining-router> <outbound-endpoint address="http://www.webservicex.net#\[header:http.request\]" synchronous="true"/> </chaining-router> </outbound> </service> Splitting Messages A message splitter can be used to break down an outgoing message into parts and dispatch those parts over different endpoints configured on the router. For example, in an order-processing application, you might want to send different parts of the message to different services for processing. You could do this using one of the following routers: List Message Splitter: accepts a list of objects that will be routed to different endpoints. For example: <outbound> <list-message-splitter-router"> <jms:outbound-endpoint queue="order.queue"> <payload-type-filter expectedtype="com.foo.order"/> </jms:outbound-endpoint> <jms:outbound-endpoint queue="item.queue"> <payload-type-filter expectedtype="com.foo.item"/> </jms:outbound-endpoint> </list-message-splitter-router> </outbound> 82 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 5: Advanced Message Routing Filtering XML Message Splitter: similar to the List Message Splitter but operates on XML documents. For example: <outbound> <mulexml:filter-based-splitter splitexpression="root/nodes" validateschema="true" externalschemalocation="/com/example/theschema.xsd"> <vm:outbound-endpoint path="order"> <payload-type-filter expectedtype="com.foo.order"/> </vm:outbound-endpoint> <vm:outbound-endpoint path="item"> <payload-type-filter expectedtype="com.foo.item"/> </vm:outbound-endpoint> </mulexml:filter-based-splitter> </outbound> Expression Splitter Router: similar to the List Message Splitter but splits the message based on an expression that returns one or more message parts. For example: <outbound> <expression-splitter-router evaluator="xpath" expression="/mule:mule/mule:model/mule:service" disableroundrobin="true" failifnomatch="false"> <outbound-endpoint ref="service1"> <expression-filter evaluator="xpath" expression="/mule:service/@name = 'service splitter'"/> </outbound-endpoint> <outbound-endpoint ref="service2"> <expression-filter evaluator="xpath" expression="/mule:service/@name = 'round robin deterministic'"/> </outbound-endpoint> </expression-splitter-router> </outbound> Mule Getting Started Guide 83

Lesson 5: Advanced Message Routing Chapter 3 Tutorial You could also split a message into parts to improve performance. The Round Robin Message Splitter splits the message into parts and sends them to endpoints in a round-robin approach. The Message Chunking Router splits a single message into a number of fixed-length messages that will all be routed to the same endpoint. After splitting messages, you use the Message Chunking Aggregator to aggregate the message parts back together again. The aggregator uses the correlation ID, which is set by the outbound router, to identify which parts belong to the same message. <inbound> <message-chunking-aggregator-router> <expression-message-info-mapping correlationidexpression="#[header:correlation]"/> <payload-type-filter expectedtype="org.foo.some.object"/> </message-chunking-aggregator-router> </inbound> Processing a Message Only Once The Idempotent Receiver ensures that only unique messages are received by a service by checking the unique message ID of the incoming message. The ID can be generated from the message using an expression defined in the idexpression attribute. By default, the expression used is #[message:id], which means the underlying endpoint must support unique message IDs for this to work. In the following example, a unique ID is a combination of the message ID and the contents of the label field in the header, and the IDs are then written to a simple text file to keep track of which messages have already been processed: <inbound> <idempotent-receiver-router idexpression="#[message:id]-#[header:label]"> <simple-text-file-store directory="./idempotent"/> </idempotent-receiver-router> </inbound> 84 Mule Getting Started Guide

Chapter 3 Tutorial Lesson 5: Advanced Message Routing Summary This lesson provided a sampling of some of the routers you can use to control how messages are processed and routed. For complete information on message routers, see the chapter on using message routers in the Mule Configuration Guide. To see additional examples, such as the Stock Quote Example, which illustrates how to add a proxy service, and the Bookstore Example, which illustrates using CXF, see the Examples page at http://www.mulesource.org/x/wam7. The Mule Cookbook (http://www.mulesource.org/x/dgi7) provides additional code snippets and examples that users and Mule developers have submitted. For more information on all topics related to configuring and using Mule, see the Mule Configuration Guide. Mule Getting Started Guide 85

Chapter 4 Using Mule IDE This chapter describes how to use Mule IDE. If you have not already downloaded, installed, and configured Mule IDE, see Installing and Configuring Mule IDE on page 43. It contains the following sections: Creating a New Mule Project on page 86 Creating a New Mule Configuration File on page 88 Testing the Application on page 89 Debugging the Application on page 93 Switching Mule Distributions on page 93 Creating a New Mule Project The Mule Project wizard creates a new Java project configured with libraries from your Mule distribution. The wizard also allows you to copy project source files from several of the examples in the Mule distribution into a new project. To create a new Mule project 1 Choose File > New > Project, expand the Mule folder and select Mule Project, and then click Next. 2 Enter a name for the project, ensuring that there is no space in the project name. If you want to put the project in a location other than the default workspace, clear the Use default location check box and specify a new file location. 3 Do one of the following: To use the default Mule distribution you configured, leave Use default Mule distribution selected. If you want to specify a non-default Mule distribution, select if from the drop-down list. Mule Getting Started Guide 86

Chapter 4 Using Mule IDE Creating a New Mule Project If you want to use a new Mule distribution, click Configure Default..., add it to the Mule Distributions list, and then select it from the list. 4 If you want your project to include the source and configuration from one of the Mule example applications, click Add sample project content and select the example you want to use. Note that not all of the examples that ship with Mule are supported. 5 Click Next, and then click the Libraries tab and verify that the Java 5 or later library is installed and available on the build path. 6 Click Finish to have Mule IDE generate your project. Mule Getting Started Guide 87

Creating a New Mule Configuration File Chapter 4 Using Mule IDE The project is added to the Package Explorer pane. The Mule libraries from the distribution you selected are contained in the project. If you selected an example, the source and configuration from that example are also in the project. Creating a New Mule Configuration File Mule IDE makes it very easy to create a new Mule configuration file. To create a new Mule configuration file: 1 Choose File > New > Other, expand the Mule folder and select Mule Configuration, and then click Next. 2 Click Browse..., expand the project in which you're creating the file, select the conf directory, and then click OK. 3 Change the default name from mule-config.xml to a unique name in the File Name box. Warning Make sure you use a unique name. If you specify the name of an existing file, the new file you are creating will overwrite the existing file. 4 Select each of the Mule modules or transports you want to include in your configuration. Mule IDE will prepopulate the namespace declarations based on your selections. Note that the Mule core namespace will be populated by default and does not need to be selected. If you want to include a custom module or transport or one from MuleForge, simply add its JAR file to the \lib\user sub-directory under the Mule home directory. As long as the JAR includes a Spring-based schema file, Mule IDE will include it in the list. 5 Click Finish. 88 Mule Getting Started Guide

Chapter 4 Using Mule IDE Testing the Application Mule IDE creates the configuration file in the conf directory of the project you selected. The namespaces are populated based on the transports and modules you selected and the distribution version of your project. Testing the Application Mule IDE allows you to run a Mule server using a specific configuration file, making it easy to test and debug your application. If you have multiple configuration files, you must create a run configuration manually. If you have only one configuration file, the run configuration can be created automatically. Mule Getting Started Guide 89

Testing the Application Chapter 4 Using Mule IDE To create a new run configuration manually: 1 Choose Run > Run Configurations in Eclipse Ganymede or Run > Open Run Dialog in Eclipse Europa. 2 Click Local Mule Server, and then click New. 3 Enter a name for the configuration you re creating. 4 Specify the project that contains the Mule configuration files you want to test. 5 Click Add and select one or more Mule configuration files in the project. 6 If you want to use a different Mule distribution for the configuration, select Use a project specific Mule distribution and select the distribution to use. 7 Click the Arguments tab, and then enter any additional arguments or properties you need to pass to the JVM using -M-DPropertyName=PropertyValue just as you would if you were passing parameters in at the command line. 90 Mule Getting Started Guide

Chapter 4 Using Mule IDE Testing the Application 8 Click Apply. You can now click Run to launch the Mule server and test this configuration immediately, or run this configuration at a later time. Mule Getting Started Guide 91

Testing the Application Chapter 4 Using Mule IDE To create a run configuration automatically 1 In the Package Explorer, right-click the configuration file. 2 Choose Run As > Mule Server. If a launch configuration exists that contains the selected Mule configuration file, it is used to launch a Mule server. Otherwise, a new run configuration is created automatically and the server is started. If multiple run configurations already exist that contain the selected Mule configuration file, you are prompted to choose which one to use. 92 Mule Getting Started Guide

Chapter 4 Using Mule IDE Debugging the Application If your application requires multiple configuration files, you must create the run configuration manually as described on page 90. Debugging the Application To debug your application, you set breakpoints as you would normally in Eclipse and follow the same steps as described in Testing the Application on page 89 with the exception that you choose Debug As... instead of Run As... Note that Mule IDE does not automatically associate the Mule source code with your project, only the libraries from the selected distribution. Switching Mule Distributions It is possible to switch your distribution of Mule for an existing project. Select the Mule Libraries entry in your project and choose File > Properties. In the next dialog, you can switch between the Mule installations you have configured. If you want to use a new version of Mule, we recommend that instead of switching the Mule distribution for your existing project, you should create a new project using the new Mule distribution. If you have created custom modules or transports, you must copy them from the previous Mule distribution to the \lib\user sub-directory in the new distribution. Likewise, you should carefully read the migration page for the new version and follow the instructions for migrating your configuration and Java files as needed for the new version, including specifying the new schema version number in the namespace declarations if you are upgrading to a new major point release (e.g., 2.1 to 2.2). Mule Getting Started Guide 93

Appendix A Distribution Contents The Mule distribution contains the following directories and files: /bin /conf /docs /examples /lib/boot /lib/endorsed /lib/mule /lib/opt /lib/user /licences /logs /sbin /src LICENSE.txt README.txt or README.pdf Shell and batch scripts for controlling Mule from the command line Configuration files API documentation (Javadoc) for Mule and its sub-projects Example applications you can run and try building yourself Libraries used by the Java Service Wrapper to boot the server Endorsed Java libraries used by Mule Mule libraries Third-party libraries Your custom classes and libraries. This directory comes before /lib/mule on the classpath and can therefore be used to patch the distributed Mule classes if necessary. License information for all libraries shipped with Mule Log file output when running in background mode Internal scripts (not to be run by the user) The source code for all Mule modules. You can import this into your IDE License agreement for Mule The Getting Started document Mule Getting Started Guide 94

Appendix B Third-party Software Mule products include the following third-party software as part of the source code, examples, or as dependencies. The license type for each third-party software product is indicated in parentheses. Some components of Mule Enterprise may also contain other software that is commercially licensed. For more information, contact MuleSoft. Third-party Software Software License Acegi Apache 2.0 Antlr AOP Alliance BSD Style Public Domain Apache Axis Apache 2.0 Apache Axis Jaxrpc Apache2.0 Apache Catalina Apache 2.0 Apache Cocoon Project Apache 2.0 Apache Commons Attributes Apache 2.0 Apache Commons Beanutils Apache 2.0 Apache Commons-cli Apache 1.1 Apache Commons Codec Apache 2.0 Apache Commons Collections Apache 2.0 Apache Commons DBUtils Apache 2.0 Apache Commons Discovery Apache 2.0 Apache Commons IO Apache 2.0 95 Mule Getting Started Guide

Appendix B Third-party Software Third-party Software (Continued) Software Apache Commons JXPath Apache 2.0 Apache Commons Lang Apache 2.0 Apache Commons Logging Apache 2.0 Apache Commons Net Apache 2.0 Apache Commons Pool Apache 2.0 Apache CXF Apache 2.0 Apache Derby Apache 2.0 Apache Geronimo Apache 2.0 Apache Jakarta Commons Transaction Source Apache 2.0 Apache Maven Apache 2.0 Apache Tomcat Utility Apache 2.0 Apache Velocity Apache 2.0 Apache WebServices Commons Apache 2.0 Apache Web Services Axis Apache 2.0 Apache Web Services Project (Wss4j) Apache 2.0 Apache Xalan Apache 2.0 Apache Xerces Apache 2. Apache XML Resolver Apache 2.0 Apache XML Schema Apache 2.0 Apache XML Security Apache 2.0 Apache XML Serializer Apache 2.0 Apache Xpath Apache 2.0 ASM Bundled with CGLIB License BSD ApsectJ EPL 1.0 96 Mule Getting Started Guide

Appendix B Third-party Software Third-party Software (Continued) Software Axis-Saaj Project Apache 2.0 Axis/Web Services Apache 2.0 Backport-util-concurrent BeanShell LGPL 2.1 Bouncy Castle Java Cryptography APIs c3p0: JDBC DataSources/Resource Pools LGPL 2.1 CAROL: Common Architecture for ObjectWeb Creative Commons Public Domain Bouncy Castle License LGPL 2.1 CGLIB Apache 2.0 Content Repository for Java (JCR) Cryptix Cryptix OpenPGP Dom4j DTDParser referenced by Linguine Maps Day Software AG License Cryptix General License Cryptix General License BSD Apache Style Fast Infoset Apache 2.0 Groovy Apache 2.0 Hibernate LGPL 2.1 Howl-logger iharder Base64 BSD IzPack Apache 2.0 Jakarta Commons HttpClient Apache 2.0 Jakarta-Oro Apache 1.1 Java Architecture for XML Binding (JAXB) CDDL 1.0 Java API for XML Web Services (JAX-WS) CDDL 1.0 Java Scripting API License Public Domain/Permissive Sun BCLA Mule Getting Started Guide 97

Appendix B Third-party Software Third-party Software (Continued) Software Java Service Wrapper Java UUID Generator Apache 2.0 Javaassist MPL 1.1 JavaBeans Activation Framework 1.1 JavaDoc for JNDI Container Implementation Tanuki Software/Silver Egg Technology Sun BCLA BSD JavaMail CDDL 1.0 Jaxen JBoss Business Process Management (jbpm) BSD style license LGPL 2.1 JBoss Transactions LGPL 2.1 JDOM BSD style license Jetty 6.1.11 Apache 2.0 Jruby JUnit CPL 1.0 Jython License CPL/GPL/LGPL Python License Linguine Maps LGPL 2.1 Log4j Apache 2.0 Mockobjects Apache 2.0 Mx4j MX4J License 1.0 Neethi Apache 2.0 OGNL OpenSymphony Software License 1.1 OpenSAML Apache 1.1 Propertyset OpenSymphony Software License 1.1 Quartz Apache 2.0 98 Mule Getting Started Guide

Appendix B Third-party Software Third-party Software (Continued) Software Retrotranslator BSD SAAJ Dual license consisting of the CDDL 1.0 and GPL 2.0 Saxon-B MPL 1.1 Servlet Specification CDDL 1.0 Simple Logging Facade for Java (SLF4J) MIT Style Smack Apache 2.0 Spring Framework/Modules Apache 2.0 StaX Apache 2.0 Sun JNDI Sun BCLA SXC Apache 2.0 Truelicense Apache 2.0 TrueXML Apache 2.0 Web Services Description Language for Java (wsdl4j) CPL 1.0 WoodSToX XML Processor Apache 2.0 WSS4J Apache 2.0 XAPool LGPL 2.1 XMLUnit XPP3 XStream YourKit Java Profiler License BSD style Indiana University Extreme! Lab Software License BSD Commercial Mule Getting Started Guide 99

Glossary Following are the terms you ll see as you work with Mule. Because of the dynamic open-source history of Mule, there are sometimes multiple terms used to describe the same thing. This glossary lists all terms but refers to the preferred term when there are synonyms. agent A service such as the Mule JMX agent that is used by or associated with Mule but is not a Mule-managed service component. An agent is registered with the Mule Manager and has the same lifecycle as the Mule instance, so you can initialize and destroy resources when the Mule instance starts or stops. channel A logical pathway on which messages are sent on a messaging framework. component See service component configuration builder A class that knows how to parse a given configuration file. The default configuration builder is the org.mule.config.mulexmlconfigurationbuilder class that knows how to parse a Mule XML configuration file. connector The heart of a transport that maintains the configuration and state for the transport. Mule Getting Started Guide 100

Glossary endpoint A configuration entity specifying how and where a message should be routed. The endpoint is configured in an inbound or outbound router and specifies where the message should be sent or from where it should be received, using which transport (and optionally which connector in that transport), and which filters should be applied before routing the message. Endpoints can also be defined globally instead of in a specific router,. Enterprise Service Bus (ESB) An architecture that allows different applications to communicate with each other by acting as a transit system for carrying data between applications within or outside your intranet. An ESB provides transaction management, routing, security, and other functionality for the messages. event See message filter Specifies logic for determining which messages are routed to a component. You can set filters on an inbound router to filter which messages that service component can receive, or you can set filters on an outbound router to indicate how you want to route messages after they have been processed by the service component. Galaxy See Mule Service Registry HQ See Mule Management Console inbound router A Java class that you configure in the Mule configuration file to determine how a service component will receive messages. The inbound router includes an endpoint that indicates where the messages will come from. Mule Getting Started Guide 101

Glossary interceptor A Java class that is used to intercept message flow into a service component. An interceptor can be used to trigger or monitor events or interrupt the flow of the message. management console See Mule Management Console message A packet of data that can be handled and sent between applications on a specific channel. Data is always wrapped in a message before it is transported by Mule. A message has a header, which contains metadata about the message (such as the sender information), and the body, which contains the actual data. message receiver A Java class used by a connector to read the incoming data, package it as a message, and passes it to a service component s inbound router. The message receiver can use a transformer if necessary to convert the data. message dispatcher A Java class used by a connector to receive the messages and routing instructions from an outbound router and send the message to the next service component. Mule community release The open-source version of Mule, available for free download at http://mule.mulesource.org/display/mule/download. As its name suggest, the community release is developed, tested, and maintained by the community. Mule Enterprise The enterprise version of Mule, available for 30-day trial download from http://www.mulesource.com/download. Mule Enterprise includes full development cycles, testing, technical support, maintenance releases and hot fixes, and management and monitoring tools from MuleSoft. If you are deploying Mule in a mission-critical 102 Mule Getting Started Guide

Glossary environment, want to ensure that you always have a stable, high-quality release, and want additional tools for managing and monitoring your deployment, you should purchase a subscription of Mule Enterprise. Mule Management Console A monitoring and management system that provides information about the hardware, services, and applications in your entire enterprise, including CPU usage and information about disks and network devices. The management console (formerly Mule HQ) provides integrated log, configuration, and server event tracking. It can detect Mule servers and associated software and hardware, and report real-time and historical details of events. The management console is available with Mule Enterprise Edition only but can monitor both Community Edition and Enterprise Edition instances of Mule 2.x servers (to monitor Mule 1.x, download the previous release, Mule HQ 3.5). The management console fully supports standalone Mule deployments and provides some monitoring data for embedded Mule instances. Mule Manager Manages the Mule objects, including connectors, endpoints, and transformers. The Mule Manager constructs these objects and provides them to the service components in the Mule Model. Each Mule instance has one Mule Manager and one or more Mule Models. Mule Model A service container that hosts the service components and manages their runtime behavior. Mule Service Registry Provides a full complement of registry and repository features, including service and artifact management, governance, and lifecycle and dependency management. The service registry is based on the open-source Mule Galaxy project, which can be used with the community edition of Mule ESB. Mule Getting Started Guide 103

Glossary outbound router A Java class that you configure in the Mule configuration file to determine how a service component will dispatch messages. The outbound router can include an endpoint to indicate where the messages should go next, or if no endpoint is configured, it returns the completed message back to the sender. POJO An acronym for plain old Java object, a POJO is a simple Java object, not an enterprise JavaBean. One advantage of Mule is that your service components can be simple POJOs, which Mule then wraps and exposes as services. provider See transport queue See channel router A Java class that determines where and how messages are transported between applications. See also inbound router and outbound router SEDA See Staged Event-driven Architecture (SEDA) service component A POJO, Spring bean, Java bean, or web service containing the business logic for processing data in a specific way. Mule simply manages the service component, bundles it with configuration settings and exposes it as a service, and ensures that the right information is passed to and from it based on the settings you specified for the service in the Mule configuration file. In early versions of Mule, service components were called Universal Message Objects, and UMO is still part of the nomenclature in the Mule APIs today. 104 Mule Getting Started Guide

Glossary service registry See Mule Service Registry Staged Event-driven Architecture (SEDA) An architecture model where applications consist of a network of event-driven stages connected by explicit queues. This architecture allows services to be well-conditioned to load, preventing resources from being overcommitted when demand exceeds service capacity. As a result, SEDA provides an efficient event-based queuing model that maximizes performance and throughput. SEDA is the default processing model in Mule. transformer A Java class that transforms message payloads (data) to and from different types. transport A construct that handles and carries messages on a specific messaging protocol, such as HTTP, moving the message from one service component to another and transforming the data as needed along the way transport provider See transport universal message object (UMO) See service component UMO See service component Wire Tap A router that makes copies of messages and forwards them to another endpoint. It can either forward a copy of all messages that it receives or it can be configured to use a filter and send a sub-set of these messages only. This router will not prevent messages from being delivered to service components. See also interceptor. Mule Getting Started Guide 105

Index A ActiveMQ 29 adapters 12 administrator what to read in this guide 7 aggregating messages 15 ANT_HOME environment variable 33 Apache CXF 29 application developer what to read in this guide 7 application layer 47 applications creating manually 54 creating with Mule IDE 51 modifying 60 architect what to read in this guide 7 architecture about 12 asynchronous message style 76 asynchronous reply routers 75 asynchronous request-response message style 78 audience for this guide 6 B basic usage 47 building Mule 31 business analyst what to read in this guide 7 business logic in the Mule architecture 13 C catch-all strategies 75 chaining routers 15 channels about 11 CIO what to read in this guide 7 client/server topology 21 community release about 31 installing 36 compression tools 31 configuring endpoints 18 configuring Mule tutorial 54 configuring routers 18 CXF 29 D data 15 logical flow in Mule 18 processing 13 debugging applications 93 decision makers what to read in this guide 7 destinations see endpoints developer what to read in this guide 7 developer release 31 director of Software Architecture what to read in this guide 7 dispatching messages 15 distributed topology 22 Tcat Server User s Guide 65

Index documentation typographic conventions 8 downloading Mule about 30 E Eclipse 38 EJB 21 endorsing the JDK 44 endpoints about 17 configuring 18 Enterprise edition about 31 Enterprise Integration Patterns about 12 Enterprise Service Bus (ESB) 10, 12 enterprise service network 21 ESB see Enterprise Service Bus examples 51 exercises 51 F failover distributing Mule for 22 file systems 21 filtering messages 15 in endpoints 18 filters 75 G GZip 31 H hub-and-spoke topology 21 I IBM WebSphere MQ 21 implementing Mule 21 J inbound routers 75 about 14 installing Mule about 30 community release 36 Enterprise 35 snapshot release 36 installing multiple Mule instances 37 integrating applications with endpoints 17 integration developer what to read in this guide 7 integration layer 47 introduction to Mule 9 IT manager what to read in this guide 7 Java beans creating service components from 14 Java Developer Kit (JDK) 32 JAVA_HOME environment variable 33 JAXP 44 JDK 32 JMS in ESBs 21 K knowledge base 8 L learning to use Mule 51 load-balancing distributing Mule for 22 logical data flow in Mule 18 M mainframe applications 21 Maven 33 MAVEN_HOME environment variable 33 message routing 75 66 Tcat Server User s Guide

Index message styles 75 messages about 11 aggregating 15 dispatching 15 filtering 15 payload 15 protocols 15 receiving 14 resequencing 15 routing 14 messaging framework about 11 MSMQ 21 Mule architecture about 12 Mule community release 31 Mule configuration file. 88 Mule Enterprise 31 installing 35 Mule IDE 86 tutorial 51 Mule snapshot release 31 Mule User Guide 30 MULE_BASE environment variable 38 MULE_HOME environment variable 34, 38 MuleSoft Technical Support 8 multiple instances installing 37 multiple instances of Mule 22 O operating systems 32 outbound router about 14 outbound routers 75 P PATH environment variable 34 payload 15 peer network topology 21 pipeline topology 21 plain old Java object (POJO) about 11 platforms 32 POJO about 11 programmer what to read in this guide 7 protocols 15 Q queues about 11 quick start 7 R receiving messages 14 request-response message style 76 resequencing messages 15 routers about 14 chaining 15 configuring 18 routing messages 14 RSS feed service components and 15 S scalability of mule 21 sending messages 14 service components about 14 routing messages between 14 service-oriented architecture about 13 services about 13 setup_local_instance script 37 snapshot release 31 installing 36 SOA see service-oriented architecture sockets 21 Tcat Server User s Guide 67

Index source code 31 spaces in the target path 34 Spring beans creating service components from 14 support 8 Synchronous message style 77 Xerces 44 X-Windows downloading without 37 T technical support 8 testing applications 89 TIBCO Rendezvous 21 topologies 21 transformers about 15 transport layer 47 transports about 15 configuring endpoints for 17 tutorial 51 typographic conventions 8 U uniform resource indicators (URI) in endpoints 17 URIs in endpoints 17 V versions switching 93 W web services creating service components from 14 WinZip 31 X Xalan, JDK endorsing 44 68 Tcat Server User s Guide

30 Maiden Lane Suite 500 San Francisco, CA 94108 Phone: 877-MULE-OSS (877-685-3677) Fax: 415-227-0842 www.mulesoft.com