JBoss Enterprise SOA Platform 4.

2 SOA ESB Administrators Guide
Your Guide to administering the JBoss ESB for the JBoss Enterprise SOA Platform 4.2.CP05

SOA ESB Administrators Guide

JBoss Enterprise SOA Platform 4.2 SOA ESB Administrators Guide Your Guide to administering the JBoss ESB for the JBoss Enterprise SOA Platform 4.2.CP05 Edition 4.2.5

Copyright © 2010 Red Hat, Inc.. The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. 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. All other trademarks are the property of their respective owners.

The JBoss Enterprise SOA Platform 4.2.CP05 edition of the JBoss ESB Administrators Guide

Preface v 1. Document Conventions ................................................................................................... v 1.1. Typographic Conventions ...................................................................................... v 1.2. Pull-quote Conventions ........................................................................................ vi 1.3. Notes and Warnings ............................................................................................ vii 2. We Need Feedback ....................................................................................................... vii 1. Configuration 1.1. Standalone server ........................................................................................................ 1.2. Clustered ESB Service ................................................................................................. 1.3. JBossESB JMS Providers ............................................................................................. 1.3.1. How can I configure a different JMS provider? .................................................... 1.4. Database Configuration ................................................................................................ 1.5. Switching Databases .................................................................................................... 1.6. Using a JSR-170 Message Store .................................................................................. 1.7. Message Tracing .......................................................................................................... 2. Registry 3. Default ReplyTo EPR 4. ServiceBinding Manager 1 1 1 2 3 5 7 8 9

11 13 15

5. Monitoring and Management 17 5.1. Monitoring and Management Console ........................................................................ 17 5.2. Alerts ......................................................................................................................... 17 6. Hot Deployment 19 6.1. Server mode .............................................................................................................. 19 6.2. Standalone (bootstrap) mode. ..................................................................................... 20 7. Contract Publishing 7.1. Overview .................................................................................................................... 7.2. "Contract" Application ................................................................................................. 7.3. Publishing a Contract from an Action ........................................................................... A. Revision History 21 21 21 22 23

iii

iv .

If not. alternative but equivalent typefaces are displayed. Document Conventions This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. file for files. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. Press Ctrl+Alt+F2 to switch to the first virtual terminal. class names. Mono-spaced Bold Used to highlight system input. Typographic Conventions Four typographic conventions are used to call attention to specific words and phrases. For example: To see the contents of the file my_next_bestselling_novel in your current working directory. check-box and radio button labels. labeled buttons. For example: Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. methods. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default. this manual uses typefaces drawn from the Liberation Fonts set. For example: File-related classes include filesystem for file systems. Press Ctrl+Alt+F1 to return to your X-Windows session. variable names and returned values mentioned within a paragraph will be presented as above. and dir for directories. 1 1. The above includes a file name. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously). in mono-spaced bold. click the Left-handed mouse check box and click 1 https://fedorahosted. Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination.1. and the circumstances they apply to. all presented in mono-spaced bold and all distinguishable thanks to context. The first paragraph highlights the particular keycap to press. If source code is discussed. a shell command and a keycap. dialog box text. file names and paths. Proportional Bold This denotes words or phrases encountered on a system. are as follows. For example: Press Enter to execute the command.org/liberation-fonts/ v .Preface 1. In the Buttons tab. including shell commands. Also used to highlight keycaps and key combinations. Each class has its own associated set of permissions. enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command. including application names. functions. These conventions. In PDF and paper editions. menu titles and sub-menu titles.

