Sun Java System Portal Server 6 2004Q2 Desktop Customization Guide |
Appendix D
JavaServer Pages Tag Library ReferenceThis 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:
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 OverviewIn 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.
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 JSPsIn 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.
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" %>
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 OverviewThis section describes the tag attributes and exceptions.
Attributes and Return Values
You can pass two kinds of attributes to the Desktop library tags:
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"/>
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 ReferenceEssentially, 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:
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:
Search Request 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.