Oracle8i JDBC Developer's Guide and Reference
Release 8.1.5
A64685-01

Library
Product
Contents
Index

Prev Chap Top Next

Working with Oracle Object Types

This section contains these subsections:

Oracle object types provide support for composite data structures in the database. For example, you could define a type Person that has attributes such as name (type CHAR), address (type CHAR), phone number (type CHAR), and employee number (type NUMBER).

Oracle provides tight integration between its Oracle object features and its JDBC functionality. You can customize how SQL types map to Java classes by creating custom Java type definition classes; Oracle offers considerable flexibility in how this mapping is done. In this book, Java classes created as classes to map to Oracle objects will be referred to as custom Java classes.

JDBC materializes Oracle objects as instances of particular Java classes. Two main steps in using JDBC to access Oracle objects are: creating the Java classes for the Oracle objects and populating these classes. You have the option of:

OR

Using Default Java Classes for Oracle Objects

If you choose not to provide a type map to explicitly specify a Java class for an Oracle object, you can let Oracle JDBC materialize the object as a Struct.

You would typically want to use Struct objects instead of custom Java objects in situations where you are manipulating data. For example, your Java application might be a tool to manipulate data as opposed to being an end-user application. You can select data from the database into Struct objects and create Struct objects for inserting data into the database. As described in "Class oracle.sql.STRUCT", STRUCTs completely preserve data because they maintain the data in SQL format. Using Struct objects is more efficient and more precise in these situations where the information does not need to be in a user-friendly format.

If your code must fully comply with JDBC 2.0, use the functionality in the oracle.jdbc2.Struct interface:

If it is not necessary to comply with JDBC 2.0 and you want to take advantage of the extended functionality offered by Oracle-defined methods, then cast the output to oracle.sql.STRUCT.

The oracle.sql.STRUCT class implements the oracle.jdbc2.Struct interface and provides extended functionality beyond the JDBC 2.0 standard. Compare the list of methods above with the methods provided for oracle.sql.STRUCT in "Class oracle.sql.STRUCT".

Using STRUCT Objects

You can use standard JDBC functionality such as getObject() to retrieve Oracle objects from the database as an instance of oracle.jdbc2.Struct. Because getObject() returns a java.lang.Object, you must cast the output of the method to a Struct. For example: 

oracle.jdbc2.Struct  myStruct = (oracle.jdbc2.Struct)rs.getObject(1);

As described in the preceding section, the oracle.jdbc2.Struct class is implemented by oracle.sql.STRUCT. If you want to use the extended functionality offered by Oracle, you can then cast the Struct object to a STRUCT. For example, to use the getOracleAttributes() method to return the attributes of the Struct, cast myStruct to oracle.sql.STRUCT: 

oracle.sql.STRUCT STRUCTattribute=s 
((oracle.sql.STRUCT)myStruct).getOracleAttributes()

The getOracleAttributes() method returns the attributes of myStruct in oracle.sql.* format.

You can also retrieve the object directly into an oracle.sql.STRUCT. For example, getObject() is used to get a NUMBER object from column 1 (col1) of the table struct_table. Because getObject() returns an Object type, the result is cast to an oracle.sql.STRUCT. This example assumes that the Statement object stmt has already been created. 

String cmd;
cmd = "CREATE TYPE type_struct AS object (field1 NUMBER,field2 DATE)";
stmt.execute(cmd);

cmd = "CREATE TABLE struct_table (col1 type_struct)";
stmt.execute(cmd);

cmd = "INSERT INTO struct_table VALUES (type_struct(10,'01-apr-01'))";
stmt.execute(cmd);

cmd = "INSERT INTO struct_table VALUES (type_struct(20,'02-may-02'))";
stmt.execute(cmd);

ResultSet rs= stmt.executeQuery("SELECT * FROM test_Struct");
oracle.sql.STRUCT struct_obj=(oracle.sql.STRUCT) rs.getObject(1);

To use an oracle.sql.STRUCT object to access, manipulate, or update data, you can bind the object to a prepared statement or callable statement by using the setOracleObject() method. This requires casting your prepared statement or callable statement to an OraclePreparedStatement object or OracleCallableStatement object. 

