//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= JNDI

For each specific Jakarta EE _environment_ there is a specific `plus` module that you must enable in order to use JNDI resources in your webapp:

* For Java EE 8, `ee8-plus`
* For Java EE 9, `ee9-plus`
* For Java {ee-current-caps}, `{ee-current}-plus`

If you have already enabled an xref:annotations/index.adoc[`annotations`] module suitable for your EE environment, an appropriate `plus` module will already have been enabled and you do not need to explicitly enable a `plus` module.

If you have extra jars associated with your JNDI resources, eg database drivers etc, that are not located inside your webapp then you must ensure they are on either the container classpath or a Jakarta EE environment classpath.
You can enable the `ext` module and place your jars in `${jetty.base}/lib/ext` to make them visible on the container classpath.
To make them visible on an EE environment classpath you should create a custom, EE environment-specific module.

You can now declare JNDI resources and reference them within your webapps.

== Declaring resources

You must declare the objects you want bound so that you can then hook them into your webapp via `env-entry`, `resource-ref` and `resource-env-refs` in `web.xml`, `web-fragment.xml` or `override-web.xml`.

You make these declarations in Jetty XML files that are either _external_  or _internal_ to your webapp.
A server or context XML file is external to your webapp.
The special `WEB-INF/jetty-{ee-all}-env.xml` file is internal to your webapp. 

TIP: It is good practice to name the file according to the `environment` into which your webapp is deployed. This way you can supply a file for each `environment` into which you deploy the webapp . If you only ever deploy to a single environment, you may omit the `environment` from the name, however be aware that you cannot change environments without updating the contents of the file to match.

See the section on <<xml,Jetty XML files>> for more information on how to choose in which XML file to place your declarations.

Regardless of its location, the XML file contains declarations of JNDI resources that can be referenced later within your webapp.

The declarations are new instances of the following types:

