9 Using Multi-Channel Server

9.1.1 Benefits of Multi-Channel

Oracle took the Multi-Channel challenge very seriously and decided to do something to help developers and enterprises to easily develop their applications only once for all channels. OracleAS Wireless Multi-Channel Server (MCS) hides the complexity that all channels present to developers. It acts as a single browser that accesses web applications.

The Multi-Channel Server supports three device-independent markup languages for developing applications:

• XHTML+XForms—XHTML 1.0 (http://www.w3.org/TR/xhtml1/) standard markup language with XForms (http://www.w3.org/TR/xforms/) support

• XHTML Mobile Profile (XHTML MP)—standard markup language (http://www1.wapforum.org/tech/documents/WAP-277-XHTMLMP-20011029-a.pdf) defined by Open Mobile Alliance Ltd. (http://www.openmobilealliance.org/)

• OracleAS Wireless XML—markup language defined by OracleAS Wireless

Some developers may not be concerned with multi-channel, and may only want to expose their applications to, say, the voice channel. Why use MCS in such a case? There are at least two reasons why even in that case you should consider the MCS:

• You can develop your application using XHTML instead of VoiceXML. Most web developers already know XHTML and they will not need to learn VoiceXML. This obviously will save you time and money.

• There are a variety of Voice Gateways that support different varieties of VoiceXML. So, if you develop your application in native VoiceXML, then you must certify your application against all the different voice gateways. MCS guarantees that your application will work with many voice gateways without any changes.

Even if you are planning to expose your application through only one channel now, you may reconsider this in the future and decide that it will be beneficial to provide additional access to that application. In that case, you will not need to make changes in the application because MCS will already support the new channel.

9.1.2 Features of Multi-Channel Server

Here are some of the key features of Multi-Channel Server:

• Multi-Channel Content Adaptation—the same device-independent content is delivered to different channels on different devices. Multi-Channel Server adapts application content based on current user device capabilities. It considers the device-specific markup language, screen size, network speed, etc.

• Support for Standard Markup Languages—applications are developed using standard markup languages. That saves development time and money since developers are not required to learn new markup languages. Even if the application is to be delivered to a single channel (for example, voice), developers do not need to learn a new channel-specific markup language. They can use the very popular XHTML and still deliver their content to VoiceXML or WML or other devices.

• Devices and Gateways Certification—with so many emerging devices and gateways on the market, it is difficult for application developers to certify that their application will run on all of them. There are only two major browsers for the PC, but still most web applications must be tailored to work best on either one of them. When you consider the new mobile devices, it becomes impossible for the developers to guarantee that their applications will work on all of them. Multi-Channel Server ensures compatibility with all those devices.

• Device Detection—Multi-Channel Server uses a sophisticated algorithm to detect devices making requests. It takes into account User-Agent, Accept, and other HTTP headers. Some device capabilities (for newer devices) are also submitted with the request by the device and used for best content adaptation.

• Multimedia Adaptation—along with text adaptation, Multi-Channel Server does device-specific adaptation of images, ringtones, voice grammars and audio/video streams.

• Single Browser—Multi-Channel Server is the only browser that the applications interact with. It shields application developers from any deficiencies that the end user device may have. For example, most mobile devices do not support HTTP cookies. But cookies are the easiest way to keep user sessions. Multi-Channel Server handles session and other cookies on behalf of the end user device.

• XForms Engine—Multi-Channel Server adds the power of XForms (http://www.w3.org/TR/xforms/) support to any user device.

• Work with Existing Portals—access any device through your existing Portal by deploying Multi-Channel Server in front of your Portal server.

• URL Caching—some devices have very limited memory, thus they limit the content that they can receive. Multi-Channel Server caches long URLs that are sent to a device, reducing the content size.

In addition to Multi-Channel Server, Oracle Application Server also includes Wireless and Voice Portal built on top of MCS. Here are some of the additional features that are provided by the Wireless and Voice Portal:

• Portal—the Wireless and Voice Portal provides full portal capabilities, including users and services managements, ACL, etc. The portal provides users with their own customizable home page which is a launch pad for individual services. The available services have a wide variety of forms, including database information, personalization, alerts, and location services. The large number of content sources adds to the complexity of having a manageable way to deliver each application to every type of device in the most optimized fashion.

• Network Adaptation—in addition to the HTTP(S) protocol, the Wireless and Voice Portal also supports various other protocols to allow access from non-HTTP devices. Network adaptation is based on an extensible framework that allows customers to plug in their own drivers for adapting to any network protocol.

• J2ME WebServices—the Wireless and Voice Portal provides a WebServices proxy to let J2ME-enabled devices access WebServices. This enables MIDlets developers to enhance their applications by accessing any external applications exposed as WebServices.

The following figure shows the main components of the Multi-Channel Server.

Multi-Channel Server is an extensible applications platform. It is built from pluggable modules. Modules implementation can be replaced to alter the default behavior. All modules and their default implementation are described below.

9.2.1 Overview of Multimedia Adaptation Services

OracleAS Wireless Multimedia Adaptation Services provide device-specific adaptation of images, ringtones, voice grammars and audio/video streams. These services are an integral part of the core Multi-Channel Server.

Devices and the browsers on them support different image formats, and have different screen sizes and color depths. As part of the content adaptation performed by OracleAS Wireless in responding to a request, images are dynamically adapted to suit client devices. Additionally, the new Intelligent Messaging component uses Image Adaptation Services to convert images for EMS and MMS.

Ringtone adaptation is provided as a Java API and allows for conversion of ringtone data to formats supported by the most popular phones. The supported formats include RTTL, iMelody and MIDI. The framework for ringtone adaptation allows developers to easily add support for new ringtone formats. The Intelligent Messaging component uses Ringtone Adaptation Services to convert ringtones for delivery through SMS, EMS and MMS.

Multimedia Adaptation Services further enhance the voice support of OracleAS Wireless by allowing voice gateway vendors to extend the OracleAS Wireless platform to support new or vendor-specific grammar formats. These formats are transformed (through the SimpleGrammar tag) into the format supported by the voice browser. Grammars that are defined in OracleAS Wireless XML are considered inline, whereas those provided by a URL reference are considered external. Voice gateway vendors wanting to support a new grammar format can easily provide XSL stylesheets to transform OracleAS Wireless XML grammars to their grammar format. Support for inline grammar transformation is provided directly in the voice transformer, and Oracle Corporation also provides a framework for external voice grammar transformations using the relevant XSL stylesheet.

9.2.2 Image Adaptation Features

The most important features of image adaptation are:

• Support for multiple input image formats.

  • File Formats: BMP, GIF, JFIF, PNG, TIFF, WBMP

  • Content Formats: MONOCHROME, 1BIT, 2BIT, 4BIT, 8BIT, 12BIT, 16BIT, 24BIT, 32BIT, 48BIT, LUT, DRCT, RGB, GRAY

  • Compression Formats: JPEG, BMPRLE, LZW, LZWHDIFF, FAX3, FAX4, HUFFMAN3, PACKBITS, GIFLZW, DEFLATE

• Support for multiple output image content formats including support for different color depths, compression formats, color schemes and file formats.

  • File Formats: JFIF (JPEG), GIF, BMP, WBMP, PNG

  • Compression: JPEG, GIFLZW, BMPRLE, DEFLATE

  • Content Formats: MONOCHROME, 2BITLUTGRAY, 4BITLUTGRAY, 8BITLUTGRAY, 8BITLUTRGB, 24BITRGB, 8BITGRAY

• Support for scaling and resizing images.

  • Scale to fixed dimensions.

  • Maintaining aspect ratio, scale to fit in a bounding box. (If original image dimensions are smaller than desired image dimensions, the original image dimension is used to define a bounding box.)

  • Reduce size of image data in bytes to honor limits on size placed by device/network.

  • Provides the above image processing functionality as a J2EE-compliant component of OracleAS Wireless.

• Supports limitation on URL length.

• Supports inbound and outbound image caching. Inbound caching means that the original images are cached in the middle tier (using webcache) so that the requests from different device types for the same image would result in one fetch of the original image. Outbound caching means that the adapted images are cached (using webcache) so that different users on similar devices can share the same adapted image.

  
  

  Note: Image caching policy is determined by the owner of the original image. MCS passes on cache headers to the web cache so that if certain images are not cacheable, web cache will not cache them.

  
  

9.2.3 Command-Line Tool

A command line tool is provided to convert images in batch mode before deployment to the web/wireless application.

• Name: ImageGenerate.{bat|sh}

• Description: A shell or unix shell script that invokes a Java application to generate images in all the formats supported by the different devices from a specified input image. The batch or script file can be found in ORACLE_HOME\wireless\bin\ImageGenerate.bat for Windows and in ORACLE_HOME/wireless/bin/ImageGenerate.sh for Unix.

• Usage:

  ImageGenerate.{bat|sh} -inFile filename -outFile filename [-outW width] [-outH height] -outFormat format [-outContent contentType] [-dataSizeLimit limit] [-maintainRatio {true|false}]
  
  

• Parameters

  • inFile filename - The filename of the input file to process. Required argument.

  • outFile filename - The resulting file after processing. Required argument.

  • outW width - The width in pixels of the resulting image. Optional argument.

  • outFormat format - The output file format of the resulting image.

    For examples, see interMedia User's Guide (available on Oracle Technology Network) for full specification.

    Examples include: GIFF - Gif format, JFIF - jpg format, WBMP - wbmp format. PNGF - png format. Required argument.

  • outContent contentType - The content format of the resulting image.

    For example, MONOCHROME to change the image to a black and white representation, or for GIF images 4BITLUT to change to 4 bit (16 color) representation. See interMedia User's Guide for full specification. Optional argument.

  • dataLimitSize datalimitsize - For GIF images only. Make the image fit in the specified size by reducing the pixel depth, eventually to monochrome, and then reducing the image size if necessary. Optional argument.

  • maintainRatio {true | false} - Maintain the aspect ratio of the image. Make it fit within box bounded by outW and outH. Default true. Optional argument.

    Usage:

    ImageGenerate -inFile stock_600_450.jpg -outFile stock_240_180.gif -outW 240 -outH 180 -outContent monochrome -outFormat giff
    
    

    
    

    Note: Ensure that either Java_HOME or ORACLE_HOME is defined as an environmental variable.

    
    

9.2.4 Extensibility Using ImageProcessor API

This section details the ImageProcessor API.

package oracle.panama.multimedia;
 
import oracle.panama.model.Device;
 
/** Use this interface to replace the existing Image processing
 *  implementation for all formats with your own implementation
 */
public interface ImageProcessor {
ImageResponse process(ImageRequest request, Device) throws MultimediaException;
}

9.2.5 Ringtone Adaptation

This section describes ringtone adaptation.

package oracle.panama.multimedia;
 
/** Use this interface to replace the existing Ringtone processing
 *  implementation for all formats with your own implementation
 */
public interface RingtoneProcessor {
RingtoneResponse process(RingtoneRequest request) throws MultimediaException;
}

package oracle.panama.multimedia;
import Java.io.InputStream;
public class RingtoneRequest {
    /** Ringtone input data types */
    public static int RINGTONE_DATA_STRING = 0;
    public static int RINGTONE_DATA_STREAM = 1;
    public static int RINGTONE_DATA_BYTES = 2;
    public static int RINGTONE_DATA_NULL = -1;
    public String inputFormat = null;
    public String outputFormat = null;
    public String inputMimeType = null;
    public String outputMimeType = null;
    private String dataString = null;
    private InputStream dataStream = null;
    private byte[] dataBytes = null;
    private int dataType = RINGTONE_DATA_NULL;
    public RingtoneRequest()  {
    }
 
    public void setData (String ringtone) {
    	this.dataString = ringtone;
    	this.dataType = RINGTONE_DATA_STRING;
    }
 
    public void setData (InputStream ringtone) {
    	this.dataStream = ringtone;
    	this.dataType = RINGTONE_DATA_STREAM;
    }
 
    public void setData (byte[] ringtone) {
    	this.dataBytes = ringtone;
    	this.dataType = RINGTONE_DATA_BYTES;
    }
 
    public String getDataAsString () {
    	return this.dataString;
    }
 
    public InputStream getDataAsStream() {
    	return this.dataStream;
    }
 
    public byte[] getDataAsBytes() {
	    return this.dataBytes;
    }
 
    /** note, no setDataType method is provided to prevent
     *  inconsistency. The dataType attribute is set when 
     *  setting data.
     */
    public int getDataType() {
    	return this.dataType;
    }
}

package oracle.panama.multimedia;
 
import Java.io.OutputStream;
 
public class RingtoneResponse {
    public String inputFormat = null;
    public String outputFormat = null;
    public String inputMimeType = null;
    public String outputMimeType = null;
    private String dataString = null;
    private OutputStream dataStream = null;
    private byte[] dataBytes = null;
    private int dataType = RingtoneRequest.RINGTONE_DATA_NULL;
    public RingtoneResponse()  {
    }
 
    public void setData (String ringtone) {
    	this.dataString = ringtone;
    	this.dataType = RingtoneRequest.RINGTONE_DATA_STRING;
    }
 
    public void setData (OutputStream ringtone) {
    	this.dataStream = ringtone;
    	this.dataType = RingtoneRequest.RINGTONE_DATA_STREAM;
    }
 
    public void setData (byte[] ringtone) {
    	this.dataBytes = ringtone;
    	this.dataType = RingtoneRequest.RINGTONE_DATA_BYTES;
    }
 
    public String getDataAsString () {
      return this.dataString;
    }
 
    public OutputStream getDataAsStream() {
    	return this.dataStream;
    }
 
    public byte[] getDataAsBytes() {
    	return this.dataBytes;
    }
 
    /** note, no setDataType method is provided to prevent
     *  inconsistency. The dataType attribute is set when 
     *  setting data.
     */
    public int getDataType() {
    	return this.dataType;
    }
}

import Java.io.FileOutputStream;
import Java.io.ByteArrayOutputStream;
import oracle.panama.multimedia.RingtoneProcessor;
import oracle.panama.multimedia.RingtoneRequest;
import oracle.panama.multimedia.RingtoneResponse;
import oracle.panama.multimedia.MultimediaException;
 
public class RingtoneUserTest {
 
public static void main(String[] args) {
try {
RingtoneProcessor processor = 
RingtoneProcessorProvider.getProvider();
if (processor != null) {
   RingtoneRequest request = new RingtoneRequest();
   request.inputFormat = "IMELODY";
request.setData("BEGIN:IMELODY\nVERSION:1.2\nFORMAT:CLASS1.0\nMELODY:r1a1a2a3e3lmnop2a2a2a2g2a2r3a3a3e3g2a3a3a2a2g2\nEND:IMELODY\r\n");
request.outputFormat = "RTTTL";
   RingtoneResponse response = processor.process(request);
   int dType = response.getDataType();
   if (dType == RingtoneRequest.RINGTONE_DATA_STRING) {
   System.out.println(response.getDataAsString());
   } else if (dType == RingtoneRequest.RINGTONE_DATA_STREAM) {
   FileOutputStream outFile = 
   new FileOutputStream("ringtone.txt");
   ((ByteArrayOutputStream) 
   response.getDataAsStream()).writeTo(outFile);
   } else if (dType == RingtoneRequest.RINGTONE_DATA_BYTES) {
     // process the byte array response
   } else {
   // process failed to set the response data
   }
} else {
// Processor is null!! No ringtone converter available
System.out.println("No ringtone converter available");
}
} catch (Exception ex) {
ex.printStackTrace();
} catch (Error e) {
e.printStackTrace();
System.out.println("Error parsing ringtone");
}
    }
}

9.2.6 Ringtone Converter Java API

This section describes the ringtone converter API.

public RingtoneResponse convert (RingtoneRequest request);

------------------
#Formats
 
ringtone.formats=RTTTL NOKIA IMELODY MIDI
 
#Converters in one string:triplets of "from format","to format","impln class"
 
ringtone.converters=RTTTL NOKIA oracle.panama.multimedia.RingtoneConverterImpl\
                 RTTTL IMELODY oracle.panama.multimedia.RingtoneConverterImpl \
                 IMELODY RTTTL oracle.panama.multimedia.RingtoneConverterImpl \
                 IMELODY MIDI oracle.panama.multimedia.RingtoneConverterImpl
 
-------------------
 

-------------------------
#Formats
 
ringtone.formats=RTTTL NOKIA IMELODY MIDI RTTTL2
 
#Converters in one string:triplets of "from format","to format","impln class"
 
ringtone.converters=RTTTL NOKIA oracle.panama.multimedia.RingtoneConverterImpl\
                 RTTTL IMELODY oracle.panama.multimedia.RingtoneConverterImpl \
                 IMELODY RTTTL oracle.panama.multimedia.RingtoneConverterImpl \
                 IMELODY MIDI oracle.panama.multimedia.RingtoneConverterImpl \
                 RTTTL RTTTL2 my.package.RTTTLToRTTTL2Converter \
-----------------------

9.3.1 Device Repository

OracleAS Wireless Device Repository contains a wealth of device knowledge that is at the heart of the system. Administrators and developers can add new device information using the OracleAS Wireless Tools.

All information in the Device Repository is used for source content adaptation to the target device. It is important the information in the repository be kept up-to-date.

9.3.2 Device Repository Access

Developers can access information in the Device Repository in these ways:

• Oracle Application Server Device Repository API

• W3C CSS Media Queries Standard

Oracle Application Server Device Repository API is a set of Java APIs available to Java and JSP developers for programmable API access to the Device Repository. CSS Media Queries can be used by OracleAS Wireless Markup authors to access Device Repository information directly from the source document. CSS Media Queries is W3C Standard with Candidate Recommendation status. For further information on CSS Media Queries, see OracleAS Wireless CSS Support on Oracle Technology Network.

9.3.3 Device Detection

OracleAS Wireless automatically detects the type of device making a service request. The device detection component uses the User Agent, if available, to determine which device from the Device Repository to associate with the service request.

Here is how the device detection rule works:

1. If the UserAgent is not available in the HTTP Header, then proceed to Step 4.

2. Select a device from the Device Repository, where the useragent match string matches the UserAgent from the HTTP Header.

3. If more than one device is returned, then choose the one with the longest useragent match string. If this result in exactly one device matched, then return the device. Done.

4. Use the Accept HTTP Header to determine the preferred content types as per the IETF RFC-2616 specification.

5. Return the first device that matches the preferred mime-type.

6. If the request contains x-up-devcap-screenpixels and x-up-devcap-screenchars HTTP headers, then find the closest matching logical device using ScreenWidth, ScreenHeight, ScreenRows, ScreenColumns attributes of the device.

7. If there are no devices selected, then log an error in the log file.

Device Detection in OracleAS Wireless can be customized by specifying a hook class that implements the interface:

oracle.panama.rt.hook.DeviceIdentificationHook

The default implementation of the hook is provided in:

oracle.panma.rt.hook.DeviceIdentificationPolicy class

9.3.4 Dynamic HTTP Header Composition and UAProf

The Device Repository APIs perform Dynamic HTTP Header form factor composition when such information is in the HTTP Request. Dynamic HTTP Header composition is accomplished as follows:

1. Retrieve the device information from the repository and create an instance of oracle.panama.model.DeviceV2 object.

2. Search for known device form factor information in the HTTP Header and update the appropriate attributes in oracle.panama.model.DeviceV2.

9.3.5 Device Transformers

The final phase in Oracle Application Server Device Adaptation is the selection and invocation of the device transformers to generate the markup language suitable for rendering on the target device from a supported source input document. Every device in the Device Repository has a list of appropriate transformers for that device.

The device transformers are grouped by the OracleAS Wireless Markup Language it accepts as an input source document as shown in Table 9-1.

Table 9-2 lists transformers, accepted by OracleAS Wireless Markup Language and the generated markup by the transformer:.

Table 9-3 lists the device transformers for XHTML+XForms.

Table 9-4 lists the device transformers for XHTML + MP.

9.3.6 Device Repository API

oracle.panama.model.Device API is deprecated. There is a new API available, oracle.panama.model.DeviceV2. DeviceV2 interface should be used to access the Device Repository from Java and JSP applications.

DeviceV2 interface can be accessed from the old Device API as follows:

Device device = RequestFactory.lookupRequest();
DeviceV2 devicev2 = device.getDeviceV2();

The above code segment retrieves the target device from the Device Repository for the current HTTP Request context. That is, devicev2 is a handle to the actual device information.

Once a handle is obtained for a DeviceV2 interface, retrieving device attributes or capability is straight-forward. There are three methods provided to retrieve the capability value as a Java boolean, String, or int as in Example 9-7

boolean bool = devicev2.getDeliveryContextAttributeBoolean(DeviceAttr.COLORCAPABLE);
String model = devicev2.getDeliveryContextAttributeString(DeviceAttr.MODEL); 
int width = devicev2.getDeliveryContextAttributeString(DeviceAttr.DEVICEWIDTH);

All device attributes or capabilities are listed in the oracle.panama.model.DeviceAttr interface. Table 9-5 lists all device attributes or capabilities.

Table 9-6 lists browser capabilities.

Table 9-7 lists messaging capabilities.

Table 9-8 lists VoiceXML gateway capabilities.

Table 9-9 lists the Java (J2ME) capabilities.

9.3.7 Device Information and Classification

OracleAS Wireless Server sends information about the user device to the back end applications using HTTP headers. This information may be used by the application to optimize the content that it generates. Table 9-10 lists of headers that an application will receive.

9.4.1 MCS Runtime Session Management

OracleAS Wireless MCS runtime tracks runtime sessions independently of the OC4J Servlet sessions by rewriting every URL with an added parameter, PAsid, which specifies the MCS session ids. The session tracking identifies that a sequence of requests are submitted by the same user. The MCS runtime session contains the device credentials, user preferences, runtime contexts, cookies, URL caches, and other states essential for context-sensitive services. Furthermore, these MCS session states can be persistent. The MCS session id is used to restore the persistent MCS session states any time the MCS session id is referenced in the request, for example by putting the PAsid parameter in the URL. The MCS runtime maintains the runtime session so that users connecting through transient sessions under the alternative channels can share long-lived MCS runtime sessions. The persistent MCS sessions increase the life time of sessions and make the multi-modal interaction more enduring.

MCS runtime sessions can be bound to OC4J Servlet sessions. WAP 2.0 devices that implement the WAP HTTP State Management Specification (http://www.wapforum.org/) can support cookies for session management. Most of the commercial WAP gateways manage cookies on behalf of WAP devices. If the device or gateway does not support cookies, the OC4J Servlet container can revert to URL rewriting to track sessions. Since the MCS runtime also tracks the session, it is possible for more than one MCS runtime session to be bound to the same OC4J Servlet session. For example, two browser windows on the same device can open two independent MCS runtime sessions although the browsers may share the same servlet session because of the shared cookie repository.

The MCS runtime session states can be replicated to other OC4J instances in the island (An island replicates session state between two or more OC4J instances.) so that device requests can be redirected to another OC4J instance in the island when the first instance fails. By default, the binding to the OC4J Servlet session is enabled and is necessary to configure the OC4J session replication and failover. When the servlet sessions expire, the MCS runtime sessions that are bound to the servlet sessions are invalidated, provided the MCS runtime session is not bound to active sessions for other channels such as voice, instance messaging, or SMS. The invalidation of the MCS runtime session only releases the in-memory resources, but does not destroy the persistent MCS session states that can be restored when the runtime session is reactivated.

MCS runtime sessions are expired when the sessions remain idle for more than what is specified by a site-wide configuration parameter value for the Runtime Session Life Time (seconds) under System > Wireless Server: Administration > Runtime Configuration Console. The default session life time is 10 minutes. This parameter is overridden by the OC4J Servlet session expiration time, which is 30 minutes by default, when the MCS runtime session is bound to the OC4J Servlet session. The session binding from the runtime sessions to Servlet sessions can be disabled by the parameter setting enable.http.session.binding=false in the System.properties file. The MCS session persistency is enabled through the Enable Runtime Session Persistency" option under System > Wireless Server: Administration > Runtime Configuration Console. The runtime session persistency is disabled by default. The Persistent Session Life Time (days) under the same console specifies when the persistent MCS sessions are purged from persistent storage after they remain idle for the specified number of days. The MCS persistent session life time can be many orders longer than the OC4J Servlet session life time or the MCS runtime session life time; the default setting is two days.

9.4.2 Multi-Channel Gateway Usage

To use Multi-Channel Gateway, you must create and deploy your web application. You can use any web technology to develop your application. You can use either static or dynamic pages. Also, you can use either Mobile XML or XHTML markup language. The only requirement is that the application is accessible through HTTP(S) protocol. You application may or may not run on the same machine as the Multi-Channel Gateway.

For simplicity, we assume that the application is a simple JSP (Hello.jsp). The URL to access this JSP directly is: http://myhost:8080/jsp/Hello.jsp.

The Multi-Channel Gateway is another web application that can be accessed using the following URL: http://hostname:7777/mcs/remote/ (7777 is the default port for Oracle Application Server Wireless). But by accessing the Multi-Channel Gateway URL, you will not get any content because the Multi-Channel Gateway does not produce content. In order to access your own application (the content source) from your device through the Multi-Channel Gateway you must specify a special URL. To illustrate how that URL is created, consider the sample URL:

http://myhost:8080/jsp/Hello.jsp

The URL that you must enter in your device is:

http://hostname:7777/mcs/remote/http/myhost/8080/jsp/Hello.jsp

Here is how the above URL was created:

1. Get the basic Multi-Channel Gateway URL. That is, http://hostname:7777/mcs/remote/

2. Create the absolute URL (including the port number even if you use the default port number: 80 for HTTP and 443 for HTTPS) to your application.

3. Replace the:// and: in your application original URL with / (That is, change from http://myhost:8080/jsp/Hello.jsp to http/myhost/8080/jsp/Hello.jsp

4. Append the modified URL to the Multi-Channel Gateway URL.

Passing parameters to your web application is very simple. Just use the standard URL syntax and append the query string at the end of the URL.

For example: If you want to pass fname and lname parameters to your Hello.jsp then use the following syntax:

http://hostname:7777/mcs/remote/http/myhost/8080/jsp/Hello.jsp?fname=John&lname=Doe

When a request is received from the user device to the Multi-Channel Gateway, it recreates the original application URL, that is:

http://myhost:8080/jsp/Hello.jsp

and sends a request to that URL. The Multi-Channel Gateway uses the same HTTP method that the user device used to send the request (If the user device used GET, then the Multi-Channel Gateway will use GET to access the back end application. Currently only GET and POST are supported.)

9.4.3 Performance Optimization and JSP Files Modification

In general, Oracle Application Server Containers for J2EE (OC4J) examines JavaServer Pages (JSP) files to detect changes, then recompiles. However, this OC4J behavior was changed in regards to the JSP files that are deployed inside the ptg web application.

If you make changes to these included, precompiled JSP files, OC4J will not detect and compile the changes in those JSP files.

For example, all JSP files that are deployed inside the ptg web application are precompiled. If for some reason you want to modify those JSP files, then you can no longer use the precompiled class files; you must change the OC4J settings to enable JSP compilation. To do that, modify the web.xml file for the ptg application, located in:

ORACLE_HOME/OC4J_Wireless/applications/ptg/ptg-web/WEB-INF/web.xml.

In order to avoid this problem (in which modifications to JSP files do not take effect), and to optimize the performance of some of the JSP files included in Oracle Application Server Wireless, you must modify the web.xml file, as detailed below:

1. Delete the following from the file:

   <!-- WARNING!!! Overridden JSP engine settings With this configuration the JSP files in this application will NOT be recompiled. Any changes to the JSP source files will NOT take effect. If you want to switch back to the default JSP engine settings simply comment out the servlet declaration and mapping for the jsp servlet below. --><servlet><servlet-name>jsp</servlet-name><servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class><!-- you can disable page scope listener if you don't need this function. --><init-param><param-name>check_page_scope</param-name><param-value>true</param-value></init-param><!-- you can set main_mode to "justrun" to speed up JSP dispatching, if you don't need to recompile your JSP anymore. You can always switch your main_mode. Please see our doc for details --><init-param><param-name>main_mode</param-name><param-value>justrun</param-value></init-param><load-on-startup>0</load-on-startup></servlet><servlet-mapping><servlet-name>jsp</servlet-name><url-pattern>/*.jsp</url-pattern></servlet-mapping><servlet-mapping><servlet-name>jsp</servlet-name><url-pattern>/*.JSP</url-pattern></servlet-mapping><servlet-mapping><servlet-name>jsp</servlet-name><url-pattern>/*.jspx</url-pattern></servlet-mapping><servlet-mapping><servlet-name>jsp</servlet-name><url-pattern>/*.sqljsp</url-pattern></servlet-mapping><servlet-mapping><servlet-name>jsp</servlet-name><url-pattern>/*.SQLJSP</url-pattern></servlet-mapping>
   
   

2. You must also delete the ORACLE_HOME/j2ee/OC4J_Wireless/applications/ptg/ptg-web/WEB-INF/classes/_modules directory, and all class files in the ORACLE_HOME/j2ee/OC4J_Wireless/applications/ptg/ptg-web/WEB-INF/classes directory whose names start with an underscore ( _ ).

3. Restart the OC4J_Wireless application.

9.4.4 MCS Runtime API

OracleAS Wireless MCS Runtime API provides the Java interfaces to examine the runtime execution states, trace the runtime execution flow, and augment the default execution semantics. The Runtime API consists of the following Java packages:

• oracle.panama.rt provides the interfaces to the essential runtime objects for state management.

• oracle.panama.rt.event provides the interfaces to monitor the runtime execution sequence based on the Java event model.

• oracle.panama.rt.hook provides the interfaces for the essential runtime customizable components and the default implementation policies for these interfaces.

These packages are included in the wireless.jar file. Make sure you have included wireless.jar in your Java classpath when you compile your Java application or plug-in components that depend on the MCS Runtime API.

package oracle.panama.rt.event; 
 
import oracle.panama.rt.Request; 
import oracle.panama.rt.Response; 
import oracle.panama.rt.Session; 
import oracle.panama.rt.AttributeCategory; 
import oracle.panama.rt.event.RequestEvent; 
import oracle.panama.rt.event.ResponseEvent; 
import oracle.panama.rt.event.SessionEvent; 
import oracle.panama.rt.event.RequestListener; 
import oracle.panama.rt.event.ResponseListener; 
import oracle.panama.rt.event.SessionListener; 
import oracle.panama.rt.event.AbortServiceException; 
 
public class Listener implements RequestListener, ResponseListener, SessionListener { 
 
      private final static String BEFORE_REQUEST    = "L__L1"; 
      private final static String REQUEST_BEGIN     = "L__L2"; 
      private final static String SERVICE_BEGIN     = "L__L3"; 
      private final static String SERVICE_END       = "L__L4"; 
      private final static String TRANSFORM_BEGIN   = "L__L5"; 
      private final static String TRANSFORM_END     = "L__L6"; 
      private final static String REQUEST_END       = "L__L7"; 
      private final static String AFTER_REQUEST     = "L__L8"; 
      private final static String BEFORE_SESSION    = "L__L9"; 
      private final static String SESSION_BEGIN     = "L__LA"; 
      private final static String SESSION_END       = "L__LB"; 
      private final static String AFTER_SESSION     = "L__LC"; 
 
      public void beforeSession(SessionEvent event) throws AbortServiceException { 
            System.out.println(event.toString()); 
      } 
 
      public void sessionBegin(SessionEvent event) throws AbortServiceException {      //[29]
         StringBuffer buf = new StringBuffer(1000000); 
         event.getSession().setAttribute(AttributeCategory.RUNTIME, this.SESSION_BEGIN, buf);
      } 
 
      public void beforeRequest(RequestEvent event) throws AbortServiceException { 
            event.put(BEFORE_REQUEST, new Long(event.getTimeStamp())); 
      } 
 
      public void requestBegin(RequestEvent event) throws AbortServiceException { 
            event.put(REQUEST_BEGIN, new Long(event.getTimeStamp())); 
      } 
 
      public void serviceBegin(RequestEvent event) throws AbortServiceException { 
            event.put(SERVICE_BEGIN, new Long(event.getTimeStamp())); 
      } 
 
      public void serviceEnd(RequestEvent event) throws AbortServiceException { 
            event.put(SERVICE_END, new Long(event.getTimeStamp())); 
      } 
 
      public void transformBegin(RequestEvent event) throws AbortServiceException { 
            event.put(TRANSFORM_BEGIN, new Long(event.getTimeStamp())); 
      } 
 
      public void transformEnd(RequestEvent event) throws AbortServiceException { 
            event.put(TRANSFORM_END, new Long(event.getTimeStamp())); 
      } 
 
      public void requestEnd(RequestEvent event) throws AbortServiceException { 
            event.put(REQUEST_END, new Long(event.getTimeStamp())); 
      } 
 
       public void afterRequest(RequestEvent event) throws AbortServiceException {     //[54]
             Long val; 
             long t1, t2, t3, t4, t5, t6; 
 
           StringBuffer buf = (StringBuffer) event.getRequest().getSession().getAttribute(
            AttributeCategory.RUNTIME, this.SESSION_BEGIN); 
 
              /* compute total response time */ 
              t6 = event.getTimeStamp(); 
              val = (Long) event.get(this.BEFORE_REQUEST); 
              t1 = val.longValue(); 
              buf.append("Request time = "); 
              buf.append(t6 - t1); 
              buf.append("\r\n"); 
  
              /* compute service time */ 
              val = (Long) event.get(this.SERVICE_END); 
              t3 = val.longValue(); 
              val = (Long) event.get(this.SERVICE_BEGIN); 
              t2 = val.longValue(); 
              buf.append("Service time = "); 
              buf.append(t3 - t2); 
              buf.append("\r\n"); 
  
              /* compute transform time */ 
              val = (Long) event.get(this.TRANSFORM_END); 
              t5 = val.longValue(); 
              val = (Long) event.get(this.TRANSFORM_BEGIN); 
              t4 = val.longValue(); 
              buf.append("Transform time = "); 
              buf.append(t5 - t4); 
              buf.append("\r\n"); 
      } 
 
       public void sessionEnd(SessionEvent event) throws AbortServiceException {     // [84]
             StringBuffer buf = (StringBuffer) event.getSession().getAttribute( AttributeCategory.RUNTIME, this.SESSION_BEGIN); 
             System.out.println(buf.toString()); 
             System.out.println(event.toString()); 
      } 
 
      public void afterSession(SessionEvent event) throws AbortServiceException { 
             System.out.println (event.toString()); 
      } 
 
      public void requestError(RequestEvent event) throws AbortServiceException { 
             System.out.println(event.toString()); 
      } 
 
      public void responseError(ResponseEvent event) throws AbortServiceException { 
            System.out.println(event.toString()); 
      } 
 
} 

9.4.5 MCS Reverse Proxy, URL Rewrite, Caching, and Compression

The MCS runtime parses the documents and rewrites the URLs in the response documents before transforming and delivering the documents to the devices. The MCS replaces all URLs in the response document, including the channel protocol, target host names, and port numbers, so that the MCS can intercept all subsequent requests that follow from the links in the document. In this way, the MCS acts as a reverse proxy server to the devices.

The MCS runtime caches each of the original URLs in the MCS session and replaces the URL with a much shorter URL consisting only the PAsid and PAckey parameters. The PAsid parameter specifies the MCS runtime session id. The PAckey parameter specifies the key to look up the URL in the MCS session. The MCS session id, the URL caches, cache keys, and cookies are part of the persistent states of the MCS session. The MCS runtime amends the requests that it intercepts with the parameters from the original URLs in the MCS session caches.

Acting as a virtual browser in the reverse proxy, the MCS generates the HTTP requests to the target host and port number that are accompanied by the cookies from the MCS session caches. The MCS URL cache-and-rewrite scheme affords a high compression ratio if the URLs contain many hidden fields.

9.4.6 MCS Virtual Browser Model

The MCS, acting as a reverse proxy server, rewrites all URLs including the channel protocol, target host, port number, and the form or query parameters so that it can proxy all requests from the devices. The MCS can thus translate the multi-channel proxy requests to the HTTP content provider requests. When generating the HTTP requests to the content providers, the MCS acts as a virtual browser to the content provider, thereby presenting a generic user agent type. The content providers need to write the application only for the generic user agent type of the MCS virtual browser. This simplifies the multi-channel application delivery model and at the same time provides a powerful development model based on industry-standard markup languages such as XHTML, XForms, and CSS.

Acting as a virtual browser, the MCS can follow the URL redirects from the content provider applications. MCS also supports HTTP Header Referrer for external applications to trace the context of the requests. MCS can use both HTTP and HTTPS protocols and support session cookies as well as other persistent cookies, which can be part of the persistent MCS sessions. The MCS chooses to use the GET or POST methods depending on the methods the devices use to access MCS runtime. Only when the device does not use HTTP channel does the MCS runtime default to the GET method.

The MCS runtime can detect the redirect response codes, such as the HTTP response code 301 to 305, and follow the redirected URLs specified by HTTP Location header. The MCS can also support post-based redirects. To send a post-based redirect, the content provider should send HTTP header x-oracle-mobile-redirect with value true, and the OracleAS Wireless XML form as shown in Example 9-9 as the response content. The line [3] sends a Post redirect to the URL http://OracleAS Wireless.oracle.com. The param1=value1 is passed as post data to the URL.

<%
response.setHeader("x-oracle-mobile-redirect", "true");
response.setHeader("Content-Type", "tex/vnd.oracle.OracleAS Wireless XML");  // [3]
%>
<?xml version = "1.0" encoding = "UTF-8" standalone="yes" ?>
<!DOCTYPE SimpleResult PUBLIC "-//ORACLE//DTD SimpleResult 1.1.0//EN" 
"http://xmlns.oracle.com/ias/dtds/SimpleResult_1_1_0.dtd">
<SimpleResult>
   <SimpleContainer>
      <SimpleForm name="ProcessSignOnForm" mimetype="text/vnd.oracle.OracleAS Wireless XML" 
target="http://OracleAS Wireless.oracle.com/MyApp" method="post">
         <SimpleFormItem name="param1" value="value1" type="hidden"/>
      </SimpleForm>
   </SimpleContainer>
</SimpleResult>

The MCS sends the referring URLs in the HTTP Header Referrer. This mechanism is used by content providers to trace the context of the current request. The Referrer header is not sent by default but the OracleAS Wireless XML attribute sendreferer described in Example 9-10 is used to indicate that the Referrer header should be sent.

<?xml version="1.0" encoding="UTF-8"?>
<SimpleResult>
    <SimpleContainer>
        <SimpleHref target="HelloWorld.xml" sendreferer="true">Send Referer</SimpleHref>
         <SimpleHref target="HelloWorld.xml" sendreferer="false">Don't Send Referer </SimpleHref>
    </SimpleContainer>
</SimpleResult>

The MCS can access HTTPS protocol based URLs. Before using HTTPS, the client certificates should be configured using the Site Configuration Tool. The MCS can access external URLs through a HTTP proxy server. The proxy settings can be specified using the Site Configuration Tool.

The MCS runtime implements the version 0 of the Cookie Specification by Netscape (http://www.netscape.com/newsref/std/cookie_spec.html). It stores the Cookies sent by the external URLs in the MCS runtime session and sends the relevant cookies from the session with the HTTP URL request to content providers. The cookies are valid as long as the MCS sessions are valid. The persistent MCS sessions must be enabled to support persistent cookies.

The MCS performs the content adaptation, and adapts web content written in standard XHTML, XForms, and CSS markups languages to the device-specific markup languages. The MCS uses a sophisticated algorithm to determine the device and network capability by looking at the User-Agent, Accept, HTTP headers attributes, and the optional device identifications and physical device models specified by the user when they register their devices. The MCS also examines the device capabilities that some of the newer devices submit with the request. It uses a repertoire of device models in the device knowledge base to render the optimal content adaptation.

9.4.7 Wireless and Voice Portal

OracleAS Wireless also includes the facilities (such as User and Device Provisioning, User Management, Content and Service Management, Single-Sign-On Authentication, Authorization, Device Registration, User Preferences Management, End-User Personalized Portals, Billing Systems Integration, etc.), that are necessary components to build a self-contained Portal. The Wireless and Voice Portal shares the User Repositories, Oracle Internet Directory, and Single-Sign-On credentials with the Oracle Application Server Portal Product and can interoperate with the main Portal. In the Wireless and Voice Portal Runtime, every request from the device is serviced within the context of a valid runtime session. The requests from anonymous devices are also tracked and assigned to individual runtime sessions although the owners of the sessions may be the Guest user, which is an anonymous user.

9.4.8 Globalization (NLS) Support

The Multi-Channel Server is a middle-tier server that is deployed between the device browser and the back-end web application. It communicates to the device and to the application through the HTTP(S) protocol.

In order to correctly do the character encoding/decoding for the requests/responses. the Multi-Channel Server must know the character encoding that both sides—device and application—use. These are the assumptions that the Multi-Channel Server makes when handling character encoding for each HTTP hop:

1. First Request from the Device—MCS uses the Accepted Character Encodings attribute of the device browser to decode the request parameters sent by the browser.

2. First Request from MCS to the Application—MCS does not know the character encoding that the Application expects. In this case, MCS UTF-8 character encoding for the very first request to the Application.

3. First Response from the Application—MCS follows the Hypertext Transfer Protocol—HTTP/1.1 specification to detect the media type of the entity-body sent to the recipient. According to that specification, the sender should include Content-Type HTTP header and add a charset value indicating the content character set. For example:

   Content-Type: application/vnd.oracle.xhtml+xforms; charset=ISO-8859-4
   

   If the Content-Type header or the charset value are missing, then the MCS assumes ISO-8859-1 character encoding.

   
   

   Note: MCS remembers this character encoding value and will use it in subsequent requests to the Application.

   
   

4. First Response from MCS—The MCS uses the Accepted Character Encodings attribute of the device browser to decode the request parameters sent by the browser.

5. Subsequent Request from the Device—The MCS uses the Accepted Character Encodings attribute of the device browser to decode the request parameters sent by the browser.

6. Subsequent Request from MCS to the Application—The MCS uses the same character encoding sent by the Application in the previous response.

7. Subsequent Response from the Application—The MCS uses the same logic as explained in step 3. The Application must specify the character encoding again. The Application can use a different encoding (though this is not common).

8. Subsequent Response from MCS—The MCS uses the Accepted Character Encodings attribute of the device browser to decode the request parameters sent by the browser.

Steps 5-8 repeat for all requests/responses after the first request/response.

In short, MCS always uses the Accepted Character Encodings device attribute to do the character encoding/decoding when communicating with a device. It always uses the charset value in the Content-Type HTTP header when communicating with the application. An exception from this rule is only the very first request from the MCS to the application when the MCS uses UTF-8 character encoding.

9.5.1 Overview of OracleAS Wireless Services

Services enable end users to access the functionality of OracleAS Wireless. They represent a link between the content source and the delivery target. Services tie a specific data source (through an adapter) to the different devices.

There are different types of services:

• MasterService—provides the actual implementation of the service. MasterServices specify the adapter used for the service and any service-specific parameters.

• Link—a pointer to a service. In most cases Links are used to publish MasterServices to end users and to customize the MasterService parameters.

• Module--a pointer to a MasterService with a known URL.

• Folder--container for other services, including other Folders. Used to build service trees.

• ExternalLink--a service that points to an external resource.

9.5.2 MasterService

MasterServices provide the basic wireless functionality. They are the actual implementation of the service. Each MasterService is based on one adapter. A MasterService sets values for the adapter init, input and output parameters. Each MasterService creates its own instance of the adapter it uses. Therefore, several services can use the same type of adapter, and each can pass its own service-specific argument values.

It is recommended that you build all MasterServices using the HTTPAdapter. That gives you the flexibility to implement the service business logic using JSPs or other web technologies.

9.5.3 Access Control

There are two type of services in terms of access:

• User Private Services—accessible by a single user.

• Shared Services—accessible by multiple users.

There are different rules that apply to those two type of services.

• The user private services are services that reside in the user home service tree. Users can access all of those services. No other user can access those services.

• Shared services, in contrast, are accessed by multiple users. The access is controlled by the User - Group - Service relationship. When you assign a service to a group, all users from that group can access the service.

9.5.4 Folder Renderer

This section describes folder renderer.

9.5.5 Bookmark

OracleAS Wireless Server can be used to manage user bookmarks on the server side. Each bookmark refers to a Data Source (URL) whose returned content can be in any device-specific markup language. In OracleAS Wireless Server, users and administrators can place bookmarks anywhere in the user service tree.

Each Bookmark is a logical entry and can contain multiple URLs corresponding to different markup languages. For example, a Yahoo bookmark can contain a URL http://www.yahoo.com for HTML markup language and URL http://wap.yahoo.com for WML markup language. If a user accesses the Yahoo bookmark from a device supporting WML markup language, then the content from the http://wap.yahoo.com URL is returned to the device. If the Yahoo bookmark is accessed from a device supporting HTML language then the content from the http://www.yahoo.com URL is returned.

Each markup language can be uniquely identified by its MIME-type. Internally OracleAS Wireless Server stores bookmarks <URL, markup language> combinations as <URL, MIME-type> combinations.

Bookmarks are integrated with the wireless transcoding API that allows WML content (text/vnd.wap.wml MIME-type) to be converted to OracleAS Wireless XML, and then converted to any device-specific markup language supported by the OracleAS Wireless Server.

Depending on the MIME-type associated with the URL, some URLs are accessed directly from the user's device and some URLs are accessed through OracleAS Wireless. Currently only URLs associated with the text/vnd.wap.wml MIME type are accessed through OracleAS Wireless Server. This list will be extended when the transcoding API supports more input markup languages.

Additionally, any URL of a bookmark can be marked as a default URL. If a device accesses a bookmark which does not have a URL corresponding to the markup language supported by the device, then OracleAS Wireless Server invokes the default URL, transcodes the content to OracleAS Wireless XML, which is again transformed to the markup language supported by the device.

The markup language of the content returned by the default URL must be supported by the wireless transcoding API (that is, only WML text/vnd.wap.wml MIME-type content can be used in the default URL).

There are several ways to access a URL stored in a bookmark, depending on the user device and the MIME-types that are supported by that Bookmark (that is, the MIME-types for which there are associated URLs):

• The user's device supports WML content type and there is a URL associated with text/vnd.wap.wml MIME type. In this case the user's device accesses the URL through the OracleAS Wireless Server. The WML content is not modified, except that all relative URLs are rewritten to point back to the OracleAS Wireless Server. All subsequent requests go through OracleAS Wireless Server.

• The user's device supports a markup language other than WML and there is a corresponding URL for that MIME type in the bookmark. In this case, the URL is accessed directly from the user's device without coming to OracleAS Wireless Server (that is, the user leaves the wireless portal).

• The user's device supports a markup language other than WML, there is no URL in the Bookmark associated with that markup language, but there is a default URL (with text/vnd.wap.wml MIME type). In this case the user's device sends a request to OracleAS Wireless Server. The server fetches the WML content, transcodes the WML to OracleAS Wireless XML, and then converts the OracleAS Wireless XML to the device-specific markup language and sends the response back to the device. This is repeated for all subsequent requests.

• The user's device supports a markup language for which there is no corresponding URL in the bookmark and there is no default URL. In this case the default FolderRenderer will not display a link for invoking that bookmark and the user will not see it.

9.5.6 Model API: General Usage

OracleAS Wireless Repository comprises the models for the Model-View-Control (MVC) architecture, while the OracleAS Wireless Runtime layer comprises the controllers for the MVC. The repository Model API in oracle.panama.model package lets you develop applications that create, delete, modify, and query the persistent objects in the OracleAS Wireless Repository.

OracleAS Wireless Repository imposes the organizational structure among the objects. For example, a user can belong to multiple Groups. Each user is assigned one or more Roles. A user can access the services that are accessible to the groups to which the user belongs. However, the implementations of the user interface can access external provisioning systems or repositories, such as the Oracle Internet Directory (OID) and the Oracle Applications User Repository (AOL), to manage the information for enterprise users and specify the user's roles, the user's group membership, and the particular services that are accessible to that user.

A Folder is a special kind of Service used as a container of the services to build the service trees. A Service or Folder can be assigned to one or more groups. A user can own a collection of DeviceAddresses, a collection of LocationMarks, a collection of Customization Profiles, and one or more collections of Presets which are used in advanced customization. A default LocationMark and a default Profile can be assigned for each user. The Device interface in the Model API defines the target device protocol (such as: WAP, SMS, or E-MAIL), as well as specifies the physical characteristics of target devices that can be used by the adapters and the transformers (for example, screen width and height, screen columns and rows, and number of softkeys).

The intended users of the Model API are developers of customization portals, portlets, custom hooks, listeners, and applications such as JSPs, servlets, modules, and other (URL addressable) resources that are invoked through the HTTP Adapter. Developers can also develop standalone applications which manipulate persistent objects using the Model API. Although these interfaces preserve the data integrity in the repository, they do not enforce access control security. The applications that access the repository through the Model API are not authenticated or authorized by the same Authentication and Authorization mechanisms in the OracleAS Wireless runtime layer. In fact, the Model APIs are used by trusted components to develop and customize authentication and authorization policies. OracleAS Wireless Tools provide authentication and authorized access control to the repository. Developers should apply extreme caution when developing services using the interfaces in the Model API, and should take appropriate measures to prevent any undesired side-effects when these services are invoked by the end users.

Use MetaLocator to get the ModelFactory and ModelServices (line [1]). 
Use ModelFactory to create a new object.
Use ModelServices to search for an object. 
MetaLocator metaLocator = MetaLocator.getInstance(); 
modelFactory = metaLocator.getModelFactory();
modelServices = metaLocator.getModelServices();

modelServices.lookupUser(userName); 

{
     user = modelFactory.createUser(userName, groups); 
} else {
     user = modelFactory.createUser(userName);
}
user.setPassword(userPassword);
user.setEnabled(true); 

modelFactory.save();

import Java.util.Vector;
 
import oracle.panama.PanamaException;
import oracle.panama.PanamaRuntimeException;
 
import oracle.panama.model.MetaLocator;
import oracle.panama.model.ModelFactory;
import oracle.panama.model.ModelServices;
import oracle.panama.model.ResultSetEnumeration;
import oracle.panama.model.User;
import oracle.panama.model.Group;
 
 
/**
 * This is a sample program demonstrates the usage of the model API.
 */
public class SampleModelClient {
 
    private ModelFactory modelFactory;
    private ModelServices modelServices;
    
    public SampleModelClient() {
        MetaLocator metaLocator = MetaLocator.getInstance();       [1]
        modelFactory = metaLocator.getModelFactory();
        modelServices = metaLocator.getModelServices();
    }
	
    /**
     * Get all group names
     */
    private String[] getGroupNames() throws PanamaException, PanamaRuntimeException {
        String[] names;
        ResultSetEnumeration result = null;
        try {
            // Find all user groups - use a wildcard for the name expression
            result = modelServices.findGroups("*");
            Vector buffer = new Vector();
            while (result.hasMoreElements()) {
                Group group = (Group)result.next();
                String name = group.getName();
                buffer.addElement(name);
            }
            names = new String[buffer.size()];
            buffer.copyInto(names);
        } catch (PanamaRuntimeException ex) {
            throw ex;
        } finally {
            if (result != null) {
                result.close();
                result = null;
            }
        }
        return names;
    }
 
    /**
     * Create a new user.
     */
    private void createUser(String userName, String userPassword, String groupName)    [2]
                           throws PanamaException, PanamaRuntimeException {
        try {
            // First check if the user does not already exists
            modelServices.lookupUser(userName);                    [3]
            // If we are here the user must already exists
            return;
        } catch (PanamaRuntimeException ignore) {}
        Group group = null;
        try {
            // Get the group to add the user
            group = modelServices.lookupGroup(groupName);          [4]
        } catch (PanamaRuntimeException ex) {
            // A PanamaRuntimeException is thrown if the group is not found
            group = null;
        }
        User user;
        // modelFactory.createUser() will automatically create a
        // home folder for the new user.
        if (group != null) {
            Group[] groups = new Group[1];
            groups[0] = group;
            user = modelFactory.createUser(userName, groups);      [5]
        } else {
            user = modelFactory.createUser(userName);
        }
        user.setPassword(userPassword);
        user.setEnabled(true);                                     [6]
 
        // save the newly created object
        modelFactory.save();                                       [7]
    }
 
    /**
     * Search for users.
     */
    private User[] searchUser(String userNamePattern)              [8]
                              throws PanamaException, PanamaRuntimeException {
        User[] users;
        ResultSetEnumeration result = null;                        [9]
        try {
            result = modelServices.findUsers(userNamePattern);     [10]
            Vector buffer = new Vector();
            while (result.hasMoreElements()) {                     [11]
                User user = (User) result.next();                  [12]
                buffer.addElement(user);
            }
            users = new User[buffer.size()];
            buffer.copyInto(users);
        } catch (PanamaRuntimeException ex) {
            throw ex;
        } finally {
            if (result != null) {
                result.close();                                    [13]
                result = null;
            }
        }
        return users;
    }
 
    /**
     * Delete a user.
     */
    private void deleteUser(String userName)                       [14]
                            throws PanamaException, PanamaRuntimeException {
        try {
            if (userName != null && userName.length() > 0) {
                User user = modelServices.lookupUser(userName);    [15]
                user.delete();                                     [16]
                
                // Save the changes
                modelFactory.save();
            }
        } catch (PanamaRuntimeException ex) {
            throw ex;
        }
    }
 
}

9.5.7 Wireless Model API Deployment and CLASSPATH

When using Wireless model APIs in an application deployed in a container other than OC4J_Wireless, this error may appear: JAVA.LANG.CLASSNOTFOUNDEXCEPTION: ORACLE.PANAMA.CORE.MODELSERVICESIMPL.

This occurs when the CLASSPATH is set incorrectly. The CLASSPATH must contain paths that enable access to the Wireless libraries.