A tag library for using the Java Naming and Directory Interface (JNDI).
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.
Follow these steps to configure your web application with this tag library:
<taglib> <taglib-uri>http://jakarta.apache.org/taglibs/jndi</taglib-uri> <taglib-location>/WEB-INF/jndi.tld</taglib-location> </taglib>
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.
useContext | Create a javax.naming.Context object for use after tag close. |
list | Lists the elements in a particular javax.naming.Context |
lookup | This looks up a particular object and exports it. |
useDirContext | Create a javax.naming.directory.DirContext object for use after tag close. |
search | Searches a DirContext. |
getAttribute | Extracts an attribute from a DirContext, a SearchResult, or an Attributes. |
forEachAttribute | Iterates attributes form a DirContext, Attributes, or SearchResult. |
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.
|
|||||
Tag Body | JSP | ||||
Restrictions |
One of the following three attributes must be specified:
|
||||
Attributes | Name | Required | 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. |
|||||
Variables | None | ||||
Examples | None |
list | Availability: 1.0 | ||||
This tag iterates through the list returned by Context.list() and the body content is evaluated for each iteration. |
|||||
Tag Body | JSP | ||||
Restrictions |
One of the following two attributes must be specified:
|
||||
Attributes | Name | Required | 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. |
|||||
Variables | None | ||||
Examples | None |
lookup | Availability: 1.0 | ||||
Lookups and exports a particular entry in a javax.naming.Context. |
|||||
Tag Body | JSP | ||||
Restrictions |
One of the following two attributes must be specified:
|
||||
Attributes | Name | Required | 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.] |
|||||
Variables | None | ||||
Examples | None |
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 Body | JSP | ||||
Restrictions |
One of the following three attributes must be specified:
|
||||
Attributes | Name | Required | 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. |
|||||
Variables | None | ||||
Examples | None |
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 Body | JSP | ||||
Restrictions |
One of the following two attributes must be specified:
|
||||
Attributes | Name | Required | 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. |
|||||
Variables | None | ||||
Examples | None |
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 Body | JSP | ||||
Restrictions |
NONE |
||||
Attributes | Name | Required | 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. |
|||||
Variables | None | ||||
Examples | None |
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 Body | JSP | ||||
Restrictions |
NONE |
||||
Attributes | Name | Required | 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. |
|||||
Variables | None | ||||
Examples | None |
See the example application jndi-examples.war for examples of the usage of the tags from this custom tag library.
Java programmers can view the java class documentation for this tag library as javadocs.
Review the complete revision history of this tag library.