<?xml version="1.0"?>
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="globalresources.html">

  &project;

  <properties>
    <author email="remm@apache.org">Remy Maucherat</author>
    <title>The GlobalNamingResources Component</title>
  </properties>

<body>


<section name="Introduction">

  <p>The <strong>GlobalNamingResources</strong> element represents the global
  JNDI resources which are defined 
  for the <a href="server.html">Server</a>.</p>

</section>


<section name="Attributes">

</section>


<section name="Nested Components">

</section>


<section name="Special Features">


  <subsection name="Environment Entries">

    <p>You can configure named values that will be made visible to
    web applications as environment entry resources, by nesting
    <code>&lt;Environment&gt;</code> entries inside this element.  For
    example, you can create an environment entry like this:</p>
<source>
&lt;GlobalNamingResources ...&gt;
  ...
  &lt;Environment name="maxExemptions" value="10"
         type="java.lang.Integer" override="false"/&gt;
  ...
&lt;/GlobalNamingResources&gt;
</source>

    <p>This is equivalent to the inclusion of the following element in the
    web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
    </p>
<source>
&lt;env-entry&gt;
  &lt;env-entry-name&gt;maxExemptions&lt;/param-name&gt;
  &lt;env-entry-value&gt;10&lt;/env-entry-value&gt;
  &lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
&lt;/env-entry&gt;
</source>
    <p>but does <em>not</em> require modification of the deployment descriptor
    to customize this value.</p>

    <p>The valid attributes for an <code>&lt;Environment&gt;</code> element
    are as follows:</p>

    <attributes>

      <attribute name="description" required="false">
        <p>Optional, human-readable description of this environment entry.</p>
      </attribute>

      <attribute name="name" required="true">
        <p>The name of the environment entry to be created, relative to the
        <code>java:comp/env</code> context.</p>
      </attribute>

      <attribute name="override" required="false">
        <p>Set this to <code>false</code> if you do <strong>not</strong> want
        an <code>&lt;env-entry&gt;</code> for the same environment entry name,
        found in the web application deployment descriptor, to override the
        value specified here.  By default, overrides are allowed.</p>
      </attribute>

      <attribute name="type" required="true">
        <p>The fully qualified Java class name expected by the web application
        for this environment entry.  Must be one of the legal values for
        <code>&lt;env-entry-type&gt;</code> in the web application deployment
        descriptor:  <code>java.lang.Boolean</code>,
        <code>java.lang.Byte</code>, <code>java.lang.Character</code>,
        <code>java.lang.Double</code>, <code>java.lang.Float</code>,
        <code>java.lang.Integer</code>, <code>java.lang.Long</code>,
        <code>java.lang.Short</code>, or <code>java.lang.String</code>.</p>
      </attribute>

      <attribute name="value" required="true">
        <p>The parameter value that will be presented to the application
        when requested from the JNDI context.  This value must be convertable
        to the Java type defined by the <code>type</code> attribute.</p>
      </attribute>

    </attributes>

  </subsection>


  <subsection name="Resource Definitions">

    <p>You can declare the characteristics of the resource
    to be returned for JNDI lookups of <code>&lt;resource-ref&gt;</code> and
    <code>&lt;resource-env-ref&gt;</code> elements in the web application
    deployment descriptor.  You <strong>MUST</strong> also define
    <a href="#Resource Parameters">Resource Parameters</a>
    for the same resource name, to configure
    the object factory to be used (if not known to Tomcat already), and
    the properties used to configure that object factory.</p>

    <p>For example, you can create a resource definition like this:</p>
<source>
&lt;GlobalNamingResources ...&gt;
  ...
  &lt;Resource name="jdbc/EmployeeDB" auth="Container"
            type="javax.sql.DataSource"
     description="Employees Database for HR Applications"/&gt;
  ...
&lt;/GlobalNamingResources&gt;
</source>

    <p>This is equivalent to the inclusion of the following element in the
    web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
<source>
&lt;resource-ref&gt;
  &lt;description&gt;Employees Database for HR Applications&lt;/description&gt;
  &lt;res-ref-name&gt;jdbc/EmployeeDB&lt;/res-ref-name&gt;
  &lt;res-ref-type&gt;javax.sql.DataSource&lt;/res-ref-type&gt;
  &lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;
