8.2  Functionality overview: A closer look at QuickTest.java

To give a broad overview of how the Java-ECLⁱPS^e Interface works, we take a closer look at QuickTest.java. Here is the Java source code from QuickTest.java.

import com.parctechnologies.eclipse.*;
import java.io.*;

public class QuickTest
{
  public static void main(String[] args) throws Exception
  {
    // Create some default Eclipse options
    EclipseEngineOptions eclipseEngineOptions = new EclipseEngineOptions();

    // Object representing the Eclipse engine
    EclipseEngine eclipse;

    // Connect the Eclipse's standard streams to the JVM's
    eclipseEngineOptions.setUseQueues(false);

    // Initialise Eclipse
    eclipse = EmbeddedEclipse.getInstance(eclipseEngineOptions);

    // Write a message
    eclipse.rpc("write(output, 'hello world'), flush(output)");

    // Destroy the Eclipse engine
    ((EmbeddedEclipse) eclipse).destroy();
  }
}

The structure of the main method in QuickTest.java contains elements which will appear in any Java code which uses the Java-ECLⁱPS^e interface. These are as follows:

Always import the com.parctechnologies.eclipse package

Note the first line using import. We need to have this in every Java source file which uses the Java-ECLⁱPS^e Interface so that it can load classes from the package.

Declare a reference to an EclipseConnection or an EclipseEngine

EclipseConnection and its subinterface EclipseEngine are Java interfaces which contain the methods used when interacting with ECLⁱPS^e.

Create an object which implements EclipseConnection or EclipseEngine

There are a number of classes which implement these interfaces. In the case of QuickTest.java we use an instance of EmbeddedEclipse . The initialisation of these implementing classes varies from class to class. In the case of EmbeddedEclipse initialisation is done by creating and configuring an EclipseEngineOptions object and using this in an invocation of the EmbeddedEclipse class’ static method getInstance.

Interact with ECLⁱPS^e using methods in the EclipseConnection or EclipseEngine interface

We interact with the ECLⁱPS^e engine by invoking methods on the object which implements EclipseConnection or EclipseEngine . In the case of QuickTest.java we invoke the rpc method, which causes the ECLⁱPS^e to execute a goal, in this case one which simply prints a message.

Terminate interaction with the ECLⁱPS^e

In order to clean up, after the Java program has finished interacting with ECLⁱPS^e, the interaction should be terminated. Like initialisation, how this termination is done varies among the classes which implement the EclipseConnection and EclipseEngine interfaces. In the case of QuickTest.java, termination is done by invoking the destroy method on the EmbeddedEclipse object.