Oracle Portal-to-Go Implementation Guide Release 1.0.2.2 A86635-02 |
Library | Service | Contents | Index

# 2
Portal-to-Go Architecture

This document discusses the Portal-to-Go architecture. It introduces the components of Portal-to-Go, and how you can configure them. Topics include:

- Overview

- Portal-to-Go Repository

- Configuring Portal-to-Go

- Error Logging

- Transaction Logging

## Overview

Portal-to-Go consists of server and client components. The client components include tools for developing, managing, and monitoring the Portal-to-Go server. The Portal-to-Go Service Designer, for example, is a visual interface for developing and maintaining Portal-to-Go objects. The Portal-to-Go objects include users, services, adapters, and transformers.

The Portal-to-Go server performs the primary tasks associated with acquiring and delivering mobile services; it receives user requests, and adapts and transforms content.

The Portal-to-Go server has the following architecture for acquiring and delivering content:

Portal-to-Go runs on the Oracle9i Application Server. It uses Oracle8i for its persistent object storage. When you implement Portal-to-Go, you primarily create and manage the repository objects, and establish relationships between them.

## Portal-to-Go Repository

The Portal-to-Go repository contains the following types of objects:

Object Type | Description
--- | ---
Adapter | Adapter objects represent the Portal-to-Go interface to content sources. Adapter objects have an attribute called `classes`. This attribute identifies the archive file that contains the actual Java implementation of the adapter.
Master service | The master service object implements the service and invokes a specific adapter. You can associate a custom transformer with a master service. Custom transformers are service- and device-specific. They can be used by only one device and one master service.
Alias | An alias is a pointer to a master service, folder, bookmark, or other alias. You can use aliases to distribute access to services and to override default parameter values defined by the master service. You can make a service accessible to a user by placing an alias to the service in a tree the user owns or can access.
Folder | You can use folders to group services. Folders make services available to end users. Every user has a "home" folder. This contains the services, usually referenced by an alias, that the user can access. A user can also access any service in a folder owned by a group to which the user belongs.
User | Each user object represents a Portal-to-Go end user. The name for the user object must be unique within Portal-to-Go. Users have an external identifier attribute. You can use this ID to associate the Portal-to-Go user with an external provisioning system account. The value of the external ID, for example, may be a telephone number or PIN.
User agent | A user agent identifies a user's device address, such as an email address or telephone number, and device type. This information enables Portal-to-Go to deliver notifications to the user. The user must configure these properties from the Personalization Portal.
User group | User groups help you manage service access for multiple users. You can create user groups based on factors such as subscription level, geographic location, or interests.
Transformer | A transformer converts the content returned by Portal-to-Go adapters. Transformer types include: Result transformers, which convert Adapter Result content into SimpleResult content. Device transformers, which convert SimpleResult content into the final target format. A device transformer can be either the default transformer for a logical device, or a custom transformer, which is used to render a specific master service for a specific logical device.
Logical device | A logical device object associates a physical device or an abstract device, such as email, with a transformer.
Bookmarks | End users can set bookmarks to external URLs at the Personalization Portal. The bookmark appears as a menu selection in the device portal. Portal-to-Go does not process the content of the URL target. The format of the target content must be supported by the user's device.

## Configuring Portal-to-Go

Portal-to-Go supports system-wide extensibility using property files. Each property file stores runtime parameters and processing information for a Portal-to-Go component. Portal-to-Go property files are named with the extension .properties.

Property files enable you to plug in new components easily, or extend and configure existing ones. For example, the stripper adapter, which acquires and converts arbitrary Web content, reads configuration settings from the Strip.properties file. It uses the settings in the file to locate classes that process the markup tags in content. Each processing class implements a strip level for the adapter. To add a strip level, you create the class that implements the strip level and reference it in Strip.properties. This makes the strip level available to the adapter, without requiring you to make changes to the stripper adapter class.

Portal-to-Go includes many property files. The System.properties file contains configuration settings for the entire Portal-to-Go system. The following table lists several other property files you can use to configure Portal-to-Go.

Property File | Description
--- | ---
Notification.properties | Contains email and SMS server configuration properties.
Provisioning.properties | Identifies the common root folder for users' service trees.
Rmi.properties | Identifies the server name and listening port of the Portal-to-Go RMI server.
useragent.properties | Links logical devices in the Portal-to-Go repository to the actual user agent parameter received in an HTTP header. Also specifies a default logical device to use if the device type cannot be determined.

These files are located in subdirectories of the following directory:

PortaltoGo_Home/server/classes/oracle/panama/core

### System Properties

The Portal-to-Go system configuration file, System.properties, contains parameters and component locators for the entire Portal-to-Go system. To start Portal-to-Go, you must have this file in the class package `oracle.panama.core.admin`. This package must be in the environment CLASSPATH.

The System.properties file contains the following parameters:

