Sun ONE Portal Server 6.0 Desktop Customization Guide: Appendix B JavaServer Pages Tag Library Reference

Previous Contents Index Next

Sun ONE Portal Server 6.0 Desktop Customization Guide

Appendix B 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 Reference

Tag Overview
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/jsptl-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.
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™ ONE Portal Server 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.

desktopProviderContext.tld - Contains tags to operate on providers that extend the ProviderAdapter class.

desktopContainerProviderContext.tld - Contains tags to operate on container providers that extend the JSPContainerProviderAdapter interface.

desktopSingle.tld - Contains tags for the SingleContainerProvider class.

desktopTable.tld - Contains tags for the TableContainerProvider class.

desktopTab.tld - Contains tags for TabContainerProvider class.

desktopTheme.tld - Contains tags for theme support in the Desktop.

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 /opt/SUNWps/web-apps/https-instancename/portal/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 Sun ONE Portal Server. 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 B-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 B-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=""> 



 <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.

<%@ 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" for more information).
Three tags are used out of the desktop.tld library. They are obtainContainer, scontent, and getContent. See Code Example B-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 B-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



 

 <tag>

 <name>scontent</name>

 <tagclass>com.sun.portal.desktop.taglib.util.SContentTag</tagclass>

 <bodycontent>empty</bodycontent>

 </tag>

</taglib>

In Code Example B-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 B-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. 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 B-3 for the listing of desktopSingle.tld with these two tags. The class and property information about each tag is defined here.

Code Example B-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>

 

 <tag>

 <name>singleContainerProvider</name>

 <tagclass>com.sun.portal.desktop.taglib.container.single.SingleContainerProvid erTag</tagclass>

 <bodycontent>JSP</bodycontent>

 </tag>

 <tag>

 <name>obtainSelectedChannel</name>

 <tagclass>com.sun.portal.desktop.taglib.container.single.ObtainSelectedChannel Tag</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 B-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 B-4 Partial JSP
<desktop:obtainContainer container="$JSPProvider">

 

 </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 B-5 Partial JSP with obtainParentContainer Tag
<desktop:obtainContainer container="$JSPProvider">

 

 <desktopcpc:obtainParentContainer>

 

 </desktopcpc:obtainParentContainer>

 

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

 

 <desktop:getSelectedChannels id="selectedChannel"/>

 

 

 <jx:forEach var="channel" items="$selectedChannel">

 <desktopcpc:obtainChannelFromContainer channel="myChannel">

 

 <desktop:getTitle/>

 

 <desktopcpc:obtainParentContainer>

 

 <desktoptab:tabContainerProvider>

 

 <desktoptab:getSelectedTabName id="selectedTabName"/>

 

 <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 Sun ONE Portal Server.

Tag Reference

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 Overview

Essentially, the Desktop tag library is a wrapper of the PAPI, the ProviderContext, and ContainerProviderContext interfaces, and the specific table containers in Sun ONE Portal Server. 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 B-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 B-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.
Table B-2 is a two column table: column one lists the tag name; column two provides a brief description.

Table B-2 Validator Tags

Tag Name

Description

providerContext

Validates that the provider in the context can legally use the tags in desktopproviderContext.tld.

containerProviderContext

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.

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 Sun ONE Portal Server.
For the remaining part of this chapter, unless specified, "tag" refers to the normal tag in the Desktop tag library.
Table B-3 through Table B-13 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 B-3 desktop.tld

Table B-4 desktopProviderContext.tld

Table B-5 desktopContainerProviderContext.tld

Table B-6 desktopTab.tld

Table B-7 desktopTable.tld

Table B-8 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 B-3 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 genericHTML 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 genericHTML.
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 B-4 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)

getBooleanProperty

Returns a Boolean that gives the value of the property.

key (required) - the name of the property
id (optional)
scope (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)

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)

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

setBooleanProperty

Sets a Boolean property.

key (required) - the name of the property
value (required) - the value of the property to be set

setCollectionProperty

Sets a collection property.

key (required) - the name of the property
value (required) - the value of the property to be set

setIntegerProperty

Sets an integer property.

key (required) - the name of the property
value (required) - the value of the property to be set

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.

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

getClientProperty

Returns a string with the value of the client property for the user's client type.

key (required)- the name of the property
clientType (optional) - the name of the client type
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)

setSessionProperty

Sets a session property.

name (required) - the name of the property
value (required) - the value of the property to be set

getSessionProperty

Returns a string with the session property.

name (required) - the name of the property
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)

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

Table B-5 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 B-6 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)

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 B-7 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)

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)

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 B-8 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 _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)

setCustomAttribute

Sets an attribute of the custom theme.

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 B-9 through Table B-13 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 B-9 searchContext tag

Table B-10 tags used before a search

Table B-11 executeSearch tag

Table B-12 tags related to Search results

Table B-13 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 B-9 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 B-10 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 B-10 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://servername:port/deployment-uri/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 searchengine 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 B-11 executes the search.

Table B-11 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 B-12 are related to search results and are used after a search is executed. They provide various counts and help display the search results.

Table B-12 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)

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 B-13 are used for debugging.

Table B-13 Miscellaneous Tags in search.tld

Tag Name

Description

Attributes/Descriptions

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 B-6 Sample Search JSP
<%--

Copyright 2002 Sun Microsystems, Inc. All rights reserved.

PROPRIETARY/CONFIDENTIAL. Use of this product is subject to license terms.

--%>



<%@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" %>

Test 1: 

<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>

Test 2: 

<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>

Test 3: 

<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>

**Code Example B-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>

**Code Example B-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>

**Code Example B-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.SingleContainerProvid erTag</tagclass>
<bodycontent>JSP</bodycontent>
</tag>

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

</taglib>

**Code Example B-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>

**Code Example B-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>

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

Tag Name	Description
providerContext	Validates that the provider in the context can legally use the tags in desktopproviderContext.tld.
containerProviderContext	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.
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.

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 genericHTML 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 genericHTML. 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

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)
getBooleanProperty	Returns a Boolean that gives the value of the property.	key (required) - the name of the property id (optional) scope (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)
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)
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
setBooleanProperty	Sets a Boolean property.	key (required) - the name of the property value (required) - the value of the property to be set
setCollectionProperty	Sets a collection property.	key (required) - the name of the property value (required) - the value of the property to be set
setIntegerProperty	Sets an integer property.	key (required) - the name of the property value (required) - the value of the property to be set
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.	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
getClientProperty	Returns a string with the value of the client property for the user's client type.	key (required)- the name of the property clientType (optional) - the name of the client type 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)
setSessionProperty	Sets a session property.	name (required) - the name of the property value (required) - the value of the property to be set
getSessionProperty	Returns a string with the session property.	name (required) - the name of the property 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)

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)

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)
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)

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)
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)
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)

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 _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)
setCustomAttribute	Sets an attribute of the custom theme.	name (required) - the name of the attribute. Possible values are: bgColor, borderColor, titleBarColor, fontColor, borderWidth and fontFace value (required) - the value to be set

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

Tag Name	Description	Attributes/Descriptions
setRDMServer	Sets the RDMServer variable. The server URL should be set explicitly. Format: http:// or https://servername:port/deployment-uri/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 searchengine 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

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

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)
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)

Tag Name	Description	Attributes/Descriptions
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)

**Code Example B-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>

Previous Contents Index Next
Copyright 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated August 29, 2002