6 Developing Mobile Web-to-Go Applications

The following sections describe how to develop and test Web-to-Go applications:

• Section 6.1, "Choose the Type of Web-to-Go Mobile Client to Use"

• Section 6.2, "Developing and Testing the Application"

6.1 Choose the Type of Web-to-Go Mobile Client to Use

To install and set up the Mobile Client, see Section 17.5.1, "Install the Mobile Client for Web-to-Go".

There are two types of Web-to-Go applications:

• The original Oracle Database Lite Web-to-Go application that uses an Oracle Database Lite Servlet stack. You can still use this type of application, but the Oracle Database Lite Server stack is not J2EE 1.3 compatible.

• A Web-to-Go application built upon the OracleAS OC4J stack. Since the OC4J product is continually updated, then building your Web-to-Go application using the J2EE standards is better if you want to use future J2EE standards. This application is known as the OC4J Web-to-Go application.

  To build the OC4J Web-to-Go application, follow the J2EE standards specified by Sun Microsystems and then create the snapshot with MDW and publish the application with the EAR or WAR file within the Packaging Wizard.

6.2 Developing and Testing the Application

Web-to-Go provides a high level Java API that provides easy-to-use functionality to developers of Mobile applications. Using this API, developers no longer need to write code for such functions as replication of database tables, database connections, security, directory locations, or deployment of applications to client devices.

In addition, the Mobile Development Kit allows developers to develop and debug Web-to-Go applications that contain Java applets, Java servlets, and JavaServer Pages (JSP).

Figure 6-1 displays the development architecture of the Mobile Server and the Oracle database.

Figure 6-1 Development Architecture

Description of "Figure 6-1 Development Architecture"

The following sections provide a discussion on how to develop Mobile applications for Web-to-Go. Topics include:

• Section 6.2.1, "Building Web-to-Go Applications"

• Section 6.2.2, "Application Roles"

• Section 6.2.3, "Developing JavaServer Pages"

• Section 6.2.4, "Developing Java Servlets for Web-to-Go"

• Section 6.2.5, "Using Web-to-Go Applets"

• Section 6.2.6, "Developing Applet JDBC Communication"

• Section 6.2.7, "Developing Applet Servlet Communication"

• Section 6.2.8, "Debugging Web-to-Go Applications"

• Section 6.2.9, "Customizing the Workspace Application"

• Section 6.2.10, "Using the Mobile Server Admin API"

6.2.1 Building Web-to-Go Applications

Web-to-Go applications adhere to Web standards and use browsers to display user interface elements in a graphical user interface. Generally, Web-to-Go applications access and manipulate data stored in databases. These applications contain static, dynamic, and database components. You can create static and dynamic components using development tools and use the Packaging Wizard to store them in the Mobile Server Repository. You can create and store the application's database components in an object relational database (Oracle Database Lite or Oracle). The following table provides examples of each component type.

Table 6-1 provides examples of each database component type.

Table 6-1 Database Component Types

Component Type	Example
static	HTML files, image files (such as GIF and JPG), HTML templates
dynamic	Java servlets, Java applets and JavaServer pages
database	tables, snapshots, and sequences

6.2.1.1 Static Components

Static components are HTML files that do not change, such as graphical elements (GIF files and JPG files), and textual elements (HTML files and templates).

6.2.1.2 Dynamic Components

Java Applets, Java Servlets, and JavaServer Pages (JSP) are dynamic components that create dynamic Web pages. Java applets, create a rich graphical user interface, while Java servlets and JSPs extend server side functionality.

6.2.1.3 Database Components

Snapshots and sequences are the two database components that Web-to-Go supports. On the Mobile Server, the snapshot definition incorporates information about the table whose snapshot was taken. Web-to-Go also executes custom DDLs (Data Definition Language) statements, enabling the creation of such database objects as views and indexes.

Note:

DDLs are only supported on Windows32 and WindowsCE platforms.

6.2.1.4 Database Connections

Database connections are both application based and session based. For a given session, Web-to-Go maintains a separate connection for each application. If an application runs multiple servlets simultaneously, they use the same connection object. This may occur if the application uses multiple frames or if a user accesses the application with two separate browser windows.

6.2.2 Application Roles

It is common for applications to display different functionality depending on the type of user who is running the application. For example, an application may show different menu items depending on whether manufacturing managers or shipping clerks are running the application.

