Oracle8i JDBC Developer's Guide and Reference Release 8.1.5 A64685-01 |
|
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:
STRUCT
. This is described in "Using Default Java Classes for Oracle Objects".
OR
SQLData
interface or the CustomDatum
interface. "Creating Custom Java Classes for Oracle Objects" describes this.
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", STRUCT
s 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:
getAttributes(map)
: retrieves the values from the values array as java.lang.Object
objects; uses entries in the type map (if they have been defined) to determine the Java classes to use in materializing the data.
getAttributes()
: retrieves the values of the values array as java.lang.Object
objects
getSQLTypeName()
: returns a Java String
that represents the fully qualified type name (schema.sql_type_name) of the Oracle object that this Struct
represents
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".
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 TABLEstruct_table
(col1 type_struct)"; stmt.execute(cmd); cmd = "INSERT INTOstruct_table
VALUES (type_struct(10,'01-apr-01'))"; stmt.execute(cmd); cmd = "INSERT INTOstruct_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();
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
.
In deciding which of these two interface implementations to use, consider the following:
Advantages of CustomDatum
:
CustomDatum
from an oracle.sql.STRUCT
. This is more efficient because it avoids unnecessary conversions to native Java types.
Datum
object (which is in oracle.sql
format) from the CustomDatum
object using the toDatum()
method.
CustomDatum
works directly with Datum
types, which is the internal format used by the driver to hold Oracle objects.
CustomDatum
implementation. As of the 8.1.5 release, SQLData
is not supported by JPublisher.
SQLData
is not supported by Oracle's implementation of SQLJ.
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.
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.
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.
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:
Follow these general steps to add entries to an existing type map.
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.
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.
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
.
Follow these general steps to create a new type map.
java.util.Dictionary
class. For example, the java.util.Hashtable
class implements the Dictionary
class.
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"));
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:
|
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.
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.
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.
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
readSQL()
must take as input a SQLInput
stream and a string that indicates the SQL type name of the data (in other words, the name of the Oracle object type, such as EMPLOYEE
).
When your Java application calls getObject()
, the JDBC driver creates a SQLInput
stream object and populates it with data from the database. The driver can also determine the SQL type name of the data when it reads it from the database. When the driver calls readSQL()
, it passes in these parameters.
readSQL()
must call the appropriate readXXX()
method of the SQLInput
stream that is passed in.
For example, if you are reading EMPLOYEE
objects that have an employee name as a CHAR
variable and an employee number as a NUMBER
variable, you must have a readString()
call and a readInt()
call in your readSQL()
method. JDBC calls these methods according to the order in which the attributes appear in the SQL definition of the Oracle object type.
readSQL()
assigns the data that the readXXX()
methods read and convert to the appropriate fields or elements of your custom Java class.
You must implement writeSQL()
as follows:
public void writeSQL(SQLOutput stream) throws SQLException
writeSQL()
must take as input a SQLOutput
stream.
When your Java application calls setObject()
, the JDBC driver creates a SQLOutput
stream object and populates it with data from your custom Java class. When the driver calls writeSQL()
, it passes in this stream parameter.
writeSQL()
must call the appropriate writeXXX()
method of the SQLOutput
stream that is passed in.
For example, if you are writing to EMPLOYEE
objects that have an employee name as a CHAR
variable and an employee number as a NUMBER
variable, then you must have a writeString()
call and a writeInt()
call in your writeSQL()
method. These methods must be called according to the order in which attributes appear in the SQL definition of the Oracle object type.
writeSQL()
must then write the data converted by the writeXXX()
methods to the SQLOutput
stream so it can be written to the database once you execute the prepared statement.
"Creating Customized Java Classes for Oracle Objects" contains an example implementation of the SQLData
interface for a given SQL definition of an Oracle object.
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
.
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
.
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
.
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.
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();
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.
OracleCallableStatement
to call the getEmployee(?)
function.
OracleCallableStatement ocs = (OracleCallableStatement) conn.prepareCall("{ ? = call getEmployee(?) }");
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();
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);
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.
OracleCallableStatement
to call the addEmployee(?)
function.
OracleCallableStatement ocs = (OracleCallableStatement) conn.prepareCall("{ call addEmployee(?) }");
setObject()
to pass the emp
object as an IN
parameter to the callable statement. Then, execute the statement.
ocs.setObject(1, emp); ocs.execute();
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.
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".
PreparedStatement pstmt = conn.prepareStatement ("INSERT INTO PERSONNEL VALUES (?)");
This assumes conn
is your connection object.
setObject()
method of the prepared statement to bind your Java datatype object to the prepared statement.
pstmt.setObject(1, emp);
pstmt.executeUpdate();
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.
The CustomDatum
interface has these additional advantages:
CustomDatum
uses oracle.sql.Datum
types directly
CustomDatum
works directly with Datum
types, the internal format the driver uses to hold Oracle objects
The CustomDatum
and CustomDatumFactory
interfaces do the following:
toDatum()
method of the CustomDatum
class transforms the data into an oracle.sql.*
representation.
CustomDatumFactory
specifies a create()
method equivalent to a constructor for your custom Java class. It creates and returns a CustomDatum
instance. The JDBC driver uses the create()
method to return an instance of the custom Java class to your Java application or applet. It takes as input an oracle.sql.Datum
object and an integer indicating the corresponding SQL type code as specified in the OracleTypes
class.
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.
The JDBC drivers provide the following methods to retrieve and insert object data as instances of CustomDatum
.
To retrieve object data:
OracleResultSet.getCustomDatum ()
method:
OracleResultSet.getCustomDatum (int col_index, CustomDatumFactory factory)
This method takes as input the column index of the data in your result set, and a CustomDatumFactory
instance. For example, you can implement a getFactory()
method of your custom Java class to produce the CustomDatumFactory
instance to input to getCustomDatum()
. The type map is not required when using Java classes that implement CustomDatum
.
OR
ResultSet.getObject(index, map)
method to retrieve data as instances of CustomDatum
. In this case, 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.
To insert object data:
OraclePreparedStatement.setCustomDatum ()
method:
OraclePreparedStatement.setCustomDatum (int bind_index, CustomDatum custom_obj)
This method takes as input the parameter index of the bind variable and the name of the object containing the variable.
OR
PreparedStatement.setObject()
method. You can also use this method, in its various forms, to insert CustomDatum
instances without requiring a type map.
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.
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".
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
.
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
.
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
.
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);
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();
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.
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".
OraclePreparedStatement opstmt = conn.prepareStatement ("UPDATE PERSONNEL SET Employee = ? WHERE Employee.EmpNum = 28959);
This assumes conn
is your Connection
object.
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);
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.
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.