Oracle9iAS Portal Developer Kit

Java Server Pages Support In Oracle9iAS Portal

Portal support for JSP pages provides a development foundation that enables JSP developers to integrate Portal functionality and services, and provides a consistent set of Java APIs and a JSP tag library to access the Portal content.

This feature allows developers to combine the flexibility of JSP pages with access to portal content. The page developer has complete control over the page layout, can produce HTML or XML pages, and can have various other J2EE services integrated with JSPs, along with portlet content.

There are two types of JSPs recognized from the Portal perspective:

1. JSP pages located in the Portal page groups

These are stored inside the Portal database and executed in the Portal middle tier. Such pages will be referred to as "internal JSPs" throughout this document.

From the developer and end-user perspective, internal JSPs are very similar to the regular, standard Portal pages. Internal JSPs live in Portal's page groups, and they can be managed by the same tools used for managing standard pages. Internal JSPs can be created simply by copying a standard Portal page as a JSP page. After a standard page is copied as an internal JSP, a developer may download the JSP source, save it to disk, and use any tool to change the JSP source code. After this is done, the JSP source can be uploaded back to the Portal database, and the internal JSP can be run.

2. JSP pages located anywhere outside of Portal

Any JSP located outside of the Portal database, but requesting Portal content by using appropriate API calls or Portal JSP tag library tags, is recognized as an "External JSP" by Portal.

External JSPs cannot be registered with Portal, so the Portal instance does not know about these pages, and ultimately does not trust them. Therefore, special configuration steps are needed to guarantee that a JSP will not be able to access any Portal content it not authorized to see. External JSPs are allowed to access Portal content only if certain rules are followed. Those rules are defined by Portal security rules, individual portlet security, and configuration information.

The next section compares the advantages and disadvantages of these two types of JSPs.

Internal JSPs & External JSPs Compared

Depending on the nature of application and your goals, one or the other type of JSP may be more suitable. Sometimes a mix of both types would be best.

Internal JSPs are more beneficial when you want the same abilities in managing JSP pages as you have with standard pages, but you want a more flexible HTML layout. In this case, you can copy your standard page as JSP. It will have the same portlets you have on the standard page, the basic HTML layout of regions, tabs, style, and so forth will be preserved, and you can modify the layout any way you want.

The advantages of external JSPs is that they can be located on any machine where Oracle9iAS middle tier is installed, and they can have access to many portal databases. Also, external JSPs are advantageous if you already have a JSP application and do not want to migrate it to Portal, but you want to extend its functionality with the additional portlet content provided by the Portal. However, external JSPs are more complex to manage, since they live in the file system, so that the developer has to deal with access priviliges, backups, and the like. Also, additional configuration is necessary to allow external JSPs to access Portal content.

To summarize the benefits and drawbacks of both types:

Internal JSPs

External JSPs

Accessing Portlets in Portal

There are two kinds of Portal portlets that JSPs can access. One is externally published portlets, and the other is portlets on standard portal pages. Portlets are referred by name in JSPs.

How to specify a name for portlets in Portal:

1. Externally Published Portlets

When you create an externally published portlet, you specify its name.You can rename it later.

2. Portlets on standard pages

Edit the standard page that contains the portlets you want to use on your JSPs. In the Edit Portlet Instance screen, you can see the name of this portlet. You can use it in your JSPs. You can also change the name, then use it in JSPs.


How to refer the portlets in JSPs:

1. Externally Published Portlets

Any externally published portlet belongs to a page group.The portlet name is unique within the page group. When specifying a portlet whithin another page or page group, slash "/" character is used as a separator.

2. Portlets on standard pages

Please note that the name of a page group is always in upper case, the name for an externally published portlets is case sensitive. The name for a page, sub page or a tab is always in upper case.

Customization of portlets on a JSP page

Customize from Portal

Externally Published Portlets

From the Navigator, click on the Customize link if you have the privilege to customize for the logged in user. Click on the Edit Defaults link to customize for all users.

Portlets from a Standard Page

