15
Using the PDK for Visualizing XML Data in Oracle Portal

This chapter describes the following sections:

Introducing Oracle Portal

Oracle9iAS Portal is a component of Oracle9i. It offers the security, reliability, and scalability of Oracle9i Application Server (Oracle9iAS) and Oracle9i database. It is comprised of easy-to-use portal software and a suite of products for application development, data warehousing, business intelligence, application integration, and mobile computing.

What are Portlets?

A portlet is a contained region on an Oracle Portal web page. Portlets can be considered as "web components" that display excerpts of other web sites and generate summaries of key information. Portlets can be placed on the same page with other portlets so that users have easy access to frequently used sites and information.

Portlets are rendered by web browsers just like any other part of a web page. Typically, portlets use standard HTML to display information to users, but their interfaces can be extended using other browser-capable technologies such as Cascading Style Sheets (CSS), eXtensible Style Language (XSL), JavaScript, and even Java applets.

Portlets can be used to access nearly any type of web-accessible information --- from files stored on the corporate intranet and reports on data managed by corporate applications to news and stock quotes from the Internet. Because of their dynamic nature, portlets are often used to highlight important information, alert users to new developments, and summarize key data.

There are three types of portlets:

Built-in portlets. Oracle Portal provides a set of built-in portlets with ready-to-use functionality for web application development, web publishing and external site integration.
Database Portlets. Implemented as stored procedures and executed in the database. Can be written in PL/SQL or Java Stored Procedures wrapped in PL/SQL. DATABASE PORTLETS. Use Database Portlets whenever your portlets require significant database interaction or when the development team has Oracle experience. To create a Database Portlet:
- Create a Database Provider by creating a package that exposes methods required by the API to display portlets accordingly.
- Code the portlet producing any technology that can be rendered within an HTML table cell, including HTML, JavaScript, applets and certain plug-ins.
- Register the provider with the Portal before it can be accessed and used. This step refreshes the portlet repository.
- Refresh the portlet repository which stores information for the providers and portlets that the provider owns. You will need to do this manually if you change portlet information after registering your provider.
Web Portlets. Implemented using any web-capable language on a web server external to the Portal. The PDK includes Java classes to make building web portlets easier.

Common Portlet Applications

Here are some common applications for portlets:

Centralizing access to intranet sites. Oracle Portal makes it easy to gather links to all many sites in one place, then organize these access points so that users have a simple way to find what they are looking for. Sets of these links can be published as portlets so that users can readily access frequently used sites from their own personalized page.
Publishing information and documents. Content on the web can be arranged into folders, then placed as portlets onto any portal page, allowing you to mix and match the specific content you wish to see.
Integrating dynamic data services. Portlets are useful for rendering content provided from external data sources and displaying that information on portal pages. For example, portlets allow real-time news stories to be displayed within the portal from XML data sources.
Providing an interface to web applications. Portlets can be used to automatically login to well used application (or its data store) and retrieve a summary of that information. The portlet can then display the information on a portal page.
Integrating with other corporate systems. Organizations have many different, sometimes incompatible, systems. Portlets allow the interfaces for these systems to be presented in a consistent manner within the Oracle Portal environment.

Oracle Portal Development Kit (PDK)

Oracle Portal Development Kit (PDK) includes services and tools for extending the Oracle9iAS Portal framework by developing portlets. These services include:

PDK Integration Services (PDKIS)

PDK Integration Services (PDKIS) is one of the services offered by Oracle9iAS Portal. PDKIS allow you to pull content into portlets directly from URLs, including URLs requiring authentication before viewing. PDKIS can do either of the following tasks:

Parse HTML content directly and place it into a portlet
Transform the HTML content into XHTML for further processing using an XSL stylesheet

PDKIS can pull content into your portal, and then modify the default XSL stylesheet to select what to display and how to display it.

PDK URL Services

You can extend the JPDK (PDK for Java) to create URL-based portlets in any language. Create portlets using any existing application without altering any code. These services can be installed on any machine using JPDK 1.4 or later.

What's Needed to Run URL Services

You need the following to run URL Services:

Oracle 9iAS Portal 3.0.8.9.8 or later. Most features of the PDK URL Services work with older versions, but is only certified against this version of Oracle 9iAS Portal. Certain features such as authenticated portlets will not work on older versions of Oracle 9iAS Portal.
JPDK 1.4 or later.

