donaldp 2002/09/01 01:47:40
Modified: loader/src/xdocs menu.xml sample.xml
Log:
Doc updates.
Revision Changes Path
1.3 +1 -1 jakarta-avalon-excalibur/loader/src/xdocs/menu.xml
Index: menu.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/loader/src/xdocs/menu.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- menu.xml 1 Sep 2002 06:23:09 -0000 1.2
+++ menu.xml 1 Sep 2002 08:47:40 -0000 1.3
@@ -16,7 +16,7 @@
<item name="DTD" href="/classloader.dtd"/>
</menu>
<menu name="Developers Guide">
- <item name="Embedding HOWTO" href="/index.html"/>
+ <item name="Embedding HOWTO" href="/embedding.html"/>
</menu>
</body>
</project>
1.2 +134 -3 jakarta-avalon-excalibur/loader/src/xdocs/sample.xml
Index: sample.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/loader/src/xdocs/sample.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- sample.xml 1 Sep 2002 06:23:09 -0000 1.1
+++ sample.xml 1 Sep 2002 08:47:40 -0000 1.2
@@ -7,9 +7,140 @@
</properties>
<body>
<section name="Introduction">
- <p>This describes a simple example of Loader descriptor
- used to host a simple application.</p>
- <p>TODO: Finish code then finish guide.</p>
+ <p>This describes a simple example of Loader descriptor.
+ Let us assume that
+ <a href="http://jakarta.apache.org/avalon/phoenix";>Phoenix</a>
+ has been integrate with Loader and that the snippet defining
+ classloader is included in Phoenixes deployment format (the
+ .sar file).</p>
+ <p>Let us also assume that we want to host a servlet container
+ (like Catalina, Jo! or Jetty) in Phoenix. The servlet
+ specification requires that the servlets are capable of
+ "seeing" the servlet API but recomends strongly that no servlet
+ should be able to access any container specific classes.</p>
+ <p>To satisfy this requirement we decided to place the
+ Servlet API classes in a parent ClassLoader to the Containers
+ ClassLoader and each Web Applications ClassLoader. ie</p>
+<pre>
+ Servlet API CL
+ |
+ +------+------+
+ | |
+ Servlet WebApp
+Container CL
+ CL
+</pre>
+ <p>This way, both the Container and the WebApp ClassLoaders will
+ load the Servlet API from the same ClassLoader.</p>
+ <p>Unfortunately, in our case Phoenix already assembles the
+ Servlet Container CL by default and does not give us the
+ opportunity to construct the Servlet API CL as a parent ClassLoader.
+ Luckily we can overide this using the Loader toolkit using the
+ following configuration file.</p>
+<source>
+ <![CDATA[
+<classloaders default="container" version="1.0">
+
+ <!-- needed to run under earlier JVMs that do not include JNDI -->
+ <classloader name="jndi-api" parent="*system*">
+ <entry location="sar:SAR-INF/ext/jndi.jar"/>
+ </classloader>
+
+ <!--
+ The actual Servlet API classLoader. Note that this does not specify
+ a physical location but instead defines an extension. This allows
+ the container to search for the library that best satisfies this
+ extension. Usually all the extensions are stored in a central directory
+ and Phoenix will search through the jars in central to find the servlet
+ jar. This allows several applications to share the same jar.
+ -->
+ <classloader name="servlet-api" parent="*system*">
+ <extension>
+ <name>javax.servlet</name>
+ <specification-version>2.3</specification-version>
+ <vendor-id>org.apache.jakarta</vendor-id>
+ <vendor-version>1.2.3.4</vendor-version>
+ </extension>
+ </classloader>
+
+ <!--
+ This is a special ClassLoader that merges two other
+ ClassLoaders together. When you try to load a class from
+ this ClassLoader, the ClassLoader will first try to load
+ the class from servlet-api ClassLoader and then try to
+ load the class from the jndi-api ClassLoader. This works
+ fine if the ClassLoaders define disjoint sets of classes.
+ ie No class should be loadable from both the servlet-api
+ ClassLoader and the jndi-api ClassLoader (with the exception
+ of Classes Loaded from System ClassLoader).
+ -->
+ <join name="common">
+ <classloader-ref name="servlet-api"/>
+ <classloader-ref name="jndi-api"/>
+ </join>
+
+ <!--
+ This classloader is needed to join the Phoenix API
+ and the Servlet API into one ClassLoader. This is needed
+ because the container is built using Phoenix APIs
+ but needs to share the Servlet APIs with the WebApps.
+ -->
+ <join name="container-base">
+ <classloader-ref name="common"/>
+ <classloader-ref name="*phoenix.api*"/>
+ </join>
+
+ <!--
+ This classloader is the one used to actually load the
+ Servlet Container. We know this as it is specified as the
+ default ClassLoader in <classloaders/> element.
+ -->
+ <classloader name="container" parent="container-base">
+ <entry location="sar:SAR-INF/classes/"/>
+ <fileset dir="sar:SAR-INF/lib/">
+ <include name="*.jar"/>
+ </fileset>
+ </classloader>
+
+</classloaders>
+]]></source>
+ <p>The first thing you notice about this is that
+ the ClassLoader hierarchy is much more complicated.
+ In fact the diagram now looks like;</p>
+<pre>
+ "servlet-api" "jndi-api"
+ CL CL
+ | |
+ +------+------+
+ |
+ "*phoenix.api*" "common" CL
+ | |
+ +----+ +------+------+
+ | | |
+ "container- WebApp
+ base" CL
+ CL (This is constructed
+ | by Container but
+ "container" shown for completeness)
+ CL
+</pre>
+ <p>In reality we could have merged "servlet-api" and
+ "jndi-api" into "common" but we separated them for
+ illustration purposes.</p>
+ <p>One thing you should notice is that Phoenix
+ exposes two predefined ClassLoaders;</p>
+ <ul>
+ <li><b>*system*</b>: The system ClassLoader</li>
+ <li><b>*phoenix.api*</b>: The ClassLoader that
+ Phoenix uses to communicate with it's hosted
+ components.</li>
+ </ul>
+ <p>The above demonstrates one of the most complex examples
+ that you are likely to come across. This arose because there
+ was multiple "containers" hosted in same ClassLoader
+ hierarchy. The Servlet API specification requires that
+ implementation classes not be visible to API clients.
+ The Phoenix API specification requires the same thing.</p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