The JSP shares the same customization as the standard page which the portlet is originally from. Run the standard page and customize the portlet there.

Customize from JSPs

When creating a portlet instance in a JSP, enable the portlet header through a tag or Java API:

Tag usage: 
<portal:showPortlet portal="MyPortal" name="EmployeeReport" header="true"/>
API usage: 
PortletInstance myReport = myPortal.usePortletInstance("EmployeeReport",true);

By default, the portlet header is on.If the user has the privilege to customize the portlet, the customize link will be displayed in the portlet header. Click on it to customize the instance for the logged in user.

How to pass parameters to portlets on a JSP page

The parameters can be passed to the portlets using the <portal:parameter> tag. The <portal:parameter> tag can be used only in the context of two tags: <portal:portlet> and <portal:showPortlet>. At this time, the parameters that can be passed to the portlet must be of Java String data type.

The following example demonstrates how you can call a portlet and pass a parameter.


<portal:usePortal/>

<portal:showPortlet name="StockQuote">

  <portal:parameter name="ticker" value="ORCL"/>

</portal:showPortlet>

This example will call a stock quote portlet and provide a value "ORCL" to the parameter called "ticker". When called, this portlet is responsible for picking up the value of that parameter and performing whatever action is appropriate to produce the output, which will be returned to the JSP.

A more complex example:


<portal:usePortal/>

<portal:prepare>

  <portal:portlet id="StockQuote1" instance="StockQuote">

     <portal:parameter name="ticker" value="ORCL"/>

  </portal:portlet>

  <portal:portlet id="StockQuote2" instance="StockQuote">

     <portal:parameter name="ticker" value="SUNW"/>

  </portal:portlet>

  <portal:portlet id="StockQuote3" instance="StockQuote">

     <portal:parameter name="ticker" value="ABCD"/>

  </portal:portlet>

</portal:prepare>

<portal:showPortlet name="StockQuote1"/>

<portal:showPortlet name="StockQuote2"/>

<portal:showPortlet name="StockQuote3"/>

In the above case, we want to show 3 stock quotes for different companies using the same stock portlet. First, we want to bundle multiple portlet calls in one <portal:prepare> block, so that we avoid additional roundtrips to the server. Second, we want to have the same portlet "StockQuote" displayed 3 times with different parameters for each call. To do that we need to add an "id" attribute that specifies the "reference" name which will be used for each call to the "StockQuote" portlet on that JSP page. Then later we call <portal:showPortlet> and provide this portlet reference name.

Configuration

This section explains the configuration steps.

Before runnning internal or external JSPs, certain configuration steps must be done:

Configure Portal to support JSP access

1. Create a Page Group.

2. Configure Page Group:

Click on the Edit Properties link from the navigator.

Click on the Configure tab.

In the Page Types and Template section, click on Edit link to select JSP page type in order to create JSP pages.

In the JSP Access section, click on Edit link to go to the Configure JSP Access screen. Then check the checkbox and define the Access Key to allow JSPs to access the portlets from this page group. In the middle tier configuration, the page group name and key should be defined in order to allow external JSPs to access the portlets within the page group.

Middle Tier Configuration

Internal JSP configuration

Out of the box, no configuration file changes are needed to run internal JSPs. Only configuration of a page group on the Portal side is required. All configuration parameters have default values, and are supplied in the web.xml file under Portal application.

There are two parameters that can be changed if required. These are servlet parameters in the $J2EE_HOME/applications/portal/portal/WEB-INF/web.xml file that are used by internal JSPs:

  1. jspRoot directory name where internal JSPs will be downloaded, could be relative or absolute.

  2. jspSrcAlias alias used for jspRoot, which in the most cases should match the jspRoot directory name.

The default values in web.xml file are:


    <init-param>

      <param-name>jspRoot</param-name>

      <param-value>internal_jsp</param-value>

    </init-param>

The jspRoot directory name is relative to the Portal application, which means the internal JSP directory will be: $J2EE_HOME/applications/portal/portal/internal_jsp


    <init-param>

      <param-name>jspSrcAlias</param-name>

      <param-value>/internal_jsp/</param-value>

    </init-param>

