<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="globalresources.html">

  &project;

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

<body>

<section name="Table of Contents">
<toc/>
</section>

<section name="Introduction">

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

  <p>These resources are listed in the server's global JNDI resource context.
   This context is distinct from the per-web-application JNDI contexts 
  described in
  the <a href="../jndi-resources-howto.html">JNDI Resources HOW-TO</a>.
  The resources defined in this element are <strong>not</strong> visible in
  the per-web-application contexts unless you explicitly link them with
  <a href="context.html#Resource Links">&lt;ResourceLink&gt;</a> elements.
  </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 all
    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;/env-entry-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 resources
    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 by defining them in this element and then linking 
    them with <a href="context.html#Resource Links">&lt;ResourceLink&gt;</a> 
    elements
    in the <code><strong>&lt;Context&gt;</strong></code> element.  

    You <strong>MUST</strong> also define any other needed parameters using
    attributes on the Resource element, 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 attributes 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 programmatically, 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 Links">
    <p>Use <a href="context.html#Resource Links">&lt;ResourceLink&gt;</a> 
    elements to link resources from the global context into 
    per-web-application contexts. Here is an example of making a custom 
    factory available to an application, based on the example definition in the 
    <a href="../jndi-resources-howto.html#Generic JavaBean Resources">
    JNDI Resource HOW-TO</a>:
    </p>

    <source>
      <![CDATA[
        <Context>
          <ResourceLink 
            name="bean/MyBeanFactory"
            global="bean/MyBeanFactory"
            type="com.mycompany.MyBean"
          />
        </Context>
      ]]>
    </source>

   </subsection>

  <subsection name="Transaction">

    <p>You can declare the characteristics of the UserTransaction
    to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>. 
    You <strong>MUST</strong> define an object factory class to instantiate
    this object as well as the needed resource parameters as attributes of the 
    <code>Transaction</code> 
    element, and the properties used to configure that object factory.</p>

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

    <attributes>

      <attribute name="factory" required="true">
        <p>The class name for the JNDI object factory.</p>
      </attribute>

    </attributes>

  </subsection>

</section>


</body>


</document>
