MobileAware Interaction Server User Guide

Appendix B - MobileAware Delivery Context API

Introduction

The MobileAware Delivery Context API provides a mechanism for developers to add `device-aware' logic into their applications. The MobileAware Delivery Context API provides methods to request a delivery context and subsequently access device attributes in the retrieved delivery context.

Applications can use the MobileAware Delivery Context API to:

Retrieve a delivery context for the device currently interacting with the application by passing in the associated http request object. These are referred to In-session Queries because MIS automatically maintains a delivery context for the current device in the session.
Retrieve delivery contexts for one or more devices that match conditions passed by the application as parameters in the delivery context query. These are referred to Out-of-session Queries.

Note: The MobileAware Delivery Context API provides access to the UAProf device attributes available using the JSR 188 Delivery Context API and also provides access to the MobileAware proprietary device profile attributes that are not available using the JSR 188 Delivery Context API.

Note: The JSR 188 Delivery Context API has not yet been extended to support Out-of-session Queries.

Requesting the Delivery Context for an Active HTTP Session

The method call used to retrieve the Delivery Context for the device associated with the active HTTP Session is

DeliveryContextFactory.getDeliveryContext (request)

where request is the request object.

The following code block illustrates how this method is used to request a Delivery Context for a device associated with an active HTTP Session.

<%@ taglib uri="mmJSPtaglib" prefix="mm" %>
<mm:page content="false">

<%@ page import="com.mobileaware.deliverycontext.*" %>

<html>
<head>
<title>MA Delivery Context API</title>
<mm:structure id="st_101" where="IsMenuDriven">
   <mm:group-ref idref="gp_101" depth="flat" type="normal" display="all"/> 
</mm:structure>
</head>
<body>
<mm:group id="gp_101" title="Details">
<%
DeliveryContext dc = DeliveryContextFactory.getDeliveryContext(request);
try {
String deviceName= dc.getAttribute("DeviceName");
String imgList= dc.getAttribute("ImgTypePref");
%>
  <p>I am a <%=deviceName%>.</p>
  <p>I accept images that are: <%=imgList%></p> 
%>
} catch(Throwable e) {
  out.println("<p>Problem creating delivery context.</p>");
} 
%> 
</mm:group>
</body>
</html>
</mm:page>

The results when accessing MobileAware attributes of a WML emulator are shown below.

Figure 1 Results

Results

Image Courtesy of Openwave Systems Inc

Requesting Out-of-Session Delivery Contexts

Establishing the Delivery Context Store

A Delivery Context Store must be established before attempting to retrieve Delivery Contexts. This Delivery Context Store indicates the MobileAware Device Database instance against which the subsequent Delivery Context queries should be issue. There are two methods for establishing the Delivery Context Store depending on whether the Device Database is deployed in a relational database or as an XML file.

To establish a Delivery Context Store where the Device Database is deployed in a database, the following method is used

DeliveryContextStoreFactory.getDeliveryContextDBStore("deviceDB.url", "deviceDB.driver")
where deviceDB.url is the location of the device database (including user and password if required) and deviceDB.driver is the driver to be used to access the database. These database connection parameters should be provided by the database administrator.

To establish a Delivery Context Store where the Device Database is deployed as an XML file, the following method is used:

DeliveryContextStoreFactory.getDeliveryContextXMLStore("deviceDB.url")
where deviceDB.url is the path to the deployed device repository XML file.

Methods for Retrieving Delivery Contexts

There are four method calls that can be used to retrieve Delivery Contexts for devices in the Device Database. The methods are described below:

To retrieve a single device where a specified attribute matches a specified value:

DeliveryContextFactory.getDeliveryContext(deliveryContextStore, "attributeName", "attributeValue")
where deliveryContextStore indicates the established delivery context store to query, attributeName indicates the device store attribute to match on, and attributeValue indicates the value of the indicated device database attribute to match on. For example, to retrieve a delivery context for the Sony Ericsson P900 you could use the following:
DeliveryContext deliveryContext = DeliveryContextFactory.getDeliveryContext(deliveryContextStore, "DeviceUniqueName","root^xhtmlmp^ericsson(xhtml)^sonyericssonp900")

Note: If more than one device matches the indicated critria, the first device that matched will be returned.

To retrieve a single device matching a specified `where' expression:

