INT-3183 Document the IMBE 'id' Attribute

When declaring an IntegrationMBeanExporter, use an 'id' attribute
if you wish to obtain programmatic access to it (using injection
or referencing the BeanFactory.

JIRA: https://jira.springsource.org/browse/INT-3183

Also turn off debug logging for JMX test cases.

spring-integration-jmx/src/test/java/log4j.properties

@@ -6,6 +6,6 @@ log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %t %c{2}:%L - %m
 
 
 log4j.category.org.springframework=WARN
-log4j.category.org.springframework.integration=DEBUG
-log4j.category.org.springframework.beans.factory=DEBUG
+#log4j.category.org.springframework.integration=DEBUG
+#log4j.category.org.springframework.beans.factory=DEBUG
 #log4j.category.org.springframework.integration.monitor=TRACE

src/reference/docbook/jmx.xml

@@ -81,7 +81,7 @@
 			relatively simple. It only requires a JMX ObjectName in its
 			configuration as shown below.
 		</para>
-		<programlisting language="xml"><![CDATA[<context:mbean:export/>
+		<programlisting language="xml"><![CDATA[<context:mbean-export/>
 
 <int-jmx:notification-publishing-channel-adapter id="adapter"
     channel="channel"
@@ -106,7 +106,7 @@
 			key. On the other hand, you can rely on a fallback <emphasis>default-notification-type</emphasis>
 			attribute provided in the configuration.
 		</para>
-		<programlisting language="xml"><![CDATA[<context:mbean:export/>
+		<programlisting language="xml"><![CDATA[<context:mbean-export/>
 
 <int-jmx:notification-publishing-channel-adapter id="adapter"
     channel="channel"
@@ -242,7 +242,8 @@
 			and a domain name (if desired). The domain can be left out, in which
 			case the default domain is <emphasis>org.springframework.integration</emphasis>.
 		</para>
-		<programlisting language="xml"><![CDATA[<int-jmx:mbean-export default-domain="my.company.domain" server="mbeanServer"/>
+		<programlisting language="xml"><![CDATA[<int-jmx:mbean-export id="integrationMBeanExporter"
+            default-domain="my.company.domain" server="mbeanServer"/>
 
 <bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
     <property name="locateExistingServerIfPossible" value="true"/>
@@ -250,7 +251,7 @@
 		<para>
 			Once the exporter is defined, start up your application with:
 		</para>
-		<screen>-Dcom.sun.management.jmxremote
+		<screen>    -Dcom.sun.management.jmxremote
     -Dcom.sun.management.jmxremote.port=6969
     -Dcom.sun.management.jmxremote.ssl=false
     -Dcom.sun.management.jmxremote.authenticate=false</screen>
@@ -262,16 +263,20 @@
 			sophisticated features than JConsole.)
 		</para>
 
-		<para>
+		<important>
+		  <para>
 			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 <literal>&lt;context:mbean-export/&gt;</literal>
-			tag. The exporter has a couple of useful metrics attached to it, for
+			tag. The exporter has a some 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).
-		</para>
+			queued messages.
+		  </para>
+		  <para>
+		    It also has a useful operation, as discussed in <xref linkend="jmx-mbean-shutdown"/>.
+		  </para>
+		</important>
 
 		<section id="jmx-mbean-features">
 			<title>MBean ObjectNames</title>

src/reference/docbook/shutdown.xml

@@ -58,4 +58,22 @@
 		If no time is left when we get to step 6, it probably means some thread is hung; in which case, the
 		operation attempts a forced shutdown on all schedulers and executors before exiting.
 	</note>
+	<para>
+		As discussed in <xref linkend="jmx-mbean-shutdown"/> this operation can be invoked using JMX. If you
+		wish to programmatically invoke the method, you will need to inject, or otherwise get a reference to,
+		the <classname>IntegrationMBeanExporter</classname>. If no <code>id</code> attribute is provided on
+		the <code>&lt;int-jmx:mbean-export/></code> definition, the bean will have a generated name. This
+		name contains a random component to avoid <classname>ObjectName</classname> collisions if multiple
+		Spring Integration contexts exist in the same JVM (MBeanServer).
+	</para>
+	<para>
+		For this reason, if you wish to invoke the method programmatically, it is recommended that you
+		provide the exporter with an <code>id</code> attribute so it can easily be accessed in the
+		application context.
+	</para>
+	<para>
+		Finally, the operation can be invoked using the <code>&lt;control-bus&gt;</code>; see the
+		<ulink url="https://github.com/spring-projects/spring-integration-samples/tree/master/intermediate/monitoring"
+		>monitoring Spring Integration sample application</ulink> for details.
+	</para>
 </section>