WAP Design Document

I. Essentials

Requirements
WAP Public Directory
WAP Administrator Directory
Tcl API
- /packages/wap/tcl/wap-procs.tcl
Data Model
- wap-create.sql

II. Introduction

The WAP package enables both the easy adaptation of existing ACS web services to a WAP-compliant format, and the building of stand-alone WAP applications on top of ACS. The WAP package enables a web application to serve both WAP and regular brower compatable pages, transitioning between the two seamlessly, alieviating developers from having to determining the requesting users type.

The WAP package, however, is not meant to take templates developed for desktop browsers and automatically generate WAP-compliant format of the same templates. Because of WAP devices' limited screen space, page flow must be designed differently, and thus different templates are called for.

III. Historical Considerations

Generate WML templates from ADP templates. To help developers port an existing web service to a WAP-compatible format, we considered automatically converting ADP templates to WML templates, by replacing HTML tags with their appropriate WML conterparts. However, since WAP devices have significantly smaller screen spaces, it does not make sense to use the same page flow and layouts of regular HTML pages. We thus opted to have developers specify a new WML template for a page to be served to a WAP device.

IV. API

User Agent Determinition: the WAP package provide tcl procedures that help developers determine the user agent type: WAP or non-WAP.
User-interface Components: currently the WAP package only has a few procedures that help developers return certain WML widgets, such as the correct header, ACS login/logout links, etc.
Data management: the WAP package provide a number of tcl wrappers for PL/SQL procedures that accomplishes legal database transactions. These transactions include the adding, modifying, and deletion of WAP user agents, toggling user agents' active status, etc.

V. Data Model Discussion

The core of the WAP data model is one table that stores user agent types:


create table wap_user_agents (
	user_agent_id		integer references acs_objects(object_id) primary key,
	name			varchar(200)
				  constraint wap_user_agent_name_nn not null,
	creation_comment        varchar(4000),
        active_p		char(1) 
				constraint wap_user_agt_act_p_chk check(active_p in('t', 'f'))
);

Recognized WAP user agents include: ALV UP/4.0.7, Alcatel-BE3/1.0 UP/4.0.6c, EricssonR320/R1A, etc. The list of valid WAP user agents is used to check against all incoming user agents to determine the request user agent type, and the type of template being returned (.adp, or .wml).

VI. User Interface

Site-wide Administrators:
The site-wide adimnistrator can manage WAP package parameters by going through the interface provided by the ACS Package Manager. Through this interface, the administrator can manage WapUAStringCompareLength and WapUADbRefresh parameters as described below in VIII. Configuration/Parameters.
WAP Administrator Directory provides administrators an interface to add, delete, and edit system-recognized WAP user agents.
Public User Directory
The public directory, /wap, allows any user to view the currently recognizable WAP user agents.

VII. Configuration/Parameters

There are two site-wide parameters that are used by the WAP package:

WapUAStringCompareLength: A number, indicates how many letters, starting from position 1, that the requesting user agent is compared to the list of know user agents to determine requesting user agent type.
WapUADbRefresh: A number, indicates how often, in seconds, cached user agent names would be refreshed from the database.

VIII. Future Improvements/Areas of Likely Change

Control WAP-accessibility by package instance. The current version of WAP does not know what package instance is WAP-enabled and what isn't. When a WAP request comes in for a non-WAP-enabled package instance, the template system will try to reply with a .wml template. When it fails to find such a template, it simply fails with a server error. In future versions, WAP package should keep track of package accesibility and return a more graceful message when a non-WAP-enabled page is being accessed by a WAP device. Vice versa, when a regular browser is trying to access a WAP-only package, a message should be returned informing the users that the package is only accessibly via WAP devices.
More WAP utility functions. ACS has a full set of utility functions that help developers to generate formatted html (i.e ad_table). We would like to develop a full set of functions to help developers to generate different wml widgets, as well. These widgets can include select lists, wml forms, etc.
All error-handling functions need to be WAP-compliant. Often times, users will be shown a page of error messages or redirected to /register/login.tcl. These messages and redirects are generated by various authentication and error-handling functions in ACS. They need to be WAP-compliant and return pages depending on the requesting user agent types.

IX. Authors

System creator: Andrew Grumet, Shan Shan Huang
System owner: Shan Shan Huang
Documentation author: Shan Shan Huang

X. Revistion History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	12/05/2000	Shan Shan Huang
0.2	Revised for new requirements	12/13/2000	Shan Shan Huang
0.3	Final revision before making an apm.	01/21/2001	Shan Shan Huang

shuang@arsdigita.com