Sun Java System Portal Server 7.1 Developer's Guide

Chapter 1 Introduction to Portal Server

This chapter provides an introduction to customizing the portal to fit the specific needs of your organization. It describes the Sun Java System Portal Server architecture, APIs, and programming concepts that developers can use.

This chapter contains the following sections:

Note –

Detailed information on the Portal Server APIs is available in the Java docs. The URL to access the Java docs is:

http://java.sun.com/javase/6/docs

Overview of Portal Server

This section provides a brief description of the Portal Server. See Sun Java System Portal Server 7.1 Technical Overview for a complete product architecture description.

What Is a Portal?

A portal is a doorway or entry point to a set of resources that an enterprise wants to make available to the portal’s users. For some consumer portals, the set of resources includes the entire World-Wide Web. For most enterprise portals, the set of resources includes information, applications, and other resources that are specific to the relationship between the user and the enterprise.

The primary purpose of the Sun Java System Portal Server is to give end users a portal Desktop, which provides access to resources and applications. In addition, a search engine infrastructure enables intranet content to be organized and accessed from the portal Desktop.

Portal Server Architecture

This section describes the Portal Server architecture. In Figure 1–1, the Portal Server components consist of:

Services such as search (made up of the search engine and robot), discussions, and subscriptions
Content delivery and presentation on the Desktop

The Java Development Kit^TM (JDK) provides the Java run-time environment for all Java software in Portal Server and its underlying components.

The Sun Java System Web Server, or the Sun Java System Application Server, or the BEA WebLogic Server, or the IBM WebSphere Application Server provides the web container. The application server provides the Portal Server with a robust, highly scalable web container for the Portal Server web applications. It also provides the Portal Server with compatibility for other applications written to use application server and for developers that want to use the additional enterprise services that are provided by these application servers.

The Directory Server provides the user profile data repository. The Access Manager provides support for core services such as profile, session, authentication, and logging. It also provides single-sign-on services, policy management, debug utility, and client support interfaces for the Portal Server. Use the Access Manager administration console for user administration.

The Portal Server Search Engine provides the search capability. It includes basic and advanced search and browse channels for the Desktop. It uses a robot to create resource descriptions for documents that are available in the intranet, and stores these resource descriptions in an indexed database. Search includes Java and C APIs for submitting resource descriptions and for searching the database. Search also includes an administration console module for editing Search service data and for configuring the search engine and the robot. The console also lets you edit the contents of the Search database.

The Desktop provides the primary end-user interface for the Portal Server and a mechanism for extensible content aggregation through the Container Provider Interface (PAPI). The Desktop includes a variety of providers that provide a container hierarchy and the basic building blocks for building some types of channels. The Desktop implements a display profile data storage mechanism on top of an Access Manager service for storing content provider and channel data.

Figure 1–1 Portal Software Architecture

The architecture diagram shows the components involved
in the Portal Server product.

Portal Desktop

The Portal desktop is a logical component, which consists of the Desktop servlet, Provider API and SPI, various channels, and other support APIs and utilities.

Sample Desktop and Desktop Hierarchy

The sample desktops use an aggregation of a variety of separate web applications (channels) within a common framework. The common framework provides multiple levels and styles of aggregation, presented to end users through a container metaphor.

Providers and Channels

In the Desktop, leaf channels are the basic unit of content, displaying a specific type of information. To the end user, a channel is a distinct unit of content in the Desktop, usually (but not always) set off with a border and header row of icons that enables users to configure the channel to their preference. A provider is a Java class responsible for converting the content, from a file or an application or service, into a presentable format for a channel.

Portlets and Web Service for Remote Portlets

Portlets and Web Service for Remote Portlets (WSRP) are available with Portal Server. Portlets are web components specifically designed to be aggregated in the context of a composite page. Java Specification Request (JSR) 168 specifies how portlets interact, how their life cycles are managed, and provides details of their semantics.

WSRP is a specification that defines a web service interface to access and interact with interactive presentation-oriented web service. WSRP is a standard to access and get the content using the portlets deployed in remote server using web services.

Portal Server Software Desktop

The Desktop provides a mechanism for extending and aggregating content through the Provider Application Programming Interface (PAPI). The PAPI is a Java API that enables you to construct the basic building blocks for creating channels. Usually, though not always, channels contain content. You can also have channels of channels; that is, a container channel that aggregates other channels. A channel can also be the entire Desktop page. The container channels define the layout of the Desktop.

The figure below shows a simple representation of a portal Desktop and its providers and containers. In this figure, the Desktop front page is a tab container with two tabs. Each tab contains a table container with various channels.

Notice how one provider, in this case, URLScraperProvider, is serving more than one channel. Providers can have a one-to-many relationship with channels.

