[jboss-svn-commits] JBL Code SVN: r34731 - in labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US: extras/configuration and 6 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Aug 15 19:23:44 EDT 2010
Author: dlesage
Date: 2010-08-15 19:23:43 -0400 (Sun, 15 Aug 2010)
New Revision: 34731
Added:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/JON_for_SOA.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/SOAPProcessor.java
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/cache_revalidation_timeout.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java1.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java2.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java4.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jbossesb-properties_1.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jbossesb-properties_2.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_1.output
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_2.output
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_3.output
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/opensso_identity_provider.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/opensso_login-config.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/swtichdb1.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/swtichdb2.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/tibco_ems.settings
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/java3.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/provider1.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/provider2.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/programmatically.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/quickstart.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/quickstartoutput.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/contract_publishing/contract_publishing_application.png
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/jon/
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/jon/JON_SOA_indicators.png
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/monitoring_and_management/jmx.png
Modified:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuration.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuring_WebService_Integration.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Contract_Publishing.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Default_ReplyTo_EPR.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Hot_Deployment.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Monitoring_and_Management.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Performance_Tuning.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Registry.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/ServiceBindingManager.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/jBPM_Console.xml
Log:
JBESB 3460
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuration.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuration.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuration.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -9,145 +9,266 @@
Configuration
</title>
+ <para>
+ This book teaches system administrators
+ how to configure the <application>JBoss SOA Platform Enterprise
+ Service Bus</application> for use in financial institutions, banks,
+ telecommunications companies and other large
+ corporations. This chapter explains how to configure the software after
+ the reader has followed the initial installation steps in the
+ <emphasis>Getting Started Guide</emphasis>.
+ </para>
+
+
+ <section id="introduction_to_soa-p">
+ <title>
+ Introduction to Basic Concepts
+ </title>
+<!-- This short, introductory section is based on Len Di Maggio's blog article at http://riftsaw.blogspot.com/2009/11/from-bpel-to-esb-and-back-introduction.html -->
+<para>
+ A <firstterm>Service Oriented Architecture</firstterm> (SOA) is not a
+ single program or technology. Think of it, rather, as a software design
+ paradigm. A hardware <firstterm>bus</firstterm> is a physical connector
+ that ties together multiple systems and subsystems. Instead of having a
+ large number of point-to-point connectors between pairs of systems,
+ each system is simply connected to the central bus. An
+ <firstterm>enterprise service bus</firstterm> (ESB) does the same thing
+ in software.
+</para>
+
+<para>
+ Instead of passing data over the bus via the connections (known as
+ <firstterm>end points</firstterm>), the ESB sits in the
+ architectural layer above a messaging system. This messaging system
+ allows <firstterm>asynchronous communications</firstterm> to occur
+ between services over the ESB. In fact, when one is using an ESB,
+ everything is, conceptually, either a <firstterm>service</firstterm>
+ (which, in this context, is one's application software) or a
+ <firstterm>message</firstterm> being sent between services.
+</para>
+
+<para>
+ It is important to note that, in this context, a "service" is not
+ necessarily a web service. Other types of applications, using various
+ transports such as File Transfer Protocol and Java Message Service, can
+ also be "services."
+</para>
+
+<note>
+ <para>
+ At this point, one may be wondering if an Enterprise Service Bus is
+ the same thing as a Service Oriented Architecture. The answer is,
+ "Not exactly." This is because an ESB does not actually form a
+ Service Oriented Architecture of itself. Rather, it provides many
+ of the tools than can be used to build one. In particular, it
+ facilitates the <firstterm>loose-coupling</firstterm> and
+ <firstterm>asynchronous message passing</firstterm> needed by a
+ SOA. Always think of a SOA as being more than just software: it is
+ a series of principles, patterns and best practices.
+ </para>
+</note>
+
+
+ <para>
+ The <application>JBoss Enterprise Service Bus</application> is an
+ open source ESB provided by Red Hat. It supports:
+ </para>
+
+<itemizedlist>
+ <listitem>
+ <para>multiple transports and protocols</para>
+ </listitem>
+ <listitem>
+ <para>a <firstterm>listener-action model</firstterm> (used to couple services together loosely)</para>
+ </listitem>
+ <listitem>
+ <para><firstterm>content-based routing</firstterm> (through
+ <application>JBoss Rules</application>)</para>
+ </listitem>
+ <listitem>
+ <para>integration with the <application>JBoss Business Process
+ Manager</application> (to facilitate <firstterm>service
+ orchestration</firstterm>.)</para>
+ </listitem>
+</itemizedlist>
+
+ </section>
+
<section id="standalone_server">
<title>
Stand-Alone Server
</title>
<para>
- If you wish to run the JBossESB server on the same machine as
- JBossAS, then you should look at the <ulink
- url="http://www.jboss.org/community/wiki/ConfiguringMultipleJBossInstancesOnOnemachine">Configuring
- Multiple JBoss Instances On One Machine</ulink> Wiki page.
+ To learn how to run the <application>JBoss Enterprise SOA
+ Platform</application> server on the same machine as another JBoss
+ Application Server, study the information on this website: <ulink
+ url="http://www.jboss.org/community/wiki/ConfiguringMultipleJBossInstancesOnOnemachine"
+ />.
</para>
</section>
-
+
+
<section id="JBossESB_JMS_Providers">
<title>
- JBossESB JMS Providers
+ JBoss ESB Java Message Service Providers
</title>
<para>
- The JBossESB supports a number of JMS providers. Currently we
- have successfully tested JBoss Messaging, JBossMQ, ActiveMQ and
- Websphere MQ Series (version 5.3 and 6.0). We recommend JBoss
- Messaging. At this time we know of no reasons why other JMS
- implementations should not also work, but have not been able to
- verify this.
+ JBoss currently supports the use of a number of
+ <firstterm>Java Message Service</firstterm> applications in
+ conjunction with the <application>JBoss Enterprise SOA
+ Platform</application>. These applications are
+ <application>JBoss Messaging</application>, <application>Tibco
+ 5.0</application> and <application>IBM MQ 6.0.2</application>.
+ The following sections instruct the reader how to configure
+ each of these.
</para>
<warning>
<para>
- This section is not intended as a replacement for the
- configuration documentation that comes with the supported JMS
- implementations. For advanced capabilities, such as clustering
- and management, you should consult that documentation as well.
+ It is best to use <application>JBoss
+ Messaging</application>, which is the default
+ option.
</para>
+
+ <para>
+ Any other <firstterm>JSR-914</firstterm> (<ulink
+ url="http://jcp.org/en/jsr/detail?id=914" />)-compliant
+ <firstterm>Java Message Service</firstterm> implementation
+ (such as <application>Apache ActiveMQ</application> or
+ <application>OracleAQ</application>) should also work. However,
+ these has been fully tested so they are not supported
+ at this time. If trying another vendor's product, always
+ consult the documentation supplied with it.
+ </para>
</warning>
-
+
+ <warning>
+ <para>
+ This section is not intended to be a replacement for the
+ configuration documentation that comes with the supported
+ Java Message Service implementations. Consult that
+ documentation to learn about advanced capabilities, such as
+ <firstterm>clustering</firstterm> and
+ <firstterm>management</firstterm>.
+ </para>
+ </warning>
- <formalpara>
- <title>
- How can I configure them?
- </title>
+
<para>
- JMSListeners and JMSGateways can be configured to listen to
- a Queue or Topic. For this you can use set the following
- parameters in the service configuration file: jndi-URL,
- jndi-context-factory, jndi-pkg-prefix, connection-factory,
- destination-type and destination-name. Furthermore you will
- need to add the client jms jars of the JMS-provider you
- want to use to the classpath.
- </para>
- </formalpara>
+ To configure <systemitem>JMS Listeners</systemitem> and
+ <systemitem>JMS Gateways</systemitem> to listen to
+ <firstterm>queues</firstterm> and
+ <firstterm>topics</firstterm>, specify the following
+ parameters in the
+ <filename>jbossesb-listener.xml</filename> and
+ <filename>jbossesb-gateway.xml</filename> configuration
+ files:
+ </para>
+
+
+ <itemizedlist>
+ <listitem><para><property>jndi-URL</property></para></listitem>
+ <listitem><para><property>jndi-context-factory</property></para></listitem>
+ <listitem><para><property>jndi-pkg-prefix</property></para></listitem>
+ <listitem><para><property>connection-factory</property></para></listitem>
+ <listitem><para><property>destination-type</property></para></listitem>
+ <listitem><para><property>destination-name</property></para></listitem>
+ </itemizedlist>
+
+ <important>
+ <para>
+ Be sure to include the chosen JMS provider's client
+ <filename>JAR</filename> files in the class-path.
+ </para>
+ </important>
+
<important>
<para>
- In the following sections we will assume that your JMS
- provider runs on 'localhost', that the connection-factory
- is 'ConnectionFactory', that we are listenening to a
- destination-type 'queue' and that it's name is 'queue/A'.
- </para>
+ In the following sections it is assumed that:
+ </para>
+
+ <itemizedlist mark='bullet'>
+ <listitem><para>the JMS provider is running on 'localhost'</para></listitem>
+ <listitem><para>the connection-factory is 'ConnectionFactory'</para></listitem>
+ <listitem><para>the destination-type is that of 'queue'</para></listitem>
+ <listitem><para>the destination-name is that of 'queue/A'</para></listitem>
+ </itemizedlist>
+
+ <para>
+ Please bear this in mind when reading through the rest of
+ this material.
+ </para>
+
</important>
- <note>
- <para>
- Each JMSListener and JMSGateway can be configured to use
- it's own JMS provider, so you can use more then one
- provider in your deployment.
- </para>
- </note>
-
- <para>
- When using JMS, JBossESB utilizes a connection pool to
- improve performance. By default the size of this pool is
- set to 20, but can be over-ridden by setting the
- org.jboss.soa.esb.jms.connectionPool property in the
- transports section of the JBossESB configuration file.
- Likewise, if a session cannot be obtained initially,
- JBossESB will keep retrying for up to 30 seconds before
- giving up. This time can be configured using the
- org.jboss.soa.esb.jms.sessionSleep property.
- </para>
-
-
<section>
<title>
Max Sessions Per Connection
</title>
<para>
- The JBoss ESB's JmsConnectionPool pools JMS Sessions and is
- used by all JMS based components – JMS Listeners, JMS
- Couriers, JMS Router etc.
+ As its name implies, the <application>JBoss Enterprise Service
+ Bus</application>'
+ <systemitem>JmsConnectionPool</systemitem> pools JMS
+ Sessions. It is used by all JMS-based components, including
+ listeners, couriers and routers.
</para>
<para>
- Some JMS providers limit the number of JMS Sessions per
- connection. This means that the JMS Components in JBoss ESB
- need to support a control mechanism for the maximum number of
- sessions created from each JMS Connection managed by a single
- JmsConnectionPool instance. This is done simply be specifying
- one or both of the following properties in the JNDI
- configuration of the JMS Component (JMS Provider/Bus, JMSRouter
- etc):
+ Some JMS providers limit the allowed number of JMS sessions per
+ connection. As a result, the <application>JBoss Enterprise
+ Service Bus</application>' JMS components feature a
+ mechanism that controls the maximum number of sessions created
+ from each JMS connection managed by a single
+ <systemitem>JmsConnectionPool</systemitem> instance. To configure
+ this mechanism, simply specify one or both of the following properties in
+ the component's JNDI configuration:
</para>
<itemizedlist>
<listitem>
<para>
- <property>max-sessions-per-connection</property>: This
- is the maximum total number of Sessions allowed per
- connection i.e. XA + non-XA Session instances. This
- value defaults to the maximum number of JMS Sessions
- allowed for a JmsConnectionPool as a whole, which
- defaults to 20 (as configured in the
- jbossesb-properties.xml file).
+ <property>max-sessions-per-connection</property>: this
+ is the maximum total number of sessions allowed per
+ connection (in other words, for
+ <systemitem>XA</systemitem> and
+ <systemitem>non-XA</systemitem> session instances.)
+ This value defaults to the maximum number of JMS
+ sessions allowed for the
+ <systemitem>JmsConnectionPool</systemitem> as a whole,
+ which is twenty (as configured in the
+ <filename>jbossesb-properties.xml</filename> file.)
</para>
</listitem>
<listitem>
<para>
<property>max-xa-sessions-per-connection</property>:
- This is the maximum number of XA Sessions allowed
- per connection i.e. XA only. This value defaults to
- the value of max-sessions-per-connection.
+ this is the maximum number of XA sessions allowed
+ per connection (for XA only.) This value defaults
+ to that which has been set for
+ <property>max-sessions-per-connection</property>.
</para>
</listitem>
</itemizedlist>
<para>
- So if neither of the above parameters are configured, the
- JmsConnectionPool will create a single JMS Connection and
- create all JMS Sessions off that Connection instance.
+ If neither of these parameters are configured, the
+ <systemitem>JmsConnectionPool</systemitem> creates a
+ single JMS connection and derives every session
+ from it.
</para>
<para>
- These configurations should be made as generic property
- configurations on the JMS Provider configuration e.g.
+ Set the parameters as generic properties on
+ the JMS provider configuration. This example code
+ demonstrates how to do so:
</para>
<programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/maxset1.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
@@ -156,52 +277,48 @@
<section id="JBossMessaging">
<title>
- JBossMQ or JBossMessaging
+ JBossMessaging
</title>
<para>
- The settings for JBossMQ and JBossMessaging are identical and
- you should set the parameters to:
+ <application>JBoss Messaging</application> is the
+ <application>JBoss SOA Platform</application>'s default JMS
+ provider.
</para>
- <programlisting><xi:include parse="text" href="extras/configuration/JBossMessaging.settings" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ This is the way in which to set its parameters:
+ </para>
+ <programlisting><xi:include parse="text" href="extras/configuration/JBossMessaging.settings" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<note>
<para>
- For JBossMQ you should have jbossmq-client.jar in your
- classpath. Not that this jar is included in
- jbossall-client.jar, which can be found in lib/ext. For
- JBossMessaging it should be jboss-messaging-client.jar While
- -for now- the JBossMQ is the default JMS provider in
- JBossAS, you can also use JBoss Messaging. Instructions for
- installing JBoss Messaging can be found on the project
- website (<ulink
- url="http://docs.jboss.org/jbossmessaging/docs/userguide-1.4.0.GA/html/installation.html"
- />).
+ Always include the
+ <filename>jboss-messaging-client.jar</filename> file in
+ the class-path. Note that this file is included in the
+ <filename>jbossall-client.jar</filename> archive, which can
+ be found in the <filename>lib/ext</filename> directory.
</para>
</note>
<section id="JBossMessagingClusteringConfiguration">
<title>
- JBoss Messaging Clustering configuration
+ JBoss Messaging Clustering Configuration
</title>
<para>
- Configuring JBoss Messaging in a clustered setup gives you
- loadbalancing and failover for JMS. Since this capability has
- changed between different versions of JBoss Messaging and may
- continue to do so, you should consult the relevant JBoss Messaging
- documentation (<ulink
- url="http://docs.jboss.org/jbossmessaging/docs/userguide-1.4.0.SP1/html_single/index.html#conf.connectionfactory.attributes.loadbalancingfactory"
- />).
+ To gain <firstterm>load balancing</firstterm> and
+ <firstterm>fail-over</firstterm> capabilities, configure
+ <application>JBoss Messaging</application> for
+ <firstterm>clustering</firstterm>.
</para>
<note>
<para>
This functionality is continually changing as <application>JBoss
Messaging</application> evolves. To learn how to configure it,
- consult the relevant <application>JBoss Messaging</application>
- documentation.)
+ consult the <application>JBoss Messaging</application>
+ documentation.
</para>
</note>
@@ -215,44 +332,52 @@
</title>
<para>
- For ActiveMQ you should set the parameters to:
+ To configure <application>ActiveMQ</application>, set these
+ parameters:
</para>
<programlisting><xi:include parse="text" href="extras/configuration/activemq.settings" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
- In your classpath you should have:
+ Configure the class-path like this:
</para>
<programlisting><xi:include parse="text" href="extras/configuration/activemq2.settings" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
- Both jars can be found in lib/ext/jms/activemq. We tested with version 4.1.0-incubator.
+ Both JARs are found in the
+ <filename>lib/ext/jms/activemq</filename> directory. (Red Hat
+ tested version 4.1.0-incubator.)
</para>
</section>
<section id="websphere_mq_series">
- <title>
- Websphere MQ Series
+ <title>
+
+ IBM Websphere MQ Series
</title>
<orderedlist>
<listitem>
<para>
- For Websphere MQ Series, you should set the main JNDI parameters to:
+ Set the main JNDI parameters for the <application>IBM
+ Websphere MQ Series</application> to the following:
</para>
<programlisting><xi:include parse="text" href="extras/configuration/websphere_msq_series.settings" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<note>
<para>
- Websphere likes all CAPS queue names and no slashes (QUEUEA),
- and the name of the Queue Manager in MQ should match what the
- value of 'connection-factory' is (or bind this name to JNDI).
- In our case we created a Queue Manager named
- “ConnectionFactory”.
+ <application>Websphere</application> queue names must be
+ written in capitals and without any slashes (an example is
+ <literal>QUEUEA</literal>). The <systemitem>queue
+ manager</systemitem>'s name should match the value of
+ <property>connection-factory</property> (one could also bind
+ this name to JNDI.) In this example, the <systemitem>queue
+ manager</systemitem> is named
+ <property>ConnectionFactory</property>.
</para>
</note>
@@ -260,16 +385,17 @@
<listitem>
<para>
- You will also need to configure the
- max-xa-sessions-per-connection property to a value of “1”
- if using XA Connections. For more on how to configure this
- property, see the Max Sessions Per Connection section.
+ If using <systemitem>XA connections</systemitem>, set
+ the <property>max-xa-sessions-per-connection</property>
+ property to <code>1</code>. (For more
+ information on how to configure this property, see the
+ "Maximum Sessions per Connection" section of this chapter.)
</para>
</listitem>
<listitem>
<para>
- On your classpath you should have
+ Check that the following items are present on the class-path:
</para>
<itemizedlist>
@@ -287,13 +413,13 @@
<listitem>
<para>
- <filename>com.ibm.mq.jar</filename> (client JAR)
+ <filename>com.ibm.mq.jar</filename> (client <filename>JAR</filename>
</para>
</listitem>
<listitem>
<para>
- <filename>com.ibm.mqjms.jar</filename> (client JAR)
+ <filename>com.ibm.mqjms.jar</filename> (client <filename>JAR</filename>)
</para>
</listitem>
</itemizedlist>
@@ -307,24 +433,20 @@
</para>
</note>
- <warning>
+ <warning>
<para>
- You may get the following exception when running MQ 6.0, which
- can be fixed by adding the user that runs the jbossesb to the
- mqm group:
- </para>
+ The following exception may be encountered when running
+ <application>Websphere MQ 6.0</application>:
+ </para>
<screen>Message: Unable to get a MQ series Queue Manager or Queue Connection. Reason: failed to create connection --javax.jms. JMSSecurityException: MQJMS2013: invalid security authentication supplied for MQQueueManager</screen>
<para>
- Explanation: There is a problem with user permissions or
- access.
+ This is a permissions issue. To fix this problem, add the user
+ responsible for running the <application>JBoss Enterprise
+ Service Bus</application> to the <systemitem>mqm
+ group</systemitem>.
</para>
-
- <para>
- Tip: Make sure the user accessing MQ Queue Manager is part of
- the mqm group.
- </para>
</warning>
</listitem>
@@ -336,11 +458,16 @@
<title>
Oracle AQ
</title>
-
+
+ <para>
+ To run <application>Oracle AQ</application>, undertake the
+ following steps:
+ </para>
+
<orderedlist>
<listitem>
<para>
- For Oracle AQ you should set the parameters to:
+ Set the parameters like this:
</para>
<programlisting><xi:include parse="text" href="extras/configuration/orac1.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
@@ -348,7 +475,7 @@
</listitem>
<listitem>
<para>
- Use the following properties:
+ Use these properties:
</para>
<programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/orac2.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
@@ -356,45 +483,48 @@
</listitem>
<listitem>
<para>
- Optionally specify a database connection url:
+ An alternative way to do this is by specifying a
+ database connection URL:
</para>
<programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/orac3.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<note>
<para>
- The above example can be used to connect to Oracle Real
- Application Cluster (RAC).
+ The example code above can be used to connect to an Oracle Real
+ Application Cluster.
</para>
</note>
<note>
<para>
- You may notice the reference to the InitialContext
- factory. You only need this is if you want to avoid
- OracelAQ to register its queues with an LDAP. The
- AqinitialContextFactory references code in a plugin jar
- that you can find in the
- plugins/org.jboss.soa.esb.oracle.aq directory. The jar
- is called org.jboss.soa.esb.oracle.aq-4.2.jar and you
- will have to deploy it to the jbossesb.sar/lib
- directory.
+ Note the reference to the
+ <classname>InitialContext</classname> factory. One only
+ needs this if one does not want the Oracle AQ to
+ register its queues with an LDAP.
</para>
- </note>
-
- <note>
+
<para>
- When creating a Queue in Oracle AQ make sure to select
- a payload type of SYS AQ$_JMS_MESSAGE.
+ The <classname>AqinitialContextFactory</classname>
+ references code found in the
+ <filename>org.jboss.soa.esb.oracle.aq-4.2.jar</filename>
+ file, found in the the
+ <filename>plugins/org.jboss.soa.esb.oracle.aq</filename>
+ directory. To use it, deploy the file to the
+ <filename>jbossesb.sar/lib</filename> directory.
</para>
- </note>
-
- <note>
+
+ <para>
+ When creating a queue in the Oracle AQ,
+ be sure to select a payload type of <literal>SYS
+ AQ$_JMS_MESSAGE</literal>.
+ </para>
+
<para>
- For a sample you can check the
- samples/quickstarts/helloworld_action/oracle-aq
- directory for an example jboss-esb.xml configuration
- file.
+ An example <filename>jboss-esb.xml</filename>
+ configuration file can be found in the
+ <filename>samples/quickstarts/helloworld_action/oracle-aq</filename>
+ directory.
</para>
</note>
@@ -411,7 +541,7 @@
<orderedlist>
<listitem>
- <para>
+ <para>
For Red Hat MRG you should set the parameters to:
</para>
@@ -447,25 +577,33 @@
</orderedlist>
</section>
+
<section id="tibco_ems">
<title>
- Tibco EMS
+ Tibco Enterprise Message Service
</title>
-
+
+ <para>
+ To use the <application>Tibco Enterprise Message
+ Service</application>, follow these instructions:
+ </para>
+
<orderedlist>
<listitem>
<para>
- For Tibco EMS you should set the parameters to:
- </para>
+ Set these parameters:
+ </para>
- <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/tibco_ems.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <programlisting><xi:include parse="text" href="extras/configuration/tibco_ems.settings" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</listitem>
- <listitem>
- <para>
- In your classpath you should have the client jars that ship
- with Tibco EMS, which are found in the
- tibco/ems/clients/java dir.
+ <listitem>
+ <para>
+ Next, check that the client <filename>JAR</filename> files
+ that ship with the <application>Tibco Enterprise Message
+ Service</application> can be found in the class-path.
+ (These files are located in the
+ <filename>tibco/ems/clients/java</filename> directory.)
</para>
<itemizedlist>
@@ -519,7 +657,7 @@
<note>
<para>
- We tested with version 4.4.1.
+ We tested with version 0.6.
</para>
</note>
@@ -530,30 +668,30 @@
<section id="extension_properties">
<title>
- Extension properties
+ Extension Properties
</title>
<para>
- The JNDI configuration used to retrieve the JMS resources
- will, by default, inherit all properties with names
- prefixed by “java.naming.”. Some JMS providers may,
- however, specify properties that use a different naming
- prefix.
+ By default, the JNDI Java Message Service resource
+ retrieval configuration is set to inherit all of those
+ properties which have names prefixed with
+ "java.naming".
</para>
<note>
<para>
- In order to support these properties we provide a mechanism
- through which the property prefixes can be specified for each
- provider, allowing properties using these additional prefixes
- to be inherited.
+ Some Java Message Service providers specify
+ different naming prefixes. In order to support these different
+ schemes, the software allows one to
+ specify individual property prefixes for each provider.
</para>
<para>
- The prefixes are configured by defining the “jndi-prefixes”
- property on the associated jms-provider element, containing a
- comma separated list of the additional prefixes. The extension
- properties are also configured in the same location.
+ To use this functionality, define the "jndi-prefixes"
+ property for the relevant <property>jms-provider</property>
+ element by adding a comma-separated list of the additional
+ prefixes. (One can also configure the extensions property in
+ this same location.)
</para>
</note>
@@ -565,14 +703,16 @@
<section id="ftp_configuration">
<title>
- FTP Configuration
+ Configuring the File Transfer Protocol
</title>
<para>
- Most configuration options are set on the FTP EPR and
- described in the Programmers Guide. However, the following
- are set at the global scope in the jbossesb-properties
- file:
+ Most configuration options are set via the File Transfer
+ Protocol <firstterm>end point reference</firstterm> (EPR.)
+ These options are described in the <emphasis>Programmers'
+ Guide</emphasis>. However, they can also be
+ set at the global level via these properties found in the
+ <filename>jbossesb-properties</filename> file:
</para>
<itemizedlist>
@@ -582,411 +722,927 @@
</para>
<para>
- When transmitting files via FTP, JBossESB sends them
- over with one file name which prevents them being
- processed, before renaming them in order that they can
- be processed. Unfortunately some FTP servers retain
- locks on the file during the time it is written and then
- renamed, preventing the rename from happening. If this
- happens, JBossESB will attempt to rename the file the
- defined number of times (default 10), sleeping in
- between each attempt, before finally generating an error
- message if the file cannot be renamed.
+ The <application>JBoss Enterprise Server
+ Bus</application> renames all files so that they have
+ the same name prior to their transmission via File
+ Transfer Protocol (this prevents the individual files
+ from being processed until the software then renames
+ them at the other end.) Unfortunately, some File
+ Transfer Protocol servers retain a lock on the file
+ after it has been written, which prevents the renaming
+ process from taking place. If this problem occurs, the
+ Enterprise Service Bus will make a pre-defined number
+ of attempts (the default being ten) to rename the
+ files, ("sleeping" in between.) If it still cannot do
+ so after the maximum number of attempts, it generates
+ an error message.
</para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </itemizedlist>
- </section>
+</section>
+
+ <section id="database_configuration">
+ <title>
+ <remark>Updated</remark>
+ Database Configuration
+ </title>
- <section id="database_configuration">
- <title>Database Configuration</title>
+ <para>
+ The SOA Platform uses a database to
+ <firstterm>persist</firstterm> both registry services and the
+ <systemitem>message store</systemitem>. A database script for
+ the <systemitem>message store</systemitem> is found in the
+ <filename>ESB_ROOT/services/jbossesb/src/main/resources/message-store-sql</filename>
+ directory.
+ </para>
- <para>
- The ESB uses a database for persisting Registry services, and the Message-Store.
- </para>
+<note>
+ <para>
+ The SOA Platform uses <application>jUDDI</application> as its
+ <systemitem>service registry</systemitem>. This means there is no
+ need to use SQL scripts because jUDDI utilises the
+ <firstterm>persistence layer</firstterm> to initialize the database
+ schema.
+ </para>
+</note>
+
+ <para>
+ The <application>JBoss Enterprise Service Bus</application>
+ uses the <application>Hypersonic</application> database by
+ default. Find the data-source definition for this database in
+ <filename><replaceable>${SOA_ROOT}</replaceable>/server/<replaceable>${CONFIG}</replaceable>/deploy/jbossesb.esb/message-store-ds.xml</filename>.
+ </para>
+
+ <important>
+ <para>
+ The <application>Hypersonic</application> database is
+ included for testing and demonstration use only. It is not
+ suitable for production deployment and is not supported by
+ Red Hat.
+ </para>
+ </important>
+
+<orderedlist>
+ <listitem>
+ <para>
+ Ensure that the following pre-requisites are met before
+ commencing this process:
+ </para>
- <para>
- Database scripts for each of these can be found under:
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <command>ant</command> must be installed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the database must already exist
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a user must exist for that database
+ </para>
+ </listitem>
+ </itemizedlist>
- <!-- FIXME: should be a variable list -->
- <para>
- Message-Store: <filename>ESB_ROOT/services/jbossesb/src/main/resources/message-store-sql</filename>
- </para>
-
- <para>
- Service Registry: The service registry is now jUDDI v 3.0.1, which does not use
- SQL scripts but uses the persistence layer to initialize the database schema.
- </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To configure data-sources, use the provided
+ <application>Database Schema Tool</application>. This is an
+ <command>ant</command> script located in the
+ <filename><replaceable>${SOA_ROOT}</replaceable>/tools/schema/</filename>
+ sub-directory. It can be run multiple times to change the
+ configuration but this requires that no additional
+ modifications have been made, otherwise the script may no
+ longer work as expected.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To run the script, use the command <command>ant</command> in
+ the directory. The following output will be displayed:
+ </para>
- <para>
- A few database types and their scripts are provided, and you should be able to
- easily create one for your particular database (if you do, please contribute it
- back to us).
- </para>
+ <screen>[ schema]$ ant
+Buildfile: build.xml
+
+[echo] JBoss SOA Platform
+[echo] ------------------
+[echo] Database Configuration Script
+[echo]
+[echo] This script is used to configure the SOA platform and all it's
+[echo] constituent components against a new RDBMS. Deployment scripts
+[echo] are currently available for the following databases: MySQL,
+[echo] Oracle9i, PostgresSQL, Oracle10g
+[echo] ------------------
+[echo] NOTICE: THIS SCRIPT MAY NOT WORK CORRECTLY IF YOU HAVE MADE MANUAL
+[echo] CHANGES TO THE DATABASE CONFIGURATION.
+[echo] </screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ The script will prompt the user for the input details it
+ requires. These are:
+ <itemizedlist>
+ <listitem>
+ <para>
+ the type of database being used. (Only MySQL,
+ PostgreSQL, Oracle 9i and Oracle 10g are supported at
+ this point in time.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the name of the database instance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the host-name or IP Address of the database.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the TCP port being used for the database instance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the user-name needed to access the database.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the password for this user account.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Alternatively, specify these values in the
+ <filename><replaceable>${SOA_ROOT}</replaceable>/tools/schema/build.properties</filename>
+ file before running the script.
+ </para>
+
+ <important>
+ <para>
+ Always re-deploy the ESB Management Console
+ after configuring the data-source.
+ </para>
+
+ </important>
+ </listitem>
+ </orderedlist>
+
+
- <para>
- For the Message-Store you will need to also update the data-source setting
- properties in the main ESB config file <filename>jbossesb-properties.xml</filename>. The following are
- settings you will need to change, based on the connection information appropriate
- to your environment – these settings are found in the DBSTORE section of the file.
- </para>
-
- <para>
- As long as there is script for your database the ESB will auto-create the schema's
- on startup. By default JBossESB is configured to use a JEE DataSource.
- </para>
- <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/defaultDB_config.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- When running from the standalone bootstrapper use:
- </para>
+<section id="Switching_Databases">
+
+ <title>
+ Switching Databases Manually
+ </title>
+
+<warning>
+ <para>
+ This section is for illustrative purposes only. One should not
+ change databases manually. These instructions have been
+ included in this book to show how the the <application>Schema
+ Tool</application> works and should only be used as a
+ reference.
+ </para>
- <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/bootstrapper_DB_config.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
-
- <variablelist>
- <title>Properties</title>
-
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.conn.manager</term>
- <listitem><para>the db connection manager.</para></listitem>
- </varlistentry>
+ <para>
+ Doing a manual configuration may prevent the
+ <application>Schema Tool</application> from working later.
+ Contact Red Hat Support for assistance if manually
+ configuring the database.
+ </para>
+</warning>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.datasource.name</term>
- <listitem><para>The datasource name (used for JNDI lookup)</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.connection.url</term>
- <listitem><para>this is the db connection url for your database.</para></listitem>
- </varlistentry>
+<para>
+ This section explains how to migrate from the default database
+ (<application>Hypersonic</application>) to
+ <application>Postgres</application>. (These steps will be almost
+ identical for any other database.)
+</para>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.jdbc.driver</term>
- <listitem><para>JDBC Driver</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.user</term>
- <listitem><para>db user</para></listitem>
- </varlistentry>
+<orderedlist>
+<listitem>
+ <para>
+ Remove the <filename>deploy/hsqldb-ds.xml</filename> file and add the
+ following code to a new file named
+ <filename>deploy/postgres-ds.xml</filename>:
+ </para>
+
+<programlisting language="XML"><xi:include parse="text" href="extras/configuration/swtichdb1.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.pwd</term>
- <listitem><para>db password</para></listitem>
- </varlistentry>
+<para>
+ This can be modified to suit one's needs with respect to connection
+ parameters and the like. However, the name of the
+ <property>DS</property> must always be <code>DefaultDS</code>.
+</para>
+</listitem>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.pool.initial.size</term>
- <listitem><para>initial size of db connection pool</para></listitem>
- </varlistentry>
+<listitem>
+<para>
+ Replace the contents of
+ <filename>deploy/jbossesb-registry.sar/juddi-ds.xml</filename> with the same
+ configuration as that created in the previous step (change the database
+ name if need be.) Ensure that <property>jndi-name</property>
+ (<code>juddiDB</code>) is kept.
+</para>
+</listitem>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.pool.min.size</term>
- <listitem><para>minimum size of db connection pool</para></listitem>
- </varlistentry>
+<listitem>
+<para>
+ Replace the contents of
+ <filename>deploy/jbossesb.esb/message-store-ds.xml</filename> with the
+ same configuration that was created in step one (change the database
+ name if need be.) Again, ensure that <property>jndi-name</property>
+ (<code>JBossESBDS</code>) is kept.
+</para>
+</listitem>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.pool.max.size</term>
- <listitem><para>maximum size of db connection pool</para></listitem>
- </varlistentry>
+<listitem>
+<para>
+ Replace the database name in the
+ <filename>deploy/jbossesb.esb/jbossesb-service.xml</filename>
+ file's <code>message-store-sql</code> element with the following:
+</para>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.pool.test.table</term>
- <listitem><para>A table name (created dynamically by pool manager) to test for valid connections in the pool</para></listitem>
- </varlistentry>
+<programlisting language="XML"><xi:include parse="text" href="extras/configuration/swtichdb2.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <varlistentry>
- <term>org.jboss.soa.esb.persistence.db.pool.timeout.millis</term>
- <listitem><para>timeout period to wait for connection requests from pool</para></listitem>
- </varlistentry>
+</listitem>
+<listitem>
+<para>
+ Edit the <filename>jbossesb-registry.sar/META-INF/persistence.xml</filename> file. The
+ <property>hibernate.dialect</property> property must be set to the type
+ of database that is going to be used as the data source. (It may, for
+ example, be
+ <classname>org.hibernate.dialect.PostgreSQLDialect</classname>.)
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+ Replace
+ <filename>deploy/jboss-messaging/hsqldb-persistence-service.xml</filename>
+ with the correct
+ <filename>postgres-persistence-service.xml</filename> file
+ for the version of JBM being used.
+</para>
+
+<para>
+ Note that this needs to match the version. It will not work if there is
+ a mismatch. (These files are found in the the JBM distribution's
+ <filename>src/etc/server/default/deploy</filename> directory.)
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+ Copy the database driver to the server's <filename>lib</filename>
+ directory.
+</para>
+</listitem>
+
+<listitem>
+<para>
+ Start the server.
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+ </section>
+<section id="Using_a_JSR-170_Message_Store">
+
+ <title>
+ Using a JSR-170 Message Store
+ </title>
+
+ <para>
+ The <application>JBoss Service-Oriented Architecture
+ Platform</application> allows one to utilize multiple message
+ store implementations via a plug-in architecture. One viable
+ alternative to the default database message store is the
+ <firstterm>JSR-170</firstterm>-compliant <firstterm>Java Content
+ Repository</firstterm>.
+ </para>
+
+ <para>
+ A Java Content Repository implementation is included. It is called
+ <application>Apache Jackrabbit</application>. To enable it, follow these steps:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Add the following property to the "core"
+ section of the
+ <filename>./deployers/esb.deployer/jbossesb-properties.xml</filename>
+ file (or the root of
+ <filename>deployers/esb.deployer</filename> on
+ AS5):
+ </para>
+
+
+<programlisting language="XML"><xi:include parse="text" href="extras/configuration/jbossesb-properties_1.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ <para>
+ This adds the Java Content Repository plug-in to the list of
+ available message stores. The Java Content Repository can now use
+ either an existing repository via JNDI or it can
+ generate a local stand-alone instance on the Application Server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In order to configure repository access, add the following list
+ of properties to the "dbstore" section of the
+ <filename>jbossesb-properties.xml</filename> file:
+ </para>
+
+<programlisting language="XML"><xi:include parse="text" href="extras/configuration/jbossesb-properties_2.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ <itemizedlist mark='bullet'>
+ <listitem>
+ <para>
+ <property>jcr.jndi.path</property>: this is an optional JNDI
+ path. It determines the location of the repository. If it
+ is not specified, a new repository will be created based
+ upon the settings in the <filename>repository.xml</filename> file (which is
+ located in the root of <filename>jbossesb.sar</filename>.)
+ In this case, the repository data is stored in the
+ <filename>JBossAS/server/{servername}/data/repository</filename>
+ directory.
+ </para>
+ </listitem>
- </variablelist>
-
- <para>
- The Service Registry database information is contained in the <filename>esb.juddi.xml</filename>
- file. 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.
+ <listitem>
+ <para>
+ <property>jcr.username</property>: this is the user
+ name. It is needed in order to obtain a repository session.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <property>jcr.password</property>: this is the password. It is
+ needed in order to access a repository session
</para>
-
- <para>
- JBoss server comes with a pre-installed hypersonic database (HSQLDB). The database
- can only be accessed in the same JVM. The data-source definition can be found in
- the <filename>jbossesb.sar/message-store-ds.xml</filename>.
+ </listitem>
+
+ <listitem>
+ <para>
+ <property>jcr.root.node.path</property>: this is the path
+ relative to the root of the repository in which messages are to
+ be stored.
</para>
+</listitem>
+
+
+</itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ To quickly test that the message store has
+ been configured properly, add the
+ <classname>org.jboss.soa.esb.actions.persistence.StoreJCRMessage</classname>
+ action to an existing service. The action will attempt to
+ store the current message in the Java Content Repository, and will report
+ back if it has worked correctly.
+ </para>
+ </listitem>
+ </orderedlist>
+</section>
+
+
+<section id="message_tracing">
+ <title>
+ Message Tracing
+ </title>
+
+ <para>
+ It is possible to trace any or all of the messages sent through
+ the <application>JBoss Service-Oriented Architecture
+ Platform</application>. This may be of use for any number of
+ reasons, such as the desire to see an audit trail or the need to
+ debug a problematic process. (Note that, in order to be traced.,
+ messages must be uniquely identified via the unique number in the
+ message header's <property>MessageID</property> field. Find more
+ information about this in the <emphasis>Programmers'
+ Guide</emphasis>.)
+ </para>
+
+ <para>
+ The <application>JBoss Service-Oriented Architecture
+ Platform</application>'s components (including
+ <firstterm>gateways</firstterm>, the <firstterm>Service
+ Invoker</firstterm> and the <firstterm>load balancer</firstterm>)
+ are, by default, configured to log all of the interactions that
+ occur between themselves and messages. They do so by generating
+ further log messages which contain the header information
+ associated with the main message. Thus, one can correlate
+ messages sent across multiple Service-Oriented Architecture
+ Platform instances. Identify the log messages by looking for the
+ following output:
+ </para>
+
+<screen><xi:include parse="text" href="extras/configuration/message_tracing_1.output" xmlns:xi="http://www.w3.org/2001/XInclude" /></screen>
+
+ <para>
+ Furthermore, one can enable a "logging" meta-data filter,
+ (<classname>org.jboss.internal.soa.esb.message.filter.TraceFilter</classname>),
+ the only role of which is to record entries in the log whenever a
+ message interacts with a component. Set this filter via the
+ properties in the <property>Filter</property> section of the
+ <filename>JBossESB</filename> configuration file. Note that this
+ filter has no effect upon the input or output message. Whenever a
+ message passes through this filter, one can observer, at the
+ <systemitem>information</systemitem> level, the following:
+ </para>
+
+<screen><xi:include parse="text" href="extras/configuration/message_tracing_2.output" xmlns:xi="http://www.w3.org/2001/XInclude" /></screen>
+
+<screen><xi:include parse="text" href="extras/configuration/message_tracing_3.output" xmlns:xi="http://www.w3.org/2001/XInclude" /></screen>
+
+ <para>
+ The <firstterm>TraceFilter</firstterm> will only log information if
+ the property entitled
+ <property>org.jboss.soa.esb.messagetrace</property> is set to
+ <code>on/ON</code>. (The default setting is <code>off/OFF</code>.)
+ If enabled, every message that passes through it is logged. To gain
+ more precise control over which messages are logged and which are
+ ignored, set the
+ <property>org.jboss.soa.esb.permessagetrace</property> property to
+ <code>on/ON</code> as well. This causes the filter to ignore those
+ messages for which the
+ <property>org.jboss.soa.esb.message.unloggable</property> property
+ is set to <code>yes/YES</code>.
+ </para>
+
+</section>
+
+<section id="clustering_and_failover_support">
+
+ <title>
+ Clustering and Fail-Over Support
+ </title>
+
+ <para>
+ The <application>JBoss Service-Oriented Architecture
+ Platform</application> supports <firstterm>stateless</firstterm>
+ service <firstterm>fail-over</firstterm>. Consult the
+ <emphasis>Programmers' Guide</emphasis> for detailed information on
+ this topic but these are the main points to note:
+ </para>
- <warning>
- <para> Use of HSQLDB for production is not recommended.</para>
- </warning>
-
- <section id="Switching_Databases">
- <title>Switching Databases</title>
+ <itemizedlist mark='bullet'>
+ <listitem>
+ <para>
+ the <systemitem>ServiceInvoker</systemitem> hides much
+ of the fail-over complexity from users but it only
+ works with native Enterprise Service Bus messages and,
+ furthermore, not every gateway has been programmed to
+ use take advantage of it. Hence, non-ESB Aware messages
+ sent to those gateway implementations may not be able
+ to take advantage of service fail-over.
+ </para>
+ </listitem>
- <para>
- This section describes the steps to move from using the default hypersonic
- database to postgres. These steps should be the same for any other database.
- Just replace postgres with the database you want to switch to.
- </para>
-
- <procedure>
- <title>Changing the database to PostgreSQL</title>
- <step>
+ <listitem>
+ <para>
+ when the <systemitem>ServiceInvoker</systemitem> tries
+ to deliver a message to a service it may potentially be
+ given a choice of multiple <firstterm>end-point
+ references</firstterm>. In order to help it determine
+ which one to select, configure a
+ <firstterm>policy</firstterm> by setting the
+ <property>org.jboss.soa.esb.loadbalancer.policy</property>
+ property in the
+ <filename>jbossesb-properties.xml</filename> file.
+ Three policies are provided but custom ones can also be
+ created. The three provided are:
+ </para>
+
+ <orderedlist>
+ <listitem>
<para>
- Remove <filename>deploy/hsqldb-ds.xml</filename> and add the following
- in a file named <filename>deploy/postgres-ds.xml</filename>:
+ first available: if a healthy <systemitem>service
+ binding</systemitem> is found it will be used until
+ it dies. The next end-point reference in the list
+ will then be used.
</para>
- <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/postgres-ds.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
- Modify the above to suite your needs, connection parameters and such.
- Make sure the name of the DS is the same though (DefaultDS)
+ There is no load balancing between the two service
+ instances with this policy.
</para>
- </step>
- <step>
+ </listitem>
+
+ <listitem>
+ <para>
+ round robin: a typical load balancing policy
+ whereby each end-point reference is "hit" in list order.
+ </para>
+ </listitem>
+
+ <listitem>
<para>
- Replace <filename>deploy/jbossesb-registry.sar/juddi-ds.xml</filename>
- with the same configuration in the previous step (change the database
- name if needed).
Again make sure the keep the jndi-name(juddiDB).
+ random robin: this is like the round robin,
+ but the selection is randomized.
</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>
+ The end-point reference list used by the the policy may
+ become smaller over time as "dead" EPRs are removed.
+ When the list is exhausted or the
+ <property>time-to-live</property> of the list cache is
+ exceeded, the <systemitem>ServiceInvoker</systemitem> will obtain a fresh list
+ of EPRs from the <systemitem>registry</systemitem>. The
+ <property>org.jboss.soa.esb.registry.cache.life</property>
+f property defaults to 60000 milliseconds. To alter it,
+ change its setting in the
+ <filename>jbossesb-properties</filename> file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When none of the end-point references work, the
+ <systemitem>Message Re-delivery Service</systemitem> is
+ used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To run the same service on more than one node in a cluster,
+ wait until the service registry cache re-validates.
+ Configure the cache re-validation time-out in the
+ <filename><replaceable>${SOA_ROOT}</replaceable>/server/<replaceable>${CONFIG}</replaceable>/deploy/jbossesb.sar/jbossesb-properties.xml</filename>
+ file (or the
+ <filename>deploy/esb.deployers/jbossesb-properties.xml</filename>
+ file on AS5):
+ </para>
+
+ <programlisting language="XML"><xi:include parse="text" href="extras/configuration/cache_revalidation_timeout.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ </listitem>
+ <listitem>
+
+ <para>
+ To remove from the <systemitem>registry</systemitem> any
+ end-point references that the
+ <systemitem>ServiceInvoker</systemitem> "suspects" has failed,
+ set the
+ <property>org.jboss.soa.esb.failure.detect.removeDeadEPR</property>
+ property to <code>true</code>.
+ </para>
+<warning>
+ <para>
+ Note that the default setting is <code>false</code> because
+ this feature should be used with extreme care. If it is
+ employed, the end-point reference for a service that is
+ simply overloaded and, therefore, slow to respond may,
+ inadvertently, be removed from the
+ <systemitem>registry</systemitem> by mistake. There will be
+ no further interactions with these "orphaned"
+ services one may have to restart them.
+ </para>
+</warning>
+ </listitem>
+ </itemizedlist>
+
+</section>
+
+<section id="OpenSSO_in_SOA">
+ <title>
+ Using OpenSSO in Conjunction with the JBoss Enterprise SOA Platform
+ </title>
+
+ <para>
+ The <application>JBoss Service-Orientated Architecture
+ Platform</application> includes the <firstterm>Open Web
+ SSO</firstterm> project (<application>OpenSSO</application>) service
+ software. This is used in order to simplify the implementation of a
+ transparent <firstterm>Single Sign-On</firstterm> service.
+ </para>
+
+<note>
+ <para>
+ To learn more about the <application>OpenSSO</application>, please
+ visit this website: <ulink url="http://opensso.dev.java.net" />.
+ </para>
+</note>
+
+<section id = "OpenSSO_in_Tomcat">
+
+ <title>
+ Installing and Configuring the OpenSSO in Tomcat
+ </title>
+
+ <important>
+ <para>
+ There is a known issue with deploying
+ <application>OpenSSO</application> on the
+ <application>JBoss Enterprise SOA Platform</application>.
+ However, it can be deployed to other web-containers for use
+ with the SOA Platform.
+ </para>
+
+ <para>
+ Details of the deployment issue can be found at <ulink
+ url="https://jira.jboss.org/jira/browse/SOA-731" />.
+ </para>
+ </important>
+
+ <para>
+ The following instructions teach the reader how to deploy the
+ <application>OpenSSO</application> onto
+ <application>Tomcat</application>. To learn about using the
+ OpenSSO with other web-containers, go to <ulink
+ url="https://opensso.dev.java.net/public/use/docs/fampdf/index.html"
+ />.
+ </para>
+
+
+ <procedure>
+ <title>
+ Deploying the OpenSSO to Tomcat
+ </title>
+ <step>
+
+
+ <para>
+ Download the <application>Tomcat</application> software from the
+ Apache Project's website at: <ulink url="http://tomcat.apache.org" />.
+ </para>
+
+
+ <note>
+ <para>
+ Red Hat customers can obtain and install <application>Tomcat</application> from the
+ software repository, so there is no need to download it from the Apache
+ Project website.
+ </para>
+ </note>
</step>
+
<step>
- <para>
- Replace <filename>deploy/jbossesb.esb/message-store-ds.xml</filename>
- with the same configuration in step one (change the database name if
- needed).
Again make sure the keep the jndi-name(JBossESBDS).
- </para>
+ <para>
+ Extract the archived files into a directory. (The following examples
+ assume that this directory is called
+ <filename>/opt/tomcat</filename>.)
+ </para>
</step>
+
<step>
- <para>
- Replace the database name in the 'message-store-sql' element in
- <filename>deploy/jbossesb.esb/jbossesb-service.xml</filename>:
- </para>
- <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/jbossesb-service.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ <para>
+ Edit the <filename>/opt/tomcat/bin/catalina.sh</filename>
+ shell script (or <filename>catalina.bat</filename> batch
+ file if one is using a Windows deployment) and add
+ <parameter>-Xmx1G</parameter> to the
+ <property>JAVA_OPTS</property> property. (This specifies
+ that the <firstterm>Java Virtual Machine</firstterm>
+ instance's maximum heap size is to be one gigabyte.)
+ </para>
+
+ <para>
+ This code sample demonstrated how to set the
+ maximum size for <property>JAVA_OPTS</property>:
+ </para>
+
+
+
+<programlisting language="Java"><xi:include parse="text" href="extras/configuration/java1.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+
</step>
+ <step>
+
+ <para>
+ Now download <filename>opensso.zip</filename> (build 4.5) from the
+ <application>OpenSSO</application> website: <ulink
+ url="https://opensso.dev.java.net/public/use/index.html" />.
+ </para>
+ </step>
<step>
<para>
- Edit <filename>jbossesb-registry.sar/META-INF/persistence.xml</filename>.
- The hibernate.dialect property must be set to the type of database that
- you are using in your datasource (org.hibernate.dialect.PostgreSQLDialect for example).
+ Extract the contents of <filename>opensso.zip</filename> and copy
+ <filename>opensso.war</filename> from <filename>deployable-war/</filename>
+ to <filename>/opt/tomcat/webapps/</filename>.
</para>
</step>
+ <step>
+ <para>
+ To deploy the <application>JBoss Enterprise Service-Oriented
+ Architecture Platform</application> and
+ <application>Tomcat</application> on the same machine,
+ change the <application>Tomcat</application> port specified
+ in the <filename>$tomcat/server.xml</filename>. This code
+ demonstrates how to do so:
+ </para>
+
+<programlisting language="Java"><xi:include parse="text" href="extras/configuration/java2.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ </step>
<step>
- <para>
- Replace <filename>deploy/jboss-messaging/hsqldb-persistence-service.xml</filename>
- with the <filename>postgres-persistence-service.xml</filename> from the
- version of JBM that you are running.
- </para>
- <para>
- This needs to match the same version and might not work it the
- versions mismatch. These files can be found in
- <filename>src/etc/server/default/deploy</filename> of a JBM distribution.
- </para>
+
+
+ <para>
+ Start <application>Tomcat</application> by running the
+ <filename>/opt/tomcat/bin/startup.sh</filename> shell script (or the
+ <filename>startup.bat</filename> batch file, on a
+ Microsoft Windows deployment.)
+ </para>
+
</step>
+ <step>
+
+ <para>
+ Open <ulink url="http://localhost:8090/opensso" /> in a web
+ browser.
+ </para>
+
+ </step>
<step>
<para>
- Copy the database driver to the servers lib directory and fire up the server.
+ Click on <guilabel>Create Default Configuration</guilabel>.
+ The OpenSSO will configure itself using the default values.
</para>
</step>
-
- </procedure>
-
- </section>
+ <step>
+
- </section>
-
- <section id="Using_a_JSR-170_Message_Store">
-
- <title>Using a JSR-170 Message Store</title>
-
- <para>
- JBossESB allows for multiple message store implementations via a plugin-based
- architecture. As an alternative to the default database message store, a
- JSR-170 (Java content repository) message store may be used. The JCR
- implementation included with JBossESB is Apache Jackrabbit. To enable the JCR
- message store, add the following property to the "core" section of
- jbossesb-properties.xml in the root of the jboss-esb.sar (or the root of
- deployers/esb.deployer on AS5):
- </para>
+ <para>
+ Enter <systemitem>adminpass</systemitem> for the
+ <guilabel>Default User[amAdmin]</guilabel> and
+ <systemitem>ldappass</systemitem> for <guilabel>Default Agent
+ [amldapuser]</guilabel>
+ </para>
- <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/usingJCR-core-jbossesb-properties.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
-
- <para>
- This adds the JCR plugin to the list of available message stores. The JCR
- message store can use an existing repository via JNDI or can create a
- standalone instance locally on the application server. The following list
- of properties should be added in the "dbstore" section of jbossesb-properties.xml
- to configure repository access:
- </para>
+ </step>
- <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/properties-dbstore-jbossesb-properties.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <step>
+
+ <para>
+ Now, open <ulink url="http://localhost:8090/opensso" /> again.
+ Log in using the proper credentials. The user name to input is
+ <systemitem>amAdmin</systemitem> and the password is that which
+ one chose to accompany that name.
+ </para>
+ </step>
+ </procedure>
- <variablelist>
- <title>Properties</title>
- <varlistentry>
- <term>jcr.jndi.path</term>
- <listitem><para>Optional path in JNDI where the repository is found. If not specified, a new repository will be created based on the repository.xml located in the root of jbossesb.sar. In this case, repository data is stored in the JBossAS/server/{servername}/data/repository directory.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>jcr.username</term>
- <listitem><para>Username for getting a repository session </para></listitem>
- </varlistentry>
+ <para>
+ To learn more about installing the
+ <application>OpenSSO</application> on
+ <application>Tomcat</application>, read this weblog entry: <ulink
+ url="http://blogs.sun.com/JohnD/entry/how_to_install_tomcat_6" />.
+ </para>
- <varlistentry>
- <term>jcr.password</term>
- <listitem><para>Password for gettging a repository session</para></listitem>
- </varlistentry>
+</section>
- <varlistentry>
- <term>jcr.root.node.path</term>
- <listitem><para>The path relative to the root of the repository where messages will be stored.</para></listitem>
- </varlistentry>
-
- </variablelist>
-
+<section id="config_opensso_in_SOA-P">
+ <title>
+ Configuring the OpenSSO for the JBoss Enterprise SOA Platform
+ </title>
+ <para>
+ The <classname>AuthContext</classname> class (found in the
+ <filename>openssoclientsdk.jar</filename> Java archive file)
+ performs the authentication process. Undertake the following
+ steps to enable this integration between the
+ <application>OpenSSO</application> and the <application>JBoss
+ Service-Oriented Architecture Platform</application>.
+ </para>
- <para>
- An easy test for whether the JCR message store is configured properly is to add
- the org.jboss.soa.esb.actions.persistence.StoreJCRMessage action onto an
- existing service. The action will attempt to store the current message to the JCR store.
- </para>
-
- </section>
-
-
- <section id="message_tracing">
- <title>Message Tracing</title>
- <para>
- It is possible to trace any and all Messages sent through JBossESB. This may
- be important for a number of reasons, including audit trail and debugging. 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, this is the only way in which Messages can be uniquely identified within
- the ESB.
- </para>
- <para>
- By default, JBossESB components (e.g., gateways, ServiceInvoker and load balancing)
- log all interactions with Messages through standard logger messages. Such log
- messages will contain the entire header information associated with the Message
- which will enable correlation across multiple JBossESB instances. You can identify
- these messages by looking for the following in your output:
- </para>
- <programlisting><xi:include parse="text" href="extras/configuration/logoutput_1.log" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- Furthermore, you can enable a logging MetaData Filter, whose only role is to issue
- log messages whenever a Message is either input to an ESB component, or output
- from it. This filter, org.jboss.internal.soa.esb.message.filter.TraceFilter, can
- be placed within the Filter section of the JBossESB configuration file, in
- conjunction with any other filters: it has no effect on the input or output
- Message. Whenever a Message passes through this filter, you will see the following
- log at info level:
- </para>
- <programlisting><xi:include parse="text" href="extras/configuration/logoutput_2.log" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <procedure>
+ <title>Configuring the OpenSSO for Integration with the JBoss Enterprise SOA Platform</title>
+ <step>
+ <para>
+ Edit the <filename>login-config.xml</filename> file as illustrated
+ below. (This file is located in the server's
+ <filename>conf/</filename> directory.) Do this in order to activate
+ the integration functionality. The full file path may, for
+ example, be
+ <filename>$JBOSS_HOME/server/default/conf/login-config.xml</filename>.
+ </para>
+
+<programlisting language="XML"><xi:include parse="text" href="extras/configuration/opensso_login-config.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+
+
+ <para>
+ Note that the 'orgName' and the 'moduleName' are
+ the same as those that one configured in the
+ <application>OpenSSO</application> system. The last property
+ indicates where, on the system, the
+ <filename>AMConfig.properties</filename> file resides.
+ </para>
+
+ </step>
+ <step>
+
+ <para>
+ Edit the <filename>AMConfig.properties</filename> file. (This file
+ is located in the <filename>conf/props/</filename> subdirectory. The
+ full file path may, for example, be
+ <filename>/jbossas/server/default/conf/props/AMConfig.properties</filename>.)
+ </para>
+
+ <para>
+ By default, it expects the server to be
+ accessible on <systemitem>localhost</systemitem> port
+ <systemitem>8080</systemitem> with the
+ <systemitem>opensso</systemitem> context path. In order to customise
+ these settings, or to adopt a pre-existing, deployed
+ <application>OpenSSO</application>, Red Hat recommends using the
+ <filename>scripts/setup.sh</filename> shell script (or the
+ <filename>setup.bat</filename> batch file on Microsoft Windows
+ deployments).
+ </para>
+
+ <para>
+ Next, run the shell script entitled
+ <filename>/samples/fam-client/sdk/scripts/setup.sh</filename>. (This
+ is found in the <filename>opensso.zip</filename> archive file.)
+ Once it has been run, one will see the following output onscreen:
+ </para>
+
+ <screen>Debug directory (make sure this directory exists): /var/local/tmp
+Password of the server application: opensso1
+Protocol of the server: http
+Host name of the server: putian.nay.redhat.com
+Port of the server: 8080
+Server's deployment URI: opensso
+Naming URL (hit enter to accept default value, http://putian.nay.redhat.com:8080/opensso/namingservice):</screen>
+
+
+ <para>
+ Copy the <filename>AMConfig.properties</filename> from the
+ <filename>$opensso.zip/samples/fam-client/sdk/resources/AMConfig.properties</filename>
+ file.
+ </para>
+
+ <para>
+ For more information about the
+ <application>OpenSSO</application> configuration,
+ please read the documentation to be found at: <ulink
+ url="http://opensso.dev.java.net" />.
+ </para>
+
+ </step>
+ </procedure>
+
+
<para>
- TraceFilter will only log if the property org.jboss.soa.esb.messagetrace is set to
- on/ON (the default setting is off/OFF). By default, if enabled it will log all
- Messages that pass through it. However, for finer grained control you may enable
- finer grained control over which Messages are logged and which are ignored. To do
- this make sure that the property org.jboss.soa.esb.permessagetrace is set to on/ON
- (the default is off/OFF). Once enabled, those Messages with a Property of
- org.jboss.soa.esb.message.unloggable set to yes/YES will be ignored by this filter.
+ Having successfully undertaken the two steps above, one can
+ now use the <systemitem>OpenSSOLogin</systemitem>
+ module as a <firstterm>JAAS plug-in provider</firstterm>.
</para>
-
- </section>
-
- <section id="clustering_and_failover_support">
- <title>Clustering and Fail-Over Support</title>
- <para>
- Beginning with JBossESB 4.2, there is now support for fail-over of stateless
- services. You should consult the Programmers Guide for further details, but
- the pertinent issues to note are:
- </para>
-
- <itemizedlist>
- <listitem>
+
- <para>
- Because ServiceInvoker hides much of the fail-over complexity from users,
- it necessarily only works with native ESB Messages. Furthermore, not all
- gateways have been modified to use the ServiceInvoker, so incoming ESB-unaware
- messages to those gateway implementations may not always be able to take
- advantage of service fail-over.
- </para>
- </listitem>
- <listitem>
- <para>
- When the ServiceInvoker tries to deliver a message to our Service it may
- get a choice of potentially multiple EPRs now. In order to help it determine
- which one to select, you can configure a Policy. In the jbossesb-properties.xml
- you can set the 'org.jboss.soa.esb.loadbalancer.policy'. Right now three
- Policies are provided, or you can create your own.
- </para>
-
- <orderedlist>
- <listitem>
- <para>
- First Available. If a healthy ServiceBinding is found it will be used unless
- it dies, and it will move to the next EPR in the list. This Policy does not
- provide any load balancing between the two service instances.
- </para>
- </listitem>
- <listitem>
- <para>
- Round Robin. Typical Load Balance Policy where each EPR is hit in order of the list.
- </para>
- </listitem>
- <listitem>
- <para>
- Random Robin. Like the other Robin but then random.
- </para>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>
- The EPR list the Policy works with may get smaller over time as dead EPRs
- will be removed from the (cached) list. When the list is exhausted or the
- time-to-live of the list cache is exceeded, the ServiceInvoker will obtain a
- fresh list of EPRs from the Registry. The 'org.jboss.soa.esb.registry.cache.life'
- can be set in the jbossesb-properties file, and is defaulted to 60,000
- milliseconds. What if none of the EPRs work at the moment? This is where we may
- use Message Redelivery Service.
- </para>
- </listitem>
- <listitem>
- <para>
- If you would like to run the same service on more than one node in a cluster
- you have to wait for service registry cache revalidation before the service is
- fully working in the clustered environment. You can setup this cache revalidation
- timeout in deploy/jbossesb.sar/jbossesb-properties.xml
- (or deploy/esb.deployers/jbossesb-properties.xml in AS5) :
- </para>
- <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/cache-life.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </listitem>
+ <para>
+ It can also be used as an identity provider, allowing one to secure
+ the Service-Oriented Architecture Platform:
+ </para>
- <listitem>
- <para>
- If you set the org.jboss.soa.esb.failure.detect.removeDeadEPR property to
- true, then whenever ServiceInvoker suspects an EPR has failed it will remove
- it from the Registry. The default setting is false, because this should be
- used with extreme care: for example, if the service represented by the EPR
- is simply overloaded and slow to respond then it may be excluded from future
- users. Therefore, if you allow ServiceInvoker to remove EPRs it is possible
- orphan services (ones that eventually receive no further interactions) may
- result and you may have to restart them.
- </para>
- </listitem>
- </itemizedlist>
- </section>
+<programlisting language="XML"><xi:include parse="text" href="extras/configuration/opensso_identity_provider.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
-</chapter>
+
+<para>
+ Having studied this chapter, you should now be confident to configure
+ the SOA Platform to meet your company's needs. The rest of the book explains
+ day-to-day administration.
+ </para>
+</section>
+
+
+ </section>
+</chapter>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuring_WebService_Integration.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuring_WebService_Integration.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuring_WebService_Integration.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -5,24 +5,105 @@
]>
<chapter id="config_SW_integration">
- <title>
+ <title>
Configuring Web Service Integration
</title>
<para>
- JBoss ESB 4.8 exposes Webservice Endpoints for through the
- SOAPProcessor action. This action integrates the JBoss
- Webservices v2.x container into JBossESB, allowing you to
- invoke JBossWS Endpoints over any channel supported by
- JBossESB. See the Programmers' Guide for more details.
+ The <application>JBoss Service-Oriented Architecture
+ Platform</application> exposes <firstterm>web service
+ end-points</firstterm> through the
+ <firstterm>SOAPProcessor</firstterm> action. This action
+ integrates the <application>JBoss Webservices</application>
+ container with the Enterprise Service Bus, thereby allowing one to
+ invoke <firstterm>JBossWS</firstterm> end-points over any
+ channel supported by the SOA Platform. Read this chapter to
+ learn how to configure this integration functionality.
</para>
- <important>
+<important>
+ <para>
+ Ensure that <application>JBossWS 2.0.1.SP2</application> (native)
+ or higher is installed on the <application>JBoss Service-Oriented
+ Architecture Platform</application> server. This must be present in
+ order to make the <classname>SOAPProcessor</classname> action
+ available for use.
+ </para>
+
+ <para>
+ Refer to the <emphasis>Programmers' Guide</emphasis> for
+ more information.
+ </para>
+ </important>
+
+ <section>
+ <!-- This section sourced from http://www.jboss.org/jbossesb/docs/4.7/javadoc/esb/org/jboss/soa/esb/actions/soap/proxy/SOAPProxy.html -->
+ <title>
+ What Does a SOAPProxy Do?
+ </title>
+
<para>
- The SOAPProcessor action requires JBossWS 2.0.1.SP2 (native) or
- higher to to be properly installed on your JBoss Application
- Server (v4.2.x.GA).
+ A <firstterm>SOAPProxy</firstterm> consumes an external web
+ service end-point (which might be hosted on
+ <literal>.NET</literal>, another external Java-based
+ application server or <systemitem>LAMP</systemitem>.) It also
+ allows one to "re-publish" a web service end-point via
+ the Enterprise Service Bus. The ESB sits between the ultimate
+ consumer/client (such as a .NET WinForm application) and the
+ producer (which might be, for instance, an
+ <systemitem>RoR</systemitem>-hosted web service.) Its purpose
+ is to provide an abstraction layer, giving
+ these advantages:
</para>
- </important>
-</chapter>
+ <itemizedlist>
+ <listitem>
+ <para>
+ the client and the service can be coupled loosely as
+ they are completely unaware of each other.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the client is no longer connected directly to the
+ remote service's <systemitem>hostname/IP</systemitem>
+ address.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the client can see a modified WSDL, changing the
+ inbound/outbound parameters. (Note that, at a minimum,
+ one must modify the WSDL so that the client is pointing
+ to the end-point exposed by the Enterprise Service Bus,
+ rather than the original end-point.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ one can introduce a SOAP envelope/body transformation via the
+ <systemitem>action chain</systemitem> that will apply to both the
+ inbound request and the outbound response.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ one can implement <firstterm>service
+ versioning</firstterm> since clients can connect to two
+ or more proxy end-points, each with its own WSDL and/or
+ transformations and routing requirements. The Enterprise
+ Service Bus will send the appropriate message to the
+ correct end-point andthen return a response.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the <classname>ContentBasedRouter</classname> class
+ introduces advanced routing functionality.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+
+ </chapter>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Contract_Publishing.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Contract_Publishing.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Contract_Publishing.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -4,108 +4,131 @@
%BOOK_ENTITIES;
]>
-<chapter id="chap-contract_publishing">
+<chapter id="contract_publishing">
+ <title>
+ Contract Publishing
+ </title>
- <title>Contract Publishing</title>
+ <para>
+ Read this chapter to learn how, why and when to use the
+ <application>Contract Application</application>.
+ </para>
+
+ <para>
+ When integrating an end-point, one is sometimes required to provide
+ information about both it and the operations supported by it. This
+ most commonly occurs when one utilises web service end-points
+ exposed by the <systemitem>SOAPProcessor</systemitem> action (as
+ described in the <emphasis>Programmers' Guide</emphasis>.)
+ </para>
- <section id="sect-overview">
- <title>Overview</title>
+ <important>
+ <para>
+ Red Hat is offering the <application>Contract
+ Application</application> as a <emphasis>Technical
+ Preview</emphasis> only at this point in time. It will
+ be replaced by different technology in a later release.
+ </para>
+ </important>
- <!-- FIXME: message action guide doesn't exist anymore -->
<para>
- Integrating to certain ESB endpoints may require information about that endpoint
- and the operations it supports. This is particularly the case for Webservice
- endpoints exposed via the SOAPProcessor action (see Message Action Guide).
+ The <application>Contract Application</application> provides
+ access to this requisite information. To use the application,
+ launch a web browser and go to this address: <ulink
+ url="http://127.0.0.1:8080/contract/" />.
</para>
-
- </section>
- <section id="sect-contract-application">
- <title>"Contract" Application</title>
-
- <important>
- <para>
- This application is only being offered as a Technical Preview.
- It will be superseded in a later release.
- </para>
- </important>
-
+
+ <figure><title>The Contract Application</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/contract_publishing/contract_publishing_application.png" />
+ </imageobject>
+ <textobject><phrase>The Contract Application</phrase></textobject>
+ </mediaobject>
+ </figure>
+
<para>
- For this purpose, we bundle the "Contract" application with the ESB. This
- application is installed by default with the ESB (after running "ant deploy"
- from the install directory of the distro). Note that the Contract application
- is also bundled inside the JBossESB Console. If you are deploying the console,
- you will first need to undeploy the default Contract application. Just remove
- contract.war from the default/deploy folder of your ESB/App Server.
+ The <application>Contract Application</application> groups
+ end-points according to the services with which they are
+ associated. This is known as <firstterm>servicing</firstterm>.
</para>
-
+<note>
<para>
- It can be accessed through the URL <ulink url="http://localhost:8080/contract/" />.
+ Some of the end-points have a
+ <guilabel>Contract</guilabel> hyperlink. (The ones visible in
+ the screen-shot are for those web service end-points exposed
+ via the <systemitem>SOAPProcessor</systemitem>. The hyperlinks
+ connect via the <systemitem>WSDL</systemitem>.)
</para>
+</note>
+
+
+<section id="publishing_a_contract_from_an_action">
+ <title>
+ Publishing a Contract from an Action
+ </title>
<para>
- <xref linkend="fig-contract_app_screenshot" /> is a screenshot of this application.
+ The <application>JBoss Enterprise SOA Platform</application>
+ "discovers" end-point contracts via the <systemitem>action
+ pipeline</systemitem>.
+ </para>
+<orderedlist>
+ <listitem>
+ <para>
+ Firstly, it looks for the first
+ <systemitem>action</systemitem> in the
+ <systemitem>pipeline</systemitem> that can publish contract
+ information. (If none of the actions can do so, then the
+ <application>Contract Application</application> displays the
+ words, <screen>Unavailable on Contract</screen>.)
</para>
-
- <figure id="fig-contract_app_screenshot">
- <title>The Contract Application</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/contract_publishing/contract_app.png" width="100%" scalefit="1" contentdepth="100%" />
- </imageobject>
- <textobject><phrase>A Screen-shot of the
- Contract Application</phrase></textobject>
- </mediaobject>
- </figure>
-
+ </listitem>
+ <listitem>
<para>
- As you can see, it groups the endpoint according to Service with which they are
- associated (servicing). Another thing you'll notice is how some of them have an
- active "Contract" hyperlink. The ones visible here are for Webservice endpoints
- exposed via the SOAPProcessor. This hyperlink links off to the WSDL.
+ In order to publish contract information, an
+ <systemitem>action</systemitem> must be given the following
+ <classname>org.jboss.internal.soa.esb.publish.Publish</classname>
+ annotation. (This example uses the
+ <systemitem>SOAPProcessor</systemitem> for demonstrative
+ purposes):
</para>
-
-
- </section>
-
- <section id="sect-publishing_contract_from_action">
- <title>Publishing a Contract from an Action</title>
-
+<programlisting language="Java"><xi:include parse="text" href="extras/configuration/SOAPProcessor.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+<note>
<para>
- JBossESB discovers endpoint contracts based on the action pipeline that's
- configured on a Service. It looks for the first action in the pipeline that
- publishes contract information. If none of the actions publish contract
- information, then the Contract application just displays "Unavailable" on
- Contract for that endpoint.
+ Find example <systemitem>SOAPProcessor</systemitem> source code here:
+ <ulink url="http://anonsvn.jboss.org/repos/labs/labs/jbossesb/branches/JBESB_4_7_CP/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/SOAPProcessor.java" />.
</para>
+</note>
+ </listitem>
+ <listitem>
<para>
- An Action publishes contract information by being annotated with the
- org.jboss.internal.soa.esb.publish.Publish annotation as follows
- (using the SOAPProcessor as an example):
+ Next, implement
+ <interfacename>org.jboss.soa.esb.actions.soap.ContractPublisher</interfacename>.
+ (One only need implement a single method):
</para>
- <programlisting language="Java" role="JAVA">@Publish(WebserviceContractPublisher.class)
-public class SOAPProcessor extends AbstractActionPipelineProcessor {
- ...
-}</programlisting>
+<programlisting language="XML"><xi:include parse="text" href="extras/configuration/java4.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+<note>
<para>
- See the SOAPProcessor code as an example at <ulink url="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/SOAPProcessor.java" />.
+ To view an example, depicting
+ <interfacename>JBossWSWebserviceContractPublisher</interfacename>
+ code, go here: <ulink
+ url="http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/JBossWSWebserviceContractPublisher.java" />.
</para>
+</note>
+ </listitem>
+ </orderedlist>
<para>
- You then need to implement a "ContractPublisher" (org.jboss.soa.esb.actions.soap.ContractPublisher),
- which just requires implementation of a single method:
+ Having read this chapter, the reader
+ now knows why and how to use the <application>Contract
+ Application</application>.
</para>
- <programlisting language="Java" role="JAVA">public ContractInfo getContractInfo(EPR epr);</programlisting>
-
- <para>
- See the WebserviceContractPublisher code as an example at <ulink url="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/WebserviceContractPublisher.java" />.
- </para>
-
- </section>
-
-
+ </section>
+
</chapter>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Default_ReplyTo_EPR.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Default_ReplyTo_EPR.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Default_ReplyTo_EPR.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -6,57 +6,69 @@
<chapter id="default_replyto_EPR">
<title>
- Default ReplyTo EPR
+ Default "ReplyTo" End-Point References
</title>
<para>
- JBossESB uses Endpoint References (EPRs) to address messages
- to/from services. As described in the Programmers Guide, messages
- have headers that contain recipient addresses, sequence numbers
- (for message correlation) and optional addresses for replies,
- faults etc. Because the recommended interaction pattern within
- JBossESB is based on one-way message exchange, responses to
- messages are not necessarily automatic: it is application dependent
- as to whether or not a sender expects a response.
+ The <application>JBoss Enterprise SOA Platform</application> uses
+ end-point references to transmit messages to and from services. As
+ described in the <emphasis>Programmers' Guide</emphasis>, messages
+ have <systemitem>headers</systemitem>. These contain recipient
+ addresses and sequential numbers (the latter being used for the
+ purpose of correlation.) One can optionally add additional
+ addresses to <systemitem>headers</systemitem> for replies, faults
+ and so forth. Because the interaction pattern most recommended by
+ Red Hat is based on one-way message exchange, responses may not
+ necessarily be received automatically: it is dependent on the
+ individual application as to whether or not a sender expects a
+ response.
</para>
<para>
- As such, a reply address (EPR) is an optional part of the header
- routing information and applications should be setting this value
- if necessary. However, in the case where a response is required and
- the reply EPR (ReplyTo EPR) has not been set, JBossESB supports
- default values for each type of transport. Some of these ReplyTo
- defaults require system administrators to configure JBossESB
- correctly.
+ The reply address is optional. The application sets it if it is
+ needed. When a response is required and the
+ <systemitem>ReplyTo</systemitem> end-point reference has not been
+ configured, the <application>JBoss Enterprise SOA
+ Platform</application> uses the default setting. (There are a range
+ of these, each specific to a different type of transport.) Note
+ that some of these defaults will only work correctly if additional
+ configuration work has been performed:
</para>
<itemizedlist>
<listitem>
<para>
- For JMS, it is assumed to be a queue with a name based on
- the one used to deliver the original request: <request
- queue name>_reply
+ in the case of the Java Messaging Service, the software
+ assumes a queue will be used and that this queue
+ will have the same name as that which was used to deliver
+ the original request, (this is the name that is prefixed with
+ '_reply.')
</para>
</listitem>
<listitem>
<para>
- For JDBC, 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. The new
- table needs the same columns as the request table.
+ in the case of the JDBC, the software assumes that a table
+ in the same database with the same name as that which was
+ used to deliver the original request is to be used. (This is
+ prefixed with '_reply_table.') Also, please bear
+ in mind that the new table needs the same columns as the
+ request table.
</para>
</listitem>
<listitem>
<para>
- For files (both local and remote), 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.
+ if local and remote files being used, then no
+ administrative changes are required. Responses are written
+ into the same directory as the request, albeit with a unique
+ suffix in order to ensure that only the original sender will
+ receive the response.
</para>
</listitem>
</itemizedlist>
-
+<para>
+ The reader now has an understanding of how replying works and how
+ to configure the system to utilise these.
+ </para>
</chapter>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Hot_Deployment.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Hot_Deployment.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Hot_Deployment.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -10,32 +10,35 @@
</title>
<para>
- JBossAS as well as the JBossESB-Server are always checking the
- 'deploy' directory for new files to deploy. So we're really talking
- about hot redeployment. So here is what you have to do to make it
- redeploy an existing deployment for the different components.
+ The <application>JBoss Service-Oriented Architecture
+ Platform</application> supports <firstterm>hot
+ deployment</firstterm>. Read this chapter to learn about this
+ feature and how to configure the server to best use it.
</para>
-
+
<orderedlist>
<listitem>
<para>
<filename>SAR</filename> files
</para>
<para>
- The jbossesb.sar is hot deployable. It will redeploy
- when
+ The <filename>jbossesb.sar</filename> is hot deploy-able.
+ It will re-deploy when:
</para>
<itemizedlist>
<listitem>
<para>
- the timestamp of the archive changes, if the sar is compressed archive.
+ the archive's time-stamp changes, (if the
+ <filename>SAR</filename> file is compressed.)
</para>
</listitem>
<listitem>
<para>
- the timestamp of the META-INF/jboss-service.xml
- changes, if the sar is in exploded from.
+ the timestamp of the
+ <filename>META-INF/jboss-service.xml</filename> file
+ changes, (if the <filename>SAR</filename> file is in exploded
+ form.)
</para>
</listitem>
</itemizedlist>
@@ -44,97 +47,124 @@
<para>
<filename>ESB</filename> files
</para>
+
<para>
- Any *.esb archive will redeploy when
+ Any <filename>*.esb</filename> archive will re-deploy when:
</para>
<itemizedlist>
<listitem>
<para>
- the timestamp of the archive changes, if the esb is
- compressed archive.
+ the time-stamp of the archive changes, (if the
+ <filename>ESB</filename> file is compressed.)
</para>
</listitem>
<listitem>
<para>
- the timestamp of the META-INF/jboss-esb.xml changes, if
- the esb is in exploded from.
+ the <filename>META-INF/jboss-esb.xml</filename> file's
+ time-stampchanges, (if the <filename>ESB</filename> is
+ in exploded form.)
</para>
</listitem>
</itemizedlist>
<para>
- Our actions have lifecycle support, so upon hot
- deployment it goes down gracefully, finishes active
- requests, and does not accept any more incoming
- messages until it is back up. All of this can be done
- by simply redeploying the .esb archive. If you want to
- update just one action, you can use groovy scripting to
- modify an action at runtime (see the groovy QuickStart:
- <ulink
+ The actions have <firstterm>life-cycle
+ support</firstterm>. This means that, upon hot
+ re-deployment, they terminate "gracefully," by
+ finishing active requests. They will not accept any
+ more incoming messages until they are re-started. (All
+ of this occurs automatically.) In order to update just
+ one action, use <application>Groovy</application>
+ scripting to modify it at run-time (see the
+ <systemitem>Groovy Quick Start</systemitem> at <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossESBQuickStart"
- />.)
- </para>
+ /> for more information.)
+ </para>
+
</listitem>
-
- <listitem>
+ <listitem>
+
<para>
- rule files
+ Rule Files
</para>
<para>
- There are two options to refresh rule files (drl or dsl)
+ There are two ways in which to refresh rule files
+ (the <filename>DRL</filename> and <filename>DSL</filename> files):
</para>
<orderedlist>
<listitem>
<para>
- redeploy the jbrules.esb (see 2)
+ by re-deploying the <filename>jbrules.esb</filename> archive.
</para>
</listitem>
<listitem>
<para>
- turn on the 'ruleReload' in the action config (see
- <ulink
+ by activating the <firstterm>Action
+ Configuration</firstterm>'s <code>ruleReload</code>
+ feature (see the "JBossESBContentBasedRouting"
+ article at <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossESBContentBasedRouting"
- />). Now if a rule file *changes* it will be
- reloaded. .) After doing so, if a rule file is
- changed, it will be re-loaded.
+ /> for more information.) After activating this
+ functionality, if a rule file changes, it is
+ re-loaded automatically.
</para>
</listitem>
</orderedlist>
</listitem>
+ <listitem>
+
- <listitem>
+
<para>
- transformation files
- </para>
+ There are also two ways in which to refresh <firstterm>transformation
+ files</firstterm>:
+ </para>
- <para>
- The only way to refresh transformation files is to
- redeploy the esb archive in which the transformation
- file resides.
- </para>
+ <orderedlist>
+ <listitem>
+
+ <para>
+ by re-deploying the <filename>ESB</filename> archive
+ in which the file resides.
+ </para>
+
+ </listitem>
+ <listitem>
+
+ <para>
+ by using the <application>Enterprise Service
+ Bus Console</application> to send out a
+ notification message over the Java Message
+ Service (<systemitem>topic</systemitem>). The
+ <application>Smooks</application> processors
+ will receive this event and it will cause them
+ to automatically re-load.
+ </para>
+
+ </listitem>
+ </orderedlist>
</listitem>
<listitem>
+
<para>
- Business Process Definitions
+ Use the <application>Eclipse</application> plug-in to
+ deploy a new version of the <application>JBoss Business
+ Process Management Tool</application>'s
+ <firstterm>business process definitions</firstterm> to
+ the jBPM database. Please be aware that only a fresh
+ process instance will use this new version. Existing
+ process life-cycles will still use the previous
+ definition. (For more information, refer to the
+ <emphasis>jBPM User Guide</emphasis>.)
</para>
-
- <para>
- When using jBPM new Business Process Definitions can be
- deployed. From within the jBPM eclipse plugin you can
- deploy a new definition to the jbpm database. New
- process instances will get the new version, in flight
- processes will finish their life cycle on the previous
- definitions. For details please see the documentation
- on jBPM.
- </para>
</listitem>
</orderedlist>
@@ -142,18 +172,28 @@
<section id="standalone_bootstrap_mode">
<title>
- Standalone (bootstrap) mode
+ Stand-Alone ("Bootstrap") Mode
</title>
<para>
- The bootstrapper does not deploy esb archives. You can only have
- one jboss-esb.xml configuration file per node. It will monitor
- the timestamp on this file and it will reread the configuration
- if a change occurs. To updates rules you will have to use the
- 'ruleReload'. And finally to update BPDs you can follow the same
- process mentioned above.
+ Be aware that Enterprise Service Bus archives will not be
+ deployed when the <firstterm>Boot-Strapper</firstterm> mode is
+ active. There can be only one <filename>jboss-esb.xml</filename>
+ configuration file per node. The node monitors the time-stamp
+ on this file and re-reads its contents if a change occurs. In
+ order to updates rules, use the
+ <systemitem>ruleReload</systemitem> functionality.
</para>
-
+ <para>
+ To update <systemitem>business process
+ definitions</systemitem>, use the same process as outlined
+ above.
+ </para>
+ <para>
+ Having studied this chapter, the reader now undestands hot
+ deployment and re-deployment and ways in which these can be
+ utilised.
+ </para>
</section>
</chapter>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/JON_for_SOA.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/JON_for_SOA.xml (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/JON_for_SOA.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,304 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<section id="JON_for_SOA">
+ <title>
+ JON for SOA
+ </title>
+
+ <para>
+ The <application>JBoss Operations Network</application> (JON)
+ program is an additional tool that system administrators can use to
+ monitor and administer JBoss SOA Platform servers. Read this
+ chapter to learn more about it.
+ </para>
+
+ <para>
+ JON allows one to undertake inventory, administrative,
+ monitoring, deployment and update tasks. It performs these jobs
+ by applying a centrally-managed model and utilises a customisable
+ web-portal interface.
+ </para>
+
+<note>
+ <para>
+ To learn more about the <application>JBoss Operations
+ Network</application> project, visit <ulink
+ url="http://www.jboss.com/products/jbosson" />.
+ </para>
+</note>
+
+ <para>
+ <firstterm>JON for SOA</firstterm> is a stand-alone version of JON.
+ It includes additional functionality designed specifically for the
+ JBoss SOA Platform. This section provides an overview of that
+ functionality and assumes that the readership already has a basic
+ knowledge of the <application>JBoss Operations
+ Network</application> product.
+ </para>
+
+
+ <!-- SOA 1531 -->
+
+ <note>
+ <para>
+ The <firstterm>JON for SOA</firstterm> plug-in only works with
+ <application>OpenJDK</application> version 1.6.
+ </para>
+ </note>
+
+
+ <section>
+ <title>
+ Adding a JBoss SOA Platform Server to the JON Inventory
+ </title>
+
+ <para>
+ The JBoss SOA Platform Server will appear in JON as a resource
+ of the type <property>JBossAS Server</property>. The
+ accompanying description will read "JBoss Enterprise SOA
+ Platform".
+ </para>
+
+ <important>
+ <para>
+ One will see an error message when JON accesses the
+ SOA Platform Server for the first time. This is simply because
+ it has not yet been provided with the authentication details
+ it needs.
+ </para>
+
+
+ <para>
+ To rectify this, configure a SOA user account by modifying the
+ settings in the
+ <filename><replaceable>${SOA_ROOT}</replaceable>/server/<replaceable>${CONFIG}</replaceable>/conf/props/soa-users.properties</filename>
+ file. Another way to access these settings is by selecting the
+ <guilabel>Server</guilabel> and then clicking on the
+ <guilabel>INVENTORY</guilabel> tab. (The error message
+ described above also contains a shortcut link to the
+ <guilabel>Connection Properties</guilabel> page.) Once there, go
+ to <guilabel>Connection Properties</guilabel> and add the
+ user-name and password to <property>Principal</property> and
+ <property>Credentials</property> respectively.
+ </para>
+ </important>
+
+ </section>
+
+ <section>
+
+ <title>
+ JBoss SOA Platform Enterprise Service Bus Statistics
+ </title>
+
+ <para>
+ Once the SOA Platform server has been correctly configured, one
+ will find that <guimenuitem>JBoss ESB Statistics</guimenuitem> now
+ appears as an item above the <guilabel>Resources</guilabel> menu
+ entry.
+ </para>
+
+ <para>
+ Click on <guimenuitem>JBoss ESB Statistics</guimenuitem> to "drill
+ down" to see various levels of statistics. At the first level, the
+ figures displayed are a summary for the overall ESB instance.
+ </para>
+
+ <para>
+ Click on the <guilabel>JBoss ESB Deployment</guilabel> item to view
+ a list of all of the Enterprise Service Bus packages deployed on
+ the server. One will not see any statistics at this level but, from
+ here, one can select a deployment and drill down into it to view
+ them. Drill down further still to view details for the services and
+ actions of which that deployment consists.
+ </para>
+
+ <para>
+ Different metrics are displayed depending on the level selected.
+ The following lists summarise all of the ones available:
+ </para>
+
+
+ <itemizedlist><title>At the ESB Level</title>
+ <listitem><para>Message Count (Successful)</para></listitem>
+ <listitem><para>Message Count (Total)</para></listitem>
+ <listitem><para>Message Counts (Failed) - SOA-1855</para></listitem>
+ <listitem><para>Processed Bytes</para></listitem>
+ <listitem><para>Last Failed Message Date</para></listitem>
+ <listitem><para>Last Successful Message Date</para></listitem>
+
+ </itemizedlist>
+
+
+ <itemizedlist><title>At the Service Level</title>
+ <listitem><para>Message Count</para></listitem>
+ <listitem><para>Message Count (avg) per Minute</para></listitem>
+ <listitem><para>Overall Bytes</para></listitem>
+ <listitem><para>Overall Bytes Failed</para></listitem>
+ <listitem><para>Overall Bytes Processed</para></listitem>
+ <listitem><para>Overall Service Time Processed</para></listitem>
+
+ </itemizedlist>
+
+
+ <itemizedlist><title>At the Action Level</title>
+ <listitem><para>Message Count</para></listitem>
+ <listitem><para>Message Count (avg) per Minute</para></listitem>
+ <listitem><para>Messages Failed</para></listitem>
+ <listitem><para>Messages Failed (avg) per Minute</para></listitem>
+ <listitem><para>Messages Successfully Processed</para></listitem>
+ <listitem><para>Messages Successfully Processed (avg) per Minute</para></listitem>
+ <listitem><para>Overall Bytes</para></listitem>
+ <listitem><para>Overall Bytes Failed</para></listitem>
+ <listitem><para>Overall Bytes Processed</para></listitem>
+ <listitem><para>Processing Time</para></listitem>
+
+ </itemizedlist>
+
+
+ <itemizedlist><title>At the Listener Level</title>
+ <listitem><para>Life-cycle State</para></listitem>
+ <listitem><para>Maximum number of threads</para></listitem>
+ <listitem><para>MEP</para></listitem>
+ <listitem><para>Service Category</para></listitem>
+ <listitem><para>Service Description</para></listitem>
+ <listitem><para>Service Name</para></listitem>
+ <listitem><para>Start Date</para></listitem>
+
+ </itemizedlist>
+
+ <para>
+ Use these statistics to configure any standard <application>JBoss
+ Operations Network</application> function, (such as
+ <systemitem>alerts</systemitem>), for any Enterprise Service Bus
+ deployment, service or action.
+ </para>
+
+ <figure><title>Displayed Metrics</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/jon/JON_SOA_indicators.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section>
+ <title>
+ Managing Deployed Enterprise Service Bus Archives
+ </title>
+
+ <para>
+ One can also use the <application>JON for SOA</application>
+ plug-in to deploy or delete Enterprise Service Bus archives. To
+ do so, go to the <guilabel>JBoss ESB Statistics</guilabel>
+ screen and click on the <guilabel>INVENTORY</guilabel> tab. One
+ will find the requisite functionality under <guilabel>Child
+ Resources</guilabel>.
+ </para>
+
+ <para>
+ Deploy a new archive by going to the
+ <guilabel>Create New</guilabel> menu and selecting
+ <guimenuitem>JBoss ESB Deployment</guimenuitem>. Then, on the
+ <guilabel>Create New Resource</guilabel> page, specify which
+ archive to deploy and to where it should be sent (which, under
+ normal circumstance, will be one's <filename>deploy</filename>
+ directory.) (Remember that only compressed files can be uploaded:
+ use the <guilabel>Deploy Zipped</guilabel> option to determine
+ whether it should be deployed as a compressed or an exploded
+ archive.)
+ </para>
+
+ <para>
+ To delete existing archives, simply go to the <guilabel>Child
+ Resources</guilabel> list, tick the entries for the ones to be
+ removed and then click <guilabel>DELETE</guilabel>.
+ </para>
+
+ <note>
+ <para>
+ One can view historical "deploy" and "delete" requests here as
+ well.
+ </para>
+</note>
+ </section>
+ <section>
+
+ <title>
+ Automatic Service Discovery
+ </title>
+
+ <para>
+ The <firstterm>JBoss Operations Network Agent</firstterm>
+ automatically detects those Enterprise Service Bus archives that
+ have been deployed or deleted independently of itself. Note that
+ newly-deployed ESB archives are added to the server's inventory
+ automatically but deleted archives are not automatically removed.
+ </para>
+
+
+ <para>
+ The <systemitem>agent</systemitem> performs this "service
+ discovery" check once every twenty-four hours. There are two ways
+ in which to change this time period setting:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ by editing the <filename>conf/agent-configuration.xml</filename> file.
+ (Restart the agent for this to take effect.) Here is an
+ example that shows how to do so:
+ </para>
+
+
+<programlisting language="XML"><xi:include parse="text" href="extras/jbpm_console/java3.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+
+ </listitem>
+ <listitem>
+ <para>
+ by using the <application>JON Console</application> to edit the configuration.
+ </para>
+
+ <para>
+ One can add JBoss Operations Network
+ <systemitem>agents</systemitem> to the inventory of server
+ resources. Once they have been added added, modify their
+ settings by going to their <guilabel>CONFIGURE</guilabel>
+ tabs and changing the <guilabel>Service Discovery
+ Period</guilabel> value. (There is no need to restart the
+ <systemitem>agent</systemitem> for the change to take
+ effect.)
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ In contrast to the SOA Platform's embedded consoles, there is
+ no way to force the <application>JBoss Operations Network
+ Console</application> to perform an immediate collection of new
+ data. Clicking on buttons such as <guilabel>Get Current
+ Values</guilabel> (found under the <guilabel>Metric
+ Data</guilabel> tab) only updates the display to reflect the
+ most recently collected data. To obtain an immediate update,
+ reset the collection period to a very low value, such as thirty
+ seconds. (Remember to set the interval back to the previous
+ figure afterwards.)
+ </para>
+
+<important>
+ <para>
+ Do not set the figure too low or performance will suffer.
+ </para>
+</important>
+ <para>
+ Having read this chapter, the system administrator now understands
+ the capabilities of JON for SOA and knows how to configure and use this
+ tool effectively.
+ </para>
+ </section>
+
+</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Monitoring_and_Management.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Monitoring_and_Management.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Monitoring_and_Management.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -10,26 +10,26 @@
</title>
<para>
- There are a number of options for monitoring and managing your ESB
- server. Shipping with the ESB are a number of useful JMX MBeans
- that help administrators monitor the performance of their server.
+ The JBoss Enterprise SOA Platform provides several monitoring and
+ management tools. Read this chapter to learn about them.
</para>
- <para>
- Under the jboss.esb domain, you should see the following MBean
- types:
- </para>
-
+
+ <para>
+ In the <systemitem>jboss.esb</systemitem> domain, one will see
+ the following <systemitem>M-Beans</systemitem>:
+ </para>
+
<variablelist>
<varlistentry>
<term>deployment=<ESB package name></term>
<listitem>
<para>
- 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.
+ The <systemitem>Deployments M-Bean</systemitem>
+ shows the status of every deployed ESB packages. It
+ also provides information about their XML
+ configurations.
</para>
</listitem>
</varlistentry>
@@ -37,12 +37,13 @@
<term>listener-name=<Listener name></term>
<listitem>
<para>
- All deployed listeners are displayed, with
- information on their XML configuration, the start
- time, maxThreads, state, etc. The administrator has
- the option of
- initialising/starting/stopping/destroying a
- listener.
+ This <systemitem>M-Bean</systemitem> lists every
+ <firstterm>listener</firstterm> deployed. It shows
+ information about their XML configurations, start
+ times, <systemitem>maxThreads</systemitem> and
+ states. From here, the system administrator has the
+ option of initializing, starting, stopping or
+ destroying each listener.
</para>
</listitem>
</varlistentry>
@@ -50,10 +51,11 @@
<term>category=MessageCounter</term>
<listitem>
<para>
- 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, as
- well as the processing time of each message.
+ The message counters display all of the services
+ deployed for a <systemitem>listener</systemitem>,
+ each service's separate actions and counts of
+ how many messages were processed, as well as the
+ time taken to process each message.
</para>
</listitem>
</varlistentry>
@@ -61,10 +63,11 @@
<term>service-name=<Service name></term>
<listitem>
<para>
- Displays statistics per-service (message counts,
- state, average size of message, processing time,
- etc). The message counts may be reset and services
- may be stopped and started.
+ This M-Bean displays a variety of statistics for
+ each service, including message counts, state,
+ average size and processing time. The message
+ counts may be reset and services may be started and
+ stopped.
</para>
</listitem>
</varlistentry>
@@ -72,9 +75,11 @@
<note>
<para>
- Additionally, jms domain MBeans show statistics for message
- queues, which is useful information when debugging or
- determining performance.
+ In addition to the M-Beans listed above, the Java Message
+ Service domain provides some extra ones that show statistics
+ for <systemitem>message queues</systemitem>. This information
+ can be quite useful when one is debugging the system or analysing
+ performance.
</para>
</note>
@@ -87,37 +92,61 @@
<para>
- JBossESB provides management and monitoring through Embedded JOPR:
- (<ulink url="http://localhost:8080/admin-console" />).
+ The <application>JBoss Enterprise SOA Platform</application>
+ provides monitoring and management functionality through the
+ <firstterm>Monitoring and Management Console</firstterm>. Access this console by loading
+ <ulink url="http://localhost:8080/admin-console" /> in a web
+ browser.
</para>
- <para>
- The JBossESB monitoring console gathers information on the
- performance of different ESB services that are deployed . As of
- JBoss ESB 4.2.0.GA, the monitoring console allows users to get
- message counts by service, action, and node, as well as other
- information like processing time, number of failed messages, bytes
- transferred, and last successful and failed message date time. As
- of JBoss ESB 4.6, the previous ESB monitoring tool has been
- deprecated.
- </para>
+<para>
+ The Console gathers statistics on the performance of each deployed ESB
+ service. It displays message counts by service, action, and node. It
+ also displays other useful information such as:
+</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ processing times
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ numbers of failed messages
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ bytes transferred
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the date-time stamps of
+ the last successful and failed messages
+ </para>
+ </listitem>
+ </itemizedlist>
+<note>
<para>
- The monitoring console is installed automatically in the
- stand-alone ESB server and JBossAS.
+ The Monitoring and Management Console is installed automatically
+ with both the stand-alone Enterprise Service Bus server and
+ JBossAS.
</para>
-
+</note>
<para>
- Below is a screenshot of the console. The console requests
- MBean information from each node within the ESB registry,
- and then displays it back.
+ Here is a a screen-shot of the Console displaying M-Bean
+ information from each of the Enterprise Service Bus
+ <systemitem>registry</systemitem>'s nodes.
</para>
<figure>
<title>JBoss Monitoring and Management Console</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/monitoring_and_management/er7b.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/monitoring_and_management/er7b.png" />
</imageobject>
<textobject>
<phrase>A Screen-shot of the JBoss Monitoring and Management Console</phrase>
@@ -133,21 +162,42 @@
</title>
<para>
- Each ESB service is displayed along with the
- processing time per action, processed count per
- action, failed count per action, and overall
- message count (per service).
+ The Console displays each ESB service and provides
+ the following information about them:
</para>
- <para>
- See below:
+<itemizedlist>
+ <listitem>
+ <para>
+ processing time per action,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ processed count per action
</para>
+ </listitem>
+ <listitem>
+ <para>
+ failed count per action
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ overall message count (per service)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Here is a screenshot displaying this functionality:
+ </para>
+
<figure><title>Services</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/monitoring_and_management/services.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/monitoring_and_management/services.png" />
</imageobject>
<textobject><phrase>A screen-shot displaying services</phrase></textobject>
</mediaobject>
@@ -163,18 +213,21 @@
</title>
<para>
- Seen above, the monitoring console also provides an overall
- counter which counts all messages that pass through the
- ESB. The MessageCounter keeps track of the successful and
- failed message counts, as well as time and date.
+ The <application>Monitoring and Management
+ Console</application> also provides an overall count of the
+ messages that have passed through the Enterprise Service
+ Bus via a <firstterm>message counter</firstterm>. This
+ counter also keeps track of the numbers of successful and
+ failed messages and records the number of processed bytes
+ and the time/date stamp for each message.
</para>
<figure><title>Monitoring and Management Console Message Counter</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/monitoring_and_management/underneath2.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/monitoring_and_management/underneath2.png" />
</imageobject>
- <textobject><phrase>A Screen-shot of the
+ <textobject><phrase>The
Message Counter</phrase></textobject>
</mediaobject>
</figure>
@@ -189,11 +242,10 @@
</title>
<para>
- For each Smooks Transformation that is registered, a Mbean
- keeps track of the processed count for each transformation,
- processing time for each transformation, and the overall
- count for the transformation chain. You can see this
- information in the jmx-console.
+ There is an M-Bean that tracks both the total number of
+ <firstterm>Smooks transformations</firstterm> and the time
+ taken to perform each. It also keeps track of the
+ <firstterm>Transformation Chain</firstterm>.
</para>
</section>
@@ -202,79 +254,169 @@
<section id="dead_letter_service">
<title>
- DeadLetterService
+ Dead Letter Service
</title>
<para>
- As has been mentioned in the Programmers Guide, the
- DeadLetterService (DLQ) can be used to store messages
- that cannot be delivered. This is a JBossESB service
- and can be monitored and inspected. Note, however, that
- the DLQ is not used if the underlying transport has
- native support, e.g., JMS. In which case you should
- inspect the JBossESB DLQ as well as any
- transport-specific equivalent.
+ As discussed in the <emphasis>Programmers'
+ Guide</emphasis>, one can use the <firstterm>Dead
+ Letter Service</firstterm> (DLQ) to store undeliverable
+ messages. This is a JBoss ESB service and,
+ consequently, one can monitor it. Note, however, that
+ the <systemitem>Dead Letter Service</systemitem> will
+ not be used if the underlying transport has native
+ support as is the case, for example, with the Java
+ Messaging Service. In those situations, one must
+ inspect both the <systemitem>Dead Letter
+ Service</systemitem> and any transport-specific
+ equivalent.
</para>
- </section>
-
+ </section>
+
<section>
- <title>
- Alerts
- </title>
+<title>
+ Alerts
+</title>
+<!-- This following section is derived from Len's blog at http://jbossesb.blogspot.com/2009/11/messagealerts-in-jbossesb-47.html -->
<para>
- The JBoss Web Console (<ulink
- url="http://community.jboss.org/wiki/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
- can use this functionality to receive alerts for ESB-related events –
- such as the DeadLetterService counter reaching a certain threshold.
+ Use the <firstterm>Message Alerts</firstterm> feature
+ (<classname>org.jboss.soa.esb.listeners.message.MessageAlerts</classname>)
+ to collect fine-grained information about the processing time and
+ number of bytes that a specific service, (or a specific action in a
+ service), requires in order for it to process a single message.
</para>
-
- <orderedlist>
- <listitem>
- <para>
- Configure ./deploy/mail-service.xml with your SMTP settings.
- </para>
- </listitem>
- <listitem>
- <para>
- Change ./deploy/monitoring-service.xml – uncomment the
- EmailAlertListener section and add appropriate header
- related information.
- </para>
- </listitem>
- <listitem>
- <para>
- Create a file ./deploy to serve as your monitor MBean.
- </para>
- </listitem>
- </orderedlist>
+
+ <important>
+ <para>
+ The <application>JBoss Operations Network</application> plug-in
+ collects ESB message alerts and generates JON events. Once
+ collected, the message alerts are no longer available through
+ the <application>Monitoring and Management
+ Console</application>. To learn how to configure JON alerts to
+ process these events, please read the JON documentation
+ available at this address: <ulink
+ url="http://www.redhat.com/docs/en-US/JBoss_ON/2.3/html/Feature_Guide/chap-Feature_Guide-Events.html"/>.
+ </para>
+ </important>
+
+<para>
+ To use message alerts, define processing time and byte-total thresholds
+ on a per-service and/or action basis. When the service or action in
+ question takes longer than the threshold time one has defined to
+ process a message, a <code>WARNING</code> is written to the server log.
+ This warning is then made available to the <application>Monitoring and
+ Management Console</application>. To define a threshold, configure
+ these properties:
+</para>
+
<programlisting language="XML" role="XML"><xi:include parse="text" href="extras/monitoring_and_management/threshold.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+<note>
<para>
- This MBean will serve as a monitor, and once the DeadLetterService
- counter reaches 5, it will send an e-mail to the address(es)
- specified in the monitoring-service.xml. Note that the alert is
- only sent once – once the threshold has been reached. If you want
- to be alerted again once resetting the counter, you can reset the
- alerted flag on your monitoring service MBean (in this case
- jboss.monitor:service=ESBDLQMonitor).
+ The time threshold is measured in milliseconds, whilst that for the
+ length is measured in bytes.
</para>
+</note>
+<note>
+ <para>
+ The byte-total threshold is useful when one is monitoring a
+ transformation service or action that is suddenly processing many
+ more bytes than might be reasonably expected.
+ </para>
+</note>
+<para>
+ To learn more about the Message Alerts feature, run the
+ <systemitem>messagealerts quick-start</systemitem>. If one has ever run
+ the <systemitem>helloworld quick-start</systemitem>, this one will be
+ quite familiar. The only two changes are the addition of the
+ <classname>org.jboss.soa.esb.samples.quickstart.messagealerts.DelayAction</classname>
+ action class (which introduces a delay to trigger the
+ <property>alertTimeThreshold</property>) and the modifications to the
+ <filename>jboss-esb.xml</filename> file listed below:
+</para>
+
+<programlisting language="XML"><xi:include parse="text" href="extras/monitoring_and_management/quickstart.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+<para>
+ When the <systemitem>quick-start</systemitem> runs, the following
+ information is written to the <filename>server.log</filename> file:
+</para>
+
+<programlisting language="XML"><xi:include parse="text" href="extras/monitoring_and_management/quickstartoutput.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
<note>
<para>
- For more details on how to use the JBoss Web Console monitoring,
- please see <ulink
- url="http://community.jboss.org/wiki/JBossMonitoring" />.
+ The same information is available in the <property>JMX
+ Log</property> which can be found under
+ <filename>jboss.esb</filename>, where
+ <property>service=MessageAlerts</property>.
</para>
</note>
-
+<para>
+ Use the <application>Monitoring and Management Console</application> to
+ clear these alerts:
+</para>
-</section>
+ <figure>
+ <title>Monitoring and Management Console</title>
+ <mediaobject>
+ <imageobject><imagedata fileref="images/monitoring_and_management/jmx.png"/></imageobject>
+ </mediaobject>
+ </figure>
+
+<para>
+ An alternative way to access the alerts is by using this
+ command: <command>sh ./twiddle.sh get
+ "jboss.esb:service=MessageAlerts"</command>.
+</para>
+
+<para>
+ To access the alerts service "programatically," modify the
+ <systemitem>quick-start</systemitem>'s
+ <filename>jboss-esb.xml</filename> file to make the action that prints
+ information to the server log run after the delay (and, therefore,
+ after the message alerts have been generated.)
+</para>
+
+<para>
+ Next, replace the code in <filename>MyJMSListenerAction.java</filename>
+ with this:
+</para>
+
+
+<programlisting language="XML"><xi:include parse="text" href="extras/monitoring_and_management/quickstart.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+<para>
+ Now when the <systemitem>quick-start</systemitem> runs, the following
+ information will be written to the <filename>server.log</filename>
+ file:
+</para>
+
+<programlisting language="XML"><xi:include parse="text" href="extras/monitoring_and_management/quickstartoutput.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+<note>
+ <para>
+ Byte counts are now available on the services. Message alerts
+ have also been added and are available if one chooses to enable them.
+ </para>
+</note>
+
+
+<para>
+ Having read this chapter, the system administrator now understands how
+ to utilise the <application>Monitoring and Management
+ Console</application>, deal with message alerts and configure
+ thresholds.
+</para>
+
</section>
+ </section>
+
+ <xi:include href="JON_for_SOA.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</chapter>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Performance_Tuning.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Performance_Tuning.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Performance_Tuning.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -11,7 +11,7 @@
<para>
- Please refer to the JBossESB wiki for information on Performance Tuning: <ulink
+ To learn about performance tuning, go to <ulink
url="http://community.jboss.org/wiki/JBossESBPerformanceTuning"
/>.
</para>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Registry.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Registry.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Registry.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -6,40 +6,57 @@
<chapter id="registry">
<title>
- Registry
+ The Registry
</title>
<para>
- At the heart of all JBossESB deployments is the registry. This is
- fully described elsewhere in the Services Guide, where
- configuration information is also discussed. However, it is worth
- noting the following:
+ At the heart of every <application>JBoss Service-Oriented
+ Architecture Platform</application> deployment lies the
+ <firstterm>registry</firstterm>. This is fully described in the
+ <emphasis>JBoss SOA Platform Services Guide</emphasis>. Here, brief
+ note shall be made of the following items:
</para>
<itemizedlist>
<listitem>
<para>
- When services run they typically place the EPR through which
- they can be contacted within the registry. If they are
- correctly developed, then services should remove EPRs from the
- registry when they terminate. However, machine crashes, or
- incorrectly developed services, may leave stale entries within
- the registry that prevent the correct execution of subsequent
- deployments. In that case these entries may be removed
- manually. However, it is obviously important that you ensure
- the system is in a quiescent state before doing so.
- </para>
+ when services run, they usually add an <firstterm>end-point
+ reference</firstterm> (through which they are contacted) to the
+ <systemitem>registry</systemitem>. If services have been
+ programmed well, they automatically remove these end-point
+ references when they terminate. However, in certain
+ circumstance, the entries might there. (This would generally
+ only happen due to machine crashes or poor programming.) These
+ "orphan" entries will prevent subsequent deployments from
+ executing correctly, so remove them manually.
+ </para>
+
+ <warning>
+ <para>
+ Always ensure that the system is in an inactive state
+ before removing them.
+ </para>
+ </warning>
+
+
</listitem>
<listitem>
<para>
- If you set the optional remove-old-service tag name in the EPR
- to true then the ESB will remove any existing service entry
- from the Registry prior to adding this new instance. However,
- this should be used with care, because the entire service will
- be removed, including all EPRs.
- </para>
+ to remove every existing entry from the
+ <systemitem>registry</systemitem> prior to adding a new
+ instance, simply set the end-point reference's
+ <code>remove-old-service</code> tag name to <code>true</code>.
+ </para>
+
+ <warning>
+ <para>
+ Always use this option with care, because the entire
+ service, including every end-point reference, will be
+ removed.
+ </para>
+ </warning>
</listitem>
</itemizedlist>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/ServiceBindingManager.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/ServiceBindingManager.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/ServiceBindingManager.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -6,28 +6,43 @@
<chapter id="servicebinding_manager">
<title>
- ServiceBinding Manager
+ The Service Binding Manager
</title>
<para>
- If you wish to run multiple ESB servers on the same machine, you
- may want to use JBoss ServiceBinding Manager. The binding manager
- allows you to centralize port configuration for all of the
- instances you will be running. The ESB server ships with a sample
- bindings file in docs/examples/binding-manager/sample-bindings.xml.
- Chapter Ten of the JBoss appplication server documentation contains
- instructions on how to set up the ServiceBinding manager.
- Note:
+ To run multiple <application>JBoss Enterprise SOA
+ Platform</application> servers on the same machine, use the
+ <firstterm>Service Binding Manager</firstterm>. It provides a
+ central point at which to set the port configurations for every
+ instance.
</para>
<note>
<para>
- <filename>remoting-service.xml</filename> – If you are using
- jboss-messaging as your JMS provider, please note that what you
- specify in your ServiceBinding manager xml for jboss-messaging
- configuration must match what is in remoting-service.xml.
+ To learn how to use it, study information found in the
+ <filename>docs/examples/binding-manager/sample-bindings.xml</filename>
+ file.
</para>
</note>
+<note>
+ <para>
+ The <application>JBoss Application Server</application>
+ documentation also includes detailed instructions that teach one
+ how to configure the <systemitem>Service Binding
+ Manager</systemitem>.
+ </para>
+</note>
+
+ <important>
+ <para>
+ Before using <systemitem>JBoss Messaging</systemitem> as the
+ Java Messaging Service provider, check that its
+ <systemitem>Service Binding Manager</systemitem> configuration
+ matches that found in the
+ <filename>remoting-service.xml</filename> file.
+ </para>
+ </important>
+
</chapter>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/SOAPProcessor.java
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/SOAPProcessor.java (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/SOAPProcessor.java 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,4 @@
+ at Publish(JBossWSWebserviceContractPublisher.class)
+public class SOAPProcessor extends AbstractActionPipelineProcessor {
+ //TODO: implement
+}
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/cache_revalidation_timeout.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/cache_revalidation_timeout.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/cache_revalidation_timeout.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,4 @@
+<properties name="core">
+ <property name="org.jboss.soa.esb.registry.cache.life" value="60000"/>
+<!-- 60 seconds is the default -->
+</properties>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java1.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java1.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java1.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1 @@
+JAVA_OPTS="$JAVA_OPTS "-Xmx1G" "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java2.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java2.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java2.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,2 @@
+<Connector port="8090" protocol="HTTP/1.1">
+<Connector port="8099" protocol="AJP/1.3" redirectPort="8443"/>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java4.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java4.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/java4.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1 @@
+public ContractInfo getContractInfo(EPR epr);
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jbossesb-properties_1.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jbossesb-properties_1.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jbossesb-properties_1.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,3 @@
+<property name="org.jboss.soa.esb.persistence.base.plugin.jcr"
+value="org.jboss.internal.soa.esb.persistence.format.jcr.JCRMessageStorePlu
+gin"/>
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jbossesb-properties_2.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jbossesb-properties_2.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jbossesb-properties_2.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,8 @@
+<property name="org.jboss.soa.esb.persistence.jcr.jndi.path"
+ value="jcr"/>
+<property name="org.jboss.soa.esb.persistence.jcr.username"
+ value="username"/>
+<property name="org.jboss.soa.esb.persistence.jcr.password"
+ value="password"/>
+<property name="org.jboss.soa.esb.persistence.jcr.root.node.path"
+ value="JBossESB/MessageStore"/>
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_1.output
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_1.output (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_1.output 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,4 @@
+header: [ To: EPR: PortReference < <wsa:Address ftp://foo.bar/> >,
+From: null, ReplyTo: EPR: PortReference < <wsa:Address http://bar.
+foo/> >, FaultTo: null, Action: urn:dowork, MessageID: urn:foo/bar
+/1234, RelatesTo: null ]
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_2.output
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_2.output (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_2.output 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,4 @@
+TraceFilter.onOutput ( header: [ To: EPR: PortReference < <wsa:Add
+ress ftp://foo.bar/> >, From: null, ReplyTo: EPR: PortReference <
+<wsa:Address http://bar.foo/> >, FaultTo: null, Action: urn:dowork
+, MessageID: urn:foo/bar/1234, RelatesTo: null ] )
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_3.output
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_3.output (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/message_tracing_3.output 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,4 @@
+TraceFilter.onInput ( header: [ To: EPR: PortReference < <wsa:Addr
+ess ftp://foo.bar/> >, From: null, ReplyTo: EPR: PortReference < <
+wsa:Address http://bar.foo/> >, FaultTo: null, Action: urn:dowork,
+MessageID: urn:foo/bar/1234, RelatesTo: null ] )
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/opensso_identity_provider.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/opensso_identity_provider.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/opensso_identity_provider.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,15 @@
+<service category="OpenSSO"
+ name="SimpleListenerSecured" description="Hello World">
+ <security moduleName="OpenSSOLogin" runAs="adminRole"/>
+ <listeners>
+ <jms-listener name="JMS-Gateway" busidref="quickstartGwChannel"
+ maxThreads="1" is-gateway="true"/>
+ </listeners>
+
+ <actions mep="OneWay">
+ <action name="debug" class="org.jboss.soa.esb.actions.SystemPrintln">
+ <property name="printfull" value="false"/>
+ <property name="message" value="In Service1"/>
+ </action>
+ </actions>
+</service>
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/opensso_login-config.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/opensso_login-config.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/opensso_login-config.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,13 @@
+<application-policy name="OpenSSOLogin">
+ <authentication>
+ <login-module
+ code="org.jboss.soa.security.opensso.OpenSSOLoginModule"
+ flag="required">
+ <module-option name="orgName">opensso</module-option>
+ <module-option name="moduleName">DataStore</module-option>
+ <module-option name="amPropertiesFile">
+ props/AMConfig.properties
+ </module-option>
+ </login-module>
+ </authentication>
+</application-policy>
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/swtichdb1.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/swtichdb1.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/swtichdb1.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<datasources>
+ <local-tx-datasource>
+ <jndi-name>DefaultDS</jndi-name>
+ <connection-url>jdbc:postgresql://host:port/database</connection-url>
+ <driver-class>org.postgresql.Driver</driver-class>
+ <user-name>username</user-name>
+ <password>password</password>
+ <metadata>
+ <type-mapping>PostgreSQL 8.3</type-mapping>
+ </metadata>
+ <check-valid-connection-sql>select count(*) from jbm_user</check-valid-connection-sql>
+ </local-tx-datasource>
+</datasources>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/swtichdb2.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/swtichdb2.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/swtichdb2.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<server>
+ <mbean code="org.jboss.internal.soa.esb.dependencies.DatabaseInitializer"
+ name="jboss.esb:service=MessageStoreDatabaseInitializer">
+ <attribute name="Datasource">java:/JBossESBDS</attribute>
+ <attribute name="ExistsSql">select * from message</attribute>
+ <attribute name="SqlFiles">
+ message-store-sql/postgresql/create_database.sql
+ </attribute>
+ <depends>jboss.jca:service=DataSourceBinding,name=JBossESBDS</depends>
+ </mbean>
+</server>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/tibco_ems.settings
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/tibco_ems.settings (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/tibco_ems.settings 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,5 @@
+jndi-URL="tcp://localhost:7222”
+jndi-context-factory=”com.tibco.tibjms.naming.TibjmsInitialContextFactory"
+connection-factory="QueueConnectionFactory"
+destination-type="queue"
+destination-name="myqueue"
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/java3.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/java3.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/java3.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1 @@
+<entry key="rhq.agent.plugins.service-discovery.period-secs" value="86400"/>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/provider1.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/provider1.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/provider1.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,11 @@
+<mbean code="org.jboss.jms.jndi.JMSProviderLoader"
+name="jboss.messaging:service=JMSProviderLoader,name=RemoteProviderLoader">
+ <attribute name="ProviderName">RemoteProviderAdapter</attribute>
+ <attribute
+name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
+ <attribute name="QueueFactoryRef">XAQueueConnectionFactory</attribute>
+ <attribute name="TopicFactoryRef">XATopicConnectionFactory</attribute>
+ <attribute name="Properties">
+ java.naming.provider.url=192.168.1.1:1099
+ </attribute>
+</mbean>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/provider2.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/provider2.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/jbpm_console/provider2.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,9 @@
+<service name="message">
+ <factory>
+ <bean
+class="org.jboss.soa.esb.services.jbpm.integration.msg.JmsMessageServiceFactory">
+ <field name="providerAdapterJNDI"><string
+value="RemoteProviderAdapter"/></field>
+ </bean>
+ </factory>
+</service>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/programmatically.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/programmatically.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/programmatically.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,43 @@
+package org.jboss.soa.esb.samples.quickstart.messagealerts;
+
+ import org.jboss.soa.esb.actions.AbstractActionLifecycle;
+ import org.jboss.soa.esb.helpers.ConfigTree;
+ import org.jboss.soa.esb.message.Message;
+ import javax.management.ObjectName;
+ import javax.management.MBeanServer;
+ import org.jboss.mx.util.MBeanServerLocator;
+
+
+ import java.util.Vector;
+
+ public class MyJMSListenerAction extends AbstractActionLifecycle
+ {
+
+ protected ConfigTree _config;
+
+ public MyJMSListenerAction(ConfigTree config)
+ { _config = config; }
+
+ public Message displayMessage(Message message) throws
+ Exception{
+
+ MBeanServer server =
+ org.jboss.mx.util.MBeanServerLocator.locateJBoss();
+ Vector theAlertsVector = (Vector)server.getAttribute(new
+ ObjectName("jboss.esb:service=MessageAlerts"), "Alerts");
+
+ for (int i = 0; i < theAlertsVector.size(); i++ ) {
+ System.out.println("******Data returned from
+ MessageAlert[" + i + "] = "
+ + theAlertsVector.elementAt(i) + "\n" );
+ }
+
+ System.out.println("&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
+ &&&&&&&&&&&&&&&&&");
+ System.out.println("Body: " + message.getBody().get()) ;
+ System.out.println("&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
+ &&&&&&&&&&&&&&&&&");
+ return message;
+ }
+
+ }
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/quickstart.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/quickstart.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/quickstart.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,34 @@
+<services>
+ <service
+ category="FirstServiceESB"
+ name="SimpleListener"
+ description="Hello World"
+ alertTimeThreshold="420"
+ alertLengthThreshold="10"
+ >
+ <listeners>
+ <jms-listener name="JMS-Gateway"
+ busidref="quickstartGwChannel"
+ is-gateway="true"
+ />
+ <jms-listener name="helloWorld"
+ busidref="quickstartEsbChannel"
+ />
+ </listeners>
+ <actions mep="OneWay">
+ <action name="action1"
+ class="org.jboss.soa.esb.samples.quickstart.messagealerts.MyJMSListenerAction"
+ process="displayMessage"
+ />
+ <action name="action2" class="org.jboss.soa.esb.actions.SystemPrintln">
+ <property name="printfull" value="false"/>
+ </action>
+ <action name="action3"
+ class="org.jboss.soa.esb.samples.quickstart.messagealerts.DelayAction"
+ process="delayMessage"
+ alertTimeThreshold="30"
+ alertLengthThreshold="50">
+ </action>
+ </actions>
+ </service>
+ </services>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/quickstartoutput.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/quickstartoutput.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/monitoring_and_management/quickstartoutput.xmlt 2010-08-15 23:23:43 UTC (rev 34731)
@@ -0,0 +1,28 @@
+22:00:28,833 INFO [STDOUT] &&&&&&&&&&&&&&&&&&&&&&
+22:00:28,837 INFO [STDOUT] Body: Message Alerts
+22:00:28,837 INFO [STDOUT] &&&&&&&&&&&&&&&&&&&&&&
+22:00:28,850 INFO [STDOUT] Message structure:
+22:00:28,850 INFO [STDOUT] [Message Alerts].
+
+22:00:31,852 WARN [ServiceMessageCounter]
+jboss.esb:category=MessageCounter,deployment=Quickstart_messagealerts.esb,service-category
+=FirstServiceESB,service-name=SimpleListener
+service, action3 action alert time 3001 took longer than 30 ms
+
+
+22:00:31,853 WARN [ServiceMessageCounter]
+jboss.esb:category=MessageCounter,deployment=Quickstart_messagealerts.esb,service-category
+=FirstServiceESB,service-name=SimpleListener
+service, action3 action message size 2960 was larger than 50 bytes
+
+
+22:00:31,853 WARN [ServiceMessageCounter]
+jboss.esb:category=MessageCounter,deployment=Quickstart_messagealerts.esb,service-category
+=FirstServiceESB,service-name=SimpleListener
+service alert time 3007 took longer than 420 ms
+
+
+22:00:31,854 WARN [ServiceMessageCounter]
+jboss.esb:category=MessageCounter,deployment=Quickstart_messagealerts.esb,service-category
+=FirstServiceESB,service-name=SimpleListener
+service message size 2960 was larger than 10 bytes
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/contract_publishing/contract_publishing_application.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/contract_publishing/contract_publishing_application.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/jon/JON_SOA_indicators.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/jon/JON_SOA_indicators.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/monitoring_and_management/jmx.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/images/monitoring_and_management/jmx.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/jBPM_Console.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/jBPM_Console.xml 2010-08-15 20:28:02 UTC (rev 34730)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/jBPM_Console.xml 2010-08-15 23:23:43 UTC (rev 34731)
@@ -6,54 +6,53 @@
<chapter id="jBPM_Console">
<title>
- jBPM
+ JBoss Business Process Management
</title>
-<section id="overview">
+ <para>
+ Read this chapter to learn how to administer the <application>jBPM
+ Web Console</application> and other parts of the <application>JBoss Business
+ Process Manager</application>.
+ </para>
+
+ <section id="overview">
<title>
- jBPM Console
+ The jBPM Web Console
</title>
<para>
- The jBPM Web Console is deployed by default as part of jbpm.esb
- and can be found at: <ulink
- url="http://localhost:8080/jbpm-console/" />. Please refer to
- the jBPM documentation for information regarding the console.
+ The <firstterm>jBPM Web Console</firstterm> is deployed, by
+ default, as part of the <filename>jbpm.esb</filename> file.
+ View the Console by loading <ulink
+ url="http://localhost:8080/jbpm-console/" /> in a web browser.
+ (Please refer to the <emphasis>jBPM User Guide</emphasis> for
+ detailed instructions on its use.)
</para>
</section>
<section id="message_and_scheduler_service">
<title>
- jBPM Message and Scheduler service
+ jBPM Message and Scheduler Services
</title>
<para>
- The jBPM integration within ESB now support additional Message
- and Scheduler services, distinct from those offered natively by
- jBPM. In addition to the standard jBPM configurations we now
- also support a JMS based Message Service, driven using JCA
- inflow, and three additional Scheduling Services, based on JBoss
- Messaging, hornetq and quartz.
- </para>
-
- <para>
- The configuration, as shipped by default within ESB, uses the
- jBPM JobExecutor and the database implementations of the
- Message and Scheduler service.
+ The default ESB configuration uses the jBPM
+ <classname>JobExecutor</classname> and the database
+ implementations of the Message and Scheduler services.
</para>
<programlisting language="XML" role="XML"><xi:include parse="text" href="extras/jbpm_console/provider.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
- In order to utilize the alternative services it is necessary to
+ In order to utilize the alternative services,
replace the active configurations with the versions specific to
- your requirements.
+ one's requirements.
</para>
<para>
- The configuration for the alternative services can be found
- within the jbpm.esb/config directory
+ Find the configurations for alternative services
+ within the <filename>jbpm.esb/config</filename> directory.
</para>
@@ -61,36 +60,102 @@
<orderedlist>
<listitem>
<para>
- jbpm.esb/config/hornetqscheduler for configuring the hornetq
- based message and scheduler services
+ JMS/JCA inflow is the only supported jBPM/ESB
+ integration configuration for Enterprise
+ Service Bus deployments.
</para>
</listitem>
<listitem>
<para>
- jbpm.esb/config/jmsscheduler for configuring the JBoss
- Messaging based message and scheduler services
+ the <filename>jbpm.esb</filename> provides support for the JBoss
+ Messaging JMS provider.
</para>
</listitem>
<listitem>
<para>
- jbpm.esb/config/quartzscheduler for configuring the JMS
- message service and a quartz based scheduler service.
+ the <application>jBPM Job Executor</application> is
+ only supported if the Enterprise Service Bus is not
+ deployed on the configuration. (The
+ <application>Executor</application> needs to be started
+ by a servlet in a <filename>WAR</filename> file.)
</para>
- </listitem>
+ </listitem>
+ <listitem>
+ <para>
+ <application>Quartz Scheduler</application>-based
+ integration is no longer available.
+ </para>
+ </listitem>
</orderedlist>
- <para>
+<para>
The configuration files within the appropriate directory should be
used to replace the active configurations within the jbpm.esb
directory, remembering to remove the .config suffix from each. It
should also be noted that only one of the quartz message queue
- service definitions should be used, either hornetq-jms.xml,
- jbm-queue-service.xml or jbmq-queue-service.xml, depending on which
- JMS implementation is currently in use.
+ service definitions should be used, either jbm-queue-service.xml or
+ jbmq-queue-service.xml, depending on which JMS implementation is
+ currently in use.
</para>
+
-
+ <section id="remote_providers">
+ <title>
+ Using Remote JMS Providers
+ </title>
+ <important>
+ <para>
+ This is new functionality that only applies to release 5.0.2
+ and onwards.
+ </para>
+ </important>
+ <para>
+ To use the JMS-based message and scheduling services to reference
+ remote JMS providers, a <firstterm>provider adapter</firstterm>
+ configuration to exist within the local JNDI. (The provider adapter
+ is an instance of <classname>JMSProviderAdapter</classname>, as can
+ be used within the standard application server's <systemitem>JCA
+ inflow</systemitem> configuration.)
+ </para>
+
+ <para>
+ Configure the <classname>JMSProviderAdapter</classname> by adding
+ an <systemitem>M-Bean</systemitem> to a
+ <filename>service.xml</filename> file. This can either be specific
+ to the jBPM integration, (by, for example, adding it to the
+ <filename>jbpm-service.xml</filename>), or it can be shared with
+ other <systemitem>JCA inflow</systemitem> configurations.
+ </para>
+
+ <para>
+ The following example creates a provider adapter which references a
+ remote JMS provider executing at
+ <literal>192.168.1.1:1099</literal>. (Use the
+ <property>Properties</property> attribute's contents to
+ create the JNDI <classname>InitialContext</classname>.)
+ </para>
+
+<programlisting language="XML"><xi:include parse="text" href="extras/jbpm_console/provider1.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ <para>
+ Next, reference the Provider Adapter within the
+ <classname>JMSMessageServiceFactory</classname> and
+ <classname>JMSSchedulerServiceFactory</classname> configurations.
+ To do so, specify the JNDI location via the
+ <property>providerAdapterJNDI</property> field. Here is an example:
+ </para>
+
+<programlisting language="XML"><xi:include parse="text" href="extras/jbpm_console/provider2.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+<para>
+ Having studied this chapter, the reader now knows the ways in which the
+ jBPM is integrated with the SOA Platform.
+ </para>
+
+</section>
+
+
</section>
</chapter>
More information about the jboss-svn-commits
mailing list