<<env,`org.eclipse.jetty.plus.jndi.EnvEntry`>>::
Used for `env-entry` type of entries
<<resource,`org.eclipse.jetty.plus.jndi.Resource`>>::
Used for most other type of resources
<<tx,`org.eclipse.jetty.plus.jndi.Transaction`>>::
For a JTA manager
<<link,`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 a similar pattern:

.wiki.xml
[,xml,subs=attributes+]
----
<New class="org.eclipse.jetty.plus.jndi.xxxx"> <!--1-->
  <Arg><!-- scope --></Arg> <!--2-->
  <Arg><!-- name --></Arg>  <!--3-->
  <Arg><!-- value --></Arg> <!--4-->
</New>
----
<1> Defines a resource to Jetty.
<2> Specifies the <<scope,scope>> of the resource.
<3> Specifies the name of the resource which will be looked up by the webapp relative to the `java:comp/` or `java:comp/env` namespace.
<4> Specifies the value of the resource.


[[env]]
=== org.eclipse.jetty.plus.jndi.EnvEntry

Sometimes it is useful to pass configuration information to a webapp at runtime that you either cannot or cannot conveniently code into a `web.xml` `<env-entry>`.
In such cases, you can use the `org.eclipse.jetty.plus.jndi.EnvEntry` class, and optionally even override an entry of the same name in `web.xml`.

Here's an example that defines the equivalent of an `env-entry` called `mySpecialValue` with value `4000` that overrides an `<env-entry>` declaration of the same name in web.xml:

.wiki.xml
[,xml,subs=attributes+]
----
<New class="org.eclipse.jetty.plus.jndi.EnvEntry"> <!--1-->
  <Arg></Arg> <!--2-->
  <Arg>mySpecialValue</Arg> <!--3-->
  <Arg type="java.lang.Integer">4000</Arg> <!--4-->
  <Arg type="boolean">true</Arg> <!--5-->
</New>
----
<1> Define an `EnvEntry` that corresponds to an `<env-entry>`.
<2> <<scope,Scoped>> at the JVM level.
<3> The name of the entry, corresponding to a lookup by the webapp of `java:comp/env/mySpecialValue`.
<4> The value of the entry, in this case the integer value `4000`.
<5> `true` means to override the value of an `<env-entry>` of the same name in `web.xml`.

Note that if you don't want to override the `web.xml` value, simply omit the last argument, or set it to `false`.

The Servlet Specification allows binding only the following object types 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

Jetty is a little more flexible and allows you to also bind:

* custom POJOs
* http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Reference.html[`javax.naming.References`]
* http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Referenceable.html[`javax.naming.Referenceables`]

Be aware that if you take advantage of this feature, your web application is __not portable__.

[[resource]]
=== org.eclipse.jetty.plus.jndi.Resource

You can configure any type of resource that you want to refer to in `web.xml` via a `resource-ref` or `resource-env-ref` by using the `org.eclipse.jetty.plus.jndi.Resource` type of naming entry.

You provide the scope, the name of the object (relative to `java:comp/env`) and a POJO, `javax.naming.Reference` or `javax.naming.Referenceable` instance.

==== DataSources

This example configures a http://db.apache.org/derby[Derby] DataSource named `jdbc/myds`:

.wiki.xml
[,xml,subs=attributes+]
----
<Configure id='wac' class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
  <New class="org.eclipse.jetty.plus.jndi.Resource">
    <Arg><Ref refid="wac"/></Arg>
    <Arg>jdbc/myds</Arg>
    <Arg>
      <New class="org.apache.derby.jdbc.EmbeddedDataSource">
        <Set name="DatabaseName">test</Set>
        <Set name="createDatabase">create</Set>
      </New>
    </Arg>
  </New>
</Configure>
----

This would be linked into the webapp's JNDI namespace via an entry in a `web.xml` like so:

[,xml]
----
<resource-ref>
  <res-ref-name>jdbc/myds</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
</resource-ref>
----

[NOTE]
====
When configuring Resources, ensure that the type of object you configure matches the type of object you expect to look up 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.

Also note that the http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing DataSources relative to `jdbc/` and thus looked up by the application as `java:comp/env/jdbc/xxx`.
Eg The Datasource bound in Jetty as `jdbc/users` would be looked up by the application as `java:comp/env/jdbc/users`

====

//TODO For more examples of datasource configurations, see xref:jndi-datasource-examples[].


==== JMS Queues, Topics and ConnectionFactories

Jetty can bind any implementation of the JMS destinations and connection factories.

Here is an example of binding an http://activemq.apache.org[ActiveMQ] in-JVM connection factory:

.wiki.xml
[,xml,subs=attributes+]
----
<Configure id='wac' class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
  <New class="org.eclipse.jetty.plus.jndi.Resource">
    <Arg><Ref refid='wac'/></Arg>
    <Arg>jms/connectionFactory</Arg>
    <Arg>
      <New class="org.apache.activemq.ActiveMQConnectionFactory">
        <Arg>vm://localhost?broker.persistent=false</Arg>
      </New>
    </Arg>
  </New>
</Configure>
----

The corresponding entry in `web.xml` to bind the ConnectionFactory into the webapp's JNDI namespace would be:

.wiki.xml
[,xml,subs=attributes+]
----
<resource-ref>
  <res-ref-name>jms/connectionFactory</res-ref-name>
  <res-type>javax.jms.ConnectionFactory</res-type>
  <res-auth>Container</res-auth>
</resource-ref>
----

[NOTE]
====
The http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing JMS connection factories under `jms/`.
Eg The ConnectionFactory bound in Jetty as `jms/inqueue` would be looked up by the application as `java:comp/env/jms/inqueue`.
====

==== Mail

To configure access to `javax.mail.Session` from within a webapp, declare an `org.eclipse.jetty.plus.jndi.Resource` with an `org.eclipse.jetty.{ee-all}.jndi.factories.MailSessionReference` that will hold the mail configuration and create the instance of the `Session` when it is referenced:

.wiki.xml
[,xml,subs=attributes+]
----
<Configure id='wac' class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
  <New class="org.eclipse.jetty.plus.jndi.Resource">
    <Arg><Ref refid="wac"/></Arg>
    <Arg>mail/Session</Arg>
    <Arg>
      <New class="org.eclipse.jetty.{ee-current}.jndi.factories.MailSessionReference"> <!--1-->
        <Set name="user">fred</Set> <!--2-->
        <Set name="password">OBF:1xmk1w261z0f1w1c1xmq</Set> <!--3-->
        <Set name="properties"> <!--4-->
          <New class="java.util.Properties">
            <Put name="mail.smtp.host">XXX</Put>
            <Put name="mail.from">me@me</Put>
            <Put name="mail.debug">true</Put>
          </New>
        </Set>
      </New>
    </Arg>
  </New>
</Configure>
----
<1> Use the `org.eclipse.jetty.{ee-current}.factories.MailSessionReference` class to hold the configuration.
<2> Set the username for the mail instance.
<3> Set the password for the mail instance -- use the xref:tools/index.adoc#password[Jetty Password tool] to obfuscate the password.
<4> Set all other applicable properties.

The webapp performs a lookup for `java:comp/env/mail/Session` at runtime and obtains a `javax.mail.Session` that has the correct configuration to permit it to send email via SMTP.

[NOTE]
====
Jetty does not provide the `javax.mail` and `javax.activation` jars.

Note also that the http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html[J2EE Specification] recommends storing JavaMail connection factories under `mail/`.
Eg The `MailSessionReference` bound to jetty as `mail/smtp` would be looked up by the application as `java:comp/env/mail/smtp`.
====

[[tx]]
=== org.eclipse.jetty.plus.jndi.Transaction

To perform distributed transactions with your resources, a _transaction manager_ that supports the JTA interfaces is required.
The transaction manager is looked up by the application as `java:comp/UserTransaction`.

Jetty does not ship with a JTA manager, but _does_ provide the infrastructure to plug in the JTA manager of your choice.

If your JTA library's implementation of `UserTransaction` implements `javax.naming.Reference`, then you should use the `org.eclipse.jetty.plus.jndi.Transaction` object in a <<xml,Jetty XML file>> to register it in JNDI:

.wiki.xml
[,xml,subs=attributes+]
----
  <New id="tx" class="org.eclipse.jetty.plus.jndi.Transaction">
    <Arg><Property name="environment" default="{ee-current}"/></Arg>
    <Arg>
      <New class="org.example.MyUserTransactionReference" />
    </Arg>
  </New>
----

If your JTA library's implementation of `UserTransaction` does _not_ implement `javax.naming.Reference`, then you should use the Jakarta EE specific Jetty class to register it in JNDI:

.wiki.xml
[,xml,subs=attributes+]
----
  <New id="tx" class="org.eclipse.jetty.{ee-current}.plus.jndi.Transaction">
    <Arg><Property name="environment" default="{ee-current}"/></Arg>
    <Arg>
      <New class="org.example.MyUserTransaction" />
    </Arg>
  </New>
----

Jetty will automatically bind this JTA manager to the webapp's JNDI namespace at `java:comp/UserTransaction`.

[[link]]
=== org.eclipse.jetty.plus.jndi.Link

Usually, the name you provide for the `org.eclipse.jetty.plus.jndi.Resource` is the same name you reference in `web.xml`.
This ensures that the two are linked together and thus accessible to your webapp.

However, if the names cannot be the same, then it is possible to effectively alias one to another using an `org.eclipse.jetty.plus.jndi.Link`.

Supposing you have a declaration for a Datasource named `jdbc/workforce` in a Jetty context XML file, but your web.xml wants to link to a `<resource-ref>` named `jdbc/employees`, and you cannot edit the web.xml.
You can create a `WEB-INF/jetty-{ee-all}-env.xml` file with an `org.eclipse.jetty.plus.jndi.Link` that ties together the names `jdbc/workforce` and `jdbc/employees`:

The context XML file declares `jdbc/workforce`:

.wiki.xml
[,xml,subs=attributes+]
----
<Configure id='wac' class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
  <New class="org.eclipse.jetty.plus.jndi.Resource">
    <Arg><Ref refid="wac"/></Arg>
    <Arg>jdbc/workforce</Arg>
    <Arg>
      <New class="org.apache.derby.jdbc.EmbeddedDataSource">
        <Set name="DatabaseName">test</Set>
        <Set name="createDatabase">create</Set>
      </New>
    </Arg>
  </New>
</Configure>
----

The `web.xml` refers to it as `jdbc/employees`:

.wiki.xml
[,xml,subs=attributes+]
----
<resource-ref>
  <res-ref-name>jdbc/employees</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
</resource-ref>
----

Create a `WEB-INF/jetty-{ee-all}-env.xml` file with a `org.eclipse.jetty.plus.jndi.Link` to link these names together:

.wiki.xml
[,xml,subs=attributes+]
----
<New class="org.eclipse.jetty.plus.jndi.Link">
  <Arg><Ref refid='wac'/></Arg>
  <Arg>jdbc/employees</Arg> <!--1-->
  <Arg>jdbc/workforce</Arg>  <!--2-->
</New>
----
<1> The name as referenced in the `web.xml` file.
<2> The name as referenced in the context XML file.

[[xml]]
=== Jetty XML files

You can define naming resources in three places:

Server XML file::
Naming resources defined in a server XML file are <<scope,scoped>> at the JVM, `org.eclipse.jetty.server.Server` or environment level.
Note that the classes for the resource _must_ be visible at the point in time that the XML executes.
For example, environment level resources should be declared in an XML file that is referenced by a custom module that contains an `[environment]` clause at the matching environment level to ensure the classpath for that environment is available.

Context XML file::
Entries in a context XML file should be <<scope,scoped>> at the level of the webapp to which they apply (it is possible to use a less strict scoping level of Server or JVM, but not recommended).
As a context XML file executes _before_ the webapp's classes are available, the classes for your resource must be external to the webapp and on either the container or environment classpath.

WEB-INF/jetty-{ee-all}-env.xml::
Naming resources in a `WEB-INF/jetty-{ee-all}-env.xml` file are <<scope,scoped>> to the webapp in which the file resides.
The resources defined here may use classes from inside your webapp.

[[scope]]
=== Resource scoping

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

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

.wiki.xml
[,xml,subs=attributes+]
----
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg></Arg>  <!--1-->
  <Arg>jms/connectionFactory</Arg>
  <Arg>
    <New class="org.apache.activemq.ActiveMQConnectionFactory">
       <Arg>vm://localhost?broker.persistent=false</Arg>
    </New>
  </Arg>
</New>
----
<1> Empty first arg equates to JVM scope for the object bound to name `jms/connectionFactory`.

*Environment scope:*
The name is unique within a Jetty _environment_.
It is represented by referencing the name of the Jakarta EE environment as the first parameter to the resource declaration.
For example:

.wiki.xml
[,xml,subs=attributes+]
----
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg>{ee-current}</Arg>  <!--1-->
  <Arg>jms/connectionFactory</Arg>
  <Arg>
    <New class="org.apache.activemq.ActiveMQConnectionFactory">
      <Arg>vm://localhost?broker.persistent=false</Arg>
    </New>
  </Arg>
</New>
----

*Webapp scope:*
The name is unique to the `org.eclipse.jetty.{ee-all}.webapp.WebAppContext` instance, and is only visible to that application.
This scope is represented by referencing the instance as the first parameter to the resource declaration.
For example:

.wiki.xml
[,xml,subs=attributes+]
----
<New class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg><Ref refid='wac'/></Arg> <!--1-->
  <Arg>jms/connectionFactory</Arg>
  <Arg>
    <New class="org.apache.activemq.ActiveMQConnectionFactory">
      <Arg>vm://localhost?broker.persistent=false</Arg>
    </New>
  </Arg>
</New>
----