PDK URL Services Overview

Oracle Portal Development Kit (PDK) currently provides services for Java and PL/SQL. These services allow developers to integrate Java classes and servlets, Java Server Pages, and PL/SQL as portlets within Oracle 9iAS Portal using Portal APIs. The PDK and JPDK (PDK Services for Java) provide samples, utilities, and articles to easily develop portlets in PL/SQL and Java, but do not provide a simple solution for developers who have applications written in any other language like C, C++, Perl, ASP,... To simplify developing portlets in any language, Oracle Portal Development Kit provides PDK URL Services.

PDK URL Services allow developers to take any application written in any language and easily create integrated portlets. The URL Services takes the URL of an application, parses the content, and uses the JPDK framework to create a portlet. This process allows each 'show mode' of your portlet to be rendered from different applications and/or languages. For example, a portlet can have 'show mode' rendered using PERL,' edit mode' rendered using ASP, 'help mode' rendered using HTML, 'details mode' rendered using JSP, and so on.

The current JPDK Framework allows you to define and list portlets through the provider.xml file and limits the amount of programming required.
PDK URL Services extends the JPDK Framework and takes advantage of its ease and simplicity. Therefore, creating URL portlets follows the same steps and configuration needed to create Web portlets with a few exceptions.

Creating a URL Portlet

To create a URL portlet, follow these main steps:

Create your application in any language.
Configure your application to be accessible through a URL.
Define your application through the provider.xml by providing a URL.
Register your provider as a "Web" provider through Oracle 9iAS Portal.
Add the portlet to a page.

Web Provider

A Web Provider is one that is written as a Web application. It is installed and hosted in a Web server and is remote from Oracle Portal. A Web Provider also owns and manages a set of portlets.

PDK Java Services offers a Provider Runtime called DefaultProvider that implements the functions of a provider. DefaultProvider owns and manages a set of portlets. It uses a initialization file to manage the set of portlets, called provider.xml.

The file, provider.xml, is a static file that stores information about a provider and its portlets. Understanding the configuration of provider.xml allows you to create your own file to list and describe your Web portlets.

URL Services Architecture

URL Services uses existing JPDK classes and extends the framework where required for rendering content from a URL. PDK URL Services allows you to define and list your URL portlets within the provider.xml file.

URL Services also eliminates the need for additional programming by including a default runtime that handles portlet creation, integration, and communication with Oracle 9iAS Portal. The three main components of PDK URL Services are:

URL Services Interface
URL Services Runtime
provider.xml.

URL Services Interface

URL Services Interface is additions to the Web Provider Interface included in JPDK. The interface specific to URL rendering is oracle.portal.provider.v1.ContentFilter, specifications for filtering URL content.

URL Services Runtime

URL Services Runtime extends classes from the current Web Provider (JPDK) Runtime to adapt to the new URL rendering capabilities. URL Services Runtime is comprised of the following set of runtime classes:

oracle.portal.provider.v1.http.DefaultURLProvider extends the Web Provider Runtime class DefaultProvider. This class represents the Provider for all portlets rendered using the URL Services.
oracle.portal.provider.v1.http.PortletNodeHandler extends the Web Provider Runtime class DefaultPortlet. This class parses all of the XML content within the provider.xml referring to URL rendering.
oracle.portal.provider.v1.http.URLSecurityManager implements the Web Provider Interface defined by oracle.portal.provider.v1.PortletSecurityManager. This class manages portlet access and security.
oracle.portal.provider.v1.http.URLPageRenderer implements the Web Provider Interfaces defined by oracle.portal.v1.PortletRenderer. The URLPageRenderer allows you to use the URL to render the content of a request.
oracle.portal.provider.v1.http.XMLFilter implements the Web Provider Interface defined by oracle.portal.provider.v1.ContentFilter. This filter converts the HTML contents received from a URL into XHTML.
oracle.portal.provider.v1.http.HtmlFilter implements the Web Provider Interface defined by oracle.portal.provider.v1.ContentFilter. This filter converts the HTML contents into Oracle 9iAS compliant HTML.

DefaultXhtml.xsl is a default stylesheet that converts XHTML to Oracle 9iAS Portal compliant XHTML.

