Skip Headers

Oracle9iAS Wireless Developer's Guide
Release 2 (9.0.2)

Part Number A90485-02
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

11
Advanced Customization

Each section of this document presents a different topic. These sections include:

Oracle9iAS Wireless incorporates Advanced Customization that enables development of adaptable applications that personalize interactions and increase mobile application efficiency. The Advanced Customization allows for quick development and deployment of reliable, secure, scalable, and manageable applications. The end result is a complete one-to-one customer interaction.

Figure 11-1 Advanced customization

Text description of feature2.gif follows.

Text description of the illustration feature2.gif

11.1 Overview of Advanced Customization

This chapter describes Oracle9iAS Wireless advanced customization features. Customization typically refers to how the user adapts the system or how the system adapts to the particular needs and preferences of the user. The user centric customization features give the users control over how they adapt the system to their needs and preferences. The system can also introduce mass customization technique that applies user profiling, sometimes by associating the user with like-minded group of users, to predict the user's needs and preferences, and adapt the system accordingly.

Customization is needed to make applications manageable by understanding visitors' needs based on their roles and preferences -- for example, it is beneficial to present information in different ways to customers, suppliers, and employees. The ultimate goal is knowing enough about a customer's preferences and needs to intelligently suggest new services that they can use. The result is to turn a series of single transactions into a series of interactions that leads to an enduring, mutually profitable relationship.

Figure 11-2 Advanced Customization

Text description of advcust2.gif follows.

Text description of the illustration advcust2.gif

Oracle9iAS Wireless includes a sample customization portal for PC browsers developed in Java Server Pages (JSP), which allows end users to customize the folder, service, bookmark, alert, alert address, location mark, and profiles. You can reuse these JSPs to re-brand the customization portal. You can also develop your own customization portals or integrate the customization tools to your existing portals. The developers should refer to the Runtime API, Data Model API, and the default JSPs for guidance when developing customization portals. You will find the concepts and features introduced in this chapter useful for designing the customization features to empower the end users.

You can introduce mass customization techniques using automatic user profiling. The usage history of the users can be found in the ptg_service_log and ptg_session_log tables in the Oracle9iAS Wireless repository. Some of the examples in this chapter describe how to extend the Oracle9iAS Wireless runtime to introduce mass customization.

The example customization portal lets the users manage the services, to rearrange, subscribe or unsubscribe, make bookmarks, and create quicklinks in each customization profile. Users can create new location marks and geocode the location marks. They can edit the presets that contain personal information or preferences. They can create new device addresses and valid them for alerts. They can subscribe to alerts for these devices.

End Users can log into the portal via a PC browser or any mobile devices to customize their Services.

The Customization 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. This gives a self branded Customization Portal.

Device-based Customization Portal targets the customers who want to customize their mobile services directly from small devices (such as cell phones, PDAs, etc.). The device Customization portal presents the services in edit mode and also includes the user's preferences setting, Land Mark creation, Alert creation, Topic subscription in the menu list. Because of the limited size of display screen and the restricted input methods, the user interface and user interaction will be simplified to fit in those devices.

Multiple User Profiles make the mobile experience much more efficient and personalized. Users are able to manage their Customization Profiles from the Customization Portal. End Users may create, delete, modify and select the default Customization Profile.

Oracle9iAS Wireless gives the option to save the input values that a user has entered as a preset value for future invocations. Furthermore, Oracle9iAS Wireless gives options to enter a symbolic name to represent the presets. These symbolic names allow easy selection if there is more than one group of preset values. In addition, the user can manage their presets with the Customization Portal from any device or PC

Developers have the control to manage the types of presets available to particular users and groups and the input values used. Developers create Preset Categories for managing the presets that are available to end users.

Each Preset Category consists of a Preset Category Name (AddressForm for example) and any number of Preset Attributes. The first Preset Attribute is Street. For example, this will give end users the ability to create a Preset called Home, Work, etc. and each will have their own values for the Preset Attributes (Street, City...).

11.2 Presets

Oracle9iAS Wireless provides the facilities for the service developers and end users to apply extensive Customization to create personalized portals, which enhance the one-one relationships between the portal and each end user. One of the key Customization facilities is the Presets for storage of the user's personal information, preference settings, and frequently used input parameters on the server side so that the services can use them to generate the personalized responses.

The Oracle9iAS Wireless repository contains the concept of a portal User with predefined number of persistent attributes. These basic attributes include name, gender, date-of-birth, home postal address, country, language, default device address, etc. Presets are persistent objects in the Oracle9iAS Wireless repository that can be used to extend repository schema, especially to incorporate new persistent attributes for the User objects in the repository.

11.2.1 Presets Concept and Architecture

The Presets are persistent objects in the Oracle9iAS Wireless repository that can be used to extend the User schema and incorporate the user's personal information into the repository. Developers of the services can define the PresetCategories to extend the User schema in application-specific ways, for example to incorporate the billing address, credit card charge account, bank accounts, brokerage accounts, stock portfolios, emergency contacts, etc. These extended schemas may be defined and exclusively maintained by Personal Information Management (PIM) services.

The Presets can be also used to incorporate the user preferences into the repository. The user agent types and the logical device models in the repository describe the capabilities of the devices. Individual end users can customize some of the capabilities of the user agent. The Presets for user agent profiles can be used to let the end users customize the capabilities of the user agent, for example, to enable or disable sound, select background color, select quality of service, to disable images to minimize packet transmissions even though the device supports images, etc. The user agent profiles control the format of the content, but more general user preference profiles can affect the selection of the services and response of the services. For example, the user preference profile for sports, entertainment, technology, privacy requirements, etc. can be used by the services to filter the contents. The Presets architecture enables the development of adaptive web services based on the emerging Composite Capability/Preference Profile (CC/PP), User Agent profile (WAP UAProf), and Platform for Privacy Preferences (P3P) standards (www.wapforum.org).

