This version of Caché includes a significant number of new Java features including:
For more information on Java support, refer to the Caché Java User's Guide.
Upgrading from the Earlier Java Binding
This section describes how to upgrade applications written using the earlier generation of the Caché Java binding to this version.
Architectural Differences
The new version of the Caché Java binding has a number of significant architectural changes from the earlier version. These include:
API Differences
There are a number of API changes from the earlier Java binding. Some of these may require application changes.
Environment Changes
The old Java binding used two JAR files, CacheJava.jar and CacheJDBC.jar; the new binding uses only one, CacheDB.jar. The location of the new JAR file is <cache-install-dir>/dev/java/lib/CacheDB.jar.
Connections
To connect to the Caché server, the old binding used the ObjectFactory class; the new binding uses the CacheDatabase class.
Because the new binding's connection is integrated with the Caché JDBC interface, a connection can now support both SQL and object access. Also, a single connection supports both the Java binding and the JDBC driver; the old binding required one connection for Java and a separate one for JDBC.
With the old binding, the following code connected to the server:
 ObjectFactory factory = null;
 String url="cn_iptcp:127.0.0.1[1972]:SAMPLES";

 // ...

 factory = new ObjectFactory(url);
With the new binding, the connection code is:
 Database dbconnection = null;
 String url="jdbc:Cache://localhost:1972/SAMPLES";
 String username="_SYSTEM";  // null for default
 String password="sys";  // null for default

 dbconnection = CacheDatabase.getDatabase(url, username, password);
Once connected the new binding's Database object and the old binding's ObjectFactory object behave identically. For more information on establishing a connection, see the section Connecting to a Database in Using Java with Caché.
Note:
You can currently still use ObjectFactory, but it is deprecated and will be removed from a future release.
Classes, Methods, and Properties
Methods are projected as Java methods as in the previous binding. Properties are projected as Java get and set methods, as in the previous binding.
Data types and NULL Handling
In the old binding, method arguments and return values were represented as Java literal data types, sometimes known as primitive types (such as int, boolean, or float); in the new binding, these are represented as Java objects (such as Integer, Boolean, or Float). This provides greater flexibility, including the ability to specify arguments with NULL values.
The following is an example using the old binding,
 /* Insert a new element */
 colors._insert( "Orange" );

 /* Remove the first element */
 colors._removeAt( 1 );

 /* Show the changes to the collection */
 colors = person.getFavoriteColors();
 for (r = 1; r <= colors._count(); r++) {
   System.out.println
      ( "Element #" + Integer.toString( r ) + "->" + colors._getAt( r ) );
 }
In the above code, the _removeAt and _getAt methods operate on the int primitive type; the _count method returns an int.
Analogous code that uses the new binding is:
 /* Insert a new element */
 colors._insert( "Orange" );

 /* Remove the first element */
 colors._removeAt( new Integer(1) );

 /* Show the changes to the collection */
 colors = person.getFavoriteColors();
 for (r = 1; r <= colors._count().intValue(); r++) {
   System.out.println
       ( "Element #" + Integer.toString( r ) + "->" 
                     + colors._getAt( new Integer(r) ) );
 }
The changes from the old binding to the new binding are:
Queries and ResultSets
The new binding enables JDBC calls and object access on a single connection. This allows you to use JDBC semantics to execute dynamic SQL queries within a Java application.
The new binding's queries place their results in a standard JDBC ResultSet class; the old binding's ResultSet class was a Caché-specific class that was modeled on but different than the JDBC ResultSet class.
With the old binding, a sample query would be:
 ResultSet rs = null; // this is a Cache class ...
 // ...

 /* Create a ResultSet */
 rs = new ResultSet(server, "Sample.Person", "ByName");

 // ...
 /* Execute the query and loop across the returned rows */
 rs.execute();
The analogous code in the new binding is:
 CacheQuery cq = null;
 java.sql.ResultSet rs = null;

 // ...

 /* Create a CacheQuery */
 cq = new CacheQuery( server, "Sample.Person", "ByName" );
 /* Execute the query and loop across the returned rows */
 rs = cq.execute("");
The new binding uses the CacheQuery class to perform the query and places the results in a standard JDBC result set; this has the additional benefit of separating the functionality of preparing and performing the query from that of processing the result set.
Note:
You can continue to use the older, Caché ResultSet mechanism, but it is deprecated and will be removed in a future release.
Streams, Collections, and Relationships
The interfaces for Streams, Collections, and Relationships now use Java standard interfaces.