<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Working with Jetty JNDI</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="jndi.html" title="Chapter&nbsp;12.&nbsp;Configuring JNDI"><link rel="prev" href="jndi.html" title="Chapter&nbsp;12.&nbsp;Configuring JNDI"><link rel="next" href="jndi-configuration.html" title="Configuring JNDI"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script>
      hljs.initHighlightingOnLoad();
    </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
            Version: 9.3.28.v20191105</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Working with Jetty JNDI</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jndi.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;12.&nbsp;Configuring JNDI<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jndi-configuration.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
          <span class="website">www.webtide.com</span></a></h5><p>
 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
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="using-jetty-jndi"></a>Working with Jetty JNDI</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="using-jetty-jndi.html#_defining_the_web_xml">Defining the web.xml</a></span></dt><dt><span class="section"><a href="using-jetty-jndi.html#defining-jndi-naming-entries">Declaring Resources</a></span></dt><dt><span class="section"><a href="using-jetty-jndi.html#jndi-where-to-declare">Deciding Where to Declare Resources</a></span></dt><dt><span class="section"><a href="using-jetty-jndi.html#jndi-name-scope">Scope of Resource Names</a></span></dt><dt><span class="section"><a href="using-jetty-jndi.html#binding-objects-into-jetty-jndi">What Can Be Bound as a Resource?</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_defining_the_web_xml"></a>Defining the web.xml</h3></div></div></div><p>You can configure naming resources to reference in a <code class="literal">web.xml</code> file and access from within the <code class="literal">java:comp/env</code> naming environment of the webapp during execution.
Specifically, you can configure support for the following <code class="literal">web.xml</code> elements:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;env-entry/&gt;
&lt;resource-ref/&gt;
&lt;resource-env-ref/&gt;</code></pre><p><a class="link" href="jndi-configuration.html#configuring-jndi-env-entries" title="Configuring JNDI env-entries">Configuring env-entries</a> shows you how to set up overrides for <code class="literal">env-entry</code> elements in <code class="literal">web.xml</code>, while <a class="link" href="jndi-configuration.html#configuring-resource-refs-and-resource-env-refs" title="Configuring resource-refs and resource-env-refs">Configuring <code class="literal">resource-refs</code> and <code class="literal">resource-env-refs</code></a> discusses how to configure support resources such as <code class="literal">javax.sql.DataSource</code>.</p><p>You can also plug a JTA <code class="literal">javax.transaction.UserTransaction</code> implementation into Jetty so that webapps can look up <code class="literal">java:comp/UserTransaction</code> to obtain a distributed transaction manager: see <a class="link" href="jndi-configuration.html#configuring-xa-transactions" title="Configuring XA Transactions">Configuring XA Transactions</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="defining-jndi-naming-entries"></a>Declaring Resources</h3></div></div></div><p>You must declare the objects you want bound into the Jetty environment so that you can then hook into your webapp via <code class="literal">env-entry</code>, <code class="literal">resource-ref</code> and <code class="literal">resource-env-refs</code> in <code class="literal">web.xml</code>.
You create these bindings by using declarations of the following types:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">org.eclipse.jetty.plus.jndi.EnvEntry</code></span></dt><dd>For <code class="literal">env-entry</code> type of entries</dd><dt><span class="term"><code class="literal">org.eclipse.jetty.plus.jndi.Resource</code></span></dt><dd>For all other type of resources</dd><dt><span class="term"><code class="literal">org.eclipse.jetty.plus.jndi.Transaction</code></span></dt><dd>For a JTA manager</dd><dt><span class="term"><code class="literal">org.eclipse.jetty.plus.jndi.Link</code></span></dt><dd>For the link between a <code class="literal">web.xml</code> resource name and a naming entry</dd></dl></div><p>Declarations of each of these types follow the same general pattern:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;New class="org.eclipse.jetty.plus.jndi.xxxx"&gt;
  &lt;Arg&gt;&lt;!-- scope --&gt;&lt;/Arg&gt;
  &lt;Arg&gt;&lt;!-- name --&gt;&lt;/Arg&gt;
  &lt;Arg&gt;&lt;!-- value --&gt;&lt;/Arg&gt;