You can accomplish this in Web-to-Go by defining application roles. The application behavior then changes depending on whether or not a user has a specific role.

In the above example, you can define the application role MANAGER. In your application code, where you generate the menu, you must check if the user has the role MANAGER, and display the correct menu items.

You will use the Packaging Wizard to define application roles in Web-to-Go. You can assign roles to users and groups through the Mobile Manager. However, it is up to the application developer to determine and implement application behavior, if the user has a specific role.

You can query the Web-to-Go user context to retrieve a list of roles that are created for users.

6.2.3 Developing JavaServer Pages

Web-to-Go handles HTTP requests for JavaServer Pages (JSP) using the Mobile client Web Server, Mobile Server, and Mobile Client for Web-to-Go.

6.2.3.1 Mobile Server or Mobile Development Kit Web Server

After the Mobile Server receives an HTTP request for a JSP, it checks if the JSP source file and corresponding class file exist. If the class file exists and is newer than the JSP source file, the Mobile Server loads the Java class and executes the servlet.

If the class file does not exist, or is older than the JSP source file, the Mobile Server automatically converts the JSP source file into a Java source file and compiles it into a Java class under the APP_HOME/_pages. After the JSP has been converted and compiled, the Mobile Server (or the Mobile Development Kit Web Server) loads the Java class and executes the servlet.

6.2.3.2 Mobile Client for Web-to-Go

After the Mobile Client for Web-to-Go receives the HTTP request for a JavaServer page, the corresponding Java class is loaded from the APP_HOME/_pages directory and is executed. Since the Mobile Client for Web-to-Go assumes that the corresponding class file exists, you must convert the JSP source file into a class file. While deploying the application using the Packaging Wizard, you must include both the JSP source file and the corresponding class file. You can create the class files using the Packaging Wizard tool or manually, using the Oracle JSP (OJSP) command line translator.

List your JSP files in the Files panel of the Packaging Wizard and click Compile under the Files tab. The Packaging Wizard automatically locates all the JSP files that you have listed and automatically compiles all of them. The Packaging Wizard adds the compile class to the application package.

6.2.4 Developing Java Servlets for Web-to-Go

You develop Web-to-Go Java servlets with the Mobile Development Kit. The Mobile Development Kit for Web-to-Go simplifies the process of writing Mobile Server servlets. Before using the Mobile Development Kit for Web-to-Go, you must first install it on the development client. The Mobile Development Kit for Web-to-Go contains a Web server called the Mobile client Web Server that executes Java servlets. You can use the Mobile client Web Server to run and debug Java servlets.

• Section 6.2.4.1, "Limitations"

• Section 6.2.4.2, "Accessing Applications on the Mobile Development Kit for Web-to-Go"

• Section 6.2.4.3, "Creating a Servlet"

• Section 6.2.4.4, "Running a Servlet"

• Section 6.2.4.5, "Accessing the Schema Directly in Oracle Database Lite"

6.2.4.1 Limitations

The Mobile Development Kit for Web-to-Go Web server is a scaled down version of the Mobile Server and has the following limitations.

• It contains no application repository. As a result, the Mobile Development Kit for Web-to-Go Web server loads all files and classes directly from the file system.

• Security and access control are disabled.

• Clients that connect to the Mobile Development Kit for Web-to-Go Web server cannot go off-line.

• It provides connection management only to Oracle Database Lite. It connects the user to the schema SYSTEM in the Oracle Database Lite named webtogo.

6.2.4.2 Accessing Applications on the Mobile Development Kit for Web-to-Go

You can access applications on the Mobile Development Kit for Web-to-Go Web server by performing the following steps.

1. To launch the Mobile Development Kit for Web-to-Go Web server, start the Command Prompt and enter the following.

   cd <ORACLE_HOME>\mobile\sdk\bin
   wtgdebug.exe
   
   

2. Use your browser to connect to the Mobile Development Kit for Web-to-Go Web server using the following URL.

   http://machine_name:7070/
   
   

   The Mobile Development Kit for Web-to-Go page displays icons that represent an application in the Mobile client Web Server. Note that port 7070 is the default port for debugging Web-to-Go. For more information, see the file webtogo.ora under the following location.

   <ORACLE_HOME>\mobile\sdk\bin\webtogo.ora
   
   

3. Click the icon of the application that you want to access.

6.2.4.3 Creating a Servlet

Web-to-Go uses servlets to handle HTTP client requests. Servlets handle HTTP client requests by performing one of the following tasks.

