6
Advanced User Interactions and Channel Optimization

Each section of this document presents a different topic. These sections include:

6.1 Introduction

In this chapter, we will discuss some of the advanced user interaction techniques provided by Oracle9iAS Wireless. So far, we have seen how Oracle9iAS Wireless allows users to specify a task when a user performs an action (for example, pressing a soft key on the phone or uttering a command on a voice enabled device). Advanced User Interactions provide the ability to perform many tasks in response to an action triggered by a user whenever supported by the device. And, the ability to perform tasks based on the value input by users is highly desirable.

Oracle9iAS Wireless provides an elaborate scheme to facilitate very sophisticated binding of tasks and actions. This is performed by the SimpleBind element which may appear in the context of SimpleText, SimpleForm, SimpleFormItem, SimpleFormSelect, SimpleMenu, SimpleResult or SimpleContainer.

6.2 Events and Tasks Using SimpleBind

SimpleBind lets you specify SimpleTask which is performed in response to an action specified as the child of SimpleMatch element. SimpleMatch may specify primary1, primary2 etc. keys, nospeech, noinput, or an item of SimpleMenu conditions, etc. Only one task may be specified in SimpleMatch and when this action is performed, all the tasks specified in SimpleTask are performed. SimpleTask may also perform tasks selectively by using SimpleSwitch, SimpleCase and SimpleDefault elements which are analogous to the switch and case constructs of many programming languages.

In SimpleSwitch, a value of a particular user input is compared to the values enumerated by SimpleCase elements. SimpleTask may specify to:

go to a remote location using SimpleGo
display a text item using SimpleTextItem
refresh the device screen (if supported) using SimpleRefresh
clear the specified device form fields using SimpleClear and SimpleName
allow voice users to reprompt input using SimpleReprompt
exit the application using SimpleExit
disconnect the device from connected state (such as a voice browser) using SimpleDisconnect
define back operation using SimplePrev and SimpleGo
submit a form using SimpleSubmit.

The rendering characteristics of the SimpleBind element are specified by the SimplDisplay element. SimpleDisplay supports SimpleTextItem as child elements that contain the actual render and display content. This allows you to play an audio or render the text for a MenuItem. See example SimpleBindExample.xml.

6.2.1 SimpleBind.xml

<SimpleBind deviceclass="voice microbrowser">
          <SimpleMatch>
            <SimpleFinish/>
            <SimpleGrammar>
              yes {}| correct {}| true {} | one {}
            </SimpleGrammar>
            <SimpleDTMF>1</SimpleDTMF>
          <SimpleKey type="primary"/>
          </SimpleMatch>

          <SimpleTask>
            <SimpleSubmit
              target="changepin.jsp"
              name="Submit"
              method="post">
              <SimpleName name="p_old_pin" />
              <SimpleName name="p_new_pin" />
            </SimpleSubmit>
          </SimpleTask>

          <SimpleDisplay>
            <SimpleTextItem deviceclass="voice">
              <SimpleAudio src="sayYesOrPressOne.wav">
                say yes, or press one, to submit
              </SimpleAudio>
            </SimpleTextItem>

            <SimpleTextItem deviceclass="microbrowser">
              Submit
            </SimpleTextItem>
          </SimpleDisplay>
        </SimpleBind>

Figure 6-1 Results of SimpleBind, SimpleMatch and SimpleDisplay

Text description of the illustration xml6-1.gif

6.2.2 Device Specific SimpleBind

