Oracle9iAS Wireless Developer's Guide Release 2 (9.0.2) Part Number A90485-02 |
|
Each section of this document presents a different topic. These sections include:
Mobile Studio is an online environment for quickly building, testing and deploying wireless applications. It lets any developer quickly develop mobile applications that are immediately accessible from all devices.
As a developer, you do not need to download or install any software to start using the Studio; provides a completely web-based development and testing environment. To access Mobile Studio on your Oracle9iAS Wireless instance, go to: http://oracle9iasw-host:port/studio.
As a developer, you must register with your instance of Studio to access the Studio web site. To register, click on the register button on the Studio home page and provide the required details to register. Once you register, Studio provides you with a personal application area to test your applications and also provides links to sample applications.
In this walkthrough you will create a HelloWorld mobile application.
<?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"> <SimpleResult> <SimpleContainer> <SimpleText> <SimpleTitle>HelloWorld Page</SimpleTitle> <SimpleTextItem>Hello World</SimpleTextItem> </SimpleText> </SimpleContainer> </SimpleResult>
Name: MyHelloWorld
URL: URL to the helloworls.xml file (such as http://server:port/....)
Deviceclass: Select "all devices"
Description: My First Studio Sample
In this walkthrough you will test and debug the HelloWorld application created in the previous walkthrough.
To deploy an application you will must be part of a Domain. In this walkthrough you will create a Domain and then deploy the MyHelloWorld application to an Oracle9iAS Wireless Server.
Name: SampleDomain
Enter a password and confirm the password selection.
Set as Default should be checked.
You can also use OracleMobile's hosted Online Studio (a developer portal) to quickly and easily build, test and deploy your mobile applications.
OracleMobile's hosted Online Studio enables any developer, systems integrator or independent software vendor to quickly develop a mobile application that is immediately accessible from any device. 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.
For more information on Oracle Online Mobile Studio, and to use OracleMobileOnline Studio, see Oracle Technology Network (OTN) at: http://otn.oracle.com.
Oracle9iAS Wireless SDK is a light development version of Oracle9iAS Wireless. It is an off-line environment that enables developers to create and test MobileXML applications. With Oracle9iAS Wireless SDK, application developers can test and simulate applications without needing to support a complete Oracle9iAS Wireless installation.
The SDK can be separated into two sub-components: transcoder and messaging.
Oracle9iAS Wireless SDK transcoder can be used to test Mobile XML applications, new XSL stylesheet transformers and new device descriptions. It provides most of the functionality available in Oracle9iAS Wireless device portal.
Oracle9iAS Wireless SDK messaging API is the same as PushAPI, which delivers all kinds of messages through Push server or Push Messaging gateway. Push Messaging gateway is based on SOAP technology. Push server is build on top of Oracle9iAS Wireless. The implementation of Push Server has been simplified in Mobile SDK so that SDK does not have dependencies on SOAP or Oracle9iAS Wireless. Only a Push Server simulator is shipped with SDK, which can send out emails only. All messages with other transports will be converted to email and send to an email address called 'default email'. Therefore, a SMTP email server and a valid email address are needed.
Oracle9iAS Wireless SDK is a J2EE application. It should be deployed on Oracle9i Application Server using the OC4J deployment tool. For more details please refer to the OC4J documentation.
Oracle9iAS Wireless SDK contains the following important files and directories:
1.1 - XSL device transformers for version 1.1 of the mobile XML schema. Every .xsl file in this directory is considered a separate transformer. The name of the file is the name of the transformer (the names are case sensitive). There are two special files in this directory:
SimpleResult_1_1_0.xsd - this is the XML schema describing Mobile XML version 1.1
SimpleResult_1_1_0.dtd - this is the XML DTD describing Mobile XML version 1.1
EncodingSets.properties - mappings between IANA and Java character encoding names. Normally you should not have to modify this file.
ProxyFirewall.properties - proxy firewall settings for the SDK. By default the SDK is not configured to use a firewall. You should modify this file only if you need to access an application that is outside your firewall.
Oracle9iAS Wireless SDK transcoder is a J2EE web application. The configuration file for the application is WEB-INF/web.xml. Some of the configuration properties can be modified at run-time using the SDK administration page.
Note: The changes made from the SDK administration page do not get persisted in web.xml. You will have to modify web.xml manually if you want to use the new settings permanently. |
Here is the list of user configurable settings:
The SDK transcoder uses two properties files for additional configuration. Normally you should not need to modify those files.
Required Parameters
The SDK reads SMTP mail server and default email from the Java VM System properties. Property name for SMTP server is mobile-sdk.email.server.host and property name for default email is mobile-sdk.default_email. These two parameters are required to run SDK.
There are two ways to set those parameter:
Not Required Parameters
MessagingGatewayURL, username and password of the constructors of Push and PushLite classes are not going to be used. But, you have to pass something to construct the instance. Passing three nulls will be permissible.
Push and PushLite have the same functionality: deliver messages to Push server (Push Server simulator in SDK). But, why do we need them both?
Push takes an instance of Packet as parameter. Packet has a message object, senders, recipients and additional information, which helps to deliver the message. For example: priority, speed of delivery, delay etc.
PushLite can send out text messages only. It's very easy to use. The users don't need to know any other classes like Packet, Message, and AddressData etc.
The reason that they co-exist in the same API is because Push and PushLite give developers an opportunity to choose the API to meet their needs. If you want to send text messages fast, use PushLite. If you need more control over the message, use Push.
The source files for both classes are in the examples directory.
Oracle9iAS Wireless SDK stores the device description as XML files in its repository directory. Each XML file stores the description of one device. The XML root element is <LDEV>. All element attributes and subelements are exactly the same as in the Oracle9iAS Wireless repository XML representation (there are a few exceptions that will be explained below). The advantage of that is that you can download the Oracle9iAS Wireless repository, save all <LDEV> elements from the repository XML file as separate files, copy them into the SDK repository directory (or modify web.xml file), and the SDK will use exactly the same device descriptions as your real server. Or, you can add a new device description to the SDK repository, fully test it, and then deploy it on your real Oracle9iAS Wireless server. In order to upload a new device to the real Oracle9iAS Wireless server you will need to create a new XML file with the following format:
<?xml version = '1.0' encoding = 'UTF-8'?> <PanamaObjects> <LDEV_LIST> <LDEV ...> The new device description goes here </LDEV> </LDEV_LIST> </PanamaObjects>
Where the <LDEV> element is the one stored in the XML file in the SDK repository directory.
Here is the complete list of attributes and subelements that comprises the LDEV element. Please keep in mind that all String values are case sensitive.
name - a String - the name of the device. The value of this attribute must be the same as the name of the XML file (without the .xml extension) in which the device description is stored. The value must be unique.
mimeType - a String - the MIME type that the device expects, for example: "text/vnd.wap.wml" or "text/html"
encoding - a String - the content encoding. The IANA character set names are published at:
http://www.iana.org/assignments/character-sets
The "mimeType" and the "encoding" attributes are used to create the Content-Type HTTP header that is sent back to the end user device. For more details please see the HTTP 1.1 specification at:
http://www.rfc.net/rfc2616.html
Content-Type: text/vnd.wap.wml; charset=ISO-8859-1
deviceCategory - a String - the device category. Oracle9iAS Wireless groups all devices in the following six categories:
See Chapter 10, "Core Technologies" for more details of the different device classes.
manufacturer - a String - the company name. For example: Nokia, Ericsson, Palm, Motorola, etc.
model - a String - the device model.
softKeys - an Integer - the number of soft keys that the device has.
screenCols - an Integer - the number of characters (per row) that the device can display.
screenRows - an Integer - the number of rows text data that the device can display.
screenWidth - an Integer - the screen width in pixels.
screenHeight - an Integer - the screen height in pixels.
imageCapable - a Boolean - whether the device supports images or not.
colorCapable - a Boolean - whether the device supports colors or not.
bitsPerPixel - an Integer - the number of bits per pixel used to represent either the color or the gray scale.
videoCapable - a Boolean - whether the device supports streaming video or not.
voiceCapable - a Boolean - whether the device supports voice or not.
system - a Boolean - whether this is a "system" device or not.
maxDocSize - size of document (in bytes) that a device can accept.
supportsAmpersandEntity - ampersand character can be used in XML-friendly devices.
supportsRelativeURL - a Boolean - whether the device supports relative URLs or not. In general all browsers should resolve relative URLs but of them do not do it.
prolog - xml prolog at the start of the content sent to a device. Specifies content type.
description - a String - a short description of the device.
needsURLCaching - a Boolean - whether the URLs for this device should be cached or not.
Note: This attribute has been deprecated. Both, the Oracle9iAS Wireless SDK and the Oracle9iAS Wireless server will always cache the URLs for all devices. |
supportsCookie - a Boolean - whether the device supports "cookies" or not.
defaultTransformer - a String - the name of the XSL transformer to be used for this device.
To deploy an application you will must be part of a Domain. In this walkthrough you will create a Domain and then deploy the MyHelloWorld application to an Oracle9iAS Wireless Server.
Name: SampleDomain
Enter a password and confirm the password selection.
Set as Default should be checked.
Oracle9iAS Wireless SDK uses the same device detection mechanism as Oracle9iAS Wireless server. See Chapter 10, "Core Technologies" for more details.
Oracle9iAS Wireless SDK comes with a default demo wireless application. This application is a single JSP page: Home.jsp. This JSP page looks in the apps directory to find user-specific applications. A user application can be a .jsp, .xml or .mxml file. The main wireless application displays a link to every one of the files it finds in the apps directory. If you want to test your application, copy its main page into the apps directory. If your application contains more than one file, then only the first page must be copied into the apps directory. All other pages should be in a separate directory (it could be a subdirectory of the apps directory). See the sample applications for more details.
JDeveloper provides a mechanism to develop, debug and test Oracle9iAS Wireless XML JSPs and XML pages in a single tool by providing an Oracle9iAS Wireless addin for JDeveloper. Developers can create JSP pages with embedded BC4J data tags with Oracle9iAS Wireless XML tags and by invoking these servlets through OC4J, they can run any BC4J application on a wireless device emulator. By using the power of the schema-driven editor, developers can create Oracle9iAS Wireless XML pages that they can further call from their JSP pages. Based on the source of the device request, the correct device stylesheet is applied to the XML document. Figure 9-1, "Simplified Request Path" shows how the servlet works (and could use BC4J as a data source for example).
To maximize developer productivity, JDeveloper provides a comprehensive set of integrated tools to support the complete development lifecycle, from source control, modeling, and coding through debugging, testing, profiling, and deploying. JDeveloper simplifies J2EE development by providing wizards, editors, visual design tools, and deployment tools to create high-quality, standard J2EE components including applets, JavaBeans, JavaServer Pages (JSP), servlets, and Enterprise JavaBeans (EJB). JDeveloper also provides a public Addin API to extend and customize the development environment and to seamlessly integrate with external products.
To simplify the development of scalable, high-performance J2EE applications, JDeveloper offers an open and extensible J2EE framework called Business Components for Java (BC4J). BC4J is an object-relational mapping tool that implements Sun's J2EE design patterns, allowing developers to quickly build sophisticated J2EE applications.
The SDK primarily consists of a Java servlet which links to a repository of stylesheets. Based on the source of the HTTP request, the correct stylesheet is applied by the servlet to transform the data to the target markup language for that device. By providing an addin for integrating the SDK into JDeveloper, we provide the developer a mechanism to develop, debug and test Oracle9iAS Wireless XML JSPs and XML pages in a single tool. The developer can create JSP pages with embedded BC4J data tags and Oracle9iAS Wireless XML tags and by invoking these servlets through OC4J, they can run any BC4J application on a wireless device emulator. By using the power of the schema-driven editor they can create Oracle9iAS Wireless XML pages that they can further call from their JSP pages. Figure 9-1, "Simplified Request Path" demonstrates how the servlet works (and could use BC4J as a data source for example):
<%@ page language="java" import="oracle.jbo.*" contentType="text/vnd.oracle.iAS Wireless XML;charset=WINDOWS-1252" %> <%@ taglib uri="/webapp/DataTags.tld" prefix="jbo" %> <SimpleResult> <SimpleContainer> <SimpleText> <SimpleTextItem>Browse Form</SimpleTextItem> </SimpleText> <jbo:ApplicationModule id="am" configname="mypackage.MypackageModule.MypackageModuleLocal" releasemode="Stateful" /> <jbo:DataSource id="ds" appid="am" viewobject="DeptView" rangesize="3"/> <jbo:DataHandler appid="am" /> <SimpleText> <SimpleTextItem>DeptView Browse Form</SimpleTextItem> </SimpleText> <SimpleTable> <SimpleTableBody> <SimpleRow> <SimpleCol><jbo:DataScroller datasource="ds" /></SimpleCol> <SimpleRow> <SimpleRow> <SimpleCol><jbo:DataTable datasource="ds" /></SimpleCol> </SimpleRow> </SimpleTableBody> </SimpleTable> <SimpleContainer> <jbo:ReleasePageResources /> </SimpleResult>
There are two simple wizards which allow a user to create an Oracle9iAS Wireless JSP and an Oracle9iAS Wireless XML document respectively.
The execution flow is as follows:
web.xml
file with the relevant servlet information (servlet name, class, parameters, etc.) and adds it to the current project. Here is the web.xml file:
<?xml version = '1.0' encoding = 'windows-1252'?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> <web-app> <display-name>Oracle 9iAS App</display-name><description>Oracle 9i Application Server Wireless SDK Application</description> <context-param> <param-name>omsdk.repository.path</param-name> <param-value>D:\OMSDK\repository</param-value> </context-param> <context-param> <param-name>omsdk.apps.path</param-name> <param-value>D:\OMSDK\apps</param-value> </context-param> <context-param> <param-name>omsdk.log.path</param-name> <param-value>D:\OMSDK\logs</param-value> </context-param> <servlet> <servlet-name>sdk</servlet-name> <servlet-class>oracle.panama.sdk.SdkServlet</servlet-class> <init-param> <param-name>xml.validation.mode</param-name> <param-value>none</param-value> </init-param> <init-param> <param-name>log.level</param-name> <param-value>debug</param-value> </init-param> <init-param> <param-name>autoreload.transformers</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>autoreload.devices</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>home.page.url</param-name> <param-value>Home.jsp</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet> <servlet-name>lfv</servlet-name> <servlet-class>oracle.panama.sdk.util.LogFileViewer</servlet-class> </servlet> <servlet-mapping> <servlet-name>sdk</servlet-name> <url-pattern>/rm</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>lfv</servlet-name> <url-pattern>/log</url-pattern> </servlet-mapping> <session-config> <session-timeout>30</session-timeout> </session-config> <mime-mapping> <extension>mxml</extension> <mime-type>text/vnd.oracle.iAS Wireless XML</mime-type> </mime-mapping> <mime-mapping> <extension>log</extension> <mime-type>text/plain</mime-type> </mime-mapping> <welcome-file-list> <welcome-file>index.jsp</welcome-file> <welcome-file>index.html</welcome-file> </welcome-file-list> </web-app>
<?xml version="1.0" encoding="WINDOWS-1252" standalone="yes" ?>
<!DOCTYPE SimpleResult PUBLIC "-//ORACLE//DTD SimpleResult 1.1.0//EN" "http://xmlns.oracle.com/ias/dtds/SimpleResult_1_1_0.dtd">
<%@ page contentType="text/vnd.oracle.iAS Wireless XML; charset=WINDOWS-1252" %>
<%@ page language="java" %>
<%@ page import='java.util.*' %>
<Simpleresult>
<Simplecontainer>
<Simpletext>
<Simpletextitem>
The current time is <% out.println((new java.util.Date()).toString()); %>
</Simpletextitem>
</Simpletext>
<menu>
<choice next="choice1.jsp">Choice 1</choice>
<choice next="choice2.jsp">Choice 2</choice>
<choice next="choice3.jsp">Choice 3</choice>
</menu>
</Simplecontainer>
</Simpleresult>
The difference between a typical JSP and the Oracle9iAS Wireless JSP is that the former is automatically run-able by any servlet engine, where as the latter is more like an XML document which needs to be processed by a servlet. In this case, its behavior is similar to a UIX page.
Here are the instructions for installing Oracle9iAS Wireless Wizards and configuring the JDeveloper properties file to run the addin and the wizards.
<Item class="oracle.ide.gallery.GalleryElement"> <name>9iAS WE XML Wizard</name> <wizardClass>oracle.iaswe.iasWEXMLWizard</wizardClass> <wizardParameters/> </Item> <Item class="oracle.ide.gallery.GalleryElement"> <name>9iAS WE JSP Wizard</name> <wizardClass>oracle.iaswe.iasWEJSPWizard</wizardClass> <wizardParameters/> </Item>
Although you will be able to test you mobile applications using a regular Web Browser on your personal computer, it is recommended that you perform testing using various device emulators with different form factors. This will allow you to understand the constructs on Oracle9iAS Wireless XML with respect to rendition on varying device form factors.
Various mobile browser vendors have emulators available that can run on a typical desktop environment. This section lists mobile browser emulators available, categorized into different form factors. The list below is a sample, and provides an introduction to various mobile simulators available; it is not an exhaustive list of all emulators available.
The typical phone device is considered to have a small form factor, although there are phones in the market that support form factor and functionality similar to a PDA device. The browser simulators that support relatively small form factors include Nokia6210, and Phone.com's HDML and WML simulators. Below is a list of phone browser simulators that can be used to test you Oracle9iAS Wireless applications. These simulators run on your Personal computer, and connect to the Oracle9iAS Wireless server over HTTP protocol.
This is an HDML (HandHeld Markup Language) simulator provided by Openwave. You can simulate application behavior on phones that support HDML browsers. HDML is a proprietary markup language supported by Openwave browsers only.
You can use SDK 4.1 to simulate your application with WML 1.1 Openwave browsers and SDK 5.0 to simulate with WML 1.3 Openwave browsers. Openwave SDK is provided by Openwave Systems Inc.For more information go to http://developer.openwave.com.
This toolkit is provided by Nokia and has a simulator for Nokia's WML browser. You can simulate your application on different Nokia phones. The Mobile Internet Tool Kit is provided by Nokia Corporation. For more information go to http://www.forum.nokia.com.
This SDK is provided by Ericsson and allows you to simulate WML applications on various Ericsson phones. The WapIDE 3.1.1 SDK is provided by Telefonaktiebolaget LM Ericsson. For more information see www.ericsson.com.
Yospace provides various WAP simulators that can used to test your application experience on various WML browsers. Yospace simulator is provided by Yospace Holdings Ltd. For more information go to http://www.yospace.com.
The typical PDA device is considered to have a medium form factor. The form factor of PDA is higher than that of a typical phone. The simulators that support PDA-style devices are PocketPC and PalmOS simulators. There are other simulators that support PDA style form factor and also other phone devices with a PDA form factor.
Simulates the Palm OS on your personal computer. You can typically install on to the Palm OS simulator a PQA or browsers such as Eudora. This enables you to test and simulate you application behavior on a PalmOS. Palm, Inc. provides this simulator. For more information see www.palmos.com.
The PocketPC SDK is a desktop application and contains a PocketPC simulator that runs on your personal computer. You can use a browser application on PocketPC such as Pocket Internet Explorer, or similar, to test your application on a PocketPC device. Microsoft Corporation provides PocketPC SDK. For more information go to http://www.microsoft.com.
Voice device are classified as a separate form factor. This is because voice devices, unlike other data devices, do not allow the user to scan the entire document. On voice devices, the user must wait until the voice browser reads the entire document; it is also difficult for users to "scroll" the document.
IBM provides a Voice Server SDK running on a personal computer, and supports VoiceXML technology. You can use IBM's Voice Server SDK to test your VoiceXML applications. The Voice Server SDK is provided by IBM Corporation. For more information see www.ibm.com.
VoiceGenie hosts a developer Voice Gateway that allows you to test your applications over voice. Also VoiceGenie provides Genie IDE that simulates the Voice platform to test your applications. VoiceGenie Technologies Inc. provides both the developer voice gateway and the Genie IDE. For more information see developer.voicegenie.com.
Oracle9iAS Wireless provides Web-based, role-specific tools to create, manage, and deploy mobile services. These webtools include wizards for developing and managing repository objects, and utilities for managing the server and deploying Oracle9iAS Wireless.
After creating your applications, use Oracle9iAS Wireless webtools to deploy them to your customers using your Wireless instance.
For more information on these web-based tools, see Oracle9i Wireless Getting Started and System Guide.
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|