// README.txt

		    javam/demo/objbyvalue example
		    -----------------------------

This example shows how to pass Java objects by value between a java
client and a java stored procedure using the serializable interface
and LONG RAW SQL parameters.

Note: as LONG RAW arguments to stored procedures are limited to 32k
bytes this technique only works if the serialized images are less than
the limit.

We use a the Employee.java class to represent entries in the EMP
table.

The stored procedure are defined in the class EmployeeByValue.
The interesting entrypoints are getEmployee and updateEmployee which
take care of creating the instances of EmployeeInfo to represent the
EMP entries:
  - EmployeeInfo getEmployee (Integer empno)
    Gets an employee number and return a Java object representing the
    Employee and all its managers.
  - void updateEmployee (Employee emp)
    Updates the EMP table entries to reflect the changes to the
    employee emp or his managers.  One could also add a createEmployee
    method that would just add entries in the EMP table.

To be able to pass the Employee objects back to a Java client the
objects must be converted to a SQL type.  We convert them to LONG RAW
by serializing them.  The methods getEmployeeInfo and
updateEmployeeInfo take care of that:
  - byte[] getEmployeeInfo (Integer empno)
    Get an EmployeeInfo by calling getEmployee, serializes the object
    and return it as a byte[]
  - void updateEmployeeInfo (byte[] info)
    Get an array containing a serialized EmployeeInfo object,
    deserializes it and call updateEmployee to update the EMP table.

These last 2 entrypoints are published to SQL with the PL/SQL covers
defined in empbyval.sql.  These covers just call the getEmployeeInfo
and updateEmployeeInfo entrypoints, mapping LONG RAW to byte[] back
and forth:

  function getempinfo (empno in number) return long raw 
    as language java name 
       'EmployeeByValue.getEmployeeInfo (java.lang.Integer) return byte[]';

  procedure updateempinfo (info long raw)
    as language java name 
       'EmployeeByValue.updateEmployeeInfo (byte[])';


The client program is Client.java.  It calls the PL/SQL covers to get
the serialized EmployeeInfo and deserializes it to get the Java
instances.  After updating the instances to give a raise to the
employee and its manager it serializes the EmployeeInfo object and
send it back to the PL/SQL cover for updating the database.