Chapter 1 Understanding the Mobile Applications

This chapter describes the three mobile applications provided by the Sun Java™ System Portal Server Mobile Access software (formerly known as Sun™ ONE Portal Server, Mobile Access) software. This chapter contains the following sections:

Mobile Applications Overview

The goal of this chapter is to demonstrate the key functionality offered by these three applications, while simultaneously providing a developer’s perspective of control flow through the individual JSP files.



Note	Due to the large number of source files, this chapter does not attempt to provide a complete code review of every individual file. Instead, this chapter uses a tutorial-style format to bring users through each application, describing the key features of certain JSP files as they pertain to the current screen.

Each mobile application is based on JavaServer Pages™ (JSP™) technology, and can be accessed through any mobile device supporting any of a number of standard markup languages -- for example, WML and XHTML. These three applications are accessed through the mobile Portal Desktop. Users can select an application for use and return to the mobile Portal Desktop when finished.

For your reference, the complete JSP file list for each application is provided in control flow reference charts in the Portal Server Mobile Access Developer’s Reference.

Each application contains at least two full sets of JSP files: an AML-based set, and a WML-based set. Most mobile devices are supported using the AML-based JSP files. The output of the AML pages is processed by the rendering engine, which translates AML to device specific markup. Some WML devices are supported by the WML-based JSP files, whose output is returned directly to the WML device.

The JSP files involved with these three applications make extensive use of five custom tag libraries: cal, socs, ab, mail, and util. Each tag library is fully documented, with code examples, in the Portal Server Mobile Access Tag Library Reference.

Preview of the util Tag Library

Three navigational tags apply to virtually every JSP file in the three sample applications: <util:url>, <util:link>, and <util:forward>. A fourth tag, <util:include>, affects the visible content on pages.



Note	Specific resource lookup rules apply when the comp and file attributes are used in conjunction with the url, include, and forward tags. The comp and file attributes are parameters to the lookup process. See the Utility Tag Library (util) in the Portal Server Mobile Access Tag Library Reference for more information on these resource lookup rules.

<util:url>

This tag facilitates the construction of context-sensitive URL values. This tag is used in both the AML-based and WML-based versions of all three mobile applications.

In this example, the URL specifies a file named someFile.jsp, and associates the file with the mobile calendar application.



Note	This tag generates a compressed URL, which can complicate the process of looking at the generated markup to discern the target. Developers wishing to debug the application JSP pages might wish to disable URL compression in the following manner: Edit the file: /etc/opt/SUNWps/MAConfig.properties and set the ma.compressor.enable property to false.

<util:link>

This tag facilitates the construction of link-type tags (in this guide, link-type items on a mobile device’s browser are referred to as options), whose content is dynamically generated. Each tag contains a tagstart and tagend attribute for specifying what appears at the start and end of the generated option:

<util:link tagstart=”<a” tagend=”>”>

<util:attr attr=”href”>

<util:url file=”someFile.jsp” comp=”cal”>

... other parameters...

</util:url>

</util:attr>

</util:link>

<util:forward>

The comp attribute associates the named file with a particular mobile application. In the preceding case, cal is an abbreviation for “calendar”.

<util:include>

This tag performs an include operation, similar to <jsp:include>, but constructs the resource name in one of two ways: with a path attribute, or with a combination of file and comp attributes. Certain JSP files use this tag to include reusable GUI elements in their output.

For more information regarding <util:url>, <util:link>, <util:forward>, and <util:include>, consult the Portal Server Mobile Access Tag Library Reference.

The Mobile Calendar Application

The calendar application is a useful organization tool. The application allows users to add, edit, and remove events and tasks, and includes support for repeating events, email reminders, and multiple calendar servers.

To launch a calendar application, users first log into the sample portal provided with Mobile Access. The mobile Portal Desktop displays a list of numbered options to select: User Information, Bookmarks, Personal Notes, Calendar, Address Book, and Mail.

The calendar option provides users access to the calendar server. The calendar home page summarizes the events and tasks scheduled for the day. When users select the View Calendar option, the calendar application launches, and displays the day view page, where user interaction actually begins.



Note	Three different calendar servers are capable of interacting with this application: Sun Java System Calendar Server (formerly Sun™ ONE Calendar Server), Microsoft Exchange, and Lotus Notes. Three different sets of JSP pages are used to support all the features made available by these three servers. A generic set of JSP pages supports features common to all three calendar servers. In fact, the generic set covers all the Microsoft Exchange features. However, the Java System and Lotus Notes servers have unique features found respectively in the cal/sun-one, and cal/notes directories.

