Using JNDI Resources with jetty6
java:comp/env lookups in webapps. This is an optional feature provided by the 2 jars
lib/plus/jetty-plus.jar. As it is an optional feature, some setup needs to be done. We'll show you how to do it, although we have provided jetty configuration files that already have JNDI enabled to help you get going faster. More on that later.
Firstly, to enable JNDI for a web application, you need to configure the WebAppContext to parse the web.xml file and perform the
java:comp/env linkages. The class that does this is
org.mortbay.jetty.plus.webapp.Configuration, and we specify its name in the list of configurations to be applied to the webapp when we define the
org.mortbay.jetty.webapp.WebAppContext for it. The following example enables naming services for the
Or, more conveniently, you can specify that these configurations are used for every webapp deployed from a specified directory, eg
webapps-plus. Assuming the same definition of the Configurations array as above, instead of explicitly configuring each individual webapp, you can say instead:
You may now configure naming resources that can be referenced in a web.xml file and accessed from within the
java:comp/env naming environment of the webapp during execution. Specifically, you may configure support for the following web.xml elements:
Configuring env-entrys shows you how to set up overrides for
env-entry elements in web.xml. Configuring resource-refs and resource-env-refs discusses how to configure support resources such as
Furthermore, it is possible to plug a JTA
javax.transaction.UserTransaction implementation into Jetty so that webapps can lookup
java:comp/UserTransaction to obtain a distributed transaction manager. See Configuring Transactions.
You can define your naming resources to be either globally accessible (ie can be resolved by any webapp) or resolvable only within a particular webapp. The section Global or scoped to a webapp shows you how.
Sometimes it is useful to be able to pass configuration information to a webapp at runtime that either cannot be or is not convient to be coded into a web.xml
env-entry. In this case, you can use
org.mortbay.jetty.plus.naming.EnvEntry and even configure them to override an entry of the same name in web.xml.
This example will define an
mySpecialValue with value
4000 that will be put into JNDI at
java:comp/env/mySpecialValue. Moreover, the boolean argument indicates that this value should override an
env-entry of the same name in web.xml. If you don't want to override, then omit this argument or set it to
Configuring resource-refs and resource-env-refs
Any type of resource that you want to refer to in a web.xml file as a
resource-env-ref can be configured in a
jetty.xml file using the
org.mortbay.naming.plus.Resource class. You need to provide the name of the object, relative to
java:comp/env and the instance of the object itself. The J2EE Specification recommends that DataSources are stored in
java:comp/env/jdbc, JMS connection factories under
java:comp/env/jms, JavaMail connection factories under
java:comp/env/mail and URL connection factories under
java:comp/env/url. For example:
Name in jetty.xml
Lets look at an example of configuring a javax.sql.DataSource. In our example, we'll use a DataSource from the Derby relational database, but you can use any implementation of a
Configuring XA Transactions
If you want to be able to perform distributed transactions with your resources, you will need a transaction manager that supports the JTA interfaces that you can lookup as
java:comp/UserTransaction in your webapp. Jetty does not ship with one, rather you may plug in the one of your preference. You can configure the one of your choice using the
org.mortbay.jetty.plus.naming.Transaction object in a jetty config file. In the following example, we will configure the Atomikos transaction manager:
See also the instructions for how to configure JOTM. Contributions of instructions for other transaction managers are welcome.
Global or scoped to a webapp
If you place any of the naming resources discussed in the next sections in a jetty configuration file, they will be used by all webapps to resolve
You can instead make naming resources that are only resolvable by a particular webapp. For instance, you might want to do this if one of the objects you want to bind can only be loaded from the webapp's classloader.
Here's how to do it. Create a
WEB-INF/jetty-env.xml file in your webapp. An example might look like:
That's all you need to do. Jetty6 will automatically check for a file of this name and add any naming resources to a locally-scoped naming environment for resolution of
web.xml references. You may define
Resource elements in this file but you cannot define a
Transaction because this is a container-level resource.
Demo Web Application
There is a demonstration webapp which sets up examples of all of the JNDI resources we've discussed so far.
In order to run this demonstration, you will need to download the transaction manager (and any necessary JDBC drivers etc) of your choice. At the time of writing, the webapp has been tested with both JOTM and with Atomikos.
Building the Demo
As the demo webapp is not pre-built with the distribution, you first have to build it. It is located in
examples/test-jndi-webapp. There is a
README.txt file in there which explains how to build it, and how to add support for different transaction managers.
Basically, it is a matter of typing:
where you replace
xxx with the name of the transaction manager package you want to use, eg
This builds the webapp and copies a suitable jetty configuration file called
jetty-test-jndi.xml into the
Running the Demo
The URL for the demonstration is at: