[CVS jcontainer] Add in classman docs
Peter Donald <pdonald-yCVjj/[email protected]> Wed, 31 Mar 2004 22:45:55 -0600
| Newsgroups | gmane.comp.java.jcontainer.cvs |
|---|---|
| Message-ID | <[email protected]> |
<html>
<head>
<style><!--
body {background-color:#ffffff;}
.file {border:1px solid #eeeeee;margin-top:1em;margin-bottom:1em;}
.pathname {font-family:monospace; float:right;}
.fileheader {margin-bottom:.5em;}
.diff {margin:0;}
.tasklist {padding:4px;border:1px dashed #000000;margin-top:1em;}
.tasklist ul {margin-top:0;margin-bottom:0;}
tr.alt {background-color:#eeeeee}
#added {background-color:#ddffdd;}
#addedchars {background-color:#99ff99;font-weight:bolder;}
tr.alt #added {background-color:#ccf7cc;}
#removed {background-color:#ffdddd;}
#removedchars {background-color:#ff9999;font-weight:bolder;}
tr.alt #removed {background-color:#f7cccc;}
#info {color:#888888;}
#context {background-color:#eeeeee;}
td {padding-left:.3em;padding-right:.3em;}
tr.head {border-bottom-width:1px;border-bottom-style:solid;}
tr.head td {padding:0;padding-top:.2em;}
.task {background-color:#ffff00;}
.comment {padding:4px;border:1px dashed #000000;background-color:#ffffdd}
.error {color:red;}
hr {border-width:0px;height:2px;background:black;}
--></style>
</head>
<body>
<table cellspacing="0" cellpadding="0" border="0" rules="cols">
<tr class="head"><td colspan="4">Commit in <b><tt>jcontainer/loom/site/xdocs/reference</tt></b><span id="info"> on MAIN</span></td></tr>
<tr><td><tt><a href="#file1"><span id="added">classman.xml</span></a></tt></td><td align="right" id="added">+166</td><td></td><td nowrap="nowrap" align="right">added <a href="http://xstream.cvs.codehaus.org/jcontainer/loom/site/xdocs/reference/classman.xml?rev=1.1&content-type=text/vnd.viewcvs-markup">1.1</a></td></tr>
</table>
<pre class="comment">
Add in classman docs
</pre>
<hr /><a name="file1" /><div class="file">
<span class="pathname" id="added"><a href="http://xstream.cvs.codehaus.org/jcontainer">jcontainer</a>/<a href="http://xstream.cvs.codehaus.org/jcontainer/loom">loom</a>/<a href="http://xstream.cvs.codehaus.org/jcontainer/loom/site">site</a>/<a href="http://xstream.cvs.codehaus.org/jcontainer/loom/site/xdocs">xdocs</a>/<a href="http://xstream.cvs.codehaus.org/jcontainer/loom/site/xdocs/reference">reference</a><br /></span>
<div class="fileheader" id="added"><big><b>classman.xml</b></big> <small id="info">added at <a href="http://xstream.cvs.codehaus.org/jcontainer/loom/site/xdocs/reference/classman.xml?rev=1.1&content-type=text/vnd.viewcvs-markup">1.1</a></small></div>
<pre class="diff"><small id="info">diff -N classman.xml
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ classman.xml 1 Apr 2004 04:45:55 -0000 1.1
@@ -0,0 +1,166 @@
</small></pre><pre class="diff" id="added">+<?xml version="1.0"?>
+
+<document>
+ <properties>
+ <title>ClassMan - Overview</title>
+ <author>Peter Donald</author>
+ </properties>
+ <body>
+ <section name="Introduction">
+ <p>The ClassMan toolkit integrated into Loom is a set of utility
+ classes that enable ClassLoader hierarchies to be constructed from
+ xml configurations. The toolkit supports hierarchial ClassLoaders
+ and ClassLoaders defined by directed graphs via the use of "Join"
+ ClassLoaders that can have multiple parents. This results in
+ construction of a ClassLoader lattice.</p>
+ <p>Each non-Join ClassLoader can be defined in terms of;</p>
+ <ul>
+ <li>Entrys: URLs designating either a directory or a file</li>
+ <li>FileSets: Sets of files defined in a manner similar to Ants Filests.</li>
+ <li>
+ <a href="../Extension.html">
+ Extensions</a>: Definitions of Extensions, aka "Optional Packages".
+ </li>
+ </ul>
+ <p>Each ClassLoader also has a name and a parent. The parent is the
+ name of the parent ClassLoader. Usually the parent ClassLoaders are
+ one of the predefined ClassLoaders. The predefined are passed into
+ the ClassMan toolkit from external application code.</p>
+ <p>The predefined ClassLoaders are generally named according to
+ a pattern that places the '*' at start and end of name. ie
+ "*myPredefinedClassLoader*". Loom predefines the following
+ classloaders.</p>
+ <ul>
+ <li>*system*: The System ClassLoader.</li>
+ <li>*common*: Common between container and application code.</li>
+ <li>*shared*: Shared between all application code. Note: This is currently
+ equivelent to *common*.</li>
+ </ul>
+ <p>The commented
+ <a href="classloader.dtd">DTD</a> describes the
+ descriptor format explicitly.
+ </p>
+ </section>
+ <section name="Loom Sample">
+ <p>Let us also assume that we want to host a servlet container
+ (like Catalina, Jo! or Jetty) in Loom. 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><![CDATA[
+ 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 Loom 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 ClassMan 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 Loom 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="webapp-common">
+ <classloader-ref name="servlet-api"/>
+ <classloader-ref name="jndi-api"/>
+ </join>
+
+ <!--
+ This classloader is needed to join the Loom API
+ and the Servlet API into one ClassLoader. This is needed
+ because the container is built using Loom APIs
+ but needs to share the Servlet APIs with the WebApps.
+ -->
+ <join name="container-base">
+ <classloader-ref name="webapp-common"/>
+ <classloader-ref name="*common*"/>
+ </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><![CDATA[
+ "servlet-api" "jndi-api"
+ CL CL
+ | |
+ +------+------+
+ |
+ "*common*" "webapp-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 "webapp-common" but we separated them for
+ illustration purposes.</p>
+ <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 Loom API specification requires the same thing.</p>
+ </section>
+ </body>
+</document>
</pre><pre class="diff"><small id="info">\ No newline at end of file
</small></pre></div>
<center><small><a href="http://www.badgers-in-foil.co.uk/projects/cvsspam/" title="commit -> email">CVSspam</a> 0.2.8</small></center>
</body></html>