|
Oracle® Application Server Wireless Developer's Guide
10g Release 2 (10.1.2) B13819-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Wireless Developer's Guide
10g Release 2 (10.1.2) B13819-02 |
|
|
Previous |
Next |
Each section of this document presents a different topic. These sections include:
OracleAS Wireless includes a developer's kit to enable development and testing of wireless applications without the full installation of Oracle Application Server. The kit provides support for developing applications in the following areas:
J2ME—OracleAS Wireless Development Kit (WDK) contains J2ME Web Services Software Development Kit (J2ME SDK) and the J2ME Web Services Proxy Server (J2ME Proxy Server). The J2ME SDK should be installed on the device before testing the MIDlets.
Messaging—the WDK includes implementation of the OracleAS Wireless Java messaging APIs to enable developers to create applications that use those APIs, and then deploy them without making changes on the OracleAS Wireless server. There are also examples that help developers quickly start their development activities.
Location Services—there are several Web Services WSDL files that can be used to create Location Services.
Multi-Channel Server—The WDK contains a light version of Multi-Channel Server: MCSLite. It provides the same adaptation features as the full Multi-Channel Server product. Wireless and voice application developers can benefit from this small memory-footprint server to test their applications before deploying them on OracleAS Wireless.
OracleAS Wireless Developer Kit is tightly integrated with Oracle JDeveloper Wireless Edition, offering such features as wizards, code templates, and device simulators. Because OracleAS Wireless Developer Kit is offered in a standalone mode, any IDE or development tool can leverage the development functionality of OracleAS Wireless.
Oracle Application Server Wireless WDK Messaging Service provides a rich framework for supporting messaging to a broad range of devices. The complexity and intricacies of underlying protocols and message formats are hidden from notification service clients, allowing them to concentrate on application logic and content creation.
Oracle Application Server Wireless WDK Messaging Service includes these features:
Oracle Application Server Wireless WDK Messaging Service supports a wide variety of messaging protocols, including all major protocols needed to communicate with wireless devices.Protocol support includes:
SMS
Supports both UCP and SMPP out of the box.
Support for both Nokia Smart Messaging and EMS extensions
MMS
Both MM1 and MM7 is supported out of the box.
Built-in MMSC for MM1 support
MM7 support for all major MMSC vendors
SMTP, IMAP and P-IMAP are all supported out of the box
Instant Messaging
Jabber XMPP protocol is supported out of the box, allowing for interoperability with all major IM providers.
Pagers
Both one-way and two-way pagers supported.
Fax
Supports text as well as multimedia attachments
Voice
All major VoiceXML gateways supported.
Voice applications can be written in both OracleAS Wireless XML, XHTML and VoiceXML
Intelligent Messaging Routing
Manual Message Routing—In this release, a single message can be delivered to multiple recipients, across different communication protocols. For example, one can send a meeting reminder to some recipients using SMS, and some other recipients through e-mail. The actual code for sending the messages can be the same regardless of which protocol or device the message is being sent to, the only thing that varies is the extended address of the device the message is sent to. The extended address consists of two parts, the delivery type and the address of the device. The delivery type can also be thought of as the delivery channel. An example of an extended address is E-mail:first.last@oracle.com. In this example, the delivery type is E-mail, and the (regular) address is first.last@oracle.com, separated from the delivery type by a colon. Other examples are sms:+16501234567 and mms: +16501234567. Both of these extended addresses refer to the same physical device, the only difference is the channel to which the message is routed.
Message Failover—In addition to the simple addressing outlined above, WDK Messaging supports sending a message to another device in case the delivery fails. This is achieved by using failover chains. A Failover Chain is a address specification that includes multiple addresses. The address is specified in the form: Address1,address2,…. Each address in the chain is separated by a comma. For example, to send an SMS message to a cell phone, and an e-mail to the same user if sending to the cell phone fails. The failover chain would in this case is: sms:+16501234567,E-mail:first.last@oracle.com. If sending to the SMS device fails, the message will be resent to the e-mail address.
Automatic Content Adaptation
Rich messaging—WDK Messaging fully supports rich messaging (messages that incorporate text formatting, attachments, hyperlinks and embedded multimedia content).
Transcoding—A message can be written in one markup for all devices. Using the Device Repository the Messaging server determines the correct message format for each target device. The input message is transcoded automatically to the correct target device message format. If the receiving device supports the source message format directly, no message conversion will take place.
The message conversion process both transcodes the input markup language, and adapts multimedia content (such as images and audio) as necessary.
The net result of message adaptation is that the application can send messages to a greatest common denominator virtual device, rather than having to keep track of the idiosyncrasies and limitations of each specific messaging channel.
Message Packaging—In addition to message transcoding, the WDK Messaging also packages messages according to the target device. The packaging can be text-based (for example as multipart/alternative for E-mail), or it can be a pure binary format (for channels such as SMS).
Table 8-1 shows the markup source format types.
Table 8-1 Markup source format types
| Markup | Description |
|---|---|
|
XHTML |
XHTML is the preferred markup language for the AS11 Notification Service transcoding engine. |
|
Mobile XML |
OracleAS Wireless XML is supported for all messaging channels. |
|
Native Markups |
In addition to the XHTML markup language, native markups (such as SMIL for MMS) can be specified, for those cases when messages will be sent to a specific set of devices and optimal control is needed. In this case no transcoding will be done on the markup itself, though media adaptation (as described below) is still available. |
|
VCard and VCal |
VCard contacts and VCal appointments can be specified in their respective standard text formats. In the case of channels such as E-mail the original VCard or VCalendar markup simply gets sent as a attachment. In the case of channels such as SMS the VCard/VCalender gets converted to the appropriate binary encoding. |
|
Images |
Images will be adapted to the correct binary format as necessary. In addition, the image can be automatically re-sized and re-dithered if the image is too large for the target device. |
|
Audio |
AS10g WDK Messaging will also adapt audio to the correct format needed by the target device as necessary. |
Imagine sending the above message to two different devices, one sms device and the other an e-mail address:
String[] recipients = [ sms:+16501234567, E-mail:First.Last@oracle.com ]; XMSSimpleSender sender = XMSFactory.createSimpleSender(); sender.sendMsg(recipients, test message, testMsg);
In this case, E-mail can display the full message, and the markup input will be transcoded to HTML. The result will be packaged up as a multipart/alternative message, which includes a plain-text representation of the message along with the HTML-formatted message, as well as the image.
On the SMS device, images cannot be displayed, so a text-only representation of the message is displayed, along with a Web link where the user can view the full message.
When using failover chains, the same transcoding occurs at failover time. If the same message was sent to a failover chain consisting of an E-mail address and an SMS device, the message will initially be sent as a multipart/alternative to the e-mail address, and then if that message delivery fails, the plain text representation will be sent to the SMS address.
The default way of sending messages in the WDK is through the Java API.The following is a brief description of the classes involved in sending messages with the WDK.
All XMS client interfaces are obtained through the XMSFactory singleton class, which is obtained using the getInstance() method standard for that idiom.Currently, the XMSFactory has just two methods, createXMSSimpleSender and createXMSSimpleSender. See the XMS Javadoc for more information on these methods.
XMSSimpleSender is primarily intended for quick implementations such as demonstrations. It allows for message sending using a minimal number of lines of code. However, if more fine-grained status tracking or more advanced functionality (such as sending binary messages) are needed, then XMSSender API is more appropriate.
See the XMS Javadoc for more information on XMSSimpleSender. Examples of how to use this class can be found in the Messaging tutorials.
Although the Java API hides the details of the XMS Web Services interface, it is described here for completeness and to allow you to understand how the WDK works. The information in this section will also be useful if you ever need to generate client-side stubs for languages other than Java.
The XMS web service is an RPC-style web service built on top of SOAP and web service technology to provide messaging services. It supports all message types in the XMS messaging system:
SMS
MMS
EMS
Voice messages
Fax
Pager
Instant Messaging
WAP Push
The XMS web service is described in a standard WSDL file. Table 8-2 shows a brief summary of the contents of that file.
Table 8-2 XMS WSDL file contents
| Method | Input Parameters | Output Parameters |
|---|---|---|
|
getVersion( ) Get the version of XMS server. |
None |
XMS server version in string. For example: 9.0.4.0 |
|
GetSupported Transports( ) Get supported message delivery types supported by the gateway server. |
None |
An array of delivery type strings. For example: SMS, E-mail, Voice |
|
sendText( ) Send a text message through messaging gateway. |
Username: Oracle Application Server wireless username as string Password: password of that user as string Senders: an array of senders' addresses. A sender's address has a transport type, an address and they are separated by colon sign(:). For example: SMS:1-1234567 ReplyTo: (optional) An array of alternative reply to addresses. Each reply to address has a transport type, an address and they are separated by colon sign(:). For example: Voice:1-650- 1234567 Recipients: an array of recipients' addresses in <delivery type> : <address> format. For example: E-mail:john@foo.com. AssociatedKey: (optional) associated key for recipients for easy tracking. Subject: subject of message as string. MessageBody: body of message as string Encoding: encoding of message content. For example: text/plain, text/xml and text/html |
An array of message ID strings. For example: 101, 12345, 112 |
|
sendTextMsg ( ) A simplified version of sendText. No subject can be specified. The content is always text, either plain text or one of the markups supported by Oracle Application Server wireless. |
Username: Oracle Application Server wireless username as string Password: password of that user as string Senders: an array of senders' addresses. A sender's address has a transport type, an address and they are separated by colon sign(:). For example: SMS:1-1234567 Recipients: an array of recipients' addresses in <delivery type> : <address> format. For example: E-mail:john@foo.com. |
Output: An array of message ID strings. For example: 101, 12345, 112 |
|
getStatusByMsgID ( ) Get the current sending status of a message ID. |
Username: Oracle Application Server wireless username as string Password: password of that user as string Message ID: message ID returned by sendTextMsg or sendText as a string |
Output: A message status string in following format: status-code, status-description [, transport-type, address] status-code: <0: failed to deliver the message =0: pending >0: sent to message center or device. status-description: Text description of status transport-type: transport type used to in the delivery address: address used in the delivery For example: "1, Message has been delivered successfully., E-mail, foo@bar.com" |
|
getStatusesByMsgIDs ( ) |
Username: Oracle Application Server wireless username as string Password: password of that user as string Message IDs: an array of message IDs |
An array of message status strings (see getStatusByMsgID) |
WSDL files can be processed by a wide variety of application development tools. See the XMS Web Services tutorial for instructions on how Oracle JDeveloper can generate Java class stub to invoke web services from the WSDL file.
The default messaging gateway for the WDK is http://messenger.oracle.com/xms/webservices. This is a test messaging webservices gateway provided by Oracle Application Server Wireless, which is configured to support MMS, EMS, SMS, e-mail, fax, IM and voice messaging.
Since it provides a standard SOAP web service, this instance can handle requests from all kinds of SOAP clients in addition to the WDK client.
The WSDL file for this instance is located at: http://messenger.oracle.com/push/PushLite.wsdl
The public instance allows free trials for new users, with a limited quota.
This section describes how developers can take advantage of the MCSLite component of the WDK to develop and test their Multi-Channel applications.
MCSLite is a J2EE web application containing servlets and a servlet filter. It has a small memory footprint, yet provides all the content adaptation functionality of a full-fledged MCS Server. Its purpose is to help developers to completely test their applications before deploying on OracleAS Wireless Server.
The main goal of the MCSLite is testing; it provides information to developers to help them better understand the execution of their application. The MCSLite log file contains the following important information:
HTTP headers and request parameters received from a device/simulator
HTTP headers and request parameters sent to back-end applications
HTTP headers and content received from back-end applications
HTTP headers and content sent to a device/simulator
any errors during request processing
MCSLite can be deployed in two ways:
local—MCSLite deployed as a servlet filter in front of a web application to be adapted. The advantage of this deployment is that MCSLite and the content-producing web application run in the same Java VM. This increases the overall performance of the application. The disadvantage of this deployment is that MCSLite must be deployed together with every application.
remote—MCSLite acts as an HTTP proxy between the device and the web application. The advantage of this deployment is that you can develop and deploy your web application independent of MCSLite, and still test it on any device. The disadvantage is that there are two HTTP hops from the device to the content; one from the device to the MCSLite server, and one from the MCSLite server to the web application. This affects performance, but it is a small price to pay compared to the ease-of-use. This is the recommended deployment for developers.
The key features of MCSLite are:
Full adaptation functionality (the same as Multi-Channel Server)
This is the process that occurs during a single cycle of adaptation:
Device detection—see below for more details.
Content retrieval—connecting to the data source and fetching the content produced by a back-end application.
Content type detection—content and HTTP headers returned by the back-end application are examined to obtain the correct content type. This is necessary for choosing the correct transformer based on the current device and content type.
Transformation—transformation from device-neutral markup language to device-specific markup language.
Small memory footprint—Advanced techniques (such as lazy object instantiation) result in a smaller memory footprint. This is helpful because developers can use less powerful machines to write and test applications in WDK.
Flexible log file system—A log file for the content adaptation process is generated. The amount of information in the log file is based on the log-level, which is configurable from the WDK web.xml. When debugging a wireless application, the log level should be set to debug as this will produce the most information. See the next section on how to change the default MCSLite configuration.
Transformers and Device descriptions auto reload—With the auto reload feature, changes to device and transformer metadata will be picked up automatically without a server restart. This is particularly useful when you are adding a new device or transformer to Multi-Channel Server. Since MCSLite uses the same XML representation of device metadata, it is very easy to create and test the new device description in MCSLite, and then upload it to MCS using the MCS XML provisioning tools.
MCSLite was designed to be extremely easy to use. To use it, you must first create and deploy your web application. You can use any web technology to develop your application. You can use either static or dynamic pages. Also, you can use either OracleAS Wireless XML or XHTML+XForms or XHTML MP markup languages. The only requirement is that the application is accessible through HTTP protocol.
The usage depends on the current deployment, either local or remote.
Local Deployment—Deploy your application along with the MCSLite web application. The easiest way to do that is to copy your JSP/Servlets into: ORACLE_HOME/j2ee/OC4J_Wireless/applications/wdk/wdk-web/WEB-INF directory. Use this method if you have a simple application that you want to test and do not want to go through the trouble of creating and deploying your own web application. Here is an example of how to use MCSLite in this deployment scenario:
MCSLite and the user application's URL is: http://apphost:port/myApp.jsp.
Start your device browser (simulator) and enter the application URL (that is, type http://apphost:port/myApp.jsp in the address field).
Remote Deployment (recommended)—This is the recommended usage of MCSLite because the application to be tested is a separate web application which can be deployed onto a running OracleAS Wireless server without any modification (after successful testing with MCSLite). Here is how to use MCSLite in this deployment scenario:
The application to be tested is deployed, and the URL to it is: http://apphost:port/myApp.jsp.
If MCSLite is deployed on a machine with hostname MCSLitehost; the URL to the MCSLite content retriever servlet is http://mcslitehost:port/wdk/mcslite.
The two web applications may or may not be deployed on the same machine. Using this deployment scenario, developers can share a single MCSLite instance. Then accessing the application from a device or simulator is a matter of entering a special URL in the browser. That special URL is: http://mcslitehost:port/wdk/mcslite/http/apphost/port/myApp.jsp (using the above examples).
Here are the steps to create that special URL:
Start with the URL of the mcslite: http://mcslitehost:port/wdk/mcslite
Append to it slash (/), and the URL of the back-end application (http://apphost:port/myApp.jsp). The result of that is: http://mcslitehost:port/wdk/mcslite/http://apphost:port/myApp.jsp
The new URL is invalid. To fix it, change colon, slash, slash (://) and colon (:) in the application URL to a slash (/). The result of that is the special URL: http://mcslitehost:port/wdk/mcslite/http/apphost/port/myApp.jsp
|
Note: There is a short form of the special URL. If the HTTP port on which the application is deployed is port 80 (the default HTTP port), then the port part of the back-end application URL can be skipped. The protocol part (http) can also be skipped. The short URL is:http://mcslitehost:port/wdk/mcslite/apphost/myApp.jsp
|
Regardless of the MCSLite deployment scenario, sending parameters to a back-end application is the same; it is no different than sending such parameters from a regular browser. Just add those parameters in the query part of the URL. For example, to send two parameters to your application:
fname=John and lname=Doe
then you add to the URL as follows:
http:// ... /myApp.jsp?fname=John&lname=Doe
|
Notes:
|
MCSLite uses the same URL rewriting and caching mechanism as MCS except that it uses a configuration parameter indicating whether the long or the short form of URL rewriting should be used.
|
See Also: For more information on URL rewriting and caching, see Chapter 9, "Using Multi-Channel Server". |
|
Note: For information on National Language Support, see Section 9.4.8, "Globalization (NLS) Support". |
The log file contains information crucial for developers; it is a good source for debug information when testing applications. There are four types of messages that can be found in the log file:
ERROR—Severe (non-recoverable) problem during request processing in MCSLite. The most common problems are invalid URLs to a back-end application, or invalid content returned by a back-end application. In those and all other error cases, the log file contains all necessary information to identify the problem.
WARNING—A problem occurred during request processing, but MCSLite recovered from it and served the request. Developers should remove all causes for such warning.
INFO—Informational message about the request processing flow.
DEBUG—Low-level messages related to a problem in the MCSLite itself, rather than in a back-end application. Use the information in the log file when reporting bugs and problems with MCSLite.
You can view the log file in one of two ways:
Directly open the file in the ORACLE_HOME/j2ee/OC4J_Wireless/applications/wdk/wdk-web/logs directory. This requires direct access to the machine on which MCSLite is running (usually the developer's own machine).
Use your PC HTML web browser to access the web log viewer. The URL for the MCSLite log viewer (a servlet) is: http://mcslitehost:port/wdk/log. The web-based log viewer is useful when a group of developers share a single MCSLite server (such as in a remote MCSLite deployment).
For each message in the log file, the IP address and session information for the device request is provided. This is useful when you want to find requests coming from your device versus requests from someone else's device.
|
Note: Error messages in the log.xml file, of the format XFM-xxxx, are generated by the XForms processor. |
One of the advantages of MCSLite is that it works out of the box without any configuration. You can optionally perform advanced configuration actions. MCSLite allows configuration of: log file location and name, logging level, XML validation mode, enabling or disabling auto-reload of devices and transformers, and more. To perform these configuration actions, edit the MCSLite web.xml file. web.xml is located in ORACLE_HOME/j2ee/OC4J_Wireless/applications/wdk/wdk-web/WEB-INF
Here are the configuration properties in MCSLite web.xml:
wdk.log.file—Absolute path to the log file (directory and file name). For example: D:\wdk\logs\wdk.log. You can also specify System.out or System.err to use the standard output or standard error. If no value is specified, then the default log file location is used: ORACLE_HOME/j2ee/OC4J_Wireless/applications/wdkwdk-web/logs/wdk.log
wdk.log.level—Specifies how much information is written to the log file. The permissible values are debug, info, warning, and error. Debug yields the most information, info second, and so on. The default value of this property is info.
xml.validation.mode—Sets the validation mode of the XML parser. Permissible values are true or false. Default value is false.
autoreload.transformers—Specifies whether changes to the transformer should be detected and reloaded automatically. Permissible values are true or false. Default value is true.
autoreload.devices—Specifies whether changes to the devices should be detected and reloaded automatically. Permissible values are true or false. Default value is true.
long.url.format—Specifies whether long or short URL format should be used to rewrite embedded URLs. Permissible values are true or false. Default value is true.
|
See Also: For explanation and comparison between long and short URL formats, see Section 8.3.1.4, "MCSLite URL Rewriting and Caching". |
In OracleAS Wireless server, all device descriptions are stored in the database. However, to simplify MCSLite, database connections are not necessary; each device description is stored in an XML file. The device XML files are located in ORACLE_HOME/j2ee/OC4J_Wireless/applications/wdk/wdk-web/repository. Each XML file contains the metadata that describes attributes and characteristics of a single device.
Some of the important device properties required by the MCSLite are:
Name—Unique name of the device.
UserAgents—Device metadata may contain multiple user agent values, which means that the device metadata can match multiple physical devices. User agents are used for device detection.
Transformers—Contains the name of the transformer that should be used for a specific device. There are multiple transformer values; one for each markup language.
DefaultMarkupLanguage—MIME type of the device. Together with Accept-Charset, constitute the content type of responses sent to a device.
Accept-Charset—Encoding of the device. Together with DefaultMarkupLanguage, constitute the content type of responses sent to a device.
DeviceClass—Class of the device (for example: microbrowser, pdabrowser, pcbrowser, voice, or micromessenger).
DeviceHeight and DeviceWidth—Height and width of the device screen
MCSLite uses the same sophisticated device detection algorithm as OracleAS Wireless server.
The multimedia adaptation supported by MCSLite is the same as in OracleAS Wireless server, except that MCSLite multimedia adaptation does not provide the extensible framework for plugging-in your own implementation of the multimedia adaptation interfaces.
|
See Also: For more information on multimedia adaptation, see Chapter 9, "Using Multi-Channel Server". |
OracleAS Wireless WDK provides a log file to help you develop wireless applications. This section provides a detailed explanation of the information logged in the WDK log file.
The amount of information that is logged in the log file can be configured by changing the wdk.log.level parameter in WEB-INF/web.xml. The possible values for this parameter, with the amount of information being most to least, are: debug, info, warning, and error. The default value of this parameter is info. At this level, the kinds of information that are logged to the log file are:
The request URL—This is the URL string and the query parameters that are associated with the current request being served. For example, http://myhost:80/myapp/foo.jsp?param1=value1
Request HTTP headers received from client—This lists all the request HTTP headers that are received from the client (device). One important header from this list is the user-agent header whose value is used for device detection.
Detected device—Informs the user that this is the device that is detected based on the user-agent header. This information should be checked when something goes wrong.
Request HTTP headers sent to back-end application—Lists all the request HTTP headers that are sent to the back-end application. As a virtual browser, the WDK modifies some of the original headers and adds additional headers.
Response HTTP headers received from back-end application—Lists all the response HTTP headers that are received from the back-end application. Note that these headers are used by the WDK for processing the response and they will not be sent back to the client (device).
XML from back-end application—Shows the exact XML string response from the back-end application.
XML type and version—The WDK will try to detect the type of the XML (whether it is a Simple Result, XHTML+XFORMS, or XHTML-MP) and the version. The result of the detection is shown in this section of the log. Based on this, WDK chooses the correct transformer to use.
WDK Response—Shows the final markup language and HTTP headers that are sent to the client (device). This final result is obtained by applying a transformer (XSLT or Java transformer) to the XML response received from the back-end application.
When debug log level is used, more log messages are produced. The debug messages are:
Transformer loading—Shows a successful loading of a transformer.
Device loading—Shows a successful loading of a device.
Device-to-transformer mapping—Every device has multiple transformers that are associated with it (one for every markup type). This debug message shows such mapping between a device and a transformer.
Back end URL—Shows the back end URL for this request.
Back-end response code and response message—Shows the back-end response code and response message for this request.
The XML passed to the transformer—Shows the XML string passed to the transformer. This XML string differs from the original XML string received from the back-end application. It is an intermediate form that results from annotation and is used as input to the transformer.
The following excerpt from the WDK log file in debug log level (see Example 8-1) is for a single successful request-response cycle using UP Simulator 4.1.1.
The header includes:
Client IP Address: 127.0.0.1
Session ID: fe88712959d4470794599b62102e61df
Log Level: INFO
Timestamp: [Fri, 23 May 2003 10:41:11 PDT]
Example 8-1 WDK log sample file
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
**************** Start of serving request ***************
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
Request URL:
http://localhost:9010/wdk/mcslite/
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
Request HTTP headers received from client:
user-agent: OWG1 UP/4.1.20a UP.Browser/4.1.20a-XXXX UP.Link/4.1.HTTP-DIRECT
x-upfax-accepts: none
x-up-devcap-max-pdu: 2984
x-up-devcap-iscolor: 0
x-up-devcap-numsoftkeys: 2
accept: application/x-hdmlc, application/x-up-alert, application/x-up-cacheop, application/x-up-device, application/x-up-digestentry, application/vnd.wap.wml, text/x-wap.wml, text/vnd.wap.wml, application/vnd.wap.wmlscript, text/vnd.wap.wmlscript, application/vnd.uplanet.channel, application/vnd.uplanet.list, text/x-hdml, text/plain, image/vnd.wap.wbmp, image/bmp, application/remote-printing text/x-hdml;version=3.1, text/x-hdml;version=3.0, text/x-hdml;version=2.0, image/bmp, text/html
x-up-devcap-smartdialing: 1
x-up-devcap-msize: 8,18
accept-charset: ISO-8859-1, UTF-8, *
x-up-devcap-screenpixels: 171,108
host: localhost:9010
accept-language: en
x-up-devcap-screendepth: 1
content-type: application/x-www-form-urlencoded
x-up-devcap-charset: ISO-8859-1
x-up-subno: rhalimma_st3010pc
cookie: JSESSIONID=fe88712959d4470794599b62102e61df
x-up-devcap-immed-alert: 1
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
Request HTTP headers sent to back end application:
x-oracle-user.location.addresslastline: Room 200
x-oracle-service.home.url: http://localhost:9000/omsdk/rm
x-up-devcap-screendepth: 1
host: localhost:9010
x-up-devcap-numsoftkeys: 2
x-oracle-user.deviceid: 1234
x-oracle-orig-user-agent: OWG1 UP/4.1.20a UP.Browser/4.1.20a-XXXX UP.Link/4.1.HTTP-DIRECT
accept: application/vnd.oracle.xhtml+xforms, text/vnd.oracle.OracleAS Wireless XML, application/vnd.wap.xhtml+xml, application/xhtml+xml;profile="http://xmlns.oracle.com/ias/dtds/xhtml+xforms", application/xhtml+xml;profile="http://www.wapforum.org/xhtml", application/xhtml+xml, application/xml, text/xml, application/vnd.oracle.xad, */*, */*
x-oracle-service.parent.url: http://localhost:9000/omsdk/rm
x-oracle-user.location.addressline2: Apt# 1004
x-oracle-user.location.addressline1: 1007 Broadway St
x-oracle-user.location.block: Block A
x-oracle-user.locale: US
x-oracle-user.authkind: unauthenticated
x-oracle-user.displayname: Jon Smith
x-oracle-user.location.type: profile
x-up-devcap-max-pdu: 2984
x-oracle-user.userkind: registered
x-up-devcap-iscolor: 0
x-up-devcap-screenpixels: 171,108
x-oracle-mcs.character.encoding: UTF-8
x-oracle-user.location.postalcodeext: 3158
accept-charset: ISO-8859-1, UTF-8, *
accept-charset: UTF-8, *
x-oracle-user.location.companyname: Company XYZ
x-oracle-home.url: http://localhost:9000/omsdk/rm
cookie: JSESSIONID=fe88712959d4470794599b62102e61df
x-up-devcap-immed-alert: 1
x-oracle-module.callback.url: http://localhost:9000/omsdk/rm
x-upfax-accepts: none
x-up-devcap-smartdialing: 1
user-agent: PTG/2.0 (Oracle9iAS Wireless 9.0.4.0; media="handheld"; paged="1")
x-oracle-user.location.postalcode: 94104
x-up-devcap-msize: 8,18
x-oracle-user.location.city: San Francisco
x-oracle-user.location.country: USA
content-type: application/x-www-form-urlencoded
x-oracle-user.name: jsmith
x-oracle-user.location.y: 200.8
x-oracle-user.location.x: 135.9
x-oracle-user.location.county: San Francisco
x-oracle-orig-accept: application/x-hdmlc, application/x-up-alert, application/x-up-cacheop, application/x-up-device, application/x-up-digestentry, application/vnd.wap.wml, text/x-wap.wml, text/vnd.wap.wml, application/vnd.wap.wmlscript, text/vnd.wap.wmlscript, application/vnd.uplanet.channel, application/vnd.uplanet.list, text/x-hdml, text/plain, image/vnd.wap.wbmp, image/bmp, application/remote-printing text/x-hdml;version=3.1, text/x-hdml;version=3.0, text/x-hdml;version=2.0, image/bmp, text/html
x-up-subno: rhalimma_st3010pc
accept-language: en
x-up-devcap-charset: ISO-8859-1
x-oracle-module.callback.label: Home
x-oracle-user.location.state: CA
127.0.0.1 - - fe88712959d4470794599b62102e61df - - DEBUG : [Fri, 23 May 2003 10:41:11 PDT]
Back end URL: http://localhost:9010/mcs/examples/index.jsp
127.0.0.1 - - fe88712959d4470794599b62102e61df - - DEBUG : [Fri, 23 May 2003 10:41:11 PDT]
Back end response code: 200 ; response message: OK
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
Response HTTP headers received from back end application:
x-oracle-wireless.referer.url: http://localhost:9010/mcs/examples/index.jsp
content-type: application/vnd.oracle.xhtml+xforms; charset=UTF-8
x-oracle-wireless.base.url: http://localhost:9010/mcs/examples/index.jsp
connection: Close
date: Fri, 23 May 2003 17:41:10 GMT
server: Oracle9iAS (9.0.3.0.0) Containers for J2EE
content-length: 994
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
XML Result from backend:
<?xml version = "1.0" encoding = "UTF-8" standalone="yes" ?>
<html profile="http://xmlns.oracle.com/ias/dtds/xhtml+xforms/0.9.0/1.0"
xmlns="http://www.w3.org/1999/xhtml"
xmlns:style="urn:oracle:iasw-internal:style.1.0"
xmlns:extra="urn:oracle:iasw-internal:mxml.1.0">
<head>
<title>Oracle9iAS Wireless Examples</title>
<style type="text/css">
.title {font-style: italic; color: blue; font-size: xx-large}
.menu {font-style: italic; color: blue; font-size: x-large}
li {font-weight: bold; color: blue}
</style>
</head>
<body>
<nl style="list-style-type: decimal">
<label class="title">Oracle9iAS Wireless Examples</label>
<li class="menu" href="xhtml%2Bxforms/index.jsp">XHTML+XFroms Examples</li>
<li class="menu" href="xhtml%2Bmp/index.jsp">XHTML MP Examples</li>
<li class="menu" href="mobile-xml/index.jsp">OracleAS Wireless XML Examples</li>
</nl>
</body>
</html>
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
XML content info - Type: XHTML, version: 0.9.0
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
Transformer that will be used: xforms-wml11-openwave
127.0.0.1 - - fe88712959d4470794599b62102e61df - - DEBUG : [Fri, 23 May 2003 10:41:11 PDT]
The XML passed to transformer:
<html profile="http://xmlns.oracle.com/ias/dtds/xhtml+xforms/0.9.0/1.0" xmlns="http://www.w3.org/1999/xhtml" xmlns:style="urn:oracle:iasw-internal:style.1.0" xmlns:extra="urn:oracle:iasw-internal:mxml.1.0" xmlns:mxml="http://xmlns.oracle.com" style:mheight="0mm" style:mwidth="0mm" style:word-spacing="normal" style:padding-top="0" style:text-align="justify" style:border-top-color="#000000" style:border-right-style="none" style:font-size="medium" style:padding-bottom="0" style:margin-right="0" style:list-style-type="disc" style:vertical-align="baseline" style:border-bottom-color="#000000" style:pause-after="none" style:width="0px" style:speech-rate="default" style:border-left-width="medium" style:speak="normal" style:float="none" style:text-decoration="none" style:padding-right="0" style:border-right-color="#000000" style:list-style-image="none" style:background-attachment="scroll" style:clear="none" style:stress="none" style:font-family="serif,san-serif" style:margin-top="0" style:letter-spacing="normal" style:font-variant="normal" style:border-top-width="medium" style:margin-bottom="0" style:border-left-style="none" style:speak-numeral="none" style:background-image="none" style:pause-before="none" style:volume="default" style:border-bottom-width="medium" style:pitch="default" style:text-transform="none" style:list-style-position="outside" style:padding-left="0" style:margin-left="0" style:border-right-width="medium" style:color="#000000" style:text-indent="0" style:border-top-style="none" style:border-left-color="#000000" style:height="0px" style:font-weight="400" style:background-repeat="repeat" style:font-style="normal" style:pitch-range="default" style:border-bottom-style="none" style:voice-family="neutral" style:speak-header="once" style:display="inline" extra:iaswhref="http://localhost:9010/wdk/mcslite/?PAckey=4!" extra:newdoc="true"><extra:param extra:name="PAckey" extra:value="4!" extra:hidden="true"/>
<head style:border-left-width="medium" style:border-left-style="none" style:border-left-color="#000000" style:display="inline"><extra:messages/><extra:patparams/>
<title style:border-left-width="medium" style:border-left-style="none" style:border-left-color="#000000" style:display="inline">Oracle9iAS Wireless Examples</title>
<style type="text/css" style:border-left-width="medium" style:border-left-style="none" style:border-left-color="#000000" style:display="inline">
.title {font-style: italic; color: blue; font-size: xx-large}
.menu {font-style: italic; color: blue; font-size: x-large}
li {font-weight: bold; color: blue}
</style>
<extra:displaypage page="1" deck="1"/></head>
<body __length__="13" style:border-left-width="medium" style:border-left-style="none" style:border-left-color="#000000" style:display="block" extra:emwidth="0" extra:pxwidth="0" extra:emheight="0" extra:pxheight="0" extra:random="30274" extra:softkeys="2" extra:paged="true"><extra:page page="1" pagelength="342" deck="1" extra:expand="true">
<nl style="list-style-type: decimal" __length__="70" style:white-space="nowrap" style:list-style-type="decimal" style:border-left-width="medium" style:margin-top="0.5em" style:margin-bottom="0.5em" style:border-left-style="none" style:border-left-color="#000000" style:display="block" extra:uid="XF1" extra:expand="true">
<label class="title" __length__="53" style:border-top-color="#0000ff" style:font-size="xx-large" style:border-bottom-color="#0000ff" style:border-left-width="medium" style:border-right-color="#0000ff" style:margin-top="0" style:margin-bottom="0" style:border-left-style="none" style:color="#0000ff" style:border-left-color="#0000ff" style:font-style="italic" style:display="inline">Oracle9iAS Wireless Examples</label>
<li class="menu" href="xhtml%2Bxforms/index.jsp" __length__="78" extra:abshref="http://localhost:9010/mcs/examples/xhtml%2Bxforms/index.jsp" extra:iaswhref="/wdk/mcslite?PAckey=5!" extra:iaswphref="/wdk/mcslite?PAckey=%PAckey!" extra:iaswpkhref="5" style:border-top-color="#0000ff" style:font-size="x-large" style:border-bottom-color="#0000ff" style:border-left-width="medium" style:text-decoration="underline" style:border-right-color="#0000ff" style:margin-top="0" style:margin-bottom="0" style:border-left-style="none" style:color="#0000ff" style:border-left-color="#0000ff" style:font-weight="700" style:font-style="italic" style:display="list-item">XHTML+XFroms Examples</li>
<li class="menu" href="xhtml%2Bmp/index.jsp" __length__="70" extra:abshref="http://localhost:9010/mcs/examples/xhtml%2Bmp/index.jsp" extra:iaswhref="/wdk/mcslite?PAckey=6!" extra:iaswphref="/wdk/mcslite?PAckey=%PAckey!" extra:iaswpkhref="6" style:border-top-color="#0000ff" style:font-size="x-large" style:border-bottom-color="#0000ff" style:border-left-width="medium" style:text-decoration="underline" style:border-right-color="#0000ff" style:margin-top="0" style:margin-bottom="0" style:border-left-style="none" style:color="#0000ff" style:border-left-color="#0000ff" style:font-weight="700" style:font-style="italic" style:display="list-item">XHTML MP Examples</li>
<li class="menu" href="mobile-xml/index.jsp" __length__="71" extra:abshref="http://localhost:9010/mcs/examples/mobile-xml/index.jsp" extra:iaswhref="/wdk/mcslite?PAckey=7!" extra:iaswphref="/wdk/mcslite?PAckey=%PAckey!" extra:iaswpkhref="7" style:border-top-color="#0000ff" style:font-size="x-large" style:border-bottom-color="#0000ff" style:border-left-width="medium" style:text-decoration="underline" style:border-right-color="#0000ff" style:margin-top="0" style:margin-bottom="0" style:border-left-style="none" style:color="#0000ff" style:border-left-color="#0000ff" style:font-weight="700" style:font-style="italic" style:display="list-item">OracleAS Wireless XML Examples</li>
</nl>
</extra:page></body>
</html>
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
Mobile WDK Response:
Content-Type: text/vnd.wap.wml; charset=UTF-8
Content-Length: 1384
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN" "http://www.phone.com/dtd/wml11.dtd">
<wml><head><meta http-equiv="Cache-Control" forua="true" content="max-age=10"/></head><template><do type="accept" name="do_accept" label="Ok"><refresh/></do></template><card><onevent type="onenterforward"><go href="#ID117"/></onevent><onevent type="onenterbackward"><prev/></onevent></card><card id="ID117" title="Oracle9iAS Wireless Examples"><p mode="nowrap"><big><i>Oracle9iAS Wireless Examples</i></big><select name="mID117"><option value="5">XHTML+XFroms Examples</option><option value="6">XHTML MP Examples</option><option value="7">OracleAS Wireless XML Examples</option><option title="Ok">[Back]<onevent type="onpick"><prev/></onevent></option></select><do type="accept" name="do_accept" label="Ok"><go href="#_nav"><setvar name="_h" value="$(mID117)"/></go></do></p></card><card id="_nav" onenterforward="/wdk/mcslite?PAckey=$(_h)!"><onevent type="onenterbackward"><prev/></onevent></card><card id="_form"><onevent type="onenterforward"><go method="post" href="http://localhost:9010/wdk/mcslite/?r=30274"><postfield name="PAckey" value="4!"/><postfield name="$(_sb)" value="$(_sv)"/><postfield name="PATpage" value="$(PATpage)"/><postfield name="PATdeck" value="$(PATdeck)"/></go></onevent><onevent type="onenterbackward"><prev/></onevent></card></wml>
127.0.0.1 - - fe88712959d4470794599b62102e61df - - INFO : [Fri, 23 May 2003 10:41:11 PDT]
**************** End of serving request ***************
This section explains some of the common mistakes encountered in the WDK:
Incorrect URL to the back-end application. For example, here are examples of correct and incorrect URL based on the back end URL http://somehost:8080/myapp/first.jsp:
Correct: http://localhost:9010/wdk/mcslite/http/somehost/9090/myapp/first.jsp
Incorrect: http://localhost:9010/wdk/mcslite/http/somehost/9090/myap/first.jsp
When an incorrect URL is used, the user will get an error page with a detailed explanation of the cause (in this case, 404 Not Found).
The value of back-end URL can be checked in the log file under Back end URL.
Sample log entries:
127.0.0.1 - - 3b34912b68474bc1b1defa87e74dbd1e - - DEBUG : [Fri, 23 May 2003 11:06:45 PDT] Back end URL: http://localhost:9010/mcs/examples/mobile-xmll/index.jsp 127.0.0.1 - - 3b34912b68474bc1b1defa87e74dbd1e - - DEBUG : [Fri, 23 May 2003 11:06:45 PDT] Back end response code: 404 ; response message: Not Found 127.0.0.1 - - 3b34912b68474bc1b1defa87e74dbd1e - - ERROR : [Fri, 23 May 2003 11:06:45 PDT] javax.servlet.ServletException: HTTP(S) Error: 404 : Not Found
Incorrect content-type response header from back-end application. For example, when developing an XForms page, the content type should be set to application/vnd.oracle.xhtml+xforms. Without setting this value, the content detection logic in WDK might fail and result in an incorrect final markup language.
The value of content type that is received from the back-end application can be checked from the log file under Response HTTP headers received from back-end application.
Sample log entries:
127.0.0.1 - - 3b34912b68474bc1b1defa87e74dbd1e - - INFO : [Fri, 23 May 2003 10:59:27 PDT] Response HTTP headers received from back end application: x-oracle-wireless.referer.url: http://localhost:9010/mcs/examples/index.jsp content-type: application/vnd.oracle.xhtml+xforms; charset=UTF-8 x-oracle-wireless.base.url: http://localhost:9010/mcs/examples/index.jsp connection: Close date: Fri, 23 May 2003 17:59:27 GMT server: Oracle9iAS (9.0.3.0.0) Containers for J2EE content-length: 994
Incorrect XML content from back-end application. The XML content from back-end applications should be a well-formed XML document. A spelling error or a missing closing tag will result in an error code 500 from WDK. When this happens, an error message will be displayed in the client device (The xml could not be parsed. It contains invalid xml.).
The XML content from back-end applications can be checked from the log file under XML Result from backend.
Sample log entries:
127.0.0.1 - - 3b34912b68474bc1b1defa87e74dbd1e - - INFO : [Fri, 23 May 2003 11:00:50 PDT]
XML Result from backend:
<?xml version = "1.0" encoding = "UTF-8" standalone="yes" ?>
<html profile="http://xmlns.oracle.com/ias/dtds/xhtml+xforms/0.9.0/1.0"
xmlns="http://www.w3.org/1999/xhtml"
xmlns:style="urn:oracle:iasw-internal:style.1.0"
xmlns:extra="urn:oracle:iasw-internal:mxml.1.0">
<head>
<title>Oracle9iAS Wireless Examples</title>
<style type="text/css">
.title {font-style: italic; color: blue; font-size: xx-large}
.menu {font-style: italic; color: blue; font-size: x-large}
li {font-weight: bold; color: blue}
</style>
</head>
<body>
<nl style="list-style-type: decimal">
<label class="title">Oracle9iAS Wireless Examples</label>
<li class="menu" href="xhtml%2Bxforms/index.jsp">XHTML+XFroms Examples</li>
<li class="menu" href="xhtml%2Bmp/index.jsp">XHTML MP Examples</li>
<li class="menu" href="mobile-xml/index.jsp">OracleAS Wireless XML Examples</li>
</nl>
<body>
</html>
127.0.0.1 - - 3b34912b68474bc1b1defa87e74dbd1e - - ERROR : [Fri, 23 May 2003 11:00:50 PDT]
oracle.wireless.sdk.SdkException: The xml could not be parsed. It contains invalid xml.
Application developers can build exciting new location services, or enhance their existing applications with location information. To do that they need specialized services:
Mobile Positioning—Applications can acquire and set the current location of users.
Location Services:
Geocoding—Find the geographical location of an address or fixed-line telephone number. Also, the inverse function of relating geographical locations to addresses or phone numbers.
Mapping—Get a map image of an area around a location, a map covering a set of locations, a map of a route, and more.
Driving Directions—Get driving directions between two addresses or locations.
Business Directory—Find businesses around an address or location, businesses in a city or state or country, and more.
OracleAS Wireless WDK provides an application programming interface (API) to access these location services components. Developers can access OracleAS Wireless Web Services from these APIs to develop, debug and test their applications without setting up the complete OracleAS Wireless environment together with the relevant content service providers.
The following sections briefly describe some of the important API calls along with some examples. API details can be found in the Javadoc provided with the WDK.
The mobile positioning service allows you to get and set a mobile user's current location. This service is implemented as a web service in OracleAS Wireless WDK. It enables applications to get and set a mobile user's current location from anywhere on the Internet using any programming model.
The oracle.panama.mp.soap.MPSoapClient class wraps the client SOAP calls and exposes the services in the Java programming interface. A client Java program must first construct an object of this class using the web service URL and the service ID before getting and setting a mobile user's location. The web service URL is the SOAP router of the location web service on an OracleAS Wireless server; for example, http://myaswserver.oracle.com:port/location/webservices. The service ID is the SOAP service ID, for example: urn:MobilePositionServer.
Getting Location
Two methods can be used to get a mobile user's location:
getPositionSimple(String username, String password, String msid)
getPosition(String username, String password, String msid, boolean getLatestLocationOnly)
In method getPositionSimple, parameters username and password are used for authentication purposes. The third parameter MSID is the mobile station ID of the user whose location is being requested. An MSID is usually a user's mobile phone number. If the request succeeds, this function returns an array of two double precision numbers representing the longitude and the latitude.
In method getPosition, the first three parameters are the same as in method getPositionSimple. The last parameter is a Boolean value indicating whether the caller wants to get the last known location of the mobile station. If this is set to true, OracleAS Wireless server will return the latest known location of the mobile station without performing any positioning operation. If there is no location cached in the OracleAS Wireless server, an exception is raised. If it is set to false, then OracleAS Wireless server returns the cached location (if its age has not exceeded the default quality of service of the system). Otherwise OracleAS Wireless server performs a mobile positioning operation to get this mobile station's current location. The return value of method getPosition is a string containing the user's location (in XML format) with the following schema:
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" elementFormDefault="qualified"> <xsd:element name="RESPONSE "> <xsd:complexType> <xsd:sequence> <xsd:element ref="TIMESTAMP"/> <xsd:element ref="POS"/> <xsd:element ref="VELOCITY" minOccurs="0"/> <xsd:element ref="BEARING" minOccurs="0"/> <xsd:element ref="ALTITUDE" minOccurs="0"/> <xsd:element ref="ALT_UNCERTAINTY" minOccurs="0"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="ALTITUDE" type="xsd:string"/> <xsd:element name="ALT_UNCERTAINTY" type="xsd:string"/> <xsd:element name="BEARING" type="xsd:string"/> <xsd:element name="LAT" type="xsd:string"/> <xsd:element name="LONG" type="xsd:string"/> <xsd:element name="POS"> <xsd:complexType> <xsd:sequence> <xsd:element ref="LONG"/> <xsd:element ref="LAT"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="TIMESTAMP" type="xsd:string"/> <xsd:element name="VELOCITY" type="xsd:string"/> </xsd:schema>
The <POS> element contains the longitude and latitude of the location.
The <TIMESTAMP> element contains the time stamp when the location was acquired. The time always uses Greenwich Mean Time. For example 2003-03-12 20:01:06 GMT.
The optional <VELOCITY> element specifies the velocity of the mobile device, in meters per second.
The optional <BEARING> element specifies the bearing angle, in degrees, clockwise from North.
The optional <ALTITUDE> element specifies the altitude of the mobile device, in meters, above sea level.
The caller, identified by the username and the password parameters, must be a valid OracleAS Wireless user, and must have been granted the location authorization to access the location of the user associated with the MSID. An exception will be raised if the username and password cannot authenticate the caller, or the caller is not authorized to access the location information.
Setting Location
A mobile device can send its current location, usually provided through a global positioning system (GPS), to OracleAS Wireless server. The current location can then be cached in the server and queried using mobile positioning and privacy APIs. You must create a client application program that posts the device's current location to OracleAS Wireless server. A Java client can call method setPosition(String xmlReq) in class oracle.panama.mp.soap.MPSoapClient. This function takes one String parameter representing the position data. The data must be in XML format, and it must conform to the following schema:
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" elementFormDefault="qualified"> <xsd:element name="MP_GPS"> <xsd:complexType> <xsd:sequence> <xsd:element ref="USERNAME"/> <xsd:element ref="PASSWORD"/> <xsd:element ref="MSID"/> <xsd:element ref="TIME" minOccurs="0"/> <xsd:element ref="GMT" minOccurs="0"/> <xsd:element ref="POS"/> <xsd:element ref="ALTITUDE" minOccurs="0"/> <xsd:element ref="ALT_UNCERTAINTY" minOccurs="0"/> <xsd:element ref="VELOCITY" minOccurs="0"/> <xsd:element ref="BEARING" minOccurs="0"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="ALTITUDE" type="xsd:string"/> <xsd:element name="ALT_UNCERTAINTY" type="xsd:string"/> <xsd:element name="BEARING" type="xsd:string"/> <xsd:element name="GMT" type="xsd:string"/> <xsd:element name="LAT" type="xsd:string"/> <xsd:element name="LONG" type="xsd:string"/> <xsd:element name="MSID" type="xsd:string"/> <xsd:element name="PASSWORD" type="xsd:string"/> <xsd:element name="POS"> <xsd:complexType> <xsd:sequence> <xsd:element ref="LAT"/> <xsd:element ref="LONG"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="TIME" type="xsd:string"/> <xsd:element name="USERNAME" type="xsd:string"/> <xsd:element name="VELOCITY" type="xsd:string"/> </xsd:schema>
The <USERNAME> and <PASSWORD> elements are used by OracleAS Wireless server to authorize the request.
The <MSID> element is the mobile station ID of the mobile device or user.
The optional <TIME> element indicates the time when this location is generated by a GPS. If this value is missing, the time when the data arrives at the OracleAS Wireless server is used.
The optional <VELOCITY> element specifies the velocity of the mobile device, in meters per second.
The optional <BEARING> element specifies the bearing angle, in degrees, clockwise from North.
The optional <ALTITUDE> element specifies the altitude of the mobile device, in meters, above sea level.
Mobile Positioning Example
Here is an example showing how to set and get a position to OracleAS Wireless server using the SOAP client:
MPSoapClient mpsc = new MPSoapClient("http://usunnab16.us.oracle.com:5555/location/webservices", "urn:MobilePositionServer");
String xmlReq = "<?xml version= '1.0' encoding='ISO-8859-1' standalone='yes'?>\n" +
"<MP_GPS>\n" +
"<MSID>6038973096</MSID>\n" +
"<POS>\n" +
"<LAT>42.1576</LAT>\n" +
"<LONG>-122.34</LONG>\n" +
"</POS>\n"+
"</MP_GPS>";
System.out.println(mpsc.setPosition(xmlReq));
// NOTE: Need to change getPosition call//
double[] ret = mpsc.getPositionSimple("", "", "6038973096");
System.out.println(ret[0] + "," + ret[1]);
The LBS web services API on the client side is virtually identical to the API within OracleAS Wireless server. The following examples demonstrate this. The most relevant difference is that a set() function must specify the server. Within OracleAS Wireless server, an application would not be required to specify such a target server.
Geocoding
Geocoding—Assigning geographical coordinates (latitude and longitude) to an address.
Bulk geocoding—Geocoding for a larger set of addresses in one operation.
Reverse geocoding – Assigning an address to a geographical coordinate (latitude and longitude).
Bulk reverse geocoding—Assigning an array of addresses to a geographical coordinate (latitude and longitude).
Telephone geocoding—assigning an address to a land line telephone number
Bulk telephone geocoding
Reverse telephone geocoding—assigning an array of telephone numbers to an address
Bulk reverse telephone geocoding
Geocoding supports these functions:
The following example shows the geocoding operation:
...
public static void main(String args[])
{
SpatialManager.set("http://myaswserver.oracle.com:port/location/webservices");
Location locs[] =
SpatialManager.getGeocoder().geocodeAddress(
new LocationImpl(
new PointImpl(0, 0),
"Oracle",
"1",
new String[] { "Oracle Dr" },
"",
"Nashua",
"NH",
"03062",
"",
"US"),
"");
if(locs != null)
{
for(int i = 0; i < locs.length; i++)
System.out.println(i + ": " + locs[i]);
}
else
System.out.println("null");
}
Mapping
Mapping supports these functions:
Display a map with or without labeled and marked points.
Display a map of a complete driving direction or a single maneuver (the same functionality in Driving Directions).
The following example shows the mapping with one marked point:
...
public static void main(String args[])
{
SpatialManager.set("http://myaswserver.oracle.com:port/location/webservices");
Location
adr1[] =
SpatialManager.getGeocoder().geocodeAddress(
new LocationImpl(
new PointImpl(0, 0),
"NEDC",
"1",
new String[] { "Oracle Dr" },
"",
"Nashua",
"NH",
"03062",
"",
"US"),
""),
adr2[] =
SpatialManager.getGeocoder().geocodeAddress(
new LocationImpl(
new PointImpl(0, 0),
"HQ",
"500",
new String[] { "Oracle Parkway" },
"",
"Redwood City",
"CA",
"94065",
"",
"US"),
"");
System.out.println(
SpatialManager.getMapper().getMapURL(
adr1[0],
ImageFormats.GIF,
800,
600,
false));
...
}
...
Driving Directions
The Driving Directions component supports these functions:
Determine driving directions between addresses or geographical point coordinates.
Display maps of complete directions or single maneuvers.
Provide a simple geometry of a driving direction.
Provide text directions, distance and time of a route requested.
The following example shows the driving direction between two addresses:
...
public static void main(String args[])
{
SpatialManager.set("http://myaswserver.oracle.com:port/location/webservices");
Location
adr1[] =
SpatialManager.getGeocoder().geocodeAddress(
new LocationImpl(
new PointImpl(0, 0),
"NEDC",
"1",
new String[] { "Oracle Dr" },
"",
"Nashua",
"NH",
"03062",
"",
"US"),
""),
adr2[] =
SpatialManager.getGeocoder().geocodeAddress(
new LocationImpl(
new PointImpl(0, 0),
"HQ",
"500",
new String[] { "Oracle Parkway" },
"",
"Redwood City",
"CA",
"94065",
"",
"US"),
"");
//////////////////////////////////////////////////////////////////
RoutingSettings settings = new RoutingSettings(true, false);
settings.setSecondaryOption(RoutingOption.maneuverMapWidth, "800");
settings.setSecondaryOption(RoutingOption.maneuverMapHeight, "600");
settings.setSecondaryOption(RoutingOption.overviewMapWidth, "800");
settings.setSecondaryOption(RoutingOption.overviewMapHeight, "600");
System.out.println(
SpatialManager.getRouter().computeRoute(
adr1[0],
adr2[0],
null,
settings,
Locale.US));
}
Business Directory
The Business Directory component supports these functions:
Finding businesses within: Cities, States, Postal codes, Distance from an address or geographical location, Distance from a driving directions route, the set of closest n businesses around an address or geographical location.
Finding businesses: With a given name, in a given category, matching a given keyword (in name or category), matching a given name and category.
Searching and navigating the category hierarchy.
The following example shows several categories and businesses with a given name:
public static void main(String args[])
{
SpatialManager.set("http://myaswserver.oracle.com:port/location/webservices");
//////////////////////////////////////////////////////////////////
System.out.println(SpatialManager.getYPFinder().getCategoryAtRoot());
System.out.println(SpatialManager.getYPFinder().getCategoryAtPath(new String[0]));
YPCategory cats[] =
SpatialManager.getYPFinder().getCategoryAtRoot().getSubCategories();
if(cats != null)
for(int i = 0; i < cats.length; i++)
System.out.println(i + ": " + cats[i]);
//////////////////////////////////////////////////////////////////
YPBusiness b[] =
SpatialManager.getYPFinder().getBusinessesAnywhere(
"Border",
Locale.US);
for(int i = 0; i < b.length; i++)
System.out.println(i + ": " + b[i]);
}
