diff --git a/docs/src/reference/docbook/control-bus.xml b/docs/src/reference/docbook/control-bus.xml index b56ac4931b..a59fd2fea8 100644 --- a/docs/src/reference/docbook/control-bus.xml +++ b/docs/src/reference/docbook/control-bus.xml @@ -1,5 +1,6 @@ -
Control Bus - As described in (EIP), the idea behind the Control Bus is that - the same messaging system can be used for monitoring and managing - the components within the framework as is used for - "application-level" messaging. In Spring Integration we build upon - the adapters described above so that it's possible to send Messages - as a means of invoking exposed operations. + As described in (EIP), the idea behind the Control Bus is that the + same messaging system can be used for monitoring and managing the components + within the framework as is used for "application-level" messaging. In Spring + Integration we build upon the adapters described above so that it's possible + to send Messages as a means of invoking exposed operations. - ]]> + <control-bus input-channel="operationChannel"/> - The Control Bus has an input channel that can be accessed for - invoking operations on the beans in the application context. It - also has all the common properties of a service activating endpoint, - e.g. you can specify an output channel if the result of the - operation has a return value that you want to send on to a - downsatrem channel. - + The Control Bus has an input channel that can be accessed for invoking + operations on the beans in the application context. It also has all the + common properties of a service activating endpoint, e.g. you can specify an + output channel if the result of the operation has a return value that you + want to send on to a downstream channel. - The Control Bus executes messages on the input channel as - Spring Expression Language expressions. It takes a message, - compiles the body to an expression, adds some context, and then - executes it. The default context just exposes all the beans in the - application context by name. - + The Control Bus executes messages on the input channel as Spring + Expression Language expressions. It takes a message, compiles the body to an + expression, adds some context, and then executes it. The default context + just exposes all the beans in the application context by name with the usual + SpEL prefix for beans (@). So to execute a method on a Spring Bean a client + would send a message to the operation channel: + Message operation = MessageBuilder.withPayload("@myServiceBean.shutdown()"); +operationChannel.send(operation) + + The root of the context for the expression is the + Message itself, so you also have access to the body + and headers, the same as all the other expressions in Spring Integration + endpoints. + + The execution context for the expressions can be customized by + providing a BeanResolver instance: + + <control-bus input-channel="operationChannel" bean-resolver="beanResolver"/> +<beans:bean class="com.mycompany.MyCustomBeanResolver"/>
diff --git a/docs/src/reference/docbook/jmx.xml b/docs/src/reference/docbook/jmx.xml index 2b5cc0d566..f06e5cd6d8 100644 --- a/docs/src/reference/docbook/jmx.xml +++ b/docs/src/reference/docbook/jmx.xml @@ -1,6 +1,10 @@ -
+
JMX Support Spring Integration provides Channel Adapters for receiving and @@ -16,26 +20,25 @@ be registered. A very simple configuration might look like this: <jmx:notification-listening-channel-adapter id="adapter" channel="channel" - object-name="example.domain:name=publisher"/> - The - notification-listening-channel-adapter registers with - an MBeanServer at startup, and the default bean name is "mbeanServer" - which happens to be the same bean name generated when using Spring's - <context:mbean-server/> element. If you need to use a different name - be sure to include the "mbean-server" attribute. The adapter can - also accept a reference to a NotificationFilter and a "handback" Object to - provide some context that is passed back with each Notification. Both of - those attributes are optional. Extending the above example to include - those attributes as well as an explicit MBeanServer bean name would - produce the following: <jmx:notification-listening-channel-adapter id="adapter" + object-name="example.domain:name=publisher"/> + The notification-listening-channel-adapter + registers with an MBeanServer at startup, and the default bean name is + "mbeanServer" which happens to be the same bean name generated when using + Spring's <context:mbean-server/> element. If you need to use a + different name be sure to include the "mbean-server" attribute. The + adapter can also accept a reference to a NotificationFilter and a + "handback" Object to provide some context that is passed back with each + Notification. Both of those attributes are optional. Extending the above + example to include those attributes as well as an explicit MBeanServer + bean name would produce the following: <jmx:notification-listening-channel-adapter id="adapter" channel="channel" mbean-server="someServer" object-name="example.domain:name=somePublisher" notification-fliter="notificationFilter" - handback="myHandback"/> - Since the notification-listening adapter is registered with - the MBeanServer directly, it is event-driven and does not require any - poller configuration. + handback="myHandback"/> Since the + notification-listening adapter is registered with the MBeanServer + directly, it is event-driven and does not require any poller + configuration.
@@ -47,10 +50,10 @@ <jmx:notification-publishing-channel-adapter id="adapter" channel="channel" - object-name="example.domain:name=publisher"/> - It does also require that an MBeanExporter be present in the - context. That is why the <context:mbean-export/> element is shown - above as well. + object-name="example.domain:name=publisher"/> + It does also require that an MBeanExporter be present in the context. That + is why the <context:mbean-export/> element is shown above as + well. When Messages are sent to the channel for this adapter, the Notification is created from the Message content. If the payload is a @@ -68,8 +71,7 @@ <jmx:notification-publishing-channel-adapter id="adapter" channel="channel" object-name="example.domain:name=publisher" - default-notification-type="some.default.type"/> - + default-notification-type="some.default.type"/>
@@ -88,8 +90,7 @@ object-name="example.domain:name=someService" attribute-name="InvocationCount"> <si:poller max-messages-per-poll="1" fixed-rate="5000"/> - </jmx:attribute-polling-channel-adapter> - + </jmx:attribute-polling-channel-adapter>
@@ -101,10 +102,10 @@ ObjectName of the target MBean. Both of these must be explicitly provided via adapter configuration: <jmx:operation-invoking-channel-adapter id="adapter" object-name="example.domain:name=TestBean" - operation-name="ping"/> - Then the adapter only needs to be able to discover the - "mbeanServer" bean. If a different bean name is required, then provide the - "mbean-server" attribute with a reference. + operation-name="ping"/> Then the adapter + only needs to be able to discover the "mbeanServer" bean. If a different + bean name is required, then provide the "mbean-server" attribute with a + reference. The payload of the Message will be mapped to the parameters of the operation, if any. A Map-typed payload with String keys is treated as @@ -148,22 +149,217 @@ <bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean"> <property name="locateExistingServerIfPossible" value="true"/> - </bean> + </bean> Once the exporter is defined start up your + application with -Dcom.sun.management.jmxremote + -Dcom.sun.management.jmxremote.port=6969 + -Dcom.sun.management.jmxremote.ssl=false + -Dcom.sun.management.jmxremote.authenticate=falseThen start + JConsole (free with the JDK), and connect to the local process on + localhost:6969 to get a look at the management + endpoints exposed. (The port and client are just examples to get you + started quickly, there are other JMX clients available and some offer more + sophisticated features than JConsole.) The MBean exporter is orthogonal to the one provided in Spring core - it registers message channels and message handlers, but not itself. You can expose the exporter itself, and certain other components in Spring Integration, using the standard - <context:mbean-export/> tag. + <context:mbean-export/> tag. The exporter has a + couple of useful metrics attached to it, for instance a count of the + number of active handlers and the number of queued messages (these would + both be important if you wanted to shutdown the context without losing any + messages). -
- MBean Features +
+ MBean ObjectNames - All the MessageChannel, MessageHandler and MessageSource - instances in the application are wrapped by the MBean exporter to - provide management and monitoring features. + All the MessageChannel, MessageHandler and MessageSource instances + in the application are wrapped by the MBean exporter to provide + management and monitoring features. For example, MessageChannel send The + generated JMX object names for each component type are listed in the + table below + + + + + <tgroup cols="2"> + <thead> + <row> + <entry align="center">Component Type</entry> + + <entry align="center">ObjectName</entry> + </row> + </thead> + + <tbody> + <row> + <entry>MessageChannel</entry> + + <entry>org.springframework.integration:type=MessageChannel,name=<channelName></entry> + </row> + + <row> + <entry>MessageSource</entry> + + <entry>org.springframework.integration:type=MessageSource,name=<channelName>,bean=<source></entry> + </row> + + <row> + <entry>MessageHandler</entry> + + <entry>org.springframework.integration:type=MessageSource,name=<channelName>,bean=<source></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>The "bean"<literal /> attribute in the object names for sources + and handlers takes one of the values in the table below</para> + + <table> + <title /> + + <tgroup cols="2"> + <thead> + <row> + <entry align="center">Bean Value</entry> + + <entry align="center">Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>endpoint</entry> + + <entry>The bean name of the enclosing endpoint (e.g. + <service-activator>) if there is one</entry> + </row> + + <row> + <entry>anonymous</entry> + + <entry>An indication that the enclosing endpoint didn't have a + user-specified bean name, so the JMX name is the input channel + name</entry> + </row> + + <row> + <entry>internal</entry> + + <entry>For well-known Spring Integration default + components</entry> + </row> + + <row> + <entry>handler</entry> + + <entry>None of the above: fallback to the + <literal>toString()</literal> of the object being monitored + (handler or source)</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="jmx-channel-features"> + <title>MessageChannel MBean Features + + Message channels report metrics according to their concrete type. + If you are looking at a DirectChannel you will + see statistics for the send operation. If it is a + QueueChannel you will also see statistics for the + receive operation. In both cases there are some metrics that are simple + counters (message count and error count), and some that are estimates of + averages of interesting quantities. The algorithms used to calculate + these estimates are described briefly in the table below: + +
+ + + <tgroup cols="3"> + <thead> + <row> + <entry align="center">Metric Type</entry> + + <entry align="center">Example</entry> + + <entry align="center">Algorithm</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Count</entry> + + <entry>Send Count</entry> + + <entry>Simple incrementer. Increase by one when an event + occurs.</entry> + </row> + + <row> + <entry>Duration</entry> + + <entry>Send Duration (method execution time in + milliseconds)</entry> + + <entry>Exponential Moving Average with decay factor 10. Average + of the method execution time over roughly the last 10 + measurements.</entry> + </row> + + <row> + <entry>Rate</entry> + + <entry>Send Rate (number of operations per second)</entry> + + <entry>Inverse of Exponential Moving Average of the interval + between events with decay in time (lapsing over 60 seconds) and + per measurement (last 10 events).</entry> + </row> + + <row> + <entry>Ratio</entry> + + <entry>Send Error Ratio (ratio of errors to total sends)</entry> + + <entry>Estimate the success ratio as the Exponential Moving + Average of the series composed of values 1 for success and 0 for + failure (decaying as per the rate measurement over time and + events). Error ratio is 1 - success ratio.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>A feature of the time-based average estimates is that they decay + with time if no new measurements arrive. To help interpret the behaviour + over time, the time (in seconds) since the last measurement is also + exposed as a metric.</para> + + <para>There are two basic exponential models: decay per measurement + (appropriate for duration and anything where the number of measurements + is part of the metric), and decay per time unit (more suitable for rate + measurements where the time in between measurements is part of the + metric). Both models depend on the fact that <screen>S(n) = sum(i=0,i=n) w(i) x(i)</screen> + has a special form when <literal>w(i) = r^i</literal>, with + <literal>r=constant</literal>: <screen>S(n) = x(n) + r S(n-1)</screen>(so + you only have to store <literal>S(n-1)</literal>, not the whole series + <literal>x(i)</literal>, to generate a new metric estimate from the last + measurement). The algorithms used in the duration metrics use + <literal>r=exp(-1/M)</literal> with <literal>M=10</literal>. The net + effect is that the estimate <literal>S(n)</literal> is more heavily + weighted to recent measurements and is composed roughly of the last + <literal>M</literal> measurements. So <literal>M</literal> is the + "window" or lapse rate of the estimate In the case of the vanilla moving + average, <literal>i</literal> is a counter over the number of + measurements. In the case of the rate we interpret <literal>i</literal> + as the elapsed time, or a combination of elapsed time and a counter (so + the metric estimate contains contributions roughly from the last + <literal>M</literal> measurements and the last <literal>T</literal> + seconds).</para> + </section> </section> - - </section> - </section> diff --git a/docs/src/reference/docbook/system-management.xml b/docs/src/reference/docbook/system-management.xml index bd03dad3f8..a914c9ccec 100644 --- a/docs/src/reference/docbook/system-management.xml +++ b/docs/src/reference/docbook/system-management.xml @@ -6,4 +6,5 @@ <xi:include href="./jmx.xml"/> <xi:include href="./message-history.xml"/> -</chapter> \ No newline at end of file + <xi:include href="./control-bus.xml"/> +</chapter>