| // ======================================================================== |
| // Copyright (c) 1995-2017 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 the 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. |