Figure 1–2 Desktop Hierarchy and Building Block Providers

Search Engine

The Portal Server Search Engine is a taxonomy and database service designed to support basic and advanced search and browse channels for the Desktop. The search engine uses a robot to create resource descriptions (RDs) for documents that are available in the intranet, and stores these resource descriptions in an indexed database. Resource descriptions can also be imported from another server or from a backup Search (Summary Object Interchange Format) file. The search engine includes Java and C APIs for submitting resource descriptions and for searching the database. The search engine database can also be used for storing other arbitrary content such as a shared content cache for other content providers.

Access Manager Software Services

Portal applications and resources use Access Manager to provide services such as authentication, single-sign-on, profile, and session management. See the Access Manager documentation for more information.

Portal Environment

This section explains the following component products associated with the Portal Server:

Java Development Kit

The minimum JDK version required for Portal Server environment is 1.5.0_05 for Solaris SPARC® 9 and 10, Solaris x86 9 and 10, and Linux operating systems.

Web Container

The Portal Server providers run within the Java Virtual Machine provided by the web container, which may vary between different web containers. Support for web containers provided in this release are Sun Java System Web Server 7.0 and Sun Java System Application Server 8.2. It is also recommended that the support for Sun Java System Web Server 6.1 and Sun Java System Application Server 7.0 and 8.1 be provided in this release.

Note –

Version 7.0 is not supported on HP-UX and also there are no Java enterprise System wide requirements to support third party web container technology.

Directory Server

The Portal Server environment supports the current and prior releases of the Sun Java System Directory Server 5.2 (R2–R4) and 6.0 (R5).

Note –

Currently, there are no Java Enterprise System wide requirements to support third party LDAP servers.

File System

The Portal Server product uses /opt/SUNWportal (/opt is a default that can be changed during installation), /etc/opt/SUNWportal, and /var/opt/SUNWportal for installing Portal Server specific packages and other files into the file system.

Most Portal Server Java classes are defined in packages under the com.sun.portal package name.

The Portal Server is installed as web application portal on the /portal URI in the web container.

Overview of APIs

This section describes the Portal Server Desktop, Search, and authentication APIs for extending your portal.

Desktop APIs

The Desktop APIs allow you to create new providers for delivering portal content to users. Conceptually, the Desktop APIs consist of Java interfaces in a “stack” as shown in the following figure:.

Figure 1–3 Desktop APIs

This figure shows the Portal Server APIs.

Provider API

At the bottom of Desktop APIs, is the Provider Application Programming Interface (PAPI), a foundation that contains the interfaces, base classes, provider context, and exception classes.

As a developer, use the PAPI and extend the base classes to create new providers. For more information, see Chapters 2 to 4.

The PAPI defines the interface for implementing the provider. A provider is the programmatic entity responsible for generating channels on the Desktop at runtime. The channel properties are read from the display profile by the provider code to dynamically generate the channel content.

There is not necessarily a one-to-one mapping between providers and channels; a single provider can generate one or more channels depending on how you configure it.

Portlet API

The Portlet API version 1.0 is based on the Java 2.0 Platform Enterprise Edition (J2EE) version 1.3. Portlet containers and Portlets meet the requirements, described in the J2EE Specification, for executing in a J2EE environment. The Portlet interface is the main abstraction of the Portlet API.

All Portlets implement this interface either directly or, more commonly, by extending a class that implements the interface. The Portlet API includes a GenericPortlet class that implements the Portlet interface and provides default functionality. If you develop Portlets, you should extend directly or indirectly, the GenericPortlet class to implement their Portlets.

The Portlet API defines the PortletURL interface. Portlets must create Portlet URLs using PortletURL objects. A Portlet creates PortletURL objects invoking the createActionURL and the createRenderURL methods of the RenderResponse interface. The createActionURL method creates action URLs. The createRenderURL method creates render URLs.

Building Blocks

At the next level of Desktop APIs, are the building block providers. Building block providers are those providers that are public and that you can extend to create new providers. The other providers, such as bookmark and mailcheck, are not public and are not extensible.

The building block providers in the figure are all the specific content providers (leaves) and specific container (presentation) providers that Portal Server supplies. All these public building block classes are based upon the base PAPI classes.

As a developer, you can extend the Java classes for some of the building block providers. An administrator can then use your extended classes to define channels for end user consumption.

Desktop Servlet

At the top of Desktop APIs, is the Desktop servlet, which routes client requests for content and processing and passes them on to the specific provider object. The Desktop servlet processes the following actions:

content: Gets the named channel’s main content
edit: Gets the named channel’s edit content
process: Allows the named channel to process form data
logout: Ends the user’s session

The action is performed on the channel (for the content, edit, and process actions). The following request parameter names are reserved by the portal Desktop.

