[jboss-remoting-commits] JBoss Remoting SVN: r4778 - remoting2/branches/2.2/docs/guide/en.

Author: ron.sigal(a)jboss.com Date: 2008-12-30 02:11:16 -0500 (Tue, 30 Dec 2008) New Revision: 4778 Added: remoting2/branches/2.2/docs/guide/en/chap-classloaders.xml Modified: remoting2/branches/2.2/docs/guide/en/master.xml Log: JBREM-1041, JBREM-1042: Added section on remote classloading facility. Added: remoting2/branches/2.2/docs/guide/en/chap-classloaders.xml =================================================================== --- remoting2/branches/2.2/docs/guide/en/chap-classloaders.xml (rev 0) +++ remoting2/branches/2.2/docs/guide/en/chap-classloaders.xml 2008-12-30 07:11:16 UTC (rev 4778) @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter> + <title>Remote classloading facility</title> + + <para>When a Remoting unmarshaller reads a serialized request or response from + the network, it needs to have access to the classes of the objects contained + in the serialized object. Frequently, these will be a simple combination of + Remoting and Java objects. For example, if an application returns a + <classname>java.lang.String</classname>, it will be wrapped in an + <classname>org.jboss.remoting.InvocationResponse</classname>, and both classes + will be known to the unmarshaller. But what if an application returns an + unknown implementation of a known interface? Remoting has a remote + classloading facility to support the latter scenario.</para> + + <section id="section-client-classloading" + xreflabel="Classloading in client invokers"> + <title>Classloading in client invokers</title> + + <para>An instance of + <classname>org.jboss.remoting.marshal.serializable.SerializableUnMarshaller</classname>, + which is the default unmarshaller, or parent of the default unmarshaller, + for the socket, bisocket, and http transports (marshalling and unmarshalling + in the rmi transport is handled by the RMI runtime), will look for classes + in the following order:</para> + + <orderedlist> + + <listitem> + <para>try system classloader, which loads from locations specified in the classpath;</para> + </listitem> + + <listitem> + <para>try the Remoting classloader, that is, the classloader that + loaded the Remoting classes (which, depending on the context, may or may not be the system classloader);</para> + </listitem> + + <listitem> + <para>try to load from Remoting's remote classloading facility;</para> + </listitem> + + <listitem> + <para>try the current thread's context classloader.</para> + </listitem> + </orderedlist> + + <para>The current thread's context classloader can be moved to the front of + the list to enable the alternative behavior:</para> + + <orderedlist> + + <listitem> + <para>try the current thread's context classloader;</para> + </listitem> + + <listitem> + <para>try system classloader, which loads from locations specified in the classpath;</para> + </listitem> + + <listitem> + <para>try the Remoting classloader, that is, the classloader that + loaded the Remoting classes (which, depending on the context, may or may not be the system classloader);</para> + </listitem> + + <listitem> + <para>try to load from Remoting's remote classloading facility.</para> + </listitem> + </orderedlist> + + <para>This alternative behavior may be enabled either by setting the + <code>org.jboss.remoting.Remoting.CLASSLOADING_PARENT_FIRST_DELEGATION</code> + parameter (actual value "classloadingParentFirstDelegation") to "false" in + the <classname>InvokerLocator</classname> or in the client invoker's + configuration map (see <xref linkend="chapter-configuration"/> for more on + configuration options) or by setting the system property + Remoting.CLASSLOADING_PARENT_FIRST_DELEGATION_PROP (actual value + "org.jboss.remoting.classloadingParentFirstDelegation") to "false".</para> + + <para>Note that the default behavior, in the absence of any explicit action + to the contrary, is for a thread's context classloader to be set to the same + classloader that loaded the application. However, somewhere outside of + Remoting, the context classloader may be set otherwise. For example, a + Remoting client invoker might be running inside an EJB3 container that + maintains a classloader associated with the EJB3's EAR file and sets the + thread context classloader to the EAR classloader whenever it passes control + into code supplied in the EAR. This situation would arise when one EJB3 + calls another EJB3, where the invocation would ultimately be made by a + Remoting client invoker. <emphasis role="bold">Note</emphasis>, by the way, + the implication that this discussion about classloading in client invokers + applies not only to clients in the ordinary client server sense, but also to + clients running inside the server.</para> + </section> + + <section id="section-server-classloading" + xreflabel="Server side support for remote classloading"> + <title>Server side support for remote classloading</title> + + <para>Remoting implements an optional remote classloading facility that + makes it possible for a client invoker unmarshaller to request copies of + classes that it encounters during the deserialization process. This facility + is provided by a special + <classname>org.jboss.remoting.transport.Connector</classname> that runs an + <classname>org.jboss.remoting.ServerInvocationHandler</classname> designed + to locate and return requested classes. This facility is enabled by + configuring a <classname>Connector</classname> with the parameter + <code>org.jboss.remoting.InvokerLocator.LOADER_PORT</code> (actual value + "loaderport") set to an available port number. (See <xref + linkend="chapter-configuration"/> for more on configuration options.) Using + the "loaderport" parameter will result in the creation of a second + <classname>Connector</classname> which responds to requests to download + classes.</para> + + <para>Prior to Remoting release 2.2.2.SP8, the classloading search + implemented by the classloading + <classname>SerrverInvocationHandler</classname> was the following:</para> + + <orderedlist> + <listitem> + <para>try system classloader, which loads from locations specified in the classpath;</para> + </listitem> + + <listitem> + <para>try the Remoting classloader, that is, the classloader that + loaded the Remoting classes (which, depending on the context, may or + may not be the system classloader).</para> + </listitem> + </orderedlist> + + <para>This original behavior is too restrictive in the context of the rich + classloading options of the JBoss Application Server. As of release + 2.2.2.SP8 (with corrections in release 2.2.2.SP11), + it is possible to configure the classloading facility with a list + of <classname>org.jboss.mx.loading.HeirarchicalLoaderRepository3</classname> + class repositories used in the JBoss Application Server. (For more information about class repositories and scoped classloading, see Section 3.2.2.4. "Inside the JBoss Class Loading Architecture" of the Application Server Guide at <ulink url=" http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Se... + http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Se... + + <para>For example, to allow an EJB3 client to get scoped classes in an EAR where the jboss-app.xml file is</para> + + <programlisting> + &lt;!DOCTYPE jboss-app PUBLIC "-//JBoss//DTD J2EE Application 1.4//EN" "http://www.jboss.org/j2ee/dtd/jboss-app_4_0.dtd"&gt; + &lt;jboss-app&gt; + &lt;loader-repository&gt;jboss.remoting:loader=titan.ear&lt;/loader-repository&gt; + &lt;/jboss-app&gt; + </programlisting> + + <para>the EJB3 Connector should look something like the following, where the new "repositories" attribute is used:</para> + + <programlisting> + &lt;mbean code="org.jboss.remoting.transport.Connector" + name="jboss.remoting:type=Connector,name=DefaultEjb3Connector,handler=ejb3"&gt; + &lt;depends&gt;jboss.aop:service=AspectDeployer&lt;/depends&gt; + &lt;attribute name="Configuration"&gt; + &lt;config&gt; + &lt;invoker transport="socket"&gt; + &lt;attribute name="serverBindAddress"&gt;${jboss.bind.address}&lt;/attribute&gt; + &lt;attribute name="serverBindPort"&gt;3873&lt;/attribute&gt; + &lt;attribute name="loaderport" isParam="true"&gt;3883&lt;/attribute&gt; + &lt;/invoker&gt; + + &lt;repositories&gt; + &lt;repository&gt;jboss.remoting:loader=titan.ear&lt;/repository&gt; + &lt;/repositories&gt; + + &lt;handlers&gt; + &lt;handler subsystem="AOP"&gt;org.jboss.aspects.remoting.AOPRemotingInvocationHandler&lt;/handler&gt; + &lt;/handlers&gt; + &lt;/config&gt; + &lt;/attribute&gt; + &lt;/mbean&gt; + </programlisting> + + <para>That is, the classloader Connector is informed about the HeirarchicalLoaderRepository3 with JMX ObjectName "jboss.remoting:loader=titan.ear".</para> + + </section> +</chapter> Modified: remoting2/branches/2.2/docs/guide/en/master.xml =================================================================== --- remoting2/branches/2.2/docs/guide/en/master.xml 2008-12-30 05:15:07 UTC (rev 4777) +++ remoting2/branches/2.2/docs/guide/en/master.xml 2008-12-30 07:11:16 UTC (rev 4778) @@ -7,6 +7,7 @@ <!ENTITY chap4 SYSTEM "chap4.xml"> <!ENTITY chap5 SYSTEM "chap5.xml"> <!ENTITY chap6 SYSTEM "chap6.xml"> +<!ENTITY chap-classloading SYSTEM "chap-classloaders.xml"> <!ENTITY chap7 SYSTEM "chap7.xml"> <!ENTITY chap8 SYSTEM "chap8.xml"> <!ENTITY chap9 SYSTEM "chap9.xml"> @@ -50,6 +51,8 @@ &chap5; &chap6; + + &chap-classloading; &chap7;