Release Notes: Changes to the  Java-ECLiPSe Interface, v5.2 to v5.3

New features

• New RemoteEclipse, OutOfProcessEclipse classes - see Embedding and Interfacing Manual chapter and API documentation for more details
• Opening/closing of ToEclipse/FromEclipseQueues can also be done with a single predicate call from the Eclipse side as well as a single method invocation from the Java side. You only need to use one of these.
• Support for "peer" concept
• New setPeerName() method in EclipseEngineOptions
• New getPeerName() method in EclipseConnection interface, implemented by all classes which implement EclipseConnection.
• EclipseEngineOptions constructors can now read default options from instances of java.util.Properties. See manual/API documentation for what the standard property strings are for the different options.There are now also 2 extra forms of the constructor: one takes a File (eclipse installation path) and the other takes an instance of java.util.Properties.
• Environmental independence. It is no longer necessary to set the PATH (Windows) or LD_LIBRARY_PATH (Unix) environment variables in order to use the Java-ECLiPSe interface. But doing so won't hurt either 8-].
• New convenience method argCT in CompoundTermImpl allows you to retrieve deeply-nested subterms without lots of casting.

 
Incompatibilities
 

There are quite a lot of incompatibilities with the first version but they are considered "tidying up" rather than substantial changes to the interface. We considered it better to move quickly towards the correct design rather than be encumbered by previous design errors.

• Changes to EclipseEngineOptions class
• Parameterless EclipseEngineOptions constructor throws exception if eclipse.directory property is not present in system properties
• setSharedSize() removed from EclipseEngineOptions
• method getEclipseDir removed from EclipseEngineOptions interface.
• isUsingQueues() method moved from EclipseEngineOptions to EclipseEngine interface: now implemented by EmbeddedEclipse and OutOfProcessEclipse.
• Changes to EmbeddedEclipse class
• getInstance(EclipseEngineOptions) is now used to initialise the EmbeddedEclipse for the first time, getInstance() is used to get a reference to it later. Used in the wrong order, these now throw exceptions.
• destroy() method now actually attempts to free resources used by the ECLiPSe (previously, it merely made the EmbeddedEclipse object unusable).
• Changes to EclipseEngine interface
• destroy() method removed from EclipseEngine interface, moved to EmbeddedEclipse.  There is also a destroy() method in OutOfProcessEclipse, but it has slightly different semantics.
• Changes to EXDRInputStream/EXDROutputStream
• readTerm() in EXDRInputStream behaves more like readByte, readInt etc. in DataInputStream than before. The difference is that it now blocks until the read completes or it encounters end-of-file
• writing a NaN value (float or double) to an EXDROutputStream now raises an exception (because there is no equivalent in ECLiPSe).
• Changes to FromEclipseQueue and ToEclipseQueue
• createFrom[To]EclipseQueue (in EclipseConnection interface) now no longer throws EclipseException
• Attempting to call methods on closed From/ToEclipseQueues results in IOExceptions.
• setListener and removeListener in From/ToEclipseQueue are now declared to throw IOExceptions.
• Changes to toString() method of AbstractCompoundTerm/CompoundTermImpl/Atom
• toString() has been removed from AbstractCompoundTerm. toString() methods have been added to CompoundTermImpl and Atom. These methods no longer approximate ECLiPSe TTY output or the output of write/1. The reason for the change is that this approximation was mistakenly suggesting to users that the output of toString() was faithfully readable by ECLiPSe, which it was not. To communicate data to ECLiPSe, the EXDR format should be used, using EXDROutputStream. If the data must also be human-readable, the builtin predicate writeq/2 should be used.

 
 
 

---