action
provider
last
containerName
targetprovider
page
error
container
selected
editChannelName

Note –

You cannot extend the Desktop Servlet.

How Concepts in the Provider API Map to the Access Manager Software

The Provider API furnishes architectural separation from the Access Manager; but the PAPI is implemented in terms of specific Access Manager APIs within the Portal Server framework.

Typically, to create a provider, you will need to access various software services for provider development. For example, this might include attribute (property) access, session services, and client-based property retrieval. In the PAPI, these services are accessible through the ProviderContext and ContainerProviderContext interfaces. The implementation of these interfaces connects to Access Manager services in an implementation independent manner. The actual implementation of software services, for the most part, is located in another layer; the context interfaces simply pull these features together into a common interface to simplify provider development.

Search APIs

The Portal Server Search service provides:

C API for customizing the way the robot crawls URLs and generates resource descriptions.
Java APIs for searching the database, for submitting data, and for manipulating Search objects, such as RDs (RDM and Search APIs). C versions of these APIs are also available.
Search provider taglib and helper beans to write customized search JSPs.

Search Robot

The robot examines a set of selected URLs and searches for documents. For each found document, the robot then creates a resource description (RD) of the document using a predefined schema. The schema defines what pieces of information about the document are put in the RD. For example, the RD could contain a date, the author, the title, the URL, and an abstract about the document. These RDs can be grouped together or classified according to a given hierarchical taxonomy.

You can configure the robot through the Portal Server administration console.

The robot has many customizeable parameters, including the following configuration parameters:

The URLs that it starts crawling from
Server access delays
Passwords
User agent string
Certificates for SSL
Proxy setup

In addition, the robot API enables you to write custom content parsers and summarizers for special URL handling requirements. You can also use the robot API to remove advertisements, generate alerts when certain pages are found, and perform specialized logging.

Search Database

The Search database consists of Summary Object Interchange Format (Search) objects. The search API creates, reads, modifies, and writes the Search database entries. Assisting APIs create buffers, set and get attribute value pairs (used to define content and metadata for the objects in the database), handle exceptions, create a Search output stream, and read a Search input stream.

Normally, the Search database can be accessed by using the Search API, but the database can also be accessed through command-line utilities. You can also add RDs that you create, or import RDs from another database.

An RD is a description of some object to include into the system. Search is the format used to represent RDs.

Authentication APIs

The Portal Server uses the Access Manager APIs for authentication, single sign-on, session, profile, and logging.

In general, most development work for a portal developer in the Access Manager area will be to customize the authentication interfaces. The following table explains the authentication development tasks and where to go for the information.

Table 1–1 Authentication Development Tasks


If you want to	Go to
Change the look and feel of the authentication screen	Sun Java System Access Manager 7 2005Q4 Developer’s Guide
Enable or disable authentication modules	Sun Java System Access Manager 7 2005Q4 Developer’s Guide
Add a custom authentication module	Sun Java System Access Manager 7 2005Q4 Developer’s Guide. By default, the Access Manager supplies authentication modules for the following types of logins: Anonymous, Certificate, LDAP, Membership, RADIUS, SafeWord, SecureID, and UNIX.

Application Development

As a developer, you can provide access to portal resources through the Portal Server (and the Access Manager) APIs. For example, you can develop channel content to define aggregation of both those channels as well as channels built from the predefined set into your site’s portal.

In extending the Portal Server, use the APIs in the following functional areas:

Desktop - Using the Provider API, you can create new providers.
Search service - Search APIs enable you to customize the search robot behavior and manipulate the Search database itself.
Sun Java System Access Manager - There are five APIs packaged with the Access Manager: authentication, debugging, logging, client detection, and Single Sign-on (SSO). You can extend the authentication and client detection APIs. The other APIs that can be used include the functional areas of SSO, debugging, and logging. This guide does not describe the Access Manager APIs in detail, but instead provides a general overview. See theAccess Manager documentation for more information on programming with those APIs.

Display Profile

The display profile is a set of XML documents used to define and configure providers and channels in the Portal Server. The display profile defines:

Providers
Channels
Container channels

A provider’s display profile document acts as a template for creating channels. They define the set of properties that channels based on this provider will make use of, as well as providing default values for these properties where appropriate. Channels and container channels must reference a provider, and will use their default property values unless the property is redefined in the channel.

The display profile used to generate a user’s Desktop is constructed by merging together multiple display profile documents. Each display profile contains a series of XML instructions for storing channel properties.

The display profile documents are stored in their entirety as a single attribute in the Sun Java System Access Manager services layer. That is, the display profile documents are an LDAP attribute residing in an instance of the Sun Java System Directory Server.

See the Sun Java System Portal Server7.1 Technical Reference Guide for a complete discussion of the display profile.