EmbeddedEclipse
Date: 2022-09-03

com.parctechnologies.eclipse

## Class EmbeddedEclipse

- java.lang.Object
- - com.parctechnologies.eclipse.EclipseConnectionImpl
  - - com.parctechnologies.eclipse.EmbeddedEclipse

- All Implemented Interfaces:
    EclipseConnection, EclipseEngine

      public class EmbeddedEclipse
      extends EclipseConnectionImpl
      implements EclipseConnection, EclipseEngine

  An ECLiPSe engine embedded in the JVM process. Since there can only be one embedded ECLiPSe engine at any one time, there is no public constructor and you should use the `getInstance(EclipseEngineOptions)` method to create an embedded ECLiPSe engine if none exists. The `EclipseEngineOptions` object should be created, configured, and then passed to this method to start the ECLiPSe with user-defined options.

  Once started, a reference to the EmbeddedEclipse instance can be obtained using the `getInstance()` method. Note that once the EmbeddedEclipse has been shut down by calling its `destroy()` method, no more embedded ECLiPSe engines can be started using `getInstance(EclipseEngineOptions)`. Here is some example code for working with an EmbeddedEclipse:

  >      // create a new EclipseEngineOptions object
  >      EclipseEngineOptions options = new EclipseEngineOptions(new File("C:\Eclipse\"));
  >      // alter the useQueues option
  >      options.setUseQueues(true);
  >      // start up the embedded Eclipse. testEclipse is a reference to the
  >      // Eclipse engine.
  >      EclipseEngine testEclipse = EmbeddedEclipse.getInstance(options);
  >      // Direct the Eclipse to load a source file.
  >      testEclipse.compile(new File(".\myEclipseSourceFile.pl"));
  >      // Execute a top-level goal in ECLiPSe.
  >      testEclipse.rpc("go");
  >      // Destroy the Eclipse
  >      ((EmbeddedEclipse) testEclipse).destroy();

  See Also:
    `EclipseConnection`, `EclipseEngine`, `EclipseEngineOptions`

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Terminate access to the EmbeddedEclipse.
    `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.
    `static EmbeddedEclipse` | `getInstance()` Returns the unique EmbeddedEclipse object if the embedded ECLiPSe has been started, but not yet terminated in this JVM.
    `static EmbeddedEclipse` | `getInstance(EclipseEngineOptions options)` If the embedded ECLiPSe has not yet been started in this JVM, start the embedded ECLiPSe using the options specified in the parameter EclipseEngineOptions.
    `boolean` | `isUsingQueues()` Query the ECLiPSe engine's "use queues" flag.

    - ### Methods inherited from class com.parctechnologies.eclipse.EclipseConnectionImpl

      `compile, getFromEclipseQueue, getPath, getPeerName, getToEclipseQueue, registerMultitask, rpc, rpc, rpc, rpc, rpc, rpc, rpc, rpc, rpc`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface com.parctechnologies.eclipse.EclipseConnection

      `compile, getFromEclipseQueue, getPath, getPeerName, getToEclipseQueue, registerMultitask, rpc, rpc, rpc, rpc, rpc, rpc, rpc, rpc, rpc`

- - ### Method Detail

    - #### getInstance

          public static EmbeddedEclipse getInstance(EclipseEngineOptions options)
                                             throws EclipseException,
                                                    java.io.IOException

      If the embedded ECLiPSe has not yet been started in this JVM, start the embedded ECLiPSe using the options specified in the parameter EclipseEngineOptions.
      Parameters:
        `options` - user-definable options used to configure the embedded ECLiPSe engine.
      Throws:
        `EclipseException` - if the embedded ECLiPSe has already been started, or if there was some ECLiPSe-related problem whilst attempting to start ECLiPSe, for example if the ECLiPSe installation directory was not set in the supplied EclipseEngineOptions object.
        `EclipseTerminatedException` - if the embedded ECLiPSe has already been terminated
        `java.io.IOException` - if there is some other I/O-related problem starting the ECLiPSe engine.

    - #### getInstance

          public static EmbeddedEclipse getInstance()
                                             throws EclipseException,
                                                    java.io.IOException

      Returns the unique EmbeddedEclipse object if the embedded ECLiPSe has been started, but not yet terminated in this JVM.
      Throws:
        `EclipseException` - if ECLiPSe has not been started.
        `EclipseTerminatedException` - if the embedded ECLiPSe has been terminated.
        `java.io.IOException`

    - #### 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`
      Overrides:
        `getAsyncEclipseQueue` in class `EclipseConnectionImpl`
      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.

    - #### destroy

          public void destroy()
                       throws java.io.IOException

      Terminate access to the EmbeddedEclipse. This closes the embedded ECLiPSe engine and frees all system resources associated with it. After `destroy()` has been invoked, use of this EmbeddedEclipse's methods will throw EclipseTerminatedExceptions. Also, once `destroy()` has been invoked, no more EmbeddedEclipse instances can be created during the lifetime of this Java virtual machine.
      Throws:
        `EclipseTerminatedException` - if the ECLiPSe engine has already been terminated.
        `java.io.IOException` - if there was a problem communicating with ECLiPSe during termination.

    - #### 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.

    - #### 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`