Preface

This preface introduces you to the Oracle8i SQLJ Developer's Guide and Reference, discussing the intended audience, structure, and conventions of 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 about programming features, with chapters 3 and 4 covering the most important aspects.

Chapter 8 provides information about translator options and features.

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 for emphasis or to indicate a 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 within 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

This section lists other documentation of interest.

See the following additional documents available from the Oracle Java Platform group:

• Oracle8i Java Developer's Guide

  This book introduces the basic concepts of Java in Oracle8i and provides general information about server-side configuration and functionality. Information that pertains to the Oracle Java platform as a whole, rather than to a particular product (such as JDBC, SQLJ, or EJBs) is in this book.

• Oracle8i JPublisher User's Guide

  This book describes how to use the JPublisher utility to translate object types and other user-defined types to Java classes. If you are developing SQLJ or JDBC applications that use object types, VARRAY types, nested table types, or object reference types, then JPublisher can generate custom Java classes to map to them.

• Oracle8i JDBC Developer's Guide and Reference

  This book covers programming syntax and features of Oracle's implementation of the JDBC standard (for Java Database Connectivity). This includes an overview of the Oracle JDBC drivers, details of Oracle's implementation of JDBC 1.22 and 2.0 features, and discussion of Oracle JDBC type extensions and performance extensions.

• Oracle8i Java Stored Procedures Developer's Guide

  This book discusses Java stored procedures--programs that run directly in the Oracle8i server. With stored procedures (functions, procedures, database triggers, and SQL methods), Java developers can implement business logic at the server level, thereby improving application performance, scalability, and security.

• Oracle8i Enterprise JavaBeans and CORBA Developer's Guide

  This book describes the Oracle extensions to the Enterprise JavaBeans and CORBA specifications.

You can also refer to the following documents from the Oracle Server Technologies group.

• Net8 Administrator's Guide

  This book contains information about the Oracle8 Connection Manager and Net8 network administration in general.

• Oracle8i National Language Support Guide

  This book contains information about NLS environment variables, character sets, and territory and locale settings. In addition, it contains an overview of common NLS issues, typical scenarios, and NLS considerations for OCI and SQL programmers.

• Oracle Advanced Security Administrator's Guide

  This book describes features of the Oracle Advanced Security Option (formerly known as ANO or ASO).

• Oracle8i Application Developer's Guide - Fundamentals

  This book introduces basic design concepts and programming features in using an Oracle8i database and creating database access applications.

• Oracle8i Application Developer's Guide - Large Objects (LOBs)

  This book describes general functionality and features of database large objects (LOBs) in Oracle8i.

• Oracle8i Application Developer's Guide - Object-Relational Features

  This book contains general information about structured objects and other object-relational database features in Oracle8i.

• Oracle8i Supplied PL/SQL Packages Reference

  This book documents PL/SQL packages available as part of the Oracle8i server, some of which may be useful to call from JDBC applications.

• PL/SQL User's Guide and Reference

  PL/This book explains the concepts and features of PL/SQL, Oracle's procedural language extension to SQL.

• Oracle8i SQL Reference

  This book contains a complete description of the content and syntax of the SQL commands and features used to manage information in an Oracle database.

• Oracle8i Reference

  This book contains general reference information about the Oracle8i server.

• Oracle8i Error Messages

  This book contains information about error messages that can be passed by the Oracle8i server.

Documentation from the following Oracle groups may also be of interest.

• Oracle8i Application Server documentation

  This documentation contains information about how the Oracle8i Application Server supports JDBC.

• Oracle8i JDeveloper Suite documentation

  This documentation contains information about how the Oracle8i JDeveloper Suite supports JDBC.

For documentation of SQLJ standard features and syntax, refer to ANSI specification X3.135.10-1998:

• Information Technology - Database Languages - SQL - Part 10: Object Language Bindings (SQL/OLB)

You can obtain this from ANSI at the following Web site:

http://www.ansi.org/

---