3
Developing Web-to-Go Applications

3.2.2.1 Java Applets

Java applets are small applications executed in the browser that extend the functionality of HTML pages by adding dynamic content. In the offline mode, the Java applets connect to the Oracle Lite database through the Mobile Client for Web-to-Go. In the online mode, the Java applets can connect directly to the Oracle8 or Oracle8i database through a thin JDBC driver. Alternatively, the Java applets connect to the Oracle database through the Mobile Server.

3.2.2.2 Java Servlets

Web-to-Go simplifies the creation of dynamic Web pages by using Java servlets. Java servlets are platform-independent, server-side modules that can be used to extend the capabilities of a Web server. Written in Java, these modules are loaded to the Web server.

3.2.2.3 JavaServer Pages

Web-to-Go generates dynamic Web pages using JavaServer Pages (JSP) technology, an extension of the Java Servlet class API. Developers use JSP to change a page's layout without altering its underlying content. JSP, which uses HTML and pieces of Java code, fuses presentation content (HTML and traditional editors) with business logic though its access of JavaBeans.

3.2.3.1 Snapshots

The Mobile Client for Web-to-Go creates disconnected support for tables through its support for snapshots. On the client side, a snapshot is created for each database table. These snapshots refresh the data each time the client synchronizes with the Mobile Server. Web-to-Go propagates the data changes automatically.

Snapshot definitions can include a WHERE clause which limits the amount of data replicated to the client. These definitions are called snapshot templates. See Oracle9i Lite Administration Guide for more information about how to register snapshot templates. For more information on how snapshot templates and subqueries snapshots can enhance your applications, see Oracle9i Lite Administration Guide.

3.2.3.2 Sequences

Sequences (used in many database applications) allow you to generate unique identifiers. You can use sequences to generate unique primary key values when inserting new records in a database table. This is very important when clients in disconnected mode insert new rows into tables. Replication uses the primary key values to identify records. Duplication of primary keys causes replication conflicts which must be manually resolved by the administrator. Because avoiding these conflicts is important, Web-to-Go provides a mechanism to ensure that sequence values generated in disconnected mode are unique (valid). To this end, Web-to-Go assigns each disconnected client a unique window of sequence values for each sequence.

Sequence numbers are from -2,147,483,648 to 2,147,483,647 in Oracle Lite and from -10^26 to 10^27 in Oracle. This allows for the creation of large windows of sequence values. For example, 10,000 users, each with a window of 10,000, use only 100,000,000 sequence values, which is approximately 5 percent of the available positive sequence values in Oracle Lite. See Oracle9i Lite Administration Guide for more information.

3.2.3.3 DDLs

In addition to replication support for tables and sequences, Web-to-Go also executes custom DDL (Data Definition Language) statements on clients. You can use DDLs to create any database object, such as a view or a synonym. DDLs are part of Web-to-Go applications and are defined using the Packaging Wizard. Web-to-Go executes DDLs only once on each client when the client synchronizes the first time.

3.2.3.4 Database Component Access

The database components can be accessed from the Java servlets through a JDBC connection. Because Web-to-Go creates and maintains the pool of JDBC connections, it is not necessary to create connections inside the servlet code. If Web-to-Go is running in online mode, the connection is to Oracle; if Web-to-Go is running in disconnected mode, the connection is to Oracle Lite. Web-to-Go assigns a connection object to the HTTPServletRequest object before processing the HTTP request using the Java servlet's doPost() or doGet() method. The connection is automatically returned to the connection pool upon completion of the HTTP request. Because a user may not get the same connection object for a subsequent HTTP request, the servlet must either commit or abort the transaction upon completion of the methods, doPost() or doGet(). Web-to-Go automatically rolls back any pending transactions before a connection object is returned to the connection pool.

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

   }

}

3.5.3.1 Packages

Web-to-Go provides four Java packages. The oracle.html and oracle.lite.html packages are both described in Appendix B, " Web-to-Go Java Packages". The oracle.lite.web.servlet and oracle.lite.web.applet packages are both described in the Mobile Server API. You can use the classes supplied in the packages to simplify the development of Java servlets.

oracle.html. This package provides class abstractions of all the HTML elements (HTML tables and form buttons), enabling you to create and manipulate HTML objects in the Java code easily. See "Using the oracle.html Package" in Appendix B, " Web-to-Go Java Packages" for more information.

oracle.lite.web.html. This package contains base classes you can extend to create customized Java servlets. These classes enable you to create HTML forms linked to database tables easily. The data is automatically loaded from the database and formatted in HTML. When the form is submitted, any changes to the data in the form are automatically reflected in the database. For more information, see Using the oracle.lite.web.html Package in the Mobile Server API. See also "Using the oracle.lite.web.html Package" in Appendix B, " Web-to-Go Java Packages" for more information.

