[jboss-cvs] JBossAS SVN: r68022 - projects/microcontainer/trunk/docs/User_Guide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Dec 7 05:43:15 EST 2007
Author: newtonm
Date: 2007-12-07 05:43:15 -0500 (Fri, 07 Dec 2007)
New Revision: 68022
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Corrected Defining classloaders chapter.
Modified: projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-07 10:19:33 UTC (rev 68021)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-07 10:43:15 UTC (rev 68022)
@@ -1072,7 +1072,7 @@
<title>Creating POJOs</title>
<section>
<title>Defining classloaders</title>
- <para>In order to create POJO instances we must first load the corresponding POJO classes into the JVM using a classloader. By default JBoss Microcontainer uses the classloader associated with the current thread of execution, i.e. the thread context classloader. But what do we mean by the current thread of execution and who sets its context classloader?</para>
+ <para>In order to create POJO instances we must first load the corresponding POJO classes into the JVM using a classloader. JBoss Microcontainer does this by using the classloader associated with the current thread of execution, i.e. the thread context classloader. But what do we mean by the current thread of execution and who sets its context classloader?</para>
<para>In all of our examples so far we have created applications that only use a single thread. This is the 'primordial' thread created by the main() function:</para>
<programlisting>public static void main(String[] args) {}</programlisting>
<para>As the only thread in the application (other than the garbage collecton thread which is created for every Java application) this executes all of the code including calling the deploy() method of our BasicXMLDeployer:</para>
@@ -1110,17 +1110,17 @@
...
}</programlisting>
- <para>The deploy() method takes a URL representing the location of the XML deployment descriptor and passes it as a string to an unmarshaller. The unmarshaller then parses the XML, converts it into an object representation called a KernelDeployment and sets its name to the string value of the URL. The KernelDeployment object is then passed to the deploy() method of the superclass BasicKernelDeployer. The BasicKernelDeployer deploy() method iterates through all of the beans in the deployment creating a context for each one which it subsequently passes to the microcontainer contoller's install() method to peform the deployment. The controller then performs actions on each context to take the bean from one state to another: NOT_INSTALLED, DESCRIBED, CONFIGURED, INSTANTIATED, CREATE, START, INSTALLED. Once a bean reaches the INSTALLED state then it's considered to be deployed.</para>
+ <para>The deploy() method takes a URL representing the location of an XML deployment descriptor and passes it as a string to an unmarshaller. The unmarshaller parses the XML, converts it into an object representation called a KernelDeployment and sets its name. The KernelDeployment object is then passed to the deploy() method of the superclass BasicKernelDeployer. This iterates through all of the beans in the deployment creating a context for each one which it subsequently passes to the contoller's install() method to peform the deployment. The controller then performs actions on each context to take the bean from one state to another: NOT_INSTALLED, DESCRIBED, CONFIGURED, INSTANTIATED, CREATE, START, INSTALLED. Once a bean reaches the INSTALLED state then it's considered to be deployed.</para>
<important>
- <para>During the deployment process, as the controller performs the Instantiate action, the thread context classloader is used as the default classloader to load the bean's class into the JVM. Since the controller code must be executed by a single thread in order to preserve the integrity of the state machine, the thread that calls the controller.install() method is by definition the current thread of execution.</para>
+ <para>During the deployment process, as the controller performs the Instantiate action, the thread context classloader is used to load the bean's class into the JVM. As all of the controller code is executed by the thread that calls controller.install(), this is what we mean by the current thread of execution.</para>
</important>
- <para>Therefore when using the BasicXMLDeployer the default classloader is retrieved from the thread that calls the BasicXMLDeployer's deploy() method as this goes on to call controller.install() which subsequently executes the Instantiate action. For all of our examples this is the primordial thread. The context class loader of the primordial thread is set to the classloader that loaded the application, i.e. the application classloader. This means that by default this classloader can load any classes present on the application, extension or boot classpaths which is why we are able to load the bean classes in our examples.</para>
+ <para>Therefore when using the BasicXMLDeployer the classloader used to load bean classes is retrieved from the thread that calls the BasicXMLDeployer's deploy() method as this goes on to call controller.install() which subsequently executes the Instantiate action. For all of our examples this is the primordial thread whose context classloader is set on startup to the classloader that loaded the application, i.e. the application classloader. This means that in our examples the microcontainer can load any bean classes present on the application, extension or boot classpaths.</para>
<para>What happens though if we create our own threads in the application and use these to call the deploy() method of our BasicXMLDeployer?</para>
- <para>If you create a thread then by default its context classloader will be set to the parent thread's context classloader. As any hierarchy of threads is ultimately rooted at the primordial thread this means that they will all use the application classloader providing you don't explicitly call setContextClassLoader() at any point. If you do call setContextClassLoader() on a thread then any threads that it creates will inherit the classloader that you set.</para>
+ <para>If you create a thread then by default its context classloader will be set to the parent thread's context classloader. As any hierarchy of threads is ultimately rooted at the primordial thread this means that by default they will all use the application classloader. To change this you simply need to call setContextClassLoader() on a thread at runtime. This is typically done on the current thread using <code>Thread.currentThread().setContextClassloader()</code>.</para>
<note>
- <para>If you choose not to use the BasicXMLDeployer and instead use the equivalent aspectized deployer then the default classloader is taken from the thread that calls the process() method of the MainDeployer. This is because the MainDeployer process() method iterates through all of the registered deployers calling their process() methods which in turn call controller.install() to perform the deployment. </para>
+ <para>If you choose not to use the BasicXMLDeployer and instead use the equivalent aspectized deployer then the classloader used to load bean classes is taken from the thread that calls the process() method of the MainDeployer. This is because the MainDeployer process() method iterates through all of the registered deployers calling their process() methods which in turn call controller.install() to perform the deployment. </para>
</note>
- <para>Now that we know how the microcontainer gets the default classloader how can we change this to use our own?</para>
+ <para>Now that we know the default classloader comes from the current thread of execution, which if not set explicitly is set on startup to be the application classloader, how can we change it to load bean classes from other locations?</para>
<para>If you are using the BasicXMLDeployer or its equivalent aspectized deployer then you can define classloaders for entire deployments or individual beans by including <classloader> elements within the XML deployment descriptor. To specify a different classloader for all the beans in a deployment you need to include a <classloader> element above all of the <bean> elements:</para>
<programlisting><deployment>
<classloader><inject bean="deploymentCL"/></classloader>
@@ -1187,9 +1187,9 @@
<classloader><inject bean="customCL"/></classloader>
...
</bean></programlisting>
- <para>If a classloader is not available for a bean when an attempt is made to deploy it then the bean will remain in a pre INSTANTIATED state. Once the classloader is deployed then the bean will automatically continue to deploy. </para>
+ <para>If a classloader is not available for a bean when an attempt is made to deploy it then the bean will remain in a pre INSTANTIATED state. Once the classloader is deployed then the bean will automatically continue to deploy. This means that you can define classloaders in the deployment descriptor after beans that depend on them and everything will deploy as expected.</para>
<note>
- <para>User defined classloaders are detected by the microcontainer during the deployment process as the controller performs the Instantiate action. They are used instead of the default classloader by calling setContextClassLoader() on the current thread. After deployment the default classloader is put back by calling setContexClassLoader() again.</para>
+ <para>User defined classloaders are detected by the microcontainer during the deployment process as the controller performs the Instantiate action. They are used instead of the default classloader by calling setContextClassLoader() on the current thread. In this way they can be subsequently retrieved by code that loads the bean class using Thread.currentThread().getContextClassLoader(). After the bean class has been loaded the default classloader is put back by calling setContexClassLoader() again.</para>
</note>
</section>
<section>
More information about the jboss-cvs-commits
mailing list