Alternative Deployment Scenarios

Although this manual mainly discusses writing for client-side SQLJ applications, you may find it useful to run SQLJ code in the following scenarios:

• from an applet

• in the server (optionally running the SQLJ translator in the server as well)

• against an Oracle Lite database

Running SQLJ in Applets

Because the SQLJ runtime is pure Java, you can use SQLJ source code in applets as well as applications. There are, however, a few considerations, as discussed below.

For an example, see "Applet Sample".

For applet issues that apply more generally to the Oracle JDBC drivers, see the Oracle8i JDBC Developer's Guide and Reference, which includes discussion of firewalls and security issues as well.

General Development and Deployment Considerations

The following general considerations apply to the use of Oracle SQLJ applets.

• You must package all the SQLJ runtime packages with your applet:

  sqlj.runtime
  sqlj.runtime.ref
  sqlj.runtime.profile
  sqlj.runtime.profile.ref
  sqlj.runtime.error
  
  

  as well as the following if you used Oracle customization:

  oracle.sqlj.runtime
  oracle.sqlj.runtime.error
  
  

  These classes are included with your Oracle installation in the file:

  [Oracle Home]/lib/runtime11.zip
  
  

• You must specify a pure Java JDBC driver, such as the Oracle JDBC Thin driver, for your database connection.

• You must explicitly specify a connection context instance for each SQLJ executable statement in an applet. This is a requirement because you could conceivably run two SQLJ applets in a single browser and, thus, in the same JVM. (For information about connections, see "Connection Considerations".)

General End User Considerations

When end users run your SQLJ applet, classes in their CLASSPATH may conflict with classes that are downloaded with the applet.

Oracle, therefore, recommends that end users clear their CLASSPATH before running the applet.

Java Environment and the Java Plug-in

Here are some additional considerations regarding the Java environment and use of Oracle-specific features.

• SQLJ requires the runtime environment of JDK 1.1.x or higher. Users cannot run SQLJ applets in browsers employing JDK 1.0.x, such as Netscape Navigator 3.x and Microsoft Internet Explorer 3.x, without a plug-in or some other means of using JRE 1.1.x instead of the browser's default JRE.

  One option is to use a Java plug-in offered by Sun Microsystems. For information, refer to the following Web site:

  http://www.javasoft.com/products/plugin
  
  

• Some browsers, such as Netscape Navigator 4.x, do not support resource files with a .ser extension, which is the extension employed by the SQLJ serialized object files that are used for profiles. The Sun Microsystems Java plug-in, however, supports .ser files.

  Alternatively, if you do not want to use the plug-in, Oracle SQLJ offers the -ser2class option to convert .ser files to .class files during translation. See "Conversion of .ser File to .class File (-ser2class)" for more information.

• Applets using Oracle-specific features require the Oracle SQLJ runtime to work. The Oracle runtime consists of the classes in the SQLJ runtime library file under oracle.sqlj.*. The Oracle SQLJ runtime library in the runtime.zip file always requires the Java Reflection API (java.lang.reflect.*); the runtime libraries in runtime11.zip, runtime12.zip, and runtime12ee.zip must use the Reflection API only in the circumstances outlined below. Most browsers do not support the Reflection API or impose security restrictions, but Sun's Java plug-in provides support for the Reflection API.

  Note: The term "Oracle-specific features" refers both to the use of Oracle type extensions (discussed in Chapter 5, "Type Support") and the use of SQLJ features that require your application to be customized to work against an Oracle database (for example, this is true of the SET statement, discussed in Chapter 3, "Basic Language Features").

• The following SQLJ language features always require the Java Reflection API (java.lang.reflect.*), regardless of the version of the SQLJ runtime you are using:
  • the CAST statement

  • REF-CURSOR-parameters or REF-CURSOR-columns being retrieved from the database as instances of a SQLJ iterator

  • retrieval of java.sql.Ref/Struct/Blob/Clob objects

  • retrieval of SQL objects as instances of Java classes implementing the oracle.sql.CustomDatum or java.sql.SQLData interfaces

    Note: There is an exception to this if you use SQLJ in a mode that is fully compatible with ISO. That is, if you use SQLJ in an environment that complies with J2EE and you translate and run your program with the SQLJ runtime12ee.zip library, and you employ connection context type maps as specified by ISO. In this case, instances of java.sql.Ref, Struct, Blob, Clob, and SQLData are being retrieved without the use of reflection.

• Consider using the runtime11.zip library for your applets. Doing so permits you to use Oracle-specific features and Oracle-specific customization.

• If your applet does not use any Oracle-specific features, you can distribute it with a generic SQLJ runtime. To support this, do not customize the applet during translation. Set -profile=false when you translate the code. (See "Profile Customization Flag (-profile)".) You can obtain a generic SQLJ runtime by removing all classes under oracle.sqlj.* from the runtime.zip library. If you neglect to set -profile=false, then the default Oracle customizer will load Oracle-specific runtime classes. This will result in your applet requiring the Oracle runtime even though it does not use Oracle-specific features.

The preceding issues can be summarized as follows, focusing on users with Internet Explorer and Netscape browsers:

