Links Docs Home Config Ref. Home Top Level Elements Server Service Connectors HTTP AJP Containers Context Engine Host Nested Components Default Context Global Resources Loader Logger Manager Realm Resources Valve |
# Server Configuration Reference ## The GlobalNamingResources Component | print-friendly version
Introduction
The GlobalNamingResources element defines the global JNDI resources for the Server. 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 JNDI Resources HOW-TO. With the exception of `<Environment>` values, the resources defined in this element are not visible in the per-web-application contexts unless you explicitly link them with <ResourceLink> elements.
Attributes
Nested Components
Special Features
> Environment Entries
> > You can configure named values that will be made visible to all web applications as environment entry resources by nesting `<Environment>` entries inside this element. For example, you can create an environment entry like this:
> >     <GlobalNamingResources ...>
> >       ...
> >       <Environment name="maxExemptions" value="10"
> >              type="java.lang.Integer" override="false"/>
> >       ...
> >     </GlobalNamingResources>
> > This is equivalent to the inclusion of the following element in the web application deployment descriptor (`/WEB-INF/web.xml`):
> >     <env-entry>
> >       <env-entry-name>maxExemptions</param-name>
> >       <env-entry-value>10</env-entry-value>
> >       <env-entry-type>java.lang.Integer</env-entry-type>
> >     </env-entry>
> > but does not require modification of the deployment descriptor to customize this value. The valid attributes for an `<Environment>` element are as follows:
> > Attribute | Description
> > --- | ---
> > `description` | Optional, human-readable description of this environment entry.
> > `name` | The name of the environment entry to be created, relative to the `java:comp/env` context.
> > `override` | Set this to `false` if you do not want an `<env-entry>` for the same environment entry name, found in the web application deployment descriptor, to override the value specified here. By default, overrides are allowed.
> > `type` | The fully qualified Java class name expected by the web application for this environment entry. Must be one of the legal values for `<env-entry-type>` in the web application deployment descriptor: `java.lang.Boolean`, `java.lang.Byte`, `java.lang.Character`, `java.lang.Double`, `java.lang.Float`, `java.lang.Integer`, `java.lang.Long`, `java.lang.Short`, or `java.lang.String`.
> > `value` | 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 `type` attribute.
> Resource Definitions
> > You can declare the characteristics of resources to be returned for JNDI lookups of `<resource-ref>` and `<resource-env-ref>` elements in the web application deployment descriptor by defining them in this element and then linking them with <ResourceLink> elements in the `<Context>` or `<DefaultContext>` elements. You MUST also define Resource Parameters 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. For example, you can create a resource definition like this:
> >     <GlobalNamingResources ...>
> >       ...
> >       <Resource name="jdbc/EmployeeDB" auth="Container"
> >                 type="javax.sql.DataSource"
> >          description="Employees Database for HR Applications"/>
> >       ...
> >     </GlobalNamingResources>
> > This is equivalent to the inclusion of the following element in the web application deployment descriptor (`/WEB-INF/web.xml`):
> >     <resource-ref>
> >       <description>Employees Database for HR Applications</description>
> >       <res-ref-name>jdbc/EmployeeDB</res-ref-name>
> >       <res-ref-type>javax.sql.DataSource</res-ref-type>
> >       <res-auth>Container</res-auth>
> >     </resource-ref>
> > but does not require modification of the deployment descriptor to customize this value. The valid attriutes for a `<Resource>` element are as follows:
> > Attribute | Description
> > --- | ---
> > `auth` | 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 `Application` or `Container`. This attribute is required if the web application will use a `<resource-ref>` element in the web application deployment descriptor, but is optional if the application uses a `<resource-env-ref>` instead.
> > `description` | Optional, human-readable description of this resource.
> > `name` | The name of the resource to be created, relative to the `java:comp/env` context.
> > `scope` | Specify whether connections obtained through this resource manager can be shared. The value of this attribute must be `Shareable` or `Unshareable`. By default, connections are assumed to be shareable.
> > `type` | The fully qualified Java class name expected by the web application when it performs a lookup for this resource.
> Resource Links
> > Use <ResourceLink> elements to link resources from the global context into per-web-application contexts. Here is an example of making a custom factory available to all applications in the server, based on the example definition in the JNDI Resource HOW-TO:
> >             <DefaultContext>
> >               <ResourceLink
> >                 name="bean/MyBeanFactory"
> >                 global="bean/MyBeanFactory"
> >                 type="com.mycompany.MyBean"
> >               />
> >             </DefaultContext>
> Resource Parameters
> > 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 MUST define resource parameters for every resource name that is specified by a `<Resource>` element inside a `<Context>` or `<DefaultContext>` element in `$CATALINA_HOME/conf/server.xml`, and/or for every name declared in a `<resource-ref>` or `<resource-env-ref>` element in the web application deployment descriptor, before that resource can be successfully accessed. 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 `lookup()` call. The resource parameters for a JDBC data source might look something like this:
> >     <GlobalNamingResources ...>
> >       ...
> >       <ResourceParams name="jdbc/EmployeeDB">
> >         <parameter>
> >           <name>driverClassName</name>
> >           <value>org.hsql.jdbcDriver</value>
> >         </parameter>
> >         <parameter>
> >           <name>driverName</name>
> >           </value>jdbc:HypersonicSQL:database</value>
> >         </parameter>
> >         <parameter>
> >           <name>user</name>
> >           <value>dbusername</value>
> >         </parameter>
> >         <parameter>
> >           <name>password</name>
> >           <value>dbpassword</value>
> >         </parameter>
> >       </ResourceParams>
> >       ...
> >     </GlobalNamingResources>
> > If you need to specify the Java class name of a factory class for a particular resource type, use a `<parameter>` entry named `factory` nested inside the `<ResourceParams>` element. The valid attributes of a `<ResourceParams>` element are as follows:
> > Attribute | Description
> > --- | ---
> > `name` | The name of the resource being configured, relative to the `java:comp/env` contxt. This name MUST match the name of a resource defined by a `<Resource>` element in `$CATALINA_HOME/conf/server.xml`, and/or referenced in a `<resource-ref>` or `<resource-env-ref>` element in the web application deployment descriptor.
Copyright © 1999-2003, Apache Software Foundation