Key | Type | Customizable? | Description
--- | --- | --- | ---
version | String | N | The Portal-to-Go version.
locator.boot.check | Boolean | N | If set to true, Portal-to-Go performs a bootstrap check procedure during system boot. The default is true.
db.connect.string | String | Y | A valid connect string, including user name and password. The precise format depends on the driver you use.
db.driver | String | Y | The JDBC driver Portal-to-Go uses to access the repository. Possible values are THIN, OCI8, INTERNAL, and CUSTOM. If set to CUSTOM, you must also set the db.driver.class parameter.
db.session.min | Integer | Y | The minimum or optimal number of open database sessions. This parameter is used to tune the session pool. It can increase when necessary, but always attempts to return to the specified number of concurrent open database sessions.
db.schema | String | Y | The repository schema to use if not using the default.
db.driver.class | Class name | Y | The class that implements the JDBC driver if using a custom driver. The default is the Oracle JDBC driver.
name.separator | Character | N | The separator used in the service path. This cannot be modified after installation.
locator.objectcache.class | Class Name | N | The object cache implementation class.
objectcache.check.timetolive | Seconds | Y | The time-to-live, in seconds, of a persistent object. After this time Portal-to-Go reconstructs the object.
objectcache.check.interval | Seconds | Y | The time required for the cache monitor to check the cache. If set to -1, Portal-to-Go does not invoke the cache monitor and the cache is not cleared.
session.expiration.time | Seconds | Y | The time-to-live attribute of a session.
session.expiration. checkinterval | Seconds | Y | The time required for the session monitor to check an open session.
locator.persistent.class | Class name | N | The locator implementation for persistent objects.
locator.logger.class | Class name | N | The logger implementation.
locale.language | String | Y | The language used. This is represented by the ISO code for the representation of names of languages. The default is English.
locale.country | String | Y | The location. This uses the ISO 3166 country code. The default is United States.
log.level | String list | Y | The log level. This can contain any of the following: error, warning, notify, or transaction.
log.directory | Path | Y | The log file directory.
log.file.name | File name | Y | The log file name pattern.
log.file.maxsize | Integer | Y | The maximum number of log records in the same file.
log.tx.directory | Path | Y | The transaction log file directory.
log.tx.file.name | File name | Y | The transaction log file name pattern.
log.tx.file.maxsize | Integer | Y | The maximum number of transaction entries in the same file.
log.tx.file.pattern | Formatted string | Y | The pattern used to write transaction log records.
log.console | Boolean | Y | Determines whether true log output is written to `stderr`.
algorithm.password | Java algorithm name | Y | The hash algorithm for passwords.
locator.external.hook.class | Class name | Y | The default implementation of `UserAuthenticationHook`.
locator.useragent.class | Class name | Y | The default implementation of the device recognition class.
locator.transform.class | Class name | Y | The default transformer implementation class.
locator.request.daemon .classes | Class name list | Y | The system daemons to start.
locator.request.queue.class | Class name | N | The asynchronous request queue implementation.
locator.notification.queue. class | Class name | N | The asynchronous notification queue implementation.
locator.notification .dispatcher.class | Class name | Y | The default notification engine implementation.
locator.postprocessor.class | Class name | N | The transformer post-processor implementation.
locator.provisioning.class | Class name | Y | The default implementation of the provisioning hook.
system.java.protocol. handler.pkgs | Class name | Y | The Java class package that provides SSL (Secure Sockets Layer) support.
order.services | String | Y | The sorting order for Portal-to-Go services, folders, and bookmarks on the output devices.

## Error Logging

Portal-to-Go generates logging information for both the server and development client components.

### Development Client Logging

By default, the Service Designer writes error information to the log directory of your Service Designer home directory. You can modify this setting, and the log naming pattern, in the preferences.xml file, which is located in the ServiceDesigner/resources directory.

### Server Logging

Portal-to-Go writes server error information to the files and directory specified in the System.properties file. You can open the log files directly, or view them from the Portal-to-Go Runtime Information and Management interface (the Probe interface) at port 8090. Click the "Files" link.

Portal-to-Go specifies these types of errors:

Error | Value
--- | ---
ERR_SERVICE_UNAVAILABLE | PTG-001
ERR_SERVICE_ERROR | PTG-002
ERR_SERVICE_NOT_FOUND | PTG-003
ERR_CONFIGURATION_ERROR | PTG-004
ERR_INTERNAL_ERROR | PTG-005
ERR_DATABASE_ERROR | PTG-006

In addition to error messages, Portal-to-Go provides extensive runtime exception logging. When fatal exceptions occur, Portal-to-Go logs the exceptions and stack traces in the global log file. If you need to contact Oracle Support Services, you should have the log information available.

## Transaction Logging

The transaction log is a log file on the Portal-to-Go server that provides information regarding user access. To enable transaction logging, you must include transaction logging as a log level in the System.properties file. For example:

`log.level=Warning, Error, Notify, Transaction`

You can also use the System.properties file to set the directory to which Portal-to-Go writes transaction logs, and to specify a file name pattern for the log files. You can also configure the transaction record pattern.

If you enable transaction logging, when a user accesses a service that has a cost value set, the transaction log generates data. You can set a cost for a master service using the Portal-to-Go Service Designer. You can access the transaction log data programmatically, to generate billing information or to integrate Portal-to-Go transaction information with an external billing management system.

The following sample shows the log results of four stock quote queries by a single user. The sample uses the default logging pattern, which you can modify in the System.properties file. It lists the time of access, the user name (Sample), the service, and the price per access (25):

    [11/14/99 4:03:26 PM] Sample   /master/OnlineQuoteYahoo 25
    [11/14/99 4:03:29 PM] Sample   /master/OnlineQuoteYahoo 25
    [11/14/99 4:03:35 PM] Sample   /master/OnlineQuoteYahoo 25
    [11/14/99 4:04:43 PM] Sample   /master/OnlineQuoteYahoo 25

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