How do you expose a container-managed JDBC DataSource to a Tomcat web application using a <Resource> element, how does application code look it up, and where must the JDBC driver jar be placed?

## What "container-managed" means here With a container-managed datasource, the *container* owns the connection pool: it reads the configuration, instantiates the pool at context start, and hands the application a `javax.sql.DataSource` through JNDI. The application never names a driver class or a URL in its own code. The upside is that connection details and credentials live in server configuration rather than in the artifact, and the pool can be shared or replaced without rebuilding the application. ## Declaring it ```xml <Context> <Resource name="jdbc/orders" auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" url="jdbc:postgresql://db.internal:5432/orders" username="orders_app" password="..." maxTotal="50" maxIdle="10" maxWaitMillis="5000"/> </Context> ``` Put this in `conf/<engine>/<host>/<appname>.xml` when the values are environment-specific — that file is not part of the WAR, survives redeployment and keeps the password out of the build artifact. Putting it in the application's `META-INF/context.xml` works too, but then every environment needs its own build. Tomcat's default pool implementation is Commons DBCP 2, repackaged inside Tomcat, which is why the sizing attributes are spelled `maxTotal`, `maxIdle` and `maxWaitMillis`. Tomcat also ships its own alternative pool, selected with `factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"`, and you can point `factory` at any other pool's object factory. Attribute names follow whichever pool you chose — a frequent source of "my setting is ignored", because an unknown attribute is simply not applied. ## Looking it up ```java Context initial = new InitialContext(); DataSource ds = (DataSource) initial.lookup("java:comp/env/jdbc/orders"); ``` The `java:comp/env` prefix is the application component's environment naming context — a private tree per web application, which is why two applications can each have a `jdbc/orders` meaning different databases. A common variant narrows to the subcontext first (`lookup("java:comp/env")` then `lookup("jdbc/orders")`); looking up the bare name `jdbc/orders` against a fresh `InitialContext` fails. In modern Tomcat a matching `<resource-ref>` in `web.xml` is optional, though older documentation and other containers still show it; the annotation form is `@Resource(name = "jdbc/orders")` on a field, which lets the container inject the datasource directly. ## Sharing one pool between applications Declare it once in `server.xml`: ```xml <GlobalNamingResources> <Resource name="jdbc/orders" auth="Container" type="javax.sql.DataSource" .../> </GlobalNamingResources> ``` and link it into each application's context: ```xml <Context> <ResourceLink name="jdbc/orders" global="jdbc/orders" type="javax.sql.DataSource"/> </Context> ``` One pool, one set of connections against the database — which is the point when several applications share a database and you care about the total connection count. The trade is coupling: a change to the global resource affects everyone, and one application exhausting the pool starves the rest. ## Where the driver jar goes, and why This is the question that actually fails in practice. The pool is constructed by Tomcat's own code, running under the **common class loader**, which sees `$CATALINA_BASE/lib` and `$CATALINA_HOME/lib` but never looks inside `WEB-INF/lib`. Put the driver in the WAR and context start-up fails with a message about being unable to create a JDBC driver of the given class for the connect URL, wrapping a `ClassNotFoundException`. Copy the driver to `$CATALINA_BASE/lib` and it works. The corollary is that a driver in the shared directory is loaded once for the whole JVM, which is also what keeps it from being a redeploy leak — an application-loaded driver registers itself with the JVM-wide `DriverManager` and pins its class loader after undeployment. ## Other resource types The same `<Resource>` mechanism binds mail sessions, custom object factories and simple constants (via `<Environment>` entries for `java:comp/env` values such as feature flags). The pattern is identical: the container creates the object, the application looks it up by name and never learns where it came from. ## Note on Jakarta From Tomcat 10 onwards the Servlet API packages are `jakarta.servlet.*`, but the datasource `type` remains `javax.sql.DataSource` — JDBC is a Java SE API and did not move. Writing `jakarta.sql.DataSource` in a `<Resource>` is a real and frequent mistake after a Tomcat 9 to 10 upgrade.