&lt;/New&gt;</code></pre><p>You can place these declarations into three different files, depending on your needs and the <a class="link" href="using-jetty-jndi.html#jndi-name-scope" title="Scope of Resource Names">scope</a> of the resources being declared.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="jndi-where-to-declare"></a>Deciding Where to Declare Resources</h3></div></div></div><p>You can define naming resources in three places:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="emphasis"><em>jetty.xml</em></span></span></dt><dd>Naming resources defined in a <code class="literal">jetty.xml</code> file are <a class="link" href="using-jetty-jndi.html#jndi-name-scope" title="Scope of Resource Names">scoped</a> 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 <code class="literal">WEB-INF/jetty-env.xml</code> file.</dd><dt><span class="term">WEB-INF/jetty-env.xml</span></dt><dd>Naming resources in a <code class="literal">WEB-INF/jetty-env.xml</code> file are <a class="link" href="using-jetty-jndi.html#jndi-name-scope" title="Scope of Resource Names">scoped</a> 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.</dd><dt><span class="term">Context xml file</span></dt><dd>Entries in a context xml file should be <a class="link" href="using-jetty-jndi.html#jndi-name-scope" title="Scope of Resource Names">scoped</a> 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 <code class="literal">jetty.xml</code> file, classes associated with the resource must be visible on the container&#8217;s classpath.</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="jndi-name-scope"></a>Scope of Resource Names</h3></div></div></div><p>Naming resources within Jetty belong to one of three different scopes, in increasing order of restrictiveness:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">JVM scope</span></dt><dd><p class="simpara">The name is unique across the JVM instance, and is visible to all application code.
You represent this scope by a <code class="literal">null</code> first parameter to the resource declaration.
For example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
  &lt;Arg&gt;&lt;/Arg&gt;  &lt;!-- empty arg --&gt;
  &lt;Arg&gt;jms/connectionFactory&lt;/Arg&gt;
  &lt;Arg&gt;
    &lt;New class="org.apache.activemq.ActiveMQConnectionFactory"&gt;
       &lt;Arg&gt;vm://localhost?broker.persistent=false&lt;/Arg&gt;
    &lt;/New&gt;
  &lt;/Arg&gt;
&lt;/New&gt;</code></pre></dd><dt><span class="term">Server scope</span></dt><dd><p class="simpara">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:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;Configure id="Server" class="org.eclipse.jetty.Server"&gt;
  &lt;New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
    &lt;Arg&gt;&lt;Ref refid="Server"/&gt;&lt;/Arg&gt;  &lt;!-- reference to Server instance --&gt;
    &lt;Arg&gt;jms/connectionFactory&lt;/Arg&gt;
    &lt;Arg&gt;
      &lt;New class="org.apache.activemq.ActiveMQConnectionFactory"&gt;
        &lt;Arg&gt;vm://localhost?broker.persistent=false&lt;/Arg&gt;
      &lt;/New&gt;
    &lt;/Arg&gt;
  &lt;/New&gt;
&lt;/Configure&gt;</code></pre></dd><dt><span class="term">Webapp scope</span></dt><dd><p class="simpara">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 <code class="literal">WebAppContext</code> instance as the first parameter to the resource declaration.
For example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"&gt;
  &lt;New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
    &lt;Arg&gt;&lt;Ref refid='wac'/&gt;&lt;/Arg&gt; &lt;!-- reference to WebAppContext --&gt;
    &lt;Arg&gt;jms/connectionFactory&lt;/Arg&gt;
    &lt;Arg&gt;
      &lt;New class="org.apache.activemq.ActiveMQConnectionFactory"&gt;
        &lt;Arg&gt;vm://localhost?broker.persistent=false&lt;/Arg&gt;
      &lt;/New&gt;
    &lt;/Arg&gt;
  &lt;/New&gt;
&lt;/Configure&gt;</code></pre></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="binding-objects-into-jetty-jndi"></a>What Can Be Bound as a Resource?</h3></div></div></div><p>You can bind four types of objects into a Jetty JNDI reference:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">An ordinary POJO instance.</li><li class="listitem">A <a class="link" href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Reference.html" target="_top">javax.naming.Reference</a> instance.</li><li class="listitem">An object instance that implements the <a class="link" href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Referenceable.html" target="_top">javax.naming.Referenceable</a> interface.</li><li class="listitem">A link between a name as referenced in <code class="literal">web.xml</code> and as referenced in the Jetty environment.</li></ul></div></div></div><script type="text/javascript">
      SyntaxHighlighter.all()
    </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jndi.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="jndi.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jndi-configuration.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;12.&nbsp;Configuring JNDI&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Configuring JNDI</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
            See an error or something missing?
            <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at
                <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2019-11-05)</i></span></div></p></body></html>