DeliveryContextFactory.getDeliveryContext(deliveryContextStore, "whereExpression")
where deliveryContextStore indicates the established delivery context store to query and whereExpression indicates the where expression to evaluate and return the first matching device for. For example, an alternative way to retrieve a delivery context for the Sony Ericsson P900 would be:
DeliveryContext deliveryContext = DeliveryContextFactory.getDeliveryContext(deliveryContextStore, "DeviceUniqueName=='root^xhtmlmp^ericsson(xhtml)^sonyericssonp900'")

Note: If more than one device matches the indicated criteria, the first device that matched will be returned.

To retrieve a delivery context for ALL devices where a specified attribute matches a specified value:

DeliveryContextFactory.getDeliveryContexts(deliveryContextStore, "attributeName","attributeValue")
where deliveryContextStore indicates the established delivery context store to query, attributeName indicates the device store attribute to match on, and attributeValue indicates the value of the indicated device database attribute to match on. For example, to retrieve a delivery context for all devices profiled as PDAs you could use the following:
DeliveryContext[] deliveryContexts = DeliveryContextFactory.getDeliveryContext(deliveryContextStore, "isPDA","true")

To retrieve a delivery context for ALL devices matching a specified `where' expression:

DeliveryContextFactory.getDeliveryContexts(deliveryContextStore, "whereExpression")
where deliveryContextStore indicates the established delivery context store to query and whereExpression indicates the where expression to evaluate and return all matching devices for. For example, an alternative way to retrieve a delivery context for all PDA devices would be:
DeliveryContext[] deliveryContexts = DeliveryContextFactory.getDeliveryContext(deliveryContextStore,"IsPDA")

Once the DeliveryContextStore is no longer needed it should be destroyed to free up any resources it may be holding onto (e.g. Database connections):

deliveryContextStore.destroy();

The following code block illustrates the use of these methods to establish a Delivery Context Store and subsequently request a Delivery Context for the SonyEricsson P900.

import java.sql.*; import com.mobileaware.deliverycontext.*;

public final class DeliveryContextExternalQuery{
  public static void main(String args[]){
    DeliveryContextStore deliveryContextStore =    
    DeliveryContextStoreFactory.getDeliveryContextDBStore(
      "jdbc:mysql://test7/madb?user=root&password=",
      "org.gjt.mm.mysql.Driver");

    try{
         //Gets the matching device whose Unique Name is root^wml
         DeliveryContext deliveryContext1 = 
         DeliveryContextFactory.getDeliveryContext(
            deliveryContextStore, 
            "DeviceUniqueName", 
            "root^xhtmlmp^ericsson(xhtml)^sonyericssonp900");

          System.out.println("DeviceUniqueName: " + 
          deliveryContext1.getAttribute("DeviceUniqueName"));
          System.out.println("ImgGIFSupported: " + 
          deliveryContext1.getAttribute("ImgGIFSupported"));
          System.out.println("IsPDA: " +
          deliveryContext1.getAttribute("IsPDA"));
          System.out.println("CharsetSupported: " +
          deliveryContext1.getAttribute("UAProf.SoftwarePlatform.
          CcppAccept-Charset"));

          //Gets the first matching device that is a PDA
          DeliveryContext deliveryContext2 =
          DeliveryContextFactory.getDeliveryContext(
             deliveryContextStore, 
             "IsPDA");

          System.out.println("DeviceUniqueName: " +
          deliveryContext2.getAttribute("DeviceUniqueName"));
          System.out.println("ImgGIFSupported: " +
          deliveryContext2.getAttribute("ImgGIFSupported"));
          System.out.println("IsPDA: " +
          deliveryContext2.getAttribute("IsPDA"));
          System.out.println("CharsetSupported: " +
          deliveryContext2.getAttribute("UAProf.SoftwarePlatform.
          CcppAccept-Charset"));

          //Gets all devices that are PDAs
          DeliveryContext deliveryContexts[] =
          DeliveryContextFactory.getDeliveryContexts(
             deliveryContextStore, 
             "IsPDA");

          System.out.println("DeviceUniqueName: " +
          deliveryContexts[2].getAttribute("DeviceUniqueName"));
          System.out.println("ImgGIFSupported: " +
          deliveryContexts[2].getAttribute("ImgGIFSupported"));
          System.out.println("IsPDA: " + 
          deliveryContexts[2].getAttribute("IsPDA"));
          System.out.println("CharsetSupported: " +
          deliveryContexts[2].getAttribute("UAProf.SoftwarePlatform.
          CcppAccept-Charset"));

     }catch(AttributeValueUndefinedException e){
          System.out.println(e.getMessage());
     finally{
          deliveryContextStore.destroy();
     }

  }
}

Note: The DeliveryContextStore is responsible for caching and connection pooling and therefore is expensive to create. It is recommended that this Object be stored and reused for connection to the database for as long as possible. It is also necessary to call destroy() on this object when you are finished as it needs to free up database connections.

The following JSP example demonstrates the recommended practice of storing this within the scope of the servlet application.

DeliveryContextStore deliveryContextStore = (DeliveryContextStore)
       application.getAttribute("DeliveryContextStore");

if(deliveryContextStore==null) {
   deliveryContextStore = 
      DeliveryContextStoreFactory.getDeliveryContextDBStore(
      "jdbc:mysql://cleantest-dev/dbHEAD-G?user=root&password=", 
      "org.gjt.mm.mysql.Driver"); 

     application.setAttribute("DeliveryContextStore",deliveryContextStore);
}

Available Public Methods

There are a number of public methods that can be used to access attributes in the retrieved Delivery Context. These are described below.

Public Methods

API Call	Attribute DataType	Java Type Returned
`getIntAttribute()`	`Integer`	`int`
`getLiteralAttribute()`	`Literal`	`String`
`getbooleanAttribute()`	`Boolean`	`boolean`
`getURIAttribute()`	`URI`	`String`
`getRationalAttribute()`	`Rational`	`double`
`getDimensionAttribute()`	`Dimension`	`Dimension`
`getSequenceAttribute()`	`Sequence`	`List`
`GetBagAttribute()`	`Bag`	`Set`
`getAttribute()`	`Integer`	`String`
`getAttribute()`	`Literal`	`String`
`getAttribute()`	`Boolean`	`String`
`getAttribute()`	`URI`	`String`
`getAttribute()`	`Rational`	`String`
`getAttribute()`	`Dimension`	`String`
`getAttribute()`	`Sequence`	`String`
`getAttribute()`	`Bag`	`String`

The methods listed here have either one or two parameters: an attribute name or an attribute name and a default value to return in the event that no value is available.

Example:

GetIntAttributes( MaxWapDeckSize"); GetIntAttribute("MaxWapDeckSize", 1400);

Handling Exceptions

There are four exceptions that can be thrown when using the methods listed in the table above. It is considered good practice to place try - catch blocks around these method calls.

DeliveryContextRuntimeException

Thrown when an unexpected condition causes DeliveryContext creation or method to fail. The exception message describes the problem, such as "invalid ServletRequest Object".

InvalidAttributeTypeException

Thrown when a type-specific method is called on an attribute of the wrong type. For example, using getBooleanAttribute() to obtain a String value.

NoSuchAttributeException

Thrown when an attribute name is requested and that attribute does not exist. This is different from the attribute existing and not having a value defined for the requesting device.

AttributeValueUndefinedException

Thrown when an attribute name is requested but the attribute value does not exist.