Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - The GlobalNamingResources Component</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The GlobalNamingResources Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Environment_Entries">Environment Entries</a></li><li><a href="#Resource_Definitions">Resource Definitions</a></li><li><a href="#Resource_Links">Resource Links</a></li><li><a href="#Transaction">Transaction</a></li></ol></li></ul>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
  <p>The <strong>GlobalNamingResources</strong> element defines the global
9 
  JNDI resources for the <a href="server.html">Server</a>.</p>
10 
 
11 
  <p>These resources are listed in the server's global JNDI resource context.
12 
   This context is distinct from the per-web-application JNDI contexts
13 
  described in
14 
  the <a href="../jndi-resources-howto.html">JNDI Resources How-To</a>.
15 
  The resources defined in this element are <strong>not</strong> visible in
16 
  the per-web-application contexts unless you explicitly link them with
17 
  <a href="context.html#Resource_Links">&lt;ResourceLink&gt;</a> elements.
18 
  </p>
19 
 
20 
</div><h3 id="Attributes">Attributes</h3><div class="text">
21 
 
22 
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
23 
 
24 
</div><h3 id="Special_Features">Special Features</h3><div class="text">
25 
 
26 
 
27 
  <div class="subsection"><h4 id="Environment_Entries">Environment Entries</h4><div class="text">
28 
 
29 
  <p>You can configure named values that will be made visible to all
30 
    web applications as environment entry resources by nesting
31 
    <code>&lt;Environment&gt;</code> entries inside this element. For
32 
    example, you can create an environment entry like this:</p>
33 
<div class="codeBox"><pre><code>&lt;GlobalNamingResources ...&gt;
34 
  ...
35 
  &lt;Environment name="maxExemptions" value="10"
36 
         type="java.lang.Integer" override="false"/&gt;
37 
  ...
38 
&lt;/GlobalNamingResources&gt;</code></pre></div>
39 
 
40 
    <p>This is equivalent to the inclusion of the following element in the
41 
    web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
42 
    </p>
43 
<div class="codeBox"><pre><code>&lt;env-entry&gt;
44 
  &lt;env-entry-name&gt;maxExemptions&lt;/env-entry-name&gt;
45 
  &lt;env-entry-value&gt;10&lt;/env-entry-value&gt;
46 
  &lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
47 
&lt;/env-entry&gt;</code></pre></div>
48 
    <p>but does <em>not</em> require modification of the deployment descriptor
49 
    to customize this value.</p>
50 
 
51 
    <p>The valid attributes for an <code>&lt;Environment&gt;</code> element
52 
    are as follows:</p>
53 
 
54 
    <table class="defaultTable"><tr><th style="width: 15%;">
55 
          Attribute
56 
        </th><th style="width: 85%;">
57 
          Description
58 
        </th></tr><tr id="Special Features_Environment Entries_description"><td><code class="attributeName">description</code></td><td>
59 
        <p>Optional, human-readable description of this environment entry.</p>
60 
      </td></tr><tr id="Special Features_Environment Entries_name"><td><strong><code class="attributeName">name</code></strong></td><td>
61 
        <p>The name of the environment entry to be created, relative to the
62 
        <code>java:comp/env</code> context.</p>
63 
      </td></tr><tr id="Special Features_Environment Entries_override"><td><code class="attributeName">override</code></td><td>
64 
        <p>Set this to <code>false</code> if you do <strong>not</strong> want
65 
        an <code>&lt;env-entry&gt;</code> for the same environment entry name,
66 
        found in the web application deployment descriptor, to override the
67 
        value specified here.  By default, overrides are allowed.</p>
68 
      </td></tr><tr id="Special Features_Environment Entries_type"><td><strong><code class="attributeName">type</code></strong></td><td>
69 
        <p>The fully qualified Java class name expected by the web application
70 
        for this environment entry.  Must be a legal value for
71 
        <code>&lt;env-entry-type&gt;</code> in the web application deployment
72 
        descriptor.</p>
73 
      </td></tr><tr id="Special Features_Environment Entries_value"><td><strong><code class="attributeName">value</code></strong></td><td>
74 
        <p>The parameter value that will be presented to the application
