Appendix D JavaServer Pages Tag Library Reference

Appendix D
JavaServer Pages Tag Library Reference

This appendix describes the Desktop custom tag library and serves as a reference to the tags available within the library.

This appendix contains the following sections:

Tag Library Overview

Using Tags in JSPs

Tag Overview

Tag Reference

See the following supplemental documentation for more information on JavaServer Pages™ (JSP™) Custom Tags and Apache’s JSP Standard Tag Library (JSTL):

http://developer.java.sun.com/developer/technicalArticles/xml/WebAppDev3/

http://jakarta.apache.org/taglibs/doc/standard-doc/

Tag Library Overview

In JavaSever Pages technology, actions are elements that can create and access programming language objects and affect the output stream. JSP technology supports reusable modules called custom actions. You invoke a custom action by using a custom tag in a JSP. A tag library is a collection of custom tags. The Desktop custom tag library contains tags that you use to perform Desktop operations for JSPs.

Overview

Before tag libraries, JSPs were difficult to maintain because you were forced to use JavaBeans™ components and scriptlets as the main mechanism for performing tasks. Custom actions, that is, a tag library, alleviate this problem by bringing the benefits of another level of componentization to JSP. A tag library encapsulates recurring tasks so that they can be reused across more than one application.

The Sun Java System Portal Server software Desktop tag library consists of six parts:

Core tags that can be used on any provider or container that implement the PAPI interface.

Tags that can be used to operate on a provider or container that support the ProviderContext and ContainerProviderContext interfaces.

Tags that operate on specific container building-block providers (SingleContainer, TableContainer, TabContainer, and so on).

JSP Standard tag libraries from Apache.

Tags that support the Search function.

Tags that provide theme support in the Desktop.

The Desktop tag library has the following Tag Library Descriptors (TLDs) in the /etc/opt/SUNWps/desktop/default/tld directory. The tag library is exposed, for convenience, through using multiple TLDs, so that tags are in their appropriate functional area.


desktop.tld	Contains core Desktop tags that bring forward the functionality available from the ProviderContext interface.
desktopContainerProvide rContext.tld	Contains tags that bring forward the functionality available from the ContainerProviderContext interface.
desktopProviderContext. tld	Contains tags to operate on providers that extend the ProviderContext
desktopSingle.tld	Contains tags to operate on single container channels. Single container channels are based on JSPSingleContainerProvider or a subclass thereof.
desktopTable.tld	Contains tags to operate on table container channels. Table container channels are based on JSPTableContainerProvider or a subclass thereof.
desktopTab.tld	Contains tags to operate on tab container channels. Tab container channels are based on JSPTabContainerProvider or a subclass thereof.
desktopTheme.tld	Contains tags for theme support in the Desktop.
im.tld	Contains tags for IMProvider class.
jr.tld	Contains tags that accept rtexprvalues for their attributes. This is a JSP Standard tag library from Apache.
jx.tld	Contains tags that accept attribute values specified using the “expression languages” that JSPTL introduces, which currently is only simplest possible expression language (SPEL). This is a JSP Standard tag library from Apache.
search.tld	Contains tags for search support in the Desktop.

The many of the Java™ classes that support these tags reside in a JAR file desktoptl.jar in the Web-Container-Instance/portal/web-apps/WEB-INF/lib directory. The classes for the jx.tld and jr.tld tags reside in the jsptl.jar file.

Desktop Tag Library Hierarchy

The Desktop tag library can be viewed as a wrapper of PAPI, ProviderContext, ContainerProviderContext, and specific container building-block providers in the Portal Server software. Thus, a hierarchy is implied.

For example, the ContainerProviderContext (interface) extends ProviderContext (interface). When you use a tag in desktopContainerProviderContext.tld, it also make sense to use it in desktopProviderContext.tld. Similarly, when you use a tag in desktopProviderContext.tld, it also makes sense to use provider tags in desktop.tld because ProviderAdapter implements Provider. By putting the tag in the level that provides the most use, you will not have to make duplicate tags.

At the bottom of this chain are the specific containers (single, table, and tab). Because all these containers extend JSPContainerProviderAdapter, they can use tags in their respective TLDs, as well as tags in desktopContainerProviderContext.tld, desktopProviderContext.tld, and desktop.tld.

Using Tags in JSPs

In your JSP you can use HTML, Java, JavaScript™, and tags to bring in repetitive Java functions. Tags encapsulate core functionality common to many JSP applications.

In Code Example D-1, a JSP for a single channel, the tag libraries are defined at the top. The library’s symbol is then used with the tag name to bring in the appropriate information or function.

Code Example D-1 Listing of single.jsp


<%--
Copyright 2001 Sun Microsystems, Inc. All rights reserved.
PROPRIETARY/CONFIDENTIAL. Use of this product is subject to license terms.
--%>
<%-- single.jsp --%>

<%@ taglib uri="/tld/desktop.tld" prefix="dt" %>
<%@ taglib uri="/tld/desktopSingle.tld" prefix="dtsingle" %>

<%@ page session=”false” %>

<dt:obtainContainer container="$JSPProvider">
<dtsingle:singleContainerProvider>
<dtsingle:obtainSelectedChannel>
<%@ include file="header.jsp" %>
<img src="<dt:scontent/>/desktop/images/nothing.gif" height="8" width="0" border="0" alt=""><br>

<!-- provider content goes here -->
<dt:getContent/>
</dtsingle:obtainSelectedChannel>
<%@ include file="menubar.jsp" %>
<%@ include file="footer.html" %>
</dtsingle:singleContainerProvider>
</dt:obtainContainer>

In Code Example B-1, the following lines define the tag libraries that are used in the single.jsp template file.


<%@ taglib uri="/tld/desktop.tld" prefix="dt" %>
<%@ taglib uri="/tld/desktopSingle.tld" prefix="dtsingle" %>



Note	You need to include a taglib directive in the page before any custom tag is used.

The dt:obtainContainer container="$JSPProvider" tag gets a return value by reference (see “Attributes and Return Values” on page 436 for more information).