oracle.lite.web.servlet. Servlets can use classes from this package to obtain user profile information. This package defines the OraHttpServletRequest class, which implements the HttpServletRequest interface from the Java Servlet API.

oracle.lite.web.applet. This package contains the classes to be used with Web-to-Go applets. It contains AppletProxy class which is used as a proxy for Web-to-Go applets making JDBC connection 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. See Using the oracle.lite.web.applet Package in the Web-to-go API for more information.

3.5.3.2 Web-to-Go User Context

Web-to-Go creates a user context (or user profile) for every user logged on 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 be used to obtain the following information:

• The name of the user

• The mode the user is running in (online or offline)

• The application the user is accessing

• The database connection

• The roles the user has for this application

• The name/value pairs stored in the registry for this user

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

This object can also be obtained from the oracle.lite.web.servlet.OraHttpServletRequest, a subclass of the JavaSoft-defined javax.servlet.http.HttpServletRequest. Servlets can typecast the request parameter to the OraHttpServletRequest object and call the getUserProfile method to obtain the user profile 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 
      OraUserProfile oraUserProfile =  ((OraHttpServletRequest)ora_request).getUserProfile();

   .

   .

   .

}

3.5.3.3 Database Connectivity in the Java Code

Servlets can obtain a connection to Oracle8i from the UserPrincipal object

Connection conn = ((OraUserProfile) request.getUserPrincipal()).getConnection();

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

  .

  .

   .

}

3.5.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 first register the application and then add the servlets to it. (Web-to-Go allows you to register multiple applications.) When you connect to the Mobile Client Web Server from the browser, 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 typing 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.

After you make your selection and click OK, the Application panel appears.

For detailed instructions on how to use the Packaging Wizard, see Chapter 4, " The Web-to-Go Tutorial".

3.5.4.2 The webtogo.ora File

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

The file is located in the Oracle_Home\mobile\sdk\bin directory.

The webtogo.ora file contains the following parameters:

Parameter	Definition
ROOT_DIR	The Mobile Server expands all file paths relative to its root directory. You can change the root directory by modifying the value of ROOT_DIR in the webtogo.ora file. The default value is 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.
XML_FILE	The XML file that contains the application information. The Packaging Wizard creates and maintains the XML file. You can modify the XML file by using the Packaging Wizard.

See the discussion of initialization parameters in Oracle9i Lite Administration Guide for more information.

3.5.4.3 Using wtgdebug.exe

Start wtgdebug.exe by performing the following steps.

1. From a DOS prompt, type:

   wtgdebug

2. Use a browser to connect to the Mobile Client Web Server located at the URL:

   http://machine_name:port

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

   
   

3.5.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 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 to your CLASSPATH:

Oracle_Home\mobile\sdk\bin\webtogo.jar

Oracle_Home\mobile\classes\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. See also "Step 5: Running the Application" from Chapter 4, " The Web-to-Go Tutorial".

The file RunWebServer.java demonstrates how to use the class oracle.lite.web.server.WebToGoServer to control and start the Mobile Client Web Server. 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. Compile the Java file by using the following command:

   javac RunWebServer.java

2. Run the Mobile Client Web Server with the following command:

   java RunWebServer

3.5.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 webtogo.ora. Properties that can be controlled are:

Property	Definition
config_file	The configuration file to use. See also "The webtogo.ora File".
port	The port on which the Mobile Client Web Server listens.
debug	Enables debugging. Set to Yes if you want to view debug messages.
log_file	The debug log file. If specified, debug messages are sent to this file, otherwise the messages are displayed to the screen.
root_dir	The root directory. Overrides ROOT_DIR in webtogo.ora. See ROOT_DIR.

For example:

WebToGoServer.setProperty ("config_file",     

                           "d:\\orant\\webtogo\\bin\\webtogo.ora"); 

WebToGoServer.setProperty ("debug", "true"); 

WebToGoServer.setProperty ("port", "80");

3.5.4.6 Registering Servlets

You can also dynamically add servlets without using the Packaging Wizard. Use the following Java code to register the servlet class HelloWorld with the Mobile Client Web Server:

WebToGoServer.addServlet("HelloWorld", "/Hello");

The servlet is added to the default application, "servlet runner," and can be accessed by typing the following URL:

http://machine_name/servlets/Hello

The servlet returns the following HTML:

<HTML><HEAD><TITLE>

Hello World

</TITLE></HEAD><BODY>

<P>This is output from HelloWorld doGet().

</BODY></HTML>

3.5.4.7 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 ASPHandler that 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")

3.5.4.8 Registering Name/Value Pairs