PreparedStatement ps= conn.prepareStatement("text_of_prepared_statement");
STRUCT mySTRUCT = new STRUCT (...)
((OraclePreparedStatement)ps).setOracleObject(1, mySTRUCT);

Similarly, to get data from the database, the OracleCallableStatement and OracleResultSet classes have a getSTRUCT() method that returns an Oracle object as an oracle.sql.STRUCT. For example: 

ResultSet rset = stmt.executeQuery (...);
oracle.sql.STRUCT mySTRUCT = ((OracleResultSet)rs).getSTRUCT();

Creating Custom Java Classes for Oracle Objects

If you want to define custom Java classes for your Oracle objects, then you must define a type map that specifies the custom Java classes that the drivers will generate for the corresponding Oracle objects.

You must also provide a way to create and populate the custom Java class from the Oracle object and its attribute data. The driver must be able to read from a Java custom class and populate it. In addition, the custom Java class can provide get and set methods corresponding to the Oracle object's attributes, although this is not necessary. To create and populate the custom classes, and provide these read/write capabilities, you can choose between these two interfaces:

The custom Java class you create must implement one of these interfaces.

For example, assume you have an Oracle object type, EMPLOYEE, in the database that consists of two attributes: Name (which is type CHAR) and EmpNum (employee number, which is type NUMBER). You use the type map to specify that the EMPLOYEE object should map to a custom Java class that you call JEmployee. You can use either the SQLData or CustomDatum interface to be implemented by the JEmployee class.

The most convenient way to create the custom Java class is to employ the JPublisher utility to create it for you. However, JPublisher supports only the CustomDatum implementation. You can also create the custom Java class yourself, and in fact must do so if you want to implement the SQLData interface.

The following section describes the relative advantages of using CustomDatum and SQLData.

Relative Advantages of CustomDatum vs. SQLData

In deciding which of these two interface implementations to use, consider the following:

Advantages of CustomDatum:

Advantages of SQLData:

The SQLData interface only lets you populate a Java object from a SQL object--the CustomDatum interface is far more powerful. In addition to enabling you to populate Java objects, CustomDatum enables you to materialize objects from SQL types that are not necessarily objects. Therefore, you can create a CustomDatum object from any datatype found in an Oracle database. This is particularly useful in the case of RAW data that can be a serialized object.

Understanding Type Maps

If you use the SQLData interface to create Java custom classes, then you must create a type map that specifies the Java custom class that corresponds to the Oracle object in the database. For a description of how to create these custom Java classes with SQLData, see "Creating Custom Java Classes for Oracle Objects".

If you do not include an object and its mapping in the type map, then the object will map to the oracle.sql.STRUCT class by default. See "Class oracle.sql.STRUCT" for more information about this class.

The type map relates a Java class to the SQL type name of an Oracle object. This is a one-to-one mapping that is stored in a hash table as a key-value pair. When you read data from an Oracle object, the JDBC driver considers the type map to determine which Java class to use to materialize the data from the SQL object type. When you write data to an Oracle object, the JDBC driver gets the SQL type name from the Java class by calling the getSQLTypeName() method of the SQLData interface. The actual conversion between SQL and Java is handled by the driver.

The attributes of the Java class that corresponds to an Oracle object can use either Java native types or Oracle native types (instances of the oracle.sql.* classes) to store attributes.

Creating a Type Map Class

The Java application programmer is responsible for providing a type map class that implements java.util.Dictionary. For example, java.util.Hashtable implements Dictionary.

The type map class must implement a put() method used to enter each mapping entry that relates a Java class to an Oracle object type. The put() method must be implemented to accept a keyword-value pair, where the key is an Oracle SQL type name and the value is the Java class object.

Creating a Type Map Object and Defining Mappings

Each connection object has an attribute for an associated type map object. Cast your connection to an OracleConnection object to use type map functionality.

You can create a type map by either of the methods described in the following sections:

Adding Entries to an Existing Type Map

