7 Developing Mobile Web Applications

7.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.

7.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 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

• Mode the user is running in (online or offline)

• 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");	
   .
   .
   .}

7.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() ; 

7.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();  ...}

7.2.4.4.1 Registering Servlets Using wtgpack.exe

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:\> wtgpack -d

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

Figure 7-2 displays the Make a Selection dialog.

Figure 7-2 Make a Selection Panel

Description of the illustration pw_selplat.gif

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

Figure 7-3 displays the Applications dialog.

Figure 7-3 Applications Panel

Description of the illustration pw_app.gif

For detailed instructions on how to use the Packaging Wizard, see Chapter 19, " Building Mobile Web Applications: A Tutorial".

7.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 7-2 describes webtogo.ora parameters.

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

7.2.4.4.3 Using wtgdebug.exe

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.

   
   

7.2.4.4.4 Using WebtoGoServer.class

Because the Mobile Client Web Server is written in Java, you can run it inside a Java Virtual Machine (JVM), instead of running the wtgdebug.exe. Running the Mobile Client Web Server in the JVM enables you to debug Web-to-Go applications by running the Mobile Client Web Server inside a Java debugger. You can use the class oracle.lite.web.server.WebToGoServer to start the Java version of the Mobile Client Web Server.

Before you can use the Java version of the Mobile Client Web Server, you need to add the following jar files to your CLASSPATH.

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

<OLITE_HOME>\bin\olite40.jar

<ORACLE_HOME>\mobile\classes\xmlparser.jar

<ORACLE_HOME>\mobile\classes\classgen.jar

<ORACLE_HOME>\mobile\classes\ojsp.jar

<ORACLE_HOME>\mobile\classes\jssl-1_2.jar

<ORACLE_HOME>\mobile\classes\javax-ssl-1_2.jar

<ORACLE_HOME>\mobile\classes\consolidator.jar

You must add the location of your application classes, such as <ORACLE_HOME>\mobile\sdk\wtgsdk\root, to the CLASSPATH. For more information, refer Section 7.2.5, "Using Web-to-Go Applets".

To control and start the Mobile Client Web Server, the file RunWebServer.java demonstrates how to use the class oracle.lite.web.server.WebToGoServer. This file is located in the following directory.

<ORACLE_HOME>\mobile\sdk\wtgsdk\src

To start the Mobile Client Web Server, perform the following steps.

1. Using the following command, compile the Java file.

   javac RunWebServer.java
   
   

2. Run the Mobile Client Web Server using the following command.

   java RunWebServer
   
   

7.2.4.4.5 Controlling Web Server Properties

You can set various properties of the Mobile Client Web Server dynamically using the method WebToGoServer.setProperty(). These values override the values in the file webtogo.ora. The following table lists properties that can be controlled.

Table 7-3 describes Mobile Client Web Server properties.

For example,

WebToGoServer.setProperty ("config_file",     
                           "d:\\orant\\mobile\\server\\bin\\webtogo.ora"); 
WebToGoServer.setProperty ("debug", "0"); 
WebToGoServer.setProperty ("port", "80");

7.2.4.4.6 Registering MIME Types

You can create your own servlet that handles all HTTP requests for files with a particular file extension. For example, you can have a servlet named ASPHandler which handles all requests that end in 'asp'.

You can register this handler with the Mobile Client Web Server using the method WebToGoServer.addMIMEHandler(). For example,

WebToGoServer.addMIMEHandler("text/asp", "asp", "ASPHandler")

7.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.

7.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();
   }}

7.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;}

7.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(); }

7.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);}

7.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 7-4, then select Empty Project.

   Figure 7-4 Creating a New Project

   
   Description of the illustration jdev1.gif
   
   

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 7-5.

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

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

   Figure 7-5 Project Settings - Input Paths

   
   Description of the illustration jdev2.gif
   
   

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
   
   

7.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 7-6. In the Library Name field, enter WTGSDK.

   Figure 7-6 The New Library Dialog

   
   Description of the illustration jdev4.gif
   
   

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.

7.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.

7.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.

7.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.