Preface

This preface introduces you to the Oracle9i 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.

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 the following chapters and appendixes:

• 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 an 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 the use of stream types, and discusses Oracle datatype extensions 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 globalization 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.

Related Documents

This section lists other documentation of interest.

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

• Oracle9i 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.

• Oracle9i JPublisher User's Guide

  This book describes how to use the Oracle 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.

• Oracle9i Java Developer's Guide

  This book introduces the basic concepts of Java in Oracle9i 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.

• Oracle9i Servlet Engine Developer's Guide

  This book documents use of the Oracle9i Servlet Engine, the servlet container in Oracle9i.

• Oracle JavaServer Pages Developer's Guide and Reference

  This book covers the use of JavaServer Pages technology to embed Java code and JavaBean invocations inside HTML pages. Both standard JSP features and Oracle-specific features are described.

• Oracle9i Java Tools Reference

  This book documents Java-related tools and utilities for use with Oracle9i or in deploying applications to Oracle9i (such as the session shell and loadjava tools).

• Oracle9i Java Stored Procedures Developer's Guide

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

• Oracle9i Enterprise JavaBeans Developer's Guide and Reference

  This book describes Oracle's Enterprise JavaBeans implementation and extensions.

• Oracle9i CORBA Developer's Guide and Reference

  This book describes Oracle's CORBA implementation and extensions.

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

• Oracle9i Net Services Administrator's Guide

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

• Oracle9i Globalization Support Guide

  This book contains information about Oracle Globalization Support environment variables, character sets, and territory and locale settings. In addition, it contains an overview of common globalization issues, typical scenarios, and related 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).

• Oracle9i Application Developer's Guide - Fundamentals

  This book introduces basic design concepts and programming features in using Oracle9i and creating data-access applications.

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

  This book describes general functionality and features of "large objects" (LOBs) in Oracle9i.

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

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

• Oracle9i Supplied Java Packages Reference

  This book documents Java packages available as part of Oracle9i.

• Oracle9i Supplied PL/SQL Packages and Types Reference

  This book documents PL/SQL packages available as part of Oracle9i.

• PL/SQL User's Guide and Reference

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

• Oracle9i 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.

• Oracle9i Database Reference

  This book contains general reference information about Oracle9i.

• Oracle9i Database Error Messages

  This book contains information about error messages that can be passed by Oracle9i.

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

• Oracle9i Application Server Documentation Library

• Oracle Application Server, Release 4.0.8.2 Developer's Guide

• Oracle JDeveloper online help

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 through the following Web site:

http://www.ansi.org/

(Click on "Electronic Standards Store" and search for the above specification number.)

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>

Documentation Accessibility

Oracle's goal is to make our products, services, and supporting documentation accessible to the disabled community with good usability. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For additional information, visit the Oracle Accessibility Program Web site at:

http://www.oracle.com/accessibility/

JAWS, a Windows screen reader, may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.