Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / fd5ee81fec460cbe9ad65f300b0faf1bf03c19bc / . / tomcat-uid / webapps / docs / config / globalresources.html
blob: 1e29141432118f021b7130347117bf27402f3eb3 [file] [log] [blame]
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference (6.0.39) - The GlobalNamingResources Component</title><meta name="author" content="Remy Maucherat"><meta name="author" content="Yoav Shapira"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
5 The Apache Tomcat Servlet/JSP Container
6 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.39, Jan 27 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><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><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</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="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><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><p><strong>Other</strong></p><ul><li><a href="filter.html">Filter</a></li><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat Configuration Reference</h1><h2>The GlobalNamingResources Component</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
7<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>
8</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
9
10 <p>The <strong>GlobalNamingResources</strong> element defines the global
11 JNDI resources for the <a href="server.html">Server</a>.</p>
12
13 <p>These resources are listed in the server's global JNDI resource context.
14 This context is distinct from the per-web-application JNDI contexts
15 described in
16 the <a href="../jndi-resources-howto.html">JNDI Resources HOW-TO</a>.
17 The resources defined in this element are <strong>not</strong> visible in
18 the per-web-application contexts unless you explicitly link them with
19 <a href="context.html#Resource Links">&lt;ResourceLink&gt;</a> elements.
20 </p>
21
22</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
23
24</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
25
26</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
27
28
29 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Environment Entries"><!--()--></a><a name="Environment_Entries"><strong>Environment Entries</strong></a></font></td></tr><tr><td><blockquote>
30
31 <p>You can configure named values that will be made visible to all
32 web applications as environment entry resources by nesting
33 <code>&lt;Environment&gt;</code> entries inside this element. For
34 example, you can create an environment entry like this:</p>
35<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
36&lt;GlobalNamingResources ...&gt;
37 ...
38 &lt;Environment name="maxExemptions" value="10"
39 type="java.lang.Integer" override="false"/&gt;
40 ...
41&lt;/GlobalNamingResources&gt;
42</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
43
44 <p>This is equivalent to the inclusion of the following element in the
45 web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
46 </p>
47<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
48&lt;env-entry&gt;
49 &lt;env-entry-name&gt;maxExemptions&lt;/env-entry-name&gt;
50 &lt;env-entry-value&gt;10&lt;/env-entry-value&gt;
51 &lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
52&lt;/env-entry&gt;
53</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
54 <p>but does <em>not</em> require modification of the deployment descriptor
55 to customize this value.</p>
56
57 <p>The valid attributes for an <code>&lt;Environment&gt;</code> element
58 are as follows:</p>
59
60 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center">
61 <p>Optional, human-readable description of this environment entry.</p>
62 </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
63 <p>The name of the environment entry to be created, relative to the
64 <code>java:comp/env</code> context.</p>
65 </td></tr><tr><td align="left" valign="center"><code>override</code></td><td align="left" valign="center">
66 <p>Set this to <code>false</code> if you do <strong>not</strong> want
67 an <code>&lt;env-entry&gt;</code> for the same environment entry name,
68 found in the web application deployment descriptor, to override the
69 value specified here. By default, overrides are allowed.</p>
70 </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
71 <p>The fully qualified Java class name expected by the web application
72 for this environment entry. Must be one of the legal values for
73 <code>&lt;env-entry-type&gt;</code> in the web application deployment
74 descriptor: <code>java.lang.Boolean</code>,
75 <code>java.lang.Byte</code>, <code>java.lang.Character</code>,
76 <code>java.lang.Double</code>, <code>java.lang.Float</code>,
77 <code>java.lang.Integer</code>, <code>java.lang.Long</code>,
78 <code>java.lang.Short</code>, or <code>java.lang.String</code>.</p>
79 </td></tr><tr><td align="left" valign="center"><strong><code>value</code></strong></td><td align="left" valign="center">
80 <p>The parameter value that will be presented to the application
81 when requested from the JNDI context. This value must be convertable
82 to the Java type defined by the <code>type</code> attribute.</p>
83 </td></tr></table>
84
85 </blockquote></td></tr></table>
86
87
88 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Resource Definitions"><!--()--></a><a name="Resource_Definitions"><strong>Resource Definitions</strong></a></font></td></tr><tr><td><blockquote>
89
90 <p>You can declare the characteristics of resources
91 to be returned for JNDI lookups of <code>&lt;resource-ref&gt;</code> and
92 <code>&lt;resource-env-ref&gt;</code> elements in the web application
93 deployment descriptor by defining them in this element and then linking
94 them with <a href="context.html#Resource Links">&lt;ResourceLink&gt;</a>
95 elements
96 in the <code><strong>&lt;Context&gt;</strong></code> element.
97
98 You <strong>MUST</strong> also define any other needed parameters using
99 attributes on the Resource element, to configure
100 the object factory to be used (if not known to Tomcat already), and
101 the properties used to configure that object factory.</p>
102
103 <p>For example, you can create a resource definition like this:</p>
104<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
105&lt;GlobalNamingResources ...&gt;
106 ...
107 &lt;Resource name="jdbc/EmployeeDB" auth="Container"
108 type="javax.sql.DataSource"
109 description="Employees Database for HR Applications"/&gt;
110 ...
111&lt;/GlobalNamingResources&gt;
112</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
113
114 <p>This is equivalent to the inclusion of the following element in the
115 web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
116<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
117&lt;resource-ref&gt;
118 &lt;description&gt;Employees Database for HR Applications&lt;/description&gt;
119 &lt;res-ref-name&gt;jdbc/EmployeeDB&lt;/res-ref-name&gt;
120 &lt;res-ref-type&gt;javax.sql.DataSource&lt;/res-ref-type&gt;
121 &lt;res-auth&gt;Container&lt;/res-auth&gt;
122&lt;/resource-ref&gt;
123</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
124
125 <p>but does <em>not</em> require modification of the deployment
126 descriptor to customize this value.</p>
127
128 <p>The valid attributes for a <code>&lt;Resource&gt;</code> element
129 are as follows:</p>
130
131 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>auth</code></td><td align="left" valign="center">
132 <p>Specify whether the web Application code signs on to the
133 corresponding resource manager programmatically, or whether the
134 Container will sign on to the resource manager on behalf of the
135 application. The value of this attribute must be
136 <code>Application</code> or <code>Container</code>. This
137 attribute is <strong>required</strong> if the web application
138 will use a <code>&lt;resource-ref&gt;</code> element in the web
139 application deployment descriptor, but is optional if the
140 application uses a <code>&lt;resource-env-ref&gt;</code> instead.</p>
141 </td></tr><tr><td align="left" valign="center"><code>description</code></td><td align="left" valign="center">
142 <p>Optional, human-readable description of this resource.</p>
143 </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
144 <p>The name of the resource to be created, relative to the
145 <code>java:comp/env</code> context.</p>
146 </td></tr><tr><td align="left" valign="center"><code>scope</code></td><td align="left" valign="center">
147 <p>Specify whether connections obtained through this resource
148 manager can be shared. The value of this attribute must be
149 <code>Shareable</code> or <code>Unshareable</code>. By default,
150 connections are assumed to be shareable.</p>
151 </td></tr><tr><td align="left" valign="center"><strong><code>type</code></strong></td><td align="left" valign="center">
152 <p>The fully qualified Java class name expected by the web
153 application when it performs a lookup for this resource.</p>
154 </td></tr></table>
155
156
157 </blockquote></td></tr></table>
158
159 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Resource Links"><!--()--></a><a name="Resource_Links"><strong>Resource Links</strong></a></font></td></tr><tr><td><blockquote>
160 <p>Use <a href="context.html#Resource Links">&lt;ResourceLink&gt;</a>
161 elements to link resources from the global context into
162 per-web-application contexts. Here is an example of making a custom
163 factory available to an application, based on the example definition in the
164 <a href="../jndi-resources-howto.html#Generic JavaBean Resources">
165 JNDI Resource HOW-TO</a>:
166 </p>
167
168 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
169
170 &lt;Context&gt;
171 &lt;ResourceLink
172 name="bean/MyBeanFactory"
173 global="bean/MyBeanFactory"
174 type="com.mycompany.MyBean"
175 /&gt;
176 &lt;/Context&gt;
177
178 </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
179
180 </blockquote></td></tr></table>
181
182 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Transaction"><strong>Transaction</strong></a></font></td></tr><tr><td><blockquote>
183
184 <p>You can declare the characteristics of the UserTransaction
185 to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
186 You <strong>MUST</strong> define an object factory class to instantiate
187 this object as well as the needed resource parameters as attributes of the
188 <code>Transaction</code>
189 element, and the properties used to configure that object factory.</p>
190
191 <p>The valid attributes for the <code>&lt;Transaction&gt;</code> element
192 are as follows:</p>
193
194 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>factory</code></strong></td><td align="left" valign="center">
195 <p>The class name for the JNDI object factory.</p>
196 </td></tr></table>
197
198 </blockquote></td></tr></table>
199
200</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
201 Copyright &copy; 1999-2014, Apache Software Foundation
202 </em></font></div></td></tr></table></body></html>