vi . To insert a special character into a gedit file. Output sent to a terminal is set in mono-spaced roman and presented thus: books books_tests Desktop Desktop1 documentation downloads drafts images mss notes photos scripts stuff svgs svn Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows: package org. If the remote machine is example.jboss. It will return a result as follows: package-version-release. version and release. To see the version of a currently installed package.Preface Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). For example: To connect to a remote machine using ssh. Italics denotes text you do not input literally or displayed text that changes depending on circumstance.InitialContext. type ssh john@example. italics denotes the first use of a new and important term.com. to remount the /home file system. all presented in proportional bold and all distinguishable by context. import javax. type the name of the character in the Search field and click Next. either for text you enter when issuing a command or for text displayed by the system. file-system. choose Search → Find… from the Character Map menu bar.2. The above text includes application names. system-wide menu names and items. Mono-spaced Bold Italic or Proportional Bold Italic Whether mono-spaced bold or proportional bold.name at a shell prompt. package. For example. domain. Pull-quote Conventions Terminal output and source code listings are set off visually from the surrounding text. Doubleclick this highlighted character to place it in the Text to copy field and then click the Copy button.ex1. Note the words in bold italics above — username.name.naming. type ssh username@domain. the addition of italics indicates replaceable or variable text. Aside from standard usage for presenting the title of a work.book. For example: Publican is a DocBook publishing system.com and your username on that machine is john.jca. the command is mount -o remount /home. The character you sought will be highlighted in the Character Table. Each word is a placeholder. 1. choose Applications → Accessories → Character Map from the main menu bar. and buttons and text found within a GUI interface. The mount -o remount file-system command remounts the named file system. use the rpm -q package command. Now switch back to your document and choose Edit → Paste from the gedit menu bar. Next. application-specific menu names.

shortcuts or alternative approaches to the task at hand. vii .3. Ignoring a note should have no negative consequences. be sure to mention the manual's identifier: ESB_ADG If you have a suggestion for improving the documentation. Object ref = iniCtx. Note Notes are tips.lookup("EchoBean").Notes and Warnings public class ExClient { public static void main(String args[]) throws Exception { InitialContext iniCtx = new InitialContext(). } } 1. but you might miss out on a trick that makes your life easier. When submitting a bug report. System. Notes and Warnings Finally.create().println("Created Echo").out. please include the section number and some of the surrounding text so we can find it easily. EchoHome home = (EchoHome) ref. Warning Warnings should not be ignored. Ignoring warnings will most likely cause data loss. System.out.println("Echo. Echo echo = home. We Need Feedback If you find a typographical error in the ESB Administrators Guide.echo('Hello') = " + echo. 2.com/jira against the Documentation component of the SOA Platform project. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration. or services that need restarting before an update will apply. we use three visual styles to draw attention to information that might otherwise be overlooked. Important Important boxes detail things that are easily missed: configuration changes that only apply to the current session. or if you have thought of a way to make this manual better.echo("Hello")). If you have found an error. we would love to hear from you! Please submit a report in JIRA: http:// jira. try to be as specific as possible when describing it.jboss.

viii .

Clustering Scenario 1 1 .1. Clustered ESB Service In a clustered ESB environment the nodes must be configured in one of the following two ways: Figure 1. Configuration 1. then you should refer to the instructions in the SOA Platform Getting Started Guide.Chapter 1.1. 1.2. Standalone server If you wish to run the JBossESB server on the same machine as JBossAS.

Chapter 1.3.0) and Tibco EMS as Java Message Service (JMS) providers.url=jnp://jawa02:1099 1. We recommend JBoss Messaging and it is included with the default configuration.naming. 2 . JBossESB JMS Providers The JBoss Enterprise SOA Platform currently supports JBoss Messaging.provider. Configuration Figure 1.3 and 6.org/en/jsr/detail?id=914) compliant JMS implementation should also work such as Apache ActiveMQ and OracleAQ.url=jnp://jawa01:1099 java. Any JSR-914 (http://jcp. • The client must have all the nodes listed in jndi.naming.provider. If you wish to try using another JMS provider you should consult that vendor's documentation. However other JMS providers have not been fully tested and are not supported at this time. Clustering Scenario 2 Two other points that must be taken into account are: • All of the clustered queues must be deployed on all cluster nodes at all times.2.properties like this: java. IBM Websphere MQ Series (version 5.

