Chapter 4 TagLib: Util

This chapter describes about the Tag Library Utilities attributes:

The Calendar Tag Library consists of the following tags:

• attr

• bean

• beans

• catalog

• context

• msg

• content

• context

• copy

• edit

• forward

• get

• if

• ifnot

• include

• link

• list

• parm

• session

• set

• url

attr

Description

Emits the following: attr="BODY". The purpose of this tag is to aid in the construction of tag attributes, whose content is dynamically generated.

Tag Body

JSP

Tag Parent

<utilsPrefix:link>

Restrictions

None.

Attributes

This tag has the following attributes for which the Required value is “Yes”:

attr

The fragment of text to emit prior to: ="BODY".

Properties

This tag provides the following bean properties for which the Access value is “n/a”:

n/a

n/a

Example(s)

<%-- example of attr tag usage --%>
<util:link tagstart="<a" tagend=">">
<util:attr attr="href">
<util:url path="/DesktopServlet"></util:url>
</util:attr>
<util:attr attr="method">GET</util:attr>
 </util:link>GO HOME</a> 

Will generate a link that includes session encoding, if needed. The "path" attribute is not subject to the rules of file lookup. The emitted markup may look something like: <a href="/DesktopServlet?sid=1a34" method="GET"/>

bean

Description

This tag makes the specified bean object available to the page. It is essentially the same as <jsp:useBean> except that it interoperates with the other bean tags in this tag library.

Tag Body

Empty

Restrictions

If the name attribute is not specified then 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

This tag has the following attributes for which the Required values are “No” and “Yes”:

id

Name of the bean to create.

name

Name of the bean to use.

type

Type of the bean; a java class name.

Properties

All the bean properties of the bean type created are available.

Example(s)

<%-- make a date available --%>
<util:bean type="java.util.Date">
date = <util:get/>
</util:bean>

<%-- make a named date available --%>
<util:bean id="date" type="java.util.Date"/>
date = <util:get name="date"/> 
</util:bean>

beans

Description

The beans tag operates on a collection of the specified bean objects and iterates through that collection.

Tag Body

JSP

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

This tag has the following attributes for which the Required values are “Yes” and “No”:

id

Name of the bean collection to create.

name

Name of the bean collection to use.

iterate

A boolean that selects iteration. Default is "false", the collection will not iterate.

type

Type of the bean; a java class name.

size

Number of beans to create for the collection.

beanid

During iteration, specifies a name by which the current bean may be retrieved from the PageContext.

Properties

This tag provides the following bean properties for which the Type values are “Integer”, “Boolean” and the Access value is “Get/Set”:

index

Index of the current bean in the collection.

count

The number of iterations the collection should perform.

start

The zero based index from which to begin iteration.

end

The zero based index that denotes the item upon which iteration will terminate.

startOne

One-based start; suitable for presentation.

endOne

One-based end; suitable for presentation.

size

The size of the collection being paged.

nextPage

Whether or not there are more items in the collection, beyond the current iterations.

prevPage

Whether there are items in the collection preceding the current iterations.

Example(s)

<%-- create a list of 5 dates and set the seconds to the index --%>
<util:beans id="dates" size="5" type="java.util.Date" iterate="true">
<util:get property="index" id="index"/>
<util:bean> 
<util:set property="seconds" id="index"/>
</util:bean>
</util:beans>

<%-- iterate through the dates collection --%>
<util:beans name="dates" iterate="true"/>
<util:bean>
date = <util:get/> 
</util:bean>
</util:beans>

catalog

Description

This tag loads a message catalog specified by the resource attribute and makes it available to the page. A message catalog is a java.util.ResourceBundle object that is locale-specific. Also see the msg tag

Tag Body

JSP

Restrictions

The id attribute is used to make the message catalog available after the catalog end tag. The name attribute is used to make a previously create catalog available. This tag also makes a scripting variable, specified by the id attribute available. Use the getMsg(String key) method to get the message string.

Attributes

This tag has the following attributes for which the Required value is “No”:

id

Name to save the catalog on the page context. This is also the name for the scripting variable.

name

Name to use to retrieve the catalog from the page context.

resource

Resource name to locate the message catalog.

Properties

None.

Example(s)