75 
        when requested from the JNDI context.  This value must be convertible
76 
        to the Java type defined by the <code>type</code> attribute.</p>
77 
      </td></tr></table>
78 
 
79 
  </div></div>
80 
 
81 
 
82 
  <div class="subsection"><h4 id="Resource_Definitions">Resource Definitions</h4><div class="text">
83 
 
84 
    <p>You can declare the characteristics of resources
85 
    to be returned for JNDI lookups of <code>&lt;resource-ref&gt;</code> and
86 
    <code>&lt;resource-env-ref&gt;</code> elements in the web application
87 
    deployment descriptor by defining them in this element and then linking
88 
    them with <a href="context.html#Resource_Links">&lt;ResourceLink&gt;</a>
89 
    elements
90 
    in the <code><strong>&lt;Context&gt;</strong></code> element.
91 
 
92 
    You <strong>MUST</strong> also define any other needed parameters using
93 
    attributes on the Resource element, to configure
94 
    the object factory to be used (if not known to Tomcat already), and
95 
    the properties used to configure that object factory.</p>
96 
 
97 
    <p>For example, you can create a resource definition like this:</p>
98 
<div class="codeBox"><pre><code>&lt;GlobalNamingResources ...&gt;
99 
  ...
100 
  &lt;Resource name="jdbc/EmployeeDB" auth="Container"
101 
            type="javax.sql.DataSource"
102 
     description="Employees Database for HR Applications"/&gt;
103 
  ...
104 
&lt;/GlobalNamingResources&gt;</code></pre></div>
105 
 
106 
    <p>This is equivalent to the inclusion of the following element in the
107 
    web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
108 
<div class="codeBox"><pre><code>&lt;resource-ref&gt;
109 
  &lt;description&gt;Employees Database for HR Applications&lt;/description&gt;
110 
  &lt;res-ref-name&gt;jdbc/EmployeeDB&lt;/res-ref-name&gt;
111 
  &lt;res-ref-type&gt;javax.sql.DataSource&lt;/res-ref-type&gt;
112 
  &lt;res-auth&gt;Container&lt;/res-auth&gt;
113 
&lt;/resource-ref&gt;</code></pre></div>
114 
 
115 
    <p>but does <em>not</em> require modification of the deployment
116 
    descriptor to customize this value.</p>
117 
 
118 
    <p>The valid attributes for a <code>&lt;Resource&gt;</code> element
119 
    are as follows:</p>
120 
 
121 
    <table class="defaultTable"><tr><th style="width: 15%;">
122 
          Attribute
123 
        </th><th style="width: 85%;">
124 
          Description
125 
        </th></tr><tr id="Special Features_Resource Definitions_auth"><td><code class="attributeName">auth</code></td><td>
126 
        <p>Specify whether the web Application code signs on to the
127 
        corresponding resource manager programmatically, or whether the
128 
        Container will sign on to the resource manager on behalf of the
129 
        application.  The value of this attribute must be
130 
        <code>Application</code> or <code>Container</code>.  This
131 
        attribute is <strong>required</strong> if the web application
132 
        will use a <code>&lt;resource-ref&gt;</code> element in the web
133 
        application deployment descriptor, but is optional if the
134 
        application uses a <code>&lt;resource-env-ref&gt;</code> instead.</p>
135 
      </td></tr><tr id="Special Features_Resource Definitions_closeMethod"><td><code class="attributeName">closeMethod</code></td><td>
136 
        <p>Name of the zero-argument method to call on a singleton resource when
137 
        it is no longer required. This is intended to speed up clean-up of
138 
        resources that would otherwise happen as part of garbage collection.
139 
        This attribute is ignored if the <code>singleton</code> attribute is
140 
        false. If not specified, no default is defined and no close method will
141 
        be called.</p>
142 
        <p>For Apache Commons DBCP 2 and Apache Tomcat JDBC connection pools
143 
        you can use <code>closeMethod="close"</code>. Note that Apache Commons
144 
        DBCP 2 requires this to be set for a clean shutdown. When using the
145 
        default Tomcat connection pool (based on DBCP 2) Tomcat will set this
146 
        attribute automatically unless it is explicitly set to the empty
