// // ======================================================================== // 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 <> 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: <>:: Used for `env-entry` type of entries <>:: Used for most other type of resources <>:: For a JTA manager <>:: 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+] ---- ---- <1> Defines a resource to Jetty. <2> Specifies the <> 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` ``. 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 `` declaration of the same name in web.xml: .wiki.xml [,xml,subs=attributes+] ---- mySpecialValue 4000 true ---- <1> Define an `EnvEntry` that corresponds to an ``. <2> <> 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 `` 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+] ---- jdbc/myds test create ---- This would be linked into the webapp's JNDI namespace via an entry in a `web.xml` like so: [,xml] ---- jdbc/myds javax.sql.DataSource Container ---- [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+] ---- jms/connectionFactory vm://localhost?broker.persistent=false ---- The corresponding entry in `web.xml` to bind the ConnectionFactory into the webapp's JNDI namespace would be: .wiki.xml [,xml,subs=attributes+] ---- jms/connectionFactory javax.jms.ConnectionFactory Container ---- [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+] ---- mail/Session fred OBF:1xmk1w261z0f1w1c1xmq XXX me@me true ---- <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 <> to register it in JNDI: .wiki.xml [,xml,subs=attributes+] ---- ---- 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+] ---- ---- 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 `` 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+] ---- jdbc/workforce test create ---- The `web.xml` refers to it as `jdbc/employees`: .wiki.xml [,xml,subs=attributes+] ---- jdbc/employees javax.sql.DataSource Container ---- 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+] ---- jdbc/employees jdbc/workforce ---- <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 <> 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 <> 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 <> 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+] ---- jms/connectionFactory vm://localhost?broker.persistent=false ---- <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+] ---- {ee-current} jms/connectionFactory vm://localhost?broker.persistent=false ---- *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+] ---- jms/connectionFactory vm://localhost?broker.persistent=false ----