Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Migrating to InterSystems IRIS

In InterSystems IRIS®, the Caché Java Binding has been replaced by the much more powerful Java Native SDK, which should be used for all new development. However, InterSystems IRIS also offers an easy upgrade path for existing Java Binding applications that would be difficult to replace.

The InterSystems IRIS version of the Java binding is intended to work as much like the old Caché Java binding as possible, but some changes were necessary. Most of the changes were an unavoidable consequence of the move from Caché to InterSystems IRIS. Other changes were introduced to fix bugs and to eliminate the most complex and problematic features of the old binding. For example, all Caché Holder classes were replaced by a single IRISReference class that handles all supported datatypes. The following sections describe these changes in detail.

New Classes and System Requirements

  • The top level Caché com.intersys.* domain has been replaced by the InterSystems IRIS com.intersystems.* domain.

  • Not all com.intersys.* classes were ported. The new binding keeps only those that are used directly by projected Java classes.

  • All Java binding library classes are consolidated to com.intersystems.binding. These classes depend on com.intersystems.jdbc.

  • Since com.intersystems.jdbc is needed, JDK 1.8 or higher must be used.

  • In Mac OS and UNIX environments, users should ensure that InterSystems IRIS has write privilege to the folders where proxy .java classes are projected. One way to do this is to set the group-owner of the folders to irisusr.

Connection Code Changes

Connection code now uses connection class IRISConnection rather than Database, and the connection string starts with jdbc:IRIS: instead of jdbc:Cache:. The following examples demonstrate these differences:

Legacy Connection Code
import com.intersys.objects.Database;

String url = "jdbc:Cache://localhost:1972/User/jdbc.log";
String user = "_SYSTEM";
String pwd = "SYS";
Database conn = CacheDatabase.getDatabase (url, user, pwd);

Person p = new Person(conn);
New Connection Code
import com.intersystems.jdbc.IRISConnection;

String url = "jdbc:IRIS://localhost:1972/User/Binding.log";
String user = "_SYSTEM";
String pwd = "SYS";
IRISConnection conn = (IRISConnection) java.sql.DriverManager.getConnection(url, user, pwd);

Person p = new Person(conn);

Interface Changes

This section describes interface features that have been removed or renamed.

Changes to RegisteredObject interface

The following changes were made in the conversion from com.intersys.classes.RegisteredObject to com.intersystems.binding.RegisteredObject:

Removed methods:

  • createObjects(): Light binding feature removed.

  • saveObjects(): Light binding feature removed.

  • getCacheClass(): expose Caché Reflection API and dynamic binding, for which there is no equivalent in InterSystems IRIS.

  • CheckAllFieldsValid() / CheckAllMethods(): these belong to RegisteredObject class, but were replaced by a no-op in any subclasses. They also use Caché Reflection API.

  • check<propertyname>Valid(): this method was projected as no-op.

  • addToBatchInsert() / executeBatchInsert(): these methods mass insert data, which should now be accomplished through JDBC.

Changed methods:

  • getCacheClassName() --> getIRISClassName(): changed method name.

Changes to SerialObject interface

The following changes were made in the conversion from com.intersys.classes.SerialObject to com.intersystems.binding.SerialObject:

Removed methods:

  • open(Database, byte[]): this method depends on Light binding.

  • createClientObject(): this method again depends on Light binding, and serves the same purpose as constructor.

Changes to Pass-By-Reference interface

The following changes were made in the conversion from com.intersys.objects.<type>Holder to com.intersystems.binding.IRISReference:

  • All holder classes are replaced by a single class IRISReference.

  • NOTE: for binding classes, com.intersystems.binding.IRISReference should be used, rather than superclass com.intersystems.jdbc.IRISReference.

Changed method interface:

  • Holder.setValue(com.intersys.cache.Dataholder) --> IRISReference.setValue(Object). It is no longer necessary to wrap objects in Dataholder when passing to setValue(). Dataholder is not supported.

  • Access modifier of local variable "value" was changed from public to protected. Accessor methods should be used instead.