Follow these general steps to add entries to an existing type map.

  1. Use the getTypeMap() method of your OracleConnection object to return the connection's Map object. The getTypeMap() method returns a java.util.Dictionary object. For example: 

    java.util.Dictionary myMap = oraconn.getTypeMap();

    In this example, the getMapType() method on the OracleConnection object oraconn returns the myMap Dictionary object.

    Note:

    If the type map in the OracleConnection object has not been initialized, then the first call to getTypeMap() returns null.  

  2. Use the Dictionary object's put() method to add entries to the map. The put() method takes two arguments: a SQL type name string and the name of the Java class object to which you want to map it. 

    myMap.put(sqlTypeName, classObject);

    The sqlTypeName is a string that represents the fully qualified name of the SQL type in the database. The classObject is the Java class object to which you want to map the SQL type. Get the class object with the class.forName() method. You can rewrite the put() method as: 

    myMap.put(sqlTypeName, class.forName(className));

    For example, if you have a PERSON SQL datatype defined in the CORPORATE database schema, then map it to a Person Java class defined as Person with this statement: 

    myMap.put("CORPORATE.PERSON", class.forName("Person"));

    The map has an entry that maps the PERSON SQL datatype in the CORPORATE database to the Person Java class.

  3. When you finish adding entries to the map, use the OracleConnection object's setTypeMap() method to overwrite the connection's existing type map. For example: 

    oraconn.setTypeMap(myMap);

    In this example, setTypeMap() overwrites the oraconn connection's original map with myMap.

Creating a New Type Map

Follow these general steps to create a new type map.

  1. Create an empty map object. An empty map object can be anything that implements the java.util.Dictionary class. For example, the java.util.Hashtable class implements the Dictionary class.

  2. Use the Map object's put() method to add entries to the map. For more information on the put() method, see Step 2 in the preceding section. For example, if you have an EMPLOYEE SQL type defined in the CORPORATE database, then you can map it to an Employee class object defined by Employee.java with this statement: 

    newMap.put("CORPORATE.EMPLOYEE", class.forName("Employee"));
  3. When you finish adding entries to the map, use the OracleConnection object's setTypeMap() method to overwrite the connection's existing type map. For example: 

    oraconn.setTypeMap(newMap);

    In this example, setTypeMap() overwrites the oraconn connections's original map with newMap.

    Notes:

    • You can explicitly provide type map objects in some getXXX() and setXXX() methods to override the custom or default mapping of your connection.

    • If the type map does not specify a Java class mapping for an Oracle object type, then it defaults to data from the object type materialized in Java in an instance of the oracle.sql.STRUCT class. For more information about this class, see "Class oracle.sql.STRUCT".

    • Do not use the type map for inserting custom objects into the database.

     

STRUCTS and the Type Map

If you do not specify a particular SQL object type in the type map, then the driver will materialize it as an instance of the oracle.jdbc2.Struct class. If the SQL object type contains embedded objects, and they are not present in the type map, the driver will materialize the embedded objects as instances of oracle.sql.Struct. If the embedded objects are present in the type map, a call to the getAttributes() method will return embedded objects as instances of the specified Java classes from the type map.

Understanding the SQLData Interface

To make an Oracle object and its attribute data available to Java applications, you can create a custom Java class for the object that implements the SQLData interface. Note that if you use this interface, you must supply a type map that specifies the Oracle objects in the database and the name of the corresponding custom Java classes that you will create for them.

The SQLData interface defines methods that translate between SQL and Java for Oracle database objects. Standard JDBC provides a SQLData interface and companion SQLInput and SQLOutput interfaces in the oracle.jdbc2 package.

If you create a custom Java class that implements SQLData, you must provide a readSQL() method and a writeSQL() method as defined by the SQLData interface.

The JDBC driver calls your readSQL() method to read a stream of data values from the database and populate an instance of your custom Java class. Typically, the driver would use this method as part of an OracleResultSet.getObject() call.

Similarly, the JDBC driver calls your writeSQL() method to write a sequence of data values from an instance of your custom Java class to a stream that can be written to the database. Typically, the driver would use this method as part of an OraclePreparedStatement setObject() call.

