RemoteEclipse
Date: 2022-09-03

com.parctechnologies.eclipse

## Class RemoteEclipse

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

- All Implemented Interfaces:
    EclipseConnection

      public class RemoteEclipse
      extends EclipseConnectionImpl
      implements EclipseConnection

  Remote connection to an existing ECLiPSe process. The connection may be made over a TCP/IP network to an ECLiPSe which has been primed using the `remote_connect/3` or the `remote_connect_setup/3` builtin predicates. As well as the functionality provided by the EclipseConnection interface, RemoteEclipse also allows for execution control to be transferred explicity over to ECLiPSe with the `resume()` method.

  The connection is terminated from the Java side using either the `disconnect()` method (when Java has execution control) or `unilateralDisconnect()` (when ECLiPSe has execution control). If the builtin predicate `remote_disconnect/1` is executed on the ECLiPSe side, the effect on the Java side are similar to the effects of `disconnect()`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_TIMEOUT_MILLIS`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RemoteEclipse(java.net.InetAddress remoteEclipseHost, int remoteEclipsePort)` Make a connection to an existing ECLiPSe process.
    `RemoteEclipse(java.net.InetAddress remoteEclipseHost, int remoteEclipsePort, int timeoutMillis)` Make a connection to an existing ECLiPSe process.
    `RemoteEclipse(java.net.InetAddress remoteEclipseHost, int remoteEclipsePort, java.lang.String passwd)` Make a connection to an existing ECLiPSe process.
    `RemoteEclipse(java.net.InetAddress remoteEclipseHost, int remoteEclipsePort, java.lang.String passwd, int timeoutMillis)` Make a connection to an existing ECLiPSe process.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `disconnect()` Terminate the remote connection to ECLiPSe.
    `void` | `resume()` Explicitly transfer execution control to ECLiPSe.
    `void` | `unilateralDisconnect()` Terminate the connection with ECLiPSe unilaterally.

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

      `compile, getAsyncEclipseQueue, 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, getAsyncEclipseQueue, getFromEclipseQueue, getPath, getPeerName, getToEclipseQueue, registerMultitask, rpc, rpc, rpc, rpc, rpc, rpc, rpc, rpc, rpc`

- - ### Field Detail

    - #### DEFAULT_TIMEOUT_MILLIS

          public static final int DEFAULT_TIMEOUT_MILLIS

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RemoteEclipse

          public RemoteEclipse(java.net.InetAddress remoteEclipseHost,
                               int remoteEclipsePort,
                               java.lang.String passwd)
                        throws java.io.IOException

      Make a connection to an existing ECLiPSe process. The ECLiPSe process must be on a server machine which is reachable on a TCP/IP network. ECLiPSe must be primed using `remote_connect_setup/3`. The builtin predicate `remote_connect_accept/6` should then be used to complete the connection. The connection details (IP address, port number, password) are specified as parameters and must match those specified/returned as arguments in the execution of `remote_connect_setup/3` and `remote_connect_accept/6`.
      Throws:
        `java.io.IOException` - if the connection could not be made, or times out within `DEFAULT_TIMEOUT_MILLIS` milliseconds.

    - #### RemoteEclipse

          public RemoteEclipse(java.net.InetAddress remoteEclipseHost,
                               int remoteEclipsePort)
                        throws java.io.IOException

      Make a connection to an existing ECLiPSe process. The ECLiPSe process must be on a server machine which is reachable on a TCP/IP network. ECLiPSe must be primed using `remote_connect/3`. The connection details (IP address, port number) are specified as parameters and must match those specified/returned as arguments in the execution of `remote_connect/3`. If `remote_connect_setup/3`. was used to prime ECLiPSe for the remote connection, this constructor will fail as it does not use a password.
      Throws:
        `java.io.IOException` - if the connection could not be made, or times out within `DEFAULT_TIMEOUT_MILLIS` milliseconds.

    - #### RemoteEclipse

          public RemoteEclipse(java.net.InetAddress remoteEclipseHost,
                               int remoteEclipsePort,
                               int timeoutMillis)
                        throws java.io.IOException

      Make a connection to an existing ECLiPSe process. The ECLiPSe process must be on a server machine which is reachable on a TCP/IP network. ECLiPSe must be primed using `remote_connect/3`. The connection details (IP address, port number) are specified as parameters and must match those specified/returned as arguments in the execution of `remote_connect/3`. If `remote_connect_setup/3`. was used to prime ECLiPSe for the remote connection, this constructor will fail as it does not use a password.
      Parameters:
        `timeoutMillis` - number of milliseconds to wait for the initial connection to be established before throwing an exception. Set `timeoutMillis` to 0 to wait indefinitely for the connection.
      Throws:
        `java.io.IOException` - if the connection could not be made, or times out within `timeoutMillis` milliseconds.

    - #### RemoteEclipse

          public RemoteEclipse(java.net.InetAddress remoteEclipseHost,
                               int remoteEclipsePort,
                               java.lang.String passwd,
                               int timeoutMillis)
                        throws java.io.IOException

      Make a connection to an existing ECLiPSe process. The ECLiPSe process must be on a server machine which is reachable on a TCP/IP network. ECLiPSe must be primed using `remote_connect_setup/3`. The builtin predicate `remote_connect_accept/6` should then be used to complete the connection. The connection details (IP address, port number, password) are specified as parameters and must match those specified/returned as arguments in the execution of `remote_connect_setup/3` and `remote_connect_accept/6`.
      Parameters:
        `timeoutMillis` - number of milliseconds to wait for the initial connection to be established before throwing an exception. Set `timeoutMillis` to 0 to wait indefinitely for the connection.
      Throws:
        `java.io.IOException` - if the connection could not be made, or times out within `timeoutMillis` milliseconds.

  - ### Method Detail

    - #### unilateralDisconnect

          public void unilateralDisconnect()
                                    throws EclipseTerminatedException

      Terminate the connection with ECLiPSe unilaterally. This method should be invoked in unforseen circumstances when the connection should be terminated while ECLiPSe has execution control. After `unilateralDisconnect` has been invoked, public methods invoked on this RemoteEclipse will throw EclipseTerminatedExceptions.
      Throws:
        `EclipseTerminatedException` - if the connection has already been terminated.

    - #### disconnect

          public void disconnect()
                          throws java.io.IOException

      Terminate the remote connection to ECLiPSe. This should be invoked while Java has control. If ECLiPSe has control then use `unlateralDisconnect` instead. After `disconnect` has been invoked, public methods invoked on this RemoteEclipse will throw EclipseTerminatedExceptions.
      Throws:
        `EclipseTerminatedException` - if the connection has already been terminated.
        `java.io.IOException` - if there was a problem communicating with ECLiPSe during disconnection.

    - #### resume

          public void resume()
                      throws java.io.IOException

      Explicitly transfer execution control to ECLiPSe. ECLiPSe will resume execution immediately after the last goal which transferred control to Java (normally `remote_connect/3` or `remote_connect_setup/3`). This method should not be invoked while control has been transferred to Java using a QueueListener. An invocation of `resume()` should normally be paired with an execution of the builtin predicate `remote_yield/1`, which can return execution control to Java.
      Throws:
        `EclipseTerminatedException` - if the connection to ECLiPSe has been terminated.
        `java.io.IOException` - if there was a problem communicating with ECLiPSe.