OutOfProcessEclipse
Date: 2022-09-03

com.parctechnologies.eclipse

## Class OutOfProcessEclipse

- java.lang.Object
- - com.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

    Constructors
    Constructor and Description
    `OutOfProcessEclipse(EclipseEngineOptions options)` Create a new OutOfProcessEclipse using the supplied options.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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:
        `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.
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.

    - #### 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.
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.

    - #### 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:
        `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.
        `java.io.IOException` - if there was an I/O problem while accessing ECLiPSe.
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.

    - #### 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:
        `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.
        `java.io.IOException` - if there was an I/O problem while accessing ECLiPSe.
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.

    - #### 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:
        `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.
        `java.io.IOException` - if there was an I/O problem while accessing ECLiPSe.
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.

    - #### 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`
      Parameters:
        `f` - file the path of the ECLiPSe object file which is to be compiled.
      Throws:
        `EclipseException` - if ECLiPSe failed or threw an exception whilst trying to compile the file.
        `java.io.IOException` - if there was an I/O problem while communicating with ECLiPSe.
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.

    - #### 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:
        `EclipseException` - if ECLiPSe failed or threw an exception whilst trying to convert the file path.
        `java.io.IOException` - if there was an I/O problem while communicating with ECLiPSe.
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.

    - #### 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:
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.
        `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:
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.
        `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:
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.
        `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:
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.
        `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:
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.
        `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:
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.
        `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:
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.
        `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:
        `EclipseException` - if registration fails or throws an ECLiPSe exception.
        `java.io.IOException` - if there was an I/O problem communicating with the ECLiPSe engine.
        `EclipseTerminatedException` - if this EclipseConnection has been terminated.