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 REFs 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 varrays 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.

---