Apache ActiveMQ Warning Apache ActiveMQ has not been fully tested & is not a supported JMS implementation. but can be over-ridden by setting the org.3.jms. 1. For JBossMessaging you should set the parameters to: jndi-URL="localhost" jndi-context-factory="org.xml): jndi-URL. 1. For advanced capabilities.connectionPool property in the transports section of the JBossESB configuration file. connection-factory.jboss. you should consult that documentation as well.esb.How can I configure a different JMS provider? Important This section is not intended as a replacement for the configuration documentation that comes with the supported JMS implementations. 3 .1. By default the size of this pool is set to 20.jnp. so you can use more then one provider in your deployment. Likewise.jar must be included in your classpath. that we are listening to a destination type of queue and that its name is queue/A. For this you can use the following parameters in their configuration (server/<name>/deploy/jbossesb. How can I configure a different JMS provider? JMSListeners and JMSGateways can be configured to listen to a Queue or Topic. In the following sections we will assume that your JMS provider runs on localhost. jndi-pkg-prefix. JBossESB utilizes a connection pool to improve performance.3. This time can be configured using the org. Configuring JBoss Messaging in a clustered setup gives you load balancing and failover facilities for JMS.esb.sessionSleep property. 1. JBoss Messaging JBoss Messaging is the default JMS provider for the JBoss SOA Platform.interfaces. such as clustering and management.1. Since this capability has changed between different versions of JBoss Messaging and may continue to do so.3.jms.soa.2. Each JMSListener and JMSGateway can be configured to use its own JMS provider.1.esb/ META-INF/jboss-esb. When using JMS. you should consult the JBoss Messaging documentation.1.soa. Furthermore you will need to add the client JMS jars of the JMS-provider you want to use to the classpath.jboss. if a session cannot be obtained initially.NamingContextFactory" connection-factory="ConnectionFactory" destination-type="queue" destination-name="queue/A" The jar file jboss-messaging-client. jndi-context-factory. destination-type and destination-name. JBossESB will keep retrying for up to 30 seconds before giving up. that the connection-factory is ConnectionFactory.

ibm.ibm. and are not provided by us.DEF.pcf.jms. Configuration For ActiveMQ you should set the parameters to: jndi-URL="tcp://localhost:61616" jndi-context-factory= "org.mq.activemq. jndi-URL="localhost:1414/SYSTEM. You will have to obtain them from your Websphere AS and MQ installations.jndi.ibm. This has been tested with version 4.mqjms.1. 1. For Oracle AQ you should set the parameters to: connection-factory=”QueueConnectionFactory” 4 .WMQInitialContextFactory" connection-factory="ConnectionFactory" destination-type="queue" destination-name="QUEUEA" On your classpath you should have: • com.jar • mqcontext.context. which can be fixed by adding the user that runs the JBoss Enterprise SOA Platform to the mqm group.0 jars should be backward compatible.apache.jar (client jar) Please note that the client jars differ between MQ 5.jar (client jar) • com. but the 6.0.ActiveMQInitialContextFactory" connection-factory="ConnectionFactory" destination-type="queue" destination-name="queue/A" Both jars can be found in lib/ext/jms/activemq. Oracle Advanced Queuing (AQ) Warning OracleAQ has not been fully tested & is not a supported JMS implementation. The jars are not open source.3. The name of the Queue Manager in MQ should match what the value of 'connection-factory' is or you will need to bind this name to JNDI.JMSSecurityException: MQJMS2013: invalid security authentication supplied for MQQueueManager 1.SVRCONN" jndi-context-factory="com. Reason: failed to create connection --javax. Also note that you may get the following exception when running MQ 6.mq.Chapter 1.1.mq.3. In our case we created a Queue Manager named "ConnectionFactory".0.3 and MQ 6.3.ibm.jar • com.0incubator.1. Message: Unable to get a MQ series Queue Manager or Queue Connection.jms. IBM Websphere MQ Series IBM Websphere MQ Series requires capitalized queue names and does not allow slashes (QUEUEA).4.