Provider.xml

provider.xml stores information by hierarchy and defines and lists available portlets. provider.xml is associated with only one provider. The default provider in the XML file is oracle.portal.provider.v1.http.DefaultProvider. To take advantage of URL Services, you need to specify oracle.portal.provider.v1.http.DefaultURLProvider. DefaultURLProvider parses the additional/updated tags within provider.xml file. The DefaultURLProvider can handle standard provider.xml tags, but DefaultProvider cannot handle tags within the provider.xml that contain URL Services information.

provider.xml Tags

Table 15-1 lists provider.xml tags that have been added or modified in the provider.xml:

Table 15-1 provider.xml Tags

provider.xml Tags	Description
provider tag	The following are tags that have been added or modified within the provider tag.
authentication	A required tag that has been added to the provider tag. It holds information about the type of authentication used.
proxyInfo	A required tag and holds proxy server information.
authorizatio	A required tag and holds information about the type of authorization.
redirectUrl	An optional tag and contains the parameter name used by the External Application for redirection after a successful authentication.
portlet tag	The following are tags that have been added or modified within the portlet tag.
registrationPortlet	An optional tag and specifies whether this portlet is a registration portlet for the provider.
portletRenderer	Modified to accept URL pages and filters for each show mode.

Using provider.xml

Provider.xml is a declarative file containing descriptive informatio. It is used to list and display portlets. DefaultProvider parses provider.xml to gather information from the file. It creates a portlet instance (Java object) for each portlet listed in provider.xml. DefaultProvider also retrieves the render modes, personalization, and security information from provider.xml. It attaches this information to each of the portlet instances it creates and pushes the information to the other class files.

DefaultProvider pushes the information about render modes to the PortletRender. It pushes the information about personalization to the PortletPersonalizationManager. Finally, it pushes security information to the PortletSecurityManager. This allows each class to retrieve information from provider.xml without knowing its name or location.

Once DefaultProvider parses provider.xml, it stores the information until the instance is shut down. When updating, adding, or removing information from provider.xml, you must stop and restart the Oracle HTTP Server and also refresh the Portal repository.

XML parser preserves whitespace surrounding XML elements that contain text, so you must take care with the use of whitespace and line feeds when editing provider.xml. Consider the example:

     <showEdit> true </showEdit> 
     <showEditDefault> true </showEditDefault> 
     <hasHelp> true </hasHelp>

Here, the boolean string values in these tags would not be recognized because of the surrounding whitespace and therefore would be evaluated as false. The tags should be specified as follows:

     <showEdit>true</showEdit> 
     <showEditDefault>true</showEditDefault> 
     <hasHelp>true</hasHelp>

Configuring provider.xml

provider.xml stores information that is used by the Web Provider. It stores information by hierarchy and its hierarchical nature starts with "Provider". The file is organized to simplify the process required by the DefaultProvider to parse the file. provider.xml file is also organized for readability.

This section describes the information in provider.xml. When creating your own provider.xml, you must follow the hierarchy and syntax required for the DefaultProvider to properly parse the file.

Provider Tag

The provider tag is the first tag within provider.xml. It specifies the class that implements oracle.portal.provider.v1.Provider. This specification points the Provider Adapter to a corresponding Provider. The provider tag has two attributes:

class is an optional attribute and names the Java class that implements oracle.portal.provider.v1.Provider. If no class is specified, it defaults to
oracle.portal.provider.v1.http.DefaultProvider.

session is an optional attribute and is used to disable the initSession method within the DefaultProvider. If this session is disabled, the DefaultProvider does not create a servlet session. The default for this attribute is true.

Below is a sample of the provider tag from provider.xml. In the sample, the provider tag declares DefaultProvider as the class that implements oracle.portal.provider.v1.Provider and that DefaultProvider creates a servlet session.

<provider class="oracle.portal.provider.v1.http.DefaultProvider" session="true">

The provider tag manages a single tag: useOldStyleHeaders is a optional. Set this to true if you are using Oracle Portal 3.0.6.6.5 with JPDK 1.3 and later, your provider's portlets support Customize/Help/About links and you want to retain the 'old 3.0.6 style' headers and footers.

For example, include the following line under the provider

