craigmcc 01/09/08 17:48:11
Modified: . RELEASE-NOTES-4.0-B8.txt RELEASE-PLAN-4.0.txt
catalina/src/share/org/apache/catalina/core
StandardContext.java
catalina/src/share/org/apache/catalina/deploy
ApplicationParameter.java ContextEnvironment.java
webapps/tomcat-docs index.xml project.xml
webapps/tomcat-docs/config context.xml defaultcontext.xml
Added: webapps/tomcat-docs jndi-resources-howto.xml
Log:
Add the half-completed "jndi-resources-howto.xml" that talks about how to
configure <Resource> and <ResourceParams> elements in server.xml. Make
the handling of the "override" property on <Environment> and <Parameter>
elements match the documentation (now that it exists :-).
TODO: Document the standard resource factories supported by Tomcat 4, and
the process for adding your own custom resource factories.
Revision Changes Path
1.4 +29 -1 jakarta-tomcat-4.0/RELEASE-NOTES-4.0-B8.txt
Index: RELEASE-NOTES-4.0-B8.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/RELEASE-NOTES-4.0-B8.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- RELEASE-NOTES-4.0-B8.txt 2001/08/14 18:50:09 1.3
+++ RELEASE-NOTES-4.0-B8.txt 2001/09/09 00:48:11 1.4
@@ -3,7 +3,7 @@
Release Notes
=============
-$Id: RELEASE-NOTES-4.0-B8.txt,v 1.3 2001/08/14 18:50:09 pier Exp $
+$Id: RELEASE-NOTES-4.0-B8.txt,v 1.4 2001/09/09 00:48:11 craigmcc Exp $
============
@@ -128,6 +128,10 @@
directory of your web application, this should now be possible, because
of the modified JAXP 1.1 parser mentioned below.
+* Make sure you do *not* place an XML parser in your Java system extensions
+ directory ($JAVA_HOME/jre/lib/ext), or modify the startup scripts to include
+ such a parser in the CLASSPATH under which Tomcat executes.
+
WARNING: Tomcat 4.0 now ships with a modified version of the JAXP/1.1
(Final) "jaxp.jar" and "crimson.jar" files in the "jasper" subdirectory.
The "sealed" attribute has been removed from the manifest file for these
@@ -177,3 +181,27 @@
* There are several test failures in the "tester" unit test suite that will
be corrected before final release. (Most of these issues related to the
bug that prevents BASIC authentication form operating.)
+
+
+-------------------------------------
+Tomcat 4.0 and JNI Based Applications:
+-------------------------------------
+
+Applications that require native libraries must ensure that the libraries have
+been loaded prior to use. Typically, this is done with a call like:
+
+ static {
+ System.loadLibrary("path-to-library-file");
+ }
+
+in some class. However, the application must also ensure that the library is
+not loaded more than once. If the above code were placed in a class inside
+the web application (i.e. under /WEB-INF/classes or /WEB-INF/lib), and the
+application were reloaded, the loadLibrary() call would be attempted a second
+time.
+
+To avoid this problem, place classes that load native libraries outside of the
+web application, and ensure that the loadLibrary() call is executed only once
+during the lifetime of a particular JVM.
+
+
1.10 +6 -32 jakarta-tomcat-4.0/RELEASE-PLAN-4.0.txt
Index: RELEASE-PLAN-4.0.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/RELEASE-PLAN-4.0.txt,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- RELEASE-PLAN-4.0.txt 2001/09/07 04:13:42 1.9
+++ RELEASE-PLAN-4.0.txt 2001/09/09 00:48:11 1.10
@@ -1,4 +1,4 @@
-$Id: RELEASE-PLAN-4.0.txt,v 1.9 2001/09/07 04:13:42 remm Exp $
+$Id: RELEASE-PLAN-4.0.txt,v 1.10 2001/09/09 00:48:11 craigmcc Exp $
Release Plan for Apache Tomcat 4.0
==================================
@@ -21,11 +21,11 @@
This Release Plan proposes the following schedule:
- Monday, September 9, 2001 Tomcat 4.0 Release Candidate 1
+ Sunday, September 9, 2001 Tomcat 4.0 Release Candidate 1
- Thursday, September 12, 2001 Tomcat 4.0 Release Candidate 2
+ Wednesday, September 12, 2001 Tomcat 4.0 Release Candidate 2
- Monday, September 17, 2001 Tomcat 4.0 Final Release
+ Monday, September 17, 2001 Tomcat 4.0 Final Release
In order to complete final release, all outstanding Bugzilla bug reports
against Tomcat 4.0 need to be fixed or deferred for later releases. This
@@ -46,10 +46,6 @@
Bugs That Must Be Addressed Before Final Release:
------------------------------------------------
-Catalina 2883 Error page for 401 error code is not populated
- (Not a spec issue, so likely to be downgraded to
- "enhancement request")
-
Catalina 3009 Manager cannot install web app
Catalina 3292 Class reloading fails (awaiting test case)
@@ -60,12 +56,10 @@
Connectors 1788 mod_webapp errors on Win2k
Connectors 2997 Webapp connector should recover when Tomcat is restarted
-
-Jasper 2693 Syntax errors in JSP source generate NumberFormatException
-Jasper 2917 JSP compiled file name is not correct
+Connectors 3476 Cannot use other than default context when using mod_webapp
-Jasper 3019 Jasper generates bad custom tag variable names
+Connectors 3481 Webapp socket leak when Apache process shuts down
Jasper 3079 NullPointerException in JakartaCommentGenerator.generateEnd
@@ -96,24 +90,4 @@
Servletapi 3196 Javadoc errors during build
Servletapi 3344 Typo in javadocs
-
-
-Enhancement Requests To Be Addressed Later:
-------------------------------------------
-
-Catalina 1400 SSLServerSocketFactory.java does not support multiple
- keys in a keystore file
-
-Catalina 1575 Slow server start due to SAX parsing
-
-Catalina 2570 Add ability to configure a default error handler
-
-Catalina 2823 Allow a <Manager> inside <DefaultContext>
-
-Catalina 3293 Allow content lengths > 2^31
-
-Jasper 2500 FileNotFoundException unintentionally caught
-
-Jasper 2622 Jasper is not taking advantage of empty body content
- optimization opportunity
1.77 +14 -4
jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/core/StandardContext.java
Index: StandardContext.java
===================================================================
RCS file:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/core/StandardContext.java,v
retrieving revision 1.76
retrieving revision 1.77
diff -u -r1.76 -r1.77
--- StandardContext.java 2001/09/06 04:00:16 1.76
+++ StandardContext.java 2001/09/09 00:48:11 1.77
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/core/StandardContext.java,v
1.76 2001/09/06 04:00:16 remm Exp $
- * $Revision: 1.76 $
- * $Date: 2001/09/06 04:00:16 $
+ * $Header:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/core/StandardContext.java,v
1.77 2001/09/09 00:48:11 craigmcc Exp $
+ * $Revision: 1.77 $
+ * $Date: 2001/09/09 00:48:11 $
*
* ====================================================================
*
@@ -142,7 +142,7 @@
*
* @author Craig R. McClanahan
* @author Remy Maucherat
- * @version $Revision: 1.76 $ $Date: 2001/09/06 04:00:16 $
+ * @version $Revision: 1.77 $ $Date: 2001/09/09 00:48:11 $
*/
public class StandardContext
@@ -1251,6 +1251,12 @@
public void addApplicationParameter(ApplicationParameter parameter) {
synchronized (applicationParameters) {
+ String newName = parameter.getName();
+ for (int i = 0; i < applicationParameters.length; i++) {
+ if (name.equals(applicationParameters[i].getName()) &&
+ !applicationParameters[i].getOverride())
+ return;
+ }
ApplicationParameter results[] =
new ApplicationParameter[applicationParameters.length + 1];
System.arraycopy(applicationParameters, 0, results, 0,
@@ -1350,6 +1356,10 @@
public void addEnvironment(ContextEnvironment environment) {
synchronized (envs) {
+ ContextEnvironment env = (ContextEnvironment)
+ envs.get(environment.getName());
+ if ((env != null) && !env.getOverride())
+ return;
envs.put(environment.getName(), environment);
}
fireContainerEvent("addEnvironment", environment.getName());
1.3 +22 -4
jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/deploy/ApplicationParameter.java
Index: ApplicationParameter.java
===================================================================
RCS file:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/deploy/ApplicationParameter.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ApplicationParameter.java 2001/07/22 20:25:10 1.2
+++ ApplicationParameter.java 2001/09/09 00:48:11 1.3
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/deploy/ApplicationParameter.java,v
1.2 2001/07/22 20:25:10 pier Exp $
- * $Revision: 1.2 $
- * $Date: 2001/07/22 20:25:10 $
+ * $Header:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/deploy/ApplicationParameter.java,v
1.3 2001/09/09 00:48:11 craigmcc Exp $
+ * $Revision: 1.3 $
+ * $Date: 2001/09/09 00:48:11 $
*
* ====================================================================
*
@@ -73,7 +73,7 @@
* to modify the application deployment descriptor itself.
*
* @author Craig R. McClanahan
- * @version $Revision: 1.2 $ $Date: 2001/07/22 20:25:10 $
+ * @version $Revision: 1.3 $ $Date: 2001/09/09 00:48:11 $
*/
public final class ApplicationParameter {
@@ -83,6 +83,20 @@
/**
+ * The description of this environment entry.
+ */
+ private String description = null;
+
+ public String getDescription() {
+ return (this.description);
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+
+ /**
* The name of this application parameter.
*/
private String name = null;
@@ -135,6 +149,10 @@
StringBuffer sb = new StringBuffer("ApplicationParameter[");
sb.append("name=");
sb.append(name);
+ if (description != null) {
+ sb.append(", description=");
+ sb.append(description);
+ }
sb.append(", value=");
sb.append(value);
sb.append(", override=");
1.5 +21 -4
jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/deploy/ContextEnvironment.java
Index: ContextEnvironment.java
===================================================================
RCS file:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/deploy/ContextEnvironment.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ContextEnvironment.java 2001/07/22 20:25:10 1.4
+++ ContextEnvironment.java 2001/09/09 00:48:11 1.5
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/deploy/ContextEnvironment.java,v
1.4 2001/07/22 20:25:10 pier Exp $
- * $Revision: 1.4 $
- * $Date: 2001/07/22 20:25:10 $
+ * $Header:
/home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/deploy/ContextEnvironment.java,v
1.5 2001/09/09 00:48:11 craigmcc Exp $
+ * $Revision: 1.5 $
+ * $Date: 2001/09/09 00:48:11 $
*
* ====================================================================
*
@@ -70,7 +70,7 @@
* an <code><env-entry></code> element in the deployment descriptor.
*
* @author Craig R. McClanahan
- * @version $Revision: 1.4 $ $Date: 2001/07/22 20:25:10 $
+ * @version $Revision: 1.5 $ $Date: 2001/09/09 00:48:11 $
*/
public final class ContextEnvironment {
@@ -108,6 +108,21 @@
/**
+ * Does this environment entry allow overrides by the application
+ * deployment descriptor?
+ */
+ private boolean override = true;
+
+ public boolean getOverride() {
+ return (this.override);
+ }
+
+ public void setOverride(boolean override) {
+ this.override = override;
+ }
+
+
+ /**
* The type of this environment entry.
*/
private String type = null;
@@ -157,6 +172,8 @@
sb.append(", value=");
sb.append(value);
}
+ sb.append(", override=");
+ sb.append(override);
sb.append("]");
return (sb.toString());
1.12 +3 -0 jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- index.xml 2001/09/05 19:45:27 1.11
+++ index.xml 2001/09/09 00:48:11 1.12
@@ -65,6 +65,9 @@
<li><a href="class-loader-howto.html"><strong>Class Loader HOW-TO</strong></a>
- Information about class loading in Tomcat 4, including where to place
your application classes so that they are visible.</li>
+<li><a href="jndi-resources-howto.html"><strong>JNDI Resources HOW-TO</strong></a>
+ - Configuring standard and custom resources in the JNDI naming context
+ that is provided to each web application.</li>
<li><a href="manager-howto.html"><strong>Manager App HOW-TO</strong></a> -
Operating the <code>Manager</code> web app to deploy, undeploy, and
redeploy applications while Tomcat is running.</li>
1.12 +1 -0 jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- project.xml 2001/09/05 19:45:27 1.11
+++ project.xml 2001/09/09 00:48:11 1.12
@@ -25,6 +25,7 @@
<menu name="Administrators">
<item name="Config. Reference" href="config/index.html"/>
<item name="Class Loader HOW-TO" href="class-loader-howto.html"/>
+ <item name="JNDI Resources HOW-TO" href="jndi-resources-howto.html"/>
<item name="Manager App HOW-TO" href="manager-howto.html"/>
<item name="Proxy Support HOW-TO" href="proxy-howto.html"/>
<item name="Realm HOW-TO" href="realm-howto.html"/>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/jndi-resources-howto.xml
Index: jndi-resources-howto.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>JNDI Resources HOW-TO</title>
</properties>
<body>
<section name="Introduction">
<p>Tomcat 4 provides a JNDI <strong>InitialContext</strong> implementation
instance to web applications running under it, in a manner that is compatible
with those provided by a <a href="http://java.sun.com/j2ee";>Java2 Enterprise
Edition</a> application server. Entries in this <code>InitialContext</code>
are configured in the <code>$CATALINA_HOME/conf/server.xml</code> file, and
may be referenced by the following elements in the web application deployment
descriptor (<code>/WEB-INF/web.xml</code>) of your web application:</p>
<ul>
<li><code><strong><env-entry></strong></code> - Environment entry, a
single-value parameter that can be used to configure how the application
will operate.</li>
<li><code><strong><resource-ref></strong></code> - Resource reference,
which is typically to an object factory for resources such as a JDBC
<code>DataSource</code>, a JavaMail <code>Session</code>, or custom
object factories configured into Tomcat 4.</li>
<li><code><strong><resource-env-ref></strong></code> - Resource
environment reference, a new variation of <code>resource-ref</code>
added in Servlet 2.3 that is simpler to configure for resources
that do not require authentication information.</li>
</ul>
<p>The <code>InitialContext</code> is configured as a web application is
initially deployed, and is made available to web application components (for
read-only access). All configured entries and resources will be placed in
the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
access to a resource - in this case, to a JDBC <code>DataSource</code> -
would look something like this:</p>
<source>
// Obtain our environment naming context
Context initCtx = new InitialContext();
Context envCtx = initCtx.lookup("java:comp/env");
// Look up our data source
DataSource ds = (DataSource)
envCtx.lookup("jdbc/EmployeeDB");
// Allocate and use a connection from the pool
Connection conn = ds.getConnection();
... use this connection to access the database ...
conn.close();
</source>
<p>See the following Specifications for more information about programming APIs
for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
servers, which Tomcat emulates for the services that it provides:</p>
<ul>
<li><a href="http://java.sun.com/products/jndi/#download";>Java Naming and
Directory Interface</a> (included in JDK 1.4, available separately for
prior JDK versions)</li>
<li><a href="http://java.sun.com/j2ee/download.html";>J2EE Platform
Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
</ul>
</section>
<section name="Configuring JNDI Resources">
<p>Each available JNDI Resource is configured based on inclusion of the
following elements in the <code>$CATALINA_HOME/conf/server.xml</code>
file:</p>
<ul>
<li><a href="config/context.html#Environment Entries"><Environment></a> -
Configure names and values for scalar environment entries that will be
exposed to the web application through the JNDI
<code>InitialContext</code> (equivalent to the inclusion of an
<code><env-entry></code> element in the web application
deployment descriptor).</li>
<li><a href="config/context.html#Resource Definitions"><Resource></a> -
Configure the name and data type of a resource made available to the
application (equivalent to the inclusion of a
<code><resource-ref></code> element in the web application
deployment descriptor).</li>
<li><a href="config/context.html#Resource Parameters"><ResourceParams></a> -
Configure the Java class name of the resource factory implementation to be
used, as well as JavaBeans properties used to configure that resource
factory.</li>
</ul>
<p>Any number of these elements may be nested inside a
<a href="config/context.html"><Context></a> element (to be associated
only with that particular web application) or inside a
<a href="config/defaultcontext.html"><DefaultContext></a> element
(used to set the default configuration characteristics for automatically
deloyed applications).</p>
<p>In addition, the names and values of all <code><env-entry></code>
elements included in the web application deployment descriptor
(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
well, overriding corresponding values from <code>conf/server.xml</code>
<strong>only</strong> if allowed by the corresponding
<code><Environment></code> element (by setting the
<code>override</code> attribute to "true").</p>
</section>
<section name="Tomcat Standard Resource Factories">
<subsection name="JavaMail Sessions">
</subsection>
<subsection name="JDBC Data Sources">
</subsection>
<subsection name="User Transactions">
</subsection>
</section>
<section name="Adding Custom Resource Factories">
</section>
</body>
</document>
1.4 +288 -3 jakarta-tomcat-4.0/webapps/tomcat-docs/config/context.xml
Index: context.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/context.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- context.xml 2001/08/27 20:22:37 1.3
+++ context.xml 2001/09/09 00:48:11 1.4
@@ -288,6 +288,136 @@
</subsection>
+ <subsection name="Context Parameters">
+
+ <p>You can configure named values that will be made visible to the
+ web application as servlet context initialization parameters by nesting
+ <code><Parameter></code> elements inside this element. For
+ example, you can create an initialization parameter like this:</p>
+<source>
+<Context ...>
+ ...
+ <Parameter name="companyName" value="My Company, Incorporated"
+ override="false"/>
+ ...
+</Context>
+</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>
+<context-param>
+ <param-name>companyName</param-name>
+ <param-value>My Company, Incorporated</param-value>
+</context-param>
+</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><Parameter></code> element
+ are as follows:</p>
+
+ <attributes>
+
+ <attribute name="description" required="false">
+ <p>Optional, human-readable description of this context
+ initialization parameter.</p>
+ </attribute>
+
+ <attribute name="name" required="true">
+ <p>The name of the context initialization parameter to be created.</p>
+ </attribute>
+
+ <attribute name="override" required="false">
+ <p>Set this to <code>false</code> if you do <strong>not</strong> want
+ a <code><context-param></code> for the same parameter name,
+ found in the web application deployment descriptor, to override the
+ value specified here. By default, overrides are allowed.</p>
+ </attribute>
+
+ <attribute name="value" required="true">
+ <p>The parameter value that will be presented to the application
+ when requested by calling
+ <code>ServletContext.getInitParameter()</code>.</p>
+ </attribute>
+
+ </attributes>
+
+ </subsection>
+
+
+ <subsection name="Environment Entries">
+
+ <p>You can configure named values that will be made visible to the
+ web application 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>
+<Context ...>
+ ...
+ <Environment name="maxExemptions" value="10"
+ type="java.lang.Integer" override="false"/>
+ ...
+</Context>
+</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="Lifecycle Listeners">
<p>If you have implemented a Java object that needs to know when this
@@ -337,10 +467,165 @@
...
</Context>
</source>
+
+ <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
+ and <a href="valve.html#Remove Host Filter">Remote Host Filter</a> for
+ more information about the configuration options that are supported.</p>
+
+ </subsection>
+
+
+ <subsection name="Resource Definitions">
+
+ <p>You can declare the characteristics of the resource
+ to be returned for JNDI lookups of <code><resource-ref></code> and
+ <code><resource-env-ref></code> elements in the web application
+ deployment descriptor. 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>
+<Context ...>
+ ...
+ <Resource name="jdbc/EmployeeDB" auth="Container"
+ type="javax.sql.DataSource"
+ description="Employees Database for HR Applications"/>
+ ...
+</Context>
+</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 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>
+<Context ...>
+ ...
+ <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>
+ ...
+</Context>
+</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>
- <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
- and <a href="valve.html#Remove Host Filter">Remote Host Filter</a> for
- more information about the configuration options that are supported.</p>
+ </attributes>
</subsection>
1.2 +285 -0 jakarta-tomcat-4.0/webapps/tomcat-docs/config/defaultcontext.xml
Index: defaultcontext.xml
===================================================================
RCS file:
/home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/defaultcontext.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- defaultcontext.xml 2001/08/25 20:06:30 1.1
+++ defaultcontext.xml 2001/09/09 00:48:11 1.2
@@ -144,6 +144,136 @@
<section name="Special Features">
+ <subsection name="Context Parameters">
+
+ <p>You can configure named values that will be made visible to
+ web applications as servlet context initialization parameters by nesting
+ <code><Parameter></code> elements inside this element. For
+ example, you can create an initialization parameter like this:</p>
+<source>
+<DefaultContext ...>
+ ...
+ <Parameter name="companyName" value="My Company, Incorporated"
+ override="false"/>
+ ...
+</DefaultContext>
+</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>
+<context-param>
+ <param-name>companyName</param-name>
+ <param-value>My Company, Incorporated</param-value>
+</context-param>
+</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><Parameter></code> element
+ are as follows:</p>
+
+ <attributes>
+
+ <attribute name="description" required="false">
+ <p>Optional, human-readable description of this context
+ initialization parameter.</p>
+ </attribute>
+
+ <attribute name="name" required="true">
+ <p>The name of the context initialization parameter to be created.</p>
+ </attribute>
+
+ <attribute name="override" required="false">
+ <p>Set this to <code>false</code> if you do <strong>not</strong> want
+ a <code><context-param></code> for the same parameter name,
+ found in the web application deployment descriptor, to override the
+ value specified here. By default, overrides are allowed.</p>
+ </attribute>
+
+ <attribute name="value" required="true">
+ <p>The parameter value that will be presented to the application
+ when requested by calling
+ <code>ServletContext.getInitParameter()</code>.</p>
+ </attribute>
+
+ </attributes>
+
+ </subsection>
+
+
+ <subsection name="Environment Entries">
+
+ <p>You can configure named values that will be made visible to
+ 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>
+<DefaultContext ...>
+ ...
+ <Environment name="maxExemptions" value="10"
+ type="java.lang.Integer" override="false"/>
+ ...
+</DefaultContext>
+</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="Lifecycle Listeners">
<p>If you have implemented a Java object that needs to know when this
@@ -166,6 +296,161 @@
that may be configured from this element. Attribute names are matched
to corresponding JavaBean property names using the standard property
method naming patterns.</p>
+
+ </subsection>
+
+
+ <subsection name="Resource Definitions">
+
+ <p>You can declare the characteristics of the resource
+ to be returned for JNDI lookups of <code><resource-ref></code> and
+ <code><resource-env-ref></code> elements in the web application
+ deployment descriptor. 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>
+<DefaultContext ...>
+ ...
+ <Resource name="jdbc/EmployeeDB" auth="Container"
+ type="javax.sql.DataSource"
+ description="Employees Database for HR Applications"/>
+ ...
+</DefaultContext>
+</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 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>
+<DefaultContext ...>
+ ...
+ <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>
+ ...
+</DefaultContext>
+</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>