Other methods no longer supported

There is no replacement for two com.intersys.classes.ObjectHandle methods:

  • getOref() / getZref(): there are no longer good ways to retrieve this information.

In com.intersys.classes.CacheRootObject (former superclass of RegisteredObject):

  • castTo(CacheClass): This method works with the Caché Reflection API, which has no equivalent in InterSystems IRIS.

Projection flags no longer supported

The following projection flags were removed from server-side %Projection.Java:

  • POJO: this mode depends on code that cannot be directly ported from Caché, and would have to be completely re-implemented.

  • PROJECTBYREFMETHODSTOPOJO: also cannot be directly ported.

  • PROJECTABSTRACTSTREAM: this flag was supposed to restrict the Stream type that could be projected, but the flag was never enabled. All streams project appropriately in both old and new binding.

Replacements for Caché Library Classes

Classes CacheObject, Database, and CacheException have been replaced as follows:

Caché
InterSystems IRIS
com.intersys.cache.CacheObject
com.intersystems.jdbc.IRISObject
com.intersys.objects.Database
com.intersystems.jdbc.IRISConnection
com.intersys.objects.CacheException
java.sql.SQLException
  • Most projected methods now call com.intersystems.jdbc.IRISConnection, which throws a java.sql.SQLException upon errors.

Classes in com.intersys.objects are replaced with equivalent new classes in com.intersystems.binding.

Caché
InterSystems IRIS
com.intersys.objects.Id
com.intersystems.binding.Id
com.intersys.objects.Oid
com.intersystems.binding.Oid
com.intersys.objects.CacheQuery
com.intersystems.binding.IRISQuery
com.intersys.objects.<type>Holder
com.intersystems.binding.IRISReference
  • Pass-by-reference undergoes some changes in JDBC, refer to the section below.
com.intersys.objects.CacheInputStream
com.intersystems.binding.InputStream
com.intersys.objects.CacheOutputStream
com.intersystems.binding.OutputStream
com.intersys.objects.CacheReader
com.intersystems.binding.Reader
com.intersys.objects.CacheWriter
com.intersystems.binding.Writer
com.intersys.objects.StatusCode
com.intersystems.binding.StatusCode

Classes in com.intersys.classes are replaced with equivalent new classes in com.intersystems.binding.

Caché
InterSystems IRIS
com.intersys.classes.AbstractCacheArray
com.intersystems.binding.AbstractIRISArray
com.intersys.classes.AbstractCacheList
com.intersystems.binding.AbstractIRISList
com.intersys.classes.AbstractStream
com.intersystems.binding.AbstractStream
com.intersys.classes.ArrayOfDataTypes
com.intersystems.binding.ArrayOfDataTypes
com.intersys.classes.ArrayOfObjects
com.intersystems.binding.ArrayOfObjects
com.intersys.classes.BinaryStream
com.intersystems.binding.BinaryStream
com.intersys.classes.CharacterStream
com.intersystems.binding.CharacterStream
com.intersys.classes.ListOfDataTypes
com.intersystems.binding.ListOfDataTypes
com.intersys.classes.ListOfObjects
com.intersystems.binding.ListOfObjects
com.intersys.classes.ObjectHandle
com.intersystems.binding.ObjectHandle
com.intersys.classes.Persistent
com.intersystems.binding.Persistent
com.intersys.classes.RegisteredObject
com.intersystems.binding.RegisteredObject
com.intersys.classes.SerialObject
com.intersystems.binding.SerialObject
com.intersys.classes.RelationshipObject
com.intersystems.binding.RelationshipObject
com.intersys.classes.SerialStream
com.intersystems.binding.SerialStream
com.intersys.classes.GlobalCharacterStream
com.intersystems.binding.CharacterStream
Feedback