7
Mobile Modules

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

• Section 7.1, "Introduction"

• Section 7.2, "Wireless XML Attributes for Mobile Modules"

• Section 7.3, "Shipped Mobile Modules"

• Section 7.4, "Using Shipped Mobile Modules"

• Section 7.5, "Developing Custom Mobile Modules"

7.1 Introduction

Mobile Modules are wireless services with well-known virtual URL (OMP URL, i.e. omp://my.module). Mobile Modules provide an analogous mechanism to data abstraction and interfaces. They allow a component-based programming model for building mobile applications within the Oracle9iAS Wireless framework. Component-based programming provides rapid application development, reusable components and easy-to-maintain code which are essential to timely, successful deployment of web applications.

Mobile Modules can be called from any application or module and may be instructed to return control to another application or module. Calls may be nested to any level. This mechanism of bi-directional linking allows quick applications assembly.

Important difference between a module and a regular service is that the module receives information about the service it needs to return to after it is done. This is not always the caller of the module (the module caller may want the module to return to a different service).

An example of an application that leverages Mobile Modules could be a store locator application for a retail company. A developer writing this application could improve the interface by linking to the Location Mobile Module, which enables a user to store frequently accessed locations as landmarks. The application would then offer to find the nearest store based on one of those locations, saving the user the time and effort of entering an address. The next logical step would be to link to the Driving Directions Mobile Module, so that a customer could easily get directions to the store they have selected. This would enable the user to get directions without typing in any additional information, since both the starting location and the destination address (store) would intelligently populate the corresponding fields in the application.

7.2 Wireless XML Attributes for Mobile Modules

The target attribute of SimpleMenuItem, SimpleAction, SimpleHref, and SimpleForm may be used for linking to a Mobile Module. The value of the target attribute starts with omp:// for accessing modules.

Note: The value of the omp:// URL is not important. There are only two important things that you need to keep in mind: The value must start with omp:// The value must be unique (just like an http:// URL)

These are the XML attributes that are used for linking to Mobile Modules:

• target - is the only mandatory attribute. Its value is the virtual (omp://) URL for the Mobile Module.
  For example:
  
  <SimpleMenuItem target="omp://oracle.com/module" callbackurl="%value service.home.url%">Call My Mobile Module</SimpleMenuItem>

• secure - an optional attribute. The value is either "true" or "false". This attribute is used to switch between HTTP (secure="false") and HTTPS (secure="true") protocol for the connection between the end user device and Oracle9iAS Wireless server when calling the module. If you do not set this attribute then the current protocol will be used.
  For example:
  
  <SimpleMenuItem target="omp://oracle.com/module" callbackurl="%value service.home.url%" secure="false">Call My Mobile Module</SimpleMenuItem>

• callbackurl - This is the URL of the service where the mobile module should return after it is done. The default value is the current caller service. You can use Mobile Context (see Chapter 8, "XML Tag Glossary") to specify values for the attribute.
  For example:
  
  <SimpleMenuItem target="omp://oracle.com/module" callbackurl="%value service.home.url%"> Call My Mobile Module</SimpleMenuItem>

• callbacksecure - an optional attribute. The value is either "true" or "false". This attribute is used to switch between HTTP (callbacksecure="false") and HTTPS (callbacksecure="true") protocol for the connection between the end user device and Oracle9iAS Wireless server when the module calls back.
  For example:
  
  <SimpleMenuItem target="omp://oracle.com/module" secure="true" callbackurl="%value service.home.url%" callbacksecure="false"> Call My Mobile Module</SimpleMenuItem>

• callbackparam - an optional attribute that sets parameters to be passed to the caller after the module is done.
  For example:
  
  <SimpleMenuItem target="omp://hostname/module" callbackurl="%value service.home.url%" callbackparam="foo=bar&amp;test=TEST&amp;a=z ">My Mobile Module</SimpleMenuItem>

7.3 Shipped Mobile Modules

Oracle9iAS Wireless contains a set of 17 ready-to-use modules subdivided in the following areas: mobile commerce, PIM and location-based services. Application developers may reuse these modules as the jumpstart of their wireless development work, or develop their own modules, by following the instructions in this document. For a complete reference on the shipped Mobile Modules, see Chapter 18, "Mobile PIM and eMail" and Chapter 19, "m-Commerce"

7.4 Using Shipped Mobile Modules

7.4.1 Commerce Services

To use the Payment Module in order to make an credit card payment of US$ 90.00 you will use:

<SimpleMenuItem target="omp://oracle/services/commerce/payment?AMOUNT=90&merchantid=bookshop&MODE=ONLINE&TYPE=AUTH&INSTRTYPE=CC" callbackurl="%value service.home.url%">Pay amount</SimpleMenuItem>

The payment module will take the action after the user chooses this menu, and will present a flow of cards that will lead to the payment itself. In the end the Payment Module will return the transaction id in the HTTP request.

7.4.2 PIM Services

To use the Mail Module you will need to inform the action and the email to whom you want to sent the message:

<SimpleMenuItem target="omp://oracle/services/pim/mail?action=messageto&mailto=[e-mail]" callbackurl="%value service.home.url%">Send eMail</SimpleMenuItem>

7.4.3 Location Services

To use the Maps Module you will need to inform the address you want to map:

<SimpleMenuItem target="omp://oracle/services/location/maps?FL=500 Oracle Parkway&CI=Redwood Shores&ST=CA" callbackurl="%value service.home.url%">Map Oracle</SimpleMenuItem>

Note: These are just small examples on how to call the shipped Mobile Modules. For a more complete reference of the Modules OMP URLs, input and output values please see Chapter 18, "Mobile PIM and eMail" and Chapter 19, "m-Commerce".

7.5 Developing Custom Mobile Modules

Developing Mobile Modules is not very different than developing your own services. For more details about how to develop service see Chapter 15, "Using Location Services", Chapter 18, "Mobile PIM and eMail", and Chapter 19, "m-Commerce". In our examples we are going to use the HttpAdapter. The mobile modules will use simple JSP pages.

7.5.1 "Hello World" Mobile Module

Our first mobile module does not do much. It will just display "Hello World" on the end user device and a link to go back to the module caller service.

7.5.1.1 Create and publish the JSP pages for the module and the caller services

Here is the JSP code for the module:

<?xml version = "1.0" encoding = "UTF-8" 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.mobilexml; charset=UTF-8" %>
<%@ page language="java" %>
<%@ page session="false" %>
<SimpleResult>
  <SimpleContainer>
    <SimpleMenu>
      <SimpleTitle>Hello World</SimpleTitle>
      <SimpleMenuItem target="%value module.callback.url%">Go Back To The 
Caller</SimpleMenuItem>
    </SimpleMenu>
  </SimpleContainer>
</SimpleResult>

Please save this code in HelloWorldModule.jsp and publish it at let say http://localhost/jsp/HelloWorldModule.jsp.

And the JSP code for the caller service:

<?xml version = "1.0" encoding = "UTF-8" 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.mobilexml; charset=UTF-8" %>
<%@ page language="java" %>
<%@ page session="false" %>
<SimpleResult>
  <SimpleContainer>
    <SimpleMenu>
      <SimpleTitle>Hello World Caller</SimpleTitle>
      <SimpleMenuItem target="omp://HelloWorld" callbackurl="%value 
service.home.url%">Call Hello World Module</SimpleMenuItem>
    </SimpleMenu>
  </SimpleContainer>
</SimpleResult>

Please save this code in HelloWorldCaller.jsp and publish it at (for instance): http://localhost/jsp/HelloWorldCaller.jsp

7.5.1.2 Create HelloWorldModuleMS and HelloWorldCallerMS MasterServices

After we publish the JSP pages we need to create two HttpAdapter based MasterServices. Use the Service Designer web tool to do that. See Oracle9iAS Wireless Getting Started and System Guide for more details about creating MasterServices

IMPORTANT: Please mark the HelloWorldModuleMS MasterService as "Modulable".

7.5.1.3 Create the caller and the module services

After you are done with the MasterServices you need create two services: HelloWorldModule and HelloWorldCaller. Use the Content Manager web tool to do that. See Oracle9iAS Getting Started and System Guide for more details about creating MasterServices.

IMPORTANT: The type of the HelloWorldCaller service should be "Normal Service". The type of the HelloWorldModule service should be "Module". Set the OMP URL for the HelloWorldModule service to omp://HelloWorld. Before you can test the newly created services you need to assign them to a Group so the users in that group can invoke those services.

That is it. Now you can test the two services from your device.

7.5.2 Sending Parameters to a Mobile Module

The Mobile Modules that you want to develop will most likely take some input from its caller and then return something back after there are done. Below are the JSP pages that show how a caller service can send an input parameter to a module. Publishing those two JSP pages on Oracle9iAS Wireless is the same as publishing the previous JSP pages.

Here is the code for the HelloNameModule.jsp

<?xml version = "1.0" encoding = "ISO-8859-1" 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.mobilexml; charset=ISO-8859-1" %>
<%@ page language="java" %>
<%@ page session="false" %>
<%
   String uname = request.getParameter("uname");
%>
<SimpleResult>
   <SimpleContainer>
    <SimpleMenu>
      <SimpleTitle>Hello Module Says Hello <%=uname%></SimpleTitle>
      <SimpleMenuItem target="%value module.callback.url%">Go Back To The 
Caller</SimpleMenuItem>
    </SimpleMenu>
   </SimpleContainer>
</SimpleResult>
And the JSP code for the HelloNameCaller.jsp:
<?xml version = "1.0" encoding = "ISO-8859-1" 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.mobilexml; charset=ISO-8859-1" %>
<%@ page language="java" %>
<%@ page session="false" %>
<SimpleResult>
   <SimpleContainer>
      <SimpleForm target="omp://HelloName">
         <SimpleTitle>Please Enter User Name</SimpleTitle>
	   <SimpleFormItem name="uname" />
      </SimpleForm>
   </SimpleContainer>
</SimpleResult>

IMPORTANT: When you create the Oracle9iAS Wireless MasterService and service objects remember to: mark the HelloNameModuleMS MasterService as "Modulable" set the type of HelloNameCaller service to be "Normal Service" and the type of the HelloNameModule service to "Module" Set the OMP URL for the HelloWorldModule service to omp://HelloName

Note: Before you can test the newly created services you need to assign them to a Group so the users in that group can invoke those services.

That is it. Now you can test the two services from your device.