<document>
  <header>
    <product>resin</product>
    <resin-2.0>$resin/ref/jndi.xtp</resin-2.0>
    <title>Resource Configuration</title>
  </header>

  <body>
    <summary/>

<section title="web-apps and JNDI Contexts">

<p>Resin organizes its resources into a tree, rooted in the
system classloader.  Each Resin context is associated with a classloader,
a JNDI context, and a set of resources (databases, JMS, EJB beans, etc.)</p>

<p>Child contexts inherit classes and resources from
the parent contexts.  For example, a database with a JNDI name
"java:comp/env/jdbc/foo" belonging to the foo.com virtual host would be
shared for all web-applications in that host.</p>

<p>When Resin detects class or configuration changes in a context, it
will reload that context and all child contexts.  This is how Resin
reloads an application when a servlet changes.</p>

<figure src="jndi_tree.gif"/>

<p>Each web-app gets its own JNDI copy.  So a web-app named /quercus
and a web-app named /cmp could each use java:comp/env/jdbc/test for a
database pool, but would use unique pools (probably using
different databases.)</p>

<p>This separation keeps web-apps from stepping on each other's toes
and also lets each virtual host use different databases.</p>

<p>The web-apps can share JNDI configuration from its host, and the
hosts can share JNDI configuration from the global server.  Each
web-app copies the host JNDI tree, and each host copies the server
JNDI tree.  So the web-app can't affect the host's JNDI, but it can
share the host's pools.</p>

<p>In Resin's configuration, the context determines where the JNDI
will be shared.  If the JNDI configuration is in the &lt;host>, it will
be shared across the entire host.  If it's in the &lt;web-app>, it
will only be used in the web-app.</p>

<deftable>
<tr><th>context<th>scope
<tr><td>http-server<td>shared across all applications
<tr><td>host<td>shared across the virtual host
<tr><td>web-app<td>specific to the servlet application (.war)
</deftable>

<example title='host and web-app specific configuration'>
...
&lt;host id='foo.com'>
  &lt;database name='jdbc/foo'>
    &lt;driver-class id="org.gjt.mm.mysql.Driver"/>
    &lt;driver-url id="jdbc:mysql://localhost:3306/foo"/>
  &lt;/database>

  &lt;web-app id='/quercus'>
    &lt;database name='jdbc/quercus'.
      &lt;driver-class id="org.gjt.mm.mysql.Driver"/>
      &lt;driver-url id="jdbc:mysql://localhost:3306/quercus"/>
    &lt;/database>
  &lt;/web-app>
&lt;/host>
...
</example>

<p>In the previous example, the java:comp/env/jdbc/foo pool is shared
across all web-apps in foo.com, but the java:comp/env/jdbc/quercus
pool is only available in the /quercus web-app.</p>

</section>

  </body>
</document>
