mx4j/src/docs/english jsr160-explained.xml,1.12,1.13

Update of /cvsroot/mx4j/mx4j/src/docs/english
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv31214/src/docs/english

Modified Files:
	jsr160-explained.xml 
Log Message:
Added section on using MX4J connectors in J2SE 5

Index: jsr160-explained.xml
===================================================================
RCS file: /cvsroot/mx4j/mx4j/src/docs/english/jsr160-explained.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** jsr160-explained.xml	31 Oct 2004 11:38:10 -0000	1.12
--- jsr160-explained.xml	13 Feb 2005 18:02:32 -0000	1.13
***************
*** 1095,1099 ****
        <para>
           Starting successfully a SOAPConnectorServer requires Axis 1.1 and a servlet 2.3 compliant web container.
!          In this example the web container will be the <ulink url="http://jetty.mortbay.com">Jetty</ulink> web
           container.
           <sbr/>
--- 1095,1100 ----
        <para>
           Starting successfully a SOAPConnectorServer requires Axis 1.1 and a servlet 2.3 compliant web container.
!          In this example the web container will be the
!          <ulink url="http://jetty.mortbay.com">Jetty</ulink> web
           container.
           <sbr/>
***************
*** 1260,1263 ****
--- 1261,1359 ----
  
  <section>
+    <title>How to use MX4J's JSR 160 connectors with J2SE 5+</title>
+    <para>
+       Since J2SE 5 (Tiger), both the standard remote JMX classes (from JSR 160, under packages
+       <classname>javax.management.remote.*</classname>) and the standard JMX classes
+       (from JSR 3, under packages
+       <classname>javax.management.*</classname>) have been included in the
+       standard JDK/JRE distribution from Sun.
+       <sbr/>
+       This means that by default, the JMX and JSR 160 implementation you use in J2SE 5 are not MX4J's,
+       but the ones shipped with the JDK, even if you put the MX4J jars in the classpath or under the
+       WEB-INF/lib directory of a web application.
+    </para>
+    <para>
+       The J2SE 5 platform contains the full implementation of JMX (JSR 3), and the mandatory part of
+       JSR 160.
+       <sbr/>
+       The mandatory part of JSR 160 contains the standard API (e.g.
+       <classname>javax.management.remote.JMXServiceURL</classname>,
+       <classname>javax.management.remote.JMXConnector</classname>,
+       <classname>javax.management.remote.JMXConnectorServer</classname>, etc), and two implementations
+       of JSR 160 providers over the
+       <emphasis>rmi</emphasis> and
+       <emphasis>iiop</emphasis> protocols.
+       <sbr/>
+       The optional
+       <emphasis>jmxmp</emphasis> protocol is not shipped with the JDK in J2SE 5 (and it is
+       not implemented by MX4J).
+    </para>
+    <para>
+       This means that by default, J2SE 5 only recognizes JMXServiceURLs of this type:
+       <sbr/>
+       <classname>service:jmx:rmi:///jndi/whatever</classname> and
+       <sbr/>
+       <classname>service:jmx:iiop:///jndi/whatever</classname>,
+       <sbr/>
+       and it is only able to instantiate
+       <classname>javax.management.remote.rmi.RMIConnectorServer</classname>s
+       and
+       <classname>javax.management.remote.rmi.RMIConnector</classname>s.
+    </para>
+    <para>
+       However, it is extremely simple to tell the JSR 160 API in J2SE 5 to recognize other JMXServiceURLs,
+       and to load connectors from other implementations such as MX4J, simply by specifying a property in the
+       environment Map passed at the moment of creation of the JMXConnectorServer or JMXConnector.
+       <sbr/>
+       Below an example of how to start the MX4J SOAP Connector using J2SE 5:
+    </para>
+    <para>
+       <example>
+          <title>How to start an MX4J SOAP Connector in J2SE 5</title>
+          <programlisting>
+             <![CDATA[
+ // Remember to put mx4j-tools.jar in the classpath
+ 
+ // How to start an MX4J SOAP JMXConnectorServer in J2SE 5
+ Map serverEnv = new HashMap();
+ serverEnv.put(JMXConnectorServerFactory.PROTOCOL_PROVIDER_PACKAGES, MX4JRemoteConstants.PROVIDER_PACKAGES);
+ 
+ JMXServiceURL url = new JMXServiceURL("soap", null, 8080, "/soapjmx");
+ 
+ JMXConnectorServer cntorServer = JMXConnectorServerFactory.newJMXConnectorServer(url, serverEnv, newMBeanServer());
+ cntorServer.start();
+ 
+ // How to connect with an MX4J SOAP JMXConnector in J2SE 5
+ Map clientEnv = new HashMap();
+ clientEnv.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, MX4JRemoteConstants.PROVIDER_PACKAGES);
+ 
+ JMXConnector cntor = JMXConnectorFactory.connect(url, clientEnv);
+ 
+ MBeanServerConnection cntion = cntor.getMBeanServerConnection();
+ int count = cntion.getMBeanCount().intValue();
+             ]]>
+          </programlisting>
+       </example>
+    </para>
+    <para>
+       Note the usage of the environment property defined by the constants
+       <classname>JMXConnectorServerFactory.PROTOCOL_PROVIDER_PACKAGES</classname> and
+       <classname>JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES</classname>, respectively for server and client,
+       and note how MX4J provides a convenient constant for their values:
+       <classname>MX4JRemoteConstants.PROVIDER_PACKAGES</classname>.
+    </para>
+    <para>
+       Further information on the JSR 160 external provider loading mechanism are detailed in the
+       <ulink url="http://jcp.org/en/jsr/detail?id=160">JSR 160 specification</ulink> and in javadocs of the
+       <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/remote/JMXConnectorFactory.html">
+          <classname>JMXConnectorFactory</classname>
+       </ulink> and
+       <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/javax/management/remote/JMXConnectorServerFactory.html">
+          <classname>JMXConnectorServerFactory</classname>
+       </ulink> classes.
+    </para>
+ </section>
+ 
+ <section>
     <title>Porting old MX4J remoting code to JSR 160</title>
     <section>



-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click