Oracle8i JPublisher User's Guide Release 2 (8.1.6) Part Number A81357-01 |
Library | Service | Contents | Index

## Using SQLJ Classes JPublisher Generates

When `-methods=true`, JPublisher generates `.sqlj` classes for object types and PL/SQL packages. The classes includes wrapper methods that invoke the server methods of the object types and packages. Run SQLJ to translate the `.sqlj` file.

This section describes how to use these generated classes in your SQLJ code.

### Using SQLJ Classes JPublisher Generates for PL/SQL Packages

To use a class that JPublisher generates for a PL/SQL package:

- Construct an instance of the class.

- Call the class's wrapper methods.

The constructors for the class associate a connection with the class. One constructor takes a `ConnectionContext`, one constructor takes a `Connection`, and one constructor has no arguments. Calling the no-argument constructor is equivalent to passing the `DefaultContext` to the constructor that takes a `ConnectionContext`. We supply the constructor that takes a `Connection,` for the convenience of the JDBC programmer who knows how to compile a SQLJ program, but is unfamiliar with SQLJ concepts such as `ConnectionContext`.

The wrapper methods are all instance methods, because the `ConnectionContext` in the `this` object is used in `#sql` statements in the wrapper methods.

Because a class generated for a PL/SQL package has no instance data other than the connection context, you will typically construct one class instance for each connection context you use. If the default context is the only one you use, call the no-argument constructor once. The Oracle8i SQLJ Developer's Guide and Reference discusses reasons for using more than one connection context.

An instance of a class generated for a PL/SQL package does not contain copies of PL/SQL package variables. It is not a `CustomDatum` class or a `SQLData` class, and you cannot use it as a host variable.

"Example: Using Classes Generated for Packages" shows how to use a class generated for a PL/SQL package.

### Using Classes JPublisher Generates for Object Types

To use an object of a class JPublisher generates for an object type, you must first initialize the object.

To initialize your object, you can:

- Assign an already initialized object to your object.

- Retrieve a copy of a database object into your object. To do this, you can:

  - Use the object as an `OUT` argument or as the function call result of a JPublisher-generated wrapper method.

  - Retrieve the object through `#sql` statements you write.

  - Retrieve the object through JDBC calls you write.

- Construct the object and set its attributes using the `set` methods.

  The constructors for the class associate a connection with the class. One constructor takes a `ConnectionContext`, one constructor takes a `Connection`, and one constructor has no arguments. Calling the no-argument constructor is equivalent to passing the `DefaultContext` to the constructor that takes a `ConnectionContext`. We provide the constructor that takes a `Connection` for the convenience of the JDBC programmer who knows how to compile a SQLJ program, but is unfamiliar with SQLJ concepts such as `ConnectionContext`.

Once you have initialized your object, you can:

- Call the object's accessor methods.

- Call the object's wrapper methods.

- Pass the object to other wrapper methods.

- Use the object as a host variable in your own `#sql` statements.

- Use the object as a host variable in your own JDBC calls.

Logically speaking, there is a Java attribute for each attribute of the corresponding database object type. The object has `get` and `set` accessor methods for each attribute. The accessor method names are of the form `getFoo()` and `setFoo()` for attribute `foo.` JPublisher does not generate fields for the attributes.``

By default, the class includes wrapper methods that invoke the associated Oracle object methods executing in the server. The wrapper methods are all instance methods, regardless of whether the server methods are. The `ConnectionContext` in the `this` object is used in `#sql` statements in the wrapper methods.

The following methods that JPublisher generates for the use of Oracle's JDBC drivers, are not intended for your use:

- `getFactory()`

- `create()`

- `toDatum()`

The `getFactory()`, `create()`, and `toDatum()` methods help implement the `CustomDatum` and `CustomDatumFactory` interfaces, which the Oracle JDBC drivers use and Oracle SQLJ requires.

The `RationalO` example, described in "Example: Using Classes Generated for Object Types", shows how to use a class that was generated for an object type and has wrapper methods.

### General Comments about SQLJ Code JPublisher Generates

Every `.sqlj` class JPublisher generates for an object type or package has its own connection context class and its own connection context instance, declared within the class as:

    #sql context _Ctx;
    _Ctx ctx;

Having different connection context classes in different generated classes gives you the option of checking different classes against different example schemas during SQLJ on-line semantics checking.

