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:
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);
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.JavaOpens in a new tab:
-
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
|
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
|
|
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 |
