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);