<%-- get key 'message' from catalog 'sample' --%>
<util:catalog resource="sample">
Message = <util:msg key="message"/>
</util:catalog>

<%-- get key from a named catalog --%>
<util:catalog id="sample" resource="sample"/>
...
Message = <util:msg name="sample" key="message"/>

<%-- get key using scripting --%>
<util:catalog id="sample" resource="sample"/>
...
Message = <%= sample.getMsg("message") %>

msg

Description

This tag get a message specified by the key attribute from a message catalog and writes it to the page output. Also see the catalog tag.

Tag Body

Empty

Restrictions

If the name attribute is not specified then a parent catalog tag is used to locate the message catalog

Attributes

The tag has the following attributes for which the Required values are “Yes” and “No”:

name

Name of the message catalog to use.

key

Key used to find the message in the catalog.

Properties

None.

Example(s)

<%-- get key 'message' from catalog 'sample' --%>
<util:catalog resource="sample">
Message = <util:msg key="message"/>
</util:catalog>

<%-- get key from a named catalog --%>
<util:catalog id="sample" resource="sample"/>
...
Message = <util:msg name="sample" key="message"/>

content

Description

The content tag sets the content type and charset of the JSP response. The charset is determined based upon the type of the device making the request, but the content type must be explicitly specified. The tag should appear prior to the generation of any output from the JSP.

Tag Body

None.

Restrictions

None.

Attributes

The only attribute for content tag for which the Required value is Yes is:

type

Content type of the current JSP response.

Properties

None.

Example(s)

<%-- utility content --%>
<util:content type="text/vnd.wap.wml"/>

context

Description

This tag provides a 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.

Tag Body

JSP

Restrictions

None.

Attributes

None.

Properties

The tag has the following properties for which the Type values are “Boolean”, “String”, and the Access value is “Get/Set”:

rfc2396

If "true", the url generated by the url tag is escaped according to the RFC2396 rules, otherwise, the url is not escaped. The default is "true".

urlAmpEntity

If "true", the "&" separator in a query string parameter list constructed by the url tag is rendered as "&", otherwise, it is rendered as "&". The default is "true".

parmDelimiter

If set, multi-value request parameters, e.g. "names=john=mary", will be concatenated into a single value when referenced within a tag attribute using the "$(parmName)" nomenclature. The concatenated values will be separated by parmDelimiter.

Example(s)

<%-- utility context --%>
<util:context>
	<util:set property="rfc2396" value="false"/>
	<util:set property="urlAmpEntity" value="false"/>
</util:context>

copy

Description

This tag copies the specified property value from the source bean to the target bean.

Tag Body

Empty

Restrictions

If the name attribute is not specified then uses a parent bean tag to locate the bean on which to operate.

Attributes

This tag has the following attributes for which the Required value is “Yes” and “No”:

name

Name of the bean to use.

source

Name of the bean to copy from.

property

Name of the bean property to copy.

Properties

None.

Example(s)

<%-- copy '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"/>

edit

Description

This tag denotes a reference to an "edit" bean, a bean whose properties specify that certain editing be performed upon the enclosed body. The edit will be performed in the following order: String substitution, if any specified. String truncation, if any specified. Character entity escaping, if any specified. The edit bean may also be referenced by the get/set tags, resulting in the appropriate modifications to the values being get or set.

Tag Body

JSP

Restrictions

At least the id or name attribute must be specified, but not both.

Attributes

This tag has the following attributes for which the Required value is “No”:

id

Specifies the id of the bean to create.

name

Specifies the name of the bean to use.

Properties

This tag provides the following bean properties for which the Type values are “Integer”, “Boolean” and Access value is “Get/Set”:

truncation

The number of characters to which to truncate the body.

escape

A boolean that indicates whether or not to apply XML style character entity escaping to the body. The characters that will be escaped are: "<", ">", and "&".

from

If present, specifies that all instances of the indicated value be replaced by the value specified by the to attribute.

to

Specifies the string with which to replace all occurrences of the string specified by the from attribute. If to is not specified, it defaults to the null string.

Example(s)

<%-- truncate a mail subject line --%>

<util:edit id="t1">
	<util:set property="truncation" value="20"/>
	<util:set property="escape" value="true"/>
