com.parctechnologies.eclipse
Class EmbeddedEclipse

java.lang.Object
  extended bycom.parctechnologies.eclipse.EclipseConnectionImpl
      extended bycom.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
 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
Throws:
EclipseException
java.io.IOException

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