• Creating dynamic HTML content and returning it to the browser.

• Processing and submitting HTML forms using an HTTP POST request.

Servlets must extend the HttpServlet abstract class defined in the Java Servlet API. The following is a servlet example.

import javax.servlet.*;import javax.servlet.http.*;import java.io.*;public class HelloWorld extends HttpServlet{   /**   * Process the HTTP POST method   */   public void doPost (HttpServletRequest request, HttpServletResponse response)   throws ServletException, IOException   {     writeOutput("doPost", request, response);   }   /**   * Process the HTTP GET method   */   public void doGet (HttpServletRequest request, HttpServletResponse response)   throws ServletException, IOException   {      writeOutput("doGet", request, response);   }   /**   * Write the actual output   */   public void writeOutput (String method, HttpServletRequest  request,                                           HttpServletResponse response)   throws ServletException, IOException   {      PrintWriter out;      // set content type      response.setContentType("text/html");      // Write the response      out = response.getWriter();      out.println("<HTML><HEAD><TITLE>");      out.println("Hello World");      out.println("</TITLE></HEAD><BODY>");      out.println("<P>This is output from HelloWorld "+method+"().");      out.println("</BODY></HTML>");      out.close();   }}

6.2.4.3.1 Packages

Web-to-Go provides the following Java package:

oracle.lite.web.applet

This package contains the classes to be used with Web-to-Go applets. It contains the AppletProxy class which is used as a proxy for Web-to-Go applets requiring JDBC connections or communicating with a servlet on the Mobile Server. It also contains a few more classes which are used by the AppletProxy class to communicate with the Mobile Server. For more information, see the oracle.lite.web.applet package as documented in the Oracle Database Lite API Specification.

6.2.4.3.2 Web-to-Go User Context

Web-to-Go creates a user context (or user profile) for every user who logs in to Web-to-Go. Web-to-Go applications always run within the user's specific context. Servlets, which are always part of an application, can use the user context (in which it is running) to access the services provided by Web-to-Go. The user context can then be used to obtain the following information.

• Name of the user

• Application that a user is accessing

• The database connection

• Roles that the user has for this application

• Name or value pairs stored in the registry for the user

Servlets can access the user profile through the standard named java.security.Principal obtained through the getUserPrincipal method of the javax.servlet.http.HttpServletRequest class.

This object can also be obtained from the HttpSession object. For example,

public void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException{
 
   // Retrieve the database connection from the User Profile, 
   // which can be accessed from the HttpRequest 
      HttpSession session = request.getSession(true);
      OraUserProfile profile = (OraUserProfile)session.getAttribute("x-mobileserver-user");        
   .
   .
   .}

6.2.4.3.3 Database Connectivity in Java Code

Servlets can obtain a connection to the Oracle database, using the following statement.

HttpSession sess = request.getSession();
WTGUser user = (WTGUser)sess.getAttribute("x-mobileserver-user");
Connection conn = user.getConnection() ; 

6.2.4.3.4 Accessing the Mobile Server Repository

Servlets can open or create a new file in the application repository. Access to the Mobile Server Repository is provided through the servlet context, which can be obtained by calling the getServletContext() from within the servlet. For example:

public void doGet(HttpServletRequest request, HttpServletResponse response)throws ServletException, IOException{   // Retrieve the servlet context   ServletContext ctxt = getServletContext();   // Open an input stream to the file input.html in the Mobile Server Repository   // All file names are relative to the application's repository directory   InputStream in = ctx.getResourceAsStream("input.html");  // Open an output stream to the file output.html in the Mobile Server Repository  // All file names are relative to the application's repository directory  URL            url = ctxt.getResource ("output.html");  URLConnection  conn = url.openConnection();  OutputStream   out  = conn.getOutputStream();  ...}

6.2.4.4 Running a Servlet

Before you can execute the servlet, perform the following:

• Section 6.2.4.4.1, "Registering Servlets Using runwtgpack.bat"

• Section 6.2.4.4.2, "The webtogo.ora File"

• Section 6.2.4.4.3, "Using wtgdebug.exe"

6.2.4.4.1 Registering Servlets Using runwtgpack.bat

Before you can access servlets from the browser, you need to register them with the Mobile client Web Server. To register servlets, you must first register the application and then add the servlets to it. As Web-to-Go enables you to register multiple applications, it displays a list of all registered applications.

The Mobile Development Kit for Web-to-Go includes the Packaging Wizard, a tool for registering applications and servlets. You can invoke the Packaging Wizard by entering the following at the command line.

C:\> runwtgpack -d

Initially, you select whether to create a new application or to continue work on an existing application.

Figure 6-2 displays the Make a Selection dialog.

Figure 6-2 Make a Selection Panel

Description of "Figure 6-2 Make a Selection Panel"

After you make your selection and click OK, the Applications dialog appears.

Figure 6-3 displays the Applications dialog.

Figure 6-3 Applications Panel

Description of "Figure 6-3 Applications Panel"

For detailed instructions on how to use the Packaging Wizard, see Chapter 17, "Tutorial for Building Mobile Web-to-Go Applications".

6.2.4.4.2 The webtogo.ora File

The configuration information for the Web server and the Packaging Wizard is stored in the webtogo.ora file.

Table 6-2 describes webtogo.ora parameters.

Table 6-2 Webtogo.ora Parameters

Parameter Name	Description
ROOT_DIR	The Mobile Server expands all file paths that are relative to its root directory. You can change the root directory by modifying the value of the parameter named ROOT_DIR in the webtogo.ora file. The default parameter value is given below. <ORACLE_HOME>\mobile\sdk\wtgsdk\root
PORT	The port on which the Web server listens. The default value is 80. The default value for the Mobile client Web Server is 7070.
XMLFILE	The XML file that contains the application information. The Packaging Wizard creates and maintains the XML file. You can modify the XML file using the Packaging Wizard.

For more information, refer the discussion of initialization parameters in the Oracle Database Lite Administration and Deployment Guide.

6.2.4.4.3 Using wtgdebug.exe

Perform the following to debug your application with the wtgdebug executable:

1. Using the Command Prompt, enter wtgdebug.exe.

2. Use a browser to connect to the Mobile client Web Server located at the following URL.

   http://machine_name:port

   This Mobile client Web Server displays the list of applications that are currently known to the Mobile client Web Server. The Mobile client Web Server retrieves this list from the XML file. By default, this list includes the sample applications Servlet Runner and Sample.

3. Select the application to debug. This action launches a new browser window which you can use to step through the application.

   Note:

   If you change and recompile your servlet, you need to restart the Web server. You can stop the Web server by pressing Control+C.

6.2.4.5 Accessing the Schema Directly in Oracle Database Lite

The Mobile Development Kit for Web-to-Go automatically creates a database connection to Oracle Database Lite. This database connection connects to the database schema SYSTEM. Within your servlet code, you can obtain this connection from the HTTP request. You can also connect to Oracle Database Lite directly using ODBC. Connecting to Oracle Database Lite directly by using ODBC is helpful for performing the following tasks.

• Creating schema objects such as tables, view and sequences

• Manually checking the contents table

To connect to Oracle Database Lite, launch msql using the Command Prompt.

msql system/manager@jdbc:polite:webtogo

6.2.5 Using Web-to-Go Applets

Web-to-Go supports Java applets. For security reasons, Web-to-Go applets must communicate with the Mobile Server or the Oracle database by using a proxy class. The AppletProxy class acts as a proxy for Web-to-Go applets and provides the applet with the required methods for communicating with the Web-to-Go servlet or for making a JDBC connection. An instance of the AppletProxy should be created while instantiating the applet. Once the instance of the AppletProxy class is created, the AppletProxy object communicates with the Mobile Server and derives all the requisite information to connect to the server or to make a JDBC connection to the Oracle database.

6.2.5.1 Creating the Web-to-Go Applet

The Web-to-Go applet extends the java.applet.Applet. When the init() method initializes the Web-to-Go applet, it creates an instance of the AppletProxy class by passing the Applet reference as the parameter. Once you create an instance of the AppletProxy class, you can use different methods of the AppletProxy class for communicating with the servlet or for establishing a JDBC connection with the Oracle database. For example,

import oracle.lite.web.applet.*; 
public class AppApplet extends Applet {
 
   public void init() 
   {
      .. 
      .. 
      // Create Instance and pass Reference of applet as parameter
      proxy = new AppletProxy(this);
   } 
   AppletProxy proxy;}

The applet can use the following methods to communicate with the servlet. Each method requires an instance of the AppletProxy class.

• getResultObject()

• setSessionId()

• showDocument()

The applet can use the getConnection() method to establish a JDBC connection with the database.

6.2.5.2 Creating the HTML Page for the Applet

The Web-to-Go applet is launched from an HTML page that contains the following tags.

<html>
<body>
<applet ARCHIVE="/webtogo/wtgapplet.jar" CODE="MyApplet.class" WIDTH=200 HEIGHT=100>
<PARAM NAME="ORACLE_LITE_WEB_SESSION_ID"  VALUE="123">
</applet>
</body>
</html>

The AppletProxy class uses the value of the ORACLE_LITE_WEB_SESSION_ID parameter to obtain the SessionID from the Mobile Server. The SessionID is subsequently added to every request an applet makes to a servlet. You can write the HTML code in a static HTML page or you can generate it from a servlet.

6.2.5.2.1 Static HTML Page

Web-to-Go can automatically add the parameter to any static page containing the APPLET tag. For this option, you must change the HTML page's extension to .ahtml as demonstrated in the following syntax.

page_name.ahtml

When the client accesses the HTML page, a Web-to-Go system servlet adds the required <PARAM> tag for the ORACLE_LITE_WEB_SESSION_ID parameter, to the HTML output. For example,

<PARAM NAME="ORACLE_LITE_WEB_SESSION_ID" VALUE="123">

The Web-to-Go system servlet sets the VALUE attribute to your Web-to-Go SessionID.

6.2.5.2.2 HTML Page Generated from a Servlet

You can also dynamically generate the HTML page that contains the <APPLET> tag. When you generate the HTML page dynamically, you must add the SessionID parameter manually. You can retrieve the SessionID information from the oraUserProfile as follows.

import oracle.lite.web.html.*;
import oracle.lite.web.servlet.*;
 
public class AppServlet extends HttpServlet{ 
   public void doGet(HttpServletRequest req, HttpServletResponse resp)
   {
      PrintWriter out = new PrintWriter(resp.getOutputStream());
      out.println("<HTML>");
      out.println("<BODY>");
      out.println("<APPLET ARCHIVE="/webtogo/wtgapplet.jar"
                  CODE='MyApplet.class' WIDTH=200 HEIGHT=100>");
      // Add these lines to add one more PARAM tag in html page
      // This code should be added in-between  <APPLET> and  </APPLET> tag
      OraHttpServletRequest ora_request    = (OraHttpServletRequest) req;
      OraUserProfile        oraUserProfile = ora_request.getUserProfile();
      out.println(" <PARAM NAME=\"ORACLE_LITE_WEB_SESSION_ID\" VALUE=\""
                  +oraUserProfile.getAppletSessionId(req)+"\"> ");
      out.println("</APPLET>");
      out.println("</BODY>");
      out.println("</HTML>");
      out.close();
   }}

6.2.6 Developing Applet JDBC Communication

You can develop Java applets that access the database using a JDBC connection. Once you create an instance of the AppletProxy class, you must use the getConnection method of the AppletProxy class to obtain a JDBC connection. The getConnection method returns the JDBCConnection object.

Note:

The AppletProxy class is described in Section 6.2.5.1, "Creating the Web-to-Go Applet".

6.2.6.1 getConnection()

You can use the getConnection method to obtain a JDBCConnection. The getConnection method determines whether the connection is connected or disconnected and provides access to the Oracle database, if connected, or to the Oracle Database Lite, if disconnected, to the user.

Example

import oracle.lite.web.applet.*; 
public class AppApplet extends Applet 
{ 
   public void init() 
   { 
      ... 
      // Create Instance and pass Reference of applet as parameter 
      proxy = new AppletProxy(this); 
   }
   public java.sql.Connection getDataBaseConnection() 
   {  
            java.sql.Connection  dBConnection = proxy.getConnection();
      return dBConnection;
   }
   AppletProxy proxy;}

6.2.6.2 Design Issue

The Web-to-Go applet holds the database connection even after the user exits Web-to-Go. The applet maintains the connection even if the user types a new URL in the browser or clicks the Back button. Web-to-Go application designers must ensure that their applications explicitly close the database connection when the user exits Web-to-Go.

Example

You can close the connection by calling the following statement.

dBConnection.close()

6.2.7 Developing Applet Servlet Communication

You can develop Java applets that communicate with Java servlets in the Web-to-Go environment. When a client first connects to the Mobile Server, the server generates a SessionID and sends it back to the client. Each subsequent client request to the server contains this SessionID. The Mobile Server authenticates the SessionID before executing the client's request. When applets communicate with Web-to-Go servlets, each applet request must also contain this SessionID. The setSessionId method in the AppletProxy class can be used to add the SessionID to each applet request. The AppletProxy class also contains other methods that provide communication between applets and servlets.

Note:

The getResultObject and showDocument methods can be used to communicate with the Java servlet. Use the setSessionID method if you want to create your own URL connection object.

6.2.7.1 Creating the Web-to-Go Servlet

Servlets must extend the HttpServlet abstract class defined in the Java Servlet API. The following example creates a servlet called HelloWorld that extends the HttpServlet class. The servlet sends the Hello World string to the applet that calls it as an object.

Example

public class HelloWorld extends HttpServlet { 
   public void doGet (HttpServletRequest request, HttpServletResponse response) 
   { 
      ObjectOutputStream out = new ObjectOutputStream (resp.getOutputStream());
      Object obj = (Object) "Hello World" ;
      out.writeObject(obj);
      out.close(); 
   } }

6.2.7.1.1 getResultObject()

The Web-to-Go applet uses the getResultObject() method to communicate with the Web-to-Go servlet by passing the servlet URL and the ServletParameter object as parameters. The servlet responds to the applet request with a text string. The ServletParameter object can be either an object that can be serialized or a string containing name/value pairs. If the servlet accepts parameters, you can call the getResultObject method and pass the servlet parameters as one of the arguments.

Example

public Object getResult() { 
   java.net.URL url = new URL("http://www.foo.com/EmpServlet");
   String ServletParameter = "empname=John";
   Object resultObject = proxy.getResultObject(url, ServletParameter);
   return resultObject;}

6.2.7.1.2 setSessionID()

You can use the setSessionID method for adding a SessionID to an existing URLConnection object. When you write the applet-servlet communication mechanism, call setSessionID (URLConnection) at the end of the method. The method adds a SessionID to the passed URLConnection object and then returns the URLConnection object.

Example

public void YourMethod() { 
   java.net.URL url = new URL("http://www.foo.com/MyServlet");
   java.net.URLConnection con = url.URLConnection(); 
   ...
   // pass the URLConnection to the method setSessionId 
   con = proxy.setSessionID(con); 
   // Do whatever you want to do with this URLConnection object 
   ObjectOutputStream out = new ObjectOutputStream(con.getOutputStream()); 
   out.writeObject(obj); 
   out.flush(); 
   out.close(); }

6.2.7.1.3 showDocument()

The showDocument method displays any static document including those with a suffix of .html, .doc, .xls, or any other one defined by the user. The showDocument method retrieves these documents from the Mobile Server and displays them in the client browser. To display documents, a user must have access permissions for the document and must have the correct MIME type set in the Mobile Server. The showDocument (String relativeDocUrl, String winName) method displays the document in a different browser window identified by a window name that is passed in the winName parameter. The following method launches the help file from the server in a browser window named 'helpwin'.

Example

public void showHelp() { 
   String relativeDocUrl = "Help/HelpIndex.html";
   proxy.showDocument (url, helpWin);}

To show the document in the same browser window as your applet, use call showDocument(url) as given below.

public void showHelp() {
   String relativeDocUrl = "Help/HelpIndex.html";
   proxy.showDocument (url);}

6.2.8 Debugging Web-to-Go Applications

You can run Web-to-Go applications inside a Java debugger if you have already installed the Mobile Development Kit for Web-to-Go and a Java debugger, such as the Oracle9i JDeveloper, Borland's JBuilder, or Visual J++. The example in this section assumes you are using Oracle9i JDeveloper. However, most of the information provided is also relevant to other debuggers.

6.2.8.1 Running Sample 1 Using Oracle9i JDeveloper

This section discusses how to configure the Oracle9i JDeveloper to run the Sample 1 application that is bundled with the Mobile Development Kit for Web-to-Go. For detailed information and full documentation on how to use Oracle9i JDeveloper, consult the online help in Oracle9i JDeveloper and Oracle9i JDeveloper's documentation.

6.2.8.1.1 Creating a Debug Project

To create a new debug project in Oracle9i JDeveloper, perform the following steps.

1. Start JDeveloper.

2. To create a new project in JDeveloper, click File, then click New (assuming you have defined a workspace in JDeveloper).

3. From the Directories menu in the left panel, select Projects, as displayed in Figure 6-4, then select Empty Project.

   Figure 6-4 Creating a New Project

   
   Description of "Figure 6-4 Creating a New Project"
   
   

4. Set the Project Settings for your new project. Right click on Project to retrieve Project Settings. In the Project Settings dialog, expand Common in the left panel and select Input Paths. In the right panel, enter the following information in the Java Source Path field, as displayed in Figure 6-5.

   <ORACLE_HOME>\mobile\sdk\wtgsdk\src\sample1\servlets
   
   

   Leave the Default Package field blank. Do not change the default HTML Root Directory.

   Figure 6-5 Project Settings - Input Paths

   
   Description of "Figure 6-5 Project Settings - Input Paths"
   
   

5. Expand Configurations and then Development in the left panel. Select Paths, which appears below Development in the left panel. In the Output Directory field, in the right panel, enter the following information.

   <ORACLE_HOME>\mobile\sdk\wtgsdk\root\sample1\servlets
   

6.2.8.1.2 Creating a Library

Oracle9i JDeveloper makes it easier to manage sets of JAR files by using libraries instead of CLASSPATH settings.

Files for the WTGSDK Library

Create a WTGSDK library with the following JAR files and add this library to your project.

<ORACLE_HOME>\mobile\classes\ojsp.jar

<OLITE_HOME>\bin\olite40.jar

<ORACLE_HOME>\mobile\sdk\bin\webtogo.jar

<ORACLE_HOME>\mobile\classes\servlet.jar

<ORACLE_HOME>\mobile\classes\xmlparser.jar

<ORACLE_HOME>\mobile\classes\classgen.jar

<ORACLE_HOME>\mobile\classes\wtgpack.jar

Creating a WTGSDK Library

Perform the following steps to create a WTGSDK library.

1. Select Libraries in the left panel, then click New in the right panel.

2. The New Library dialog appears, as illustrated in Figure 6-6. In the Library Name field, enter WTGSDK.

   Figure 6-6 The New Library Dialog

   
   Description of "Figure 6-6 The New Library Dialog"
   
   

3. Click Edit... next to the Class Path field. The File dialog appears.

4. From the appropriate directory, select the six .jar files that are listed above.

5. To add the files, click OK.

6.2.8.1.3 Adding Files to the Project

To add the Sample1 files to your project, perform the following steps.

1. Click the green plus-sign in the Oracle9i JDeveloper System-Navigator to add the Java sources to the project. The File dialog appears.

2. Select the Java source file Helloworld.java in the directory <ORACLE_HOME>\mobile\sdk\wtgsdk\src\sample1\servlets, and click Open.

3. Also, add the file RunWebServer.java, which is located in the directory <ORACLE_HOME>\mobile\sdk\wtgsdk\src, to the project.

4. A dialog appears prompting you to update the project source path. Click No.

6.2.8.1.4 Running and Debugging

Set one or more breakpoints in your code by right-clicking at the statement where you want to break. Select Toggle breakpoint. The background of the statement becomes red, indicating the breakpoint.

1. Select the file RunWebServer.java in the System-Navigator window.

2. Choose Debug by right clicking on the file that you selected to start the Mobile Server inside the debugger.

The Mobile Server is now ready for use. You can access it through your Web browser, by accessing the following URL.

http://<machine_name>

Where <machine_name> is the host name of the computer on which you are running Oracle9i JDeveloper.

6.2.8.1.5 Troubleshooting

This section describes troubleshooting options that you can implement.

Improving Performance

When you run the Mobile Server inside the Java debugger and access it using a Web browser, performance may decrease. To improve performance, perform the following tasks.

1. Run the Web browser on a different machine.

2. Using the Task Manager, set the priority of the Web browser process to LOW after you start the Web browser.

6.2.9 Customizing the Workspace Application

The Mobile Development Kit for Web-to-Go includes a set of APIs that contain a basic Web-to-Go workspace application. Developers can use these APIs to replace the standard Web-to-Go workspace application with a customized version with the following restrictions:

• This can only be customized for the Web-to-Go client only. This is not supported for the Web-to-Go OC4J client.

• You cannot customize the workspace if both the Web-to-Go client and Web-to-Go OC4J client are used.

• The customized workspace is part of the Windows version of the MDK only.

• The Mobile Server and MDK must be installed in the same <ORACLE_HOME>.

These APIs provide the following functionality.

• Login

• Logoff

• Synchronize

• List User Applications

• Change User's Password

For more information on the APIs used to build a customized Web-to-Go workspace application, see the Oracle Database Lite API Specification, which you can view off the main documentation index, which is located at the following:

<ORACLE_HOME>\mobile\index.htm

1. Develop the customized Web-to-Go workspace application using the Web-to-Go APIs.

2. Create an Oracle Database Lite database called webtogo and load the new Web-to-Go workspace application into it. The database acts as the Mobile Server Repository in the Mobile Client for Web-to-Go. For more information, refer to the file crclient.bat, which is included in the sample Web-to-Go workspace application.

3. Create a webtogo.ora file for the Mobile Client for Web-to-Go, which instructs the Mobile Server to use the customized Web-to-Go workspace application. For the correct parameter settings in the webtogo.ora file, refer the section, Section 6.2.9.1, "Web-to-Go Parameters".

4. Load the webtogo.odb file, which is created by the Mobile Client for Web-to-Go, the webtogo.ora file for the Mobile Client for Web-to-Go, and the Web-to-Go workspace into the Mobile Server Repository. For more information, refer to the file crserver.bat, which is included in the sample Web-to-Go workspace application.

5. Instruct the Mobile Server to use the new Web-to-Go workspace application by modifying the webtogo.ora file on the server. For the correct parameter settings in the webtogo.ora, refer the section Section 6.2.9.1, "Web-to-Go Parameters".

6.2.9.1 Web-to-Go Parameters

To instruct Web-to-Go to use a customized Web-to-Go workspace application, you must set the following parameters in the [WEBTOGO] section of the webtogo.ora file.

Table 6-3 describes webtogo.ora parameter settings.

Table 6-3 Setting webtogo.ora Parameters

Parameter	Setting
CUSTOM_WORKSPACE	YES
CUSTOM_DIRECTORY	Repository directory of the Web-to-Go workspace application. For example, /myworkspace.
DEFAULT_PAGE	The entry point of the Web-to-Go workspace application. For example, myfirstpage.html.
CUSTOM_FIRSTSERVLET	The name of the servlet that you want to use in your customized workspace. For example, CUSTOM_FIRSTSERVLET=HelloWorld;/hello

Note:

Web-to-Go supports only one workspace application per Mobile Server.

6.2.9.2 Sample Workspace

The Mobile Development Kit for Web-to-Go includes a sample Web-to-Go workspace application that illustrates how to use the Web-to-Go workspace API. Developers can use this sample application as a starting point when developing their Web-to-Go workspace applications. The sample Web-to-Go workspace application is written using JavaServer Pages (JSP) and .html files. The JSP files are located in the myworkspace/out directory in the Mobile Development Kit for Web-to-Go. These files are compiled into class files that are copied into myworkspace/out directory. This directory also contains all .html files and image files that are used by the sample Web-to-Go workspace application.

The Mobile Development Kit for Web-to-Go includes the following scripts that compile the JSP files, create the Oracle Database Lite named webtogo for the Mobile Client for Web-to-Go, and load all necessary files into the Mobile Server Repository.

Table 6-4 describes scripts available for JSP compilation.

Table 6-4 Scripts for JSP Compilation

Script Name	Description
compile.bat	Compiles .jsp files and copies the class files to the myworkspace/out directory.
crclient.bat	Copies all files in the myworkspace/out directory into the webtogo.odb file.
crserver.bat	Copies all files in the myworkspace/webtogo directory to the Mobile Server Repository, including the webtogo.odb and webtogo.ora files.

6.2.10 Using the Mobile Server Admin API

The Mobile Server Admin API enables an administrator to manage the application resources programmatically. Using the Mobile Server Admin API set, administrators can potentially create their own customized Mobile Manager application to perform the following functions.

• Creating and modifying users and user groups

• Including users and excluding users from group level access to applications

• Assigning snapshot variables to the user

• Suspending and resuming applications

• Publishing a pre-packaged Web-to-Go application

• Customizing an application's underlying database connections

For more information on using the API to build the Mobile Manager, see the Oracle Database Lite API Specification, which you can link to off the following Web page:

<ORACLE_HOME>\mobile\index.htm

Note:

Administrators cannot use the open API set to change the basic properties of an application, such as snapshot definitions or servlets. This can only be done through the Packaging Wizard. For more information, see Chapter 6, "Using the Packaging Wizard" in the Oracle Database Lite Developer's Guide.