Contents

Title and Copyright Information

Send Us Your Comments

Preface

Intended Audience

Documentation Accessibility

Structure

Related Documents

Conventions

1 Introduction to JPublisher

Overview of JPublisher

JPublisher Initial Considerations

New JPublisher Features in Oracle Database 10g

New Features for Web Services

Awareness of Java Environment Classpath

New Features for Usage of SQLJ

JPublisher Usage of the Oracle SQLJ Implementation

Overview of SQLJ Usage

Overview of SQLJ Concepts

Backward Compatibility Modes Affecting SQLJ Source Files

JPublisher General Requirements

Required Packages and JAR Files in the Database

Verifying or Installing the UTL_DBWS Package

Verifying or Installing the SQLJUTL and SQLJUTL2 Packages

Verifying or Loading the utl_dbws_jserver.jar File

Loading JAR Files For Web Services Call-outs in Oracle9i or Oracle8i

Verifying or Loading the sqljutl.jar File

Situations for Reduced Requirements

JPublisher Limitations

What JPublisher Can Publish

Publishing SQL User-Defined Types

Publishing PL/SQL Packages

Use of Object Types Instead of Java Primitive Numbers

Wrapper Class for Procedures at the SQL Top Level

Publishing Server-Side Java Classes

Publishing SQL Queries or DML Statements

Publishing Proxy Classes and Wrappers for Web Services Call-Outs

JPublisher Mappings and Mapping Categories

JPublisher Mappings for User-Defined Types and PL/SQL Types

Representing User-Defined SQL Types Through JPublisher

Using Strongly Typed Object References for ORAData Implementations

Using PL/SQL Types Through JPublisher

JPublisher Mapping Categories

JDBC Mapping

Object JDBC Mapping

BigDecimal Mapping

Oracle Mapping

JPublisher Input and Output

Input to JPublisher

Output from JPublisher

Java Output for User-Defined Object Types

Java Output for User-Defined Collection Types

Java Output for OPAQUE Types

Java Output for PL/SQL Packages

Java Output for Server-Side Java Classes and Web Services Call-Outs

Java Output for SQL Queries or DML Statements

PL/SQL Output

JPublisher Operation

Summary of the Publishing Process: Generation and Use of Output

JPublisher Command-Line Syntax

Sample JPublisher Translation

2 Datatype and Java-to-Java Type Mappings

JPublisher Datatype Mappings

Overview of JPublisher Datatype Mappings

SQL and PL/SQL Mappings to Oracle and JDBC Types

JPublisher User Type Map and Default Type Map

JPublisher Logical Progression for Datatype Mappings

Allowed Object Attribute Types

Mapping of REF CURSOR Types and Result Sets

Data Link Support and Mapping

Support for PL/SQL Datatypes

Type Mapping Support for OPAQUE Types

General Support for OPAQUE Types

Support for XMLTYPE

Type Mapping Support for Scalar Indexed-by Tables Using JDBC OCI

Type Mapping Support Through PL/SQL Conversion Functions

Type Mapping Support for PL/SQL RECORD and Indexed-by Table Types

Sample Package for RECORD Type and Indexed-by Table Type Support

Support for RECORD Types

Support for Indexed-by Table Types

Direct Use of PL/SQL Conversion Functions Versus Use of Wrapper Functions

Other Alternatives for Datatypes Unsupported by JDBC

JPublisher Styles and Style Files

Style File Specification and Locations

Style File Formats

Style File TRANSFORMATION Section

Style File OPTIONS Section

Summary of Key Java-to-Java Type Mappings in Oracle Style Files

Use of Multiple Style Files

3 Generated Classes and Interfaces

JPublisher Treatment of Output Parameters

Passing Output Parameters in Arrays

Passing Output Parameters in JAX-RPC Holders

Passing Output Parameters in Function Returns

Translation of Overloaded Methods

JPublisher Generation of SQLJ Classes

Important Notes About Generation of SQLJ Classes

Use of SQLJ Classes That JPublisher Generates for PL/SQL Packages

Use of SQLJ Classes That JPublisher Generates for Object Types

More About Connection Contexts and Instances in SQLJ Classes

The setFrom(), setValueFrom(), and setContextFrom() Methods

JPublisher Generation of Non-SQLJ Classes

JPublisher Generation of Java Interfaces

JPublisher Subclasses

Extending JPublisher-Generated Classes

Syntax for Mapping to Alternative Classes

Format of the Class that Extends the Generated Class

JPublisher-Generated Subclasses for Java-to-Java Type Transformations

JPublisher Support for Inheritance

ORAData Object Types and Inheritance

Precautions when Combining Partially Generated Type Hierarchies

Mapping of Type Hierarchies in JPublisher-Generated Code

ORAData Reference Types and Inheritance

Casting a Reference Type Instance into Another Reference Type

Why Reference Type Inheritance Does Not Follow Object Type Inheritance

Manually Converting Between Reference Types

Example: Manually Converting Between Reference Types

SQLData Object Types and Inheritance

Effects of Using SQL FINAL, NOT FINAL, NOT INSTANTIABLE

4 Additional Features and Considerations

Summary of JPublisher Support for Web Services

