2010-04-14 - Jakarta Taglibs has been retired.

For more information, please explore the Attic.

Jakarta Project: JNDI Tag library (Beta 1)

Version: 1.0

Table of Contents

Overview

A tag library for using the Java Naming and Directory Interface (JNDI).

Requirements

This custom tag library requires a servlet container that supports the JavaServer Pages Specification, version 1.1.

This custom tag library requires the JNDI API. This comes as part of Java 1.3. If you are using a version of Java prior to Java 1.3 you will need to download the JNDI API from Sun and install it in your $JAVA_HOME/jre/lib/ext directory.

Configuration

Follow these steps to configure your web application with this tag library:

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/jndi" prefix="jndi" %>

where "jndi" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

JNDI Tags
useContextCreate a javax.naming.Context object for use after tag close.
listLists the elements in a particular javax.naming.Context
lookupThis looks up a particular object and exports it.
useDirContext Create a javax.naming.directory.DirContext object for use after tag close.
searchSearches a DirContext.
getAttributeExtracts an attribute from a DirContext, a SearchResult, or an Attributes.
forEachAttributeIterates attributes form a DirContext, Attributes, or SearchResult.
 

Tag Reference

useContext Availability: 1.0

This tag creates an instance of a javax.naming.Context based on the values of the attributes providing some of the standard values. In addition to the System properties and the jndi.properties, some standard properties are scanned in the pageContext attributes.

  • note: should this be extended to the servlet init params as well?
  • note: as of right now this does not look into the id and scope to see if the context already exists, so it does not behave entirely like useBean

Tag BodyJSP    
Restrictions

One of the following three attributes must be specified:

  • env
  • envRef
  • url
And one of the following three attributes must be specified: One of the following three attributes must be specified:
  • initialFactory
  • providerUrl
  • url

AttributesNameRequired Runtime Expression Evaluation Availability
 envRef  No   No  1.0
 

This is the name of an attribute that will be searched for that provides additional environment information. This info is subordinate to the info provided by the attributes to this tag.

 env  No   Yes  1.0
 

Same as envRef, except that the value is of type java.util.Hashtable.

 url  No   Yes  1.0
 

If provided, the context created by the other attributes is used to create a context in which the parameter of this attribute is used to preform a lookup(String) operation. The context returned from the lookup will be the context returned by the tag.

 providerUrl  No   Yes  1.0
 

Provides the value of the Context.PROVIDER_URL attribute to the InitialContext environment Hashtable.

 initialFactory  No   Yes  1.0
 

Provides the value of the Context.INITIAL_CONTEXT_FACTORY attribute to the InitialContext environment Hashtable.

 dnsUrl  No   Yes  1.0
 

Provides the value of the Context.DNS_URL attribute to the InitialContext environment Hashtable.

 authoritative  No   Yes  1.0
 

Provides the value of the Context.AUTHORITATIVE attribute to the InitialContext environment Hashtable.

 batchsize  No   Yes  1.0
 

Provides the value of the Context.BATCHSIZE attribute to the InitialContext environment Hashtable.

 objectFactories  No   Yes  1.0
 

Provides the value of the Context.OBJECT_FACTORIES attribute to the InitialContext environment Hashtable.

 stateFactories  No   Yes  1.0
 

Provides the value of the Context.STATE_FACTORIES attribute to the InitialContext environment Hashtable.

 urlPkgPrefixes  No   Yes  1.0
 

Provides the value of the Context.URL_PKG_PREFIXES attribute to the InitialContext environment Hashtable.

 id  Yes   No  1.0
 

The name that the context is to be exported as. (A potential future relaxation may make this optional, but it will only be available to body content enclosed that asks for an implicit context)

 scope  No   No  1.0
 

The scope the object is to be exported as. Default is 'page'. Follows the JSP spec conventions.

VariablesNone
ExamplesNone
list Availability: 1.0

This tag iterates through the list returned by Context.list() and the body content is evaluated for each iteration.

Tag BodyJSP    
Restrictions

One of the following two attributes must be specified:

  • context
  • contextRef

AttributesNameRequired Runtime Expression Evaluation Availability
 contextRef  No   Yes  1.0
 

Attribute name that will be searched for to provide the context.

 context  No   Yes  1.0
 

A literal instance of type javax.naming.Context to be used.

 nameId  No   Yes  1.0
 

The attribute name of the name listing to be exported

 nameScope  No   Yes  1.0
 

The scope that the name object will be exported to (page is the default).

 classId  No   Yes  1.0
 

The attribute name of the class name to be exported.

 classScope  No   Yes  1.0
 

The scope that the class name will be exported to (page is the default).

 objId  No   Yes  1.0
 

