Version: 9.3.16.v20170120 |

Working with Jetty JNDI
Previous | Chapter 12. Configuring JNDI Home | Next

##### Contact the core Jetty developers at www.webtide.com

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 for sponsored feature development

## Working with Jetty JNDI

### Defining the web.xml

You can configure naming resources to reference in a `web.xml` file and access from within the `java:comp/env` naming environment of the webapp during execution. Specifically, you can configure support for the following `web.xml` elements:

    <env-entry/>
    <resource-ref/>
    <resource-env-ref/>

Configuring env-entries shows you how to set up overrides for `env-entry` elements in `web.xml`, while Configuring `resource-refs` and `resource-env-refs` discusses how to configure support resources such as `javax.sql.DataSource`.

You can also plug a JTA `javax.transaction.UserTransaction` implementation into Jetty so that webapps can look up `java:comp/UserTransaction` to obtain a distributed transaction manager: see Configuring XA Transactions.

### Declaring Resources

You must declare the objects you want bound into the Jetty environment so that you can then hook into your webapp via `env-entry`, `resource-ref` and `resource-env-refs` in `web.xml`. You create these bindings by using declarations of the following types:

`org.eclipse.jetty.plus.jndi.EnvEntry`
  For `env-entry` type of entries
`org.eclipse.jetty.plus.jndi.Resource`
  For all other type of resources
`org.eclipse.jetty.plus.jndi.Transaction`
  For a JTA manager
`org.eclipse.jetty.plus.jndi.Link`
  For the link between a `web.xml` resource name and a naming entry

Declarations of each of these types follow the same general pattern:

    <New class="org.eclipse.jetty.plus.jndi.xxxx">
      <Arg><!-- scope --></Arg>
      <Arg><!-- name --></Arg>
      <Arg><!-- value --></Arg>
    </New>

You can place these declarations into three different files, depending on your needs and the scope of the resources being declared.

### Deciding Where to Declare Resources

You can define naming resources in three places:

jetty.xml
  Naming resources defined in a `jetty.xml` file are scoped at either the JVM level or the Server level. The classes for the resource must be visible at the Jetty container level. If the classes for the resource only exist inside your webapp, you must declare it in a `WEB-INF/jetty-env.xml` file.
WEB-INF/jetty-env.xml
  Naming resources in a `WEB-INF/jetty-env.xml` file are scoped to the web app in which the file resides. While you can enter JVM or Server scopes if you choose, we do not recommend doing so. The resources defined here may use classes from inside your webapp. This is a Jetty-specific mechanism.
Context xml file
  Entries in a context xml file should be scoped at the level of the webapp to which they apply, although you can supply a less strict scoping level of Server or JVM if you choose. As with resources declared in a `jetty.xml` file, classes associated with the resource must be visible on the container’s classpath.

### Scope of Resource Names

Naming resources within Jetty belong to one of three different scopes, in increasing order of restrictiveness:

JVM scope

  The name is unique across the JVM instance, and is visible to all application code. You represent this scope by a `null` first parameter to the resource declaration. For example:

      <New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
        <Arg></Arg>  <!-- empty arg -->
        <Arg>jms/connectionFactory</Arg>
        <Arg>
          <New class="org.apache.activemq.ActiveMQConnectionFactory">
             <Arg>vm://localhost?broker.persistent=false</Arg>
          </New>
        </Arg>
      </New>

Server scope

  The name is unique to a Server instance, and is only visible to code associated with that instance. You represent this scope by referencing the Server instance as the first parameter to the resource declaration. For example:

      <Configure id="Server" class="org.eclipse.jetty.Server">
        <New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
          <Arg><Ref refid="Server"/></Arg>  <!-- reference to Server instance -->
          <Arg>jms/connectionFactory</Arg>
          <Arg>
            <New class="org.apache.activemq.ActiveMQConnectionFactory">
              <Arg>vm://localhost?broker.persistent=false</Arg>
            </New>
          </Arg>
        </New>
      </Configure>

Webapp scope

  The name is unique to the WebAppContext instance, and is only visible to code associated with that instance. You represent this scope by referencing the `WebAppContext` instance as the first parameter to the resource declaration. For example:

      <Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
        <New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
          <Arg><Ref refid='wac'/></Arg> <!-- reference to WebAppContext -->
          <Arg>jms/connectionFactory</Arg>
          <Arg>
            <New class="org.apache.activemq.ActiveMQConnectionFactory">
              <Arg>vm://localhost?broker.persistent=false</Arg>
            </New>
          </Arg>
        </New>
      </Configure>

### What Can Be Bound as a Resource?

You can bind four types of objects into a Jetty JNDI reference:

- An ordinary POJO instance.
- A javax.naming.Reference instance.
- An object instance that implements the javax.naming.Referenceable interface.
- A link between a name as referenced in `web.xml` and as referenced in the Jetty environment.

Previous | Top | Next
Chapter 12. Configuring JNDI | Home | Configuring JNDI

See an error or something missing? Contribute to this documentation at Github!(Generated: 2017-01-20)