Having different connection context instances in different objects guarantees that your objects can be used in different Java threads without explicit synchronization.

Your SQLJ code can use `.java` classes generated by JPublisher for `REF`, `varray`, and nested table types, and for object types generated by JPublisher when `-methods=false`. Having no embedded `#sql` statements, these are ordinary `.java` files.

You can use instances of these classes in your own `#sql` statements as host variables, and as arguments to wrapper methods generated by JPublisher. The next section further discusses them.

#### Using Java Classes JPublisher Generates

When `-methods=false`, JPublisher does not generate wrapper methods for object types, and it does not generate code for PL/SQL packages at all, because they are not useful without wrapper methods. When `-methods=false`, JPublisher exclusively generates `.java` files.

JPublisher generates the same Java code for `REF`, `varray`, and nested table types regardless of whether `-methods` is `false` or `true`.

To use an object of a class JPublisher generates for an object type when `-methods=false`, or for a `REF`, `varray`, or nested table type, you must first initialize the object.

To initialize your object, you can:

- Assign an already initialized object to your object.

- Retrieve a copy of a database object into your object. To do this, you can:

  - Use the object as an `OUT` argument or as the function call result of a JPublisher-generated wrapper method in some other class.

  - Retrieve the object through `#sql` statements you write.

  - Retrieve the object through JDBC calls you write.

- Construct the object and initialize its data.

Unlike the constructors generated in `.sqlj` classes, the constructors generated in `.java` classes do not take a connection argument. Instead, when your object is passed to or returned from a `Statement`, `CallableStatement`, or `PreparedStatement`, JPublisher applies the connection it uses to construct the `Statement`, `CallableStatement`, or `PreparedStatement`.

This does not mean that you can use the same object with different connections at different times. On the contrary, this is not always possible. An object might have a subcomponent, such as a `REF` or a `BLOB`, that is valid only for a particular connection.

To initialize the object's data, you use the `set` methods if your class represents an object type, and you use the `setArray()` or `setElement()` methods if your class represents a `varray` or nested table type. If your class represents a `REF` type, you can only construct a null `REF`. All non-null `REF`s come from the database.

Once you have initialized your object, you can:

- Pass the object to wrapper methods in other classes.

- Use the object as a host variable in your own `#sql` statements.

- Use the object as a host variable in your own JDBC calls.

- Call the methods that read and write the object's state. These methods operate on the collection object in your program and do not affect data in the database.

  - For a class that represents an object type, you can call the `get` and `set` accessor methods.

  - For a class that represents a `varray` or nested table, you can call the `getArray()`, `setArray()`, `getElement()`, and `setElement()` methods.

    The `getArray()` and `setArray()` methods return or modify the collection as a whole. The `getElement()` and `setElement()` methods return or modify individual elements of the collection.

- You cannot modify a `REF`, because it is an immutable entity, but you can read and write the database object it references, using the `getValue()` and `setValue()` methods.

  The `getValue()` method returns a copy of the database object to which the REF refers. The `setValue()` method updates an object type instance in the database, taking as input an instance of the Java class that represents the object type. Unlike the `get` and `set` accessor methods of a class generated for an object type, the `getValue()` and `setValue()` methods read and write database objects.

A few methods have not been mentioned yet. You use the `getFactory()` method in JDBC code to return a `CustomDatumFactory` that constructs objects of your JPublisher-generated class. You pass this `CustomDatumFactory` to the Oracle `getCustomDatum()` methods in the classes `ArrayDataResultSet`, `OracleCallableStatement`, and `OracleResultSet` classes in the `oracle.jdbc.driver` package. The Oracle JDBC driver uses the `CustomDatumFactory` to create an object of your class.

In addition, classes representing `varray`s and nested tables have a few methods that implement features of the `oracle.sql.ARRAY` class:

- `getBaseTypeName()`

- `getBaseType()`

- `getDescriptor()`

JPublisher-generated classes for `varrays` and nested tables do not, however, extend `oracle.sql.ARRAY`.

The following methods that JPublisher generates and Oracle's JDBC drivers employ are not intended for your use:

- `create()`

- `toDatum()`

These methods implement the `CustomDatum` and `CustomDatumFactory` interfaces, which the Oracle JDBC drivers require.

The `RationalP` example, described in "Example: Using Classes Generated for Packages", includes a class that was generated for an object type that does not have wrapper methods.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index