Three tags are used out of the desktop.tld library. They are obtainContainer, scontent, and getContent. See Code Example D-2 for a partial listing of desktop.tld including these three tags. The class and property information about each tag is defined here.

Code Example D-2 Partial Listing of desktop.tld


<?xml version=”1.0” encoding=”ISO-8859-1”?>

<!DOCTYPE taglib PUBLIC “-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN” “http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd”>

<taglib>
<tlibversion>0.1</tlibversion>
<jspversion>1.1</jspversion>
<shortname>desktop</shortname>

<tag>
<name>obtainChannel</name>
<tagclass>com.sun.portal.desktop.taglib.provider.ObtainChannelTag</tagclass>
<bodycontent>JSP</bodycontent>
<attribute>
<name>channel</name>
<required>true</required>
<rtexprvalue>false</rtexprvalue>
</attribute>
</tag>
<tag>
<name>obtainContainer</name>
<tagclass>com.sun.portal.desktop.taglib.container.ObtainContainerTag</tagclass>
<bodycontent>JSP</bodycontent>
<attribute>
<name>container</name>
<required>true</required>
<rtexprvalue>false</rtexprvalue>
</attribute>
</tag>

------------clip

<tag>
<name>getContent</name>
<tagclass>com.sun.portal.desktop.taglib.provider.GetContentTag</tagclass>
<bodycontent>empty</bodycontent>
</tag>
------------clip

<!-- Utility Tag, can be used anywhere -->
<tag>
<name>scontent</name>
<tagclass>com.sun.portal.desktop.taglib.util.SContentTag</tagclass>
<bodycontent>empty</bodycontent>
</tag>
</taglib>

In Code Example D-2, the bodycontent property has a value of JSP or empty. The JSP value means that you can add more content including more Java code or JSP tags between the tag open and tag close for this particular tag. The empty value means that a tag can contain no extra content and is complete in itself.

In Code Example D-2, the required property has a value of true meaning that a value for that attribute is required. If the required property has a value of false, a value for the attribute is optional. The rtexprvalue or run time expression value means that an attribute value can be evaluated at run time or can have a hardcoded value. By default, all of the core, provider, and container tags have this value as false.

Two tags are used out of the desktopSingle.tld library. They are singleContainerProvider and obtainSelectedChannel. See Code Example D-3 for the listing of desktopSingle.tld with these two tags. The class and property information about each tag is defined here.

Code Example D-3 Listing of desktopSingle.tld


<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN" "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd">

<taglib>
<tlibversion>0.1</tlibversion>
<jspversion>1.1</jspversion>
<shortname>desktopSingle</shortname>

<!-- Validator Tag -->

<tag>
<name>singleContainerProvider</name>
<tagclass>com.sun.portal.desktop.taglib.container.single.SingleContainerProviderTag</tagcla ss>
<bodycontent>JSP</bodycontent>
</tag>

<tag>
<name>obtainSelectedChannel</name>
<tagclass>com.sun.portal.desktop.taglib.container.single.ObtainSelectedChannelTag</tagclass >
<bodycontent>JSP</bodycontent>
</tag>

</taglib>

The first tag in desktopSingle.tld is a validator tag. The validator tag ensures that the JSP using the tag library is a valid type, looking for single container information, not tab information.

Using the Desktop Tag Library in Your Application

To use the Desktop tag library within your web application, you need to set up the context properly by using the Context Setup tags (tags with the prefix obtain). See Table D-1 for the Context Setup tags.

Because it is possible to have provider(s) within a container, to access a channel within the container you would need the following (partial JSP with obtainContainer and obtainChannelFromContainer tags):

Code Example D-4 Partial JSP


<desktop:obtainContainer container="$JSPProvider">
<!-- make sure we can use the obtainChannelsFromContainer ->
<desktopcpc:containerProviderContext>
<desktopcpc:obtainChannelFromContainer channel="myChannel">
<!-- tags to operate on channel "myChannel" within the container stored as attribute "JSPProvider" in page context-->

</desktopcpc:obtainChannelFromContainer>
</desktopcpc:containerProviderContext>
</desktop:obtainContainer>

The Desktop tag library also provides an obtainParentContainer tag, which gives you access to the parent container anytime (adding the obtainParentContainer tag to the partial JSP):

Code Example D-5 Partial JSP with obtainParentContainer Tag


<desktop:obtainContainer container="$JSPProvider">
<!-- make sure we can use the obtainChannelsFromContainer ->
<desktopcpc:containerProviderContext>
<desktopcpc:obtainChannelFromContainer channel="myChannel">

<!-- tags to operate on channel "myChannel" within the container stored as attribute "JSPProvider" in page context -->

<desktopcpc:obtainParentContainer>
<!-- tags to operate on the container stored as attribute "JSPProvider" in page context -->
</desktopcpc:obtainParentContainer>

<!-- more tags to operate on channel "myChannel" within the container stored as attribute "JSPProvider" in page context -->

</desktopcpc:obtainChannelFromContainer>
</desktopcpc:containerProviderContext>
</desktop:obtainContainer>



Note	The current design does not allow multiple levels of containment hierarchy in a single JSP, thus the tag library does not support deeper nesting of the obtain tags.

Example Tab Page with Selected Channels

The following example shows how the obtainContainer, obtainChannelsFromContainer, and obtainParentContainer tags can be used in a JSP to produce a tab page with selected channels.


<desktop:obtainContainer container="$JSPProvider">
<!-- get the selected channel list and store it in attribute selectedChannel -->
<desktop:getSelectedChannels id="selectedChannel"/>
<!-- make sure we can use the obtainChannelsFromContainer ->
<desktopcpc:containerProviderContext>
<!-- loop through each channel using Jakarta forEach tag. With each iteration, the next -->
<!-- channel’s value (name of the channel) will be stored in attribute "channel" -->
<jx:forEach var="channel" items="$selectedChannel">
<desktopcpc:obtainChannelFromContainer channel="myChannel">
<!-- print out the title of this channel -->
<desktop:getTitle/>
<br>

