Java Doc for JSPProvider.java in  » Portal » Open-Portal » com » sun » portal » providers » jsp » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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/SUNWportal/desktop/SunBlue_de_DE/myChan/wml/noki/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue_de_DE/myProvider/wml/noki/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue_de_DE/myChan/wml/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue_de_DE/myProvider/wml/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue_de_DE/myChan/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue_de_DE/myProvider/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue_de_DE/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue/myChan/wml/noki/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue/myProvider/wml/noki/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue/myChan/wml/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue/myProvider/wml/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue/myChan/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue/myProvider/chan.jsp
    /etc/opt/SUNWportal/desktop/SunBlue/chan.jsp
    /etc/opt/SUNWportal/desktop/default_de_DE/myChan/wml/noki/chan.jsp
    /etc/opt/SUNWportal/desktop/default_de_DE/myProvider/wml/noki/chan.jsp
    /etc/opt/SUNWportal/desktop/default_de_DE/myChan/wml/chan.jsp
    /etc/opt/SUNWportal/desktop/default_de_DE/myProvider/wml/chan.jsp
    /etc/opt/SUNWportal/desktop/default_de_DE/myChan/chan.jsp
    /etc/opt/SUNWportal/desktop/default_de_DE/myProvider/chan.jsp
    /etc/opt/SUNWportal/desktop/default_de_DE/chan.jsp
    /etc/opt/SUNWportal/desktop/default/myChan/wml/noki/chan.jsp
    /etc/opt/SUNWportal/desktop/default/myProvider/wml/noki/chan.jsp
    /etc/opt/SUNWportal/desktop/default/myChan/wml/chan.jsp
    /etc/opt/SUNWportal/desktop/default/myProvider/wml/chan.jsp
    /etc/opt/SUNWportal/desktop/default/myChan/chan.jsp
    /etc/opt/SUNWportal/desktop/default/myProvider/chan.jsp
    /etc/opt/SUNWportal/desktop/default/chan.jsp

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

JSP Compilation Path

JSPProvider has two JSP compilation modes. JSPs are either compiled to the most specific JSP path or the real JSP path. Most specific path mode ensures that the correct statically included JSPs are compiled into the JSP class. JSP class packages are are based on their most specific path. See javadocs for the method getMostSpecificPath() for details. This allows both static includer and includee JSP source files to be shared at various levels of specificity in the file search path of JSPProvider. The problem with this approach is that it does not allow compiled JSP classes to be shared in situations where the JSP source is the same physical JSP file.

Real path compilation mode allows JSPProvider to share compiled JSP classes, at the expense of less flexibility in sharing the source JSPs. Specifically, the rule when operating in this mode is: if a JSP statically includes another JSP, the static includee must be in the same directory path as the static includer. In cases where there is complex sharing arrangement, with different versions of JSPs at different levels of specificity in the file search path, this is undesirable, and JSPProvider should be used in most specific path compilation mode. However, if all JSPs are co-located in a single directory, real path compilation mode will optimize compilation, resulting in far fewer compiled JSP classes.

For an example where real path compilation mode is useful, consider the case where all JSPs are defined in a provider-specific directory, with no channel specific directories for the many channels based on said provider. In most specific path compilation mode, JSPProvider will compile a new set of JSPs for every channel. However, in real path compilation mode, JSPProvider will only compile the JSPs once and will share the compiled classes between all channels based on the provider.

Compilation mode is configured via JSPProvider's compileToRealPath boolean property. If the property's value is true, JSPProvider will operate in real path compilation mode. If this property's value is false, or if the property is non-existent, JSPProvider will operate in most specific compiled path mode.

Extending classes may further modify JSP path derivation behavior by overriding the getMostSpecificJSPPath(), getCompiledJSPPath(), and getExistingJSPPath() methods. See the javadocs of these methods for details.

Accessing Sun 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 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 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:   com.sun.portal.providers.Provider
See Also:   com.sun.portal.providers.ProfileProviderAdapter

If the contentPage attribute has a value, it is used as the name of a JSP to execute per the search algorithm defined above.

If the editPage attribute has a value, it is used as the name of a JSP to execute per the search algorithm defined above.

If additional initialization is required by a provider that extends JSPProvider, this method may be overriden.

Dictates whether the provider is presentable.

Searches for the JSP specified in the contentPage attribute.

If the processPage attribute has a value, it is used as the name of a JSP to execute per the search algorithm defined above.

The default implementation of this method either returns the real (physical) JSP path, or the most specific JSP path (by calling getMostSpecificJSPPath()), depending on if the JSPProvider is in real or most specification path compilation mode, repsectively.
Parameters:
  channel - The channel name.
Parameters:
  file - The template name. a String, the compiled JSP path.
throws:
  ProviderException - if an error occurs in getting the path.

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

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

Classes that extend JSPProvider can override this method to use a different JSP lookup mechanism. The default implementation of this method calls ProviderContext.getTemplatePath() to derive its return value.
Parameters:
  channel - The channel name.
Parameters:
  file - The template name. a String, the path to the template.
throws:
  ProviderException - if an error occurs in getting thetemplate path.
See Also:   com.sun.portal.providers.jsp.JSPProvider.getTemplatePath

The return value of this method determines the JSP compilation path when JSPProvider is operating in most specific path compilation mode. In most specific path compilation mode, the default implementation of the getCompiledJspPath() method calls this method to determine its return value. In real path compilation mode, this method is not called. Classes that extend JSPProvider can override this method to control the JSP compilation path.

The default implementation of this method calls ProviderContext.getTemplateMostSpecificPath() to derive its return value.
Parameters:
  channel - The channel name.
Parameters:
  file - The template name. a String, the most specific path to the template.
throws:
  ProviderException - if an error occurs in getting thetemplate path.

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.
Parameters:
  n - The unique indentifying name for this channel.
Parameters:
  httpreq - HttpServletRequest wrapper.
throws:
  ProviderException - If ProfileProviderAdapter.init throws an exception
See Also:   com.sun.portal.providers.Provider.init

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.
Parameters:
  req - An HttpServletRequest that containsthe request the client made of the provider. boolean value dictating presentability
See Also:   com.sun.portal.providers.ProviderAdapter.isPresentable

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)