[jboss-cvs] JBossAS SVN: r67443 - projects/microcontainer/trunk/docs/User_Guide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Nov 26 09:56:40 EST 2007
Author: newtonm
Date: 2007-11-26 09:56:40 -0500 (Mon, 26 Nov 2007)
New Revision: 67443
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Redrafted Chapter 4 section titles.
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-11-26 14:32:38 UTC (rev 67442)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-11-26 14:56:40 UTC (rev 67443)
@@ -472,7 +472,7 @@
<para>Depending on how you access the service at runtime you may need to shutdown the application and restart it again to redeploy the service and see your changes. This reduces the flexibility of the application but results in faster performance at runtime. Alternatively you may be able to simply redeploy the service whilst the application is running. This increases flexilibity but results in slower runtime performance. Careful consideration of these tradeoffs must be made before deciding on the approach you will take.</para>
</section>
<section>
- <title>Accessing a service directly</title>
+ <title>Direct access</title>
<para>If no parameter is given to the <code>run.sh</code> script when the client is started then a reference to the HRService bean is looked up using the microcontainer controller once the service is deployed:</para>
<programlisting>private final static String HRSERVICE = "HRService";
@@ -504,7 +504,7 @@
<para>To reliably redeploy the reconfigured service you must therefore shutdown the application completely using the 'q' option and then restart it using the run.sh script. For enterprise services such as Transactions, Messaging and Persistance this is not considered a problem since they are generally always in use. As such they cannot be redeployed at runtime and benefit from the high performance given by using direct access. If your service falls into this category then you too should consider using direct access via the microcontainer controller.</para>
</section>
<section>
- <title>Accessing a service indirectly</title>
+ <title>Indirect access</title>
<para>The run.sh script can be called with an optional parameter 'bus' to specify that calls to the Human Resources service should take place using the microcontainer bus:</para>
<programlisting>./run.sh bus</programlisting>
<para>We no longer lookup a direct reference to the bean instance using the microcontainer controller but instead call an invoke() method on the bus passing in the bean name, method name, method arguments and method types. The bus takes this information and uses it to call the bean on the client's behalf.</para>
@@ -533,10 +533,10 @@
<note>
<para>You can test this behaviour out for yourself by deploying the service and using the 'p' option to print out the status. Undeploy the service using the 'u' option and check that you cannot access it anymore. Now make some changes to the configuration using the jboss-beans.xml file and deploy it again using the 'd' option (remember to save any changes you make to jboss-beans.xml first). Printing out the status again using the 'p' option should reveal that the client is accessing the new service configuration.</para>
</note>
- <para>As the bus uses reflection to call bean instances it is slower than using direct access. The benefit however is that only the bus references the bean instances directly. This means that when a service is redeployed we can clean up all of the existing references and replace them with new ones, allowing us to reliably redeploy a service at runtime. Services that are not used very often or that are specific to certain applications are good candidates for indirect access using the microcontainer bus.</para>
+ <para>As the bus uses reflection to call bean instances it is slower than using direct access. The benefit however is that only the bus references the bean instances directly. This means that when a service is redeployed we can clean up all of the existing references and replace them with new ones, allowing us to reliably redeploy a service at runtime. Services that are not used very often or that are specific to certain applications are good candidates for indirect access using the microcontainer bus. This is either because the lack in performance does not matter if the service is used rarely or the service can be deployed and undeployed together with the relevant applications to keep the runtime environment clean.</para>
</section>
<section>
- <title>Dynamic deployment</title>
+ <title>Dynamic classloading</title>
<para>So far we have been using the external and application classloaders to load all of the classes in our application. The application classpath was setup by the run.sh script using the -cp flag to include the current directory and the client-1.0.0.jar.</para>
<programlisting>java -Djava.ext.dirs=`pwd`/lib -cp .:client-1.0.0.jar org.jboss.example.client.Client $1</programlisting>
<para>For convenience the JARs in the lib directory were added to the external classloader's classpath using the <code>java.ext.dirs</code> system property as this prevents us from having to list the full path to each of the JARs after the -cp flag. Since the external classloader is the parent of the application classloader our client classes can find all of the microcontainer classes together with the Human Resources service classes at runtime.</para>
@@ -544,8 +544,9 @@
<para>If you are using Java 6+ then you can use a wildcard to include all JARs in a directory with the -cp flag.<programlisting>java -cp `pwd`/lib/*:.:client-1.0.0.jar org.jboss.example.client.Client $1</programlisting>This means that all of the classes in our application will be added to the application classloader's classpath.</para>
</note>
<para>This is all well and good but what happens if we now want to deploy an additional service at runtime? If the new service is packaged in a JAR file then it needs to be visible to a classloader before any of the classes can be loaded. The trouble is we have already setup the classpath for the application classloader (and external classloader) on startup so we cannot easily add the url of the JAR. The same situation applies if the service classes are contained in a directory structure. Unless the top-level directory is located in the current directory (which is on the application classpath) then the classes will not be found by the application classloader.</para>
- <para>What we need is the ability to create a new classloader that knows the location of the new service's classes so that we can load them and deploy the service's beans. JBoss Microcontainer allows us to do this using the <classloader> element in the deployment descriptor.</para>
- <para>Also mention the fact that we need to create a new classloader if we want to reload the service after we have recompiled the classes. Creating new classloaders is necessary because we wish to deploy new services or redeploy existing ones at runtime without stopping the server. It is therefore the deployer which is responsible for creating a classloader and in doing so it must also consider what the parent of the newly created classloader should be.</para>
+ <para>It's also possible that we wish to redeploy an existing service with changes to some of its classes. Since it is forbidden for an existing classloader to reload classes (due to security constraints) how can this be done?</para>
+ <para>What we need is the ability to create a new classloader that knows the location of the new service's classes, or that can load in new versions of an existing service's classes, so that we can deploy the service's beans. JBoss Microcontainer allows us to do this using the <classloader> element in the deployment descriptor.</para>
+ <para> It is the deployer which is responsible for creating a classloader and in doing so it must also consider what the parent of the newly created classloader should be.</para>
</section>
</chapter>
<chapter>
More information about the jboss-cvs-commits
mailing list