The Day View Page

The name of the file that displays the day view page is dayview.jsp. On a browser, this page displays the current calendar ID, the date, and a summary of any tasks or events currently scheduled. The displayed page also provides options that users can select in order to add a new event, add a new task, view other calendars, or reset the calendar to a specific date. In the source code, such options are specified as <util:link> from the util tag library, as described in <util:link>.

The calendar application allows users to add two basic kinds of scheduling objects: events, and tasks. Events and tasks are similar in that they both contain generic properties such as title, location, and details, but differ in that events specify a start and end time, whereas tasks specify a due date and indicate whether or not the task is complete.

Adding an Event

To add an event to the calendar, users select the Add event option from the day view page. The code for the day view page—which is stored as the dayview.jsp file—contains the following tag: <util:link>. This tag points to the eventSess.jsp file, which creates a new event. This new event—which at this point does not have any information entered by the user—is added to user sessions (see <util:session> in the Portal Server Mobile Access Tag Library Reference for more information about user sessions). From there, the tag <util:forward> passes control to the editEvent.jsp file and is displayed on screen as a series of individual prompts. Users are prompted for event information, such as Start (for start time), End (for end time), Title, Location, and Details. After filling in the required information, users see the following options in their browsers: Submit, Repeat, Invite, Remind, and Compose.

Submit

The Submit option submits the newly created event. When users select the Submit option, control flows to the doUpdateEvent.jsp file.This action brings up a success or failure confirmation message. Furthermore, this action brings up an option users can select to return to the day view page.

Repeat

The Repeat option allows users to specify the repeat frequency (daily, weekly, monthly, or yearly) for the event. Beyond the initial repeat frequency options, users have more specific options from which to select, as follows:

For the daily repeat frequency, users can specify that the event repeat every day, on alternate days, or on a group of days, such as Monday, Wednesday, and Friday; Tuesday and Thursday; or Saturday and Sunday.

For the weekly repeat frequency, users can specify that the event repeat every week, on alternate weeks, or once per week on a particular day.

For the monthly repeat frequency, users can specify that the event repeat every month, on alternate months, or once per month on a specified date.

For the yearly repeat frequency, users can specify that the event repeat every year, on alternate years, or once per year on a specified date.

After users select a repeat frequency and supply repeat information, they have the option of supplying one final parameter: the “Repeat until” value. As its name implies, this value sets the duration of time that the repeat should continue. The choices are to repeat until: Forever, Number of Instances, or Date.

The JSP files responsible for the repeat process begin with the prefix repeat, as in repeatFreq.jsp. The files involved are: repeatFreq.jsp, repeatInt.jsp, repeatInterval.jsp, repeatIntOK.jsp, repeatOn.jsp, repeatOnOK.jsp, repeatOnMonthly.jsp, repeatOnWeekly.jsp, repeatOnYearly.jsp, repeatUntil.jsp, repeatUntilDate.jsp, repeatUntilDateOK.jsp, repeatUntilNumber.jsp, and repeatUntilNumOK.jsp.

To see exactly which files link to which, consult the control flow reference charts for Calendar in the Portal Server Mobile Access Developer’s Reference.

Invite

The Invite option allows users to invite another person (the invitee) to the event. Selecting this option presents users with a number of methods for specifying the invitee, including: Quick Invite, Search, and Enter calID (calendar ID). When users select the Invite option, control flows from the dayview.jsp file to the rsvp.jsp file, to the doRSVP.jsp file, and then back to the eventHm.jsp file.



Note	This feature is not supported when connecting to servers other than Sun Java System Calendar Server.

Remind

The Remind option enables users to set up email reminders. When users select this option, they are prompted for additional reminder data, (with one prompt per screen), as follows: the recipient’s email address, the time (prior to the event) to send the email reminder, and a message to be included with the reminder. After users select the Remind option, control flows through the following files: remindMail.jsp, remindTime.jsp, remindInterval.jsp, remindMsg.jsp, doRemind.jsp, and then back to eventHm.jsp.



Note	This feature is not supported when connecting to servers other than Sun Java System Calendar Server.

The Compose option allows users to modify the event being created. When users select the Compose option, control flows to the editEvent.jsp file.

Adding a Task

Users can also add tasks to the calendar. The method for adding a task to the calendar is similar to the method for adding an event. From the day view page, users simply select the Add Task option and proceed to fill in the requested information, such as the task title, location, due date, due time, details, and whether or not the task is already complete. When finished, users are given the following options: Submit, Remind, and Repeat.