• Distribute your applet with the runtime11.zip and classes111.zip libraries. In this case, the SQLJ and JDBC versions must match. For example, to use the SQLJ 8.1.7 runtime, you must have the Oracle 8.1.7 JDBC driver.

• If you use object types, JDBC 2.0 types, REF CURSORS, or the CAST statement in your SQLJ statements, then either the browser in which you run must support JDK 1.1 and permit reflection, or you must run your applet through a browser Java plug-in.

• If your applet does not use Oracle-specific features, then you can compile it without customization (-profile=false) and distribute it with the generic SQLJ runtime subset.

  Note: For an example of a generic SQLJ applet (not using Oracle-specific features), see "Applet Sample".

Introduction to SQLJ in the Server

In addition to its use in client applications, SQLJ code can run within the target Oracle8i server in stored procedures, stored functions, triggers, Enterprise JavaBeans, or CORBA objects. Server-side access occurs through an Oracle JDBC driver that runs inside the server itself. Additionally, the Oracle8i server has an embedded SQLJ translator so that SQLJ source files for server-side use can optionally be translated directly in the server.

The two main areas to consider, which Chapter 11, "SQLJ in the Server", discusses in detail are:

• creating SQLJ code for use within the server

  Coding a SQLJ application for use within the target Oracle8i server is similar to coding for client-side use. What issues do exist are due to general JDBC characteristics, as opposed to SQLJ-specific characteristics. The main differences involve connections:

  • You have only one connection.

  • The connection is to the database in which the code is running.

  • The connection is implicit (does not have to be explicitly initialized, unlike on a client).

  • The connection cannot be closed--any attempt to close it will be ignored.

  Additionally, the JDBC server-side driver used for connections within the server does not support auto-commit mode.

  Note: There is also a server-side Thin driver for connecting to one server from code that runs in another. This case is effectively the same as using a Thin driver from a client and is coded in the same way. See "Overview of the Oracle JDBC Drivers".

• translating and loading SQLJ code for server-side use

  You can translate and compile your code either on a client or in the server. If you do this on a client, you can then load the class and resource files into the server from your client machine, either pushing them from the client using the Oracle loadjava utility or pulling them in from the server using SQL commands. (It is convenient to have them all in a single .jar file first.)

  Alternatively, you can translate and load in one step, using the embedded server-side SQLJ translator. If you load a SQLJ source file instead of class or resource files, then translation and compilation are done automatically. In general, loadjava or SQL commands can be used for class and resource files or for source files. From a user perspective .sqlj files are treated the same as .java files, with translation taking place implicitly.

  See "Loading SQLJ Source and Translating in the Server" for information about using the embedded server-side translator.

Using SQLJ with an Oracle Lite Database

You can use SQLJ on top of an Oracle Lite database. This section provides a brief overview of this functionality. For more information, refer to the Oracle Lite Java Developer's Guide.

Overview of Oracle Lite and Java Support

Oracle Lite is a lightweight database that offers flexibility and versatility that larger databases cannot. It requires only 350K to 750K of memory for full functionality, natively synchronizes with the Palm Computing platform, and can run on Windows NT (3.51 or higher), Windows 95, and Windows 98. It offers an embedded environment that requires no background or server processes.

Oracle Lite is compatible with Oracle8i, previous versions of Oracle8, and Oracle7. It provides comprehensive support for Java, including JDBC, SQLJ, and Java stored procedures. There are two alternatives for access to the Oracle Lite database from Java programs:

• native JDBC driver

  This is intended for Java applications that use the relational data model, allowing them direct communication with the object-relational database engine.

  Use the relational data model if your program has to access data that is already in SQL format, must run on top of other relational database systems, or uses very complex queries.

• Java Access Classes (JAC)

  This is intended for Java applications that use either the Java object model or the Oracle Lite object model, allowing them to access persistent information stored in the Oracle Lite database, without having to map between the object model and the relational model. Use of JAC also requires a persistent Java proxy class to model the Oracle Lite schema. This can be generated by Oracle Lite tools.

  Use the object model if you want your program to have a smaller footprint and run faster and you do not require the full capability of the SQL language.

There is interoperability between Oracle Lite JDBC and JAC, with JAC supporting all types that JDBC supports, and JDBC supporting JAC types that meet certain requirements.

Requirements to Run Java on Oracle Lite

Note the following requirements if you intend to run a Java program on top of an Oracle Lite database:

• Windows NT 3.51 or higher, Windows 95, or Windows 98

• Oracle Lite 3.0 or higher

• JDK 1.1.x or higher

• Java Runtime Environment (JRE) that supports Java Native Interface (JNI)

  The JREs supplied with JDK 1.1.x and higher, Oracle JDeveloper, and Symantec Visual Cafe support JNI.

Support for Oracle Extensions

The JDBC driver implemented with Oracle Lite versions 3.6 and prior supports standard SQL92 types only, so Oracle-specific functionality cannot be used on top of these versions. Therefore, you cannot use Oracle type extensions, such as BFILE and ROWID, and user-defined object and collection types.

Beginning with version 4.0, however, Oracle Lite will include an Oracle-specific JDBC driver and Oracle-specific SQLJ runtime classes (including the Oracle semantics-checkers and customizer), allowing use of Oracle-specific features and type extensions.

---