147 
        string.</p>
148 
      </td></tr><tr id="Special Features_Resource Definitions_description"><td><code class="attributeName">description</code></td><td>
149 
        <p>Optional, human-readable description of this resource.</p>
150 
      </td></tr><tr id="Special Features_Resource Definitions_name"><td><strong><code class="attributeName">name</code></strong></td><td>
151 
        <p>The name of the resource to be created, relative to the
152 
        <code>java:comp/env</code> context.</p>
153 
      </td></tr><tr id="Special Features_Resource Definitions_scope"><td><code class="attributeName">scope</code></td><td>
154 
        <p>Specify whether connections obtained through this resource
155 
        manager can be shared.  The value of this attribute must be
156 
        <code>Shareable</code> or <code>Unshareable</code>.  By default,
157 
        connections are assumed to be shareable.</p>
158 
      </td></tr><tr id="Special Features_Resource Definitions_singleton"><td><code class="attributeName">singleton</code></td><td>
159 
        <p>Specify whether this resource definition is for a singleton resource,
160 
        i.e. one where there is only a single instance of the resource. If this
161 
        attribute is <code>true</code>, multiple JNDI lookups for this resource
162 
        will return the same object. If this attribute is <code>false</code>,
163 
        multiple JNDI lookups for this resource will return different objects.
164 
        This attribute must be <code>true</code> for
165 
        <code>javax.sql.DataSource</code> resources to enable JMX registration
166 
        of the DataSource. The value of this attribute must be <code>true</code>
167 
        or <code>false</code>. By default, this attribute is <code>true</code>.
168 
        </p>
169 
      </td></tr><tr id="Special Features_Resource Definitions_type"><td><strong><code class="attributeName">type</code></strong></td><td>
170 
        <p>The fully qualified Java class name expected by the web
171 
        application when it performs a lookup for this resource.</p>
172 
      </td></tr></table>
173 
 
174 
 
175 
  </div></div>
176 
 
177 
  <div class="subsection"><h4 id="Resource_Links">Resource Links</h4><div class="text">
178 
    <p>Use <a href="context.html#Resource_Links"><code>&lt;ResourceLink&gt;</code></a>
179 
    elements to link resources from the global context into
180 
    per-web-application contexts. Here is an example of making a custom
181 
    factory available to an application, based on the example definition in the
182 
    <a href="../jndi-resources-howto.html#Generic_JavaBean_Resources">
183 
    JNDI Resource How-To</a>:
184 
    </p>
185 
 
186 
    <div class="codeBox"><pre><code>&lt;Context&gt;
187 
  &lt;ResourceLink
188 
    name="bean/MyBeanFactory"
189 
    global="bean/MyBeanFactory"
190 
    type="com.mycompany.MyBean"
191 
  /&gt;
192 
&lt;/Context&gt;</code></pre></div>
193 
 
194 
   </div></div>
195 
 
196 
  <div class="subsection"><h4 id="Transaction">Transaction</h4><div class="text">
197 
 
198 
    <p>You can declare the characteristics of the UserTransaction
199 
    to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
200 
    You <strong>MUST</strong> define an object factory class to instantiate
201 
    this object as well as the needed resource parameters as attributes of the
202 
    <code>Transaction</code>
203 
    element, and the properties used to configure that object factory.</p>
204 
 
205 
    <p>The valid attributes for the <code>&lt;Transaction&gt;</code> element
206 
    are as follows:</p>
207 
 
208 
    <table class="defaultTable"><tr><th style="width: 15%;">
209 
          Attribute
210 
        </th><th style="width: 85%;">
211 
          Description
212 
        </th></tr><tr id="Special Features_Transaction_factory"><td><strong><code class="attributeName">factory</code></strong></td><td>
213 
        <p>The class name for the JNDI object factory.</p>
214 
      </td></tr></table>
215 
 
216 
  </div></div>
217 
 
218 
</div></div></div></div></div><footer><div id="footer">
219 
    Copyright &copy; 1999-2025, The Apache Software Foundation
220 
    <br>
221 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
222 
    are either registered trademarks or trademarks of the Apache Software
223 
    Foundation.
224 
    </div></footer></div></body></html>