com.sun.portal.providers.jsp
Class JSPProvider

java.lang.Object
  |
  +--com.sun.portal.providers.ProviderAdapter
        |
        +--com.sun.portal.providers.ProfileProviderAdapter
              |
              +--com.sun.portal.providers.jsp.JSPProvider

All Implemented Interfaces:

Provider, ProviderEditTypes, ProviderWidths

Direct Known Subclasses:

JSPContainerProviderAdapter

public class JSPProvider

extends ProfileProviderAdapter

A JSPProvider is a content provider that can use JavaServer Pages (JSPs) to create the content for a channel on the desktop.

A provider is responsible for providing the HTML content for a channel as well as defining the various attributes for a channel (title, description, etc.) and optionally implementing edit functionality (one or more edit pages and the logic for processing changes to the channel).

JavaServer Pages is a alternative technology for defining web pages that provides several advantages over Java servlet development. These same advantages apply to the idea of developing Portal Server desktop channels using JavaServer Pages. Several key advantages include:

• Separation of presentation from business logic. The HTML tags associated with a channel can be placed in the JSP file, while the Java code that is needed to generate the content can be placed either in the provider or in a separate class.
• A standard template mechanism. Any proprietary templating mechanism does not provide the flexibility that is available with the open standard of JSPs.
• Rapid development. Development of a JSP is easier from the developer perspective than creation of a provider. The JSPProvider can update a JSP without restarting the web server.

The JSPProvider class provides the following features:

• Configuration of several JSPs to form a provider.
• Access to Sun ONE Portal Server platform services used by the JSP. JSPProvider extends the ProfileProviderAdapter class so it supports setting of various other attributes for the channel.
• Support for efficient execution of JSP-based providers. JSPProvider implements a JSP engine so that JSPs are executed directly by the provider, not via another connection to a web server.

JSPProvider channels are typically created by using the channel wizard in the administration console to add a JSP channel to the desktop. Along with the attributes that are common to all providers that are based on ProviderContext, JSPProvider supports the following unique attributes:

• contentPage - the JSP that is used to generate the channel content (via the getContent method)
• editPage - the JSP that is used to generate the edit page content (via the getEdit method)
• processPage - the JSP that is used to process the results of an edit page (via the processEdit method).
• showExceptions - if true, JSPProvider shows exceptions generated while processing the JSP as the channel output for the getContent and getEdit methods. This can be useful during development.

The contentPage JSP generates the HTML content for the channel. The generated HTML must contain only those tags that are appropriate for display within a channel. The JSP has access to Sun ONE Portal Server platform services via the mechanisms described below.

The editPage JSP generates the internals for the edit form that is displayed when the user clicks the Edit button for the channel. This page is optional. As with the contentPage JSP, the JSP has access to Sun ONE Portal Server platform services.

The contentPage and editPage JSPs can be used in various combinations. For example, a JSP could be used to generate the content while the edit page could be generated using Java code in a class that extends JSPProvider.

There are several options for handling the processing of an edit form for a JSP-based provider. Typically, processing of the edit form consists of Java code that checks validity of the form entry and updates user preferences for the channel. The result is either a redisplay of the desktop (in the case of success) or a redisplay of the edit page, possibly with some error information for the user (in the case of a failure). To handle the processing of an edit form, the JSP-based provider has the following options:

• Define a processPage JSP. If defined, this JSP is invoked and the JSP can process the results, either using a scriptlet or a bean or other Java class.
  • If the JSP returns normally (an HTTP 200 response), the processEdit method for the provider returns null, which causes a redisplay of the desktop.
  • Or, the JSP can produce a redirect in the response by calling response.sendRedirect. In this case, the processEdit method for the provider returns the value of the redirect.
• Extend the JSPProvider class and implement the processEdit method. The processPage attribute is left blank.

File Searching

