Oracle9i Application Server Wireless Edition Developer's Guide Release 1.1 Part Number A86700-01 |
Library | Service | Contents | Index

# 5
Using the Personalization Portal API

This document describes the Wireless Edition Personalization Portal API. Each section of this document presents a different topic. These sections include:

- Section 5.1, "Overview"

- Section 5.2, "Personalization Portal API Classes"

- Section 5.3, "Session Flow"

## 5.1 Overview

The Personalization Portal API classes are designed to allow you to customize a version of the Wireless Edition Personalization Portal. They provide a streamlined set of classes for portal customization. There are also built in syntax checks to verify data model logic.

The use of the Personalization Portal is a sequence of Hypertext Transaction Protocol (HTTP) requests. Each request begins with the user selecting a JavaServer Page (JSP) link which issues the request. The user enters data and clicks a button which causes the JSP to retrieve, update, or create a new repository object. Each request is controlled by classes which have been grouped into controllers based around the type of operation being performed.

Note: For detailed information regarding the Personalization Portal API, see the Oracle9i Application Server Wireless Edition Javadoc.

## 5.2 Personalization Portal API Classes

The Wireless Edition Personalization Portal is represented by a default set of JavaServer Pages (JSP) which allow you to personalize folder, service, bookmark, alert, alert address, locationmark, and profile repository objects. The Personalization Portal API enables you to create your own JSPs. The classes are categorized by specific function. Combining these functions is one method of creating your own JSP framework. See Chapter 4, "Rebranding the Personalization Portal" for other methods of creating your own JSPs.

The API is categorized into the following controllers. Each of them is stateless and can be used as a Java singleton class. Calls to these classes are not context sensitive.

### 5.2.1 Login and Initialize Session - RequestController

RequestController handles operations related to requests and session control such as:

- User login.

- Session creation.

- Requesting a service.

- Logging out.

Table 5-1 Request Controller API Examples

Operation | API Method Called
--- | ---
Login and user authentication at login page | login
Initialize session and load proper JSP at the top of each page | initRequest
Request a service | runService
Log out of Personalization Portal | logout

### 5.2.2 Group Creation and Modification - GroupController

GroupController is used to handle group related operations such as:

- Creating or deleting group objects.

- Retrieving and updating group properties.

- Listing the users within a group.

- Moving users in or out of a group.

Table 5-2 Group Controller API Examples

Operation | API Method Called
--- | ---
Group creation | createNewGroup
Display an array of all existing groups | getAllGroups
Modify group properties, such as name | setParameters
Set group root services or folders | setRootServiceHash
View and customize group owned services | getGroupService
Query and view all the group users | getGroupUserList
Delete group | deleteGroup

### 5.2.3 User Creation and Modification - UserController

UserController oversees operations involving users, such as:

- Create user home folder.

- Search for and display a user list by user name and/or display name.

- View and modify user profile.

- Delete single/multiple users.

Table 5-3 User Controller API Examples

Operation | API Method Called
--- | ---
Create a user home folder | createNewUser
Search the user list by user name or display name | QueryUserList
Display the user profile for modification | getCurrentLoginUser getGroupRootFolders getAlertAddresses getAllAlerts setDefaultLocationMark getAvailableLanguages getAvailableCountries
Display the services for a user's group(s) | getUserRootFolder
Deletes user(s) | deleteUser
Moves user(s) | setUserParameters

### 5.2.4 Object Customization -- ServiceController

ServiceController regulates operations for service, folder, and bookmark objects such as:

- Viewing the service tree.

- Create sub-folder or bookmark.

- Copying a service.

- Reordering objects within a folder.

- View a bookmark URL.

- Set object parameters.

- Setting objects as visible/invisible.

- Delete an object.

Table 5-4 Service Controller API Examples

Operation | API Method Called
--- | ---
Display the service tree | getChildren
Create new folder or bookmark | createNewFolder createNewBookmark
Copy a service | copyService
View the URL target of a bookmark | getExternalURL
Reorder the contents of a folder | setParameters
Make object visible or invisible | setVisibilityHash
Delete an object | deleteService

### 5.2.5 Alert Customization -- AlertController

AlertController handles operations of alerts and alert address settings such as:

- Create an alert or alert address.

- Retrieving the parameters of an alert.

- Setting the parameters of an alert.

- Setting the parameters of an alert address.

- Delete an alert address.

Table 5-5 Alert Controller API Examples

Operation | API Method Called
--- | ---
Create a new alert or alert address | createNewAlert createNewAlertAddress
View the parameters of an alert | getAlertFreqType getAlertFreqDay getAlertFreqValue getAlertFreqUnit getAlertStartTime
Set the parameters of an alert | setParameters setTimeParameters
Set the parameters of an alert address | setAddressParameters
Delete an AlertAddress | deleteAlertAddress

### 5.2.6 Locationmark Creation and Modification -- LocationMarkController

LocationMarkController manages operations with locationmarks including:

- Create a locationmark.

- View all the locationmarks.

- Modify a locationmark.

- Set default locationmark.

- Delete a locationmark.

Table 5-6 LocationMarkController API Examples

Operation | API Method Called
--- | ---
Creating a location mark | createNewLocationMark
Display location mark parameters | getParametersHash
Set location mark parameters | setParameters
Delete a location mark | deletLocationMark

## 5.3 Session Flow

The following diagram displays the flow of operations in an HTTP request. RequestController handles authenticating the user and initializing the request. Other controllers are called depending on the parameters of objectId, the current request, and any input from the user in the form of input strings.

#### Figure 5-1 Session Flow

Text description of the illustration portflow.gif

### 5.3.1 Sample Code

The following code samples demonstrate an example of an HTTP session based on the process illustrated in Figure 5-1.

#### 5.3.1.1 Authenticate User

    try {
         // request is HttpServletRequest
         // -1 means the application Session will never expire
         // until the HttpSession expires
         RequestController.getInstance().login(request, -1);
    } catch (PortalException pe) {
    }

#### 5.3.1.2 Initialize Session

    try
         // request is HttpServeltRequest
         Request _mRequest =
    RequestController.getInstance().initRequest(request);
    }  catch (PortalException pe) {
    }

#### 5.3.1.3 Retrieve Objects

    try {
         //_mRequest is oracle.panama.rt.Request
         //currentUser is current user with type of //oracle.panama.model.User
         //currentService is current service in Request with type of
         //oracle.panama.model.Service
         User currentUser = UserController.getInstance().getCurrentUser(_mRequest);
         Service currentService =
         ServiceController.getInstance().getCurrentService(_mRequest);
    } catch (PortalException pe) {
    }

#### 5.3.1.4 Display/Edit Objects

    try {
         //inputHash is assigned with a hashtable of
         //inputArgument name-value pairs
         Hashtable inputHash = ServiceController.getInstance().
         getInputArguments(currentService.getId());

         //display inputArgument name and value,
         //and modify some of the values in inputHash
         ..

         //update the inputArgument values of the current service
         ServiceController.getInstance().
         setInputArguments(currentService.getId(), inputHash);
    } catch (PortalException pe) {
    }

#### 5.3.1.5 Cleanup Request

    //_mRequest is oracle.panama.rt.Request
    RequestController.getInstance().freeRequest(_mRequest);

| Copyright © 2001 Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index