new html documentation for the jndi taglib

Torgeir Veimo Wed, 05 Sep 2001 03:43:27 -0700

I submitted this some time ago, but it was lost I think. Here it is
again. 


-- 
- Torgeir

Title: jndi taglib Documentation

The jndi Tag Library

1. Introduction

The jndi custom tag library contains tags that can be used to perform operations against a jndi context, including but not limited to LDAP servers, DNS servers etc., with appropriate jndi providers.

2. Prerequisite Software

This custom tag library requires

a JSP 1.1 compliant servlet container (of course)

3. Configuration Information

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

Copy the tag library descriptor file (jndi/jndi.tld) to the /WEB-INF subdirectory of your web application.
Copy the tag library JAR file (jndi/jndi.jar) to the /WEB-INF/lib subdirectory of your web application.
Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml like this:

    <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="x"%>

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

4. Tag Documentation

This custom tag library includes several tags, with the following characteristics:

4.1 The "useContext" tag

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)

Example:

<jndi:useContext
    id='ctx' 
    scope='session' 
    initialFactory='javax.sun.com.LdapInitialContext' 
    providerUrl='ldap://192.168.75.153:389'>
</jndi:useContext>

Attribute	Description	Required
envRef	This is the name of an attribute that will be searched for that provides additional environment information. This info is subordnate to the info provided by the attributes to this tag	No
env	Same as envRef, except that the value is the hashtable.	No
url	If provided, the context created by the other attributges 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.	This or one of providerUrl or intialFactory required.
providerUrl	Provides the value of the Context.PROVIDER_URL attribute to the InitialContext environment Hashtable.	This one or one of url or dnsUrl required.
initialFactory	Provides the value of the Context.INITIAL_CONTEXT_FACTORY attribute to the InitialContext environment Hashtable	This one or one of url or dnsUrl required.
dnsUrl	Provides the value of the Context.DNS_URL attribute to the InitialContext environment Hashtable.	No
authoritatibe	Provides the value of the Context.AUTHORITATIVE attribute to the InitialContext environment Hashtable.	No
batchsize	Provides the value of the Context.BATCHSIZE attribute to the InitialContext environment Hashtable.	No
objectFactories	Provides the value of the Context.OBJECT_FACTORIES attribute to the InitialContext environment Hashtable.	No
stateFactories	Provides the value of the Context.STATE_FACTORIES attribute to the InitialContext environment Hashtable.	No
urlPkgPrefixes	Provides the value of the Context.URL_PKG_PREFIXES attribute to the InitialContext environment Hashtable.	No
id	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.)	Yes
scope	The scope the object is to be exported as. (default: page) Follows the JSP spec conventions.	No

4.2 The "useDirContext" tag

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.

4.3 The "list" tag

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

Attribute	Description	Required
contextRef	Attribute name that will be searched for to provide the context.	This or context required.
context	A literal instance of a context to be used. Runtime of type javax.naming.Context	This or contextRef required.
name	The name to preform the list against.	No
nameObj	Like name, a literal 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. Runtime of type javax.naming.Name.	No
bindings	Specifies wether or not bound objects are returned.	No
nameId	The attribute name of the name listing to be exported.	No
nameScope	The scope that the name object will be exported to (default: page).	No
classId	The attribute name of the class name to be exported.	No
classScope	The scope that the class name will be exported to (default: page).	No
objId	The attribute name of the bound object listing to be exported.	No
objScope	The scope that the bound object will be exported to (default: page).	No

4.4 The "lookup" tag

This looks up a particular object and exports it.

Example:

<jndi:lookup 
    contextRef='ctx' 
    name='<%=(String)session.getAttribute("dn")%>' 
    id='profile' />

Attribute	Description	Required
contextRef	Attribute name that will be searched for to provide the context.	This or context required.
context	A literal instance of a context to be used.	This or contextRef required.
id	Attribute name of the object to be exported.	No
scope	The scope the object is to be exported as. (Default: page). Follows the JSP spec conventions	No
name	The name to preform the lookup against.	No
nameObj	Like name, a literal 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. Runtime of type javax.naming.Name.	No
type	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.]	No

4.5 The "search" tag

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

Example:

<jndi:search 
    contextRef='ctx' 
    id='profile' 
    name='dc=arius,dc=com' 
    filter='cn=Mark*' 
    searchScope='SUBTREE_SCOPE' 
    bindings='false' 
    timeLimit='5000' 
    attributes='*' />

Attribute	Description	Required
id	Attribute name of the SearchResult to be exported.	Yes
scope	The scope the object is to be exported as. (Default: page). Follows the JSP spec conventions	No
contextRef	Attribute name that will be searched for to provide the context. Runtime of type javax.naming.Context.	This or context required .
context	A literal instance of a context to be used.	This or contextRef required .
name	The name to perform the search against .	No
nameObj	Like name, a literal 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.	No
filter	The LDAP-style search filter to use.	Yes
countLimit	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).	No
derefLink	Determines whether links will be dereferenced during the search. Default is false.	No
attributes	A (generally) comma seperated list of attributes to return in the search results. Default is null which means return all.	No
attributesSeparator	If comma seperated attributes won't do, provides an alternate delimiter string for the attributes attribute. Default is ",".	No
bindings	Wether or not to return bound objects. Default is false.	No
searchScope	What scope the search is to be preformed against. One of subtree, subtree_scope, onelevel, onelevel_scope, object, object_scope. (The <foo> variants are treated as the the <foo>_scope variants).	No
timeLimit	The time limit in ms to wait. 0 means wait indefinatly. Runtime of type int.	No

4.6 The "getAttribute" tag

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 futhter 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 singlely valued or non-existant attribute, and the value of the attribute is explicitly written to the appropriate output stream.
And for the case of 'itterate' the the contents of the body are itterated over for each value of the attribute, whether singlely valued of 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.

Example:

<jndi:getAttribute ref='profile' attribute='cn'/>

Example:

<table border="true">
  <th>name</th><th>value</th>

  <jndi:forEachAttribute ref='profile' id='attr'>

    <jndi:getAttribute ref='attr' id='val' scope='page' multivalue='itterate'/>

    <tr>
      <td><jsp:getProperty name='attr' property='ID'/></td>
      <td><%=val%></td>
    </tr>

  </jndi:forEachAttribute>
</table>

Attribute	Description	Required
id	Page Context attribute name of the actual Attribute value to be exported. For multivalued attributes where the multivalue mode is 'separator' no attribue is exported, while for the value of 'itterator' 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.	No
scope	The scope the object is to be exported as. (Default: page). Follows the JSP spec conventions	No
ref	A refrence to a PageContext attribute to be searched for to use as the object to preform attribute operations against.	No
object	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. Runtime of type java.lang.Object.	No
attribute	The name of the attribute to use for objects of type DirContext, SearchResult and Attributes. Ignored for object of type Attribute.	No
multivalue	One of 'one', 'separator', or 'itterate'. Se tag description for details.	No

4.7 The "forEachAttribute" tag

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

Example: se above.

Attribute	Description	Required
id	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.	No
scope	The scope the object is to be exported as. Default is 'page'. Follows the JSP spec conventions	No
ref	A refrence to a PageContext attribute to be searched for to use as the object to perform attribute operations against. Valid types are DirContext, SearchResult and Attributes.	No
object	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.	No