8.7  Managing connections to ECLⁱPS^e

• A unified ECLⁱPS^e-side interface to Java : the ‘peer’ concept
• Creating and managing ECLⁱPS^e engines from Java
• Connecting to an existing ECLⁱPS^e engine using RemoteEclipse
• Comparison of different Java-ECLⁱPS^e connection techniques

As of ECLⁱPS^e 5.3 and later, there are three Java classes which can be used to provide interaction with ECLⁱPS^e. These are EmbeddedEclipse, OutOfProcessEclipse and RemoteEclipse. Although the three classes all implement the EclipseConnection interface, there are some important differences in initialisation, termination and use which are explained in this section. On the ECLⁱPS^e side, as of version 5.3 and later, there is a unified interface for interaction with Java, based around the concept of a ‘peer’. This is explained in Section 8.7.1. Section 8.7.2 discusses how to create an ECLⁱPS^e engine from within Java (this covers both EmbeddedEclipse and OutOfProcessEclipse). Section 8.7.3 discusses the RemoteEclipse class, which allows Java to connect to an existing ECLⁱPS^e engine. Finally, Section 8.7.4 compares the three connection classes, assessing the advantages and disadvantages of each.

8.7.1  A unified ECLⁱPS^e-side interface to Java : the ‘peer’ concept

To allow ECLⁱPS^e code to be independent of the way it is interfacing with Java, there is a unified technique in ECLⁱPS^e for interfacing to Java and other non-ECLⁱPS^e programs, based on the concept of a peer. A peer is a computation environment which is external to ECLⁱPS^e, either in the sense of being a different computer language or being a different process, possibly on a different machine. When ECLⁱPS^e is communicating with one or more Java virtual machines using the Java-ECLⁱPS^e interface (including cases where ECLⁱPS^e is embedded), it stores some global information to keep track of each peer.

Each peer of the ECLⁱPS^e engine is indexed within ECLⁱPS^e by a unique peer name which is an atom. This is set during the initialisation of the connection between ECLⁱPS^e and Java; the details vary according to the Java class used to make the connection.

The peer name is used in those ECLⁱPS^e predicate calls related to the peer connection. In particular, those related to the opening and closing of peer queues (see Section 8.5.1). The EclipseConnection interface includes the method getPeerName() which can be used to retrieve this name on the Java side.

8.7.2  Creating and managing ECLⁱPS^e engines from Java

There are at present two options for creating an ECLⁱPS^e engine from Java. With EmbeddedEclipse, the engine takes the form of a dynamically loaded shared library within the Java virtual machine. With OutOfProcessEclipse it is a separate, child process of the Java virtual machine. These two options have in common that they are both initialised using an EclipseEngineOptions object and that both classes implement EclipseEngine .

Configuring an EclipseEngineOptions object

Before an ECLⁱPS^e engine is created using either option, an EclipseEngineOptions object must be created and configured. An instance of the EclipseEngineOptions class represents our configuration choices for a new ECLⁱPS^e engine.

The options can be specified by either looking them up in a java.util.Properties instance or by calling “set” methods on the EclipseEngineOptions instance.

In the first case you can either specify system properties (by passing -D command line options to the JVM) or you can use an EclipseEngineOptions constructor which takes a Properties parameter. Each option has a standard property name detailed below.

Once the EclipseEngineOptions object is created, there are also “set” methods we can invoke on it to set the different options.

The ECLⁱPS^e installation directory (eclipse.directory)

This must be the correct path of an ECLⁱPS^e installation so that Java can find the files it needs to start ECLⁱPS^e. If an EclipseEngineOptions constructor is invoked without a directory having been set, either using a constructor parameter or as a property, an exception will be thrown.

The default module (eclipse.default-module)

is the default ECLⁱPS^e module where goals are executed. If no setting is made, then the default module will be “eclipse”.

Local and global size (eclipse.local-size and eclipse.global-size)

are the maximum size of the local stack and the global stack respectively. In each case the option is an integer representing the required size in megabytes. If no setting is made, the sizes default to the ECLⁱPS^e defaults.

Local size

is the maximum combined size of the local stack and the control stack. Roughly speaking, the local stack is the ECLⁱPS^e equivalent of the call/return stack in procedural languages. The control stack is used to store the choicepoints which occur in the execution of non-deterministic code. You may therefore need to increase this limit if your search tree is exceptionally deep or if there is a lot of non-determinism. You can use the ECLⁱPS^e goal get_flag(max_local_control, X) to find out the current setting. For more details, see the section on “Memory Organisation and Garbage Collection” in the ECLⁱPS^e User Manual.