The Presets can also store frequently used input parameters for the services. The services can define the attributes of the Presets relation to closely match the forms used by the services. These Presets can be used to auto fill the forms. The services can store the user inputs as the Presets for subsequent use. The Presets names uniquely identify the input parameter values and can be used as shorthand to significantly reduce the amount of data entry.

There are different categories of Presets in the repository. Each Presets relation contains a set of preset attribute values whose types and relations are defined by the PresetCategory. A User may own one or more Presets relations in each of the PresetCategory's. A PresetCategory contains a collection of PresetDescriptor's, each of which provides the metadata for the attributes in the Presets relation. The metadata of an attribute includes the name, type, size, format, and description of the attribute. For example, a Presets relation of the address book PresetCategory may contain the name, address, and phone number attributes of a contact for the user. Such a PresetCategory may be defined and exclusively maintained by a Personal Information Management (PIM) service. Another PresetCategory may define the attributes of the Presets relations that contain the stock symbols, names, and classifications of the companies in the user's watch list or portfolio. The stock symbols in this category can be used as input parameters for the stock quote service.

The name of the PresetCategory must be unique within the repository. Likewise, the name of the PresetDescriptor must be unique within the PresetCategory to which it belongs. The name of the Presets relation is optional but if given the name must be unique among the Presets relations that are owned by the same User within the same PresetCategory. The PresetCategory's created programmatically are marked as system by default, i.e. they are to be maintained by the applications exclusively. System level PresetCategory's are not visible in the customization portals and cannot be edited by the end users directly. The applications can set the PresetCategory to non-system so that end users may edit its Presets in the customization portal.

11.2.2 Sample Applications

The PresetCategory's can be created programmatically as shown in the following examples. They can also be created from the Service Designer > Preset Definitions control panel in Webtool.

11.2.2.1 Example 1: Adding attributes to the User schema.

The following code fragment shows how to create a PresetCategory "Billing Address" to extend the User schema. The method first checks in line [13] if the "Billing Address" category already exists in the repository. If the category does not exist, the ModelFactory method createPresetCategory("Billing Address") is used to create the category in line [21]. Line [23] through [27] defines the first attribute "Addressee Name" of the category. Line [25] defines that the first attribute is comprised of a single line of text. In contrast, the second attribute "Street Address" is defined as a multi-line text field in line [31]. The new PresetCategory is committed in line [47].

import oracle.panama.model.ModelFactory;
import oracle.panama.model.PresetCategory;
import oracle.panama.model.PresetDescriptor;
import oracle.panama.ArgumentType;
import oracle.panama.PanamaException;

public void createAddressBook() throws PanamaException {

        ModelFactory factory = MetaLocator.getInstance().getModelFactory();
        ModelServices services = MetaLocator.getInstance().getModelServices();

        PresetCategory category;
        try {
            category = services.lookupPresetCategory("Billing Address");    [13]
        } catch (PanamaRuntimeException ex) {
            category = null;
        }

        if (category != null) {
            return;   // category already exists
        }
         category = factory.createPresetCategory("Billing Address");        [21]

        PresetDescriptor descriptor = category.createPresetDescriptor("Addressee Name");   [23]
        descriptor.setDescription("The name of the addressee");
        descriptor.setPresetType(ArgumentType.SINGLE_LINE);   [25]
        descriptor.setStoredType(java.sql.Types.VARCHAR);
        descriptor.setSize(new Long(40));						[27]

        descriptor = category.createPresetDescriptor("Street Address");
        descriptor.setDescription("The street address");
        descriptor.setPresetType(ArgumentType.MULTI_LINE);    [31]
        descriptor.setStoredType(java.sql.Types.VARCHAR);
        descriptor.setSize(new Long(120));

        descriptor = category.createPresetDescriptor("State");
        descriptor.setDescription("The name of the state");
        descriptor.setPresetType(ArgumentType.SINGLE_LINE);
        descriptor.setStoredType(java.sql.Types.VARCHAR);
        descriptor.setSize(new Long(2));

        descriptor = category.createPresetDescriptor("Zip code");
        descriptor.setDescription("The postal zip code");
        descriptor.setPresetType(ArgumentType.SINGLE_LINE);
        descriptor.setStoredType(java.sql.Types.NUMERIC);
        descriptor.setSize(new Long(5));

        factory.save();   [47]
    }

Please note that the name of the PresetCategory must be unique in the repository. The createPresetCategory() method of the ModelFactory will throw oracle.panama.model.NameUniquenessViolationException if the application tries to create the PresetCategory with the same name. Likewise, the name of the PresetDescriptor must be unique within the PresetCategory. The createPresetDescriptor() method of the PresetCategory will throw oracle.panama.model.NameUniquenessViolationException if the application tries to create the PresetDescriptor with the same name. The names of PresetCategory and PresetDescriptor are case sensitive and can contain any valid characters including spaces.

11.2.2.2 Example 2: Adding a unique Presets relation for the User

The following code fragment shows how the PresetCategory "Billing Address" is used to add persistent attributes to the User. If the "Billing Address" category does not exist, this method creates the new category. The example uses the unique object id of the User as the name of the Presets. The new Presets relation is created in line [16] only if the look up method in line [13] does not find any existing Presets relation with the same name. The use of the object id as the Presets name ensures that only one instance of the Presets relation for "Billing Address" is created for each user. The attribute values of the Presets relation are modified in line [18] through [21]. The modified Presets relation is committed into the repository in line [23].

import oracle.panama.model.*;

