| Previous Contents Index Next |
| iPlanet Portal Server: Mobile Access Pack Programmer's Guide |
Appendix A API Descriptions
This appendix discusses the:
Client Data API
Use the information in this appendix to understand the default implementation of these APIs. For customizing and extending these APIs, see also Appendix B "Sample Tasks."Client Detection API
Client Help API
The Client Data stores client specific information for the Mobile Access Pack server. When a client contacts the Mobile Access Pack server, the server's Client Detection module examines the HTTP request of the client and matches it against the server's Client Data objects. Once a suitable match is found for the client's HTTP header in the Client Data, the Client Detection module returns a unique identifier (clientType) for the given HTTP header from the Client Data. This clientType value is used to retrieve specific properties about the client from the corresponding elements in the Client Data object. The clientType value is then stored in the Session Service for subsequent use by other parts of the system.
Client Data objects store various properties about the client. The Client.java API (in package com.iplanet.portalserver.client) provides common access to the Client Data stored in the profile service (refer to the javadocs for more information on the Client.java API).
The Client Java API
The Mobile Access Pack server uses the following algorithm in its client data parsing interface. It:
Gets a client instance for a specific clientType. If client instance for the specific clientType is not found, it gets a client instance for the default clientType.
In the profile server, information about each supported client is stored as values of an attribute. This attribute, iwtClient-clientTypes, contains a list of supported clientTypes. In the default installation, support for the following clients are included:
Returns an iterator of Client Data objects for all known clientTypes.
- The default clientType is stored in the iwtClient-defaultClientType attribute.
Gets the name of the clientType from the Client Data for this client instance.
Gets the Client Data value for the specified key.
Returns a set of property names for this Client Data instance.
- Null is returned if the key does not exist or if the key value is null.
Each listed clientType contains a set of properties which store information about the corresponding client. For detailed information on these properties, see "iwtClient-clientTypes".
Client Java API
public class Client {static public Client getInstance(String clientType) {
* Get a Client instance for a specific client type.
* @param clientType - The client type
* @return - The Client instance corresponding to the clientType.
* @exception - ClientException is thrown when clientType is null
or when the requested clientType does not exist.
static public Client getDefaultInstance() {
* Get a Client instance for the default client type
* @return - The Client instance corresponding to the default
static public Iterator getAllInstances() {
* @return - Iterator of Client objects for all known client types
public String getClientType() {
* Gets the name of the client type for the data in this client
* @return - Name of the client type
public String getProperty(String name) {
* Gets the client property for the specified key
* @param name - The key for the client property to be returned.
* @return - The client property.
* @exception - ClientException is thrown when the requested key
is not found or when null or empty string is passed as key.
public Set getPropertyNames() {
* @return The set of property names for this client data
public void profileChanged(ProfileEvent event) {
com.iplanet.portalserver.profile.ProfileListener#profileChanged
Sample Client Data Implementation
For a sample implementation of the Client API in a wireless provider, see "Implementing the Client Data API".
The Mobile Access Pack Client Detection module examines the HTTP header from the client's request and matches it against the server's Client Data objects. By default, the Client Detection module only considers the client's userAgent HTTP header to determine the clientType. Once a suitable match is found for the client's userAgent HTTP header in the Client Data, the Client Detection Module returns the unique identifier (clientType) for the given userAgent HTTP header from the Client Data object.
By default, client detection is achieved by the client detector object that:
Parses data from the HttpServletRequest of the requesting client
Performs a method of matching based on the stored clientTypes and their corresponding userAgents.
The Default Client Detection Interface
The Mobile Access Pack server uses the following algorithm in its client detection interface:public interface ClientDetectionInterface {
* Detects the client type based on the request
* @param request HttpServletRequest
* @return a string representing the clientType
* @exception - ClientDetectionException if there is an error
The Mobile Access Pack server uses the following algorithm to set the clientType:
public String getClientType(HttpServletRequest request) throws ClientDetectionException{
* Get userAgent from the HttpServletRequest
* Get Iterator of known clientTypes from Client
* @param request - The calling object passes in the
* If userAgent equals a known userAgent, then save the clientType
* If saved clientTypes > 1, look at length of filePath, return
clientType with longest filePath
* If clientType not found, return the default clientType
* @return - The string corresponding to the clientType
* @throws ClientDetectionException - Thrown when a default
The Mobile Access Pack server uses the following algorithm to compare the HttpServletRequest userAgent with the userAgent stored for the requesting clientType:
protected boolean userAgentCheck(String httpUA, String clientUA){
* @param httpUA - The HttpServletRequest user-agent
* @param clientUA - The Client userAgent
* @return true or false if they match
The Mobile Access Pack server Client Detector object:
Gets the userAgent from the HttpServletRequest
Calls the Client.getAllInstances() method which returns a list of supported clients.
Iterates through each client in the list and calls Client.getProperty("userAgent") which returns the stored clientType's userAgent.
- It looks for a partial match between the requestor's userAgent and the client's userAgent that is stored in a hashtable with the clientType and the size of the userAgent.
- If there are multiple matches, the clientType with the longest userAgent is returned since it assumes that the longer the userAgent is, the more precise it is. If no userAgent in the hashtable match the requesting client's userAgent, then the default clientType is returned. This is achieved through a call to the Client.getDefaultInstance().getProperty("clientType").
Developing a Customized Client Detection Module
When developing a customized client detection module, write a method that:
Takes the requesting client's HTTP header value as a string.
See also "Customizing the Client Detection Interface" for detailed instructions on creating a customized Client Detector and for modifying the default Client Detector.Matches the HTTP header value against the stored Client Data objects.
Returns the clientType value from the Client Data for the matching HTTP header value.
- The method can match the HTTP header value against any stored property of the client. When matching, take into account the environment from which the client is sending its request for an accurate match against the stored Client Data objects.
Client specific help is provided by the WirelessFrontProvider. The WirelessFrontProvider looks for the attribute iwtDesktop-clientHelpLinks attribute. If this is found, then a string is returned to the calling method. The [tag:front_help], [tag:prov_help], [tag:help_link] tag swapper tags are used within the template files to make the link visible. If no client specific help is found, then an empty string is substituted into the template.
For each provider providing help, there must be the following two template files in each supported markup language (or for each supported clientType) in the filepath:
frontProvider.template - Displays the help link. In this file, the tag [tag:front_help] is the tag that gets substituted with the help link.
That is,frontHelpLink.template - Contains the anchor tag around the URL that gets produced.
The path to the URL is retrieved from the iwtDesktop-clientHelpLinks attribute.
Each provider uses the Provider API (PAPI) interface to find which methods are called by the various desktop classes to create the desktop. The two methods, hasHelp() and getHelp(), are used by the Mobile Access Pack server to display a help link for each provider.The path is placed inside of the markup in the frontHelpLink.template file.
Then the whole string is substituted into the frontProvider.template file.
@return boolean - This method returns true or false depending on whether or not it finds <channelName>-clientHelpLinks attribute in the profile for the particular provider
@return java.net.URL - This method returns the help URL that corresponds to the requesting clientType from the <channelName>-clientHelpLinks attribute
The APIs discussed in this section can be used by a provider to:
Determine whether or not the requesting clientType is supported by the provider
Get the content for the client based on whether or not content for the client is available
Determine whether or not the channel (for the provider) is editable
Each Provider defines its own logic to determine presentability to the desktop. For example, presentability can be based on clientType, userAgent type, contentType, charsets, or whether or not a given template is found for the requesting clientType. For more information on isPresentabe, see "isPresentable() Method Added to the Provider API" section in the iPlanet Portal Server 3.0 SP3a Release Notes.
* Determines whether the provider is presentable
* Searches for the key genericHTML with the value true on the client data for the session's client type and returns true
* If there is no genericHTML key, method will return true
* If the session's client type is named genericHTML
* In both cases, the contentType for the session's client type must equal text/html in order for the method to return true
* @return boolean value dictating presentability
* @see com.iplanet.portalserver.providers.Provider#isPresentable
Sample Implementation
In the following example, presentability is based on the boolean isPresentable. The wireless provider determines presentability based on the client's charsets property.Presentability is based on the boolean isPresentable. It is defaulted to true in the provider init() method.
private String clientType = null;
private String clientCharsets = null;
private String targetCharset = "ISO-2022-JP";
private boolean isPresentable;
public void init(String n, Session s) throws ProviderException {
clientType = s.getProperty("ips.clientType");
clientObj = Client.getInstance(clientType);
clientCharsets = clientObj.getProperty("charsets");
} catch (SessionException se) {
throw new ProviderException("Unable to retrieve Session
} catch (ClientException ce) { }
// If the targetCharset is not in the clientCharsets list, then
// set Presentability to false. This means that channels based on
// this Provider will not be displayed.
if (clientCharsets.indexOf(targetCharset) == -1) {
The getContent() method can be used to determine availability of content for a client. In the following example, the provider retrieves content based on the requesting client's userAgent property. The conditional logic is hardcoded in to the Provider class.
Sample Implementation
This example includes the:Content returned is based on the value of the UserAgent and the known hard coded user agent values in the class.
private String clientType = null;
private String clientUserAgent = null;
private static final String uaUpBrowser = "UP";
private static final String uaNokiaBrowser = "Nokia7110";
private static final String uaDoCoMoBrowser = "DoCo";
public void init(String n, Session s) throws ProviderException {
clientType = s.getProperty("ips.clientType");
clientObj = Client.getInstance(clientType);
clientUserAgent = clientObj.getProperty("userAgent");
} catch (SessionException se) {
throw new ProviderException("Unable to retrieve Session
} catch (ClientException ce) { }
public StringBuffer getContent(Map m) throws ProviderException {
StringBuffer content = new StringBuffer("");
if ((clientUserAgent.equals(uaUpBrowser)) ||
(clientUserAgent.equals(uaNokiaBrowser))) {
content.append("<P>Hello<BR/> WML World<BR/></P>");
} else if (clientUserAgent.equals(uaDoCoMoBrowser)) {
content.append("<BR>Hello cHTML World<BR>");
content.append("<BR><B><I>Hello HTML World</I></B><BR>");
By default, the Mobile Access Pack providers are only editable via the genericHTML client. Each Mobile Access Pack provider overrides the isEditable() method and based on the clientType, they will return false. If the clientType is genericHTML, then it will invoke the super.isEditable() method.
Sample Implementation
public boolean isEditable() {The isGenericHTML can be retrieved via:
private String clientType = null;
private boolean isGenericHTML;
public void init(String n, Session s) throws ProviderException {
clientType = s.getProperty("ips.clientType");
clientObj = Client.getInstance(clientType);
isGenericHTML = Boolean.valueOf(clientObj.getProperty
("genericHTML")).booleanValue();
} catch (SessionException se) {
throw new ProviderException("Unable to retrieve Session
} catch (ClientException ce) { }
Previous Contents Index Next
Copyright © 2001 Sun Microsystems, Inc. All rights reserved.
Last Updated November 14, 2001