From jboss-remoting-commits at lists.jboss.org Tue Aug 12 01:58:03 2008 Content-Type: multipart/mixed; boundary="===============6147833926738231525==" MIME-Version: 1.0 From: jboss-remoting-commits at lists.jboss.org To: jboss-remoting-commits at lists.jboss.org Subject: [jboss-remoting-commits] JBoss Remoting SVN: r4506 - remoting2/branches/2.x/docs/guide/en. Date: Tue, 12 Aug 2008 01:58:03 -0400 Message-ID: --===============6147833926738231525== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: ron.sigal(a)jboss.com Date: 2008-08-12 01:58:03 -0400 (Tue, 12 Aug 2008) New Revision: 4506 Added: remoting2/branches/2.x/docs/guide/en/chap-classloaders.xml Log: JBREM-1000, JBREM-1019: New chapter about classloading. Added: remoting2/branches/2.x/docs/guide/en/chap-classloaders.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- remoting2/branches/2.x/docs/guide/en/chap-classloaders.xml = (rev 0) +++ remoting2/branches/2.x/docs/guide/en/chap-classloaders.xml 2008-08-12 0= 5:58:03 UTC (rev 4506) @@ -0,0 +1,201 @@ + + + Remote classloading facility + + When a Remoting unmarshaller reads a serialized request or respons= e from + the network, it needs to have access to the classes of the objects conta= ined + in the serialized object. Frequently, these will be a simple combination= of + Remoting and Java objects. For example, if an application returns a + java.lang.String, it will be wrapped in an + org.jboss.remoting.InvocationResponse, and both c= lasses + 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. + = +
+ Classloading in client invokers + + An instance of + org.jboss.remoting.marshal.serializable.SerializableUnMarsh= aller, + which is the default unmarshaller, or parent of the default unmarshall= er, + for the socket, bisocket, and http transports (marshalling and unmarsh= alling + in the rmi transport is handled by the RMI runtime), will look for cla= sses + in the following order: + = + + + + try system classloader, which loads from locations specifi= ed in the classpath; + + = + + try the Remoting classloader, that is, the classloader that + loaded the Remoting classes (which, depending on the context, ma= y or may not be the system classloader); + + = + + try to load from Remoting's remote classloading facility;<= /para> + + = + + try the current thread's context classloader. + + + = + The current thread's context classloader can be moved to the fro= nt of + the list to enable the alternative behavior: + + + = + + try the current thread's context classloader; + + + + try system classloader, which loads from locations specifi= ed in the classpath; + + = + + try the Remoting classloader, that is, the classloader that + loaded the Remoting classes (which, depending on the context, ma= y or may not be the system classloader); + + = + + try to load from Remoting's remote classloading facility.<= /para> + + + = + This alternative behavior may be enabled either by setting the + org.jboss.remoting.Remoting.CLASSLOADING_PARENT_FIRST_DELEGATION= + parameter (actual value "classloadingParentFirstDelegation") to "false= " in + the InvokerLocator or in the client invoker's + configuration map (see for m= ore on + configuration options) or by setting the system property + Remoting.CLASSLOADING_PARENT_FIRST_DELEGATION_PROP (actual value + "org.jboss.remoting.classloadingParentFirstDelegation") to "false". + = + Note that the default behavior, in the absence of any explicit a= ction + to the contrary, is for a thread's context classloader to be set to th= e 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 t= he + thread context classloader to the EAR classloader whenever it passes c= ontrol + 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. Note, by t= he way, + the implication that this discussion about classloading in client invo= kers + applies not only to clients in the ordinary client server sense, but a= lso to + clients running inside the server. +
+ = +
+ Server side support for remote classloading + = + 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 fa= cility + is provided by a special + org.jboss.remoting.transport.Connector that run= s an + org.jboss.remoting.ServerInvocationHandler desi= gned + to locate and return requested classes. This facility is enabled by + configuring a Connector with the parameter + org.jboss.remoting.InvokerLocator.LOADER_PORT (actual val= ue + "loaderport") set to an available port number. (See for more on configuration options.= ) Using + the "loaderport" parameter will result in the creation of a second + Connector which responds to requests to download + classes. + = + Prior to Remoting release 2.4.0.SP1, the classloading search + implemented by the classloading + SerrverInvocationHandler was the following: + + + + try system classloader, which loads from locations specifie= d in the classpath; + + = + + 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). + + + = + This original behavior is too restrictive in the context of the r= ich + classloading options of the JBoss Application Server. As of release + 2.4.0.SP1, it is possible to configure the classloading facility with a= list + of additional classloaders. One option is to pass a list of classloader= s to a + Connector programatically using the + org.jboss.remoting.Remoting.Remoting.REMOTE_CLASS_LOADERS + parameter (actual value "remoteClassLoaders") in either a configuration= map + or an org.jboss.remoting.ServerConfiguration. For + example: + = + +ServerConfiguration serverConfiguration =3D new ServerConfiguration("socke= t"); +Map invokerLocatorParameters =3D new HashMap(); +invokerLocatorParameters.put(InvokerLocator.LOADER_PORT, "5544"); +serverConfiguration.setInvokerLocatorParameters(invokerLocatorParameters); +Map serverParameters =3D new HashMap(); +ArrayList classLoaders =3D new ArrayList(); +classLoader1 =3D ... +classLoader2 =3D ... +classLoaders.add(classLoader1); +classLoaders.add(classLoader2); +serverParameters.put(Remoting.REMOTE_CLASS_LOADERS, classLoaders); +serverConfiguration.setServerParameters(serverParameters); +connector =3D new Connector(); +connector.setServerConfiguration(serverConfiguration); + + = + An alternative in the presence of the JBoss microcontainer, e.g.,= in + the Application Server, would be to achieve the same result declarative= ly. + For example: + = + <?xml version=3D"1.0" encoding=3D"UTF-8"?> +<deployment xmlns=3D"urn:jboss:bean-deployer:2.0"> + = + <bean name=3D"remoting:serverConfiguration" + class=3D"org.jboss.remoting.ServerConfiguration"> + <constructor> + <parameter>socket</parameter> + </constructor> + <property name=3D"invokerLocatorParameters"> + <map keyClass=3D"java.lang.String" valueClass=3D"java.lang.Str= ing"> + <entry> + <key>loaderport</key> + <value>5544</value> + </entry> + </map> + </property> + <property name=3D"serverParameters"> + <map keyClass=3D"java.lang.String" valueClass=3D"java.lang.Obj= ect"> + <entry> + <key>remoteClassLoaders</key> + <value> + <list elementClass=3D"java.lang.ClassLoader"> + <value>ear1:classloader</value> + <value>ear2:classloader</value> + </list> + </value> + </entry> + </map> + </property> + <property name=3D"invocationHandlers"> + ... + </property> + </bean> + = + <bean name=3D"remoting:connector" class=3D"org.jboss.remoting.transp= ort.Connector"> + <property name=3D"serverConfiguration"> + <inject bean=3D"remoting:serverConfiguration"/> + </property> + </bean> + = +</deployment> +
+ --===============6147833926738231525==--