|
| |
| Sun Java System Portal Server Mobile Access 6 2004Q2 Developer's Guide | |
Chapter 3
Using the Mobile Access Public APIsThis chapter provides information about the public APIs exposed by the Mobile Access software. The chapter 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 Javadoc for the Desktop API and the Rendered Desktop API can be found on the system where Portal Server is installed, which is at this link:
http://hostname:port/portal/javadocs/ma/index.html
In addition, the Tag Library API is described in the following section, which lists all of the publicly exposed classes that are provided in this release.
The Tag Library API
The Tag Library API provides a mechanism for tracking user state across multiple requests. This API also enables developers to change the behavior of the current tag library by creating their own custom subclasses.
The Tag Library API 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. The API contains the following classes:
Usage instructions for the preceding classes are available from the Javadoc on the system where Portal Server is installed, which is at this link:
http://hostname:port/portal/javadocs/ma/index.html
The Rendered Desktop API
The Rendered Desktop API provides classes related to the rendering and delivery of AML markup. The API contains the following classes:
As with the Desktop API, usage instructions for the Rendered Desktop API are also available on the system where Portal Server is installed, which is at this link:
http://hostname:port/portal/javadocs/ma/index.html
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, the method 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 the context with an 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 is 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 user sessions 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 user sessions. 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 might need to override the ssoTokenChanged method to provide additional behavior as necessary.
- User client types are detected and made accessible through the public String getClientType() method. Once established, user content types become accessible through the public String getContentType() method.
- User locales are determined and made accessible through the methods public Locale getLocale(), public Locale getUserLocale(), and public String getUserLocaleString().
- User time zones are retrieved and stored in the protected TimeZone time zone 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 and available on the system where Portal Server is installed, which is at this link:
http://hostname:port/portal/javadocs/ma/index.html
Understanding the ContextCache ClassThe ContextCache class, as its name implies, is a simple cache mechanism for storing multiple Context instances. This class exists for essentially one reason: to give a unique name to the cache into which a particular type of context will be stored.
The ContextCache class 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. This class 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 the context or state 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 user sessions, and your subclass will inherit this base behavior. You might 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 the direct Context subclass. 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