If neither of these parameters is specified (that is, they have been manually removed from web.xml configuration file), they will be defaulted to the following:

  1. jspRoot will have value jsp, which is relative to the Portal application home, $J2EE_HOME/applications/portal/portal/jsp

  2. jspSrcAlias will have value /jsp/

External JSP configuration

External JSPs must be configured before they can be run.There are three required steps in the configuration of external JSPs, and one optional step.

1. The location of the external JSP configuration file:

The following parameter in the $J2EE_HOME/applications/portal/portal/WEB-INF/web.xml file is used to determine the location of the external JSP configuration file:

Parameter name: oracle.webdb.service.ConfigLoader

Parameter value: fully qualified name or relative name to the configuration file

The following is an excerpt from the default web.xml file configuration:


..........

<context-param>

 <param-name>oracle.webdb.service.ConfigLoader</param-name>

 <param-value>/WEB-INF/wwjps.xml</param-value>

 <description>This parameter specifies the location of the JPS configuration file</description>

</context-param>

........
The configuration file can be located in any directory accessible by the OC4J.

2. External JSP configuration file:

This configuration file defines the list of Portal instances and page groups within those instances to which external JSPs may have access. Here is an example of a configuration file: 


<jps version="1.0">

 <portal name="MyPortal" default="true">

   <database data-source="jdbc/MyPortal"/>

   <url host="xyz.oracle.com" port="7500" path="/pls/portal"/>

   <cookie name="portal" maxAge="-1" path="/"/>

   <pageGroups>

     <pageGroup name="PGDEMO1"  key="welcome" default="true"/>

     <pageGroup name="PGDEMO2" key="welcome" default="false"/>

   </pageGroups>

 </portal>

 <portal name="AnotherPortal">

   <database data-source="jdbc/AnotherPortal"/>

   <url protocol="http" host="abc.oracle.com" port="8888" path="/pls/portal90"/>

   <cookie name="portal90" maxAge="-1" path="/"/>

   <pageGroups>

     <pageGroup name="JSPDEMO1"  key="welcome1"/>

     <pageGroup name="JSPDEMO2"  key="welcome2"/>

     <pageGroup name="JSPDEMO3"  key="welcome3"/>

     <pageGroup name="JSPDEMO4"  key="welcome4"/>

   </pageGroups>

 </portal>

</jps>

This configuration file defines two Portal instances, one named MyPortal that is the default portal in this configuration file, and another named AnotherPortal. The MyPortal configuration gives access to two pagegroups in this Portal - PGDEMO1 and PGDEMO2. Note that the page group names should be in upper case.

For a detailed description of the configuration file format, please see the "Integrating Java Server Pages with Oracle9iAS Portal" documentation.


3. JDBC Datasource configuration:

Configuring a datasource is the last step for the external JSPs. A datasource should be created in data-sources.xml file pointing to the application schema of the portal instance. The datasource configuration file is located in: $J2EE_HOME/config/data-sources.xml.

Example of a datasource definition for MyPortal:


        <data-source

                class="com.evermind.sql.DriverManagerDataSource"

                name="MyPortal"

                location="jdbc/MyPortal"

                xa-location="jdbc/xa/MyPortal"

                ejb-location="jdbc/MyPortal"

                connection-driver="oracle.jdbc.driver.OracleDriver"

                username="portal_app"

                password="portal_app"

                url="jdbc:oracle:thin:@abc.oracle.com:1521:orcl9"

                inactivity-timeout="30"

        />

For additional information on the data-sources.xml configuration file, please see the "Oracle9iAS Containers for J2EE" documentation.


Mod_osso and JAZN LDAP configuration for external JSPs

This is an optional step in the external JSP configuration. By default all external JSPs are public JSP pages, which therefore can be run by any user who has access to your JSP application.