When specifying a JSP in one of the JSP attributes, the path name is interpreted relative to the desktop template directory for the user using the same algorithm as for other desktop templates including inclusion of the desktop type and locale settings, providerName, channelName and the clientPath. For example, if the user's locale is de_DE, desktop type is SunBlue, provider name is myProvider, channel name is myChan, clientPath is wml/noki and a JSP attribute is set to chan.jsp, JSPProvider searches for the following JSP files:
/etc/opt/SUNWps/desktop/SunBlue_de_DE/myChan/wml/noki/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue_de_DE/myProvider/wml/noki/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue_de_DE/myChan/wml/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue_de_DE/myProvider/wml/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue_de_DE/myChan/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue_de_DE/myProvider/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue_de_DE/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue/myChan/wml/noki/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue/myProvider/wml/noki/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue/myChan/wml/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue/myProvider/wml/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue/myChan/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue/myProvider/chan.jsp
/etc/opt/SUNWps/desktop/SunBlue/chan.jsp
/etc/opt/SUNWps/desktop/default_de_DE/myChan/wml/noki/chan.jsp
/etc/opt/SUNWps/desktop/default_de_DE/myProvider/wml/noki/chan.jsp
/etc/opt/SUNWps/desktop/default_de_DE/myChan/wml/chan.jsp
/etc/opt/SUNWps/desktop/default_de_DE/myProvider/wml/chan.jsp
/etc/opt/SUNWps/desktop/default_de_DE/myChan/chan.jsp
/etc/opt/SUNWps/desktop/default_de_DE/myProvider/chan.jsp
/etc/opt/SUNWps/desktop/default_de_DE/chan.jsp
/etc/opt/SUNWps/desktop/default/myChan/wml/noki/chan.jsp
/etc/opt/SUNWps/desktop/default/myProvider/wml/noki/chan.jsp
/etc/opt/SUNWps/desktop/default/myChan/wml/chan.jsp
/etc/opt/SUNWps/desktop/default/myProvider/wml/chan.jsp
/etc/opt/SUNWps/desktop/default/myChan/chan.jsp
/etc/opt/SUNWps/desktop/default/myProvider/chan.jsp
/etc/opt/SUNWps/desktop/default/chan.jsp

The root of the search directory (default value: /etc/opt/SUNWps/desktop/) can be changed by modifying the templateBaseDir property in the "dtconfig.properties" file.

Accessing Sun ONE Portal Server Services

A JSP-based provider may need access to service APIs that are provided by the Portal Server platform. A Java-based provider accesses these services by either using Provider API methods such as ProfileProviderAdapter.getProperty or by invoking Sun ONE Portal Server APIs directly Examples might include:

• reading display profile information (ProfileProviderAdapter getStringProperty method)
• reading user profile information (getProviderContext().getStringAttribute())

Typically a JSP-based provider consists of one or more JSP files, beans or other Java classes that implement business logic, and possibly a Java class that extends JSPProvider. Access to Sun ONE Portal Server services is needed in all of these places. A Java class that extends JSPProvider already has access to all of the APIs, so that case is handled. For all other cases, JSPProvider provides the JSPProvider pageContext attribute for the JSP and other supporting classes to access the Sun ONE Portal Server services.

Every JSP has access to several implicit objects. One of these, called pageContext, represents the context within which the page executes. The pageContext.getAttribute method allows an arbitrary object to be retrieved from the pageContext. The JSPProvider defines a JSPProvider attribute that provides access to the provider object that is executing the JSP. This may be a JSPProvider object or a class that is extended from JSPProvider.

Once the JSP has access to the provider object, it can use methods in the JSPProvider class to access Sun ONE Portal Server services, or it can pass this object to other objects so that they can access Sun ONE Portal Server services. Please refer to the Sample JSP Provider or other Sun ONE Portal Server JSP Providers for code examples.

JSP Engine

The JSP engine used by JSPProvider supports the same set of JSP features as is supported by the Sun ONE Web Server that is included with Portal Server.

Any classes or beans that are accessed by JSPs must be placed into the directory that is specified in the providerClassBaseDir property in the "dtconfig.properties" file (or the server specific configuration file).

Each JSP is compiled by the JSP engine into a Java file and then the Java file is compiled by the JDK into class files. These files are saved in a scratch directory which is the subdirectory "tmp" under servlet init parameter "server.root" specified in the web.xml.

Troubleshooting

During development of JSP-based channels, there are several techniques available for debugging problems.

The showExceptions attribute can be turned on for a channel. This will cause exception messages to be displayed in the user desktop for the getContent and getEdit methods.

Error messages from JSPProvider are printed in the desktop.debug file in /var/opt/SUNWam/debug. If the showExceptions attribute is turned off, this is where to look for exception messages.

When the JSP file is changed on disk, the JSP is automatically recompiled and reloaded without restarting the web server or logging out and logging back in. However, as with other channels that use ProfileProviderAdapter, user attributes are not reread unless you logout and log back in.

JSP are compiled into Java files and the output is put into the scratch directory. Sometimes looking at the Java code can reveal problems in the JSP.

See Also:

Provider, ProfileProviderAdapter

Fields inherited from interface com.sun.portal.providers.ProviderWidths

WIDTH_FULL_BOTTOM, WIDTH_FULL_TOP, WIDTH_THICK, WIDTH_THIN

Fields inherited from interface com.sun.portal.providers.ProviderEditTypes

EDIT_COMPLETE, EDIT_SUBSET

Constructor Summary

JSPProvider()
Constructs a JSPProvider.

Method Summary

StringBuffer	getContent(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) Gets the provider's content by executing a JSP.
StringBuffer	getEdit(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) Gets the provider's edit page by executing a JSP.
void	init(String n, javax.servlet.http.HttpServletRequest httpreq) Initializes the JSPProvider.
boolean	isPresentable() Dictates whether the provider is presentable.
URL	processEdit(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) Performs the provider's edit page processing by executing a JSP.

