| Sun ONE Portal Server, Mobile 6.2 Developer's Manual |
Chapter 3
Using the Mobile Access Public APIsThis chapter provides information about the public APIs exposed by the SunTM ONE Portal Server, Mobile Access 6.2 software. It contains the following sections:
OverviewThis release exposes three public APIs that you can access while developing your own mobile applications: the Tag Library API, the Desktop API, and the Rendered Desktop API. The Tag Library API, however, is the only API requiring additional explanation beyond what is already described in the SunTM ONE Portal Server, Mobile Access 6.2 Javadoc Reference. As such, it is the primary focus of this chapter.
For completeness, the following section lists all publicly exposed classes provided in this release.
The Tag Library API
The Tag Library API provides a mechanism for tracking user state across multiple requests. It also enables developers to change the behavior of the current tag library by creating their own custom subclasses.
It consists of the following base and application-specific classes:
The base classes, Context, ContextCache, and ContextTag, are the primary focus of this chapter.
The Desktop API
The Desktop API provides methods for accessing and manipulating rows and channels. It contains the following classes:
Usage instructions for the above classes are provided in the SunTM ONE Portal Server Mobile Access 6.2 Javadoc Reference.
The Rendered Desktop API
The Rendered Desktop API provides classes related to the rendering and delivery of AML markup. It contains the following classes:
As with the Desktop API, usage instructions for the Rendered Desktop API are also provided in the SunTM ONE Portal Server Mobile Access 6.2 Javadoc Reference.
Understanding the Context ClassThe Context class resides in the com.sun.portal.wireless.taglibs.base package, and defines the core state-tracking functionality that your custom subclasses will inherit.
To obtain an instance of this class, invoke its getContext method:
public static Context getContext(PageContext pageContext, String contextClassName, String contextCacheClassName, String contextType);
Like all public static methods, getContext should be invoked by class name, not by object reference. When invoked, this method will first attempt to retrieve the context from the pageContext and contextCache objects. If both attempts fail, the method will instantiate a new context, placing a copy into the cache before returning. This method is most commonly invoked by Context subclasses as part of their own getContext implementations.
When the getContext method creates a new Context object, it triggers an initialization phase that sets values for many of its properties. The process is initiated by invoking either of the following methods:
The first version initializes the context and associates it with a SunTM ONE Identity Server service. This version is typically invoked with super.init(...) from within the init(...) implementations of specific Context subclasses.
The second version simply initializes the context. This version is typically invoked by the context framework, such as Context.getContext(...), immediately after instantiating a new Context object.
Regardless of which version was invoked, the following tasks are always performed during context initialization:
- The session and ssoAdapter parameters are assigned to protected instance variables of the same name. Both objects will become directly accessible in your subclass, as well as through the public methods getSession() and getSSOAdapter().
- The ID value of the user’s session becomes accessible through the public method getSessionID(), and the configuration name of the ssoAdapter becomes available through the public method getConfigName().
- The context instance is registered as an SSOTokenListener on the user’s session. SSOTokenEvent notifications will be received by this instance through its public void ssoTokenChanged(SSOTokenEvent evt) method. All subclasses will inherit this behavior, and as such, will automatically receive SSOTokenEvent change notifications for events such as logouts and timeouts. Your subclass may need to override the ssoTokenChanged method to provide additional behavior as necessary.
- The user’s client type is detected and made accessible through the public String getClientType() method. Once established, the user’s content type becomes accessible through the public String getContentType() method.
- The user’s locale is determined and made accessible through the methods public Locale getLocale(), public Locale getUserLocale() and public String getUserLocaleString().
- The user’s time zone is retrieved and stored in the protected TimeZone timezone instance variable.
The remaining methods of this class are simple methods for reading and writing the context’s properties. For example, public Context getParentContext() and public void setParentContext(Context), which get and set the parent context. Such methods are fully documented in the SunTM ONE Portal Server Mobile Access 6.2 Javadoc Reference.
Understanding the ContextCache ClassThe ContextCache class, as its name implies, is a simple cache mechanism for storing multiple Context instances. It exists for essentially one reason: to give a unique name to the cache into which a particular type of context will be stored.
It resides in the com.sun.portal.wireless.taglibs.base package.
Typically, for every major Context subclass (for example, MailContext, CalContext, and ABContext), there exists a corresponding ContextCache subclass (for example, MailContextCache, CalContextCache, and ABContextCache).
To obtain an instance of this class, invoke the following method, passing in the name of the context to be retrieved:
public static synchronized ContextCache getInstance(String className)
To add/remove contexts to or from the cache, invoke put or get:
Understanding the ContextTag ClassThe ContextTag class resides in the same package as Context and ContextCache. It is a simple class that represents a context tag.
A context tag represents the session state for an valid authenticated connection to a backend service. This tag validates that the session is still valid and provides a context for other tags to make requests to that service. At the first request, a connection is made to the backend service using configuration and authentication information. The session service context or state is stored in the session so that it is available across requests.
A context tag does the following:
- The service context is retrieved from the session.
- If there is no context, a new service context is created and stored into the session.
- The service configuration (for example, host, port) and user authentication (for example, credentials) are used to connect to the service.
- If a valid session is created, the service context is stored into the session
The ContextTag class defines an abstract findContext method, which finds the context this tag represents:
public abstract Context findContext() throws Exception;
Subclasses must implement this method to return the appropriate context for the session. For an example of this, see "Extending the Tag Library".
Creating Custom SubclassesThis section presents guidelines that you should follow when deriving your own classes from Context or ContextCache.
- If you are creating a direct Context subclass, you should define the following String constants, since their values will be required when obtaining a context: CONTEXT_CLASS_NAME, CONTEXT_CACHE_CLASS_NAME, and CONTEXT_TYPE. The first two constants should contain the fully-qualified class names for your Context and ContextCache subclasses. The last constant declares the name of the context type appropriate to this new Context subclass.
- If you are creating a direct Context subclass, you should define a unique value for CONTEXT_TYPE that is descriptive of the type of service provided by the new context. If you are simply extending an existing major Context subclass (for example, MailContext, CalContext, or ABContext), you should just inherit the value for CONTEXT_TYPE that is defined in those subclasses.
- If you are creating a direct Context subclass, you should define a getContext method for obtaining its instances. The body of the method can simply call Context.getContext, casting the result to the current class:
- If you are extending an existing Context subclass, such as ABContext, the result can be cast to that class instead:
return (ABContext) Context.getContext(pageContext,
CONTEXT_CLASS_NAME,CONTEXT_CACHE_CLASS_NAME,CONTEXT_TYPE);
- When overriding either version of init, make sure that your subclass invokes super as its first line:
- The base Context class registers itself as a listener for changes fired from the user’s session, and your subclass will inherit this base behavior. You may want to override this method to perform additional tasks beyond what is defined in the parent implementation. Typically this will involve code for cleaning up the context when the session becomes invalid.
- If you have created a direct Context subclass, you should also create a direct ContextCache subclass that corresponds to it. For example, IMContext and IMContextCache. Using this example, the new cache class need only contain the following:
package com.whatever.im;
import com.sun.portal.wireless.taglibs.base.*;
public class IMContextCache extends ContextCache { }
- If you are extending an existing major Context subclass, you should not create a new ContextCache subclass. Instead, you should use the same ContextCache subclass that is already defined.
Extending the Tag LibraryThis section provides an example of how to extend the current Tag Library by defining new Context, ContextCache, and ContextTag subclasses.
- Extend the Context class.
public class NewCalContext extends CalContext {
public static String CONTEXT_CLASS_NAME=
"com.sun.portal.wireless.taglibs.cal.NewCalContext";
public static final String CONTEXT_CACHE_CLASS_NAME=
"com.sun.portal.wireless.taglibs.cal.NewCalContextCache";
public static final String CONTEXT_TYPE = "Calendar";
protected boolean newProp = false;
public void setNewProp(boolean newProp){
Util.logMessage("NewCalContext.setNewProp(): “ +
“Setting New to " + newProp + ", instance = " + this);
this.newProp = newProp;
}
public boolean isNewProp(){
Util.logMessage("NewCalContext.isNewProp():Retrieving New= "
+ newProp + ", instance = " + this); return newProp;
}
public static CalContext getContext(PageContext pageContext)
throws Exception {
return (NewCalContext) Context.getContext(pageContext,
CONTEXT_CLASS_NAME,CONTEXT_CACHE_CLASS_NAME,CONTEXT_TYPE);
}
- Optionally, extend the ContextCache class.
If your application does not need access to the original context object, extending the ContextCache class is not necessary.
However, if your application needs access to both the new and original context, you must create a new ContextCache subclass. You do not need to override any methods.
public class NewCalContextCache extends CalContextCache { }
- Write a ContextTag class that refers to the new Context subclass.
public class NewCalContextTag extends CalContextTag {
public NewCalContextTag()
super();
}
public Context findContext() throws Exception {
String configNameKey = NewCalContext.CONTEXT_TYPE +
"configName";
String ssoAdapterKey = NewCalContext.CONTEXT_TYPE +
"ssoAdapter";
computeConfigName(pageContext, configNameKey, ssoAdapterKey,‘
CalContext.SSO_CONFIG_TYPE);
return NewCalContext.getContext(pageContext);
}
}
Use this new ContextTag in the tld to refer to the Tag class.
Global Namespace Request ParametersGLOBAL namespace requests parameters are provided in this release for the rendered and native Portal Desktop. and for the voice Portal Desktop. This section lists them.
Rendered and Native Desktop
Voice Desktop