</source>

    <p>but does <em>not</em> require modification of the deployment
    descriptor to customize this value.</p>

    <p>The valid attriutes for a <code>&lt;Resource&gt;</code> element
    are as follows:</p>

    <attributes>

      <attribute name="auth" required="false">
        <p>Specify whether the web Application code signs on to the
        corresponding resource manager programatically, or whether the
        Container will sign on to the resource manager on behalf of the
        application.  The value of this attribute must be
        <code>Application</code> or <code>Container</code>.  This
        attribute is <strong>required</strong> if the web application
        will use a <code>&lt;resource-ref&gt;</code> element in the web
        application deployment descriptor, but is optional if the
        application uses a <code>&lt;resource-env-ref&gt;</code> instead.</p>
      </attribute>

      <attribute name="description" required="false">
        <p>Optional, human-readable description of this resource.</p>
      </attribute>

      <attribute name="name" required="true">
        <p>The name of the resource to be created, relative to the
        <code>java:comp/env</code> context.</p>
      </attribute>

      <attribute name="scope" required="false">
        <p>Specify whether connections obtained through this resource
        manager can be shared.  The value of this attribute must be
        <code>Shareable</code> or <code>Unshareable</code>.  By default,
        connections are assumed to be shareable.</p>
      </attribute>

      <attribute name="type" required="true">
        <p>The fully qualified Java class name expected by the web
        application when it performs a lookup for this resource.</p>
      </attribute>

    </attributes>


  </subsection>


  <subsection name="Resource Parameters">

    <p>This element is used to configure the resource manager (or object
    factory) used to return objects when the web application performs a
    JNDI lookup operation on the corresponding resource name.  You
    <strong>MUST</strong> define resource parameters for every resource name
    that is specified by a <code>&lt;Resource&gt;</code> element inside a
    <code>&lt;Context&gt;</code> or <code>&lt;DefaultContext&gt;</code>
    element in <code>$CATALINA_HOME/conf/server.xml</code>, and/or for every
    name declared in a <code>&lt;resource-ref&gt;</code> or
    <code>&lt;resource-env-ref&gt;</code> element in the web application
    deployment descriptor, before that resource can be successfully
    accessed.</p>

    <p>Resource parameters are defined by name, and the precise set of
    parameter names supported depend on the resource manager (or object
    factory) you are using - they must match the names of settable JavaBeans
    properties on the corresponding factory class.  The JNDI implementation
    will configure an instance of the specified factory class specified by
    calling all the corresponding JavaBeans property setters, and then
    making the factory instance available via the JNDI <code>lookup()</code>
    call.</p>

    <p>The resource parameters for a JDBC data source might look something
    like this:</p>
<source>
&lt;GlobalNamingResources ...&gt;
  ...
  &lt;ResourceParams name="jdbc/EmployeeDB"&gt;
    &lt;parameter&gt;
      &lt;name&gt;driverClassName&lt;/name&gt;
      &lt;value&gt;org.hsql.jdbcDriver&lt;/value&gt;
    &lt;/parameter&gt;
    &lt;parameter&gt;
      &lt;name&gt;driverName&lt;/name&gt;
      &lt;/value&gt;jdbc:HypersonicSQL:database&lt;/value&gt;
    &lt;/parameter&gt;
    &lt;parameter&gt;
      &lt;name&gt;user&lt;/name&gt;
      &lt;value&gt;dbusername&lt;/value&gt;
    &lt;/parameter&gt;
    &lt;parameter&gt;
      &lt;name&gt;password&lt;/name&gt;
      &lt;value&gt;dbpassword&lt;/value&gt;
    &lt;/parameter&gt;
  &lt;/ResourceParams&gt;
  ...
&lt;/GlobalNamingResources&gt;
</source>

    <p>If you need to specify the Java class name of a factory class for a
    particular resource type, use a <code>&lt;parameter&gt;</code> entry
    named <code>factory</code> nested inside the
    <code>&lt;ResourceParams&gt;</code> element.</p>

    <p>The valid attributes of a <code>&lt;ResourceParams&gt;</code> element
    are as follows:</p>

    <attributes>

      <attribute name="name" required="true">
        <p>The name of the resource being configured, relative to the
        <code>java:comp/env</code> contxt.  This name <strong>MUST</strong>
        match the name of a resource defined by a <code>&lt;Resource&gt;</code>
        element in <code>$CATALINA_HOME/conf/server.xml</code>, and/or
        referenced in a <code>&lt;resource-ref&gt;</code> or
        <code>&lt;resource-env-ref&gt;</code> element in the web application
        deployment descriptor.</p>
      </attribute>

    </attributes>

  </subsection>


</section>


</body>


</document>