Methods inherited from class com.sun.portal.providers.ProfileProviderAdapter

existsBooleanProperty, existsIntegerProperty, existsListProperty, existsListProperty, existsStringProperty, existsStringProperty, getBooleanProperty, getBooleanProperty, getClientProperty, getIntegerProperty, getIntegerProperty, getListProperty, getListProperty, getMapProperty, getMapProperty, getMapProperty, getMapProperty, getStringAttribute, getStringProperty, getStringProperty, getStringProperty, getStringProperty, getTemplate, getTemplate, isAllowed, setBooleanProperty, setClientProperty, setIntegerProperty, setListProperty, setMapProperty, setStringAttribute, setStringProperty

Methods inherited from class com.sun.portal.providers.ProviderAdapter

getContent, getDescription, getEdit, getEditType, getHelp, getHelp, getName, getProviderContext, getRefreshTime, getResourceBundle, getResourceBundle, getTitle, getWidth, isEditable, processEdit

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JSPProvider

public JSPProvider()

Constructs a JSPProvider.

Method Detail

init

public void init(String n,
                 javax.servlet.http.HttpServletRequest httpreq)
          throws ProviderException

Initializes the JSPProvider. If additional initialization is required by a provider that extends JSPProvider, this method may be overriden. However, the overriding init() call must always have super.init() as the first statement executed.

Overrides:

init in class ProviderAdapter

Parameters:

n - The unique indentifying name for this channel.

s - The user's session.

Throws:

ProviderException - If ProfileProviderAdapter.init throws an exception

See Also:

Provider.init(java.lang.String, javax.servlet.http.HttpServletRequest)

isPresentable

public boolean isPresentable()

Dictates whether the provider is presentable.

Searches for the JSP specified in the contentPage attribute. If the JSP is found , then returns true. If the contentPage attribute is not specified, or if the JSP file is not found, then the superclass method is called.

Overrides:

isPresentable in class ProviderAdapter

Returns:

boolean value dictating presentability

See Also:

ProviderAdapter.isPresentable()

getContent

public StringBuffer getContent(javax.servlet.http.HttpServletRequest req,
                               javax.servlet.http.HttpServletResponse res)
                        throws ProviderException

Gets the provider's content by executing a JSP. If the contentPage attribute has a value, it is used as the name of a JSP to execute per the search algorithm defined above. The body of the response is returned as the value for the method. If the contentPage attribute is blank, the superclass method is called. The following values from the request are passed on to the JSP servlet:

• cookies
• parameters

Overrides:

getContent in class ProviderAdapter

Parameters:

request - An HttpServletRequest that contains information related to this request for content.

response - An HttpServletResponse that allows the provider to influence the overall response for the desktop page (besides generating the content).

Returns:

StringBuffer holding the channel content.

Throws:

ProviderException - If there was an error generating the content. Upon catching this error, the desktop application will attempt to fetch a cached copy of the content. If a cached copy does not exist, then an error message will be displayed in the body of the provider.

See Also:

ProviderAdapter.getContent(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

getEdit

public StringBuffer getEdit(javax.servlet.http.HttpServletRequest req,
                            javax.servlet.http.HttpServletResponse res)
                     throws ProviderException

Gets the provider's edit page by executing a JSP. If the editPage attribute has a value, it is used as the name of a JSP to execute per the search algorithm defined above. The body of the response is returned as the value for the method. If the editPage attribute is blank, the superclass method is called. The following values from the request are passed on to the JSP servlet:

• cookies
• parameters

Overrides:

getEdit in class ProviderAdapter

Parameters:

request - An HttpServletRequest that contains information related to this request for content.

response - An HttpServletResponse that allows the provider to influence the overall response for the desktop page (besides generating the content).

Returns:

StringBuffer holding the channel edit page.

Throws:

ProviderException - If there was an error generating the content.

See Also:

ProviderAdapter.getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

processEdit

public URL processEdit(javax.servlet.http.HttpServletRequest req,
                       javax.servlet.http.HttpServletResponse res)
                throws ProviderException

Performs the provider's edit page processing by executing a JSP. If the processPage attribute has a value, it is used as the name of a JSP to execute per the search algorithm defined above. If the response from the JSP is a redirect, the redirect location is returned as a URL. If the response from the JSP is a normal OK response (200), null is returned resulting in a redisplay of the desktop. Otherwise an exception is thrown. If the processPage attribute is blank, the superclass method is called. The following values from the request are passed on to the JSP servlet:

• cookies
• parameters (already decoded into Unicode)

Overrides:

processEdit in class ProviderAdapter

Parameters:

request - An HttpServletRequest that contains information related to this request for content.

response - An HttpServletResponse that allows the provider to influence the overall response for the desktop page (besides generating the content).

Returns:

URL of the redirect location or null.

Throws:

ProviderException - If there was an error processing the JSP.

See Also:

Provider.processEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)