Migrating from JDK 1.1 to Java 2

Java 2 is, for the most part, compatible with JDK 1.1. Sun Microsystems changed certain features, such as the security feature, in Java 2. These changes are documented at the following Sun Microsystems's web site:

http://java.sun.com/products/jdk/1.2/compatibility.html

The following sections discuss how the changes made within Java 2 affected Oracle8i:

• Your Development Environment

• JDBC 2.0

• Java 2 Security

• Java 2 ORB APIs

Your Development Environment

The level of your development environment determines your interoperability with the server. If your development environment is Java 2-based, any code compiled and debugged on your system can be loaded and executed on the database. However, if you are developing applications in a JDK 1.1 development environment on your client, you can only use JDK 1.1 classes. With very few exceptions, you can load and execute your JDK 1.1 application in the Java 2 database server. Of course, you always have the option to code your Java 2-based application on your system, load it into the database, and use the Java 2 compiler that exists on the database.

Note: There is another workaround for using Java 2 security even though your code is JDK 1.1-based. The security APIs are provided within a PL/SQL package. You can use these call specifications before your code executes; thus, enabling the correct Java 2 permissions.

JDBC 2.0

Even though 8.1.5 was JDK 1.1-based, JDBC 2.0 support was added to 8.1.5 in an Oracle-specific package--oracle.jdbc2. However, the current version of Oracle8i supports Java2, so JDBC 2.0 exists in its intended package--java.sql. If you have JDBC programs that used the oracle.jdbc2 package for JDBC 2.0 APIs, you must modify these programs before executing with JDBC 2.0 drivers.

Note: If your Java application does not use the oracle.jdbc2 package JDBC APIs (or return an object whose type is within this package), no migration is necessary to connect to the 8.1.6 database.

With the addition of Java 2 in Oracle8i, the JDBC 2.0 support exists in the java.sql package, which is contained in the JDK core libraries. This affects your application, as follows:

Environment
Running a server application in Oracle8i which uses JDBC 2.0.	You must use the java.sql package. If you use oracle.jdbc2, your application will not compile.
Running a client in a Java 2 environment	You must use the java.sql package. If you use oracle.jdbc2, your client will not compile.
Running a client in a JDK 1.1 environment.	You can continue to use the oracle.jdbc2 APIs, but only if you compile against classes111.zip and you use this code only for accessing the server as a client. If you try to load this code within the server, you must migrate to the java.sql package.

Server Applications Using JDBC 2.0

Since the server application is loaded and runs within the database, which is always a Java 2 environment, you must port your application, as stated below:

1. Replace all imports and other mentions of oracle.jdbc2 with java.sql in your programs.

   The oracle.jdbc2 package contains the JDBC 2.0 implementation that Oracle implemented in the JDK 1.1 drivers. Because those classes and interfaces are available in Java 2, oracle.jdbc2 is not included in classes12.zip.

2. The return type of the getTypeMap() method of Connection has been changed from java.util.Dictionary to java.util.Map. Modify your application accordingly. No change is necessary if you are using java.util.Hashtable, because Hashtable implements java.util.Map.

3. Replace classes111.zip with classes12.zip in your makefile.

4. Recompile and relink your executable.

   You must recompile all classes that used to import oracle.jdbc2. In addition, you must recompile any classes where an object is returned and its type exists within the oracle.jdbc2 package. Consider the following example:

   #import java.sql.*;
   . . .
   jd = (java.sql.Connection) getDC();
   
   

   If the getDC method returns an object type from within the oracle.jdbc2 package, the compiler will not catch this as a problem because it is typecast to java.sql.*. Instead, you will receive the following error when you load the application in the database:

   ORA-29521: referenced name oracle/jdbc2/<classname> could not be found.
   
   

   Recompile all of these classes against classes12.zip, which will correct the object type returned to java.sql.*.

For more information, See Chapter 4 in the Oracle8i JDBC Developer's Guide and Reference.

Clients Using JDBC 2.0

The following client applications can interoperate with 8.1.6:

• Java client conforms to JDK 1.1 and uses the JDBC 2.0 APIs contained in oracle.jdbc2. This application imports the oracle.jdbc2 package within classes111.zip.

• Java client conforms to Java 2 and uses the JDBC 2.0 APIs contained in java.sql. This application imports the java.sql package contained within the classes12.zip, not the oracle.jdbc2 package.

Java 2 Security

Java 2 security is implemented in 8.1.6. The JDK 1.1 security sandbox is no longer applicable within Oracle8i. To use the Java 2 security Permissions without modifying your code, you can manage these Permissions through the PL/SQL package--DBMS_JAVA. To execute any of the Java 2 security methods, such as doPrivileged, you must compile your application within a Java 2 environment, as the Permissions are new for the JDK 1.2 release.

See "Java 2 Security" for more information on Java 2 security.

Java 2 ORB APIs

Oracle8i JServer updated its ORB implementation to Visigenic 3.4. This version is compatible with both JDK 1.1 and Java 2.

Note: All existing CORBA applications must regenerate their stubs and skeletons to work with 8.1.6. You must use the 8.1.6 tools when regenerating your application.

Sun Microsystems's Java 2 contains an ORB implementation; JDK 1.1 did not. Thus, when you imported the Visigenic libraries and invoked the CORBA methods, it always invoked the Visigenic implementation. With Java 2, if you invoke the CORBA methods without any modifications--as discussed below--you will invoke Sun Microsystems's CORBA implementation, which can cause unexpected results.

