tomcat JNDI data source setup - howto guides seem mistaken

Hi I've read the following HOWTOs on the apache site:

http://tomcat.apache.org/tomcat-6.0-doc/jndi-datasource-examples-howto.html
http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html
http://tomcat.apache.org/tomcat-5.0-doc/jndi-datasource-examples-howto.html

They all say to put information about the data source into web.xml as well as context.xml

Every time I've done this, it seems like putting it into both places is not necessary. Plus, the docs about context.xml (http://tomcat.apache.org/tomcat-5.5-doc/config/context.html) say the following,

You can create a resource definition like this:
<Context ...> ... <Resource name="jdbc/EmployeeDB" auth="Container" type="javax.sql.DataSource" description="Employees Database for HR Applications"/> ... </Context>

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.

which seems to say exactly the opposite of what the HOWTOs say.

So are the HOWTOs wrong? If so, they've been wrong for many years. What's the deal?

Tim McGuire wrote:Hi I've read the following HOWTOs on the apache site:

http://tomcat.apache.org/tomcat-6.0-doc/jndi-datasource-examples-howto.html
http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html
http://tomcat.apache.org/tomcat-5.0-doc/jndi-datasource-examples-howto.html

They all say to put information about the data source into web.xml as well as context.xml

What do they say exactly?

You have to put the definitions of JNDI objects into web.xml.

You can optionally put override definitions into a Tomcat configuration.

However, in the case of datasources, the web.xml element isn't a resource definition, it's a <resource-ref> - a resource Reference. It doesn't define the value of the object, only its logical name and datatype. Therefore, it must me matched (via its logical name) to an externally-supplied Definition.

For a DataSource, that definition indicates the database URL, its connection parameters, pool configuration, and other important items that shouldn't require modifying the WAR if you want to change them.

Does that make sense?

Tim Holloway wrote:You have to put the definitions of JNDI objects into web.xml.

You can optionally put override definitions into a Tomcat configuration.

However, in the case of datasources, the web.xml element isn't a resource definition, it's a <resource-ref> - a resource Reference. It doesn't define the value of the object, only its logical name and datatype. Therefore, it must me matched (via its logical name) to an externally-supplied Definition.

For a DataSource, that definition indicates the database URL, its connection parameters, pool configuration, and other important items that shouldn't require modifying the WAR if you want to change them.

Does that make sense?

I can't tell if you are saying that a resource-ref element is required. I'm looking at several tomcat applications that have no resource-ref defined in web.xml but are working fine with data sources defined in context.xml

The reason I'm interested is that I spent some time messing with the web.xml of my application when the problem with my datasource was somewhere else and I felt misled by the HOWTO.

In my experience, the Tomcat docs are specific to each version of Tomcat. If I were using Tomcat 6.0.24 I would look at the Tomcat 6 docs and ignore the previous doc versions.

JNDI Resources HowTo

Under web.xml configuration:

Providing that Tomcat is able to identify an appropriate resource factory to use to create the resource and that no further configuration information is required, Tomcat will use the information in /WEB-INF/web.xml to create the resource.

Under context.xml configuration:

If Tomcat is unable to identify the appropriate resource factory and/or additional configuration information is required, additional Tomcat specific configuration must be specified before Tomcat can create the resource. Tomcat specific resource configuration is entered in the <Context> elements that can be specified in either $CATALINA_BASE/conf/server.xml or, preferably, the per-web-application context XML file (META-INF/context.xml).
...

If a resource has been defined in a <Context> element it is not necessary for that resource to be defined in /WEB-INF/web.xml. However, it is recommended to keep the entry in /WEB-INF/web.xml to document the resource requirements for the web application.

Which type of JNDI resource are you trying to create? User Database, JDBC Data Source, LDAP? You should start with the appropriate "Realm" on the realm-howto page, that stuff goes in server.xml
The "resource-ref" stuff goes in web.xml