public void addBillingAddress(User user, String addressee, String streetAddress,
                             String state, int zipCode) throws PanamaException {
        ModelFactory factory = MetaLocator.getInstance().getModelFactory();
        ModelServices services = MetaLocator.getInstance().getModelServices();

        PresetCategory category;
        try {
            category = services.lookupPresetCategory("Billing Address");
        } catch (PanamaRuntimeException ex) {
            createAddressBook();						[9]		
            category = services.lookupPresetCategory("Billing Address");
        }

        Presets presets = user.getPresets(category, Long.toString(user.getId()));											[13]

        if (presets == null) {
            presets = user.createPresets(category, Long.toString(user.getId()));    [16]
        }
        
        presets.setPresetValue("Addressee Name", addressee);    [18]
        presets.setPresetValue("Street Address", streetAddress);
        presets.setPresetValue("State", state);
        presets.setPresetValue("Zip code", Integer.toString(zipCode));     [21]

        factory.save();   [23]
    }

Please note that the name of the Presets relation must be unique within the User's domain. If the application tries to create the Presets again with the same name for the same User, the createPresets() method of the User will throw the oracle.panama.model.NameUniquenessViolationException. The names of Presets relations are case sensitive and can contain any valid characters including spaces.

11.2.2.3 Example 3: Adding a unique Presets relation for Users' Profiles

The Profile's are repository objects that support multiple versions of personalized portals for each user. Let's suppose that the user has a Profile for "Business" and another Profile for "Personal" and requires a separate credit card charge account for each of the Profile's. The following code fragment describes how to create the "Credit Card Charge Account" category and the Presets relation that is unique for each profile of the user. The unique presets name is created from the object id of the User and the Profile in line [43] to ensure that only one Presets relation is created for each profile. The example also shows the use of preset type ArgumentType.ENUM for the "Card Type" attribute. The ENUM type lets you specify the valid options for that attribute as shown in line [28] and [30]. Lines [60] through [62] shows the use of the java.sql.Date type for persistent storage. The expiration date of the credit card is formatted using the java.text.DateFormat utility in line [61] so that it can be parsed and stored as Date type in the repository.

import oracle.panama.model.*;
import java.util.Date;
import java.text.DateFormat;