tag: <useOldStyleHeaders>true</useOldStyleHeaders>

Portlet Tag

Web Provider has a tag called portlet. There is one portlet tag for each portlet that the provider manages. The portlet tag declares the class that implements oracle.portal.provider.v1.Portlet. The tag lists and describes a set of portlets that this provider manages. The portlet tag has three attributes:

class is an optional attribute and names the Java class that implements oracle.portal.provider.v1.Portlet. If no class is specified, it defaults to
oracle.portal.provider.v1.http.DefaultPortlet.
resource is an optional attribute and specifies the class file that represents the resource bundle. The resource bundle is a compiled Java source that localizes the portlet string of the meta-data information. The resource bundle stores information about your portlet in a local environment. You can store information like portlet name, portlet title, and portlet description. If you specify information in the resource bundle, you would not create a tag in the provider.xml for those values. Default for this attribute is null.

version is an optional attribute and specifies the PDK version that the portlet implements. It is the version of the Portlet interface the portlet relies on. Currently, the value must be 1 and the attribute defaults to 1 if no version is specified.

Below is a sample of the portlet tag with three attributes from provider.xml. In the sample, the portlet tag declares DefaultPortlet as the class that implements Portlet, declares a resource bundle called HelloWorldBundle and a version of 1.

<portlet class="oracle.portal.provider.v1.http.DefaultPortlet" 
resource="oracle.portal.sample.devguide.helloworld.resource.HelloWorldBundle" 
version="1" >

Portlet tag has twenty tags that it manages. Each tag describes an attribute of the portlet. Table 15-2 lists these tags.

Table 15-2 Configuring provider.xml: Portlet Tags