The attribute name of the bound object listing to be exported.

 objScope  No   Yes  1.0
 

The scope that the bound object will be exported to (page is the default).

 name  No   Yes  1.0
 

The name to preform the list against.

 nameObject  No   Yes  1.0
 

Like name, a literal javax.naming.Name object to use to list against. If both this and name are specified and the value is not null, this attribute is the one used.

 bindings  No   Yes  1.0
 

Whether or not bound objects are returned, true or false.

VariablesNone
ExamplesNone
lookup Availability: 1.0

Lookups and exports a particular entry in a javax.naming.Context.

Tag BodyJSP    
Restrictions

One of the following two attributes must be specified:

  • context
  • contextRef

AttributesNameRequired Runtime Expression Evaluation Availability
 contextRef  No   Yes  1.0
 

Attribute name that will be searched for to provide the context.

 context  No   Yes  1.0
 

A literal instance of type javax.naming.Context to be used.

 id  Yes   No  1.0
 

Attribute name of the object to be exported.

 scope  No   No  1.0
 

The scope the object is to be exported as. Default is 'page'. Follows the JSP spec conventions.

 name  No   Yes  1.0
 

The name to preform the lookup against.

 nameObject  No   Yes  1.0
 

Like name, a literal javax.naming.Name object to use to lookup. If both this and name are specified and the value is not null, this attribute is the one used.

 type  No   No  1.0
 

The class to cast the looked up object to. Right now failure to cast results in a null return. The default is java.lang.Object. This also determines the type of the exposed scripting variable. [Adding an attribute failure with string values null, exception, or classcast to return null, throw a JSPExceptionm or to re-throw the class-cast is a thought.]

VariablesNone
ExamplesNone
useDirContext Availability: 1.0

This behaves exactly like useContext except that the object exported will be of type javax.naming.directory.DirContext and the InitialDirContext will be used to generate the contexts.

Tag BodyJSP    
Restrictions

One of the following three attributes must be specified:

  • env
  • envRef
  • url
And one of the following three attributes must be specified: One of the following three attributes must be specified:
  • initialFactory
  • providerUrl
  • url

AttributesNameRequired Runtime Expression Evaluation Availability
 envRef  No   No  1.0
 

This is the name of an attribute that will be searched for that provides additional environment information. This info is subordinate to the info provided by the attributes to this tag.

 env  No   Yes  1.0
 

Same as envRef, except that the value is of type java.util.Hashtable.

 url  No   Yes  1.0
 

If provided, the context created by the other attributes is used to create a context in which the parameter of this attribute is used to preform a lookup(String) operation. The context returned from the lookup will be the context returned by the tag.

 providerUrl  No   Yes  1.0
 

Provides the value of the Context.PROVIDER_URL attribute to the InitialContext environment Hashtable.

 initialFactory  No   Yes  1.0
 

Provides the value of the Context.INITIAL_CONTEXT_FACTORY attribute to the InitialContext environment Hashtable.

 dnsUrl  No   Yes  1.0
 

Provides the value of the Context.DNS_URL attribute to the InitialContext environment Hashtable.

 authoritative  No   Yes  1.0
 

Provides the value of the Context.AUTHORITATIVE attribute to the InitialContext environment Hashtable.

 batchsize  No   Yes  1.0
 

Provides the value of the Context.BATCHSIZE attribute to the InitialContext environment Hashtable.

 objectFactories  No   Yes  1.0
 

Provides the value of the Context.OBJECT_FACTORIES attribute to the InitialContext environment Hashtable.

 stateFactories  No   Yes  1.0
 

Provides the value of the Context.STATE_FACTORIES attribute to the InitialContext environment Hashtable.

 urlPkgPrefixes  No   Yes  1.0
 

Provides the value of the Context.URL_PKG_PREFIXES attribute to the InitialContext environment Hashtable.

 id  Yes   No  1.0
 

The name that the context is to be exported as. (A potential future relaxation may make this optional, but it will only be available to body content enclosed that asks for an implicit context)

 scope  No   No  1.0
 

The scope the object is to be exported as. Default is 'page'. Follows the JSP spec conventions.

VariablesNone
ExamplesNone
search Availability: 1.0

Performs a search against a DirContext according to the semantics of the search(Name name, String filter, SearchControls cons) in javax.naming.directory.DirContext.

Tag BodyJSP    
Restrictions

One of the following two attributes must be specified:

  • context
  • contextRef

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

Attribute name of the SearchResult to be exported.

 scope  No   No  1.0
 

The scope the object is to be exported as. Default is 'page'. Follows the JSP spec conventions.

 contextRef  No   Yes  1.0
 