Understanding the SQLInput and SQLOutput Interfaces

The JDBC driver includes classes that implement the SQLInput and SQLOutput interfaces. It is not necessary to implement the SQLOutput or SQLInput objects. The JDBC drivers will do this for you.

The SQLInput implementation is an input stream class, an instance of which must be passed in to readSQL(). SQLInput includes a readXXX() method for every possible Java type that attributes of an Oracle object might be converted to, such as readObject(), readInt(), readLong(), readFloat(), readBlob(), and so on. Each readXXX() method converts SQL data to Java data and returns it into an output parameter of the corresponding Java type. For example, readInt() returns an integer.

The SQLOutput implementation is an output stream class, an instance of which must be passed in to writeSQL(). SQLOutput includes a writeXXX() method for each of these Java types. Each writeXXX() method converts Java data to SQL data, taking as input a parameter of the relevant Java type. For example, writeString() would take as input a string attribute from your Java class.

Implementing readSQL() and writeSQL() Methods

When you create your custom Java class that implements SQLData, you must also implement the readSQL() and writeSQL() methods.

You must implement readSQL() as follows: 

public void readSQL(SQLInput stream, String sql_type_name) throws SQLException

You must implement writeSQL() as follows: 

public void writeSQL(SQLOutput stream) throws SQLException

"Creating Customized Java Classes for Oracle Objects" contains an example implementation of the SQLData interface for a given SQL definition of an Oracle object.

Reading and Writing Data with a SQLData Class

This section describes how to read data from an Oracle object or write data to an Oracle object if your corresponding Java class implements SQLData.

Reading Data from an Oracle Object Using a SQLData Interface

This section summarizes the steps to read data from an Oracle object into your Java application when you choose the SQLData implementation for your custom Java class.

These steps assume you have already defined the Oracle object type, created the corresponding custom Java class, updated the type map to define the mapping between the Oracle object and the Java class, and defined a statement object stmt.

  1. Query the database to read the Oracle object into a JDBC result set. 

    ResultSet rs = stmt.executeQuery("SELECT Emp_col FROM PERSONNEL");
rs.next();

    The PERSONNEL table contains one column, Emp_col, of SQL type Emp_object. This SQL type is defined in the type map to map to the Java class Employee.

  2. Use the getObject() method of your result set to populate an instance of your custom Java class with data from one row of the result set. The getObject() method returns the user-defined SQLData object because the type map contains an entry for Employee. 

    Employee emp = (Employee)rs.getObject(1);

    Note that if the type map did not have an entry for the object, getObject() would return an oracle.sql.STRUCT object. In this case you must cast the output to an oracle.sql.STRUCT. 

    Struct empstruct = (oracle.sql.STRUCT)rs.getObject(1);
...

    The getObject() call triggers readSQL() and readXXX() calls as described above.

    Note:

    To avoid the need for the type map, use the getSTRUCT() method. This method always returns a STRUCT object even if there is a mapping entry in the type map.  

  3. If you have get methods in your custom Java class, then use them to read data from your object attributes. For example, if EMPLOYEE has an EmpName (employee name) of type CHAR and EmpNum (employee number) of type NUMBER, provide a getEmpName() method that returns a Java String and a getEmpNum() method that returns an integer (int). Then invoke them in your Java application as follows: 

    String empname = emp.getName();
int empnumber = emp.getEmpNum();

    Note:

    Alternatively, fetch data by using a callable statement object, which also has a getObject() method.  

Passing SQLData Objects to a Callable Statement as an OUT Parameter

Suppose you have an OracleCallableStatement ocs that calls a PL/SQL function getEmployee(?). The program passes an employee number (empnumber) to the function; the function returns the corresponding Employee object.

  1. Prepare an OracleCallableStatement to call the getEmployee(?) function. 

    OracleCallableStatement ocs = 
  (OracleCallableStatement) conn.prepareCall("{ ? = call getEmployee(?) 
}");
  2. Declare the empnumber as the input parameter to getEmployee(?). Register the SQLData object as the OUT parameter. The SQL type of the Employee object is OracleTypes.STRUCT. Then, execute the statement. 

    ocs.setInt(2,empnumber); 
