Programmers Guide Your guide to developing for the JBoss ESB by JBoss ESB Development Team with Community Contributions 1. The Enterprise Service Bus ......................................................................................... 1 1.1. What is an ESB? ................................................................................................ 1 1.2. When would you use JBossESB? ........................................................................ 2 2. JBossESB .................................................................................................................... 7 2.1. Rosetta .............................................................................................................. 7 2.2. The core of JBossESB in a nutshell ..................................................................... 8 3. Services and Messages ............................................................................................. 11 3.1. The Service ...................................................................................................... 11 3.2. The Message .................................................................................................... 13 3.3. Getting and Setting Data on the Message Body .................................................. 19 3.4. Extensions to Body ........................................................................................... 20 3.5. The Message Header ........................................................................................ 21 3.6. LogicalEPR ....................................................................................................... 24 3.7. Default FaultTo ................................................................................................. 24 3.8. Default ReplyTo ................................................................................................ 24 3.9. The Message payload ....................................................................................... 25 3.10. The MessageFactory ....................................................................................... 26 3.11. Message Formats ........................................................................................... 28 4. Building and Using Services ..................................................................................... 31 4.1. Listeners, Routers/Notifiers and Actions ............................................................. 31 4.1.1. Listeners ................................................................................................ 31 4.1.2. Routers .................................................................................................. 31 4.1.3. Notifiers ................................................................................................. 32 4.1.4. Actions and Messages ........................................................................... 36 4.1.5. Handling Responses .............................................................................. 36 4.1.6. Error handling when processing actions ................................................... 37 4.2. Meta-Data and Filters ........................................................................................ 38 4.3. Pipeline Interceptors ......................................................................................... 40 4.4. What is a Service? ........................................................................................... 41 4.4.1. ServiceInvoker ....................................................................................... 41 4.4.2. Transactions .......................................................................................... 43 4.4.3. Services and the ServiceInvoker ............................................................. 43 4.4.4. InVM Transport ...................................................................................... 44 4.4.5. InVM Scope ........................................................................................... 44 4.4.6. InVM Transacted .................................................................................... 45 4.4.7. Transaction Semantics ........................................................................... 45 4.4.8. Threading .............................................................................................. 46 4.4.9. Lock-step Delivery .................................................................................. 46 4.4.10. Load Balancing .................................................................................... 47 4.4.11. Pass-by-Value/Pass-by-Reference ......................................................... 47 4.5. Service Contract Definition ................................................................................ 48 4.6. Message validation ........................................................................................... 48 4.7. Exposing an ESB service as a webservice ......................................................... 49 5. Other Components .................................................................................................... 51 iii Programmers Guide 5.1. The Message Store .......................................................................................... 51 5.2. Data Transformation ......................................................................................... 51 5.3. Content-Based Routing ..................................................................................... 51 5.4. The Registry ..................................................................................................... 52 6. Example ..................................................................................................................... 53 6.1. How to use the Message .................................................................................. 53 6.1.1. The Message Structure .......................................................................... 53 6.1.2. The Service ........................................................................................... 54 6.1.3. Unpicking the payload ............................................................................ 56 6.1.4. The Client .............................................................................................. 56 6.1.5. Configuration for a remote ServiceInvoker ............................................... 57 6.1.6. Sample Client ........................................................................................ 58 6.1.7. Hints and Tips ....................................................................................... 59 7. Advanced Topics ....................................................................................................... 61 7.1. Fail-over and load-balancing support .................................................................. 61 7.1.1. Services, EPRs, listeners and actions ...................................................... 61 7.1.2. Replicated Services ................................................................................ 62 7.1.3. Protocol Clustering ................................................................................. 66 7.1.4. Clustering .............................................................................................. 69 7.1.5. Channel Fail-over and Load Balancing .................................................... 69 7.1.6. Message Redelivery ............................................................................... 71 7.2. Scheduling of Services ...................................................................................... 74 7.2.1. Simple Schedule .................................................................................... 74 7.2.2. Cron Schedule ....................................................................................... 75 7.2.3. Scheduled Listener ................................................................................. 75 7.2.4. Example Configurations .......................................................................... 76 7.2.5. Quartz Scheduler Property Configuration ................................................. 77 8. Fault-tolerance and Reliability ................................................................................... 79 8.1. Failure classification .......................................................................................... 79 8.1.1. JBossESB and the Fault Models ............................................................. 80 8.1.2. Failure Detectors and Failure Suspectors ................................................. 82 8.2. Reliability Guarantees ....................................................................................... 83 8.2.1. Message Loss ........................................................................................ 83 8.2.2. Suspecting Endpoint Failures .................................................................. 84 8.2.3. Supported Crash Failure Modes .............................................................. 85 8.2.4. Component Specifics .............................................................................. 85 8.3. Recommendations ............................................................................................ 85 9. Defining Service Configurations ................................................................................ 89 9.1. Overview .........................................................................................................