Global size

is the maximum combined size of the global stack and the trail stack. The global stack is used to store data structures. The trail stack is used to store backtracking information and is therefore closely related to the control stack. You may need to increase this limit if you are creating large data structures in ECLⁱPS^e, or if there is a lot of non-determinism. You can use the ECLⁱPS^e goal get_flag(max_global_trail, X) to find out the current setting. Again, see the section in the ECLⁱPS^e User Manual for more details.

The “use queues” flag (eclipse.use-queues)

If false (the default case), the ECLⁱPS^e engine’s standard streams (stdin, stdout and stderr) will be connected to the standard streams of the JVM. So for example if, as in QuickTest.java, a message is written to stdout from within ECLⁱPS^e, this will appear on the stdout stream of the JVM. Similarly, if ECLⁱPS^e requests input from the stdin stream, input will be requested from the stdin stream of the JVM. If the flag is set true, FromEclipseQueue and ToEclipseQueue objects are used to represent the ECLⁱPS^e’s standard streams.

The peer name (eclipse.peer-name)

is the peer name by which the Java side can be referenced within ECLⁱPS^e, for example when queues are created from the ECLⁱPS^e side. By default the peer name for the Java side when using an EmbeddedEclipse or an OutOfProcessEclipse is “host”.

Using EmbeddedEclipse

This section discusses issues specific to using the EmbeddedEclipse class. With EmbeddedEclipse, the ECLⁱPS^e engine is a dynamically loaded native library in the Java virtual machine. Figure 8.1 shows this deployment model in UML notation. The important consequences of this deployment model are:

• The ECLⁱPS^e engine shares memory and other resources with Java.
• Only one such engine can exist in a Java virtual machine at any one time.
• Communication between Java and ECLⁱPS^e is very efficient.

Initialising an EmbeddedEclipse

The embedded ECLⁱPS^e which runs within the JVM and shares its resources, can be started and ended only once during the lifetime of the JVM. There is no public constructor method for EmbeddedEclipse. Initialisation of the embedded ECLⁱPS^e is done using the static getInstance method of class EmbeddedEclipse which takes an EclipseEngineOptions instance as a parameter. The method uses this to configure and set up ECLⁱPS^e and then returns an object of type EmbeddedEclipse. There may only ever be one instance of EmbeddedEclipse in a JVM. If the embedded ECLⁱPS^e has already been set up or if it has been set up and terminated, subsequent invocations of getEclipse with an EclipseEngineOptions will throw exceptions. However during the lifetime of the embedded ECLⁱPS^e, a reference to the unique EmbeddedEclipse object can be obtained using the parameterless static getEclipse method.

Termination of an EmbeddedEclipse

The destroy method which appears in the EmbeddedEclipse class will shut the embedded ECLⁱPS^e down. Once the destroy method has been invoked, the invocation of any methods which require use of the ECLⁱPS^e engine will result in an EclipseTerminatedException being thrown. The destroy method should free all the resources of the JVM process which were being used by the embedded ECLⁱPS^e.

Once the EmbeddedEclipse has been destroyed, getEclipse can no longer be used during the lifetime of the JVM to initialise an embedded ECLⁱPS^e engine. In other words, by invoking destroy, one removes the ability to use embedded ECLⁱPS^e engines within the current instance of the JVM.

Using OutOfProcessEclipse

This section discusses issues specific to the OutOfProcessEclipse class. With OutOfProcessEclipse, the ECLⁱPS^e engine is a child process of the Java virtual machine. Figure 8.2 shows this deployment model in UML notation. The important consequences of this deployment model are:

• The ECLⁱPS^e engine uses separate memory and other resources, depending on how the operating system allocates these between processes.
• Several instances of OutOfProcessEclipse can exist in a Java virtual machine at any one time.
• Communication between Java and ECLⁱPS^e is less efficient.

Initialisation of an OutOfProcessEclipse

OutOfProcessEclipse has a single constructor which takes an EclipseEngineOptions object as its only parameter. See Section 8.7.2 for details of how to create and configure this object. Unlike EmbeddedEclipse, multiple OutOfProcessEclipse instances are allowed.

Termination of an OutOfProcessEclipse

We invoke the instance method destroy() in OutOfProcessEclipse to terminate both the child ECLⁱPS^e process and our association with it. Once the destroy method has been invoked, the invocation of any methods on the destroyed OutOfProcessEclipse object which require use of the ECLⁱPS^e engine will throw an EclipseTerminatedException. Unlike EmbeddedEclipse, invoking destroy() on an OutOfProcessEclipse does not affect our ability to create new OutOfProcessEclipse instances during the lifetime of the Java virtual machine.

