Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Portal Server Mobile Access 6 2004Q2 Developer's Guide 

Chapter 3
Using the Mobile Access Public APIs

This chapter provides information about the public APIs exposed by the Mobile Access software. The chapter contains the following sections:


This 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:


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:


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:


Understanding the Context Class

The 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 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:


Understanding the ContextCache Class

The 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 Class

The 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 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 Subclasses

This section presents guidelines that you should follow when deriving your own classes from Context or ContextCache.

Extending the Tag Library

This section provides an example of how to extend the current Tag Library by defining new Context, ContextCache, and ContextTag subclasses.

  1. Extend the Context class.
  2. public class NewCalContext extends CalContext {

      public static String CONTEXT_CLASS_NAME=


      public static final String CONTEXT_CACHE_CLASS_NAME=


      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,



  3. Optionally, extend the ContextCache class.
  4. 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 { }

  5. Write a ContextTag class that refers to the new Context subclass.

    public class NewCalContextTag extends CalContextTag {

      public NewCalContextTag()



      public Context findContext() throws Exception {

        String configNameKey = NewCalContext.CONTEXT_TYPE +


        String ssoAdapterKey = NewCalContext.CONTEXT_TYPE +


        computeConfigName(pageContext, configNameKey, ssoAdapterKey,‘


        return NewCalContext.getContext(pageContext);




    Use this new ContextTag in the tld to refer to the Tag class.





      <info> New Calendar context tag </info>







Global Namespace Request Parameters

Global 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

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.