ocs.registerOutParameter(1, OracleTypes.STRUCT, "EMP_OBJECT"); 
ocs.execute();
  3. Use the getObject() method to retrieve the employee object. Because the object is returned as a STRUCT, cast the output of getObject() to an Employee object. 

    Employee emp = (Employee) ocs.getObject(1);
Passing SQLData Objects to a Callable Statement as an IN Parameter

Suppose you have a PL/SQL function addEmployee(?) that takes an Employee object as an IN parameter and adds it to the PERSONNEL table. In this example, emp is a valid Employee object.

  1. Prepare an OracleCallableStatement to call the addEmployee(?) function. 

    OracleCallableStatement ocs = 
  (OracleCallableStatement) conn.prepareCall("{ call addEmployee(?) }");
  2. Use setObject() to pass the emp object as an IN parameter to the callable statement. Then, execute the statement. 

    ocs.setObject(1, emp); 
ocs.execute();
Writing Data to an Oracle Object Using a SQLData Interface

This section describes the steps in writing data to an Oracle object from your Java application when you choose the SQLData implementation for your custom Java class.

This description assumes you have already defined the Oracle object type, created the corresponding Java class, and updated the type map to define the mapping between the Oracle object and the Java class.

  1. If you have set methods in your custom Java class, then use them to write data from Java variables in your application to attributes of your Java datatype object. 

    emp.setEmpName(empname);
emp.setEmpNum(empnumber);

    This statement uses the emp object and the empname and empnumber variables defined in "Reading Data from an Oracle Object Using a SQLData Interface".

  2. Prepare a statement that updates an Oracle object in a row of a database table, as appropriate, using the data provided in your Java datatype object. 

    PreparedStatement pstmt = conn.prepareStatement
   ("INSERT INTO PERSONNEL VALUES (?)");

    This assumes conn is your connection object.

  3. Use the setObject() method of the prepared statement to bind your Java datatype object to the prepared statement. 

    pstmt.setObject(1, emp);
  4. Execute the statement, which updates the database. 

    pstmt.executeUpdate();

    Note:

    You can use your Java datatype objects as either IN or OUT bind variables.  

Understanding the CustomDatum Interface

To make an Oracle object and its attribute data available to Java applications, you can create a custom Java class for the object that implements the oracle.sql.CustomDatum and oracle.sql.CustomDatumFactory interfaces. The CustomDatum and CustomDatumFactory interfaces are supplied by Oracle and are not a part of the JDBC standard.

Note:

The JPublisher utility supports the generation of classes that implement the CustomDatum and CustomDatumFactory interfaces.  

The CustomDatum interface has these additional advantages:

The CustomDatum and CustomDatumFactory interfaces do the following:

CustomDatum and CustomDatumFactory have the following definitions: 

public interface CustomDatum 
{ 
    Datum toDatum (OracleConnection conn) throws SQLException; 
} 
 
public interface CustomDatumFactory 
{ 
    CustomDatum create (Datum d, int sql_Type_Code) throws SQLException; 
}

where conn represents the Connection object, d represents an object of type oracle.sql.Datum and sql_Type_Code represents the SQL type code of the Datum object.

Note:

It is up to the developer to decide how to handle a situation where the SQL type code contradicts the type of the Datum object.  

The JDBC drivers provide the following methods to retrieve and insert object data as instances of CustomDatum.

To retrieve object data:

OR

To insert object data:

OR

The following sections describe the getCustomDatum() and setCustomDatum() methods.

To continue the example of an Oracle object EMPLOYEE, you might have something like the following in your Java application: 

CustomDatum datum = ors.getCustomDatum(1, Employee.getFactory());

In this example, ors is an Oracle result set, getCustomDatum() is a method in the OracleResultSet class used to retrieve a CustomDatum object, and the EMPLOYEE is in column 1 of the result set. The Employee.getFactory() call will return a CustomDatumFactory to the JDBC driver. The JDBC driver will call create() from this object, returning to your Java application an instance of the Employee class that is populated with data from the result set.

