Oracle Database JPublisher User's Guide, 10g Release 1 (10.2)

10g Release 1 (10.2)

B14188-01

Contents

List of Figures

List of Tables

Title and Copyright Information

Preface

- Intended Audience

- Documentation Accessibility

- Structure

- Related Documents

- Conventions

1 Introduction to JPublisher

- Overview of JPublisher

- JPublisher Initial Considerations

- New Features in Oracle Database 10g JPublisher

- New Features for Web Services

- Awareness of Java Environment

- Implicit SQLJ Translation

- JPublisher Usage of the SQLJ Implementation

- Overview of SQLJ Usage

- Overview of SQLJ Concepts

- Backward-Compatibility Modes Affecting SQLJ Source Files

- General Requirements for JPublisher

- Required Database Setup

- Verifying or Installing the SQLJUTL and SQLJUTL2 Packages

- Verifying or Loading the sqljutl.jar File

- Verifying or Installing the UTL_DBWS Package

- Verifying or Loading the dbwsclient.jar File

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

- Setting Up Password File for Remote SYS Login

- Situations for Reduced Requirements

- JPublisher Limitations

- What JPublisher Can Publish

- 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

- Java Output for AQs and Streams

- PL/SQL Output

- JPublisher Operation

- Overview of the Publishing Process: Generation and Use of Output

- JPublisher Command-Line Syntax

- Sample JPublisher Translation

2 Using JPublisher

- Publishing User-Defined SQL Types

- Publishing PL/SQL Packages

- Publishing Oracle Streams AQ

- Publishing a Queue as a Java Class

- Publishing a Topic as a Java Class

- Publishing a Stream as a Java Class

- Publishing Server-Side Java Classes Through Native Java Interface

- Publishing Server-Side Java Classes Through PL/SQL Wrappers

- Publishing Server-Side Java Classes to PL/SQL

- Publishing Server-Side Java Classes to Table Functions

- Publishing Web Services Client into PL/SQL

3 Data Type and Java-to-Java Type Mappings

- JPublisher Data Type Mappings

- Overview of JPublisher Data Type Mappings

- SQL and PL/SQL Mappings to Oracle and JDBC Types

- JPublisher User Type Map and Default Type Map

- JPublisher Logical Progression for Data Type Mappings

- Object Attribute Types

- REF CURSOR Types and Result Sets Mapping

- Connection in JDBC Mapping

- Support for PL/SQL Data Types

- Type Mapping Support for OPAQUE Types

- Support for OPAQUE Types

- Support for XMLTYPE

- Type Mapping Support for Scalar Index-by Tables

- Type Mapping Support Through PL/SQL Conversion Functions

- Type Mapping Support for PL/SQL RECORD and Index-By Table Types

- Sample Package for RECORD Type and Index-By Table Type Support

- Support for RECORD Types

- Support for Index-By Table Types

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

- Other Alternatives for Data Types Unsupported by JDBC

- JPublisher Styles and Style Files

- Style File Specifications and Locations

- Style File Format

- 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

4 Generated Classes and Interfaces

- 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

- Generation of SQLJ Classes

- Important Notes About Generation of SQLJ Classes

- Use of SQLJ Classes for PL/SQL Packages

- Use of SQLJ Classes for Object Types

- Connection Contexts and Instances in SQLJ Classes

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

- Generation of Non-SQLJ Classes

- 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

- 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

5 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

- Server-Side Java Invocation (Call-in)

- 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 Oracle Database 10g Release 1 and Release 2

- Changes in JPublisher Behavior Between Oracle9i Database and Oracle Database 10g

- Changes in JPublisher Behavior Between Oracle8i Database and Oracle9i Database

- JPublisher Backward-Compatibility Modes and Settings

- Explicit Generation of .sqlj Files

- Oracle9i Compatibility Mode

- Oracle8i Compatibility Mode

- Individual Settings to Force Oracle8i JPublisher Behavior

6 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

- Declaration of Server-Side Java Classes to Publish

- Declaration of Server-Side Java Classes to Publish

- Declaration of Server-Side Java Classes to Publish

- Settings for Java and PL/SQL Wrapper Generation

- Input Properties File

- Declaration of Object Types and Packages to Translate

- Declaration of SQL Statements to Translate

- Declaration of Object Types to Translate

- Connection Options

- SQLJ Connection Context Classes

- The Default datasource Option

- JDBC Driver Class for Database Connection

- Connection URL for Target Database

- User Name and Password for Database Connection

- Options for Data Type Mappings

- Mappings for Built-In Types

- Mappings for LOB Types

- Mappings for Numeric Types

- Mappings for User-Defined Types

- Mappings for All Types

- Style File for Java-to-Java Type Mappings

- Type Map Options

- Adding an Entry to the Default Type Map

- Additional Entry to the User Type Map

- Default Type Map for JPublisher

- Replacement of the JPublisher Type Map

- Java Code-Generation Options

- Method Access

- Case of Java Identifiers

- Method Filtering According to Parameter Modes

- Method Filtering According to Parameter Types

- Code Generation Adherence to the JavaBeans Specification

- Class and Interface Naming Pattern

- Generation of User Subclasses

- Generation of Package Classes and Wrapper Methods

- Omission of Schema Name from Name References

- Holder Types for Output Arguments

- Name for Generated Java Package

- Serializability of Generated Object Wrapper Classes

- Generation of toString() Method on Object Wrapper Classes

- Rename main Method

- PL/SQL Code Generation Options

- Generation of SQL types

- File Names for PL/SQL Scripts

- Generation of PL/SQL Wrapper Functions

- Package for Generated PL/SQL Code

- Package for PL/SQL Index-By Tables

- Input/Output Options

- No Compilation or Translation

- Output Directories for Generated Source and Class Files

- Java Character Encoding

- Options to Facilitate Web Services Call-Outs

- WSDL Document for Java and PL/SQL Wrapper Generation

- Web Services Endpoint

- Proxy URL for WSDL

- Superuser for Permissions to Run Client Proxies

- Option to Access SQLJ Functionality

- Settings for the SQLJ Translator

- Backward Compatibility Option

- Backward-Compatible Oracle Mapping for User-Defined Types

- Java Environment Options

- Classpath for Translation and Compilation

- Java Compiler

- Java Version

- SQLJ Migration Options

- 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: Server-Side Java Call-in

- The Source Files

- Publishing Server-Side Java Class

- The Generated Files

- Testing the Published Files

B Troubleshooting

- Error While Publishing Web Services Client

Index

List of Figures

- 1-1 Translating and Using JPublisher-Generated Code