JBoss Enterprise SOA Platform 5

ESB Programmers Guide

This guide is for software engineers.

Edition 5.3.1

David Le Sage

Red Hat Engineering Content Services

B Long

Red Hat Engineering Content Services

Darrin Mison

Legal Notice

Copyright © 2013 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.


This reference document contains information about programming with the JBoss Enterprise SOA Platform product.
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. Give us Feedback
1. Preface
1.1. Business Integration
1.2. What is a Service-Oriented Architecture?
1.3. Key Points of a Service-Oriented Architecture
1.4. What is the JBoss Enterprise SOA Platform?
1.5. The Service-Oriented Architecture Paradigm
1.6. Core and Components
1.7. Components of the JBoss Enterprise SOA Platform
1.8. JBoss Enterprise SOA Platform Features
1.9. Features of the JBoss Enterprise SOA Platform's JBossESB Component
1.10. Task Management
1.11. Integration Use Case
1.12. Utilising the JBoss Enterprise SOA Platform in a Business Environment
I. Introduction
2. Preliminaries
2.1. Intended Audience
2.2. Aim of This Book
2.3. Back Up Your Data
2.4. Red Hat Documentation Site
2.5. Variable Name: SOA_ROOT Directory
2.6. Variable Name: PROFILE
3. Introducing the JBoss Enterprise SOA Platform
3.1. Enterprise Service Bus
3.2. Core Components of the Enterprise Service Bus
3.3. Integration Between EDS and the JBoss Enterprise SOA Platform
3.4. Enterprise Data Services Overview
3.5. Developing with Enterprise Data Services
II. Theory
4. Services and Messages
4.1. Services
4.1.1. Service
4.1.2. Action Pipeline
4.1.3. ESB-Awareness
4.1.4. Message Listeners
4.1.5. ServiceInvoker
4.1.6. InVM Transport
4.1.7. Creating Your First Service
4.1.8. Types of Message Listener
4.1.9. Gateway Listener
4.1.10. Adding a Gateway Listener to a Service
4.2. Messages
4.2.1. ESB Message
4.2.2. Components of an ESB Message
4.2.3. How Message Objects are Sent to the Queue
4.2.4. Message Interface
4.2.5. Message Header
4.2.6. Message Header Format
4.2.7. The To Field
4.2.8. Message Context
4.2.9. Message Body
4.2.10. Message Payload
4.2.11. Serialize
4.2.12. Message Body Format
4.2.13. Message Fault
4.2.14. Fault Message Format
4.2.15. Message Properties
4.2.16. Message Attachment
4.2.17. Message Attachment Interface
4.2.18. Choosing the Right Method
4.2.19. Advice on Adding Data to the Body of a Message
4.2.20. Configure for Legacy Message Payload Exchange
4.2.21. Extensions to the Message Body
4.2.22. End-Point Reference
4.2.23. Logical EPR
4.2.24. Logical EPR Use
4.2.25. FaultTo Field
4.2.26. Dead Letter Queue
4.2.27. ReplyTo Field
4.2.28. Table of ReplyTo Field Settings
4.2.29. Advice on Serializing Messages
4.2.30. Change the Default Message Type
4.2.31. Register a Marshaling Plug-In
III. Developing
5. Building and Using Services
5.1. Message Listener Configuration Properties
5.2. Characteristics of Filesystem Gateway Listeners
5.3. Pipeline Interceptor
5.4. Working with Pipeline Interceptors
5.5. Routers
5.6. Router Configuration
5.7. Content-Based Router
5.8. Static-Based Router
5.9. Notifier
5.10. ServiceInvoker
5.11. Developing with the ServiceInvoker
5.12. RegistryException
5.13. FaultMessageException
5.14. MessageDeliverException
5.15. Java Message Service
5.16. JMS Transacted Session
5.17. IncompatibleTransactionScopeException
5.18. InVM
5.18.1. InVM Transport
5.18.2. InVM Limitations
5.18.3. Developing with the InVM
5.18.4. Set an InVM Scope for an Individual Service
5.18.5. Set the Default InVM Scope for a Deployment
5.18.6. Change the Number of Listener Threads Associated with an InVM Transport
5.18.7. Lock-Step Delivery
5.18.8. Lock-Step Delivery Settings
5.19. Load Balancing
5.19.1. Load Balancing
5.19.2. Configure a Load-Balancing Policy
5.19.3. Load Balancing Policies
5.20. Service Contract Definition
5.20.1. Service Contract
5.20.2. Declaring Service Contract Schemas
5.20.3. Message Validation
5.21. Exposing ESB Services via Web Service End-Points
5.21.1. Exposing ESB Services via Web Service End-points
6. Other Components
6.1. Message Store
6.2. Smooks
6.3. Visitor Logic in Smooks
6.4. Data Transformation
6.5. Content-Based Router
6.6. Content Based Routing Using the JBoss Rules Engine
6.7. Service Registry
6.8. jUDDI Registry
6.9. jUDDI and the JBoss Enterprise SOA Platform
7. Tutorial on Developing Messages
7.1. Overview
7.2. Message Structure
7.3. Developing the Service
7.4. Decode the Payload
7.5. Construct the Client
7.6. Configuring a Remote Service Invoker
7.7. Start the JBoss Enterprise SOA Platform
7.8. Deploy the "Hello World" Quickstart on Your Test Server
7.9. Test the Configuration of the Remote Client
7.10. Verify That a Remote Client's Configuration is Correct
7.11. Further Advice for When Building Clients and Services
8. Advanced Topics
8.1. Node
8.2. The Bus
8.3. Delivery Channel
8.4. Run the Same Service on More than One Node in a Cluster
8.5. Remove Failed End-Point References from the Registry
8.6. How Services Work
8.7. Application Service
8.8. How Service Replication Works
8.9. JBossMessaging
8.10. Cluster
8.11. Stateless Service Failover
8.12. Enable JMS Clustering
8.13. Protocol Clustering
8.14. Running the Same Service Across Different Nodes in a Cluster
8.15. Configure the Registry Cache Time-Out Value
8.16. Channel Fail-Over
8.17. Deactivate Automatic Fail-Over
8.18. Load Balancing
8.19. Configure a Load-Balancing Policy
8.20. Load Balancing Policies
8.21. Transactions and the Action Pipeline
8.22. Rollbacks
8.23. Rollbacks and the JMS JCA Listener
8.24. Message Re-delivery
8.25. Scheduling
8.25.1. Quartz Scheduler
8.25.2. Configuring Quartz Scheduler
8.25.3. Scheduling Services
8.25.4. Simple Schedule
8.25.5. Cron Schedule
8.25.6. Scheduled Listener
8.25.7. Sample Configuration Combining the Scheduled Listener and Cron Scheduler
9. Fault Tolerance and Reliability
9.1. System Reliability
9.2. Fault Tolerance
9.3. Dependability
9.4. Message Loss
9.5. Failed End-Points
9.6. Supported Crash Recovery Modes
9.7. Message Failure, Component by Component
9.8. Ways in Which You Can Minimize the Risk of Failures
10. Defining Service Configurations
10.1. Introduction to Configuring the Product
10.2. Providers
10.3. Types of Providers
10.4. Services
10.5. Attributes of a Service
10.6. Attributes of a Listener
10.7. Actions
10.8. Attributes of an Action
10.9. Implementing a Transport-Specific Configuration
10.10. Configuring the File System Provider
10.11. Configuring an FTP Provider
10.12. UDP Gateway
10.13. Configuring the UDP Gateway
10.14. JBoss Remoting Gateway
10.15. Configuring the JBoss Remoting Gateway
10.16. HTTP Gateway
10.17. Configuring the HTTP Gateway
10.18. Securing the HTTP Gateway
10.19. Secure the HTTP Gateway
10.20. Further HTTP Gateway Security
10.21. Apache Camel
10.22. Camel Gateway
10.23. Configuring the Camel Gateway
10.24. Transitioning from the Old Configuration Model to the New
10.25. Configuring the Enterprise Service Bus
11. Data Decoding: Mime Decoders
11.1. Message Composer
11.2. Mime Decoder
11.3. Implement a Mime Decoder
11.4. ConfigTree
11.5. Mime Decoder Implementations Available Out-of-the-Box
11.6. Using Mime Decoders in Gateway Implementations
12. Web Services Support
12.1. JBoss Web Services
12.2. JBoss Web Services Support
13. Actions Available for Use Out of the Box
13.1. Out-of-the-Box Actions
13.2. JBoss Enterprise SOA Platform Out-of-the-Box Actions
13.3. Transformer Actions
13.3.1. Transformers
13.3.2. ByteArrayToString
13.3.3. LongToDateConverter
13.3.4. ObjectInvoke
13.3.5. ObjectToCSVString
13.3.6. ObjectToXStream
13.3.7. XStreamToObject
13.3.8. XsltAction
13.3.9. Validating XsltActions
13.3.10. Smooks
13.3.11. Using Smooks
13.3.12. SmooksTransformer
13.3.13. SmooksAction
13.3.14. Use SmooksAction to Process XML, EDI, CSV and "Other Type" Message Payloads
13.3.15. Specifying the SmooksAction Result Type
13.3.16. PersistAction
13.4. Business Process Management Actions
13.4.1. jBPM
13.4.2. JBPM Integration
13.4.3. jBPM BpmProcessor
13.5. Scripting Actions
13.5.1. Scripting Actions
13.5.2. Groovy
13.5.3. GroovyActionProcessor
13.5.4. Bean Scripting Framework (BSF)
13.5.5. ScriptingAction
13.6. Service Actions
13.6.1. Service Actions
13.6.2. EJBProcessor
13.7. Routing Actions
13.7.1. Routing Actions
13.7.2. Aggregator
13.7.3. Streaming Aggregator
13.7.4. EchoRouter
13.7.5. HttpRouter
13.7.6. Java Message Service
13.7.7. JMSRouter
13.7.8. EmailRouter
13.7.9. Content-Based Router
13.7.10. The RegexProvider
13.7.11. XPath Domain-Specific Language
13.7.12. ContentBasedRouter
13.7.13. StaticRouter
13.7.14. SyncServiceInvoker
13.7.15. StaticWireTap
13.7.16. E.-Mail WireTap
13.8. Notifier Actions
13.8.1. Notifier Action
13.8.2. Notifier
13.8.3. NotifyConsole
13.8.4. NotifyFiles
13.8.5. NotifySqlTable
13.8.6. NotifyQueues
13.8.7. NotifyTopics
13.8.8. NotifyEmail
13.8.9. NotifyFTP
13.8.10. NotifyFTPList
13.8.11. NotifyTCP
13.9. SOAP Client Actions
13.9.1. Simple Object Access Protocol (SOAP)
13.9.2. SOAPProcessor
13.9.3. SOAPProcessor Action Configuration
13.9.4. Use the SOAPProcessor Action
13.9.5. SOAPClient
13.9.6. Object Graph Navigation Library (OGNL)
13.9.7. Using the Object Graph Navigation Library
13.9.8. SOAP Operation Parameters
13.9.9. Specify an End-Point Operation for the SOAPClient Action
13.9.10. Dealing with SOAP Response Messages
13.9.11. Use XStream to Populate an Object Graph
13.9.12. Extract SOAP response data to an OGNL Keyed Map
13.9.13. HttpClient
13.9.14. Configuring the HttpClient
13.9.15. Specify the HttpClientFactory Configuration on the SOAPClient
13.9.16. Configure the HttpClient Directly in the Action Configuration
13.9.17. SOAPProxy
13.9.18. Using the SOAPProxy Action
13.10. Miscellaneous Actions
13.10.1. SystemPrintln
13.10.2. Using SystemPrintln
13.10.3. SchemaValidationAction
13.10.4. Using SchemaValidationAction
13.10.5. ServiceLoggerAction
13.10.6. Using the ServiceLoggerAction
14. Developing Your Own Actions
14.1. Developing Custom Actions
14.2. Configuring an Action by Setting Properties for It
14.3. Reflection
14.4. Managed Lifecycle
14.5. Life-cycle Action
14.6. ActionLifecycle
14.7. ActionPipelineProcessor
14.8. Implementing ActionLifecycle and ActionPipelineProcessor
14.9. Java Bean Action
14.10. Configuring a Java Bean Action
14.11. Annotated Action
14.12. Using Annotations
14.13. Legacy Action
14.14. Behaviour and Attributes of a Legacy Action
15. Gateways and Connectors
15.1. Introduction to Gateways and Connectors
15.2. Gateways
15.2.1. Gateway Listener
15.2.2. Differences Between a Gateway Listener and a Normal Listener
15.2.3. Gateway Data Mappings
15.2.4. Changing Gateway Data Mappings
15.3. Connectors
15.3.1. Java Connector Architecture (JCA)
15.3.2. Connecting via JCA
15.3.3. Configuring a JCA Inflow Gateway
15.3.4. Mapping Standard Activation Properties
16. JAXB Annotation Introductions
16.1. JAXB Annotation Introductions
16.2. Using JAXB Annotation Introductions
16.3. Writing JAXB Annotation Introduction Configurations
A. Revision History