<desktopcpc:obtainParentContainer>
<!-- make sure the container is a tab container be we use a tab container tag -->
<desktoptab:tabContainerProvider>
<!-- store the selected tab name in attribute selectedTabName -->
<desktoptab:getSelectedTabName id="selectedTabName"/>
<!-- declare selectedTabName as String using Jakarta tag, so the value can be used in the jsp -->
<jx:declare id="selectedTabName" type="java.lang.String"/>
<desktop:getName/> container has the tab <%=selectedTabName%> selected.
</desktoptab:tabContainerProvider>
</desktopcpc:obtainParentContainer>
</desktopcpc:obtainChannelFromContainer>
</jx:forEach>
</desktopcpc:containerProviderContext>
</desktop:obtainContainer>

The desktop:getSelectedChannels id="selectedChannel"/ tag provides an example of an empty bodycontent property. The jx:forEach var="channel" items="$selectedChannel" tag is a function from one of the JSP Standard tag libraries included with the Portal Server software.

Tag Overview

This section describes the tag attributes and exceptions.

Attributes and Return Values

You can pass two kinds of attributes to the Desktop library tags:

String - The simplest way to pass in an attribute is to specify it as a string, for example:

<dt:sometag attribute1="myAttribute"/>

The string myAttribute becomes the value of attribute1. If a tag expects an integer attribute, use the following:

<dt:sometag attribute1="12345"/>

The tag uses the corresponding Java classes (java.lang.Integer) to translate the string to an integer value. The same applies to all the primitive Java types (boolean, int, and so on).

Reference - Sometimes you cannot pass in an attribute as a string. For example, it is impossible to specify a provider object as a string. In this case, the attribute needs to be passed in as a reference defined in the pageContext. You do so by concatenating the character $ with the name of the object stored in the pageContext, for example:

<dt:sometag attribute1="$myAttribute"/>

In this example, the value of attribute1 is whatever object is stored in the pageContext. The method pageContext.findAttribute( ) is used, not getAttribute(). So it is possible to define some value in the request object and pass this object in as a reference.



Note	This mechanism is the main form of communication between tags in the Desktop tag library as well as other tags in other tag libraries (for example, jsptl).

Tags with attributes id and scope (even if they are optional) are expected to return a value as a result of using the tags. Values can be “returned” in two ways:

Print to the JspWriter stream - If the attribute id is not given when using a tag, the tag prints the value to the JspWriter stream. This results in the value showing up in the HTML code generated by the JSPs. In this case, the attribute scope is ignored.

Store the value in pageContext - If you specify the attribute id when using a tag, the tag stores the value to the pageContext as an attribute with a name specified by the id attribute. This operation overwrites whatever original value the attribute has. In addition to the id, you can also define the attribute scope. It can have one of the following values: page, request, session, or application. These values correspond to the PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, and APPLICATION_SCOPE defined in javax.servlet.jsp.PageContext. This specifies the scope in which to save the value. If no or unrecognized scope is given, the default is to save it in page scope.

Tag Library Exceptions

The tag library provides five types of exceptions:

Invalid Tag Sequence - Occurs when obtain tags are nested in an invalid sequence. See Using the Desktop Tag Library in Your Application for the sequencing of the obtain tags. The name of the first tag that violates the sequence is provided.

Invalid Provider Type - Occurs when a validation test is not passed. That is, the TLD does not support the current provider in the context. The name of the validator tag that failed is provided.

Invalid Parameter - Occurs when an attribute passed in with the tag is not a legal parameter for the tag. The name of the attribute that causes the problem is provided.

Undefined Parameter - Occurs when an attribute is passed in as reference, but the attribute is not defined in the page context. The name of the attribute is provided.

Empty Context - Occurs when there is no container or provider in the context to operate on. Most likely, the appropriate obtain tag is missing so the context is not set up properly.

Tag Reference

Essentially, the Desktop tag library is a wrapper of the PAPI, the ProviderContext, and ContainerProviderContext interfaces, and the specific table containers in Portal Server software. The tags in the Desktop tag library fall into three basic groups: context setup tags, validator tags, and normal tags.

Context Setup Tags

These tags, which start with the prefix obtain, set up the context (storing the container or provider in question into the pageContext). Whatever tag operation that happens within these tags is done on the provider that is set in the context.

Table D-1 describes the context setup tags in the tag libraries. The table has four columns: the first column lists the tag name, the second describes what the tag does, the third column gives what TLD file the tag is in, and the fourth lists that tag’s attributes with brief comments.

All the context setup tags contain a value of JSP for the bodycontent tag.

Table D-1 Context Setup Tags
Tag Name	Description	in TLD File	Attributes/Descriptions
obtainChannel	Gets channel object.	desktop.tld	channel (required) - the name of the channel
obtainContainer	Gets container object.	desktop.tld	container (required) - the name of the container
obtainParentContainer	Gets the parent container name.	desktopContainerProviderContext.tld	none
obtainChannelFromContainer	Gets the channel name.	desktopContainerProviderContext.tld	channel (required) - the name of the channel
obtainSelectedChannel	Gets the selected channel name.	desktopSingle.tld	none
obtainTab	Gets the tab object.	desktopTab.tld	tab (required) - the name of the tab
obtainTabByName	Gets the tab name.	desktopTab.tld	name (required) - the name of the tab

Validator Tags

These tags validate that the provider in context can legally use the tags in the TLD. Each TLD, with the exception of desktop.tld, has a validator tag defined (usually with the name of the TLD file). If the provider in context cannot use the tags defined in the TLD, an exception is thrown that is displayed on the screen and processing stops.

Users should surround tags that belong to a specific TLD with the respective validator tag. However, it is not possible to enforce that in a JSP environment. To make it easier for users to “guess” which TLD they can use or to debug the JSPs, getProviderClassName() and getContainerClassName() tags are provided in the desktop.tld. They return the class name of the container or provider in the context.

The following is a two column table: column one lists the tag name; column two provides a brief description.


providerContext	Validates that the provider in the context can legally use the tags in desktopproviderContext.tld.
containerProviderContex t	Validates that the provider in the context can legally use the tags in desktopcontainerProviderContext.tld.
singleContainerProvider	Validates that the provider in the context can legally use the tags in desktopSingle.tld.
obtainSelectedChannelFr omRequest	Gets the channel name from request. This tag is in desktopSingle.tld.
tableContainerProvider	Validates that the provider in the context can legally use the tags in desktopTable.tld.
tabContainerProvider	Validates that the provider in the context can legally use the tags in desktopTab.tld.