Portlet Tags	Description
id	A required tag and holds the portlet ID number. This number must be unique within this portlet provider. The number is specified by the developer and does not need to be sequential. There is no limit to the length of the number as it is received in by the DefaultProvider as a LONG. There is no default value for this tag.
name	A required tag and holds the portlet name. This portlet name must be unique and contain no spaces or special characters. There is no default value for this tag.
title	A recommended tag. The title is the display name for the portlet and is what is seen by users accessing your portlet. The title may have spaces and special characters. There is no default value for this tag.
description	A recommended tag. The description is displayed to users adding portlets to a page. There is no default value for this tag.
imageURL	Optional and holds the URL that the portlet image references. There is no default value for this tag.
thumbnailURL	Optional and holds the URL that the thumbnail image references. There is no default for this tag.
timeout	Optional and holds the timeout in seconds that the Portal waits for the portlet before it times out. If no timeout is specified, it takes the timeout of the Provider.
timeoutMsg	Optional and holds the timeout message that displays if the portlet times out. If no timeout message is specified, it takes the timeout message of the Provider.
showEdit	Optional flag for whether the portlet will have an "Customize" link. This is a boolean value and the default for this tag is false.
showEditPublic	Optional flag for whether the public users may edit the portlet. By default a public page where users are not logged-in does not display the "Customize" link. If you want public users to be able to customize the portlet, specify true here. This is a boolean value and the default for this tag is false.
showEditDefault	Optional flag for whether the customization page will have an EditDefaults link. This is a boolean value and the default for this tag is false.
showPreview	Optional flag for whether the portlet will have a preview option when adding portlets to a page. This is a boolean value and the default for this tag is false.
showDetails	Optional flag for whether the portlet can be displayed in a full browser page. This is a boolean value and the default for this tag is false.
hasHelp	Optional flag for whether the portlet will have a "Help" link. This is a boolean value and the default for this tag is false.
hasAbout	Optional flag for whether the portlet will have an "About" link. This is a boolean value and the default for this tag is false.
defaultLocale	Optional tag and holds the language that the portlet uses by default. You specify the Locale as a two digit language and a two digit country. The java.util.Locale class contains a list of locales. For example: en.US
acceptContentTypes	Optional tag and holds mime types that the portlet recognizes. This tag is an array and contains one tag called item.
item	A required tag under acceptContentTypes, it specifies a mime type. There is one item tag per mime type recognized by the portlet. The sample below lists to mime types recognized by the portlet, HTML and XML. <item>text/html</item> <item>text/xml</item>
portletRenderer	A required tag and specifies the class that will render portlet pages. The portletRenderer tag is an array. It has one attribute and eleven tags. class is an optional attribute and names the Java class that implements oracle.portal.provider.v1.PortletRenderer. If no class is specified, it defaults to oracle.portal.provider.v1.http.
PageRenderer. appPath	A required tag and holds the virtual path to the root of pages that render the portlet.
appRoot	A required tag and holds the physical path to the root of pages that render the portlet.
showPage	A required tag and specifies the page that renders the portlet.
aboutPage	An optional tag and specifies the page used to supply information about the portlet. helpPage is an optional tag and specifies the help page of the portlet.
editPage	Optional tag and specifies the page used to display portlet customization.
editDefaultsPage	An optional tag and specifies the page used by an administrator to customize the default settings for the portlet.
previewPage	An optional tag and specifies the preview page of the portlet.
showDetailsPage	An optional tag and specifies the page used to display the portlet in a full browser window.
pageParameterName	An optional tag and holds the parameter name to render additional pages. This tag allows the PortletRenderer to support screen chaining.
renderContainer	An optional tag and is a flag that determines whether to render a title bar and border for this portlet. The default value is true. The sample below declares PageRenderer as the implementation class and displays a render page and a few additional display modes. This portlet also renders a container. <portletRenderer class="oracle.portal.provider.v1.http.PageRenderer" > <appPath>/lottery</appPath> <appRoot>E:\jpdk\htdocs\lottery</appRoot> <showPage>lotto.jsp</showPage> <editPage>custom.jsp</editPage> <aboutPage>about.html</aboutPage> <helpPage>help.html</helpPage> <renderContainer>true</renderContainer> </portletRenderer>
portletPersonalizationManager	An optional tag and specifies the class that handles user customization. The portletPersonalizationManager is an array. It has one attribute and two tags.
class	An optional attribute and names the Java class that implements oracle.portal.provider.v1.PortletPersonalizationManager. If no class is specified, it defaults to oracle.portal.provider.v1.http.DefaultPortletPersonalizationManager.
dataClass	An optional tag and references the Java class that implements CustomizationObject. If no class is specified, it defaults to oracle.portal.provider.v1.http.BaseCustomization.
multiLangStringClass	An optional tag and references the Java class that implements the language used to store the customization string. If no class is specified, it defaults to the language of the Java Virtual Machine. The sample below declares DefaultPortletPersonalizationManager as the implementation class, the customization class as BaseCustomization, and language class as HashMLString. <portletPersonalizationManager class="oracle.portal.provider.v1.http.DefaultPortletPersonalizationManager" > <dataClass> oracle.portal.provider.v1.http.BaseCustomization </dataClass> <multiLangStringClass> oracle.portal.provider.v1.HashMLString </multiLangStringClass> </portletPersonalizationManager>
portletSecurityManager	An optional tag that specifies the java class that implements PortletSecurityManager. There is no default value for this tag.

See Also:

http://otn.oracle.com/products
WebDB 2.1: Getting Started - Installation and Tutorial (A70070-01)
WebDB 2.1: Creating and Managing Components - Task Help (A74969-01)
WebDB 2.1: Creating and Managing Components - Field-Level Help (A70072-01) Contains field level help for the component building features of WebDB.
WebDB 2.1: Creating and Managing Sites - Task Help (A70073-01) Contains task help for the site building features of WebDB.
WebDB 2.1: Creating and Managing Sites - Field-Level Help (A70074-01)

Integrating Technologies into Oracle 9iAS Portal

You can seamlessly integrate Oracle9iAQ Portal with technologies not natively included with Oracle 9iAS Portal, such as

Developing portlets with Dynamic Services. See also Chapter 18, "Using Oracle9iAS Dynamic Services and XML" and http://otn.oracle.com/products
Developing Portlets with HyperText Templates (HTT). HyperText Templates (HTT) is an Oracle developed utility for building dynamic Web Pages using templates. HTT does a 100% separation of presentation, logic, and data. HTT is used by Oracle internal consultants to build Internet and Intranet solutions. HTT is simple to understand and use. The technology facilitates the rapid development of dynamic Web pages and allows for code and template reuse, as well as assembly from multiple templates.

15 Using the PDK for Visualizing XML Data in Oracle Portal