Control flow through the various JSP pages for adding a task is similar to the flow for adding an event. First, control passes from the dayview.jsp file to the taskSess.jsp file, which creates a new task. This new task—which at this point does not have any information entered by the user—is added to user sessions. From there, the tag <util:forward> passes control to the taskHm.jsp file, which issues the task-related options provided when adding a task: Submit, Remind, and Repeat. The Remind and Repeat options take users through the same process as described in Adding an Event. The only difference between the process of adding an event and adding a task is that the source files responsible for adding a task have the suffix “Task,” such as remindMailTask.jsp. While the source files for adding an event do not have this suffix, such as remindMail.jsp.



Note	The task location, task remind, and task repeat features are not supported when connecting to servers other than Sun Java System Calendar Server.

Going to a Different Date

Users can reset the day view page to any arbitrary date by selecting the Go To option. When users select this option, the tag <util:link> transfers control from the dayview.jsp file to the goto.jsp file, which presents users with the following Go To options: “Today”, “Next week”, “Next month”, “Previous week”, “Previous month”, or a “Specific date”. As you might expect, when users select the “Next week” and “Next month” options, the calendar rolls forward by a week or a month; the “Previous week” and “Previous month” options roll the calendar back. The Today option rolls the calendar to the current date. When users select the “Specific date” option, control transfers from the goto.jsp file to the date.jsp file. Users can then type a specific date, which rolls the calendar to that date.

When the calendar is rolled forward or backward, control passes from the dayview.jsp file to the doRoll.jsp file, and then back to the dayview.jsp file, which displays the data for the new date. For convenience, the day view page also provides links to the next six days of the calendar, each of which link to the doRoll.jsp file as well.

Viewing an Existing Event or Task

As described in The Day View Page, the day view page summarizes all events and tasks for the day. Each summary is also an option that, when selected, displays the details of the particular event or task. For the purpose of this discussion, imagine a calendar containing one event (a party at 7:00 p.m.) and one task (buying refreshments, due by 5:00 p.m.).

To view the event or task, users select the desired option, which passes control from the dayview.jsp file to the event.jsp file or the task.jsp file.

To change event details, users select the Change option, which prompts users for event details (see Adding an Event). To delete the event, users select the Delete option, which leads to the delete.jsp file, and eventually back to the the dayview.jsp file.

As with the event details, changing or deleting the task is simply a matter of following the appropriate options.

The Mobile Address Book Application

The address book is a convenient application for storing personal contacts. The address book application works in conjunction with the mobile mail application to provide an efficient mechanism for sending mail to one or more recipients.

As with the calendar application, users launch the address book application from options provided on the mobile desktop. From the mobile desktop, the address book option allows users access to the address book channel. Users launch the address book application by selecting the address book option. This action passes control to the list.jsp file, which presents the address book home page to users. The address book home page summarizes the number of contacts currently stored and allows users to interact with the application.

Adding a Contact

To add a contact to the address book, users select the “Add contact” option, which uses the <util:link> tag to transfer control from the list.jsp file to the add.jsp file. The add.jsp file uses the <util:include> tag to link to GUI code in the edit.jsp file, which presents users with a series of individual prompts describing the new contact. The prompts include: “First name”, “Last name”, Phone, and Email. Control passes from the add.jsp file to the doAdd.jsp file (which submits the contact to the address book). The <util:forward> tag automatically returns control to the list.jsp file.

Adding a Group

The address book allows users to place multiple contacts into named groups. To create a new group, users select the “Add group” option, which passes control from the current page (the list.jsp file) to the add group page (the addGroup.jsp file). The add group page prompts users for the name of the group, then passes control to the members options page (the addMembersOption.jsp file), which presents the following menu: Search, Browse, and Enter Member.

The Search option allows users to find a specific contact or group, or a list of contacts or groups, by entering search criteria and choosing the contacts or groups from the list of results. When users select this option, control passes from the addMembersOption.jsp file to the searchMemberChoices.jsp file, then to doSearchMemberChoices.jsp file, and finally to the pickMemberChoices.jsp file. The pickMemberChoices.jsp file displays the results in the form of a choice list, from which users can select the contacts or groups to be added to the group.

Browse

The browse option allows users to scroll through the complete list of stored contacts and groups, without having to explicitly perform a search. When users select this option, control passes from the addMembersOption.jsp file to the browseMemberChoices.jsp file.

After fetching all of the contacts and groups, the browseMemberChoices.jsp file forwards control to the pickMemberChoices.jsp file. Again, this file displays the results in the form of a choice list, from which users can pick and select the contacts or groups to be added to the group.