Summary of Support for Web Services Call-Ins to the Database

Support for Web Services Call-Outs from the Database

Features to Filter JPublisher Output

Publishing a Specified Subset of Functions or Procedures

Publishing Functions or Procedures According to Parameter Modes or Types

Ensuring that Generated Methods Adhere to the JavaBeans Specification

Backward Compatibility and Migration

JPublisher Backward Compatibility

Changes in JPublisher Behavior Between Oracle9i and Oracle Database 10g

Changes in JPublisher Behavior Between Oracle8i and Oracle9i

JPublisher Backward Compatibility Modes and Settings

Explicit Generation of .sqlj Files

Oracle9i Compatibility Mode

Oracle8i Compatibility Mode

Individual Settings to Force Oracle8i JPublisher Behavior

5 Command-Line Options and Input Files

JPublisher Options

JPublisher Option Summary

JPublisher Option Tips

Notational Conventions

Options for Input Files and Items to Publish

File Containing Names of Objects and Packages to Translate (-input)

Declaration of Server-Side Java Classes to Translate (-java)

Input Properties File (-props)

Declaration of Object Types and Packages to Translate (-sql)

Declaration of SQL Statements to Translate (-sqlstatement)

Declaration of Object Types to Translate (-types)

Connection Options

SQLJ Connection Context Classes (-context)

JDBC Driver Class for Database Connection (-driver)

Connection URL for Target Database (-url)

User Name and Password for Database Connection (-user)

Options for Datatype Mappings

Mappings For Built-In Types (-builtintypes)

Mappings For LOB Types (-lobtypes)

Mappings For Numeric Types (-numbertypes)

Mappings for User-Defined Types (-usertypes)

Mappings for All Types (-mapping)

Style File for Java-to-Java Type Mappings (-style)

Options for Type Maps

Additional Entry to the Default Type Map (-adddefaulttypemap)

Additional Entry to the User Type Map (-addtypemap)

Default Type Map for JPublisher (-defaulttypemap)

Replacement of the JPublisher Type Map (-typemap)

Java Code Generation Options

Method Access (-access)

Case of Java Identifiers (-case)

Method Filtering According to Parameter Modes (-filtermodes)

Method Filtering According to Parameter Types (-filtertypes)

Code Generation Adherence to the JavaBeans Specification (-generatebean)

Class and Interface Naming Pattern (-genpattern)

Generation of User Subclasses (-gensubclass)

Generation of Package Classes and Wrapper Methods (-methods)

Omission of Schema Name from Name References (-omit_schema_names)

Holder Types for Output Arguments (-outarguments)

Name for Generated Java Package (-package)

Serializability of Generated Object Wrapper Classes (-serializable)

Generation of toString() Method on Object Wrapper Classes (-tostring)

PL/SQL Code Generation Options

File Names for PL/SQL Scripts (-plsqlfile)

Generation of PL/SQL Wrapper Functions (-plsqlmap)

Package for Generated PL/SQL Code (-plsqlpackage)

Input/Output Options

No Compilation or Translation (-compile)

Output Directories for Generated Source and Class Files (-dir and -d)

Java Character Encoding (-encoding)

Options to Facilitate Web Services Call-Outs

Mechanisms Used in Exposing Java to PL/SQL

Classes for Java and PL/SQL Wrapper Generation (-proxyclasses)

Settings for Java and PL/SQL Wrapper Generation (-proxyopts)

WSDL Document for Java and PL/SQL Wrapper Generation (-proxywsdl)

Web Services Endpoint (-endpoint)

Proxy URL for WSDL (-httpproxy)

Superuser for Permissions to Run Client Proxies (-sysuser)

Option to Access SQLJ Functionality

Settings for the SQLJ Translator (-sqlj)

Backward Compatibility Option

Backward-Compatible Oracle Mapping for User-Defined Types (-compatible)

Java Environment Options

Classpath for Translation and Compilation (-classpath)

Java Compiler (-compiler-executable)

Java Version (-vm)

Code Generation for Wrapper Class and PL/SQL Wrapper Options

Wrapper Class Generation without Handles

Wrapper Class Generation with Handles

Code Generation for Method Parameters

Code Generation for Table Functions

JPublisher Input Files

Properties File Structure and Syntax

INPUT File Structure and Syntax

Understanding the Translation Statement

Sample Translation Statement

INPUT File Precautions

Requesting the Same Java Class Name for Different Object Types

Requesting the Same Attribute Name for Different Object Attributes

Specifying Nonexistent Attributes

JPublisher Reserved Terms

A Generated Code Examples

Generated Code: User Subclass for Java-to-Java Transformations

Interface Code

Base Class Code

User Subclass Code

Generated Code: SQL Statement

Generated Code: Java and PL/SQL Wrappers for Web Services

WSDL Document

JAX-RPC Client Proxy Classes and Interfaces

Java Wrapper Class and PL/SQL Wrapper

Additional PL/SQL Utility Scripts

Generated Code: Java and PL/SQL Wrappers for General Use

Classes to Be Wrapped

Java and PL/SQL Wrappers for Static Methods

Java and PL/SQL Wrappers for Instance Methods Using the Handle Mechanism

Index