If the child process ECLⁱPS^e crashes or is killed while ECLⁱPS^e has control, the Java thread which handed control to ECLⁱPS^e should throw an EclipseTerminatedException. If this happens while Java has control, usually the next invocation of a method on the OutOfProcesEclipse should throw an EclipseTerminatedException, although it is possible that some operations will throw a different class of IOException. If this should happen it is worth calling the destroy method to do a final clean-up.

8.7.3  Connecting to an existing ECLⁱPS^e engine using RemoteEclipse

In some applications, for example where Java is used to visualise search in ECLⁱPS^e, the life of the ECLⁱPS^e engine may begin before the connection with Java is initialised or end after the connection with Java is terminated. Furthermore, it may also be useful for the eclipse engine and the Java virtual machine to be running on physically separate computers, for example if the ECLⁱPS^e tasks are being executed on a compute server, but the Java program is to be run on a workstation. The RemoteEclipse class can be used to connect Java to ECLⁱPS^e in these two scenarios. The deployment model is that the RemoteEclipse Java object is a “Proxy” for the ECLⁱPS^e engine which is running on the remote machine, as shown in UML notation in Figure 8.3.

The key consequences of this deployment model are:

• ECLⁱPS^e and Java can run on different machines and the two machines may have a different architecture/OS.
• ECLⁱPS^e can connect to multiple Java processes using this model.
• The lifetime of the ECLⁱPS^e engine need not necessarily be a sub-duration of the lifetime of the JVM.

Initialisation of a RemoteEclipse connection

Connecting Java to ECLⁱPS^e using RemoteEclipse requires the ECLⁱPS^e engine to be primed so that it is ready to accept the connection. By the time it connects, the Java program must have the IP address of the machine hosting the ECLⁱPS^e engine (the server) and the port number being used for the connection. The attachment protocol also optionally allows for a password to be used by the Java side and checked against one specified on the ECLⁱPS^e side. Also the server must be configured to allow TCP/IP socket servers which can be connected to by the machine hosting Java. Initialising a connection using RemoteEclipse therefore requires some coordination between the ECLⁱPS^e code and the Java code. The Java code always consists of a single RemoteEclipse constructor invocation, although the constructor parameters may vary.

The ECLⁱPS^e side of the code uses certain builtins. Refer to the relevant documentation of these for precise details of usage. On the ECLⁱPS^e side, the code can be structured in two different ways; one simpler and the other allowing more flexibility. We outline here the sequence of actions in each case.

Basic connection sequence

This can be used in situations where no password is to be used and where the port number is specified in advance, rather than generated dynamically by ECLⁱPS^e, and is known by the Java side.

1. The ECLⁱPS^e side executes the builtin remote_connect/3, specifying the port number in advance. This builtin will block until the connection is established.
2. The Java side then invokes one of the RemoteEclipse constructors which has no password parameter. This should immediately complete or throw an exception if the connection is unsuccessful.

Advanced connection sequence

This more complicated sequence uses a password and optionally allows the port number to be generated dynamically and then communicated to the Java side.

1. The ECLⁱPS^e side executes the builtin remote_connect_setup/3, specifying the password and either specifying the port number or allowing it to be generated dynamically.
2. The port number must be communicated to the Java side somehow, e.g. manually, or via a file.
3. The Java side then invokes one of the RemoteEclipse constructors with a password parameter. This either blocks until the connection is successful or throws an exception.
4. The ECLⁱPS^e side executes the builtin remote_connect_accept/6, specifying the password which the Java should supply.
5. The Java constructor invocation then completes, or throws an exception if the connection could not be made.

If left as a free variable, the Host argument of either the remote_connect/3 or remote_connect_setup/3 goal will become instantiated to the IP address of the machine hosting ECLⁱPS^e. Another possibility is to call the goal with this argument already instantiated to the atom localhost. This will mean that only client connections made by processes on the same machine and using the loopback address will be accepted. With this usage, on the Java side you should use invoke InetAddress.getHostByName("localhost"). Note that InetAddress.getLocalHost() will not work in this situation.

In both connection sequences, the peer name indexing the connection is either specified or generated dynamically on the ECLⁱPS^e side in the remote_connect/3 or remote_connect_setup/3 goal.

Once the connection has been established by one of the above sequences, control initially rests with the Java side. Therefore the ECLⁱPS^e code which called the remote_connect/3 goal or the remote_connect_accept/6 goal blocks until the Java side explicitly transfers control to ECLⁱPS^e or disconnects.