SimpleBind is primarily useful while writing voice applications. However, an application may use SimpleBind based on a particular device by the use of the `deviceclass' attribute. This attribute can take the values `pdabrowser', `pcabrowser', `voice', `microbrowser', `micromessenger' and `messenger'.

6.3 Device Headers and Device Class

Devices are classified based on two criteria in Oracle9iAS Wireless. The classification is based on:

form factor of the device
communication channel of the device (synchronous request/response or async mode)

See the following document for more information:

http://mobile.us.oracle.com/ompm/site/internal/api/iaswheaders/dheaders.jsp

Developers may develop value added services, which make use of device specific properties. For example, Oracle9iAS Wireless does not support server side management of large response. A service may use the maximum size of response for a device to provide navigation dynamically. The following headers are supported:

X-Oracle-Device.Class: Indicates the channel mode and the form factor of a device. Each value of the Device.Class indicates a unique communication channel mode and the unique form factor. The value set for the attribute "deviceclass" is same as the header X-Oracle-Device.class. Note that device.class does not represent target device markup language.
X-Oracle-Device.Orientation: Indicates the orientation of a device. May be used by an application to change the rendering style for certain devices. Possible values are "landscape" "portrait". Default value is "portrait".
X-Oracle-Device.MaxDocSize: Approximate value of maximum number of bytes of content that can be handled by the device in question. The approximation arises due to fact that Oracle9iAS Wireless XML size may not be the same as transformed device-specific markup language. If the service returns a Oracle9iAS Wireless XML document greater than the MaxDocSize, the response for such a request is unspecified. It is not guaranteed that a document size bounded by MaxDocSize will result in the content size, which can be pushed to the device. The value of the parameter is set by the administration tool of Oracle9iAS Wireless for the deviceclass. The default value is 0.
X-Oracle.Device.Secure: Indicates if the connection between the Oracle9iAS Wireless server and the device was secure when the current request for the resource was made. Possible values are "true" or "false".

The following jsp uses a PageNavigation bean to deliver news content in multiple trips.

6.3.1 Article.jsp

<?xml version = "1.0" encoding = "UTF-8" standalone="yes" ?>
<!DOCTYPE SimpleResult PUBLIC "-//ORACLE//DTD SimpleResult 1.1//EN" 
"http://xmlns.oracle.com/ias/dtds/SimpleResult_1_1_0.dtd">
<%@ page import="oracle.wireless.xmldevguide.PageNavigation"%>
<%
boolean loopback = Boolean.valueOf(request.getParameter("loopback")).booleanValue();
int pageIndex = 0;
try {
    pageIndex = Integer.parseInt(request.getParameter("pageIndex"));
}
catch(Exception ex){}
%>
<SimpleResult>
<SimpleContainer>
    <jsp:useBean id="contentHandler" class="oracle.wireless.xmldevguide.PageNavigation" 
scope="session"/>
    <%
    if(!loopback) {
        String size = request.getHeader("X-Oracle-Device.MaxDocSize");
        if(size != null && !("0".equals(size))) {
           contentHandler.setDeckSize(Integer.parseInt(size));
        }
        pageIndex = 0;
        // get the article content from a source.
        String articleContent = "OracleMobile Online Studio is an online "+
        "developer portal for quickly building, testing and deploying "+
        "wireless applications. It lets any developer, systems integrator "+
        "or independent software vendor quickly develop a mobile application "+
        "that is immediately accessible from all devices. This unique, next "+
        "generation environment allows companies to benefit from faster time "+
        "to market, increased productivity, and a dramatically simplified "+
        "testing cycle, while providing access to the latest mobile applications "+
        "and tools. It enables you to focus on your business logic which is your "+
        "core competency, while we focus on the device complexity, our core "+
        "competency. <SimpleBreak/><SimpleBreak/>"+
        "OracleMobile Online Studio's build, test, and deploy model is new and "+
        "unique to software development. It presents a hosted approach to developing "+
        "dynamic content. You do not need to download any software or tools to start "+
        "using it. All you need to do is access the OracleMobile Online Studio, "+
        "register, and login. Once authenticated, you will have access to "+
        "reusable modules, examples, documentation, runtime information, and other "+
        "useful resources.  <SimpleBreak/><SimpleBreak/>"+
        "Now you can even use OracleMobile Online Studio to write a single application "+
        "that can be accessed via both wireless and voice interfaces. Listen to your "+
        "OracleMobile Online Studio applications by calling: "+
        "888-226-4854. <SimpleBreak/><SimpleBreak/>"+
        "Simplify the development of your OracleMobile Online Studio application "+
        "with Where2Net's daVinci Studio.";
 
         contentHandler.setContent(articleContent);
    }
    String nextURL = null;
    String previousURL = null;
    int numPages = contentHandler.getAvailablePages();
    if(numPages > 1) {
        nextURL = (pageIndex < numPages - 1) ? 
"article.jsp?loopback=true&amp;pageIndex="+(pageIndex + 1) : null;
        previousURL = (pageIndex > 0) ? "article.jsp?loopback=true&amp;pageIndex="+ 
(pageIndex - 1) : null;
    }
    String articleTitle = (pageIndex == 0) ? "OracleMobile online studio" : "contd...";
    %>
    <SimpleText>
     <SimpleTitle><%=articleTitle%></SimpleTitle>
    <%
        String s = (nextURL == null) ? "articleIndex.jsp" : nextURL;
        if(pageIndex != numPages - 1) {
            %>
            <SimpleAction type="primary2" label="Close" target="articleIndex.jsp"/>
            <SimpleAction type="primary1" label="Next" target="<%=s%>"/>
            <%
        }
        else {
            %>
            <SimpleAction type="primary1" label="Close" target="<%=s%>"/>
            <%
        }
        %>
        <SimpleTextItem><%=contentHandler.getPage(pageIndex)%></SimpleTextItem>
        <%
        if(previousURL != null) {
            %>
            <SimpleTextItem><SimpleHref 
target="<%=previousURL%>">Previous</SimpleHref></SimpleTextItem>
            <%
            }
            if(nextURL != null){
                %>
                <SimpleTextItem><SimpleHref 
target="<%=nextURL%>">Next</SimpleHref></SimpleTextItem>
                <%
            }
            %>
    </SimpleText>
    </SimpleContainer>
 </SimpleResult>

6.3.2 PageNavigation.java

package oracle.wireless.xmldevguide;

import java.io.StringReader;
import java.io.StringWriter;
import java.io.Serializable;
import java.io.IOException;

import java.util.ArrayList;

/**
 * The bean breaks a text content into mutiple deck of a defined size. Content
 * deck do not include any formatting information of the content which should
 * be provided by the content view. 
 *
 * @author Chandra Patni
 * @version 1.0
 */
public class PageNavigation implements Serializable {

    /**
     * To keep the location of a page
     */
     private class Page {
        /**
         * starting index of the page, inclusive of start
         */
        public int start;
        /**
         * end index of the page, exclusive
         */
        public int end;
        /**
         * returns the length of the page
         */
        public int length() {
            return end - start;
        }

        /**
         * retruns the content of the page
         */
        public String toString() {
            return content.substring(start, end);
        }
     }

    /**
     * Default size of a deck in characters. The actual deck size will be 
adjusted
     * so that a word is not split. However, an orphan, end of paragraph etc
     * conditions are not checked for.
     */
    public static final int DECK_SIZE = 900;

    /**
     * size of a deck. default value is 900 chars
     */
    private int deckSize = DECK_SIZE;

    /**
     * Sets the size of one deck. Should be called before setContent()
     */
    public void setDeckSize(int value) {
        deckSize = value;
    }

    /**
     * Returns the size of one deck.
     */
    public int getDeckSize() {
        return deckSize;
    }

    /**
     * Conent to be decked
     */
    private String content;

    /**
     * Pages in the content
     */
    private Page pages[];

    /**
     * The total number of pages by the content
     */
    private int totalPages;

    /**
     * Default constructor
     */
    public PageNavigation() {
    }

    /**
     * Default constructor
     */
    public PageNavigation(String content) {
        setContent(content);
    }

    /**
     * get the page content at the given index
     */
    public String getPage(int index) {
        return pages[index].toString();
    }

    /**
     *  Returns the total number of pages
     */
    public int getAvailablePages() {
        if(pages == null) return 0;
        return pages.length;
    }

    /**
     * initializes the bean
     */
    private void init() {
        // get the rough estimate of pages
        totalPages = content.length() / deckSize + 1;
        // initialize the array
        int lastIndex = 0;
        ArrayList list = new ArrayList(totalPages);
        Page p = null;
        while((p = getNextPage(lastIndex)) != null) {
            list.add(p);
            lastIndex = p.end;
        }
        pages = (Page []) list.toArray(new Page[list.size()]);
    }

    private Page getNextPage(int lastIndex) {
        if(lastIndex >= content.length()) return null;
        char c = content.charAt(lastIndex);
        while(Character. isWhitespace(c)) {
            if(++lastIndex >= content.length()) return null;
            c = content.charAt(lastIndex);
        }
        Page p = new Page();
        p.start = lastIndex;
        // again look for whitespaces while trimming the content.
        p.end = p.start + deckSize;
        if(p.end >= content.length()) {
            p.end = content.length();
            return p;
        }
        // if not then we need to figure out the previous white space
        do {
            c = content.charAt(p.end);
            if(Character. isWhitespace(c)) {
                return p;
            }
            p.end--;
            if(p.end == 0) {
                p.end = p.start + deckSize;
                return p;
            }
        }while(true);
    }

    /**
     * sets the content to the specified value. default MIME type is text/plain
     */
    public void setContent(String s) {
        content = s;
        init();
    }
}

6 Advanced User Interactions and Channel Optimization