The following lists the three methods for accessing CORBA server objects in Oracle8i from your client and the recommendations for bypassing Sun Microsystems's CORBA implementation:

• JNDI Lookup--The setup for the lookup method is identical for both JDK 1.1 and Java 2. However, you must regenerate the stubs and skeletons.

• Aurora ORB Interface--The Aurora ORB provides an interface for initializing the ORB. If you do not use JNDI, your client initializes an ORB on its node to communicate with the ORB in the database. You can use an Aurora ORB on your client through this class.

• CORBA ORB Interface--If you want to use OMG's CORBA ORB interface, you must set a few properties to ensure you are accessing the correct implementation. If you do not wish to use the Aurora ORB on your client, you can use the pure CORBA interfaces. However, you need to set up your environment to direct your calls to the correct implementation.

JNDI Lookup

If you are using JNDI on the client to access CORBA objects that reside in the server, no code changes are required. However, you must regenerate your CORBA stubs and skeletons.

Aurora ORB Interface

If your client environment uses JDK 1.1, you do not need to change your existing code. You will need to regenerate your stubs and skeletons.

If your client environment has been upgraded to Java 2, you can initialize the ORB through the oracle.aurora.jndi.orb_dep.Orb.init method. This method guarantees that when you initialize the ORB, it will initialize only a single ORB instance. That is, if you use the Java 2 ORB interface, it returns you a new ORB instance each time you invoke the init method. Aurora's init method initializes a singleton ORB instance. Each successive call to init returns an object reference to the existing ORB instance.

In addition, the Aurora ORB interface manages the session-based IIOP connection.

oracle.aurora.jndi.orb_dep.Orb Class

There are several init methods, each with a different parameter list. The following describes the syntax and parameters for each init method.

Note: The returned class for each init method are different. You can safely cast the org.omg.CORBA.ORB class to com.visigenic.vbroker.orb.ORB.

public com.visigenic.vbroker.orb.ORB init();
public org.omg.CORBA.ORB init(Properties props);
public org.omg.CORBA.ORB init(String[] args, Properties props);

Parameter	Description
Properties props	ORB system properties.
String[] args	Arguments that are passed to the ORB instance.

Example 2-1 Using Aurora ORB init method

The following example shows a client instantiating an ORB using the Aurora Orb class.

// Create the client object and publish it to the orb in the client
// Substitute Aurora's Orb.init for OMG ORB.init call
// old way: org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init ();
com.visigenic.vbroker.orb.ORB orb = oracle.aurora.jndi.orb_dep.Orb.init();

Joining a Session

If your client receives a reference to an object that is created in a session, it can invoke a method on that object within the session. However, since all clients must authenticate, you must provide a username and password to the database. If the server requires client-side authentication in the form of SSL_CREDENTIALS, you can provide the client's username, password, and role, which is passed on the connect handshake within the ORB.init method.

public org.omg.CORBA.ORB init(String un, String pw, String role,
	boolean ssl, java.util.Properties props);

Parameter	Description
String un	The username for client-side authentication.
String pw	The password for client-side authentication.
String role	The role to use after logging on.
Boolean ssl	If true, SSL is enabled for the connection. If false, a NON-SSL connection is used.
Properties props	ORB system properties.

CORBA ORB Interface

If you have implemented a pure CORBA client--that is, you do not use JNDI--you need to set the following properties before the ORB initialization call. These properties direct the call to the Aurora implementation, rather than the Java 2 implementation. This ensures the behavior that you expect. The behavior expected from the Visigenic ORB is as follows:

• Even if you invoke ORB.init more than once, only a single ORB instance is created. If you do not set these properties, be aware that each invocation of ORB.init will create a new ORB instance.

• The session IIOP connection is managed correctly.

• Callbacks from the server are managed correctly.

  Note: The Aurora CORBA implementation is based upon Visibroker 3.4.

  Property	Assign Value
  org.omg.CORBA.ORBClass	com.visigenic.vbroker.orb.ORB
  org.omg.CORBA.ORBSingletonClass	com.visigenic.vbroker.orb.ORB

Example 2-2 Assigning Visigenic values to OMG properties

The following example shows how to set up the OMG properties for directing the OMG CORBA init method to the Visigenic implementation.

System.getProperties().put("org.omg.CORBA.ORBClass",

	"com.visigenic.vbroker.orb.ORB");
System.getProperties().put("org.omg.CORBA.ORBSingletonClass",

	"com.visigenic.vbroker.orb.ORB");

Or you can set the properties on the command line, as follows:

java -Dorg.omg.CORBA.ORBClass=com.visigenic.vbroker.orb.ORB

	-Dorg.omg.CORBA.ORBSingletonClass=com.visigenic.vbroker.orb.ORB 

Backwards Compatibility for 8.1.5 CORBA and EJB Applications

The tools provided with Oracle8i, such as publish, have been modified to work with either a JDK 1.1 or Java 2 environment. However, any CORBA or EJB code that has been generated or loaded with the 8.1.5 version of any tool, will not succeed. Make sure that you always use the 8.1.6 version of all tools. This rule applies to your CORBA stubs and skeletons. You must regenerate all stubs and skeletons with the 8.1.6 IDL compiler.

---