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 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.

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.

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.

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

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

2Portal-to-Go Architecture