diff --git a/spring-integration-reference/src/jmx.xml b/spring-integration-reference/src/jmx.xml new file mode 100644 index 0000000000..aa44668380 --- /dev/null +++ b/spring-integration-reference/src/jmx.xml @@ -0,0 +1,175 @@ + + + + JMX Support + + Spring Integration provides Channel Adapters for receiving and publishing JMX Notifications. + There is also an inbound Channel Adapter for polling JMX MBean attribute values, and an + outbound Channel Adapter for invoking JMX MBean operations. + + +
+ Notification Listening Channel Adapter + + The Notification-listening Channel Adapter requires a JMX ObjectName for the MBean that publishes + Notifications to which this listener should be registered. A very simple configuration might look like this: + +]]> + + 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: + +]]> + Since the notification-listening adapter is registered with the MBeanServer directly, it is + event-driven and does not require any poller configuration. + +
+ +
+ Notification Publishing Channel Adapter + + The Notification-publishing Channel Adapter is relatively simple. It only requires a + JMX ObjectName in its configuration as shown below. + + + +]]> + 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 String it will be + passed as the "message" text for the Notification. Any other payload type + will be passed as the "userData" of the Notification. + + + JMX Notifications also have a "type", and it should be a dot-delimited String. + There are two ways to provide the type. Precedence will always be given to a + Message header value associated with the JmxHeaders.NOTIFICATION_TYPE key. + On the other hand, you can rely on a fallback "default-notification-type" + attribute provided in the configuration. + + + +]]> + +
+ +
+ Attribute Polling Channel Adapter + + The attribute polling adapter is useful when you have a requirement to periodically + check on some value that is available through an MBean as a managed attribute. The + poller can be configured in the same way as any other polling adapter in Spring + Integration (or it's possible to rely on the default poller). The "object-name" + and "attribute-name" are required. An MBeanServer reference is also required, but + it will automatically check for a bean named "mbeanServer" by default just like + the notification-listening-channel-adapter described above. + + + + + +]]> + +
+ +
+ Operation Invoking Channel Adapter + + The operation-invoking-channel-adapter enables Message-driven invocation of + any managed operation exposed by an MBean. Each invocation requires the + operation name to be invoked and the ObjectName of the target MBean. In each + case, the adapter will first check for header values on the Message itself. + The keys for these headers are defined as JmxHeaders.OPERATION_NAME and + JmxHeaders.OBJECT_NAME, respectively. If relying on those Message headers, + the configuration is trivial. + +]]> + That 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 name/value pairs whereas a List or + array would be passed as a simple argument list (with no explicit parameter names). + If the operation requires a single parameter value, then the payload can represent + that single value, and if the operation requires no parameters, then the payload + would be ignored. + + + Similar to the behavior described above for the Notification type resoltion, + the operation-invoking-channel-adapter will also fallback to default values if + provided: + +]]> + If you want to expose a channel for a single common operation to be invoked + by Messages that need not contain headers, then that option works well. + +
+ +
+ Control Bus + + Spring Integration components themselves may be exposed as MBeans when the Control Bus + is configured. 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. Internally, the Control Bus uses + a Spring MBeanExporter instance to expose the various endpoints and channels. To create + an instance of the Control Bus, define a bean and provide a reference to an MBeanServer + and a domain name (we will be providing namespace support). The domain can be left out + in which case the default domain is "org.springframework.integration". + + + + + + + + +]]> + + + The Control Bus has an "operationChannel" that can be accessed for invoking operations + on the MBeans that it has exported. This will also be covered by namespace support soon + to make it easier to configure references to that channel for other producers. We will + likely add some other channels for notifications and attribute polling as well. + + + The Control Bus functionality is a work in progress. At this time, one can perform some + basic monitoring of Message Channels and/or invoke Lifecycle operations (start/stop) on + Message Endpoints. Now that the foundation is available, however, we will be able to extend + the attributes and operations that are being exposed. + +
+ + \ No newline at end of file diff --git a/spring-integration-reference/src/spring-integration-reference.xml b/spring-integration-reference/src/spring-integration-reference.xml index 53412607bc..5503a2affd 100644 --- a/spring-integration-reference/src/spring-integration-reference.xml +++ b/spring-integration-reference/src/spring-integration-reference.xml @@ -75,6 +75,7 @@ +