Web-to-Go provides a registry that can be used to persistently store objects. These objects can be obtained inside your servlet code using the method OraUserProfile.getValue(). The Mobile Server stores the registry objects in the access control system. For the Mobile Client Web Server you can set these registry objects dynamically using the method WebToGoServer.addRegistryEntry(). This enables you to test applications that use the registry. For example:

// Add a registry name/value pair to the default application "servletRunner" 

WebToGoServer.addRegistryEntry ("usercode", "1111");

// Add a registry name/value pair to the specified application. 

WebToGoServer.addRegistryEntry ("TESTAPPLICATION", "code", "112");

3.6.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. 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 session ID.

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

   }

}

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

   } 

}

3.8.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. For 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;

}

3.8.1.2 setSessionId()

You can use the setSessionId method for adding a session ID 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 session ID to the passed URLConnection object and then returns the URLConnection object. For 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(); 

}

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

public void showHelp() 

{

   String relativeDocUrl = "Help/HelpIndex.html";

   proxy.showDocument (url, helpWin);

}

To show the document in the same browser window as your applet uses call showDocument(url) as shown below:

public void showHelp() 

{

   String relativeDocUrl = "Help/HelpIndex.html";

   proxy.showDocument (url);

}

3.9.1.1 Creating a Debug Project

To create a debug project:

1. Start JDeveloper.

2. Select File and then New Project. The Project Type (Step 1) screen appears.

   Figure 3-4 The Project Type Screen

   
   

3. Enter the project's file name in the "What is the project's filename?" field.

4. In the second section of the Project Type screen ("What type of project would you like to select?"), select the radio button for empty project.

5. Click Next. The Project Options (Step 2) screen appears. Enter the following information:

   Field	Description
   Default Package Name	Leave this field blank.
   Project Source Path	Oracle_Home\mobile\sdk\wtgsdk\src\sample1\servlets
   Output Directory	Oracle_Home\mobile\sdk\wtgsdk\root\sample1\servlets

   Figure 3-5 The Project Options Screen

   
   
   
   

   Note: orant is the Oracle Home name on Windows NT systems.

   
   

6. Click Next. The Project Information Screen (Step 3) appears.

   Figure 3-6 The Project Information Screen

   
   

7. Enter information in the following fields:

   Field	Description
   Title	Name of the project.
   Author	Name of the author.
   Copyright	Copyright date.
   Company	Company name.
   Description	A description of the project.

8. Click Next. The Finish screen appears.

9. Check the options listed in the Finish screen. Click Back, if needed. Click Finish.

3.9.1.2 Setting the Project Properties

Configure the project properties for debugging. In the JDeveloper navigator menu bar, select Project and then Project Properties to view the Properties dialog box. Configure the following:

Paths Tab

Target JDK Version:

Select 'Java version "JDK1.2.2_JDeveloper" ' as your target JDK version.

Source Root Directories:

Verify that this directory points to the root of the sources. It should be set to
Oracle_Home\mobile\sdk\wtgsdk\src\sample1\servlets.

Output Root Directory:

Set the output root directory to the directory
Oracle_Home\mobile\sdk\wtgsdk\root\sample1\servlets. The Mobile Server expects the class files to be in this directory.

Run/Debug Working Directory:

Set the run/debug directory to Oracle_Home\mobile\sdk\bin.

Libraries Tab

JDeveloper 3.1 makes it easier to manage sets of .jar files by using libraries instead of CLASSPATH settings. Create a WTGSDK library with the following .jar files and add this library to your project.

Oracle_Home\mobile\classes\consolidator.jar

Oracle_Home\mobile\classes\ojsp.jar

Oracle_Home\mobile\classes\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

Perform the following steps to create a WTGSDK library:

1. Select the Libraries tab from the Properties dialog box.

2. Click Add.

   Figure 3-9 Select a Java Library Dialog Box

   
   

3. Click New.

4. Enter WTGSDK.

5. Click "..." next to the Class Path field. The File dialog box appears.

6. Select the six .jar files noted above and then click OPEN.

7. Click OK.

Compiler Tab

Check the Include debug information box. Close the Properites dialog box by clicking OK.

3.9.1.3 Adding Files to the Project

To add the Sample1 files to your project:

1. Click the green plus sign in the JDeveloper 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\servlets, and click Open.

3. Add the file RunWebServer.java, which is located in the directory Oracle_Home\mobile\sdk, to the project.

3.9.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 Navigator window.

2. Choose Run/Debug "RunWebServer" from the menu 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 URL:

http://machine_name/

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

3.9.1.5 Troubleshooting

When you run the Mobile Server inside the Java debugger and access it using a Web browser, performance may decrease. You can improve performance by:

• Running the Web browser on a different machine.

• Using the Task Manager to set the priority of the Web browser process to "LOW" (after you start the Web browser).