Normal Tags

These tags serve as wrappers of PAPI, ProviderContext, ContainerProviderContext, and the specific containers in the Portal Server software.

For the remaining part of this chapter, unless specified, “tag” refers to the normal tag in the Desktop tag library.

Table D-2 through Table D-7 describe the normal tags in the tag libraries. Each table has three columns: the first column lists the tag name, the second a description of the tag’s function, and the third column lists that tag’s attributes with brief comments.

The tables are:

Table D-2 - desktop.tld

Table D-3 - desktopProviderContext.tld

Table D-4 - desktopContainerProviderContext.tld

Table D-5 - desktopTab.tld

Table D-6 - desktopTable.tld

Table D-7 - desktopTheme.tld

Search Tags - search.tld



Note	The desktopSingle.tld tag library has no normal tags.

All of the normal tags in the desktop.tld file have a bodycontent of empty.

Table D-2 desktop.tld Normal Tags with Attributes
Tag Name	Description	Attributes/Descriptions
getProviderClassName	Returns the class name of the provider that backs the channel.	id (optional) scope (optional)
getContent	Returns a string buffer with the contents of the provider’s object’s default view. This method is called by the clients of the provider object to request the provider’s default view. This method may return null if the provider does not implement a default view. In this case, the provider should return false from its isPresentable() method.	none
getTitle	Returns a string with the title of the channel.	id (optional) scope (optional) silentException (optional)
getDescription	Returns a string with the description for the channel.	id (optional) scope (optional) silentException (optional)
getEdit	Returns a string buffer with the provider’s Edit page.	id (optional) scope (optional)
getHelp	Returns the help URL for this provider. The returned help URL can be either fully qualified URL string (http://server:port/portal/docs/en/desktop/usedesk.htm) or a relative path (desktop/usedesk.htm). When it is a relative path, the Desktop software resolves it to the full URL.	id (optional) scope (optional) silentException (optional)
getName	Returns a string with the name of the provider, which must match the name of the provider the channel was initialized with.	id (optional) scope (optional)
getRefreshTime	Returns a long with the refresh time for this provider in seconds. Use this value to determine if you should fetch a fresh default view for the provider. If the return value from this method is X, you may choose not to fetch fresh content (and use a cached copy instead) if less than X seconds has elapsed since the last time the content was refreshed. If provider content is expected to change infrequently, this method can return some value so that the provider’s content is not fetched every time the front page is drawn, thereby saving significant processing time.	id (optional) scope (optional)
getWidth	Returns an integer with the suggested width for the channel to the container of the channel as to how much screen real estate it requires. The values correspond to thick, thin, full top and full bottom.	id (optional) scope (optional) silentException (optional)
getEditType	Returns an integer that defines edit type either EDIT_SUBSET or EDIT_COMPLETE.	id (optional) scope (optional)
isEditable	Returns a Boolean that gives the editable status of the channel. Returns true if the channel is editable; otherwise false.	id (optional) scope (optional)
isPresentable	Returns a Boolean that gives the presentable status for a channel. Returns true if the channel is presentable. Searches for the key HTML with the value true on the client data for the session’s client type and returns true. If there is no such key, the method returns true if the session’s client type is named HTML. In both cases, the content-type for the session’s client type must equal text/html in order for the method to return true.	id (optional) scope (optional)
processEdit	Performs the provider’s Edit page processing. Processes a form for this provider. This method is called to process form data associated with the provider. Typically, this method is called to process the Edit page generated from the getEdit() method. Usually, the client calling this method on a provider object is the desktop servlet. Form data that is passed into this method in the request has been decoded into Unicode.	id (optional) scope (optional)
getContainerClassName	Returns the class name of the container that backs the container.	id (optional) scope (optional)
getSelectedChannels	Returns a list of selected channel names. The list returned is a Collection of Strings. Each of the Strings is the name of a channel that has been selected.	id (required) scope (optional)
getAvailableChannels	Returns a list of available channel names. The list returned is a Collection of Strings. Each of the Strings is the name of a channel that is available.	id (required) scope (optional)
scontent	Returns the URL of the directory that has the static content (for example, images and style sheet). This utility tag can be used anywhere.	none

All of the normal tags in the desktopProviderContext.tld file have a bodycontent of empty.

Table D-3 desktopProviderContext.tld Normal Tags with Attributes
Tag Name	Description	Attributes/Descriptions
getStringProperty	Returns a string with the property value. This is an overloaded method that can return alternately the default or localized version of the property value.	key (required) - the name of the property localized (optional) id (optional) scope (optional) pflist (optional)
getBooleanProperty	Returns a Boolean that gives the value of the property.	key (required) - the name of the property id (optional) scope (optional) pflist (optional)
getCollectionProperty	Returns a Java Map with the collection property. Here, a collection refers to a multi-value property. Depending on the context, it is either the analogue of Java Maps or Lists. For Lists, the returned Java Map object contains key-value pairs where the key equals the value. This is an overloaded method that can return alternately the default or localized version of the collection property.	key (required) - the name of the property id (optional) scope (optional) pflist (optional)
getIntegerProperty	Returns an integer with the integer property. This method returns a default value if the property does not exist.	key (required) - the name of the property id (optional) scope (optional) pflist (optional)
getProperty	Returns a Java Object with a property. The value returned from this method is a Java Object of type String, Integer, Boolean, or Map. If the property does not exist, then the default value is returned.	key (required) - the name of the property id (optional) scope (optional)
setStringProperty	Sets a string property.	key (required) - the name of the property value (required) - the value of the property to be set pflist (optional)
setBooleanProperty	Sets a Boolean property.	key (required) - the name of the property value (required) - the value of the property to be set pflist (optional)
setCollectionProperty	Sets a collection property.	key (required) - the name of the property value (required) - the value of the property to be set pflist (optional)
setIntegerProperty	Sets an integer property.	key (required) - the name of the property value (required) - the value of the property to be set pflist (optional)
getLocalePropertiesFilters		id (required) scope (optional)
getClientPropertiesFilters		id (required) scope (optional)
getClientAndLocalePropertiesFilters		id (required) scope (optional)
getClassName	Returns a string with the class name for the provider class that this object is providing an environment for. The class name returned must implement the provider interface. This method is used to construct the provider object. It is used by container channels.	id (optional) scope (optional)
getTemplate	Returns a string buffer with the desktop template. The actual template buffer returned is based on the Desktop type, locale, channel, client type, and the template name.	file (required) - name of template to return table (optional) - hashtable - tag table used for tag swapping id (optional) scope (optional)
getDesktopURL	Returns a string with the Desktop URL. The Desktop URL is the absolute URL used to access the Desktop application. For example: http://server:port/portal/dt. The request object parameter is included to facilitate implementations. It may be used to build the Desktop URL by supplying the server, port, and protocol of the request. It is not required that the request object be utilized to generate the Desktop URL.	querymap (optional) querystring (optional) pathinfo (optional) escape (optional) id (optional) scope (optional)
getDesktopType	Returns a string with the Desktop type. The Desktop type, also known as template type, is a string that is one of several indexes used to lookup Desktop templates and JSP files. The Desktop type is typically used to group Desktop customization files to provide different themes.	id (optional) scope (optional)
getLocaleString	Returns a string representation of the locale.	id (optional) scope (optional)
getLocale	Returns Java Locale object representation of the locale.	id (optional) scope (optional)
getLogoutURL	Returns a string with the logout URL. The result of making a connection to the logout URL is typically the termination of the user’s session. What actually happens is dependent on the application receiving the URL connection. Providers may use this value to generate links that allow the user to end their session.	id (optional) scope (optional)
getStringAttribute	Returns a string with the value of the string attribute or null if the attribute is not found. Attributes are settings that are not channel-specific. An example of an attribute might be the user’s first and last name. Channel-specific settings are called properties. Properties can be retrieved by calling the get*Property() methods. Whether a particular value is considered a property or an attribute depends on the underlying implementation of ProviderContext.	key (required) - the name of the attribute id (optional) scope (optional)
setStringAttribute	Sets a string attribute. Attributes are settings that are not channel-specific. An example of an attribute might be the user’s first and last name. Channel-specific settings are called properties. Properties can be set by calling the set*Property() methods. Whether a particular value is considered a property or an attribute depends on the underlying implementation of ProviderContext.	key (required)- the name of the attribute value (required) - the value of the attribute
getClientTypeProperty		key (required) clientType (optional) id (optional) scope (optional)
getClientType	Returns a string with the client type. There is no requirement as to how the client type is determined. It may be hardcoded, derived from the session, or otherwise.	id (optional) scope (optional)
getDefaultClientType	Returns a string with the default client type.	id (optional) scope (optional)
getCharset	Returns a string with the character set. The character set is used for decoding input and encoding output.	id (optional) scope (optional)
getClientPath	Returns a string with the client path. The client path is one of several components used to lookup Desktop templates and JSPs.This allows the lookup to be client-specific.	id (optional) scope (optional)
getContentType	Returns a string with the content type. This value is used to determine if a provider is able to produce content for the client’s device.	id (optional) scope (optional)
getSessionID	Returns a string with the unique session identifier. The format of the return value is implementation specific. The only guarantee is that it is unique (each user session has a unique session ID).	id (optional) scope (optional)
getUserID	Returns a string with the user identifier. The format of the return value is implementation specific. There is no guarantee that this value is unique (there may be multiple user sessions for a given user identifier).	id (optional) scope (optional)
setClientProperty	Sets a client property.	name (required) - the name of the property value (required) - the value of the property to be set
getClientProperty	Returns a string with the client property.	name (required) id (optional) scope (optional)
isLogMessageEnabled	Returns a Boolean; true if the log level is set to message or higher; otherwise false.	id (optional) scope (optional)
isLogWarningEnabled	Returns a Boolean; true if the log level is set to warning or higher; otherwise false.	id (optional) scope (optional)
logError	Logs a message (any Java Object) if the logging level is error. The location to store logging messages is implementation dependent.	value (required) - message to log throwable (optional)
logMessage	Logs a message (any Java Object) if the logging level is message or higher. The location to store logging messages is implementation dependent.	value (required) - message to log throwable (optional)
logWarning	Logs a message (any Java Object) if the logging level is warning or higher. The location to store logging messages is implementation dependent.	value (required) - message to log throwable (optional)
getDefaultChannelName	Returns a string with the default channel name.	id (optional) scope (optional)
getTopChannelName	Returns the top channel name for the current request.	id (optional) scope (optional)
getStaticContentPath	Gets the URI prefix to web server static content.	id (optional) scope (optional)
getProviderVersion	Get the version of the provider schema for the current channel.	id (optional) scope (optional)
encodeURLParameter	URL encodes a unicode string.	id (optional) scope (optional) key (required)
decodeURLParameter	Decodes the URL encoded Unicode string. This tag just returns back the original string passed in.	id (optional) scope (optional) key (required)
encodeURL	Encodes a URL. Rewrites the URL to include the session id.	url (required) id (optional) scope (optional)
escape	Escapes a String using an encoder class that encodes a specific type of markup. This tag is used to allow provider code to encode content in a device-unaware manner.	id (optional) scope (optional) unescaped (required)

The normal tag in the desktopContainerProviderContext.tld file has a bodycontent of empty.

Table D-4 desktopContainerProviderContext.tld Normal Tags with Attributes
Tag Name	Description	Attributes/Descriptions
getContent	Returns a string buffer with the content of the named channel. This method is provided for convenience. It gets the provider object for the named channel and calls Provider.getContent().	channel (required) - the name of the channel id (optional) scope (optional)

All of the normal tags in the desktopTab.tld file have a bodycontent of empty.

Table D-5 desktopTab.tld Normal Tags with Attributes
Tag Name	Description	Attributes/Descriptions
getAvailableTabs	Returns a list of available tabs. The list returned is a Collection of Strings. Each of the Strings is the name of an Unmodifiable Tab that is available.	id (optional) scope (optional)
getSelectedTabs	Returns the list of selected tabs. The list returned is a Collection of Strings. Each of the Strings is the name of an Unmodifiable Tab that is selected.	id (optional) scope (optional)
getSelectedTab	Returns the selected tab, the current selected Unmodifiable Tab in the user’s session.	id (optional) scope (optional)
getMakeTab	Returns the make tab, the tab spec to be used for “Make My Own tab” creation by the user.	id (optional) scope (optional)
getStartTabNam	Returns a string with the start tab Name, the name of the tab to be displayed when the user logs in.	id (optional) scope (optional)
getSelectedTabName	Returns a string with the selected tab Name, the current selected tab in the user’s session.	id (optional) scope (optional)
getTabURL	Returns the Tab URL. This method gets the tab URL used to switch the selected tab on the user’s desktop.	id (optional) scope (optional)
getName	Returns a string with the name of the tab.	id (optional) scope (optional)
getDesc	Returns a string with the description of the tab.	id (optional) scope (optional)
getDisplayName	Returns a string with the display name of the tab.	id (optional) scope (optional)
getEncodedName	Returns a string with the HTML encoded name of the tab.	id (optional) scope (optional)
isPredefined	Determines whether the tab is predefined or not and returns a boolean that gives the predefined status of a tab.	id (optional) scope (optional)
isRemovable	Returns a Boolean that gives the removable status of the tab. Returns true if the tab is removable; otherwise false.	id (optional) scope (optional)
isRenamable	Returns a Boolean that gives the renamable status of the tab. Returns true if the tab is renamable; otherwise false.	id (optional) scope (optional)

All of the normal tags in the desktopTable.tld file have a bodycontent of empty.

Table D-6 desktopTable.tld Normal Tags with Attributes
Tag Name	Description	Attributes/Descriptions
getColumns	Returns a list of channel names that belong in that particular column.	column (required) id (required)
getColumnWidth	Returns the width of a column (a percentage with respect to the entire Desktop). Valid columns are left, center, and right.	column (required) id (optional)
getHasFrame	Returns a Boolean that gives the frame status of the channel. Returns true if the channel has a frame; otherwise false.	id (optional) scope (optional)
getIsMinimized	Returns a Boolean that gives the minimized status of the channel. Returns true if the channel is minimized; otherwise false.	id (optional) scope (optional)
getIsMovable	Determines whether the channel is movable or not and returns a Boolean that gives the movable status of a channel.	id (optional) scope (optional)
getProviderCommand	Gets the HTML code needed to display the provider commands (minimize channel, help screen, edit channel, and so forth). The commands are put in a Map. The keys for the Map are minMaximizedCommand, helpCommand, editCommand, detachAttachCommand, and removeCommand.	id (optional) scope (optional)
getIsDetached	Returns a Boolean that gives the detached status of the channel. Returns true if the channel is detached; otherwise false.	id (optional) scope (optional)
getDetached	Returns the detached channels list. The list returned is a Collection of Strings. Each of the Strings is the name of a channel. The channels returned are not necessary channels that have been detached from the desktop. The tag getIsDetached should be used to verify that a channel has been detached.	id (required) scope (optional)
getWindowName	Returns a string with the window name for the detached window when a channel is detached.	id (optional) scope (optional)
isPopup	Determines whether the page is being drawn for a popup channel. Returns true if the table container action is a popup and returns false otherwise.	id (optional) scope (optional)
getPopupWindowWidth	Returns an integer with the popup window width for the detached window when a channel is detached.	id (optional) scope (optional)
getPopupWindowHeight	Returns an integer with the popup window height for the detached window when a channel is detached.	id (optional) scope (optional)
getContents	Returns a string buffer with the contents of all non-minimized and selected channels of the table container. The contents are put in a Map with the channel name as the key.	id (required) scope (optional)

All of the normal tags in the desktopTheme.tld file have a bodycontent of empty.

Table D-7 desktopTheme.tld Normal Tags with Attributes
Tag Name	Description	Attributes/Descriptions
getGlobalThemes	Returns the list of globally defined themes. The list returned is a Collection of Strings. Each of the Strings is the name of a globally defined theme.	id (required) scope (optional)
getSelectedName	Returns the name of the selected theme. The name returned can be the name of one of the globally defined themes or CustomTheme. If CustomTheme is returned, this means the user has defined and is using the custom defined theme.	id (optional) scope (optional)
setSelectedName	Sets a theme for the current user. The theme to be set can be one of the globally defined themes or a CustomTheme.	value (required) - the name of the theme set
getAttribute	Returns the value of a theme attribute. Get a specific attribute value of a specific theme.	name (required) - the name of the attribute. Possible values are: bgColor, borderColor, titleBarColor, fontColor, borderWidth and fontFace theme (optional) - the name of the theme. If this is not specified, the currently selected theme is used. requestOverride (optional) true or false - Whether to use value in the request to override the theme value. If this is not specified, false is assumed. This is useful in the preview case. id (optional) scope (optional) default - the default value. If getAttribute() of a theme returns null, and a default value is defined in the tag, then return the default value.
setCustomAttribute	Sets a customized value in the CustomTheme	name (required) - the name of the attribute. Possible values are: bgColor, borderColor, titleBarColor, fontColor, borderWidth and fontFace value (required) - the value to be set

Search Tags

The Search tag library contains tag wrappers for the SearchContext Java API. SearchContext is an extension of the Search API with convenient methods for advanced search and search result status. The Search tag library can be divided into various categories depending upon where the tags should be used.

Table Table D-8 through Table D-12 describe the normal tags in the Search tag library. Each table has three columns: the first column lists the tag name, the second a description of the tag’s function, and the third column lists that tag’s attributes with brief comments. The tables are:

Table D-8 - searchContext tag

Table D-9 - tags used before a search

Table D-10 - executeSearch tag

Table D-11 - tags related to Search results

Table D-12 - miscellaneous tags

The search.tld does not have any context setup or validator tags. All of the normal tags in the search.tld file have a bodycontent of empty except searchContext and SOIF.

A number of attributes have a value of true for rtexprvalue, which means the value for this attribute can be obtained at run time or it can be hardcoded. These attributes are listed as dynamic attributes.

Table D-8 searchContext Tag
Tag Name	Description	Attributes/Descriptions
searchContext	Main outer tag that encloses all other tags.	bodycontent - JSP rdmServer (optional) - search server - http://.../portal/search or https://../portal/search rdmType (optional) - rd-request (default), taxonomy-request, schema-request, server-request or status-request ql (optional) - query language query (optional) - dynamic attribute

The tags in Table D-9 are normally used before executing a search. Before a successful search can be executed these tags must set a value:

setRDMServer

setRDMType

setQuery or setCriteria

Table D-9 Pre-Search Tags in search.tld
Tag Name	Description	Attributes/Descriptions
setRDMServer	Sets the RDMServer variable. The server URL should be set explicitly. Format: http:// or https://hostname:port/portal/search Value has to be set.	rdmServer (required) - server URL; can be an expression or a hardcoded string value.
setRDMType	Sets the RDM Request type. RDMType - Can be one of: rd-request: The default request type. Resource descriptions (documents). taxonomy-request: Taxonomy. schema-request: The schema. server-request: Server information. status-request: Server status information. Set value explicitly; the default set by the system may not return the expected results.	rdmType (required) - string
setViewAttributes	Sets the SOIF attributes that are returned for the search. This is an optional tag. It assumes the default values if not set explicitly.	viewAttributes (required) - string: null (all) or comma delimited list of attributes.
setSessionID	The Search Server needs to validate the user’s identity for document level security. This tag is a wrapper for setSessionID(String) method in SearchContext. The JSP gets the portal access Token string and passes it along to the search server using this tag.	sessionID (required) - string
setViewHits	Sets the maximum number of hits returned.	viewHits (required) - integer - dynamic attribute
setViewOrder	Sets the sorting order for results.	viewOrder (required) - string: null or comma delimited list of attributes each proceeded with + for ascending order or - for descending order.
setCategory	Sets the category id. It is mainly required for browsing and category searches. The category is appended to the query string based on the RDMType and query language in the executeSearch tag.	category (required) - string: current category level; if not set, the root of the taxonomy tree is used and the search is executed for all categories.
setFirstHit	setFirstHit takes a string input. Sets the starting hit for search results. In other words, start from 1, start from 11 and so forth. It corresponds to the setFirstHit() method in the Search API. Results are returned from this hit. This is an optional tag. Alternately you can use setPage and setViewHits.	fromHit (required) - integer
setQuery	Query string. Either this value has to be set or else setCriteria has to be set.	query (required) - string - dynamic attribute
setDatabase	Has a string attribute. Default value is ‘’, which means use berkeley db. Database should be specified if berkeley db should not be used.	database (required) - string - dynamic attribute
setPage	Sets the current page value. The page value is used to calculate the firstHit and totalPages.	page (required) - integer - dynamic attribute
setSearchAll	Set searchAllCategories or not. If the search is within a particular category then set it to false; else set it to true. Default is true.	searchAll (required) - Boolean
setQueryLanguage	Sets the query language. ql - Can be one of: search: The default Search query language. Searches documents or the taxonomy. taxonomy-basic: Used for requesting branches or parts of the taxonomy. schema-basic: Queries the Compass schema. url: Retrieves RDs by URL (scope=url).	ql (required) - string
setCriteria	Sets the query string in a list format. Useful in advanced search. The list should have an operand, operator and a value. The list of valid operator’s are defined in the SearchContext API. The operand can be a schema field. The user can bypass this tag and just use the setQuery tag directly by converting a complex query into the syntax that the search engine requires. The setCriteria tag is a wrapper for the setScope(list) method in the searchContext API. This method basically parses the list and converts it into a string. For example, author CONTAINS xyz. This produces a query. Either this value has to be set or else setQuery has to be set.	criteria (required) - string - dynamic attribute

The executeSearch tag in Table D-10 executes the search.

Table D-10 executeSearch Tag
Tag Name	Description	Attributes/Descriptions
executeSearch	Tag for the execute method in SearchContext API. Executes search after doing some validation of the search parameters and query string.	none

The tags in Table D-11 are related to search results and are used after a search is executed. They provide various counts and help display the search results.

Table D-11 Post Search Tags in search.tld
Tag Name	Description	Attributes/Descriptions
SOIF	Wrapper for SOIF API.	bodycontent - JSP input (required) -SOIF document
getSoifResult	Returns SOIF type object.	id (optional) scope (optional)
getValue	Returns a string value of the attribute or returns a string value of a multivalue attribute with index. Wrapper for SOIF API. This tag must be used within the SOIF tag.	soifAttribute (required) - string - attribute name escape (optional) id (optional) scope (optional) truncate (optional) - specifies the number of characters to display in the title
getURL	Returns a string with the SOIF URL. Wrapper for SOIF API. This tag must be used within the SOIF tag.	escape (optional) id (optional)
getHasNextPage	Returns true if there are more hits for the next page by considering the values of viewHits and the current page.	id (optional) scope (optional)
getHasPreviousPage	Returns true if there is a previous page. Value based on viewHits and current page value.	id (optional) scope (optional)
getNoHits	Returns true if no matching hits were found. This is a convenience tag.	id (optional) scope (optional)
getHitCount	Returns the total number of results that matched the query.	id (optional) scope (optional)
getToHit	Returns the last hit being displayed on a page. The value is based on firstHit and viewHits.	id (optional) scope (optional)
getPage	Returns the current page. If the value is not set, calculates the page based on viewHits and firstHit.	id (optional) scope (optional)
getTotalDocuments	Returns the total number of documents in the database.	id (optional) scope (optional)
getTotalPages	Returns the total number of pages of hits that are available. The value is calculated from viewHits and hitCount.	id (optional) scope (optional)
getResultCount	Returns the number of results returned by the search. Returns -1 for an error.	id (optional) scope (optional)

The tags in Table D-12 are used for debugging.

Table D-12 Miscellaneous Tags in search.tld
Tag Name	Description	Attributes
getSearchString	Returns a string with a the search query being executed. Good for debugging.	id (optional) scope (optional)
getCategory	Returns a string with the current category name or else set to root.	id (optional) scope (optional)
getFirstHit	Returns the starting hit being displayed.	id (optional) scope (optional)
getSessionID	Returns a string with a user’s session id. It has no value unless previously set.	id (optional) scope (optional)
getQuery	Returns the query string; returns an empty string if not set.	id (optional) scope (optional)
getViewHits	Returns viewHits, an integer that defines the maximum number of hits returned (range 0-100). The default value is 8 if not set or set outside of range.	id (optional) scope (optional)

Search Exceptions

When you are developing JSPs or doing Search administration tasks, you may see the following exceptions:

Taglib Use Errors:

Invalid Tag Sequence: Must be within a searchContext Tag

Variable Undefined in Page Context

Invalid nesting of context

Error in creating search context

Search Request Errors:

Search server is not defined

View Hits cannot be 0

RDM Type must be defined

Query Language must be defined



Tip	When debugging, if you receive unusual exceptions, check that the search server is set and its format is correct and has no typographical errors.

Example of a Search JSP

Code Example D-6 Sample Search JSP


<%--
Copyright 2002 Sun Microsystems, Inc. All rights reserved.
PROPRIETARY/CONFIDENTIAL. Use of this product is subject to license terms.
--%>

<!-- @(#)searchContent.jsp -->

<%@page language= "java" import="com.sun.portal.search.providers., java.lang., java.util., java.text." %>
<%@page errorPage="error.jsp" %>

<%@ taglib uri="/tld/search.tld" prefix="search" %>
<%@ taglib uri="/tld/desktop.tld" prefix="dt" %>
<%@ taglib uri="/tld/desktopProviderContext.tld" prefix="dtpc" %>

<B>Test 1: </B><BR>
<dt:obtainChannel channel="$JSPProvider">
<dtpc:providerContext>

<search:searchContext>
<%--<search:setQueryLanguage ql= "search"/> --%>
<search:setQuery query= "java"/>
<%--<search:setRDMType rdmType= "rd-request"/>--%>
<search:setRDMServer rdmServer= "http://milonga1.sesta.com:80/portal/search"/>
<search:setViewAttributes viewAttributes= "url,title,description,score,content-length,classification"/>
<search:setViewHits viewHits= "10"/>
<search:setPage page= "1"/>

<dtpc:getSessionID id = "accessToken"/>
<search:setSessionID sessionID="$accessToken"/>

<search:executeSearch/>

<UL>
<LI><search:getSearchString/>
<LI>Query = <search:getQuery/>
<LI>resultCount = <search:getResultCount/>
<LI>hitCount = <search:getHitCount/>
<LI>total Documents = <search:getTotalDocuments/>
<LI>total Pages = <search:getTotalPages/>
<LI>hasnoHits= <search:getNoHits/></UL>

</search:searchContext>
</dtpc:providerContext>
</dt:obtainChannel>

<B>Test 2: </B><BR>
<search:searchContext query="*" rdmType="rd-request" ql="search" rdmServer="http://milonga1.sesta.com:80/portal/search">
<search:setViewHits viewHits= "10"/>
<search:executeSearch/>
<UL><LI>Query = <search:getQuery/>
<LI>resultCount = <search:getResultCount/></UL>
</search:searchContext>

<B>Test 3: </B><BR>
<search:searchContext query="*" rdmType="rd-request" ql="search" rdmServer="http://milonga1.sesta.com:80/portal/search">
<search:setFirstHit firstHit= "21"/>
<search:setViewHits viewHits= "10"/>
<search:executeSearch/>
<UL><LI>Query = <search:getQuery/>
<LI>Page = <search:getPage/>
<LI>resultCount = <search:getResultCount/></UL>
</search:searchContext>

Instant Messaging Tags

The IMProvider content page uses a custom tag library defined in a file called im.tld which is installed into the /etc/opt/SUNWps/desktop/default/tld directory. The im.tld file defines the following tags:

Table D-13 Tags in im.tld
Tag Name	Description	Attributes
getContactGroups	Returns list of contact groups that the user has defined. The list is returned as a Collection of Strings where each String is the display name for a contact group.	id (optional) scope (optional)
getContactGroup	Returns the list of contacts in the named contact group. The list is returned as a Collection of internal objects that can be passed to the obtainContact tag.	group (required) - The name of the contact group. id (optional) scope (optional)
getUsername	Returns the instant messaging username for the user.	id (optional) scope (optional)
getToken	Returns the login token for the user (either an Identity Server software SSOToken or the user’s password.)	id (optional) scope (optional)
obtainContact	A context setup tag that is used to obtain the presence information for the indicated contact. The remaining tags can be used inside this tag.	contact (required) - The internal identifier of the contact, typically obtained from the getContactGroup tag.
getContactPresence	Returns the current presence status for the contact. The status can be: AWAY, BUSY, CLOSED, FORWARDED, IDLE, OPEN, OTHER. These are from the PresenceSession class in the instant messaging API.	id (optional) scope (optional)
getContactName	Return the common name for the contact.	id (optional) scope (optional)
getContactUsername	Returns the instant messaging user name for the contact.	id (optional) scope (optional)
getDateTime	Returns the update time.	format (required) id (optional) scope - (optional)
isSecureMode	Returns boolean indicating whether the channel is being accessed via the Secure Remote Access Gateway component and the Netlet is loaded.	id (optional) scope (optional)
getCodebase	Returns the codebase to use to download the applet. This takes into account whether the channel is being accessed via the Secure Remote Access Gateway component and the Netlet is loaded.	id (optional) scope (optional)
getIMServer	Returns the -server argument to pass to the IM client. This takes into account whether the channel is being accessed via the Secure Remote Access Gateway component and the Netlet is loaded.	id (optional) scope (optional)

The entire interface to the Instant Messaging server APIs is in the getContactGroup tag. This tag will fetch all of the presence information and cache it in the request. The remaining tags will simply fetch the information out of the cache.

Previous Contents Index Next

Previous Contents Index Next
Sun Java System Portal Server 6 2004Q2 Desktop Customization Guide