These settings are found in the DBSTORE section of the file.jar.xml configuration file.tibjms. and the Message-Store.aq. jta-spec1_0_1.1. 1.esb.jms.sar/lib directory.naming. Database Configuration The ESB uses databases for persisting Registry services.esb. 5 . The following are settings that you will need to change.jar.naming.tibco.aq.jar and you will have to deploy it to the jbossesb.server" value="<server>"/> <property name="java. tibjmsapps.soa.4.4. The jar is called org.jar. tibjms. tibjmsadmin.naming. For the Message-Store you will need to also update the data-source setting properties in the main ESB config file jbossesb-properties. When creating a Queue in Oracle AQ make sure to select a payload type of SYS AQ $_JMS_MESSAGE.port" value="1521"/> <property name="java. 1.naming.jar.jboss. Database scripts for each of these can be found under: Service Registry: ESB_ROOT/install/juddi-registry/sql Message-Store: ESB_ROOT/services/jbossesb/src/main/resources/message-store-sql A few database types and their scripts are provided. which are found in the tibco/ems/clients/java dir: jaxp.jar.oracle.initial" value="org.jar.oracle.user" value="<user>"/> <property name="java.oracle.naming.naming.aq.naming.aq.xml. and you should be able to easily create one for your particular database (if you do.soa.jar We tested with version 4.aq.oracle.AQInitialContextFactory"/> <property name="java.jar.oracle. based on the connection information appropriate to your environment.naming. For a sample you can check the samples/quickstarts/helloworld_action/oracle-aq directory for an example jboss-esb. The AQInitialContextFactory references code in a plugin jar that you can find in the plugins/org.aq.soa.TibjmsInitialContextFactory" connection-factory="QueueConnectionFactory" destination-type="queue" destination-name="<queue-name>" In your classpath you should have the client jars that ship with Tibco EMS.password" value="<pw>"/> <property name="java.jboss.naming.schema" value="<schema>"/> <property name="java.jar. tibrvjms.2.driver" value="thin"/> You may notice the reference to the InitialContext factory.instance" value="<instance>"/> <property name="java.1. jndi.3.aq. You only need this if you want to avoid OracleAQ registering its queues with an LDAP server.esb.Database Configuration and use the following properties: <property name="java.oracle.aq.5.jboss.oracle.aq-4.oracle.factory.oracle.oracle. tibcrypt. please contribute it back to us). Tibco EMS For Tibco EMS you should set the parameters to: jndi-URL="tcp://localhost:7222" jndi-context-factory= "com.aq directory.

persistence.soa.db.esb.soa.jboss.esb.persistence.soa.soa.pool.esb.soa.datasource.soa.manager" value="org.esb.pool.persistence.db.min.jboss.soa.url The database connection URL.pool.jboss.esb.db.esb.size" value="2"/> <property name="org.driver JDBC Driver org.test.esb.soa.esb.size" value="2"/> <property name="org.db.StandaloneConnectionManager" /> <property name="org.jboss.table" value="pooltest"/> <property name="org.jboss.persistence.manager.size" value="5"/> <property name="org.jboss.property is only used if using the j2ee connection manager --> <property name="org.url" value="jdbc:hsqldb:hsql://localhost:9001/jbossesb"/> <property name="org.db.db.persistence.manager" value="org.persistence.persistence.name" value="java:/JBossESBDS"/> </properties> When running from the standalone bootstrapper use: <properties name="dbstore"> <!-.db.esb.conn.soa. By default JBossESB is configured to use a JEE DataSource.jboss.persistence.soa.soa.esb.size The initial size of database connection pool org.esb.J2eeConnectionManager"/> <!-.jboss.esb.esb.db.db.esb.db.pool.connection.db.esb.manager The database connection manager.persistence.persistence.jdbc.db.jboss.soa.db.esb.soa.jboss.connection manager type --> <property name="org.persistence.connection.Chapter 1. org.soa.jboss.persistence.jboss.jboss.esb.user The database user org.esb.esb.jboss.name The datasource name (used for JNDI lookup) org.soa.persistence.esb.conn.persistence.pool.persistence. <properties name="dbstore"> <property name="org.persistence.driver" value="org.db.soa.persistence.initial.soa.db.soa.esb.hsqldb.jboss.size The minimum size of database connection pool 6 .db.jdbc.db.initial.pool.soa.timeout.conn.persistence.jboss.db.jboss.jboss.jdbcDriver"/> <property name="org.jboss.pwd" value=""/> <property name="org.datasource.pwd The database password org.persistence.db.manager.persistence.millis" value="5000"/> </properties> Database Configuration Properties org.max.jboss.jboss.soa.soa.persistence.min. Configuration As long as there is a script for your database the ESB will auto-create the schemas on startup.jboss.esb.user" value="sa"/> <property name="org.soa.db.pool. org.persistence.

max. You should change your datasource configuration before using the JBoss SOA Platform in a production capacity.Switching Databases org.pool. Oracle9i. If you make additional changes then the script may no longer work as expected.esb. The JBoss Enterprise SOA Platform includes a Database Configuration Script for datasource configuration. Use of HSQLDB for production is not recommended. 7 .properties file. 1.millis The timeout period to wait for connection requests from pool The Service Registry database information is contained in the juddi.soa. The Database Configuration Script is an ant script located in ${SOA_ROOT}/tools/schema/.esb.pool.jboss.persistence.jboss.persistence.esb/ message-store-ds. HSQLDB has a number of limitations and is included only for testing and demonstration use.soa. [ schema]$ ant Buildfile: build. Switching Databases This section describes the steps required to change the datasource configuration from one database to another. Important The default datasource configuration uses the included Hypersonic database (HSQLDB).table A table name (created dynamically by pool manager) to test for valid connections in the pool org.size The maximum size of database connection pool org. The data-source definition can be found in the jbossesb. use the command ant in that directory. 1. JBoss server comes with a pre-installed hypersonic database (HSQLDB). and is not a supported configuration for the SOA Platform.pool.xml.esb. Deployment scripts are currently available for the following databases: MySQL.db.5. To run the script.db.xml [echo] [echo] [echo] [echo] [echo] [echo] [echo] [echo] [echo] [echo] [echo] [echo] JBoss SOA Platform -----------------Database Configuration Script This script is used to configure the SOA platform and all it's constituent components against a new RDBMS. PostgresSQL. The database can only be accessed in the same JVM.db.jboss.persistence.test. You should consult the Service Registry section of this document for more detailed information on what settings and their values and how they effect the behavior of the ESB. It is not suitable for production deployment and is not supported.timeout. This script can be run multiple times to change your configuration but requires that no additional changes have been made to your configuration. Oracle10g -----------------NOTICE: THIS SCRIPT MAY NOT WORK CORRECTLY IF YOU HAVE MADE MANUAL CHANGES TO THE DATABASE CONFIGURATION.soa.

esb.jboss.path .soa.soa.node.the path relative to the root of the repository where messages will be stored.persistence. If not specified.path .jcr. • The username to access the database.esb.properties before running the script.format. repository data is stored in the JBossAS/server/{servername}/data/repository directory.jndi.JCRMessageStorePlugin" /> This adds the JCR plugin to the list of available message stores.esb. • The password for the user account to access the database.jboss.sar: <property name="org. As an alternative to the default database message store.soa.xml configure repository access: <property name="org. jcr.persistence. jcr.jboss. Oracle 9i and Oracle 10g are supported at this time.esb. The action will attempt to store the current message to the JCR store. You can also specify these values in the file ${SOA_ROOT}/tools/schema/build.username" value="username"/> <property name="org.esb. jcr. PostgreSQL.xml located in the root of jbossesb.jcr.password . • The name of the database instance.soa.jcr. add the following property to the core section of jbossesb-properties. Configuration The script will prompt you for the details it requires.persistence.6. • The hostname or IP Address of the database. The following list of properties should be added in the dbstore section of jbossesb-properties.username for the repository session 3. 2.base.root.persistence.persistence.soa.password for the repository session 4. 1.username .password" value="password"/> <property name="org.esb.persistence. Only MySQL.soa. In this case. a JSR-170 (Java content repository) message store may be used.path" value="JBossESB/MessageStore"/> 1. The JCR message store can use an existing repository via JNDI or can create a standalone instance locally on the application server. These details are: • The type of database you are using.jndi.jcr" value= "org. jcr.jboss.jboss.Chapter 1. To enable the JCR message store. Using a JSR-170 Message Store JBossESB allows for multiple message store implementations via a plugin-based architecture.jcr. The JCR implementation included with JBossESB is Apache Jackrabbit.persistence.plugin.xml in the root of the jboss-esb.sar.jcr.node.jboss.esb.jboss.soa. a new repository will be created based on the repository.StoreJCRMessage action onto an existing service. • The TCP port being used for the database instance.actions. An easy test for whether the JCR message store is configured properly is to add the org.path" value="jcr"/> <property name="org.root.internal. 8 .optional path in JNDI where the repository is found.

onOutput ( header: [ To: EPR: PortReference < <wsa:Address ftp://foo. ReplyTo: EPR: PortReference < <wsa:Address http://bar. you will see the following log at info level: TraceFilter. gateways.foo/> >. By default. MessageI D: urn:foo/bar/1234.esb. This may be important for a number of reasons.message.esb.unloggable set to yes will be ignored by this filter.jboss.onInput ( header: [ To: EPR: PortReference < <wsa:Address ftp://foo. From: null. You can identify these messages by looking for the following in your output: header: [ To: EPR: PortReference < <wsa:Address ftp://foo.permessagetrace is set to on (the default is off).TraceFilter.esb.jboss. Once enabled. foo/> >. ServiceInvoker and load balancing) log all interactions with Messages through standard logger messages. or output from it.7. RelatesTo: null ] ) TraceFilter. you can enable a logging metadata filter.filter. Action: urn:dowork. JBossESB components (e. can be placed within the Filter section of the JBossESB configuration file. FaultTo: null. To do this make sure that the property org..Message Tracing 1. However.foo/> >. FaultTo: null. Message Tracing It is possible to trace any and all Messages sent through JBossESB. for finer grained control you may enable finer grained control over which Messages are logged and which are ignored. Action: urn:dowork. By default. including audit trail and debugging. FaultTo: null.soa. whose only role is to issue log messages whenever a Message is either input to an ESB component. MessageID: urn:foo/bar/1234.bar/> >.g. ReplyTo: EPR: PortReference < <wsa:Addr ess http://bar.internal. MessageID: urn:foo/bar /1234.jboss.soa. RelatesTo: null ] ) TraceFilter will only log if the property org.soa. From: null.soa.bar/> >. RelatesTo: null ] Furthermore.messagetrace is set to on (the default setting is off). In order to trace Messages you should ensure that they are uniquely identified using the MessageID field of the Message header: as mentioned in the Programmers Guide.bar/> >.esb. Such log messages will contain the entire header information associated with the Message which will enable correlation across multiple JBossESB instances. org. Whenever a Message passes through this filter. those Messages with a property of org. 9 . This filter. in conjunction with any other filters: it has no effect on the input or output Message.message. From: null. if enabled it will log all Messages that pass through it. Action: urn:dowork. this is the only way in which Messages can be uniquely identified within the ESB.jboss. ReplyTo: EPR: PortReference < <wsa:Add ress http://bar.

10 .

It is important that you ensure the system is in a quiescent state before doing this. This is fully described in the Registry Guide. In that case those entries may be removed manually. • If you set the optional remove-old-service tag in the EPR to true then the ESB will remove any existing service entry from the Registry prior to adding this new instance. because the entire service will be removed. 11 . Additionally. services typically register the EPR through which they can be contacted. including all EPRs. this should be used with care. However. Well behaved services should remove EPRs from the registry when they terminate. where configuration information is also discussed. machine crashes or incorrectly developed services may leave stale entries in the registry that prevent the correct execution of subsequent deployments.Chapter 2. it is worth noting the following: • When run. However. Registry At the heart of all JBossESB deployments is the registry.

12 .

messages have headers that contain recipient addresses. However. in the case where a response is required and the reply EPR (ReplyTo EPR) has not been set. As described in the Programmers Guide. sequence numbers (for message correlation) and optional addresses for replies. The new table needs the same columns as the request table. For files (both local and remote). As such. For JMS. Some of these ReplyTo defaults require system administrators to configure JBossESB correctly. 1.Chapter 3. 13 . faults etc. a reply address (EPR) is an optional part of the header routing information and applications should be setting this value if necessary. Because the recommended interaction pattern for within JBossESB is based on one-way message exchange. Default ReplyTo EPR JBossESB uses Endpoint References (EPRs) to address messages to/from services. no administration changes are required: responses will be written into the same directory as the request but with a unique suffix to ensure that only the original sender will pick up the response. it is assumed to be a queue with a name based on the one used to deliver the original request: <request queue name>_reply 2. 3. it is assumed to be a table in the same database with a name based on the one used to deliver the original request: <request table name>_reply_table. JBossESB supports default values for each type of transport. For JDBC. responses to messages are not necessarily automatic: it is application dependent as to whether or not a sender expects a response.

14 .

you may want to use JBoss ServiceBinding Manager. Note If you are using jboss-messaging as your JMS provider.xml.xml. The binding manager allows you to centralize port configuration for all of the instances you will be running. 15 . The ESB server ships with a sample bindings file in docs/examples/ binding-manager/sample-bindings. please note that what you specify in your ServiceBinding manager xml for jboss-messaging configuration must match what is in remoting-service. ServiceBinding Manager If you wish to run multiple ESB servers on the same machine.Chapter 4. The Getting Started Guide contains instructions for setting up the ServiceBinding manager in the Post-Installation Section.

16 .

listener-name=<Listener name> .xml with your SMTP settings.ThresholdMonitor" name="jboss.Message counters break all of the services deployed for a listener down into their separate actions and give counts of how many messages were processed. File: deploy/DeadLetterQueue_Monitor-service.monitor:service=ESBDLQMonitor"> <attribute name="MonitorName"> ESB DeadLetterQueue Monitor </attribute> 17 . 3. You can use this functionality to receive alerts for ESB-related events such as the DeadLetterService counter reaching a certain threshold.jsp?page=WebConsole) is a utility within both the JBoss AS and the JBoss ESB Server that is capable of monitoring and sending alerts based off of JMX MBean properties. you should see the following MBean types : 1.jboss. Change deploy/monitoring-service.monitor. state. 5. Alerts The JBoss Web Console (http://jboss.pdf). average size of message. 2.xml . 2. processing time. Additionally. 5. The message counts may be reset and services may be stopped and started. Shipping with the ESB are a number of useful JMX MBeans that help administrators monitor the performance of their server.Deployments show the state of all of the esb packages that have been deployed and give information about their XML configuration and their current state. 3. Monitoring and Management There are a number of options for monitoring and managing your ESB server. as well as the processing time of each message. 4.xml <?xml version="1. with information on their XML configuration. etc).All deployed listeners are displayed. Configure deploy/mail-service. deployment=<ESB package name> . which is useful information when debugging or determining performance.1. .Displays statistics per-service (message counts. Create a file deploy to serve as your monitor MBean. Under the jboss. jms domain MBeans show statistics for message queues. Monitoring and Management Console JBossESB has its own monitoring and management console for ESB related properties (http:// localhost:8080/jbossesb). etc. category=MessageCounter . The administrator has the option of initializing/starting/stopping/destroying a listener. the start time. The Monitoring and Management Console is covered in-depth in its own help documentation (docs/governance/Monitoring.2.esb domain. maxThreads. service=<Service-name>.0" encoding="UTF-8"?> <server> <mbean code="org.Chapter 5.org/wiki/Wiki. 1.uncomment the EmailAlertListener section and add appropriate header related information. state.

For more details on how to use the JBoss Web Console monitoring.esb:category=MessageCounter. you need to also reset the alerted flag on your monitoring service MBean (in this case jboss.alerts:service=ConsoleAlertListener </depends-list-element> <depends-list-element> jboss.alerts:service=EmailAlertListener </depends-list-element> </depends-list> <depends>jboss.deployment=jbossesb.jboss.Chapter 5. please see http://wiki.when the threshold is reached.jsp?page=JBossMonitoring 18 . Monitoring and Management <attribute name="ObservedObject"> jboss.esb</depends> </mbean> </server> This MBean will serve as a monitor.esb. Note that the alert is only sent once . it will send an e-mail to the address(es) specified in the monitoring-service.xml.monitor:service=ESBDLQMonitor).org/ wiki/Wiki. and once the DeadLetterService counter reaches 5.servicename=DeadLetterService </attribute> <attribute name="ObservedAttribute"> overall service message count </attribute> <attribute name="Threshold">4</attribute> <attribute name="CompareTo">-1</attribute> <attribute name="Period">1000</attribute> <attribute name="Enabled">true</attribute> <depends-list optional-attribute-name="AlertListeners"> <depends-list-element> jboss. If you want to be alerted again after resetting the counter.esb:deployment=jbossesb.

redeploy the esb archive containing the transformation file. the timestamp of the archive changes.org/wiki/Wiki. Here are the instructions for doing this: sar files The jbossesb.Chapter 6. esb files Any *. so when hot deployed a component goes down gracefully. if the esb is compressed archive.esb archive. All of this can be done by simply redeploying the . However. From within the jBPM eclipse plugin you can deploy a new definition to the jbpm database.xml changes. you 1 can use groovy scripting to modify an action at runtime (see the groovy QuickStart ).jboss. 2.esb (see 2) 2. redeploy the jbrules.xml changes. and does not accept any more incoming messages until it is back up. Once this is done when a rule file changes it will be reloaded.jsp?page=JBossESBQuickStart 19 . It will redeploy when: 1. 2. Server mode JBossAS as well as the JBossESB-Server are always checking the deploy directory for new files to deploy. JBoss ESB actions have life-cycle support. if the sar is in exploded form. send out a notification message over JMS(topic) using the esb-console. There are additional steps to deploy beyond copying a file to that directory. the timestamp of the archive changes. If you want to update just one action. on occasion you may need to redeploy an existing component. if the sar is compressed archive. if the esb is in exploded form.esb archive will redeploy when: 1.1. the timestamp of the META-INF/jboss-service. turn on the ruleReload in the action config (see JBossESBContentBasedRouting ). Business Process Definitions When using jBPM new Business Process Definitions can be deployed. finishes active requests. 2.sar is hot deployable. The Smooks processors will receive this event and reload. New process instances will get the new 1 http://wiki. 2 Transformation files There are two options to refresh transformation files: 1. Hot Deployment 6. Rule files There are two options to refresh rule files (drl or dsl) 1. the timestamp of the META-INF/jboss-esb.

Chapter 6. Standalone (bootstrap) mode. in flight processes will finish their life cycle on the previous definitions.xml configuration file per node. You can only have one jboss-esb. The bootstrapper does not deploy esb archives. For details please see the documentation on jBPM. and finally to update BPDs you can follow the process mentioned in Business Process Definitions. 6.2. 20 . To update rules you will have to use the ruleReload. to update transformations you need to send out a Smooks JMS notification using the esb-console. Hot Deployment version. It will monitor the timestamp on this file and it will reread the configuration if a change occurs.

This hyperlink links off to the WSDL. it groups the endpoint according to Service with which they are associated (servicing). This application is installed by 1 default with the ESB (after running ant deploy from the install directory) .1. Figure 7. you will first need to undeploy the default Contract application. Contract Publishing 7. 1 Note that the Contract application is also bundled inside the JBossESB Console. If you are deploying the console.1. "Contract" Application For this purpose. This is particularly the case for web service endpoints exposed via the SOAPProcessor action (see the JBoss SOA Platform ESB Message Action Guide). Overview Integrating to certain ESB endpoints may require information about that endpoint and the operations it supports. Another thing you'll notice is how some of them have an active "Contract" hyperlink.war from the default/deploy folder of your ESB/ App Server. 7. Just remove contract. we bundle the "Contract" application with the ESB.2. The Contract Application As you can see. 21 . The ones visible here are for web service endpoints exposed via the SOAPProcessor.Chapter 7. It can be accessed through the following URL: http://localhost:8080/contract/ The following is a screenshot of this application.

actions. 3 2 2 http://anonsvn.internal.java 3 http://anonsvn.com/labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/ WebserviceContractPublisher.Chapter 7. You then need to implement a ContractPublisher (org.. See the WebserviceContractPublisher code as an example . Publishing a Contract from an Action JBossESB discovers endpoint contracts based on the action pipeline that's configured on a Service.labs. If none of the actions publish contract information.java 22 .ContractPublisher). } See the SOAPProcessor code as an example .Publish annotation as follows (using the SOAPProcessor as an example): @Publish(WebserviceContractPublisher.. It looks for the first action in the pipeline that publishes contract information. then the Contract application displays "Unavailable" on Contract for that endpoint.3. An Action publishes contract information by being annotated with the org.com/labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/ SOAPProcessor.soa.publish.jboss.class) public class SOAPProcessor extends AbstractActionPipelineProcessor { // .esb.jboss.esb.jboss.jboss. Contract Publishing 7.soa.labs.soap. which requires implementation of a single method: public ContractInfo getContractInfo(EPR epr).

CP05 David Le Sage dlesage@redhat.xml and jbossesb-gateway.6" Revision 1.database schema content added to configuration chapter Revision 1."Docs refer to bossesb-listener.xml" SOA-556 .1.com Updated for CP02 SOA-534 .2.4 Fri Jun 12 2009 Darrin Mison dmison@redhat.com 23 .1 Thu 3 Apr 2008 Updated for CP01 Joshua Wulf jwulf@redhat.com Revision 1. Revision History Revision 1.com Updated for CP04 SOA-1132 .com Revision 1."CP01 Administrators' Guide PDF has corrupted characters in section 3.2 Fri 23 May 2008 Joshua Wulf jwulf@redhat.Appendix A.5 Tue Apr 20 2010 Updated for SOA 4.3 Mon 3 Nov 2008 Updated for CP03 Darrin Mison dmison@redhat.

24 .