| Oracle® Database Lite Developer's Guide Release 10.3 Part Number E12090-02 |
|
|
View PDF |
| Oracle® Database Lite Developer's Guide Release 10.3 Part Number E12090-02 |
|
|
View PDF |
The following sections discuss how to develop applications for Oracle Database Lite:
Section 5.2, "Supported Native APIs for Oracle Database Lite"
Section 5.4, "Using Stored Procedures in Oracle Database Lite"
Table 5-1 lists the supported APIs for accessing data within the Oracle Lite database:
Table 5-1 Supported APIs
| Native API | Description |
|---|---|
|
JDBC |
Use JDBC to access the Oracle Lite database. See Section 5.1.2, "JDBC" or Oracle Database JDBC manuals for more information. |
|
ODBC |
Use ODBC to access the Oracle Lite database. See Section 5.1.3, "ODBC". |
|
.NET environment |
Use the ADO.NET API. You can use Oracle-specific APIs for connecting to the database, programmatic synchronization, and other functions. See Section 5.1.4, "ADO.NET" for more information. |
|
SODA |
Simple Object Data Access (SODA) for object and relational database development. See Chapter 12, "Using Simple Object Data Access (SODA)" in the Oracle Database Lite Client Guide for more information. |
|
Visual Basic |
Use ODBC to access database. |
|
.NET environment |
Use the ADO.NET API. You can use Oracle-specific APIs for connecting to the database, programmatic synchronization, and other functions. See Section 5.1.4, "ADO.NET" for more information. |
These data access APIs are described in Chapter 5, "Oracle Database Lite Data Access APIs"" in the Oracle Database Lite Client Guide. The focus in the client guide is for accessing the Oracle Lite database on the client without the Mobile Server synchronization feature. However, if you are using the Mobile Server product and providing synchronization, then the following sections describe the differences to take into account for these APIs in the Mobile Server environment.
Note:
After you perform a complete installation of Oracle Database Lite, you can view samples that show how to access data within the Oracle Lite database. The samples are available in your <
ORACLE_HOME>\Mobile\Sdk directory. The tools, locations for samples, and descriptions are described in Section 2.5, "Using Oracle Lite Samples" in the Oracle Database Lite Client Guide. .When you create a data source name using the ODBC Manager, you should use the following conventions:
In Windows 32, the data source name is automatically created as <username_dbname> after the first synchronization, where both the username and database name are taken from within the publication.
In Windows CE, the data source name is simply the database name; that is, <dbname>.
It is helpful to create a data source name to contain all of the properties of your connection to the database.
For Mobile clients within the Mobile Server environment, all JDBC drivers are provided for you to use within the Oracle Database Lite binaries. See Chapter 7, "JDBC Programming" in the Oracle Database Lite Client Guide for more information on programming with JDBC.
The Mobile Server supports Level 3 compliant ODBC 2.0 and the ODBC 3.5 drivers. The ODBC 2.0 driver is installed and used by default for all Oracle Database Lite components. The ODBC 3.5 driver should be used solely for the standalone application that uses an embedded Oracle Lite database.
Note:
You cannot use ODBC 3.5 for any multi-user listener application or Branch Office scenario.If you want to use the ODBC 3.5 driver for an embedded application on a Mobile client, you must install and configure the ODBC 3.5 driver on the client in one of the following methods:
Automatic installation: Configure the INF file for automatic installation and configuration: Modify the INF file to instruct the client install to automatically download the ODBC 3.5 DLLs to the Mobile client and register the ODBC 3.5 driver and the DSN in the ODBC.INI file. See the following sections on how to modify the INF file: Section 8.10.5.2, "FILE Section" and Section 8.10.5.5, "ODBC Section" in the Oracle Database Lite Administration and Deployment Guide.
Manual installation: See Chapter 6, "ODBC Drivers" in the Oracle Database Lite Client Guide on how to install and configure the ODBC 3.5 DLL from the MDK to the Mobile client.
For a full description of the ODBC drivers, see Chapter 6, "ODBC Drivers" in the Oracle Database Lite Client Guide.
The Oracle Database Lite ADO.NET provider resides in the Oracle.DataAccess.Lite namespace. Use this programming interface to access Oracle Database Lite and trigger data synchronization in .NET applications. The ADO.Net classes are described in Chapter 11, "Oracle Database Lite ADO.Net Provider" in the Oracle Database Lite Client Guide. However, since the Oracle Database Lite Client Guide describes only the Oracle Lite client, it does not include any details on how to enable the client as a Mobile client with synchronization. The following sections describe the ADO.Net classes that enable synchronization and create a client database for testing:
Section 5.1.4.1, "Data Synchronization With the OracleSync or Oracle Engine Classes"
Section 5.1.4.3, "Developing an ADO.NET Application on WinCE"
You can perform a synchronization programatically with the OracleSync or OracleEngine classes. For full details, see Section 4.4, "Synchronization API for C#".
In a non-production environment, you may want to create a database to test your ADO.NET application against. In the production environment, the database is created when you perform the OracleEngine.Synchronize method (see Section 4.4.2, "Using the OracleEngine to Synchronize" for more information). However, to just create the database without synchronization, you can use the CreateDatabase method of the OracleEngine class. To remove the database after testing is complete, use the RemoveDatabase method. These methods are only supported when you install the Mobile Development Kit (MDK).
The following is the signature of the CreateDatabase method:
OracleEngine.CreateDatabase (string dsn, string db, string pwd)
For an example of how to develop an ADO.NET application, see Chapter 14, "Tutorial for Building Mobile Applications for Windows CE".
The C, C++, C# APIs use ODBC to access the Oracle Lite database. Use Oracle-specific APIs for programmatic synchronization. See Section 4.1, "Synchronization APIs For C or C++ Applications" for more information.
The following sections describe how to develop and test Java applications:
Table 5-2 lists the Java support provided for each platform in Oracle Database Lite.
Table 5-2 Java Support
| Category | Web-to-Go (both Windows and Linux) | Windows 32 Native | Windows CE | Linux Native | For More Information... |
|---|---|---|---|---|---|
|
JDBC |
Yes Oracle Database Lite offer three JDBC drivers. Refer to Section 5.3.1.1, "JDBC Drivers". |
Yes |
Yes |
Yes On Linux, only JDBC and ODBC access is supported. |
Chapter 7, "JDBC Programming" in the Oracle Database Lite Client Guide |
|
Java Stored Procedures /Triggers |
Yes Java Stored Procedures/Triggers are not supported in the Web-to-Go application model. However Java Stored Procedures can be replicated using the Consolidator Manager API. |
Yes |
N/A |
Yes |
See Chapter 10, "Using Stored Procedures and Triggers" in the Oracle Database Lite Client Guide |
|
Java Server Pages |
1.1 |
N/A |
N/A |
N/A |
|
|
Java Servlet |
2.2 |
N/A |
N/A |
N/A |
Section 5.5.2.5, "Developing Java Servlets for Web-to-Go" and Section 5.5.2.8, "Developing Applet Servlet Communication" |
|
BC4J |
Yes Latest version of Oracle JDeveloper 10g. |
N/A |
N/A |
N/A |
|
|
Struts |
Yes |
N/A |
N/A |
N/A |
For programmatically synchronizing from a Java application, see Chapter 2, "Synchronization".
The Oracle Database Lite JDBC driver is JDBC 1.2 compliant. Oracle Lite provides a limited number of extensions specified by JDBC 2.0. These extensions are compatible with the Oracle Database JDBC implementation.
Oracle Database Lite offers the following JDBC drivers:
Type 2 driver: There are two types of type 2 driver: one provides an embedded, direct connnection. This driver allows Java applications to communicate directly with the Oracle Lite database. The other type 2 driver provides a remote connection and requires Multi-User service support.
Type 4 driver : 100% Java implementation. Requires the multi-user database version.
To develop Java applications, you need to set up your development environment to create Oracle Database Lite applications, as follows:
You must have the Sun Microsystems Java Development Kit (JDK), version 1.4.2 (or higher).
To enable Oracle Database Lite to work with the JDK, set your PATH and CLASSPATH environment variables after you install Oracle Database Lite. See Section 5.3.2.1, "Setting Variables for the JDK" for full details.
Note:
If your environment includes aCLASSPATH user variable before you install Oracle Database Lite and the user variable does not include the CLASSPATH system variable (is not specified as CLASSPATH=...;%CLASSPATH%), then you must modify the CLASSPATH user variable to include the olite40.jar file in the OLITE_HOME\bin directory.Note:
All command prompt windows must be closed and reopened to reflect changes made to yourCLASSPATH.The directory with the JDK 1.4.2 or 5.0 Java compiler (javac.exe) should be in the PATH variable before any other directories that contain other Java compilers.
Add the directory that contains the Classic Java Virtual Machine (JVM) shared library, jvm.dll, to the PATH. jvm.dll should be in your JDK_Home\jre\bin\classic directory.
For example,
set PATH=C:\JDK_Home\bin;c:\JDK_Home\jre\bin\classic set CLASSPATH=c:\JDK_Home\jrc\lib\rt.jar;c:\OLITE_HOME\bin\olite40.jar
As an alternative to using the Classic JVM, you can use the HotSpot JVM. HotSpot is a JDK add on module provided by Sun Microsystems. HotSpot is available from the Sun Microsystems Web site.
After installing HotSpot, set your PATH as given below.
set PATH=c:\jdk\bin;c:\jdk\jre\bin\hotspot;%PATH%
In the example above, your installation of the JDK and HotSpot is on Drive C:\. Verify the location of your installation before amending your PATH statement. To test whether your system is set up correctly, run the Java examples in the <ORACLE_HOME>\Mobile\Sdk\Samples\JDBC directory.
A stored procedure is a method that is stored in Oracle Database Lite. The procedure can be invoked by applications that access the database. Stored procedures can return a single value, a row, or multiple rows.
A trigger is a stored procedure that executes when a specific event occurs, such as a row update, insertion, or deletion. An update of a specific column can also fire a trigger. Triggers, however, cannot return a value. A trigger can operate at the statement-level or row-level.
The description of how to create, load and define stored procedures for the Mobile client are contained in Chapter 10, "Using Stored Procedures and Triggers" in the Oracle Database Lite Client Guide. However, if you are using the Mobile Server, then there are a few instructions on how to load and define stored procedures when using the Mobile Server.
The following sections describe how to load and define stored procedures in a Mobile Server environment.
You can either use Java stored procedures in a standalone Oracle Lite database or integrated within an enterprise Mobile system that uses synchronization. Each of these require a different method to load and define the Java stored procedure, as described in the following sections:
Section 5.4.1.2, "Load and Define Java Stored Procedures in an Enterprise Mobile Server Environment"
The methods for loading and defining the Java stored procedures are described in Section 10.2.1, "Load and Define Java Stored Procedures" in the Oracle Database Lite Client Guide.
When you are in an enterprise environment where you are using the Mobile option including synchronization between the Mobile Server and the Mobile clients, then you can have the Java stored procedure automatically downloaded to each client and loaded into the client Oracle Lite database.
You can load and define the Java stored procedure in an enterprise Mobile environment in one of following ways:
When you are creating the publication using MDW, part of the process is a section to load the Java stored procedure, as detailed below:
Archive the Java stored procedure into a JAR file. You cannot upload the CLASS file to MDW.
Upload the JAR file as a Resource for the publication within MDW. Once loaded as a Resource, then it will be loaded into the Oracle Lite database on the client on the first synchronization.
Create a SQL script with DDL that uses one of the definition methods on the Java stored procedure: ATTACH, CREATE METHOD, CREATE PROCEDURE or CREATE TRIGGER. Once created, add the script to the publication as a Script. The script is automatically executed after download to the client.
Note:
You can also perform these functions through the Consolidator Manager API. See the Oracle Database Lite API Specification documentation for more information.On the server, you can invoke the following ConsolidatorManager APIs to create the Java stored procedure and to add it to the publication.
Invoke the createStoredProc API to load and define the Java stored procedure in the server. Provide the name of the Java class and the method that you want defined.
The Consolidator loads the Java stored procedure into the repository and creates the call specification for defining the method on the client within the repository.
Note:
You cannot use the attach for definition; this method creates the call specification only withCREATE FUNCTION or CREATE PROCEDURE.Invoke the addJavaResourceAndScripts API to add the Java stored procedure to the publication.
When the client first synchronizes, the application and Java stored procedure contained within the publication are downloaded onto the client. The Java stored procedure is then loaded into the Oracle Lite database and the call specification is used to define the method within the Java stored procedure.
Once you create the C, C++ and C# stored procedures, you still need to load and define them on the client Oracle Lite database. This section describes how to perform this manually for a standalone client Oracle Lite database or how you can implement a solution for automatically loading and defining these stored procedures to multiple clients.
Section 5.4.2.1, "Defining the C, C++, or C# Stored Procedure"
Section 5.4.2.2, "Loading the C, C++ or C# Stored Procedure to the Oracle Lite Database"
For details on how to define the C, C++, or C# stored procedure, see Section 10.10, "Defining the C, C++, or C# Stored Procedures" in the Oracle Database Lite Client Guide.
When you have a standalone client, then you can load the stored procedure by copying it directly to the client. Define the stored procedure by executing the CREATE statements on the Mobile device directly, as described in Section 5.4.2.1, "Defining the C, C++, or C# Stored Procedure".
However, if you are using the Mobile Server and have multiple clients on which you want to install and use these stored procedures, then you may want to automate the load and definition process for these stored procedures.
Use one of the following methods to download the DLL containing the stored procedures and to define the stored procedures:
Option 1: Extend the Client Platform and Use Scripts
To download the DLL, extend the client platform and adding the required DLL. When the users download the setup.exe for your extended platform, then the DLL is automatically downloaded and installed. When you use this option, then you should install the DLL in the same directory as the msync.exe and ocapi.dll files on the client.
Create a script that issues the CREATE commands, as defined in Section 5.4.2.1, "Defining the C, C++, or C# Stored Procedure", that defines the stored procedures or triggers. Once you create the SQL script, then you can load the script into the publication using either the Add Script function within MDW or the Consolidator APIs. Once added to the publication, then the synchronization downloads the script with the application and it is executed upon completion of the download. In this case, the DLL containing the stored procedures must already be loaded onto the device before the script is executed. When loading the DLL, ensure that it is within the PATH or for C#, within the Global Assembly Cache.
Option 2: Issue the Definition From Within Your Application
Package the DLL containing the stored procedures with the other application files. Then, when you load the package, the DLL is loaded when the application is loaded.
Implement the application to issue the definition CREATE statements within an initialization routine that is executed the first time the application runs.
This option is simpler than extending an existing platform, because the DLL can be part of the application itself.
The following sections describe how to develop and test Web-to-Go applications:
To install and set up the Mobile Client, see Section 11.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.
Web-to-Go provides a Java API for 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 enables developers to develop and debug Web-to-Go applications that contain Java applets, Java servlets, and JavaServer Pages (JSP).
Figure 5-1 displays the development architecture of the Mobile Server and the Oracle database.
The following sections provide a discussion on how to develop Mobile applications for Web-to-Go. Topics include:
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 5-3 provides examples of each database component type.
Table 5-3 Database Component Types
| Component Type | Example |
|---|---|
|
Static Component |
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). |
|
Dynamic Component |
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. |
|
Database Component |
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 Win32 and WinCE platforms. |
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.
It is common for applications to behave differently depending on the type of user executing the application. For example, an application may display 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 of 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.
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.
Web-to-Go handles HTTP requests for Java Server Pages (JSP) using the Mobile Client Web Server, Mobile Server, and Mobile Client for Web-to-Go, as described in the following sections:
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.
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.
The following sections describe how to develop a Java Servlet for Web-to-Go:
Section 5.5.2.5.1, "Using Mobile Development Kit for Web-to-Go for Development"
Section 5.5.2.5.3, "Obtaining Database Connectivity from a Servlet"
Section 5.5.2.5.4, "Web-to-Go User Context for Authentication"
Section 5.5.2.5.5, "Web-to-Go Servlet Uses Applet Package When Communicating With an Applet"
Section 5.5.2.5.6, "Accessing the Mobile Server Repository from a Servlet"
Section 5.5.2.5.7, "Debugging the Servlet Using WTGDEBUG.EXE"
Develop Web-to-Go Java servlets with the Mobile Development Kit, which simplifies the process of writing Mobile Server servlets. Before using the Mobile Development Kit for Web-to-Go, 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.
The Mobile Development Kit for Web-to-Go Web server is a scaled down version of the Mobile Server and has the following limitations.
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.
Provides connection management only to Oracle Database Lite. It connects the user to the schema SYSTEM in the Oracle Database Lite named webtogo.
You can access applications on the Mobile Development Kit for Web-to-Go Web server by performing the following steps.
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
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
Click the icon of the application that you want to access.
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();
}
}
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.
HttpSession sess = request.getSession();
WTGUser user = (WTGUser)sess.getAttribute("x-mobileserver-user");
Connection conn = user.getConnection();
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
On the command-line on the client, you can connect to the Oracle Lite database locally outside the realm of the application with the mSQL command, as follows:
msql system/manager@jdbc:polite:webtogo
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");
...
}
The oracle.lite.web.applet package provided by Web-to-Go 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.
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 method 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();
...
}
Perform the following to debug your application with the wtgdebug executable:
Using the Command Prompt, enter wtgdebug.exe.
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.
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.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.
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.
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.
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.
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();
}}
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.
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;
}
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.
You can close the connection by calling the following statement.
dBConnection.close()
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:
ThegetResultObject 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.When creating a servlet, it 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();
} }
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;
}
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();
}
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);
}
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 JDeveloper, Borland's JBuilder, or Visual J++. The example in this section assumes you are using JDeveloper. However, most of the information provided is also relevant to other debuggers.
The following sections describe how to configure 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 JDeveloper, consult the online help in JDeveloper and the JDeveloper documentation.
To create a new debug project in Oracle9i JDeveloper, perform the following steps.
Start JDeveloper.
To create a new project in JDeveloper, click File, then click New (assuming you have defined a workspace in JDeveloper).
From the Directories menu in the left panel, select Projects, as displayed in Figure 5-2, then select Empty Project.
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 5-3.
<ORACLE_HOME>\mobile\sdk\wtgsdk\src\sample1\servlets
Leave the Default Package field blank. Do not change the default HTML Root Directory.
Figure 5-3 Project Settings - Input Paths
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
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.
Select Libraries in the left panel, then click New in the right panel.
The New Library dialog appears, as illustrated in Figure 5-4. In the Library Name field, enter WTGSDK.
Click Edit... next to the Class Path field. The File dialog appears.
From the appropriate directory, select the six .jar files that are listed above.
To add the files, click OK.
To add the Sample1 files to your project, perform the following steps.
Click the green plus-sign in the Oracle9i JDeveloper System-Navigator to add the Java sources to the project. The File dialog appears.
Select the Java source file Helloworld.java in the directory <ORACLE_HOME>\mobile\sdk\wtgsdk\src\sample1\servlets, and click Open.
Also, add the file RunWebServer.java, which is located in the directory <ORACLE_HOME>\mobile\sdk\wtgsdk\src, to the project.
A dialog appears prompting you to update the project source path. Click No.
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.
Select the file RunWebServer.java in the System-Navigator window.
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.
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.
Run the Web browser on a different machine.
Using the Task Manager, set the priority of the Web browser process to LOW after you start the Web browser.
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
Develop the customized Web-to-Go workspace application using the Web-to-Go APIs.
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.
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 5.5.2.10.1, "Web-to-Go Parameters".
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.
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 5.5.2.10.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 5-4 describes webtogo.ora parameter settings.
Table 5-4 Setting webtogo.ora Parameters
| Parameter | Setting |
|---|---|
|
|
YES |
|
|
Repository directory of the Web-to-Go workspace application. For example, |
|
|
The entry point of the Web-to-Go workspace application. For example, |
|
|
The name of the servlet that you want to use in your customized workspace. For example, |
Note:
Web-to-Go supports only one workspace application per Mobile Server.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 5-5 describes scripts available for JSP compilation.
Table 5-5 Scripts for JSP Compilation
| Script Name | Description |
|---|---|
|
|
Compiles |
|
|
Copies all files in the |
|
|
Copies all files in the |
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.
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 MDW. For more information, see Chapter 6, "Using Mobile Database Workbench to Create Publications".
|
 Copyright © 1997, 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|