| <?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> |
| <author email="yoavs@apache.org">Yoav Shapira</author> |
| <title>The GlobalNamingResources Component</title> |
| </properties> |
| |
| <body> |
| |
| |
| <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>. |
| With the exception of <code><strong><Environment></strong></code> |
| values, |
| 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"><ResourceLink></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><Environment></code> entries inside this element. For |
| example, you can create an environment entry like this:</p> |
| <source> |
| <GlobalNamingResources ...> |
| ... |
| <Environment name="maxExemptions" value="10" |
| type="java.lang.Integer" override="false"/> |
| ... |
| </GlobalNamingResources> |
| </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> |
| <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> |
| </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><Environment></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><env-entry></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><env-entry-type></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><resource-ref></code> and |
| <code><resource-env-ref></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"><ResourceLink></a> |
| elements |
| in the <code><strong><Context></strong></code> |
| or <code><strong><DefaultContext></strong></code> elements. |
| |
| 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> |
| <GlobalNamingResources ...> |
| ... |
| <Resource name="jdbc/EmployeeDB" auth="Container" |
| type="javax.sql.DataSource" |
| description="Employees Database for HR Applications"/> |
| ... |
| </GlobalNamingResources> |
| </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> |
| <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> |
| </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><Resource></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><resource-ref></code> element in the web |
| application deployment descriptor, but is optional if the |
| application uses a <code><resource-env-ref></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"><ResourceLink></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 all applications in the server, based on the example |
| definition in the |
| <a href="../jndi-resource-howto.html#Generic JavaBean Resources"> |
| JNDI Resource HOW-TO</a>: |
| </p> |
| |
| <source> |
| <![CDATA[ |
| <DefaultContext> |
| <ResourceLink |
| name="bean/MyBeanFactory" |
| global="bean/MyBeanFactory" |
| type="com.mycompany.MyBean" |
| /> |
| </DefaultContext> |
| ]]> |
| </source> |
| |
| </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><Resource></code> element inside a |
| <code><Context></code> or <code><DefaultContext></code> |
| element in <code>$CATALINA_HOME/conf/server.xml</code>, and/or for every |
| name declared in a <code><resource-ref></code> or |
| <code><resource-env-ref></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> |
| <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> |
| </source> |
| |
| <p>If you need to specify the Java class name of a factory class for a |
| particular resource type, use a <code><parameter></code> entry |
| named <code>factory</code> nested inside the |
| <code><ResourceParams></code> element.</p> |
| |
| <p>The valid attributes of a <code><ResourceParams></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><Resource></code> |
| element in <code>$CATALINA_HOME/conf/server.xml</code>, and/or |
| referenced in a <code><resource-ref></code> or |
| <code><resource-env-ref></code> element in the web application |
| deployment descriptor.</p> |
| </attribute> |
| |
| </attributes> |
| |
| </subsection> |
| |
| |
| </section> |
| |
| |
| </body> |
| |
| |
| </document> |
