|
| |
| Sun ONE Directory Server Resource Kit 5.2 Tools Reference | |
Chapter 33
Tag Library ReferenceThis chapter provides a detailed reference of the Lightweight Directory Access Protocol (LDAP) Tag Libraries, the Utilities Tag Libraries and the JavaServer Pages™ Standard Tag Library (JSPTL) included with the Sun™ ONE Directory Server Resource Kit (DSRK). This information can help you customize the phone book application (called LookMeUp) or develop other web-based LDAP clients. It contains the following sections:
OverviewJavaServer Pages (JSP) allow developers to dynamically generate HTML, XML or other types of web pages. The technology allows Java code to be embedded into static content. The code will most probably include a set of pre-defined actions (standardized in the JSP specification) to handle the core functionality common to most JSP, including database access, and XML processing. JSP also supports the development of reusable modules to handle other functions; these are referred to as custom actions. All actions are invoked by tags defined using an XML syntax (a start tag, an end tag, and possibly a body). Code Example 33-1 is a simple HTML page using a pre-defined action (include) surrounded by a tag. (jsp: is the start tag and, because there is no body, /> is the end tag.)
Code Example 33-1 Simple Action and Tag
<HTML>
<BODY>
Going to include hello.jsp...<BR>
<jsp:include page="hello.jsp"/>
</BODY>
</HTML>
A tag library is a collection of tags (and their corresponding actions). Tags are grouped in libraries according to their function. The LookMeUp application relies on the LDAP Tag Library to perform LDAP queries, the Utilities Tag Library to form said queries and process responses, and the JSP Standard Tag Library, Early Access Release 1.2, for iterations and conditional operations.
LDAP Tag LibraryThe LDAP Tag Library (LDAPTL) implements the interface between a JSP-enabled web server and LDAP v3 directories. It sits in top of the JSP Standard Tag Library which performs LDAP operations on the directory server. The LDAPTL represents LDAP attributes, entries, and operations, as well as the results of operations. The implementation of these tags uses the Sun ONE LDAP SDK for Java to interact with any directory server. The tag library definition is contained in the ldaptl.tld found in the DSRK_base/jdgw/phonebook-app/WEB-INF directory.
Summary
The following material is relevant when using the LDAPTL.
- All tags for performing LDAP operations have host and port attributes to specify the directory server. Both attributes are optional and, when omitted, LDAP operations will use the standard port 389 on the local host.
- The user and password attributes are used to bind to the directory server and are also optional. If not provided, an anonymous bind will be performed.
- The <ldap:add> and <ldap:modify> tags are the only ones in the library to contain other tags. The add operation defines the new entry as a set of associated <ldap:attr> tags that may be either contained in the <ldap:add> tag or referenced in a variable. In a similar manner, the <ldap:modify> tag may either contain or reference <ldap:mod> tags to define individual modifications.
- The LDAP operation tags will return LDAP exceptions in the variable specified in their response attribute. Check this variable to determine if an error has occurred while processing the operation. Explanations for errors may be displayed by accessing the text in the ldaperrors.properties file through a <util:prop> tag.
<ldap:add>Add a set of attribute-value pairs as a new entry in the directory.
DESCRIPTION
The <ldap:add> element either references or contains a set of attribute-value pairs that will become the contents of the new entry. Attributes and their values are defined by the <ldap:attr> element. You must define all required attributes for the new entry, including any naming attributes and objectclass attributes. If schema checking is enabled in your directory, the other attributes and their values must conform to any defined object class.
SYNTAX
<ldap:add [ host="hostname" port="port" ]
user="bindDN" passwd="password"
dn="newDN" attrs="varName" [ response="varName" ]/><ldap:add [ host="hostname" port="port" ]
user="bindDN" passwd="password"
dn="newDN" [ response="varName" ]>
<ldap:attr ... /> ...
</ldap:add>ATTRIBUTES
EXAMPLES
- The following example shows attribute definitions referenced by the attrs attribute of the <ldap:add> element:
<ldap:attr var="attrs" scope="request"
name="objectclass" value="top"/>
<ldap:attr var="attrs" scope="request"
name="objectclass" value="organizationalunit"/>
<ldap:attr var="attrs" scope="request"
name="ou" value="People"/>
<ldap:attr var="attrs" scope="request"
name="description" value="Employee branch"/><ldap:add host="phonebook.example.com"
user="cn=Directory Manager" passwd="password"
dn="ou=People,dc=example,dc=com"
attrs="$request:attrs" response="addError"/>- The second example creates an identical entry, but the attributes are defined within the <ldap:add> tag:
<ldap:add host="phonebook.example.com"
user="cn=Directory Manager" passwd="password"
dn="ou=People,dc=example,dc=com" response="addError">
<ldap:attr name="objectclass" value="top"/>
<ldap:attr name="objectclass" value="organizationalunit"/>
<ldap:attr name="ou" value="People"/>
<ldap:attr name="description" value="Employee branch"/>
</ldap:add>SEE ALSO
<ldap:attr>Defines an attribute-value pair for the <ldap:add> element or retrieves an attribute-value pair from an <ldap:search> result.
DESCRIPTION
The <ldap:attr> element represents an LDAP attribute, its name and its values. It is used with the <ldap:add> element to define the attributes of a new entry. It also simplifies the access to attributes and their values in <ldap:search> results.
This element may appear inside the <ldap:add> element where it defines the name and value of a new attribute. It may also be referenced from outside the <ldap:add> element, in which case it must also name a variable and optional scope where the definition is stored. See <ldap:search> for more information.
When processing search results, the <ldap:attr> element extracts the value or values of the named attribute for display or storage in a variable. Use the entry attribute to name the variable containing search results, either inside or outside of an <ldap:search> element.
SYNTAX
For defining an attribute:
<ldap:attr name="attrName" value="valueString"
[ var="varName" scope="scopeName" ]/>For displaying an attribute:
<ldap:attr name="attrName" entry="varName"
[ default="valueString" op="value|values" ]
[ var="varName" scope="scopeName" ]/>ATTRIBUTES
SEE ALSO
<ldap:add> and its examples, <ldap:search> and its examples.
<ldap:delete>Delete an entry from the directory.
DESCRIPTION
Evaluating this tag will perform the LDAP delete operation on the given DN. Check the variable given by the response attribute to determine if the operation was successful.
SYNTAX
<ldap:delete [ host="hostname" port="port" ]
user="bindDN" passwd="password"
dn="oldDN" response="varName"/>ATTRIBUTES
EXAMPLE
<ldap:delete host="phonebook.example.com"
user="cn=Directory Manager" passwd="password"
dn="uid=007,ou=People,dc=example,dc=com"
response="deleteError"/>
<ldap:dn>Normalize or extract distinguished name (DN) components for display or storage.
DESCRIPTION
This element extracts the comma-separated components of a distinguished name (DN), according to the op attribute. Specify a variable name and optional scope to store the component string or array of strings in a variable. If none is specified, the element will display component in the output. If no operation is specified, the element will normalize the DN string. The DN is specified either as the value attribute or as the tag’s contents.
SYNTAX
<ldap:dn value="DNstring" [ op="leaf|leaf-value|parts|value-parts" ]
[ var="varName" scope="scopeName" ]/><ldap:dn [ op="leaf|leaf-value|parts|value-parts" ]
[ var="varName" scope="scopeName" ]>
DNstring
</ldap:dn>ATTRIBUTES
EXAMPLES
INPUT DN STRING: 'cn=Babs Jensen,ou=People,dc=example,dc=com’
Normalize =
<ldap:dn>cn=Babs Jensen,ou=People,dc=example,dc=com</ldap:dn><br>Leaf Value =
<ldap:dn value="cn=Babs Jensen,ou=People,dc=example,dc=com"
op="leaf-value"/><br>Leaf =
<ldap:dn value="cn=Babs Jensen,ou=People,dc=example,dc=com"
op="leaf"/><br><ldap:dn value="cn=Babs Jensen,ou=People,dc=example,dc=com"
op="value-parts" var="values"/>
<jx:forEach var="val" items="$valuess">
Value Part: <jx:expr value="$val"/><br>
</jx:forEach><ldap:dn value="cn=Babs Jensen,ou=People,dc=example,dc=com"
op="parts" var="parts"/>
<jx:forEach var="part" items="$parts">
Part: <jx:expr value="$part"/><br>
</jx:forEach>
<ldap:mod>Define a modification to a single attribute. One or more instances of this element are either contained in or referenced by the <ldap:modify> element.
DESCRIPTION
Each instance of this element defines a modification to perform on a single attribute of an entry. A modification may perform one of the following changes:
Use multiple instances to create a set of modifications for the <ldap:modify> tag to perform. The <ldap:modify> tag must either contain <ldap:mod> elements or reference the variable named by the var and scope attributes.
SYNTAX
<ldap:mod op="add|delete|replace"
name="attrName" [ value="valueString" ]
[ var="varName" scope="scopeName" ]>ATTRIBUTES
SEE ALSO
<ldap:modify> and its examples.
<ldap:modify>Perform a set of modifications on attributes of a single entry.
DESCRIPTION
The <ldap:modify> element either references or contains a set of attribute modifications that will be performed on the target entry. Attributes may be added, replaced, or deleted, as defined in the <ldap:mod> element.
You must provide the authentication for a bind DN that has write permission on the target DN. If schema checking is enabled in your directory, new attributes or new values must conform to the object class of the target DN. Write permission or schema errors will cause the operation to fail, which you can detect in the variable named by the response attribute.
SYNTAX
<ldap:modify [ host="hostname" port="port" ]
user="bindDN" passwd="password"
dn="targetDN" mods="varName" response="varName"/><ldap:modify [ host="hostname" port="port" ]
user="bindDN" passwd="password"
dn="targetDN" response="varName">
<ldap:mod ... /> ...
</ldap:modify><ldap:modify >
ATTRIBUTES
EXAMPLES
- The following example shows individual modifications that are referenced by the mods attribute of the <ldap:modify> element:
<ldap:mod var="mods" scope="request"
op="replace" name="postalAddress"
value="123 Main Street"/><ldap:mod var="mods" scope="request"
op="replace" name="facsimileTelephoneNumber"
value="408 555 1234"/><ldap:mod var="mods" scope="request"
op="delete" name="telephoneNumber"
value="407 555 9876"/><ldap:mod var="mods" scope="request"
op="add" name="telephoneNumber"
value="408 555 6789"/><ldap:modify host="phonebook.siroe.com"
user="cn=Directory Manager" passwd="password"
dn="uid=6,ou=People,dc=siroe,dc=com">
mods="$request:mods" response="modifyError/>- The second example performs the same operation, but the modifications are defined within the <ldap:add> tag. Note that the default modification is to replace an attribute value, so the op attribute may be omitted:
<ldap:modify host="phonebook.siroe.com"
user="cn=Directory Manager" passwd="password"
dn="uid=6,ou=People,dc=siroe,dc=com"
response="modifyError">
<ldap:mod name="postalAddress" value="123 Main Street"/>
<ldap:mod name="facsimileTelephoneNumber" value="408 555 1234"/>
<ldap:mod op="delete" name="telephoneNumber"
value="407 555 9876"/>
<ldap:mod op="add" name="telephoneNumber"
value="408 555 6789"/>
</ldap:modify>SEE ALSO
<ldap:search>Performs an LDAP search and returns the set of resulting entries. This element is an iterator that will evaluate its contents for every entry in the search results.
DESCRIPTION
The <ldap:search> element searches the directory according to the specified base, search scope, and filter. There are two ways to process the search results:
- Use other elements inside this tag to process each entry. The tag is an iterator and will evaluate its contents for each of the entries in the results.
- Specify a variable name and optional scope for storing the search results. Then access this variable from other elements to process the entries it contains.
In both cases, the results may be accessed as variables or using the <ldap:dn> and <ldap:attr> tags to extract information.
SYNTAX
<ldap:search [ host="hostname" port="port" ]
[ user="bindDN" passwd="password" ]
base="baseDN" [ srchScope="base|one|sub" ]
[ filter="filterString" attrs="attrList" ]
[ maxEntries="number" controls="beanName" ]
[ entry="iterName" response="varName" ]>
<...> ...
</ldap:search><ldap:search [ host="hostname" port="port" ]
[ user="bindDN" passwd="password" ]
base="baseDN" [ srchScope="base|one|sub" ]
[ filter="filterString" attrs="attrList" ]
[ maxEntries="number" controls="beanName" ]
var="varName" [ scope="varScope" response="varName" ]/>ATTRIBUTES
host="hostname"
Specify the hostname of the directory server. When this attribute is omitted, the default is localhost.
port="port"
Specify the port number of the directory server on the given host. When this attribute is omitted, the default port is 389.
user="bindDN"
Specify a bind DN for accessing your directory. If the bind DN and its password are omitted, the operation will use anonymous binding. The bind DN determines what entries and attributes will appear in the search results, according to the DN’s access permissions.
passwd="password"
Specify the password for the bind DN. CAUTION: the password is visible in this tag, so the JSP file should be read-protected.
base="baseDN"
Specify the base DN for the search operation.
srchScope="scope"
Specify the scope of a search with one of the following values:
filter="filterString"
Specify an LDAP filter string for the search. When omitted, the default filter is (objectclass=*), which returns all entries in the search scope.
attrs="attrList"
Specify the list of attributes that will be returned with their values for each entry in the search results. Attribute names in the list are separated by vertical bars (|).
maxEntries="number"
Specify the maximum number of entries to return. A search that yields more than this limit will generate an exception. Regardless of the value specified here, if at all, a search will never return more entries than the number allowed by the directory server’s nsslapd-sizelimit attribute whose default is 2,000 entries. See “nsslapd-sizelimit (Size Limit)” in the Sun ONE Directory Server Reference Manual.
entry="iterName"
Give the name of the loop variable used to store each entry in turn when iterating through the search results. When this attribute is omitted, the default name of the loop variable is entry.
var="varName"
Give the name of the variable where the search results will be stored. This variable name and scope may be omitted when search results are processed in the element contents.
scope="varScope"
Give the scope of the variable where the search results will be stored. When omitted, the default scope is PAGE.
controls="beanName"
Give the name of a variable containing the LDAP controls for this search. See <ldap:sortControl> and <ldap:vlControl>.
response="varName"
Give the name of a variable (in the PAGE scope) for storing any error response. When omitted, the default name is response. If an LDAP error occurs during the operation, this variable will be set to the corresponding LDAPException Bean.
EXAMPLES
- This first example shows a simple search that displays the DN and several attributes for each result. The comments in the code explain the different ways to access attribute information in the results.
<ldap:search host="phonebook.example.com"
user="cn=Directory Manager" passwd="password"
base="ou=People,dc=example,dc=com" srchScope="sub"
filter="(surname=a*)"
attrs="dn|cn|employeeNumber|mail|telephonenumber"><!-- "entry" is the default iterator variable for results -->
Entry: <jx:expr value="$entry"/><br><!-- The DN can be read from the entry structure -->
DN: <jx:expr value="$entry.dn"/><br><!-- The pageContext Bean contains all attribute values -->
cn: <%= ((EntryBean) pageContext.
getAttribute("entry")).getAttr("cn").getValue() %><br><!-- ldap:attr will display the value of the attribute -->
ID: <ldap:attr entry="$entry" name="employeeNumber"/><br><!-- ldap:attr can also store the value of the attribute, for
use in other expressions -->
<ldap:attr entry="$entry" name="mail" var="address" default=""/>
mail: <jx:if test="$address != ’’">
<A HREF=mailto:<jx:expr value="$address"/>
><jx:expr value="$address"/></A>
</jx:if><br><!-- For multivalued attributes, use ldap:attr to retrieve all
values, then iterate -->
<ldap:attr entry="$entry" name="telephonenumber" op="values"
var="values" scope="sess"/>
<jx:forEach var="val" items="$session:values">
telephonenumber: <jx:expr value="$val"/>
</jx:forEach><p></ldap:search>
- The next example performs an anonymous search and retrieves all attributes of the matching entries. It uses iterators inside the <ldap:search> element to display them all in the search results.
<ldap:search host="phonebook.example.com"
base="ou=People,dc=example,dc=com" srchScope="sub"
filter="(surname=b*)" var="results">Entry: <jx:expr value="$entry"/><br>
DN: <jx:expr value="$entry.dn"/><br>
Number of attributes:
<jx:expr value="$entry.size" default="NULL"/><P><table border="0" cellpadding="0" cellspacing="2">
<jx:forEach var="oneAttr" items=$entry><tr><td valign="top" align="right" nowrap>
<jx:expr value="$oneAttr.name">
</td><td valign="top">
<jx:forEach var="oneVal" items="$oneAttr">
<jx:expr value="$oneVal"><br>
</jx:forEach>
</td></tr></jx:forEach>
</table>
</ldap:search><P>Number of entries returned:
<jx:expr value="$results.size" default="NULL"/><br><br>- The following example stores search results in a variable and accesses them outside of the <ldap:search> element. It also shows all information that is available for each attribute retrieved in a search. The search itself returns all configuration attributes under the configuration root entry.
<ldap:search host="phonebook.example.com"
user="cn=Directory Manager" passwd="password"
base="o=Root" srchScope="one"
var="result"/><util:logScopes/>
<jx:forEach var="entry" items="$result">
<!-- Search scope one should return only a single entry -->
Entry: <jx:expr value="$entry"/><br>
DN: <jx:expr value="$entry.dn""/><br><jx:forEach var="oneAttr" items="$entry">
Name=<jx:expr value="$oneAttr.name"/><br>
<jx:forEach var="oneVal" items="$oneAttr">
Value=<jx:expr value="$oneVal"/><br>
</jx:forEach>
Single.Value=<jx:expr value="$attr.value"
default="NULL"/><br>
Size=<jx:expr value="$attr.size"/><br>
Subtype=<jx:expr value="$attr.subtype" default="NULL"/><br>
Values=<jx:expr value="$attr.values" default="NULL"/><br>
ByteValue=<jx:expr value="$attr.byteValue"
default="NULL"/><br>
ByteValues=<jx:expr value="$attr.byteValues"
default="NULL"/><br></jx:forEach>
</ldap:search>
- The last example produces an exception by setting a low limit to the number of entries returned and then displays all information about the exception.
<ldap:search host="phonebook.example.com"
base="ou=People,dc=example,dc=com" srchScope="sub"
maxEntries="3" response="searchError">
DN=<jx:expr value="$entry.dn" default="NULL"/>
</ldap:search>Response:
<jx:expr value="$searchError" default="NULL"/><br>
Response.code:
<jx:expr value="$searchError.code" default="NULL"/><br>
Response.exception:
<jx:expr value="$searchError.exception" default="NULL"/><br>
Response.message:
<jx:expr value="$searchError.message" default="NULL"/><br>
Response.klass:
<jx:expr value="$searchError.klass" default="NULL"/><br>SEE ALSO
<ldap:attr>, <ldap:sortControl>,
<ldap:sortControl>, <ldap:vlControl>, <ldap:vlControl>
<ldap:sortControl>Define an LDAPSortControl for sorting search results. This element must contain <ldap:sortKey> elements to specify the keys.
DESCRIPTION
Use the <ldap:sortControl> and <ldap:sortKey> elements together to specify one or more attributes to use for sorting search results. The first <ldap:sortKey> element it contains will be the primary sort key, the second one will be the secondary sort key, and so on.
Specify a variable name and optional scope to store the control definition and then reference this variable with the controls attribute of the <ldap:search> element. You may add the sort controls to an existing variable, as long as it is an instance of a ControlsBean, created by either <ldap:sortControl> or <ldap:vlControl>.
SYNTAX
<ldap:sortControl var="varName" [ scope="scopeName" ]>
<ldap:sortKey ...> ...
</ldap:sortControl>ATTRIBUTES
var="varName"
Give the name of the variable where the sort control will be stored.
scope="varScope"
Give the scope of the variable where the sort control will be stored.
EXAMPLES
<ldap:sortControl var="controls">
<ldap:sortKey key="sn"/>
<ldap:sortKey key="givenname"/>
</ldap:sortControl><ldap:search host="phonebook.example.com"
base="ou=People,dc=example,dc=com" srchScope="sub"
filter="(surname=a*)" controls="$controls"
attrs="dn|sn|givenname|employeeNumber|telephonenumber"
var="results" scope="page" response="searchError"/>SEE ALSO
<ldap:vlControl>, <ldap:search>
<ldap:sortKey>Defines the attribute to use for sorting within an <ldap:sortControl> element.
DESCRIPTION
The <ldap:sortKey> element may only occurs within an <ldap:sortControl> element. It specifies an attribute to use as the key for sorting the results of a search, and optionally reverse sort order or a matching rule.
SYNTAX
<ldap:sortKey key="attrName" [ reverse="yes" matchRule="OID" ]/>
ATTRIBUTES
SEE ALSO
<ldap:sortControl> and its examples.
<ldap:vlControl>This element may be used in conjunction with <ldap:sortControl> to perform searches with sorted virtual lists (VL).
DESCRIPTION
The <ldap:vlControl> element allows you to add virtual list (VL) functionality to sorted searches. Use in conjunction with the <ldap:sortControl> by specifying the same name and optional scope for the var and scope attributes.
DESCRIPTION
The <ldap:vlControl> element allows you to add virtual list (VL) functionality to sorted searches. Use in conjunction with the <ldap:sortControl> by specifying the same name and optional scope for the var and scope attributes.
SYNTAX
For the initial search:
<ldap:vlControl jump="string" before="number" after="number"
var="varName" [ scope="scopeName" ]/>For subsequent searches in the same virtual list:
<ldap:vlControl start="index" before="number" after="number"
content="number" var="varName" [ scope="scopeName" ]/>ATTRIBUTES
EXAMPLES
<ldap:sortControl var="controls">
<ldap:sortKey key="cn"/>
</ldap:sortControl><ldap:vlControl jump="A" before="5" after="5" var="controls"/>
<ldap:search host="phonebook.example.com"
base="ou=People,dc=example,dc=com" srchScope="sub"
filter="(surname=a*)" controls="$controls"
var="results" scope="page" response="searchError"/>VL Response = <jx:expr value="$results.vlResponse" default="NULL"/>
<table border="2">
<jx:forEach var="entry" items="$results">
<tr><td><ldap:attr entry="$entry" name="cn"/></td></tr>
</jx:forEach>
</table><!-- Use the VL info from the first search to prepare subsequent
searches of the same list. -->
<jx:set var="first" value="$results.vlResponse.firstPosition"/>
<jx:set var="count" value="$results.vlResponse.contentCount"/><% Integer firstI = (Integer) pageContext.getAttribute("first");
Integer countI = (Integer) pageContext.getAttribute("count");
if ((firstI != null) && (countI != null)) {
int next = firstI.intValue() + 10;
if (next <= countI.intValue())
application.setAttribute("next", new Integer(next));
else
application.removeAttribute("next");
}
application.removeAttribute("last");
%>SEE ALSO
<ldap:sortControl>, <ldap:search>
Utilities Tag LibraryThe Utilities Tag Library is also built on JSPTL and provides some useful elements for writing LDAP-enabled JSP applications. These tags perform such tasks as reading values from a properties file, testing the existence of an attribute, and so on. The tag library definition is contained in the util.tld found in the DSRK_base/jdgw/phonebook-app/WEB-INF directory.
<util:date>Outputs a date and time string using the java.text.DateFormat class.
DESCRIPTION
The <util:date> element generates a date and time string according to the given locale. For a complete description of the possible date formats, see the API reference for the java.text.DateFormat class.
By default the element will display the current date in the page output. However, you may specify a different date string to reformat, and you may give the name of a variable and optional scope to store the formatted string.
SYNTAX
<util:date [ value="timeString" format="SHORT|MEDIUM|LONG|FULL" ]
[ lang="subtype" cntry="subtype" varnt="localeVariant" ]
[ var="varName" scope="varScope" ]/>>ATTRIBUTES
EXAMPLES
SHORT: <util:date format="short"/>
MEDIUM: <util:date format="medium"/>
LONG: <util:date format="long"/>
FULL: <util:date format="full"/><P>
DEFAULT: <util:date/><P>
TIMESTAMP 20010807163841Z:
<util:date format="full" value="20010807163841Z"/>
<util:encode>Encode a string into UTF-8 format.
DESCRIPTION
This element converts its contents or its value attribute to UTF-8, where all characters are encoded in 8 bits.
If you do not specify a variable and optional scope in which to store the encoded value, it will be displayed as part of the page output.
SYNTAX
<util:encode [ var="varName" scope="varScope" ]>inputString</util:encode>
<util:encode value="inputString" [ var="varName" scope="varScope" ]/>
ATTRIBUTES
EXAMPLES
DN string: "cn=Babs Jensen,ou=People,dc=example,dc=com"
Normalized:
<ldap:dn value="cn=Babs Jensen,ou=People,dc=example,dc=com"/>
<ldap:dn value="cn=Babs Jensen,ou=People,dc=example,dc=com" var="dn"/>
Encoded: <util:encode value="$dn"/>
<util:importParams>Import all parameters from the ServletRequest into the REQUEST scope.
DESCRIPTION
This element reads all the parameters of the request and sets page context attributes, either single or multivalued, in the REQUEST scope.
SYNTAX
<util:importParams/>
<util:log>Writes a string to the log file.
DESCRIPTION
This element will add the following line to the ServletContext log:
<Log> logString
SYNTAX
<util:log value="logString"/>
ATTRIBUTES
EXAMPLES
<util:log value="Log this value"/>
<util:logScopes>Logs all variables and values defined currently defined in all scopes.
SYNTAX
<util:logScopes/>
DESCRIPTION
This element will write a section in the ServletContext log containing the name and value of all variables or attributes in a specified scope.
SEE ALSO
<util:present>Checks the existence of a variable and returns true if present.
DESCRIPTION
This element checks for the existence of a variable name in a given scope and sets a boolean value in another variable. The result is true if the named variable exists and false otherwise. The scope attribute of this tag determines the scope of the variable name to test, not the scope of the output variable.
SYNTAX
<util:present name="varName" [ scope="nameScope" var="varName" ]/>
ATTRIBUTES
<util:prop>Retrieve a property value from a properties file.
DESCRIPTION
This element will retrieve a value corresponding to the given property key from a properties file. You may specify the language, country, and variant that determine a locale through the lang, cntry, and optional varnt attributes.
The name of the properties bundle and optional locale determine the name of the file where the keys and values are defined. The element will return an error if the file cannot be found.
The property key is the name of the property, as found in the file. You may also specify an optional default value that will be returned when the key does not exist in the file.
If you do not specify a variable and optional scope in which to store the property value, it will be displayed as part of the page output.
SYNTAX
<util:prop prps="bundleName" key="propName" [ def="value" ]
[ lang="subtype" cntry="subtype" varnt="localeVariant" ]
[ var="varName" scope="varScope" ]/>ATTRIBUTES
EXAMPLES
The following example from the LookMeUp application uses localized properties to create a row of headings in a table output.
<table border="0" cellpadding="1" cellspacing="0" width="100%"
bgcolor="#FFFFFF" align="center">
<tr align="left" bgcolor="#990000"> <!-- Shaded heading row --><td><b>
<util:prop prps="screen" key="searchresults.name"
lang="$app:language" cntry="$app:country"/>
</b></td><td><b>
<util:prop prps="screen" key="searchresults.phone"
lang="$app:language" cntry="$app:country"/>
</b></td><td><b>
<util:prop prps="screen" key="searchresults.email"
lang="$app:language" cntry="$app:country"/>
</b></td></tr> ...
</table>
JSP Standard Tag LibraryJSPTL, Early Access Release 1.2, is the standard JavaServer Pages Tag Library. It contains simple tags that provide core functionality common to many JSP applications.
Note
While the JSPTL has been superseded by the JSP Standard Tag Library (JSTL), the LookMeUp application relies on the older JSPTL described in this section. If you develop new JSP, we recommend you use the latest JSTL. The latest release and its documentation is available from:
http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html
JSPTL is comprised of two tag libraries. The two libraries contain very common sets of tags, with one major difference: the first library (jr) has tags that accept request-time attribute values (rtexprvalues) for their attributes, while the second library (jx) accepts attribute values specified using the expression language (EL) introduced in JSPTL. To use the jr tags, include the following line at the top of your .jsp file:
<%@ taglib uti=http://java.sun/com/jsptl/ea/jr prefix="jr" %>
Note
You may choose any prefix, but jr is the current recommendation for the rtexprvalue version of the JSPTL library.
The LookMeUp application included with the DSRK relies on the jx library that supports EL. This second library is detailed in this guide. To access this library, the application’s JSP use the following directive:
<%@ taglib uti=http://java.sun/com/jsptl/ea/jx prefix="jx" %>
The tag library definition is contained in the jx.tld found in the DSRK_base/jdgw/phonebook-app/WEB-INF directory.
<jx:expr>Returns the value of its expression.
SYNTAX
<jx:expr value="valueExpr" [ default="value" ]/>
ATTRIBUTES
DESCRIPTION
Use this tag to fetch the value of a variable by specifying the $varName syntax in the value attribute. This element is the EL-equivalent of the <%=...%> element.
EXAMPLE
See <jx:set> and its example.
<jx:set>Store the result of an expression evaluation in a scoped variable.
SYNTAX
<jx:set var="varName" [ scope="varScope" ] value="valueExpr"/>
<jx:set var="varName" [ scope="varScope" ]>contents</jx:set>
ATTRIBUTES
DESCRIPTION
Use this tag to evaluate an expression in the value attribute and store its result in the designated variable and optional scope. You may also store the elements which are contents of this tag in the designated variable.
EXAMPLE
<jx:set var="city" value="$custmer.address.city"/>
<jx:set var="customerFmt" scope="request">
<font color="red">
<jx:expr value="$city"/>
</font>
</jx:set>
<jx:declare>Declares a scripting variable.
SYNTAX
<jx:declare id="varName" [ type="typeClass" ]/>
ATTRIBUTES
id="varName"
Specify the name of the scripting variable.
type="typeClass"
Specify the type or Java class of the attribute. When omitted, the default type is java.lang.Object.
DESCRIPTION
Declares a scripting variable, initially defined by an existing scoped attribute of the same name.
EXAMPLE
<jx:declare id = "customer" type= "acme.Cutomer" />
<jx:forEach>The basic iteration tag, accepting many different collection types.
SYNTAX
<jx:forEach var="iterName" items="varName" [ status="varName" ]
[ begin="index" end="index" step="number" ]>
contents
</jx:forEach>ATTRIBUTES
DESCRIPTION
This element will process its contents once for every iteration defined by the items attribute and by the optional begin, end, and step attributes. During the iteration, the variable named by the var attribute will contain each value of the items in sequence. For example, this element allows you to process each value of a multi-valued LDAP attribute.
EXAMPLE
<jx:forEach var="customer" items="$customers">
<jx:expr value="$customer.name">
</jx:forEach>
<jx:forToken>Iterates over tokens in a string, separated by the specified delimiters.
SYNTAX
<jx:forToken var="iterName" items="tokenString" delims="delimChars"
[status="varName" begin="index" end="index" step="number"]>
contents
</jx:forToken>ATTRIBUTES
DESCRIPTION
This element will process its contents once for every token defined by the items and delims attributes. As with the <jx:forEach> element, you may modify the iteration sequence with the optional begin, end, and step attributes. During the iteration, the variable named by the var attribute will contain each token in sequence. For example, this element allows you to process strings containing fields or choice values.
EXAMPLE
<jx:forToken var="token" items="blue|white|red" delims="|">
contents
</jx:forToken>
<jx:if>The basic conditional tag.
SYNTAX
<jx:if test="boolExpr" [ var="varName" scope="varScope" ]>
contents
</jx:if>ATTRIBUTES
DESCRIPTION
The <jx:if> element evaluates its contents if the boolean expression in the test attribute evaluates to true. The optional var attribute names a variable to store the Boolean result of evaluating the test condition.
EXAMPLES
<jx:if test="$customer.address.country == ’USA’"
var="isUsCustomer">
contents
</jx:if>SEE ALSO
<jx:choose> <jx:when> <jx:otherwise>
<jx:choose> <jx:when> <jx:otherwise>Conditional tag that allows mutually exclusive conditional operations marked by <jx:when> and <jx:otherwise>.
SYNTAX
<jx:choose>
<jx:when test="boolExpr">
contents
</jx:when>
...
[ <jx:otherwise>
contents
</jx:otherwise> ]
</jx:choose>ATTRIBUTES
DESCRIPTION
The <jx:choose>, <jx:when>, and <jx:otherwise> elements allow the common if-then-elsif-else conditional construct.
The <jx:choose> element must directly contain one or more <jx:when> elements. It may directly contain an optional <jx:otherwise> element which must occur last. The boolean expressions in the test attributes will be evaluated in the order they appear and the contents of the first one that is true will be evaluated. If all are false, the contents of the <jx:otherwise> element will be evaluated, if present.
EXAMPLE
<ldap:search host="phonebook.example.com"
base="ou=People,dc=example,dc=com" srchScope="sub"
var="results" response="searchError"/><jx:choose>
<jx:when test="$searchError == ’NULL’">
<!-- process the search results -->
<jx:choose>
<jx:when test="$results.size > 1">
<!-- display a table of search results-->
<%@ include file="searchresults.jsp" %>
</jx:when><jx:when test="$results.size == 1">
<!-- extract the single result from the list -->
<jx:forEach var="result" items="$results">
<!-- set the request:dn for use in person.jsp -->
<jx:set var="dn" scope="request"
value="$result.dn"/>
<jsp:include page="person.jsp"></jsp:include>
</jx:forEach>
</jx:when>
<jx:otherwise>
<!-- Display a message -->
<h1><center>No matching entry was found</h1>
</jx:otherwise>
</jx:choose>
</jx:when><jx:otherwise>
<!-- display the search error -->
Response: <jx:expr value="$resp" default="NULL"/><br>
Message:
<jx:expr value="$resp.message" default="NULL"/><br>
</jx:otherwise>
</jx:choose>