|
| Sun ONE Portal Server Developer's Guide |
Chapter 1 Introduction to the APIs
This chapter provides an introduction to customizing the portal to fit the specific needs of your organization. It describes the SunTM ONE Portal Server software architecture, APIs, and programming concepts that developers can use.
This chapter contains the following sections:
See the Sun ONE Portal Server 6.0 Administrator's Guide for information on administering the Sun ONE Portal Server software. See the Sun ONE Portal Server 6.0 Desktop Customization Guide for information on customizing the Desktop templates and JavaServer PagesTM (JSPTM).
Note Detailed information on the Sun ONE Portal Server APIs is available in the Javadocs. The URL to access the Javadocs is:
http://hostname:port/URI/javadocs
Overview
This section provides a brief description of the Sun ONE Portal Server software. See Chapter 1, "Introduction to Sun ONE Portal Server," in the Sun ONE Portal Server 6.0 Administrator's Guide 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 Sun ONE Portal Server software 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.
Desktop and Desktop Hierarchy
The Desktop uses 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. 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 area in the Desktop, usually (but not always) set off with a border and header row of icons than enables users to configure the channel to their preference.
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 Sun ONE Portal Server software provides a number of building block leaf providers, such as URLScraperProvider (for generating the complete content of a web site in the channel) and XMLprovider (for converting and displaying XML files according to a specified style sheet). A JSPProvider is also available. These providers are already implemented and available for you to tailor to your site's needs.
The Sun ONE Portal Server software also provides content providers such as mailcheck, bookmark, userinfo, and so on. These are not building block providers, but are provided as out-of-the box channels.
See Figure 1-1 for 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-1 Desktop Hierarchy and Building Block Providers
Display Profile
The display profile is a set of XML documents used to define and configure providers and channels in Sun ONE Portal Server software. The display profile defines the following three items:
- Providers
- Containers
- Channel properties
The display profile does not define the overall layout of what users see on their desktops. However, it does indirectly control some aspects of channel presentation, such as column layout for a table container or how the table container draws channels in a table. The display profile does not control such things as how the XMLProvider parses XML; it only has a definition of the kind of rules (XSL file) that are in it.
The display profile used to generate a user's Desktop is constructed by merging together multiple display profile documents.The display profile is implemented on top of the iPlanetTM Directory Server Access Management Edition software. The display profile is a series of XML documents for storing content provider and channel data.
The display profile documents are stored in their entirety as a single attribute in the iPlanet Directory Server Access Management Edition software services layer. That is, the display profile documents are an LDAP attribute residing in an instance of the SunTM ONE Directory Server software.
See Chapter 5 in the Sun ONE Portal Server 6.0 Administrator's Guide for a complete discussion of the display profile and its administrative tasks.
Deploying Channels
The Sun ONE Portal Server software includes an optional packaging mechanism—the provider archive file— often abbreviated as PAR file, for transporting channels and providers in to and out of the server. The .par suffix denotes a PAR file. The PAR file mechanism is an extended form of the .jar file format, which uses added manifest information to carry the deployment information as well as an XML document intended for integration into the Sun ONE Portal Server software display profile on the target server.
See Chapter 12 in the Sun ONE Portal Server 6.0 Administrator's Guide for information on creating and deploying .par files.
Search Engine
The Sun ONE Portal Server provides a search engine service that includes basic and advanced search and browse channels for the Desktop. The search engine uses a robot to create resource descriptions 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 SOIF (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.
Software Services
Portal applications and resources use iPlanet Directory Server Access Management Edition software to provide services such as authentication, profile, and session management. See the iPlanet Directory Server Access Management Edition software Administrator's Guide for more information.
Application Development
As a developer, you can provide access to portal resources through the Sun ONE Portal Server software (and iPlanet Directory Server Access Management Edition software) 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 Sun ONE Portal Server software, you use the APIs in the following functional areas:
- Desktop - Using the Desktop API, you can create new providers.
- Search service - Search APIs enable you to modify robots and manipulate the Search database itself.
- iPlanet Directory Server Access Management Edition software - There are five APIs packaged with iPlanet Directory Server Access Management Edition software: 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 iPlanet Directory Server Access Management Edition software APIs in detail, but instead provides a general overview. See the iPlanet Directory Server Access Management Edition software Programmer's Guide for more information on programming with those APIs.
Software Architecture
Figure 1-2 shows the Sun ONE Portal Server software architecture. In this figure, the Sun ONE Portal Server components consist of:
- Applications, such as NetMail
- Search, made up of the search engine and robot
- Content Delivery and Presentation on the Desktop
The Sun ONE Directory Server software provides the data store, and Sun ONE Web Server software provides the web container. The search engine also provides data storage (for RDs) and the file system where Sun ONE Portal Server software provides data storage for templates and JSPs (presentation information). iPlanet Directory Server Access Management Edition software provides support for core services such as profile, session, authentication, and logging. You use the iPlanet Directory Server Access Management Edition software administration console for service, profile, and user administration. See also the iPlanet Directory Server Access Management Edition software Administrator's Guide for more information.
Figure 1-2 Sun ONE Portal Server Architecture
Overview of the APIs
This section describes the Sun ONE Portal Server software Desktop, Search, and authentication APIs for extending your portal.
Desktop APIs
The Desktop APIs allows 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 Figure 1-3.
Figure 1-3 Desktop APIs
Provider API
At the bottom of Figure 1-3 is the Provider Application Programming Interface (PAPI), a foundation that contains the interfaces, base classes, provider context, and exception classes.
As a developer, you use the PAPI and extend the base classes to create new providers. See chapters 2 through 4 for more information.
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 how you configure it.
Building Blocks
At the next level of Figure 1-3 are the out-of-the box building block providers. Building block providers are those providers that are public and that you can extend to create new providers. Building block providers have a one-to-many relationship between provider and channels.
The other out-of-the box providers, such as bookmark and mailcheck, are not public. Because they have a one-to-one relationship between provider and channel, they are not building block providers; but they do generate leaf channels.
The building block providers in the figure are all the specific content providers (leaves) and specific container (presentation) providers that Sun ONE Portal Server software 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.
See the Sun ONE Portal Server 6.0 Desktop Customization Guide for more information on the out-of-the box content providers.
Desktop Servlet
At the top of Figure 1-3 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).
Note You cannot extend the Desktop servlet.
How Concepts in the Provider API Map to iPlanet Directory Server Access Management Edition software
The Provider API furnishes architectural separation from iPlanet Directory Server Access Management Edition software; but the PAPI is implemented in terms of specific iPlanet Directory Server Access Management Edition software APIs within the Sun ONE Portal Server software framework.
The getAttribute() and setAttribute() methods in the Provider API refer directly to iPlanet Directory Server Access Management Edition software attributes. The getProperty and setProperty methods in the Provider API refer to display profile properties. The client related methods in the Provider API map to the iPlanet Directory Server Access Management Edition software client APIs. The session property methods map to the iPlanet Directory Server Access Management Edition software session interface.
See the schema reference in Appendix G in the Sun ONE Portal Server 6.0 Administrator's Guide for more information.
Search APIs
The Sun ONE 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 SOIF objects, such as RDs (RDM and SOIF 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 iPlanet Directory Server Access Management Edition software administration console. In addition, you can use the robot API to develop your own handlers for custom behavior.
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 (SOIF) objects. The SOIF 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 an SOIF output stream, and read an SOIF input stream.
Normally, you access the Search database by using the SOIF API, but you can also access the database 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. SOIF is the format used to store and transmit RDs.
Authentication APIs
The Sun ONE Portal Server 6.0 software uses the iPlanet Directory Server Access Management Edition software APIs for authentication, session, profile, and logging.
In general, most development work for a portal developer in the iPlanet Directory Server Access Management Edition software area will be to customize the authentication interfaces. Table 1-1 explains the authentication development tasks and where to go for the information.
Portal Environment
The Sun ONE Portal Server software providers run within the Java Virtual Machine provided by the web container, which may vary between different web containers. The Sun ONE Portal Server 6.0 environment in the Sun ONE Web Server software web container is JDK 1.3.1. In addition to the standard J2SE environment, the following additional Java libraries and capabilities are available to Sun ONE Portal Server software extensions that run within the web container:
- HTTPS protocol scheme is recognized by the URLConnection class
- JavaMail 1.2
- Java Activation Framework 1.0.1
- JNDI 1.1.2
- SOAP 2.2
- JAXP 1.1