Enter Member

The Enter Member option allows users to enter a contact or group directly if the exact name is already known.

Viewing, Changing, or Deleting a Contact

To view the details for a specific contact, users select the desired name from the list of contacts presented from the list.jsp file. If the selected option points to a single contact, control passes from the list.jsp file to the view.jsp file. If the selected option is for an entire group, control passes to the viewGroup.jsp file.

After selecting a single contact, users have three options: Compose (an email to the named contact), Change (the contact details), or Delete (the selected contact). Depending on which option users select, control passes from the current page to the compose.jsp file, change.jsp file, or the delete.jsp file.

Compose

Change

The Change option allows users to change the first name, last name, phone number, and email address of the selected contact. The JSPTM page responsible for generating this page (the change.jsp file) uses the <util:include> tag to include the GUI from the edit.jsp file. Existing properties appear with their current values, which users can change or accept. Control flow passes from the change.jsp file, which collects the information, to the doChange.jsp file, which submits the changes and returns users to the address book home.

Delete

To delete a contact from the address book, users simply select the Delete option. Control passes from the current page (The view.jsp file) to the delete page (The delete.jsp file) and then back to the address book home.

Viewing, Changing, or Deleting a Group

Users view, change, or delete a group from the address book following the same procedure as described for a single contact; however, in this scenario, control passes to group-specific JSP files such as the changeGroup.jsp file, doChangeGroup.jsp file, and the deleteGroup.jsp file.

When users view a group, they see a list of the group members and they have the option of composing an email to the entire group. Users can change a group by adding or deleting group members, or by changing the name of the group. Users delete a group in the same manner that they delete a contact, as explained in Delete.

The Mobile Mail Application

The mobile mail application is an email client that works in conjunction with the address book. Like the calendar and address book applications, mail is accessed through the main menu on the mobile desktop. The mail option provides access to the mail channel, which provides an option to launch the mail application.

Control passes to the mail home page, which is presented by the summary.jsp file. This display page summarizes the messages, and provides options for managing Inbox, composing a new message, and accessing other folders. This page can also provide the option for messages to be collected from a POP server if the Collections option has been properly configured. The possible options for the email home page appear as follows:

Inbox

Inbox contains a From line at the top of the screen indicating the range of messages that are currently viewable. If Inbox contains more messages, an option labeled More appears at the bottom of the page. When users select that option, the current page is reloaded and the From line is updated to reflect the new range of messages that are then viewable. The range is updated on screen because, in the code, the start index value for the new range is set to increase by an increment of 1 over the end index value displayed in the previous range. This process loads the next set (page) of messages.

Views

Within Inbox or other mailboxes—though Inbox is the most common mailbox within which to set views—users see the messages that are visible depending upon which view, if any, Inbox is set to. If one or more views have been configured, the View option becomes available. When the View option is available, the option that by default is labeled MailHm changes to a menu option; therefore, the option no longer brings users to the mail home page, but instead offers users different view options. When users select the menu option, they see the “All messages” option and they see an option for each view that they have configured.

Views are pre-configured rules that determine which messages are visible on screen.

To Configure a View

Scroll to the Mail communication channel

Select Edit Mail (the pencil icon)

Select the “Edit your mobile mail preferences” link

Under the Mobile Mail Views heading, configure the Views using the following options:

Rules Configuration

Views Configuration

Device Views

Users first configure a rule (Rules Configuration). Then they add the rule to a view (View Configuration). Finally, they apply the view to their specific mobile devices (Device Views). Once users have finished editing the mobile mail preferences page, they return to their mobile devices, navigate to the Views option, and select the view they want. The Views option appears only if users have already configured a view.

Email Messages

Each individual email message is summarized to show the sender’s address and message subject. To view a message, users select the desired option, which passes control from the current page to the getmsg.jsp file, which fetches the message data from the server and forwards requests to the message.jsp file, which displays the subject and body of the message as well as the applicable options.

The possible options are the “List attachment(s)”, Next, and Previous options. When available, these options appear at the bottom of the message body. The Next option, Previous option, or both (Next and Previous options) appear when next and previous messages are available to view. When users select one of these options, the respective message (next or previous) is loaded. The “List attachment(s)” option appears when one or more attachments are attached to the message. When users select this option, control is passed to the attach.jsp file, and users are presented with a list of available attachments.

After users have opened a message, they have a menu of other options available to them. This menu option is linked to the menu.jsp file. When users select this menu option, the menu page appears on their browsers. This page provides users with the following options: Reply, Delete, Forward, Move To, Copy To, Add to Addr, “View header”, Mailbox.

