Preface

This preface introduces you to the Oracle8i SQLJ Developer's Guide and Reference, discussing the intended audience, structure, and conventions for this document. A list of related Oracle documents is also provided.

Intended Audience

This manual is intended for anyone with an interest in SQLJ programming but assumes at least some prior knowledge of the following:

• Java

• SQL

• Oracle PL/SQL

• JDBC

• Oracle databases

Although general knowledge of SQL and JDBC is sufficient, any knowledge of Oracle-specific SQL and JDBC features would be helpful as well.

See "Related Documents" below for the names of Oracle documents that discuss SQL and JDBC.

Document Structure

The two major aspects of using SQLJ are:

• creating your SQLJ source code

• running the SQLJ translator

Chapters 3 through 7 provide information you must have to create your code, with chapters 3 and 4 covering the most important aspects.

Chapter 8 provides information you must have to run the translator.

In all, this document consists of twelve chapters and two appendixes, as follows:

Chapter 1	"Overview"--Introduces SQLJ concepts, components, and processes. Discusses possible alternative deployment or development scenarios.
Chapter 2	"Getting Started"--Guides you through the steps of testing and verifying the installation of the Oracle database, Oracle JDBC drivers, and Oracle SQLJ.
Chapter 3	"Basic Language Features"--Discusses SQLJ programming features you must have for basic applications. Focuses largely on standard SQLJ constructs, as opposed to Oracle extended functionality.
Chapter 4	"Key Programming Considerations"--Discusses key issues to consider as you write your source code, such as connections, null-handling, and exception-handling.
Chapter 5	"Type Support"--Lists Java types that Oracle SQLJ supports, discusses use of stream types, and discusses Oracle type extensions in the database and the Java types that correspond to them.
Chapter 6	"Objects and Collections"--Discusses Oracle SQLJ support of user-defined object and collection types, including use of the Oracle JPublisher utility to generate corresponding Java types.
Chapter 7	"Advanced Language Features"--Discusses additional SQLJ programming features you may need for more advanced applications.
Chapter 8	"Translator Command Line and Options"--Documents command-line syntax, properties files, and options for the Oracle SQLJ translator.
Chapter 9	"Translator and Runtime Functionality"--Discusses the functionality of translator operations, translator and runtime error messages, and NLS support.
Chapter 10	"Profiles and Customization"--Describes SQLJ profiles (used in implementing SQL operations); documents options you can specify during translation regarding the customization of your profiles for particular environments.
Chapter 11	"SQLJ in the Server"--Discusses how to create and load SQLJ applications to run in the server, typically as stored procedures or functions. This includes optional use of the server-side embedded translator.
Chapter 12	"Sample Applications"--Contains source code for a range of fully functional SQLJ sample applications. Oracle provides these applications in the demo directory on the product CD.
Appendix A	"Performance and Debugging"--Briefly discusses performance tuning and refers to other useful documentation; discusses debugging scenarios, focusing on the AuditorInstaller utility that is provided with Oracle SQLJ.
Appendix B	"SQLJ Error Messages"--Lists Oracle SQLJ translator and runtime error messages, their causes, and what actions you should take in response.

Document Conventions

This document uses UNIX syntax for file paths (for example: /myroot/myfile.html). If you are using some other kind of operating system, then substitute the appropriate syntax.

This document uses [Oracle Home] to indicate your Oracle home directory.

In addition, this document uses the following conventions:

Convention	Meaning
italicized regular text	Italicized regular text is used either for emphasis or to indicate a special term that is being defined or will be defined shortly.
. . .	Horizontal ellipsis points in sample code indicate the omission of a statement or statements or part of a statement. This is done when you would normally expect additional statements or code to appear, but such statements or code would not be related to the example.
code text	Code text in the midst of regular text indicates class names, object names, method names, variable names, Java types, Oracle datatypes, file names, and directory names.
italicized_code_text	Italicized code text in a program statement indicates something that must be provided by the user.
<italicized_code_text >	Angle brackets enclosing italicized code text in a program statement indicates something that can optionally be provided by the user.

In this document, it was not feasible to use more standard conventions, such as square brackets [] to enclose optional items to be provided, because of the particulars of SQLJ coding syntax.

For example, in the following statement the square brackets and curly brackets are part of SQLJ coding syntax, but the angle brackets indicate that connctxt_exp, execctxt_exp, and results_exp are optional entries. You must provide a SQL operation, however.

#sql <[<connctxt_exp><,><execctxt_exp>]> <results_exp> = { SQL operation };

And in the following SQLJ command line option (-user), the angle brackets indicate that conn_context_class and the password (with preceding slash) are optional entries. You must provide a username, however.

-user<@conn_context_class>=username</password>

Related Documents

For information about Java-related aspects of Oracle8i, see the following Oracle documents from the Java Products documentation group:

• Oracle8i Java Developer's Guide (overview and configuration information)

• Oracle8i JDBC Developer's Guide and Reference

• Oracle8i JPublisher User's Guide (relevant to support for objects and collections)

• Oracle8i Java Stored Procedures Developer's Guide

• Oracle8i Enterprise JavaBeans and CORBA Developer's Guide

The Java Developer's Guide and JPublisher User's Guide are not included on the release 8.1.5 documentation CD.

Also, the following Oracle documents from the Server Technology group may be useful and are sometimes referenced in this document:

• Oracle8i SQL Reference

• Oracle8i Application Developer's Guide--Fundamentals

• Oracle8i Supplied Packages Reference

• Net8 Administrator's Guide

• PL/SQL User's Guide and Reference

For documentation of SQLJ standard features and syntax, refer to the ANSI SQL/OLB standard X3.135.10-1998. You can access this at the following Web site:

http://www.sqlj.org/

---