</util:edit>
...
<util:edit name="t1">
	<mail:message>
		<mail:get property="subject"/>
	</mail:message>
</util:edit>
...
<%-- same thing, different way --%>
...
<mail:get property="subject" edit ="t1"/>

forward

Description

This tag will perform a "forward" operation, similar to <jsp:forward>, but will construct the JSP resource name in one of two ways: The path attribute may specify a path to be used verbatim during the construction of the URL. Client data specific rewriting will not be applied to this value. The file and comp attributes may together specify a JSP resource that will be resolved using client data driven file lookup rules. Additionally, query string parameters may be appended to the URL by the inclusion of the appropriate parm tags within the body of the "forward" tag. With the exception of the parm tags, all body content is discarded. The parameters that are ultimately passed to the destination resource are the concatenation of those present in the original request, and those specified in the body of the forward tag.

Tag Body

JSP

Restrictions

Either path or, file and comp must be specified.

Attributes

The tag has the following attributes for which the Required value is “No”:

file

The file for which to perform the lookup, and thence to forward.

comp

The component that the target file belongs to, e.g., "mail", "cal", or "ab".

path

The path component of the URL. If path is specified, neither file nor comp should be specified.

Properties

n/a

Example(s)

<%-- forward tag example --%>

<util:forward file="inbox.jsp" comp="mail"/>

... or possibly ... 

<util:forward file="inbox.jsp" comp="mail">
	<util:parm name="parm1">abc</util:parm>
</util:forward>

get

Description

This tag retrieves the specified property and writes its value to the page output.

Tag Body

Empty

Restrictions

If the name attribute is not specified then uses a parent bean tag to locate the bean on which to operate. The property attribute should be used to specify what to retrieve; if not specified then the bean object itself is retrieved as a string. The id attribute specifies the name to save the retrieved property as; useful for non-string properties. If the eval attribute is specified then the value of the attribute is evaluated and written to the page output; this replaces the bean processing described above.

Attributes

This tag has the following attributes for which the Required value are “Yes” and “No”:

name

Name of the bean to use.

property

Name of the property to retrieve. If not specified then the bean itself is retrieve as a string.

id

Name to save the retrieved value as.

eval

Attribute to evaluate and write to page output.

edit

Specifies the edit bean that will be applied to the returned value.

Properties

None.

Example(s)

<%-- get the date time property from parent bean --%>
<util:bean type="java.util.Date">
time = <util:get property="time"/>
</util:bean>

<%-- get the date time property from named bean --%>
<util:bean id="date" type="java.util.Date"/>
...
time = <util:get name="date" property="time"/>

<%-- get the date bean itself as a string --%>
<util:bean type="java.util.Date">
date = <util:get/>
</util:bean>

<%-- get a non-string bean property --%>
<util:bean: type="Bean">
<util:get property="prop" id="handle"/>
</util:bean>

<%-- get 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}"/>

if

Description

The if tag tests the specified property and includes the tag body if the property evaluates to true.

Tag Body

JSP

Restrictions

If the name attribute is not specified then uses a parent bean tag to locate the bean on which to operate. The property 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

This tag has the following attributes for which the Required value are “Yes” and “No”:

name

Name of the bean to use.

property

Name of the property to test.

value

String value of the property to test.

id

Bean object value of the property to test.

Properties

None.

Example(s)

<%-- test if the date time == 0 on parent bean --%>
<util:bean type="java.util.Date">
<util:if property="time" value="0">
... date.time == 0
</util:if>
</util:bean>

<%-- test if the date time == 0 on named bean --%>
<util:bean id="date" type="java.util.Date"/>
...
<util:if name="date" property="time" value="0">
... date.time == 0
</util:if>

<%-- test if bean property is non-null --%>
<util:bean type="Bean">
<util:if property="name">
... Bean.name != null
</util:if>
</util:bean>

<%-- test using two beans --%>
<util:bean id="one" type="BeanOne"/>
<util:bean id="two" type="BeanTwo"/>
<util:if name="one" property="bean" id="two">
... one.bean == two
</util:if>

ifnot

Description

This tag tests the specified property and includes the tag body if the property evaluates to false. This is the opposite of the if tag.

Tag Body

JSP

Restrictions