The Reply option provides users with a dialog for replying to the sender’s message. When users select this option control passes to the reply.jsp file, which asks users if the reply should go only to the sender, or to everyone included in the original email. To answer this question, users select To Sender or To All, both of which pass control to the compose.jsp file. This action brings up the compose page on users’ browsers, where they can compose a message (see Compose).

Delete

The Delete option simply deletes the message. Control passes from the current page (the menu.jsp file) to the delete.jsp file, and then back to Inbox.

Forward

The forward option forwards the message to a specified recipient, which passes control to the pickaddr.jsp file. Users are then able to select a recipient from the list of stored contacts. Users select the recipients to include, which passes control to the compose.jsp file. If no address book channel is configured, control passes to the compose.jsp file directly. For details about the compose page, see Compose.

Move To

The Move To option moves the message to a specified folder, deleting the message from Inbox in the process. When users select this option, control passes to the getfolders.jsp file, which fetches the folder names from the server, then forwards users to the folders.jsp file, which displays the available list of folders. A New Folder option also appears, enabling users to create a new folder if desired (see Folders).

Copy To

The Copy To option behaves exactly as Move To, except that the original message is left in Inbox after the operation.

Add to Addr

The Add to Addr option adds a contact to the address book. When users select this option, control passes from the current page (the menu.jsp file), to the addpab.jsp file (short for add to personal address book), which prompts users—one screen at a time—for the following contact information: first name, last name, phone, and email address. For the email address, the sender’s address is automatically provided, but the sender’s address can be edited by users if desired. After users supply the contact information, a Mailbox option appears which returns users to the current mailbox folder, Inbox in this case.

View Header

The View header option links to the header.jsp file, and displays the following email header fields: from, date, subject, and to. This screen simply displays information. Users are not presented with additional choices.

Mailbox

The Mailbox option returns users to the currently selected mailbox. In this case, when users select this option, control returns to Inbox.

Compose

The compose page (the compose.jsp file), is where users compose a new email message. The Compose option is available in the mail home page, which is presented by the summary.jsp file:

When users select this option, control is first passed to the pickaddr.jsp file, (even when an address book communication channel has not been configured), then control is passed to the compose.jsp file. The compose page prompts users for standard email fields, such as: to, cc, subject, and message body. The interface is intuitive; users simply supply the requested fields, submit the message, and return to Inbox.

An email message composed on a mobile device can be time-consuming; therefore, users are allowed to define up to nine preset messages. These predefined replies can be selected for inclusion at the beginning of the compose screen.

To Create a Predefined Reply

Scroll to the Mail channel

Click Edit Mail (the pencil icon)

Click the “Edit your mobile mail preferences” link.

Predefined replies have a 30-character maximum.

Folders

After users click the Folders option in the mail home page— which is presented by the summary.jsp file—they are able to view or create a specific folder. When users select the Folders option, control is passed to the getfolders.jsp file, which fetches the folder names from the server and forwards requests to the folders.jsp file, which then displays the available list of folders. A New Folder option also appears, allowing users to create a new folder if needed.

When users select the New folder option, control passes from the current page (the folders.jsp file), to the newFd.jsp file, which prompts users for the name of the folder. Control then passes to the doNewFd.jsp file, which creates the new folder. Users then return to the folders page by following the Folders option that appears after the new folder has been created.

When users select an existing folder, control passes to the folderMenu.jsp file, which provides users with three options from which to select: Open, Rename, or Delete.

Open

The Open option reloads Inbox screen (passing control to the doInbox.jsp file), substituting the selected folder data for Inbox data.

Rename

The Rename option passes control to the renameFd.jsp file, which prompts users to enter a new name for the folder.

Delete

The Delete option passes control to the delFd.jsp file, which deletes the folder.

All three links eventually present users with a Folders option that returns control to the folders.jsp file.

Collections

The Collections option can be made available in the mail home page, which is presented by the summary.jsp file. The Collections option allows users to view mail on their mobile devices that was collected from a POP mail server.

To Configure a POP Mail Server for Mail Retrieval:

Scroll to the Mail channel.

Click Edit Mail (the pencil icon).

Click the “Edit your mobile mail preferences” link.

Under the Mobile Mail POP Collections heading, select Add.

Populate the fields of the POP Information box with the details for the POP server to which users want to connect.

Click Finished.

Once users have finished editing the mobile mail preferences page, they return to their mobile devices where they see the Collections option in the mail home page.

Previous Contents Index Next
Sun Java System Portal Server Mobile Access 6 2004Q2 Developer's Guide