| Previous Contents Index Next |
| iPlanet Portal Server: Mobile Access Pack Programmer's Guide |
Chapter 6 JSP Tag Libraries
This chapter discusses the Java Server Page (JSP) tag libraries that facilitate the delivery of content from the iPlanet Messaging Server, iPlanet Calendar Server, and the iPlanet Personal Address Book to the user's mobile device.For detailed information on the usage of these tags within the Mobile Access Pack applications, see Chapter 5 "Application JSPs".
The JSP tag libraries for these applications:
Maintain client session state using the iPlanet Portal Server session mechanism.
Use the iPlanet Portal Server profile interface to retrieve profile information such as configuration (such as, backend service host/port), authentication (such as, credentials), and preferences (such as, address book sorting).
Log error and warning messages through the iPlanet Portal Server logging interface.
A tag typically follows one of the following patterns:
A context tag represents the session state for a valid authenticated connection to a backend service. This tag verifies that the session is still valid and provides a context for other tags to make requests to that service. The object a context tag gives reference to is called the service context.
At the first request, a connection is made to the backend service using the configuration and authentication information from the portal profile service. The service context is based upon the current portal session so that it is available across multiple requests.
A bean tag represents a java bean object to store on the current page context. The bean properties are retrieved or modified with the get or set tags. The following tag attributes specify how the bean is found:
The id attribute creates a new empty bean and stores it in the page context using the attribute's value.
If neither one of these attributes are set, then the current item in an enclosing collection parent tag is used.The name attribute value is a bean object. This attribute looks for a property with the attribute's value in the page context.
Get tag
The get tag retrieves the value of a property of a bean object and writes it to the page output.The property attribute specifies the name of the property to retrieve. If the property attribute is not specified, the results of the toString() method of the identified object will be returned as the results of the get tag.
If there is a name attribute, it is used to locate the bean in the page context. If there is no name attribute, then the enclosing bean parent tag is used to find the bean object.
Set Tag
The set tag modifies the value of a property of a bean object. The property attribute specifies the name of the property to modify. The value attribute specifies the value to set the property to. The tag body content is executed only if the tag fails to modify the bean property.
These tags provide access to a collection of beans constructed by a preceding command tag. Information about the collection can be accessed by the properties of a collection tag.
This collection is typically stored within a particular service context and is referenced implicitly by the name of the particular collection tag. For example, the <mail:messages> tag refers to the current messages collection stored within the current mail service context.
The id and name attributes permit bean tag like access to the properties of the collection. This is useful for constructing paginated access to a collection from within a Java Server Page. The optional beanid attribute, when specified when the collection is in iterative mode, stores the "current" bean from the collection onto the page context using the name specified by the beanid attribute.
The collection tags operate in non-iterative and iterative modes, as specified by the iterate attribute.
In the non-iterative mode, various properties of the collection can be set or retrieved and the body of a collection tag is processed only once.
In the iterative mode, the body is evaluated until a count property is exhausted (but at least once), and the iteration begins at an index in the collection as specified by the start property.
Usage Examples
The following reference to a collection tag establishes iteration parameters:<util:set property="start" value="$(start)"/>
<util:set property="count" value="10"/>
The following iterates through the collection in the specified manner:
<collection-tag name="example" iterate="true">
Item#<util:get property="indexOne"/>
<util:get property="some-bean-specific-property-name"/>
The following is a demonstration of the construction of a "next page" link
<collection-tag name="example">
<util:link tagstart="<a" tagend=">">
<url comp="whatever" file="next.jsp">
<parm name="start"><util:get property="nextStart"/></util:parm>
A command tag makes a request to a backend service. It uses the service context to make the request. The request arguments come from the tag attributes, request parameters, or iPlanet Portal Server profile settings. The request stores the results as properties in a service context and/or as beans on the page context. The tag body content is executed only if the request fails.
The content tag is used to set the content type and charset of the Java Server Page output stream. The charset is read and set from the user's iPlanet Portal Server profile. The content tag, combined with the catalog tags, enables JSP template files with no localized content to generate localized output (based on message catalogs) in the correct charset.
This tag provides access to session attributes.
These tags provide a way to store beans, that are beyond the scope of a page context, within the scope of a session.
These tags construct dynamically generated link type tags.
Before processing a tag, the attributes of most tags in the tag libraries are subject to the following rules of evaluation. If an attribute contains:
$(parameterName) - This is replaced by the value of the HTTP request parameter identified by parameterName.
${beanName:propertyName} - This is replaced by the value of the bean property identified by beanName and propertyName. The bean is assumed to exist on the current page context.
$[catalogName:key] - This is replaced by the value of the message catalog entry identified by catalogName and key. The catalogName refers to a catalog bean placed on the page context by a preceeding catalog tag.
$/componentName:attributeName[:defaultValue]/ - This is replaced by the client (device) specific value of the iPlanet Portal Server profile attribute as identified by componentName and attributeName. If the attribute does not exist, a null string is returned, unless defaultValue is specified as well.
The following are sample evaluation of some tag attribute values:
Example 1
<mail:message id="newmsg"><mail:set property="to" value="$(to)"/>
In the above example, the value of the attribute evaluates to the value of the HTTP request parameter named to.
Example 2
<mail:message name="newmsg"><mail:set property="to" value="${newmsg:to} $(to)"/>
In the above example, the value of the attribute evaluates to the value of the to property of the newmsg bean, followed by a space, and then followed by the value of the HTTP request parameter named to.
The Mobile Access Pack tag libraries log error and warning messages in:
This logging functionality is controlled by a property in the iPlanet Portal Server configuration file:
/etc/opt/SUNWips/platform.conf
For JSP debugging, edit this file. For example, open the platform.conf file and modify the following property:
This section provides an abbreviated list of each tag in the Mobile Access Pack tag libraries. For detailed information on each library and its collection of tags, refer to the relevant section in this chapter.
Table 6-1 contains a list of tags from the utilities tag library.
Utilities Tag Library">
Table 6-1    Utilities Tag Library
Tag
Description
This tag provides reference to the state of the utility service for a given session.
This tag operates on a collection of the specified bean objects, iterates through that collection, and makes that bean collection available to the page.
This tag retrieves the specified property and writes its value to the page output.
This tag copies the specified property value from the source bean to the target bean.
This tag tests the specified property and includes the tag body if the property evaluates to true.
This tag tests the specified property and includes the tag body if the property evaluates to false.
This tag lists all properties of the specified bean to the page output.
This tag loads a message catalog specified by the resource attribute and makes it available to the page.
This tag gets a message specified by the key attribute from a message catalog and writes it to the page output.
This tag is used to set the content type and charset of the JSP output stream from the user's iPlanet Portal Server profile.
This tag refers to an "edit" bean which specifies that certain editing be performed upon the enclosed body.
This tag performs a "forward" operation, similar to <jsp:forward>.
This tag performs an "include" operation, similar to <jsp:include>.
Table 6-2 contains a library of tags for the calendar server.
iPlanet Calendar Server Client Tag Library">
Table 6-2    iPlanet Calendar Server Client Tag Library
Tag
Description
This tag represents the state of the session to the calendar service.
This tag fetches the specified range of events into the calendar context.
This tag stores the specified event into the current calendar set.
This tag deletes the specified event from the current calendar set.
This tag either formats a datetime for output or parses one from an input.
This tag rolls the specified datetime attribute value forward or backward.
This tag sets or updates the specified event bean property or field.
This tag contains a collection of event beans in the calendar context.
Table 6-3 contains a library of tags for the mail server.
iPlanet Messaging Server Client Tag Library">
Table 6-3    iPlanet Messaging Server Client Tag Library
Tag
Description
This tag provides reference to the state of the mail service for a given session.
This tag fetches a collection of folders (a collection of messages), messages (a collection of lines), or lines into the context.
This tag refers to the current bean or folder within an enclosing collection or folders <mail:folders>.
This tag refers to the current bean or message within an enclosing collection of messages <mail:messages>.
This tag refers to the current bean or line within an enclosing collection of lines <mail:lines>.
This tag refers to a preset message from a collection of preset messages.
This tag retrieves the specified property and writes its value to the page output.
Table 6-4 contains a list of tags from the address book tag library.
Personal Address Book Client Tag Library">
Table 6-4    Personal Address Book Client Tag Library
Tag
Description
This tag is used to maintain state between requests. It ensures that the address book context is present within the current pageContext.
This tag fetches a collection of address book entries and sets the current collection within the current address book context (AbContext).
This tag refers to an address book entry within a collection of address book entries <ab:entries>.
This tag sets a bean property or updates the specified bean property.
This tag refers to a collection of address book entries or beans.
This tag library implements a collection of utility tags. The Utility Tag Libraries consists of the following tags:
Description
The context tag provides reference to the state of the utility service for a given session. Use of this tag without a body verifies correct operation of the utility service.
Properties
The tag has the following properties:
Example
The following is an example of the context tag:<util:set property="rfc2396" value="false"/>
<util:set property="urlAmpEntity" value="false"/>
Description
This tag constructs a link. The content of the link is dynamically generated.
Attributes
The tag has the following attributes:
Example
<util:link tagstart="<a" tagend=">"><util:url path="/DesktopServlet"></util:url>
<util:attr attr="method">GET</util:attr>
In the above example, the tag generates a link that includes session encoding, if needed. The path attribute is not subject to the rules of file lookup. The following is an example of the emitted markup:
<a href="/DesktopServlet?sid=1a34" method="GET">RETURN HOME</a>
Description
This tag adds attributes to a link tag. The content of this tag is dynamically generated.
Attributes
The tag has the following attributes:
Table 6-7    ipsUtils attr Tag Attributes
Attribute
Description
Required?
Specifies the fragment of text to include before the body of the tag.
Example
<util:link tagstart="<a" tagend=">"><util:url path="/DesktopServlet"></util:url>
<util:attr attr="method">GET</util:attr>
In the above example, the tag generates a link that includes session encoding, if needed. The path attribute is not subject to the rules of file lookup. The following is an example of the emitted markup:
<a href="/DesktopServlet?sid=1a34" method="GET"/>
Description
This tag aids in the construction of URLs. The path to the URL can be specified in the following ways:
The path attribute can specify a path to be used during the construction of the URL. Client specific rewriting can not be applied to this value.
Also, query string parameters can be appended to the URL by including the appropriate parm tags within the body of the url tag. All body content is discarded except the value of the parm tag.The file and comp attributes can together specify a JSP resource that will be resolved using client data driven file lookup rules.
Restrictions
Either the path attribute, or comp and file attributes must be specified.
Attributes
The tag has the following attributes:
Examples
The following are examples of the URL tag:Example 1: The following is an example of url tag usage, with the path attribute:
<util:link tagstart="<a" tagend=">">
<util:url path="/DesktopServlet"></util:url>
<util:attr attr="method">GET</util:attr>
In the above example, the tag generates a link that includes session encoding, if needed. The path attribute is not subject to the rules of file lookup. The following is an example of the emitted markup:
<a href="/DesktopServlet?sid=1a34" method="GET"/>
Example 2: The following is an example of url tag usage, with file and comp attributes:
<util:link tagstart="<a" tagend=">">
<util:url file="inbox.jsp" comp="mail"></util:url>
<util:attr attr="method">GET</util:attr>
In the above example, this tag generates a link that has been resolved to the correct path for the client that has requested the page. The session encoding is added as needed. The following is an example of the emitted markup:
<a href="/jsp/default/mail/wml/inbox.jsp?sid=1a34" method="GET"/>
Description
This tag adds request parameters to URLs. The following will be added as a query string parameter to the URL being constructed by an enclosing url tag:Here, name is a value specified by the parm tag's name attribute and BODY is whatever is evaluated as the parm tag's body.
The urlAmpEntity property of the utility context controls whether the query string parameter separator is generated as "&" or "&".
Tag Parent
<utilsPrefix:url> or <utilsPrefix:forward>
Attributes
The tag has the following attributes:
Table 6-9    ipsUtil parm Tag Attributes
Attribute
Description
Required?
Example
<util:link tagstart="<a" tagend=">"><util:url path="/DesktopServlet">
<util:parm name="op1">stuff</util:parm>
<util:attr attr="method">GET</util:attr>
In the above example, the tag generates a link that includes session encoding, if needed. The path attribute is not subject to the rules of file lookup. The following is an example of the resultant markup:
<a href="/DesktopServlet?sid=1a34&op1=stuff" method="GET"/>
Description
This tag operates on a collection of the specified bean objects, iterates through that collection, and makes that bean collection available to the page.
Restrictions
If the id attribute is specified, then a collection of type and size is created. If the name attribute is specified, then the collection is restored from the page context. The type attribute specifies the java class name of the object to create for the collection.
Attributes
The tag has the following attributes:
Examples
The following are examples of beans collection:Example 1: The following example creates a list of five dates and sets the seconds to the index:
<util:beans id="dates" size="5" type="java.util.Date" iterate="true">
<util:get property="index" id="index"/>
<util:set property="seconds" id="index"/>
Example 2: The following example iterates through the dates collection:
<util:beans name="dates" iterate="true"/>
Description
This tag makes a bean object available to the page. It is similar to the <jsp:useBean> except that it interoperates with the other bean tags in this tag library.
Restrictions
If the name attribute is not specified, then it uses a parent bean tag to locate the bean on which to operate. The type attribute specifies the java class name of the object to use or create.
Attributes
The tag has the following attributes:
Table 6-12    ipsUtil bean Tag Attributes
Attribute
Description
Required?
Examples
The following are examples of the bean tag:Example 1: The following example makes a date available:
<util:bean type="java.util.Date">
Example 2: The following example makes a specified date available:
<util:bean id="date" type="java.util.Date"/>
date = <util:get name="date"/>
Description
This tag retrieves the specified property and writes its value to the page output.
Restrictions
If the name attribute is not specified, then it uses a parent bean tag to locate the bean on which to operate. The property attribute must be used to specify what to retrieve. If the property attribute is not specified, then the bean object itself is retrieved as a string. The id attribute specifies the name to save the retrieved property as. If the eval attribute is specified, then the value of the attribute is evaluated and written to the page output.
Attributes
The tag has the following attributes:
Examples
The following are examples of the get tag:Example 1: The following example gets the date time property from the parent bean:
<util:bean type="java.util.Date">
time = <util:get property="time"/>
Example 2: The following example gets the date time property from the specified bean:
<util:bean id="date" type="java.util.Date"/>
time = <util:get name="date" property="time"/>
Example 3: The following example gets the date bean itself as a string:
<util:bean type="java.util.Date">
Example 4: The following example gets a non-string bean property:
<util:get property="prop" id="handle"/>
Example 5: The following example gets an evaluated attribute:
<util:catalog id="catalog" resource="catalog"/>
<util:bean id="bean" type="java.util.Date"/>
Msg = <util:get eval="$[catalog:msg]"/>
Param = <util:get eval="$(requestparam)"/>
Bean = <util:get eval="{bean}"/>
Description
This tag updates the specified property.
Restrictions
If the name attribute is not specified, then it uses a parent bean tag to locate the bean on which to operate. The property attribute specifies what to update. The value attribute specifies the string value to update the property. The id specifies the bean object value to update the property. Either value or id must be specified.
Attributes
The tag has the following attributes:
Table 6-14    ipsUtil set Tag Attributes
Attribute
Description
Required?
Specifies the edit bean that will be applied to the value prior to storage
Examples
The following are examples of the set tag:Example 1: The following example sets the date time property on the parent bean:
<util:bean type="java.util.Date">
<util:set property="time" value="0"/>
Example 2: The following example sets the date time property on the named bean:
<util:bean id="date" type="java.util.Date"/>
<util:set name="date" property="time" value="0"/>
Example 3: The following example sets a bean onto another bean property:
<util:bean id="one" type="BeanOne"/>
<util:bean id="two" type="Beantwo"/>
<util:set name="two" id="one" property="one"/>
Description
This tag copies the specified property value from the source bean to the target bean.
Restrictions
If the name attribute is not specified, then it uses a parent bean tag to locate the bean on which to operate.
Attributes
The tag has the following attributes:
Table 6-15    ipsUtil copy Tag Attributes
Attribute
Description
Required?
Example
The following example copies the time property from d1 to d2:<util:bean name="d1" type="java.util.Date"/>
<util:bean name="d2" type="java.util.Date"/>
<util:copy name="d2" property="time" source="d1"/>
Description
This tag tests the specified property and includes the tag body if the property evaluates to true.
Restrictions
If the name attribute is not specified, then it uses a parent bean tag to locate the bean on which to operate. The property attribute specifies what to test. The value attribute specifies the string value to test the property. The id attribute specifies the bean object value to test the property. If neither value or id is specified, then the test is true if the property value is non-null.
Attributes
The tag has the following attributes:
Table 6-16    ipsUtil if Tag Attributes
Attribute
Description
Required?
Examples
The following are examples of the if bean:Example 1: The following example tests if the date time equals to zero on the parent bean:
<util:bean type="java.util.Date">
<util:if property="time" value="0">
Example 2: The following example tests if the date time == 0 on named bean:
<util:bean id="date" type="java.util.Date"/>
<util:if name="date" property="time" value="0">
Example 3: The following example tests if the bean property is non-null:
... Bean.name != null </util:if>
Example 4: The following example tests using two beans:
<util:bean id="one" type="BeanOne"/>
<util:bean id="two" type="BeanTwo"/>
<util:if name="one" property="bean" id="two">
Description
This tag tests the specified property and includes the tag body if the property evaluates to false.