If the name attribute is not specified then uses a parent bean tag to locate the bean on which to operate. The property 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

This tag has the following attributes for which the Required value are “Yes” and “No”:

name

Name of the bean to use.

property

Name of the property to test.

value

String value of the property to test.

id

Bean object value of the property to test.

Properties

None.

Example(s)

<%-- test if the date time != 0 on parent bean --%>
<util:bean type="java.util.Date">
<util:ifnot property="time" value="0">
... date.time != 0
</util:ifnot>
</util:bean>

<%-- test if the date time != 0 on named bean --%>
<util:bean id="date" type="java.util.Date"/>
...
<util:ifnot name="date" property="time" value="0">
... date.time != 0
</util:ifnot>

<%-- test if bean property is null --%>
<util:bean type="Bean">
<util:ifnot property="name">
... Bean.name == null
</util:ifnot>
</util:bean>

<%-- test using two beans --%>
<util:bean id="one" type="BeanOne"/>
<util:bean id="two" type="BeanTwo"/>
<util:ifnot name="one" property="bean" id="two">
... one.bean != two
</util:ifnot>

include

Description

This tag will perform an "include" operation, similar to <jsp:include>, but will construct the JSP resource name in one of two ways: The path attribute may specify a path to be used verbatim during the construction of the URL. Client data specific rewriting will not be applied to this value. The file and comp attributes may together specify a JSP resource that will be resolved using client data driven file lookup rules.

Tag Body

Empty

Restrictions

Either path or, file and comp must be specified.

Attributes

This tag has the following attributes for which the Required value is “No”:

file

The file for which to perform the lookup, and thence to include.

comp

The component that the target file belongs to, e.g., "mail", "cal", or "ab".

path

The path component of the URL. If path is specified, neither file nor comp should be specified.

Properties

n/a

Example(s)

<%-- include tag example --%>
<util:include file="inbox-common.jsp" comp="mail"/>

link

Description

Emits the following: tagstartBODYtagend The purpose of this tag is to aid in the construction of "link"-type tags, whose content is dynamically generated.

Tag Body

JSP

Restrictions

None.

Attributes

This tag has the following attributes for which the Required value is “Yes”:

tagstart

The fragment of text to emit prior to the BODY.

tagend

The fragment of text to emit following the BODY.

Properties

n/a

Example(s)

<%-- example of link tag usage --%>

<util:link tagstart="<a" tagend=">">
	<util:attr attr="href">
		<util:url path="/DesktopServlet"></util:url>
	</util:attr>
	<util:attr attr="method">GET</util:attr>
</util:link>GO HOME</a>

Will generate a link that includes session encoding, if needed. The "path" attribute is not subject to the rules of file lookup. The emitted markup may look something like: <a href="/DesktopServlet?sid=1a34" method="GET"/>

list

Description

The list tag lists all properties of the specified bean to the page output. This tag is most useful for debugging; in particular the list format may not be suitable for markup and should be contained in <PRE> or equivalent tags.

Tag Body

Empty

Restrictions

If the name attribute is not specified then uses a parent bean tag to locate the bean on which to operate.

Attributes

This tag has the following attribute for which the Required value is “No:

name

Name of the bean to use.

Properties

None.

Example(s)

<%-- list the properties of a parent bean --%>
<util:bean type="java.util.Date">
<util:list/>
</util:bean>

<%-- list the properties of a named bean --%>
<util:bean id="date" type="java.util.Date"/>
...
<util:list name="date"/>

parm

Description

The following: name=BODY will be added as a query string parameter to the URL being constructed by an either an enclosing url or forwardtag. The urlAmpEntity property of the utility context controls whether the query string parameter separator is generated as "&" or "&amp;", when used from within an url tag.

Tag Body

JSP

Tag Parent

<utilsPrefix:url> or <utilsPrefix:forward>

Restrictions

None.

Attributes

This tag has the following attribute for which the Required value is “Yes”:

name

The name of the URL argument to be generated.

Properties

n/a

Example(s)

<%-- example of parm tag usage --%>

<util:link tagstart="<a" tagend=">">
<util:attr attr="href">
<util:url path="/DesktopServlet">
<parm> name="op1">stuff</util:parm>
</util:url>
</util:attr>
<util:attr attr="method">GET</util:attr>
</util:link>GO HOME</a>