Notes:

  • CustomDatum and CustomDatumFactory are defined as separate interfaces so that different Java classes can implement them if you wish (such as an Employee class and an EmployeeFactory class).

  • Your custom Java classes must import oracle.sql.* (or at least CustomDatum, CustomDatumFactory, and Datum), oracle.jdbc.driver.* (or at least OracleConnection and OracleTypes), and java.sql.SQLException.

  • Refer to the Javadoc for more information about the CustomDatum and CustomDatumFactory classes.

 

CustomDatum versus SQLData: Comparison for Serializable Objects

The CustomDatum interface provides far more flexibility than the SQLData interface. The SQLData interface is designed to only let you customize the mapping of SQL object types (that is, Oracle8 object types) to Java types of your choice. Implementing the SQLData interface lets the JDBC driver populate the fields of the customized Java class from the original SQL object data and vice-versa, after performing the appropriate conversions between Java and SQL types.

The CustomDatum interface goes beyond simply supporting the customization of SQL object types to Java types. It lets you provide a mapping between Java object types and any SQL type supported by the oracle.sql package.

For example, use CustomDatum to store instances of Java objects that do not correspond to a particular SQL Oracle8 object type in the database in columns of SQL type RAW. The create() method in CustomDatumFactory would have to implement a conversion from an object of type oracle.sql.RAW to the desired Java object. The toDatum() method in CustomDatum would have to implement a conversion from the Java object to an oracle.sql.RAW. This can be done, for example, by using Java serialization.

Upon retrieval, the JDBC driver transparently retrieves the raw bytes of data in the form of an oracle.sql.RAW and calls the CustomDatumFactory's create() method to convert the oracle.sql.RAW object to the desired Java class.

When you insert the Java object into the database, you can simply bind it to a column of type RAW to store it. The driver transparently calls the CustomDatum.toDatum() method to convert the Java object to an oracle.sql.RAW object. This object is then stored in a column of type RAW in the database.

Support for the CustomDatum interfaces is also highly efficient because the conversions are designed to work using oracle.sql.* formats, which happen to be the internal formats used by the JDBC drivers. Moreover, the type map, which is necessary for the SQLData interface, is not required when using Java classes that implement CustomDatum. For more information on why classes that implement CustomDatum do not need a type map, see "Understanding the CustomDatum Interface".

Reading and Writing Data with a CustomDatum Interface

This section describes how to read data from an Oracle object or write data to an Oracle object if your corresponding Java class implements CustomDatum.

Reading Data from an Oracle Object Using the CustomDatum Interface

This section summarizes the steps in reading data from an Oracle object into your Java application. These steps apply whether you implement CustomDatum manually or use JPublisher to produce your custom Java classes.

These steps assume you have already defined the Oracle object type, created the corresponding custom Java class or had JPublisher create it for you, and defined a statement object stmt.

  1. Query the database to read the Oracle object into a result set, casting to an Oracle result set. 

    OracleResultSet ors = (OracleResultSet)stmt.executeQuery
   ("SELECT Emp_col FROM PERSONNEL");
