//  ========================================================================
//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================

[[using-jetty-jndi]]
=== 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:

[source, xml, subs="{sub-order}"]
----

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

      
----

link:#configuring-jndi-env-entries[Configuring env-entries] shows you
how to set up overrides for `
    env-entry` elements in `web.xml`, while
link:#configuring-resource-refs-and-resource-env-refs[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 link:#configuring-xa-transactions[Configuring XA Transactions].

[[defining-jndi-naming-entries]]
==== 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 link between a `web.xml` resource name and a naming entry

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

[source, xml, subs="{sub-order}"]
----

<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 link:#jndi-name-scope[scope] of the resources
being declared.

[[jndi-where-to-declare]]
==== Deciding Where to Declare Resources

You can define naming resources in three places:

jetty.xml::
  Naming resources defined in a `jetty.xml` file are
  link:#jndi-name-scope[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
  link:#jndi-name-scope[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 link:#jndi-name-scope[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.

[[jndi-name-scope]]
==== 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:
  +
[source, xml, subs="{sub-order}"]
----

<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:
  +
[source, xml, subs="{sub-order}"]
----

<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:
  +
[source, xml, subs="{sub-order}"]
----

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

                
----

[[binding-objects-into-jetty-jndi]]
==== What Can Be Bound as a Resource?

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

* An ordinary POJO instance.
* A
http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Reference.html[javax.naming.Reference]
instance.
* An object instance that implements the
http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Referenceable.html[javax.naming.Referenceable]
interface.
* A link between a name as referenced in `web.xml` and as referenced in
the Jetty environment.