Will generate a link that includes session encoding, if needed. The "path" attribute is not subject to the rules of file lookup. The emitted markup may look something like: <a href="/DesktopServlet?sid=1a34&op1=stuff" method="GET"/>

session

Description

The session tag provides access to session attributes.

Tag Body

Empty

Restrictions

If the id attribute is specified then the page attribute is restored using the session attribute. If the name attribute is specified then the session attribute is saved using the page attribute. If neither is specified then the session attribute is removed.

Attributes

This tag has the following attributes for which the Required values are “Yes” and “No”:

id

Name of the page attribute to restore from the session attribute.

name

Name of the page attribute to save into the session attribute.

attribute

Name of the session attribute to operate on.

Properties

None.

Example(s)

<%-- create a date bean to use --%>
<util:bean id="now" type="java.util.Date"/>

<%-- save that bean into the session attributes --%>
<util:session name="now" attribute="viewDay">

<%-- restore from the session attributes --%>
<util:session id="now" attribute="viewDay"/>

<%-- remove the bean from the session attributes --%>
<util:session attribute="viewDay"/>

set

Description

The set tag updates the specified property.

Tag Body

JSP

Restrictions

If the name attribute is not specified then uses a parent bean tag to locate the bean on which to operate. The property specifies what to update. The value attribute specifies the string value to update the property; the id attribute specifies the bean object value to update the property. Either value or id must be specified.

Attributes

The tag has the following attributes for which the Required values are “Yes” and “No”:

name

Name of the bean to use.

property

Name of the property to update.

value

String value of the property to update.

id

Bean object value of the property to update.

edit

Specifies the edit bean that will be applied to value prior to storage.

Properties

None.

Example(s)

<%-- set the date time property on parent bean --%>
<util:bean type="java.util.Date">
<util:set property="time" value="0"/>
</util:bean>

<%-- set the date time property on named bean --%>
<util:bean id="date" type="java.util.Date"/>
...
<util:set name="date" property="time" value="0"/>

<%-- set 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"/>

url

Description

The purpose of this tag is to aid in the construction of URLs. The path portion of the URL may be specified in one of two ways: The path attribute may specify a path to be used verbatim during the construction of the URL. Client data specific rewriting will not be applied to this value. The file and comp attributes may together specify a JSP resource that will be resolved using context sensitive resource lookup rules. The servlet context path will be prepended to the resulting URL. Additionally, query string parameters may be appended to the URL by the inclusion of the appropriate parm tags within the body of the "url" tag. With the exception of the parm tags, all body content is discarded.

Tag Body

JSP

Tag Parent

<utilsPrefix:attr>

Restrictions

Either path or, file and comp must be specified.

Attributes

This tag has the following attributes for which the Required value is “No”:

file

The file for which to generate a URL reference. If file is specified, comp should be specified and path should not be specified.

comp

The component that the target file belongs to, e.g., "mail", "cal", or "ab".

path

The path component of the URL. If path is specified, neither file nor comp should be specified.

includeSid

A boolean that indicates whether or not the session id should ever be included in the generated URI.

Properties

n/a

Example(s)

<%-- example of url tag usage, with "path" attribute --%>

<util:link tagstart="<a" tagend=">">
	<util:attr attr="href">
		<util:url path="/portal/jsp/default/launchMail.jsp"></util:url>
	</util:attr>
	<util:attr attr="method">GET</util:attr>
</util:link>GO HOME</a>

Will generate a link that includes session encoding, if needed. The "path" attribute is not subject to the rules of resource lookup. The emitted markup may look something like:<a href="/portal/jsp/launchMail.jsp?sid=1a34" method="GET"/>. Another example...

<%-- example of url tag usage, with "file" and "comp" attributes --%>

<util:link tagstart="<a" tagend=">">
	<util:attr attr="href">
		<util:url file="inbox.jsp" comp="mail"></util:url>
	</util:attr>
	<util:attr attr="method">GET</util:attr>
</util:link>GO HOME</a>

Will generate 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 emitted markup may look something like: <a href="/portal/jsp/default/mail/wml/inbox.jsp?sid=1a34" method="GET"/>