The mod_osso module and JAZN must be configured only when you want to protect your JSP pages from unauthorized users. When this feature is configured, an attempt to run that protected page by an unauthorized user will result in redirecting to the login server and the user will be asked to enter a username/password. The JSP page will be run only after a successful authentication.

There are several steps to enable this feature. These steps are outlined in section 4 of "Integrating Java Server Pages with Oracle9iAS Portal."

The following 3 steps are not neccessary unless you chose a "custom" install of 9iAS. During the default install these steps will be performed by the installer.

1. Apache HTTP Server must be registered with the Login Server.

2. Mod_osso must be configured

Note: When configuring mod_osso manually, make sure that the OssoIpCheck parameter in the mod_osso.conf file is set to "off". When IP check is enabled, external JSPs will not run.

3. Restart Apache server

The following step must be performed manually after the installation or manual configuration.

4. Enable JAZN-LDAP integration with external JSPs accessing Portal.

The following needs to be added to orion-application.xml, which is located in the J2EE Portal application-deployments directory: 


   <jazn provider="LDAP" location="ldap://[oid_server_name]:[oid_port_number]">

     <jazn-web-app auth-method="SSO" />

   </jazn>

Changes in the JSP sources

1. The tag must explicitly specify the Portal name, page group name, and login attributes.

The id attribute is the Portal name from the configuration file, and pagegroup is a pagegroup located in that portal and included in the configuration file. The login attribute must be set to true to enable login.


  <portal:usePortal id="MyPortal" pagegroup="PGDemo1" login="true"/>

2. If your JSP was using the "default" portal, now it needs to have the portal name in all tags:


  <portal:prepare portal="MyPortal">

     <portal:portlet id="my_banner_portlet" instance="banner" header="false"/>

     <portal:portlet id="my_form" instance="form"/>

     <portal:portlet id="my_report" instance="report"/>

  </portal:prepare>

The same is applicable to the rest of the tags in the JSP page:


<portal:useStyle portal="MyPortal" name="SHARED/MAIN_STYLE"/>

<portal:showPortlet portal="MyPortal" name="my_banner_portlet" header="false"/>

<portal:showPortlet portal="MyPortal" name="my_report"/>

<portal:showPortlet portal="MyPortal" name="my_form"/>

After the login attribute of <portal:usePortal> is set to true and you are not logged in to Portal, you will not be able to run this JSP page unless you log in, even when this JSP page has only public portlets. At this point this JSP is considered to be a "protected" JSP. If later you want this JSP to be public again, all you need to do is to change login attribute to be false and you can access this JSP as a public user.

National Language Support

For writing external JSPs, you can use any valid language/character set combination. But if later you want to load your JSPs to Portal, or you are creating or editing internal JSPs, you need to use the same character set as is used in the Portal database.

For example, if the database was created using the UTF-8 character set, and your JSPs are coded using Japanese Shift-JIS character set, then when you save your JSP you need to save it as UTF-8. Then you can upload it into Portal.

If your JSPs are only external JSPs, you can save them either in UTF-8 or some other Japanese character set, such as Shift-JIS. When downloading internal JSPs from Portal, configure for JSP type to be displayed to the browser, then save to the file system. For downloading the JSP sources, in this example you should make sure that the browser's encoding is also set to UTF-8.

Performance considerations

1. Whenever you are calling more that one portlet in your JSP, it makes sense to use the <portal:prepare> tag instead of individual <portal:showPortlet> tags. This will reduce the number of roundtrips to the server to one, because all portlets included in the <portal:prepare> tag will be delivered in a single roundtrip.

2. If you have a lot of portlets on your JSP page, consider changing caching options for individual portlets on that page. This will allow the JSP page to run faster. Depending on your application requirements, you might choose expires-based caching for portlets whose content is not changing very often.

Jar files uploaded as internal JSPs

In the current version of Portal, the support for JAR files is limited to the JAR files that have a set or combination of JSP pages, HTML files, and image files. No class files placed in a JAR file will be recognized by the container. As a workaround, you can put your class files in the /WEB-INF/classes directory.

Revision History:

May 24, 2002. Initial version