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