What is resource-ref in web.xml used for?

Question

I'm just wondering when/why you would define a <resource-ref> element in your web.xml file?

I would have thought that it would be defined in your web/app server using JNDI and then look up the JNDI reference in your Java code?

The resource-ref definition seems a bit redundant to me and I can't think of when it might be useful. Example:

<resource-ref>
  <description>Primary database</description>
  <res-ref-name>jdbc/primaryDB</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>CONTAINER</res-auth>
</resource-ref>

Answer 1

You can always refer to resources in your application directly by their JNDI name as configured in the container, but if you do so, essentially you are wiring the container-specific name into your code. This has some disadvantages, for example, if you'll ever want to change the name later for some reason, you'll need to update all the references in all your applications, and then rebuild and redeploy them.

<resource-ref> introduces another layer of indirection: you specify the name you want to use in the web.xml, and, depending on the container, provide a binding in a container-specific configuration file.

So here's what happens: let's say you want to lookup the java:comp/env/jdbc/primaryDB name. The container finds that web.xml has a <resource-ref> element for jdbc/primaryDB, so it will look into the container-specific configuration, that contains something similar to the following:

<resource-ref>
  <res-ref-name>jdbc/primaryDB</res-ref-name>
  <jndi-name>jdbc/PrimaryDBInTheContainer</jndi-name>
</resource-ref>

Finally, it returns the object registered under the name of jdbc/PrimaryDBInTheContainer.

The idea is that specifying resources in the web.xml has the advantage of separating the developer role from the deployer role. In other words, as a developer, you don't have to know what your required resources are actually called in production, and as the guy deploying the application, you will have a nice list of names to map to real resources.

Answer 2

An old question, but I have a nice example of where this is useful. I've got two WAR files based on a common framework, and which need to be deployed into the same application server... they require different data sources, but because of the common framework, they use the same JNDI to look it up. It's further complicated by the fact that they're deployed on WebLogic for production and Tomcat for testing, so portability of the container-specific names is a factor.

Using <resource-ref> makes it simple... the framework supplies a common web.xml which looks for a specific name of jdbc/myDataSource, and external to the application itself, both WebLogic and Tomcat can be configured to serve a suitable data source under that alias. And because the alias is application specific, multiple applications in the same server can request the same JNDI name, and get different data sources as required.