Attribute name that will be searched for to provide the context.

 context  No   Yes  1.0
 

A literal instance of type javax.naming.Context to be used.

 name  No   Yes  1.0
 

The name to preform the lookup against.

 nameObject  No   Yes  1.0
 

Like name, a literal javax.naming.Name object to use to lookup. If both this and name are specified and the value is not null, this attribute is the one used.

 filter  Yes   Yes  1.0
 

The LDAP-style search filter to use.

 countLimit  No   Yes  1.0
 

The maximum number of entries to return. Default is 0 which _should_ mean return all entries found (but behavior has been observerved in some provider/server combinations to mean none).

 derefLink  No   Yes  1.0
 

Determines whether links will be dereferenced during the search. Set to true or false, default is false.

 attributes  No   Yes  1.0
 

A (generally) comma seperated list of attributes to return in the search results. Default is null which means return all.

 attributeSeparator  No   Yes  1.0
 

If comma seperated attributes won't do, provides an alternate delimiter string for the attributes attribute. Default is ",".

 bindings  No   Yes  1.0
 

Whether or not to return bound objects. Set to true or false, default is false.

 searchScope  No   Yes  1.0
 

What scope the search is to be preformed against. One of subtree, subtree_scope, onelevel, onelevel_scope, object, object_scope. (The variants are treated as the the _scope variants).

 timeLimit  No   Yes  1.0
 

The time limit in ms to wait. 0 means wait indefinatly.

VariablesNone
ExamplesNone
getAttribute Availability: 1.0

This is a flexible tag to get an attribute. The specified object can be a DirContext, SearchResult, Attributes, or an Attribute. If the object is a DirContext an Attributes object is retrieved with just the requested attribute, and then further processed. If it is a SearchResult then the return of getAttributes is processed further. For any Attributes object passed in explicitly or derived the get(attribute) method is executed and stored as the attribute. The contents of the attribute are processed in one of three ways depending on the value of the multivalue tag attribute. If the value is 'one' then the value returned by Attribute.get() is written to the output stream and the body is skipped. For 'separator' then the body of the tag servers as a separator for the attribute values in the event of multivalue attributes, but it is skipped in the event of a singly valued or non-existant attribute, and the value of the attribute is explicitly written to the appropriate output stream. And for the case of 'iterate' the the contents of the body are iterated over for each value of the attribute, whether singly valued or multi-valued (and skipped for a non-existant attribute). In all cases the attribute is exported to the id and scope if provided at the beginning of the tag, so it is available both within the tag and after it's execution.

Tag BodyJSP    
Restrictions

NONE

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   No  1.0
 

Page Context attribute name of the actual Attribute value to be exported. For multivalued attributes where the multivalue mode is 'separator' no attribute is exported, while for the value of 'iterator' it is the current value inside the body content or the final value outside the tag. For 'one' it is the only value of the attribute.

 scope  No   No  1.0
 

The scope the object is to be exported as. Default is 'page'. Follows the JSP spec conventions.

 ref  No   Yes  1.0
 

A refrence to a PageContext attribute to be searched for to use as the object to preform attribute operations against.

 object  No   Yes  1.0
 

A literal instance of an object to have the attribute operations applied against. An invalid object type will result in the body content being skipped an no output being written to the output stream.

 attribute  No   No  1.0
 

The name of the attribute to use for objects of type DirContext, SearchResult and Attributes. Ignored for object of type Attribute.

 multivalue  No   Yes  1.0
 

One of 'one', 'separator', or 'iterate'. Se tag description for details.

VariablesNone
ExamplesNone
forEachAttribute Availability: 1.0

This tag allows you to iterate through all of the attribute names returned for a DirContext, SearchResult, or an Attributes object.

Tag BodyJSP    
Restrictions

NONE

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

Page Context attribute name of the actual Attribute to be exported. This is the name exposed within the tag Body and after. It is the Attribute object and not the value of the attribute.

 scope  No   No  1.0
 

The scope the object is to be exported as. Default is 'page'. Follows the JSP spec conventions.

 ref  No   Yes  1.0
 

A refrence to a PageContext attribute to be searched for to use as the object to preform attribute operations against. Valid types are DirContext, SearchResults, and Attributes.

 object  No   Yes  1.0
 

A literal instance of an object to have the attribute operations applied against. An invalid object type will result in the body content being skipped an no output being written to the output stream. Valid types are DirContext, SearchResults, and Attributes.

VariablesNone
ExamplesNone

Examples

See the example application jndi-examples.war for examples of the usage of the tags from this custom tag library.

Java Docs

Java programmers can view the java class documentation for this tag library as javadocs.

Revision History

Review the complete revision history of this tag library.