Jetty has moved!
Jetty is a project at the Eclipse Foundation.
Jetty Powered:
Contact the core Jetty developers at
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 39 Next »

Using JNDI Resources with jetty6

Jetty6 supports java:comp/env lookups in webapps. This is an optional feature provided by the 2 jars lib/naming/jetty-naming.jar and 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, 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 xyzWebAppContext:

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:



To save you some time, we have included the etc/jetty-plus.xml configuration file that configures all of the features in the lib/naming/jetty-naming.jar and lib/plus/jetty-plus.jar for any webapp deployed to the webapps-plus directory.

In order to run Jetty with support for JNDI, all you need to do is:

java -jar start.jar etc/jetty.xml etc/jetty-plus.xml

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 javax.sql.DataSource.

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 XA 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.

Before we go any further, lets take a look at what kind of things can be bound into JNDI with Jetty.

What can be bound and general overview

There are 3 types of objects that can be bound into Jetty's JNDI:

  • an ordinary POJO instance
  • a java.naming.Reference instance
  • an object instance that implements the java.naming.Referenceable interface

The binding for all of these object types follows the same pattern:

<New class=type of naming entry>
<Arg>name to bind as</Arg>
<Arg>the object to bind</Arg>

The type of naming entry will be either "" (for <env-entry>s or a "" (for all other type of resources). There is also a third type of naming entry "" which deviates slightly from this pattern which is used to bind a JTA manager (we'll take a closer look at that in the Configuring XA Transactions section).

Configuring env-entrys

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 and even configure them to override an entry of the same name in web.xml.

This example will define an env-entry called 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 false.

Note that the Servlet Specification only allows the following types of object to be bound to an env-entry: java.lang.String, java.lang.Integer, java.lang.Float, java.lang.Double, java.lang.Long, java.lang.Short, java.lang.Character, java.lang.Byte, java.lang.Boolean. However, Jetty is a little more flexible and will allow you to bind custom POJOs, javax.naming.References and javax.naming.Referenceables. Be aware if you take advantage of this feature that your web application will not be portable.

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-ref or resource-env-ref can be configured in a jetty.xml file using the class. You need to provide the name of the object, relative to java:comp/env and a POJO instance, javax.naming.Reference instance or javax.naming.Referenceable instance.

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:

Resource Type

Name in jetty.xml

Environment Lookup










Configuring DataSources

Lets look at an example of configuring a javax.sql.DataSource. Jetty can use any DataSource implementation available on it's classpath. In our example, we'll use a DataSource from the Derby relational database, but you can use any implementation of a javax.sql.DataSource:



If you want to try this yourself, you will need to download Derby.

The above would create an instance of org.apache.derby.jdbc.EmbeddedDataSource, call the two setter methods setDatabaseName("test"); and setCreateDatabase("create"); and bind it into JNDI such that it is available from application lookups as java:comp/env/jdbc/myds.



When configuring Resources, you need to ensure that the type of object you configure matches the type of object you expect to lookup in java:comp/env. For database connection factories, this means that the object you register as a Resource must implement the javax.sql.DataSource interface.

Configuring Mail

Jetty also provides infrastructure for providing access to {{javax.mail.Session}}s from within an application:

The setup above creates an instance of the class, calls it's setter methods setUser("fred");, setPassword("OBF:1xmk1w261z0f1w1c1xmq"); to set up the authentication for the mail system, then populates a set of Properties, setting them on the MailSessionReference instance. The result of this is that an application can lookup java:comp/env/mail/Session at runtime and obtain access to a javax.mail.Session that has the necessary configuration to permit it to send email via SMTP.

Configuring JMS Queues, Topics and ConnectionFactory-s

Jetty is able to bind any implementation of the JMS destinations and connection factories. You just need to ensure the implementation jars are available on Jetty's classpath.

Here's an example of binding an ActiveMQ in-JVM connection factory:

There is more information about ActiveMQ and Jetty here.

We will be adding more examples of configuring database datasources (eg using XAPool and DBCP) and jms connection factories, so check back regularly. Contributions are also welcome.

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 object in a jetty config file. In the following example, we will configure the Atomikos transaction manager:



In order to use the Atomikos transaction manager, you will need to download it and install it. There are instructions here on how to configure it for jetty6.

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 web.xml references.

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 any naming resources in this file, but it would usually be undesirable to define a Transaction, because this is intended to be a container-level resource and if defined in the {{jetty-env.xml} file the transaction manager will only be visible to that webapp.

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 -Dtxmgr=jotm or -Dtxmgr=atomikos.

This builds the webapp and copies a suitable jetty configuration file called jetty-test-jndi.xml into the etc directory.

Running the Demo

The URL for the demonstration is at:


  • No labels
Contact the core Jetty developers at
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery