com.parctechnologies.eclipse
Class OutOfProcessEclipse

java.lang.Object
  extended bycom.parctechnologies.eclipse.OutOfProcessEclipse
All Implemented Interfaces:
EclipseConnection, EclipseEngine

public class OutOfProcessEclipse
extends java.lang.Object
implements EclipseConnection, EclipseEngine

An ECLiPSe engine which runs in a child process of the Java virtual machine. An OutOfProcessEclipse is created using the public constructor, which takes an EclipseEngineOptions object. A JVM may have any number of instances of this class. Invocation of the destroy() method does not affect the ability to create new OutOfProcessEclipse instances.


Constructor Summary
OutOfProcessEclipse(EclipseEngineOptions options)
          Create a new OutOfProcessEclipse using the supplied options.
 
Method Summary
 void compile(java.io.File f)
          Direct ECLiPSe to compile a named object file.
 void destroy()
          Terminate the OutOfProcessEclipse process and the connection to it.
 AsyncEclipseQueue getAsyncEclipseQueue(java.lang.String name)
          Create or access an asynchronous queue to transfer data between Java and ECLiPSe.
 FromEclipseQueue getEclipseStderr()
          Return a FromEclipseQueue which allows access to the ECLiPSe engine's stderr stream.
 ToEclipseQueue getEclipseStdin()
          Return a ToEclipseQueue which allows access to the ECLiPSe engine's stdin stream.
 FromEclipseQueue getEclipseStdout()
          Return a FromEclipseQueue which allows access to the ECLiPSe engine's stdout stream.
 FromEclipseQueue getFromEclipseQueue(java.lang.String name)
          Create or access a queue to transfer data from ECLiPSe to Java.
 java.lang.String getPath(java.io.File f)
          Convert a file path from the Java representation to the ECLiPSe representation.
 Atom getPeerName()
          Return the name by which the peer representing the Java side of the connection is indexed in ECLiPSe.
 ToEclipseQueue getToEclipseQueue(java.lang.String name)
          Create or access a queue to transfer data from Java to ECLiPSe.
 boolean isUsingQueues()
          Query the ECLiPSe engine's "use queues" flag.
 EclipseMultitaskConnection registerMultitask(MultitaskListener multitaskListener)
          Register this peer as desiring participation in any multitasking phases that ECLiPSe enters.
 CompoundTerm rpc(CompoundTerm goal)
          Make an "RPC" (remote predicate call) to the ECLiPSe engine.
 CompoundTerm rpc(java.lang.Object[] goalTerm)
          Convenience rpc method.
 CompoundTerm rpc(java.lang.String goal)
          Make an "RPC" (remote predicate call) to the ECLiPSe engine.
 CompoundTerm rpc(java.lang.String functor, java.lang.Object arg1)
          Convenience rpc method.
 CompoundTerm rpc(java.lang.String functor, java.lang.Object[] args)
          Convenience rpc method.
 CompoundTerm rpc(java.lang.String functor, java.lang.Object arg1, java.lang.Object arg2)
          Convenience rpc method.
 CompoundTerm rpc(java.lang.String functor, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3)
          Convenience rpc method.
 CompoundTerm rpc(java.lang.String functor, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4)
          Convenience rpc method.
 CompoundTerm rpc(java.lang.String functor, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4, java.lang.Object arg5)
          Convenience rpc method.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OutOfProcessEclipse

public OutOfProcessEclipse(EclipseEngineOptions options)
                    throws java.io.IOException,
                           EclipseException
Create a new OutOfProcessEclipse using the supplied options.

Parameters:
options - settings for the new ECLiPSe engine.
Throws:
java.io.IOException - if the connection to the child process failed
EclipseException - if there was a problem setting up the ECLiPSe side of the connection.
Method Detail

isUsingQueues

public boolean isUsingQueues()
Description copied from interface: EclipseEngine
Query the ECLiPSe engine's "use queues" flag. If true, ECLiPSe's standard streams (stdin, stdout and stderr) have been linked to FromEclipseQueue/ToEclipseQueue objects: if false, they have been linked to the operating system standard streams.

Specified by:
isUsingQueues in interface EclipseEngine

getEclipseStdin

public ToEclipseQueue getEclipseStdin()
                               throws EclipseTerminatedException
Description copied from interface: EclipseEngine
Return a ToEclipseQueue which allows access to the ECLiPSe engine's stdin stream. Returns null if the ECLiPSe was not set up to use queue objects for its standard streams (see EclipseEngineOptions).

Specified by:
getEclipseStdin in interface EclipseEngine
Throws:
EclipseTerminatedException - if the ECLiPSe engine has been destroyed or disconnected.

getEclipseStdout

public FromEclipseQueue getEclipseStdout()
                                  throws EclipseTerminatedException
Description copied from interface: EclipseEngine
Return a FromEclipseQueue which allows access to the ECLiPSe engine's stdout stream. Returns null if the ECLiPSe was not set up to use queue objects for its standard streams (see EclipseEngineOptions).

Specified by:
getEclipseStdout in interface EclipseEngine
Throws:
EclipseTerminatedException - if the ECLiPSe engine has been destroyed.

getEclipseStderr

public FromEclipseQueue getEclipseStderr()
                                  throws EclipseTerminatedException
Description copied from interface: EclipseEngine
Return a FromEclipseQueue which allows access to the ECLiPSe engine's stderr stream. Returns null if the ECLiPSe was not set up to use queue objects for its standard streams (see EclipseEngineOptions).

Specified by:
getEclipseStderr in interface EclipseEngine
Throws:
EclipseTerminatedException - if the ECLiPSe engine has been destroyed.

destroy

public void destroy()
             throws java.io.IOException
Terminate the OutOfProcessEclipse process and the connection to it. After destroy() has been invoked, future invocations of public methods will throw EclipseTerminatedExceptions

Throws:
EclipseTerminatedException - if the destroy() method had already been called.
java.io.IOException

rpc

public CompoundTerm rpc(java.lang.String goal)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Make an "RPC" (remote predicate call) to the ECLiPSe engine.

Specified by:
rpc in interface EclipseConnection
Parameters:
goal - the goal as it would be typed in on the ECLiPSe command line, (the full stop is unnecessary).
Returns:
a CompoundTerm representing the goal, with any variables possibly further instantiated with the results of the computation.
Throws:
java.io.IOException - if there was an I/O problem communicating with the ECLiPSe engine.
EclipseException - if execution of the goal fails or throws an ECLiPSe exception.

rpc

public CompoundTerm rpc(CompoundTerm goal)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Make an "RPC" (remote predicate call) to the ECLiPSe engine.

Specified by:
rpc in interface EclipseConnection
Parameters:
goal - the goal represented as a CompoundTerm.
Returns:
a CompoundTerm representing the goal, with any variables possibly further instantiated with the results of the computation.
Throws:
EclipseException - if execution of the goal fails or throws an ECLiPSe exception.
java.io.IOException - if there was an I/O problem communicating with the ECLiPSe engine.

getFromEclipseQueue

public FromEclipseQueue getFromEclipseQueue(java.lang.String name)
                                     throws EclipseException,
                                            java.io.IOException
Description copied from interface: EclipseConnection
Create or access a queue to transfer data from ECLiPSe to Java. If a FromEclipseQueue with this name has already been created for this EclipseConnection, it is returned. The supplied name should not be in use by any ECLiPSe stream which is not a FromEclipseQueue between ECLiPSe and this EclipseConnection: if it is, an EclipseException is thrown. Otherwise, a new FromEclipseQueue with the specified name is returned.

Specified by:
getFromEclipseQueue in interface EclipseConnection
Parameters:
name - the name to be used for the stream representing the queue on the ECLiPSe side.
Returns:
a FromEclipseQueue object which can be used by Java to read data on the queue which was written there by ECLiPSe.
Throws:
java.io.IOException - if there was an I/O problem while accessing ECLiPSe.
EclipseException - if the name for the ECLiPSe stream is already in use, or ECLiPSe could not create its side of the queue for some reason.

getToEclipseQueue

public ToEclipseQueue getToEclipseQueue(java.lang.String name)
                                 throws EclipseException,
                                        java.io.IOException
Description copied from interface: EclipseConnection
Create or access a queue to transfer data from Java to ECLiPSe. If a ToEclipseQueue with this name has already been created for this EclipseConnection, it is returned. The supplied name should not be in use by any ECLiPSe stream which is not a ToEclipseQueue between ECLiPSe and this EclipseConnection: if it is, an EclipseException is thrown. Otherwise, a new ToEclipseQueue with the specified name is returned.

Specified by:
getToEclipseQueue in interface EclipseConnection
Parameters:
name - the name to be used for the stream representing the queue on the ECLiPSe side.
Returns:
a ToEclipseQueue object which can be used by Java to write data on the queue which can be read by ECLiPSe.
Throws:
java.io.IOException - if there was an I/O problem while accessing ECLiPSe.
EclipseException - if the name for the ECLiPSe stream is already in use, or ECLiPSe could not create its side of the queue for some reason.

getAsyncEclipseQueue

public AsyncEclipseQueue getAsyncEclipseQueue(java.lang.String name)
                                       throws EclipseException,
                                              java.io.IOException
Description copied from interface: EclipseConnection
Create or access an asynchronous queue to transfer data between Java and ECLiPSe. If an AsyncEclipseQueue with this name has already been created for this EclipseConnection, it is returned. The supplied name should not be in use by any ECLiPSe stream which is not a AsyncEclipseQueue between ECLiPSe and this EclipseConnection: if it is, an EclipseException is thrown. Otherwise, a new AsyncEclipseQueue with the specified name is returned.

Specified by:
getAsyncEclipseQueue in interface EclipseConnection
Parameters:
name - the name to be used for the stream representing the queue on the ECLiPSe side.
Returns:
a AsyncEclipseQueue object which can be used by Java to obtain an InputStream object (which can be used to read data from the queue which was written there by ECLiPSe) and/or an OutputStream object (which can be used to write data on the queue which can be read by ECLiPSe).
Throws:
java.io.IOException - if there was an I/O problem while accessing ECLiPSe.
EclipseException - if the name for the ECLiPSe stream is already in use, or ECLiPSe could not create its side of the queue for some reason.

compile

public void compile(java.io.File f)
             throws EclipseException,
                    java.io.IOException
Description copied from interface: EclipseConnection
Direct ECLiPSe to compile a named object file.

Specified by:
compile in interface EclipseConnection
Throws:
java.io.IOException - if there was an I/O problem while communicating with ECLiPSe.
EclipseException - if ECLiPSe failed or threw an exception whilst trying to compile the file.

getPath

public java.lang.String getPath(java.io.File f)
                         throws EclipseException,
                                java.io.IOException
Description copied from interface: EclipseConnection
Convert a file path from the Java representation to the ECLiPSe representation.

Specified by:
getPath in interface EclipseConnection
Parameters:
f - the file path to be converted.
Returns:
a String: the file path in the ECLiPSe representation
Throws:
java.io.IOException - if there was an I/O problem while communicating with ECLiPSe.
EclipseException - if ECLiPSe failed or threw an exception whilst trying to convert the file path.

rpc

public CompoundTerm rpc(java.lang.String functor,
                        java.lang.Object arg1)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Convenience rpc method. The user supplies the functor string and 1 argument.

Specified by:
rpc in interface EclipseConnection
Throws:
EclipseException
java.io.IOException
See Also:
EclipseConnection.rpc(CompoundTerm)

rpc

public CompoundTerm rpc(java.lang.String functor,
                        java.lang.Object arg1,
                        java.lang.Object arg2)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Convenience rpc method. The user supplies the functor string and 2 arguments.

Specified by:
rpc in interface EclipseConnection
Throws:
EclipseException
java.io.IOException
See Also:
EclipseConnection.rpc(CompoundTerm)

rpc

public CompoundTerm rpc(java.lang.String functor,
                        java.lang.Object arg1,
                        java.lang.Object arg2,
                        java.lang.Object arg3)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Convenience rpc method. The user supplies the functor string and 3 arguments.

Specified by:
rpc in interface EclipseConnection
Throws:
EclipseException
java.io.IOException
See Also:
EclipseConnection.rpc(CompoundTerm)

rpc

public CompoundTerm rpc(java.lang.String functor,
                        java.lang.Object arg1,
                        java.lang.Object arg2,
                        java.lang.Object arg3,
                        java.lang.Object arg4)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Convenience rpc method. The user supplies the functor string and 4 arguments.

Specified by:
rpc in interface EclipseConnection
Throws:
EclipseException
java.io.IOException
See Also:
EclipseConnection.rpc(CompoundTerm)

rpc

public CompoundTerm rpc(java.lang.String functor,
                        java.lang.Object arg1,
                        java.lang.Object arg2,
                        java.lang.Object arg3,
                        java.lang.Object arg4,
                        java.lang.Object arg5)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Convenience rpc method. The user supplies the functor string and 5 arguments.

Specified by:
rpc in interface EclipseConnection
Throws:
EclipseException
java.io.IOException
See Also:
EclipseConnection.rpc(CompoundTerm)

rpc

public CompoundTerm rpc(java.lang.String functor,
                        java.lang.Object[] args)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Convenience rpc method. The user supplies the functor string and an array of arguments.

Specified by:
rpc in interface EclipseConnection
Throws:
EclipseException
java.io.IOException
See Also:
EclipseConnection.rpc(CompoundTerm)

rpc

public CompoundTerm rpc(java.lang.Object[] goalTerm)
                 throws EclipseException,
                        java.io.IOException
Description copied from interface: EclipseConnection
Convenience rpc method. The user supplies an array. Element 0 is the functor of the goal term and the remaining elements are the arguments.

Specified by:
rpc in interface EclipseConnection
Throws:
EclipseException
java.io.IOException
See Also:
EclipseConnection.rpc(CompoundTerm)

getPeerName

public Atom getPeerName()
Description copied from interface: EclipseConnection
Return the name by which the peer representing the Java side of the connection is indexed in ECLiPSe.

Specified by:
getPeerName in interface EclipseConnection
Returns:
an Atom, the peer name.

registerMultitask

public EclipseMultitaskConnection registerMultitask(MultitaskListener multitaskListener)
                                             throws EclipseException,
                                                    java.io.IOException
Description copied from interface: EclipseConnection
Register this peer as desiring participation in any multitasking phases that ECLiPSe enters.

Specified by:
registerMultitask in interface EclipseConnection
Parameters:
multitaskListener - A listener whose methods are called when ECLiPSe enters/leaves multitasking phases.
Returns:
An object which can be used to perform RPCs during ECLiPSe multitasking phases.
Throws:
java.io.IOException - if there was an I/O problem communicating with the ECLiPSe engine.
EclipseException - if registration fails or throws an ECLiPSe exception.