ors.next();

    where PERSONNEL is a one-column table. The column name is Emp_col of type Employee_object.

  2. Use the getCustomDatum() method of your Oracle result set to populate an instance of your custom Java class with data from one row of the result set. The getCustomDatum() method returns an oracle.sql.CustomDatum object, which you can cast to your specific custom Java class. 

    Employee emp = (Employee)ors.getCustomDatum(1, Employee.getFactory());

    OR 

    CustomDatum datum = ors.getCustomDatum(1, Employee.getFactory());

    This example assumes that Employee is the name of your custom Java class and ors is the name of your OracleResultSet object.

    If you do not want to use getCustomDatum(), the JDBC drivers let you use the standard JDBC ResultSet.getObject() method to retrieve CustomDatum data. However, you must have an entry in the type map that identifies the factory class to be used for the given object type, and its corresponding SQL type name.

    For example, if the SQL type name for your object is EMPLOYEE, then the corresponding Java class is Employee, which will implement CustomDatum. The corresponding Factory class is EmployeeFactory, which will implement CustomDatumFactory.

    Use this statement to declare the EmployeeFactory entry for your type map: 

    map.put ("EMPLOYEE", Class.forName ("EmployeeFactory"));

    Then use the form of getObject() where you specify the map object: 

    Employee emp = (Employee) rs.getObject (1, map);

    If the connection's default type map already has an entry that identifies the factory class to be used for the given object type, and its corresponding SQL type name, then you can use this form of getObject(): 

    Employee emp = (Employee) rs.getObject (1);
  3. If you have get methods in your custom Java class, use them to read data from your object attributes into Java variables in your application. For example, if EMPLOYEE has Name of type CHAR and EmpNum (employee number) of type NUMBER, provide a getName() method that returns a Java string and a getEmpNum() method that returns an integer. Then invoke them in your Java application as follows: 

    String empname = emp.getName();
int empnumber = emp.getEmpNum();

    Note:

    Alternatively, you can fetch data into a callable statement object. The OracleCallableStatement class also has a getCustomDatum() method.  

Writing Data to an Oracle Object Using the CustomDatum Interface

This section summarizes the steps in writing data to an Oracle object from your Java application when you use JPublisher to produce your custom Java class or otherwise choose the CustomDatum implementation.

These steps assume you have already defined the Oracle object type, created the corresponding custom Java class or had JPublisher create it for you.

Note:

The type map is not used when you are performing database INSERTs and UPDATEs.  

  1. If you have set methods in your custom Java class, then use them to write data from Java variables in your application to attributes of your Java datatype object. 

    emp.setName(empname);
emp.setEmpNum(empnumber);

    This statement uses the emp object and the empname and empnumber variables defined in "Reading Data from an Oracle Object Using the CustomDatum Interface".

  2. Write an Oracle prepared statement that updates an Oracle object in a row of a database table, as appropriate, using the data provided in your Java datatype object. 

    OraclePreparedStatement opstmt = conn.prepareStatement
   ("UPDATE PERSONNEL SET Employee = ? WHERE Employee.EmpNum = 28959);

    This assumes conn is your Connection object.

  3. Use the setCustomDatum() method of the Oracle prepared statement to bind your Java datatype object to the prepared statement. 

    opstmt.setCustomDatum(1, emp);

    The setCustomDatum() method calls the toDatum() method of your custom Java class to retrieve an oracle.sql.STRUCT object that can be written to the database.

    In this step you could also use the setObject() method to bind the Java datatype. For example: 

    opstmt.setObject(1,emp);

    Note:

    You can use your Java datatype objects as either IN or OUT bind variables.  

Using JPublisher with JDBC

JPublisher is an Oracle utility for creating Java classes that map to Oracle objects. It generates a full class definition for a custom Java class, which you can instantiate to hold the data from an Oracle object. JPublisher-generated classes include methods to convert data from SQL to Java and from Java to SQL, as well as getter and setter methods for the attributes of the class.

If you want additional functionality you can create a subclass and add features as desired. JPublisher has features that will create references to the code you write if you need to regenerate the original class. The alternative, editing the generated class by adding methods to it, is not recommended if you anticipate running JPublisher at some future time to regenerate the class. If you run JPublisher to regenerate a class that you have modified in this way, your changes (that is, the methods you have added) will be overwritten. Even if you direct JPublisher output to a separate file, you will still need to merge your changes into the file.

You do not have to use JPublisher to create your custom Java classes, but it is usually very convenient. For more information on JPublisher, see the Oracle8i JPublisher User's Guide.

JPublisher Mapping Options

If you use JPublisher to implement your custom Java class, then you can choose among three mappings for attributes:

JPublisher has a command-line option that enables you to choose among these three mapping options. For more information on the mapping options, see the Oracle8i JPublisher User's Guide.


Prev
Top
Next
Oracle
Copyright © 1999 Oracle Corporation.
All Rights Reserved.

Library
Product
Contents
Index