public void addCreditAccount(User user, Profile profile, String cardNumber,
                            String cardType, int expireMonth, int expireYear)
                            throws PanamaException {
        ModelFactory factory = MetaLocator.getInstance().getModelFactory();
        ModelServices services = MetaLocator.getInstance().getModelServices();

        PresetCategory category;
        try {
            category = services.lookupPresetCategory("Credit Card Charge Account");
        } catch (PanamaRuntimeException ex1) {
            try {
                category = factory.createPresetCategory("Credit Card Charge Account");
            } catch (PanamaException ex2) {
                throw ex2;
            }

            PresetDescriptor descriptor = category.createPresetDescriptor("Account Number");
            descriptor.setDescription("The credit card account number");
            descriptor.setPresetType(ArgumentType.SINGLE_LINE);
            descriptor.setStoredType(java.sql.Types.VARCHAR);
            descriptor.setSize(new Long(40));

            descriptor = category.createPresetDescriptor("Card Type");
            descriptor.setDescription("The type of credit card");
            descriptor.setPresetType(ArgumentType.ENUM);    [25]
            descriptor.setStoredType(java.sql.Types.VARCHAR);
            descriptor.setSize(new Long(40));
            String cardTypes[] = { "Master", "Visa", "Discover", "American Express", "Diners 
Club" };      [28]
            try {
                descriptor.setOptions(cardTypes);     [30]
            } catch (TooManyOptionsException ex3) {
                throw new PanamaException(ex3);
            }

            descriptor = category.createPresetDescriptor("Expiration Date");
            descriptor.setDescription("The expiration date of the credit card");
            descriptor.setPresetType(ArgumentType.SINGLE_LINE);
            descriptor.setStoredType(java.sql.Types.DATE);

            factory.save();      [40]
        }

        String presetsName = Long.toString(user.getId()) + "-" + Long.toString(profile.getId()); 
[43]
        Presets presets = user.getPresets(category, presetsName);
        if (presets == null) {
            presets = user.createPresets(category, presetsName);
        }

        presets.setPresetValue("Account Number", cardNumber);
        presets.setPresetValue("Card Type", cardType);
        Date date = new Date(expireYear, expireMonth, 1);   [60]
        String dateStr = DateFormat.getInstance().format(date);    [61]
        presets.setPresetValue("Expiration Date", dateStr);    [62]

        factory.save();     [64]
    }

11.2.2.4 Example 4: Selecting the Presets relation under the current Profile.

The following fragment of codes from a RequestListener illustrates how the Presets relation for the "Credit Card Charge Account" is accessed during the serviceBegin() event notification. The routine throws AbortServiceException if no valid credit card charge account is available for the user. It checks for request profile, session profile, or default user profile in order as shown in line [14] and [16]. It composes the Presets name from the object id of the User and Profile. If the Presets relation for the "Credit Card Charge Account" is found, the listener provides the credit card information to the service as request parameters in line [51] through [52].

import oracle.panama.rt.event.RequestEvent;
import oracle.panama.rt.event.AbortServiceException;
import oracle.panama.rt.Session;
import oracle.panama.rt.Request;

public void serviceBegin(RequestEvent event) throws AbortServiceException {
        Request request = event.getRequest();
        PresetCategory category;
        String presetsName;
        ModelServices services = MetaLocator.getInstance().getModelServices();
        String serviceName = request.getServicePath();
        User user;

        Profile profile = request.getProfile();      [14]
        if (profile == null) {
            profile = request.getSession().getProfile();    [16]
        }
        if (profile != null) {
            user = profile.getUser();
            presetsName = Long.toString(user.getId()) + "-" + Long.toString(profile.getId());
        } else {
            user = request.getSession().getUser();
            presetsName = Long.toString(user.getId());
        }

        try {
            category = services.lookupPresetCategory("Credit Card Charge Account");
        } catch (PanamaRuntimeException ex1) {
            throw new AbortServiceException("This service " + serviceName + " requires a valid 
charge account");
        }

        Presets presets = user.getPresets(category, presetsName);
        if (presets == null) {
            throw new AbortServiceException("This service " + serviceName + " requires a valid 
charge account");
        }

        String creditCardNumber;
        String cardType;
        String expiration;
        try {
            creditCardNumber = presets.getPresetValue("Account Number");
            cardType = presets.getPresetValue("Card Type");
            expiration = presets.getPresetValue("Expiration Date");
        } catch (PanamaException ex) {
            throw new AbortServiceException("This service " + serviceName + " requires a valid 
charge account");
        }

        if (! creditAvailable(creditCardNumber, cardType, expiration)) {
            throw new AbortServiceException("This service " + serviceName + " requires a valid 
charge account");
        }

        request.setParameter("Account Number", creditCardNumber);     [51]
        request.setParameter("Card Type", cardType);      [52]
        request.setParameter("Expiration Date", expiration);    [53]
    }

The above examples are based on the scenario that requires the applications to use well-defined naming conventions for the Presets relations, although the Presets names are optional. The following example illustrates a PresetCategory "Appointments" which allows multi-set entries. The identity of the Presets relation is provided by one of the attributes in the Presets relation. In this example, the Presets are created without names.

11.2.2.5 Example 5: Creating Presets without given name.

The following code fragment shows the PresetCategory "Appointments" that lets the users create appointment events. Since the attribute "Short Title" can be used to identify the events, the event Presets are created without names as shown in line [65]. All event Presets for the user can be retrieved from the repository as shown in line [97]. The "Appointments" category is set to non-system in line [25] so that the category can be included in the customization portal for end users to edit. The example shows the use of DateFormat utility to save the event time in line [69] and retrieve it in line [105]. The expired events are deleted from the repository in line [112]. The example also shows the use of the regular expression to constrain the format of the "Phone Number" attribute. The regular expression is compatible with the public domain org.apache.regexp.RE toolset. The regular expression in line [59] is for the phone numbers in the US locale, which is

"\s*[(]?[1-9]\d{2}[)]?\s*-?\s*\d{3}\s*-?\s*\d{4}" 

without the escape characters. The setPresetValue() method, line [77], in the Presets will throw PanamaException if the value does not match the regular expression. The full regular expression syntax, which is compatible with the org.apache.regexp.RE toolset, is given in the next section.

import oracle.panama.model.*;
import oracle.panama.PanamaException;
import oracle.panama.PanamaRuntimeException;
import oracle.panama.ArgumentType;

import java.util.Vector;
import java.util.Enumeration;
import java.util.Date;
import java.text.DateFormat;
import java.text.ParseException;

public class SamplePresets {

    public void addAppointment(User user, String title, String memo, Date time,
                               boolean alarm, String phone) throws 
PanamaException {
        ModelFactory factory = MetaLocator.getInstance().getModelFactory();
        ModelServices services = MetaLocator.getInstance().getModelServices();

        PresetCategory category;
        try {
            category = services.lookupPresetCategory("Appointments");
        } catch (PanamaRuntimeException ex1) {
            try {
                category = factory.createPresetCategory("Appointments");
                category.setSystem(false);         [25]
            } catch (PanamaException ex2) {
                throw ex2;
            }

            PresetDescriptor descriptor = category.createPresetDescriptor("Short 
Title");
            descriptor.setDescription("Brief description of the event");
            descriptor.setPresetType(ArgumentType.SINGLE_LINE);
            descriptor.setStoredType(java.sql.Types.VARCHAR);
            descriptor.setSize(new Long(40));

            descriptor = category.createPresetDescriptor("Memo");
            descriptor.setDescription("Memo for the event");
            descriptor.setPresetType(ArgumentType.MULTI_LINE);
            descriptor.setStoredType(java.sql.Types.VARCHAR);
            descriptor.setSize(new Long(400));

            descriptor = category.createPresetDescriptor("Time");
            descriptor.setDescription("Time of event");
            descriptor.setPresetType(ArgumentType.SINGLE_LINE);
            descriptor.setStoredType(java.sql.Types.VARCHAR);
            descriptor.setSize(new Long(40));

            descriptor = category.createPresetDescriptor("Alarm");
            descriptor.setDescription("Enable or disable alarm before event");
            descriptor.setPresetType(ArgumentType.SINGLE_LINE);
            descriptor.setStoredType(java.sql.Types.VARCHAR);
            descriptor.setSize(new Long(1));

            descriptor = category.createPresetDescriptor("Phone Number");
            descriptor.setDescription("Optional phone number to ring for 
alarm");
            descriptor.setPresetType(ArgumentType.SINGLE_LINE);
            descriptor.setStoredType(java.sql.Types.VARCHAR);
            descriptor.setSize(new Long(40));
            
descriptor.setFormat("\\s*[(]?[1-9]\\d{2}[)]?\\s*-?\\s*\\d{3}\\s*-?\\s*\\d{4}");      
[59]
            descriptor.setEmptyOK(true);

            factory.save();
        }

        Presets presets = user.createPresets(category);    [65]

        presets.setPresetValue("Short Title", title);
        presets.setPresetValue("Memo", memo);
        String timeStr = DateFormat.getDateTimeInstance().format(time);   [69]
        presets.setPresetValue("Time", timeStr);
        if (alarm) {
            presets.setPresetValue("Alarm", "Y");
        } else {
            presets.setPresetValue("Alarm", "Y");
        }
       try {
            presets.setPresetValue("Phone Number", phone);         [77]
        } catch (PanamaException ex) {
            // ignore
        }

        factory.save();
    }

    public Presets[] getAppointments(User user) throws PanamaException {
        ModelFactory factory = MetaLocator.getInstance().getModelFactory();
        ModelServices services = MetaLocator.getInstance().getModelServices();

        PresetCategory category;
        try {
            category = services.lookupPresetCategory("Appointments");
        } catch (PanamaRuntimeException ex1) {
            throw new PanamaException(ex1);
        }

        Date now = new Date(System.currentTimeMillis());
        Vector allPresets = user.getAllPresets(category);       [97]
        Enumeration enum = allPresets.elements();
        Vector pending = new Vector();
        while (enum.hasMoreElements()) {
            Presets event = (Presets) enum.nextElement();
            String timeStr = event.getPresetValue("Time");
            Date time;
            try {
                time = DateFormat.getDateTimeInstance().parse(timeStr);   [105]
            } catch (ParseException ex) {
                time = null;
            }
            if (time != null && time.after(now)) {
                pending.add(event);
            } else {
                user.deletePresets(category, new Long(event.getId()));    [112]
            }
        }
        factory.save();

        Presets presetsArray[] = new Presets[pending.size()];
        pending.copyInto(presetsArray);
        return presetsArray;
    }

}

11.2.3 Regular Expressions Syntax for the Presets Attribute Formats

The full regular expression syntax that can be used to define for formats is:

Table 11-1 Characters
Character Description

char

Matches any identical character

\

Used as an escape character (for example: \*, \\, \w)

\\

Matches a single '\' character

\0nnn

Matches a character with given octet number

\xhh

Matches a character with given 8-bit hexadecimal value

\\uhhhh

Matches a character with given 16-bit hexadecimal value

\t

Matches a tab character

\n

Matches a newline character

\r

Matches a return character

\f

Matches a form feed character

Table 11-2 Character Classes
Character Description

[abc]

Simple character class

[a-zA-Z]

Range character class; range specified with "-" and "]" (for example: [x-z]

[^abc]

Negated character class, for exclusion tests.

Table 11-3 Standard POSIX Character Classes
Character Description

[:alnum:]

Alphanumeric characters.

[:alpha:]

Alphabetic characters.

[:digit:]

Numeric characters.

[:upper:]

Upper-case alphabetic characters.

[:lower:]

Lower-case alphabetic characters.

[:space:]

Space characters (such as space, tab, and formfeed, to name a few).

Table 11-4 Variable Classes
Class Description

.

Matches any character other than newline

\w

Matches an alphanumeric character

\W

Matches a non-alphanumeric character

\s

Matches a whitespace character

\S

Matches a non-whitespace character

\d

Matches a digit character

\D

Matches a non-digit character

Table 11-5 Boundary Matchers
Matcher Description

^

Matches the beginning of a line

$

Matches the end of a line

\b

Matches a word boundary

\B

Matches a non-word boundary

Table 11-6 Greedy Closures (match as many elements as possible)
Element Description

A*

Matches A 0 or more times (greedy)

A

Matches A 1 or more times (greedy)

A?

Matches A 1 or 0 times (greedy)

A{n}

Matches A exactly n times (greedy)

A{n,}

Matches A at least n times (greedy)

A{n,m}

Matches A at least n but not more than m times (greedy)

Table 11-7 Reluctant Closures (match as few elements as possible)
Element Description

A*?

Matches A 0 or more times (reluctant)

A?

Matches A 1 or more times (reluctant)

A??

Matches A 0 or 1 times (reluctant)

Table 11-8 Logical Operators
Operator Description

AB

Matches A followed by B (concatenation)

A|B

Matches either A or B(union)

(A)

Matches subexpression inside "(" and ")", not including "(" and ")"

11.3 Location Marks

Location awareness is a key feature of Oracle9iAS Wireless. A user's location can be obtained from E911 or GPS units or Location Marks. Location Marks are user defined locations. For example, an end user may enter into their location-aware applications their home, work and headquarters office addresses. Then, when using a restaurant lookup application, the application can use the current location to provide driving directions. To ensure security and privacy, users can control which applications can access their location.

Due to the limitations of certain mobile devices such as telephones, it is difficult to input or display lengthy alphanumeric strings. A location mark stores a piece of spatial information identified by a concise, easy-to-understand name. For example, "My home" might be the name of a location mark, while the underlying spatial information might be "123 Main Street, Somewhere City, CA, 12345; Lon = -122.42, Lat = 37.58".

Users have complete control of their location marks and are easily able to select, create, delete and modify location with any device or PC.

Location marks also allow users to try "what-if" scenarios: to make an application behave as if they were in a location different from their default or current location. For example, a user of an entertainment services application might be in Boston, but will be traveling to San Francisco in a few days. This person could set a location mark in San Francisco, and be presented with information relevant to the San Francisco area. Each user can have personalized location marks, which are stored in the Wireless repository.

Location marks are created using the LocationMark class. Users can also create location marks by logging into the Oracle9iAS Wireless Customization Portal, clicking the LocationMarks tab, and clicking Create. See Chapter 15, "Using Location Services" for more information on using Location Marks with Geocoding, Mapping, Routing, Traffic and Region Modeling services.

11.4 User Device Management

Oracle9iAS Wireless gives users, with multiple devices, the ability to easily manage and optimize their mobile experience for each device. The user can manage their devices from either a PC or mobile device. In addition, users are easily able to modify their current default device.

Once a user creates a new device profile, they can enter the following attributes for each device:

11.5 Multiple Customization Profiles

Oracle9iAS Wireless enables development of user-centric web services that adapt the contents not only to the device and network capability but also to the end user's preferences. The device portals typically provide the menu of services, which may be organized under several folders and subfolders. Menu driven device portals are designed to optimize the interactive efficiency of wireless devices. Service menus are usually static but the portal may intelligently suggests new services to the user as it learns more about the user's needs and preferences. The Oracle9iAS Wireless server lets the end users personalize the portal by controlling the arrangement of the services in the menus. The portal can suggest new services to the user, but the user still controls when to include or exclude each service in the user's personalized portal. The administrators can explicitly prevent the end users from rearranging or removing certain services, such as promotions, preferred partners, emergency services, etc., from their personalized portals.

11.5.1 Concepts

The Profiles let the users create multiple personalized versions of the portals for their devices. The service menus may be different from one profile to another. For example, let's suppose that one of the folders for the user may contain the following five services:

In the Home profile, the service menu in the folder may be customized as:

The same folder may be customized differently for the Traveling profile as:

Multiple Profile's can be created for different roles, locations or contexts, device and network characteristics, or any other taxonomy. For a user with sale, marketing, and consulting responsibilities who may play multiple roles in the enterprise portal, Profile's may be created for each of these roles to increase efficiency and accessibility of services. For a nomadic user who frequents among multiple metropolitan centers, the profiles may be created for each location. For example, a user's customization Profile for a cultural center like "San Francisco" may include services for theaters, sporting events, and BART schedules. The same user may have another Profile for the lake Tahoe area with a different combination of services. A location aware portal can automatically set the session Profile's for the users when they connect from different locations.

The Oracle9iAS Wireless runtime controllers can be extended to automatically provision the Profile's for users, for example to provide different views of the portal from more than one type of device. The example in the following section describes how to automatically provision a profile for the user. Alternatively, end users can create any number of Profile's for any context through the Customization Portal via a PC browser. Through the Service Management tool in the Customization Portal, they can customize the arrangement of services for each of the Profile's.

The administrators can specify the default sorting rules for the shared folders. Under the Profile architecture, end users can alter the default sorting rules to personalize the views of the shared folders. They can choose from the following five sorting rules:

The sequence numbers, lexicographic ordering, and date of creation produce the static views of the folders. Sorting by frequency of access or last access time produces the dynamic views of the folders. Furthermore, the administrators can control the static or dynamic arrangements of some of the services in the folder, such as emergency, promotion, and preferred partner's services, that may not be rearranged by the end users. The administrators can designate the segments of the views that may be rearranged or hidden by the end users. The view of the folder may be segmented such that one segment is sorted by the administrator's specification and another segment is sorted by the user's specification.

The Profile architecture lets the end users specify the visibility of a service in the profile provided the administrator does not explicitly disable the personalizable attribute of a service. This lets the end users "subscribe" or "unsubscribe" a service that may be placed in the user's folder by the system. The system may also apply the location based filtering of the services in the location enabled folders, which offers additional dynamism to the views that vary with the user's mobile position.

Services that access the runtime objects can get the current Profile from the ServiceContext.getProfile method. See Section 10.6, "Runtime and Data Model APIs" for the description of runtime objects. This method first looks up the Profile in the current Request. If the Request does not specify a Profile, the method looks in the runtime Session for the session Profile. If the session Profile is empty, then the method looks up the default Profile of the User. This resolution strategy lets the Request overrides the session Profile, and the session to override the default User Profile. ServiceContext.getProfile can return null if there is no Profile at all. Applications should be prepared to react with default behavior when the Profile is not specified.

11.5.2 Sample Applications

The following example describes how to automatically provision a Profile for each of the devices that the User may use. The SampleRequestListener listens for the serviceBegin() event and provisions a new Profile in line [25] and [27] if the Request and Session do not already specify a Profile, line [17] and [19]. For the new Profile, it sets the user's home folder to sort the services in the home folder by the last access time of the service in line [36]. For each service that is view customizable in line [39], it sets the service to be hidden in the Profile in line [40]. The end users can later customize the Profile's to unhide the services that they want to use. This needs to be done only once after the Profile's are first created. The listener then sets the Profile in the Request in line [54].

import oracle.panama.model.*;
import oracle.panama.rt.Session;
import oracle.panama.rt.Request;
import oracle.panama.rt.event.RequestAdapter;
import oracle.panama.rt.event.RequestEvent;
import oracle.panama.rt.event.AbortServiceException;
import oracle.panama.PanamaException;

public class SampleRequestListener extends RequestAdapter {

    public void serviceBegin(RequestEvent event) throws AbortServiceException {
        Request request = event.getRequest();
        Session session = request.getSession();
        User user = session.getUser();

        Profile profile = request.getProfile();         [17]
        if (profile == null)
            profile = session.getProfile();                [19]
        if (profile == null) {
            Device device = request.getDevice();
            String deviceName = device.getName();
            Profile deviceProfile;
            synchronized(user) {
                deviceProfile = user.lookupProfile(deviceName);         [25]
                if (deviceProfile == null) {
                    deviceProfile = user.createProfile(deviceName);      [27]
                    ModelFactory factory = 
MetaLocator.getInstance().getModelFactory();
                    try {
                        factory.save();
                    } catch (PanamaException ex) {
                        deviceProfile = null;
                    }
                    if (deviceProfile != null) {
                        boolean needCommit = false;
                        Folder home = user.getHomeFolder();
                        deviceProfile.setSortRule(home, SortRule.SORT_BY_ACCESS_
TIME_ASCEND);    [36]
                        Service[] services = 
home.getAccessibleUserServices(user);
                        for (int i = 0; i < services.length; i++) {
                            if (services[i].isViewCustomizable()) {           
[39]
                                deviceProfile.setHide(services[i], true);      
[40]
                                needCommit = true;
                            }
                        }
                        try {
                            if (needCommit)
                                factory.save();
                        } catch (PanamaException ex) {

                        }
                    }
                }
            }
            if (deviceProfile != null)
                request.setProfile(deviceProfile);                  [54]
        }
    }

}

11.6 User and Group Management

Oracle9iAS Wireless has advanced group and user management. Any user that is granted "User Manager" abilities is able to create, delete and modify groups and users through any device or PC. Any Group or User can be restricted or granted access to any folder or service.

Advanced Access Control List (ACL) used with the User and Group Management allows for fine grained access control that takes advantage of the flexible user or group policies that may be applied to Services or Folders

11.7 Service Management

Oracle9iAS Wireless offers complete control to the developer to manage what end users can do in terms of folder management. Developers can offer groups or users complete flexibility with their Service Management or restricted use of Service Management.

Services and folders may be organized in the following ways:

The end user also has the ability to customize their mobile experience with Bookmarks and Quicklinks. This gives users the ability to link frequently accessed services to the home deck or any other desired folder.

11.8 Rebranding the Customization Portal

11.8.1 Overview

Oracle9iAS Wireless Customization Portal is both a framework for the Customization interface and a sample implementation of that framework. The framework consists of JavaServer Pages (JSP) files, JavaBean modules, JavaScript, and such static elements as images, XSL stylesheets, and HTML files. Another element of the framework is the logical sequence in which the elements execute. You can rebrand the Customization Portal based on the existing framework or restructure the framework itself by altering the logic in the JSP files and JavaBeans.

The following sections describe the elements that generate the Customization Portal and their order of execution, as well as the file naming conventions and the directory structure used.

11.8.2 Page Naming Conventions

Some Customization Portal pages display information, while others allow you to customize user information or repository object characteristics. The JSP files execute the tasks that are associated with user customization.

Each JSP file consists of an action applied to an object. One part of the JSP file name represents the action (usually Ed or Do, as in EdFolder.jsp and DoFolder.jsp). A second part of the file name represents the object (or the target) of the action, such as, Folder, Service, Alert, or Bookmark.

For example, to customize a user from the Service Subscription page Myservice.jsp, click the User link to invoke EdFolder.jsp, which displays the editable characteristics of that folder. In this example, the action is editing; it is represented by the prefix Ed in the file name. The object of the action is folder; it is represented by Folder in the file name. To apply the changes that you have made, the DoFolder.jsp file processes the input.

In this case, the actions are Ed and Do; the object is Folder.

There are action/object combinations for all Customization Portal objects. For example:

11.8.3 JavaServer Pages Structure

Each Customization Portal JSP is composed of a series of JavaBeans assembled to generate the page when they are rendered. Each JavaBean is a reusable element and can be rendered individually or as part of the JSP.

Figure 11-3 Sample Page JavaBean Structure

Text description of rebrand1.gif follows.

Text description of the illustration rebrand1.gif

Figure 11-4 JavaBean Location on Sample Page

Text description of jb1.gif follows.

Text description of the illustration jb1.gif

Table 11-9 JavaBean Function
JavaBean Description

Root

Encompasses the JSP and allows it to be rendered as a whole.

1. Form and Page Layout

Establishes the Header and Footer and reserves the remainder of the page for other content. This component contains the Tab Bar, Navigation Trace, Row Layout, and Button elements.

Figure 11-5 Form and Page Layout

Text description of jb2.gif follows.

Text description of the illustration jb2.gif

2. Header

Company branding and Tab Bar.

Figure 11-6 Header

Text description of jb3.gif follows.

Text description of the illustration jb3.gif

3. Navigation Trace

Displays navigation cue and display name elements.

Figure 11-7 Navigation Tree

Text description of jb4.gif follows.

Text description of the illustration jb4.gif

4. Footer

Global button links and Copyright information.

Figure 11-8 Footer

Text description of jb5.gif follows.

Text description of the illustration jb5.gif

5. Row Layout

The main section of the page, which contains Tree, Cell, and Button elements.

Figure 11-9 Row Layout

Text description of jb6.gif follows.

Text description of the illustration jb6.gif

6. HGrid Table

Linked hierarchical lists.

Figure 11-10 HGrid Table

Text description of jb7.gif follows.

Text description of the illustration jb7.gif

7. Button bar

Used to approve or cancel page actions. This is part of a row layout.

Figure 11-11 Button bar

Text description of jb8.gif follows.

Text description of the illustration jb8.gif

Pages can be modified in one of two ways.

11.8.4 Directory Structure

To rebrand the Customization Portal, you modify the JSP files that generate the Customization Portal. After installing Oracle9iAS Wireless, these files are located in the $ORACLE_HOME/OC4J_Wireless/j2ee/applications/customization directory which has the following structure:

Table 11-10 Portal Directory Contents

Directory Contents

customization-web

Container JSP files. Container files are accessed directly by browsers. also contains JavaScript files.

customization-web/images

Images used throughout the Customization Portal.

customization-web/Web-inf/jsp

Module JSP files. These files are included by either container JSP files or other module JSP files.

customization-web/cabo

JavaBean stylesheet, image, and JavaScript.

customization-web/cabo/images

JavaBean static images.

customization-web/cabo/images/cache

JavaBean generated images.

customization-web/cabo/jsLibs

Javascript.

customization-web/cabo/styles

Stylesheets.

customization-web/cabo/styles/cache

Generated stylesheets.

portal/messages/portal.properties

Sets page contents. For more information, see Section 11.8.7, "Setting the Multi-Byte Encoding for the Customization Portal".

11.8.5 Customization Levels

Customization Portal pages can be customized in several different ways. You can easily alter the appearance of logos, banners, and icons. Alternatively, you may want to create your own JSP to achieve the desired look and feel.

11.8.5.1 Appearance Customization

This method requires replacing static strings in the HookFunc.jsp file located in the $ORACLE_HOME/OC4J_Wireless/j2ee/applications/customization/customization-web/WEB-INF/jsp directory. By changing the file names called in by these static strings, you can alter the banner art, logo art, and tool tip text.

Table 11-11 HookFunc.jsp String Usage
String Page Element

logoImage

Page logo image

logoDesc

Page logo tool tip text

advImage

Optional advertising banner image

advDescrip

Optional advertising banner image tool tip text

advDest

Optional advertising banner image destination

11.8.5.2 Colors and Fonts

The colors and fonts can be customized by modifying the XML Style Sheet file:

$ORACLE_HOME/j2ee/OC4J_Wireless/applications/customization/customization-web/

cabo/styles/blaf.xss.

After the modification, remove:

$ORACLE_HOME/j2ee/OC4J_Wireless/applications/customization/customization-web/

cabo/styles/cache directory, and restart the server.

The new Colors and Fonts will take effect on the Web page.

11.8.5.3 JSP Modification

The JSP file PageTemp.jsp generates the Customization Portal page template. PageTemp.jsp is included in other JSP files which generate different contents in each page.

11.8.6 Customization Components

The edit and action JSP files execute the tasks associated with user customization:

For example, to rename a folder, Oracle9iAS Wireless first invokes EdFolder.jsp, then DoFolder.jsp.

Users can customize or configure the following:

11.8.6.1 Flow Example - Customizing a Services

The MyService.jsp file displays the Service Subscription page, which allows the user to customize or copy a service. Depending on the option selected by the user, an input form is displayed by an EdService.jsp file. When the user clicks a button on the input form, the flow moves to a DoService.jsp file. The DoService.jsp file posts and processes input values, and, depending on the validity of the input values, returns to the MyService.jsp or displays an error message. The following figure displays the flow of control when a user edits a service.

Figure 11-12 Service Customization Flow

Text description of rebrand4.gif follows.

Text description of the illustration rebrand4.gif


Note:

The action pages, DoService.jsp and DoFolder.jsp have no display component, they perform their function, update the database, and then return the user to an input page, such as EdFolder.jsp or MyService.jsp.


11.8.6.2 Creating New JSP

To create a new JSP, you implement the Customization Portal API. The classes in this API enable you to customize a version of the Customization Portal by providing a set of interfaces for portal customization.

11.8.7 Setting the Multi-Byte Encoding for the Customization Portal

The Customization Portal gets the encoding for the text of the site from the setting in the PAPZ logical device, which is in the repository. The default encoding is UTF-8, which can handle Western European languages as well as some Asian languages. The portal sets the content for each page with the encoding specified by the logical device. To change the default encoding, click PAPZ under Logical Devices in the Service Designer and change the encoding according to the IANA standards for your particular language.

The UI labels are loaded from portal_LANGUAGE (_COUNTRY if any). For example, portal_fr_CA.properties in the directory: $ORACLE_HOME/OC4J_Wireless/j2ee/server/classes/messages. Before login, the locale is determined by the Oracle9iAS Wireless locale setting. After login, the locale setting is determined by the user's locale preference.

11.9 Using the Customization Portal API

This section describes the Oracle9iAS Wireless Customization Portal API.

11.9.1 Overview

The Customization Portal API classes are designed to allow you to customize a version of the Oracle9iAS Wireless Customization 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 Customization 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 Customization Portal API, see the Oracle9iAS Wireless Javadoc.


11.9.2 Customization Portal API Classes

The Oracle9iAS Wireless Customization 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 Customization 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.

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.

11.9.2.1 Login and Initialize Session - RequestController

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

For more details on Controller APIs, see the javadoc included with Oracle9iAS Wireless.

11.9.2.2 User Creation and Modification - UserController

UserController oversees operations involving users, such as:

For more details on User Controller APIs, see the javadoc included with Oracle9iAS Wireless.

11.9.2.3 Object Customization--ServiceController

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

For more details on Service Controller APIs, see the javadoc included with Oracle9iAS Wireless.

11.9.2.4 Alert Subscription Customization--Alert Subscription Controller

AlertSubscription handles operations of alert subscription and trigger settings such as:

For more details on Alert Subscription Controller APIs, see the javadoc included with Oracle9iAS Wireless.

11.9.2.5 Device Customization--Device Controller

Device Controller handles device customization activities, such as:

For more information, see Oracle9iAS Wireless Getting Started and System Guide, and the javadoc included with Oracle9iAS Wireless.

11.9.2.6 Alert Customization--AlertController (deprecated)

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

11.9.2.7 Locationmark Creation and Modification--LocationMarkController

LocationMarkController manages operations with locationmarks including:

For more details on LocationMark Controller APIs, see the javadoc included with Oracle9iAS Wireless.

11.9.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 11-13 Session Flow

Text description of rebrand5.gif follows.

Text description of the illustration rebrand5.gif

11.9.3.1 Sample Code

The following code samples demonstrate an example of an HTTP session based on the process illustrated above.

11.9.3.2 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) {
}

11.9.3.3 Initialize Session

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

11.9.3.4 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) {
}

11.9.3.5 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) {
}

11.9.3.6 Cleanup Request

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

Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index