Explicit transfer of control between ECLⁱPS^e and Java

As mentioned above, after the initial connection has been established, Java has control by default. However, this may not be convenient. For example, in the case of search visualisation, after the initialisation of the visualisation client, we may prefer ECLⁱPS^e to have control by default, allowing control to pass to Java only on certain occasions. Control can be explicitly passed from Java to ECLⁱPS^e by invoking the resume() method on a RemoteEclipse. In this case the ECLⁱPS^e code will resume execution after the last point where it passed control to Java. For example, if resume() is invoked immediately after the RemoteEclipse constructor completes, ECLⁱPS^e execution will resume at the point just after the call to the remote_connect/3 goal or the remote_connect_accept/6 goal.

Control can be transferred to a Java peer using the remote_yield/1 builtin. In this case the Java thread which passed execution to ECLⁱPS^e will resume execution at the point where it blocked.

The resume() method and the remote_yield/1 builtin should be used with care. An invocation of resume() should be paired with an execution of a remote_yield/1 goal in most cases. In addition, remote_yield/1 should not be executed in any code executed as a result of an rpc invocation and resume() should not be executed within the QueueListener methods dataAvailable() or dataRequest().

The resume() method and the remote_yield/1 builtin should only be used when other techniques such as rpc are not suitable.

Termination of a RemoteEclipse connection

A RemoteEclipse connection between ECLⁱPS^e and Java may be terminated in different ways. Firstly, disconnection may be initiated by either side. Secondly the disconnection may be either multilateral or unilateral. Multilateral disconnection, the preferred method, is where the side which has control initiates disconnection. Unilateral disconnection is where the side which initiates disconnection does not have control, and should only take place as a clean-up routine when one side is forced to terminate the connection because of an unexpected event.

Java-initiated multilateral disconnect

is performed by invoking the disconnect method on the RemoteEclipse instance while the Java side has control.

Java-initiated unilateral disconnect

is performed by invoking the unilateralDisconnect method on the RemoteEclipse instance while Java does not have control.

ECLⁱPS^e-initiated multilateral disconnect

is performed on the ECLⁱPS^e side by executing a remote_disconnect/1 goal while ECLⁱPS^e has control, identifying the connection to be closed by supplying the peer name.

ECLⁱPS^e-initiated unilateral disconnect

cannot be executed by the user, since ECLⁱPS^e is not multi-threaded. However, it may occur in certain urgent situations e.g. if the ECLⁱPS^e process is killed while ECLⁱPS^e does not have control.

If an ECLⁱPS^e-initiated disconnect occurs, or the connection is lost for whatever reason while ECLⁱPS^e has control, the Java thread which handed control to ECLⁱPS^e should throw an EclipseTerminatedException. If either of these happens while Java has control, the next invocation of a method on the RemoteEclipse should throw an EclipseTerminatedException, although it is possible that some operations will throw a different class of IOException. If this should happen it is worth invoking the unilateralDisconnect() method to do a final clean-up.

8.7.4  Comparison of different Java-ECLⁱPS^e connection techniques

This section should give you some idea of when it is most appropriate to use each connection class. Figure 8.4 is a UML class diagram showing the most important relationships and operations of the principal classes and interfaces.

All three classes implement EclipseConnection , which provides all the functionality you would expect during a “session” with ECLⁱPS^e. The EclipseEngine interface is implemented when the JVM “owns” the ECLⁱPS^e engine, and so provides the methods to access the standard I/O streams. Note that the termination methods are not in either of the interfaces, but are specific to each class. Furthermore, the resume() method allows RemoteEclipse to explicitly hand control to ECLⁱPS^e, but this operation is not supported by the other two classes.

To summarise the advantages and disadvantages Table 8.2 gives an at-a-glance comparison of the different features of the different connection classes.

---

Feature	Java-ECLiPSe connection class
	Embedded	OutOfProcess	Remote
Implements EclipseConnection interface (allowing rpc and queues)	•	•	•
Implements EclipseEngine interface (allowing access to ECLiPSe stdio streams)	•	•	–
ECLiPSe is in a separate process (with separate memory heap/stack)	–	•	•
ECLiPSe can be on a separate machine from Java	–	–	•
ECLiPSe engine can start before/ end after Java virtual machine	–	–	•
ECLiPSe engine created/ destroyed from Java	•	•	–
Efficient transfer of data on queues and rpc invocations	•	–	–
One ECLiPSe can connect to many Java virtual machines using this	–	–	•
One Java virtual machine can connect to many ECLiPSe engines using this	–	•	•

Table 8.2: Feature comparison table for different ECLiPSe connection classes

---