Launching with EASE

I have been doing some experiments with Eclipse EASE in preparation for determining the suitability – and creating a prototype – of using EASE with non-JVM scripting languages, in particular Python (CPython specifically).

To achieve this end goal I am working on a new module, /System/Launch, to allow me to explore that functionality. As a practical goal I am trying to use EASE to solve a long term problem of how to launch more complicated systems, especially those that run out of steam with the Launch Groups. For instance, multiple launches for debugging a multi-core system (especially with customizations and interdependencies) or parametrization of job launches.

Scripted Launch Group

As a starting point I want to simply re-create what Launch Groups can do in Javascript. So with EASE installed, including my new module, this is what a simple Launch Group replacement looks like.

The Launch Module

The Launch Module is a new module under consideration for EASE (Bug 478397). Its key method is the “launch” method which takes a Launch Configuration Name and an optional Launch Mode. The method then loads the named launch configuration and launches it, finally returning an ILaunch to allow future interaction with.

By using the launch method multiple times, with some additional control around it, allows complex launch sequences to be created.

Examples

For these examples I have already created three launch configurations for my individual tools (the name of the launch configuration is the quoted string in the bullet list):

• “Prepare” – An External Tools configuration which prepares my test environment
• “Server” – A PyDev supplied, Python Run configuration to launch my Python server
• “Client” – A Java configuration to launch my Java client

Running The Examples

1. Create three launch configurations named as above.
2. Clone/Import “JavaScript Snippets” project. The examples are located in org.eclipse.ease.scripts git repository (or will be soon, follow Bug 478397 to find out more).
3. Open the scripts in “Launch Module Examples” folder.
4. Right-click on the desired script
5. Choose Run As –> EASE Script

Alternatively paste the lines from the examples into the Rhino Script Shell console (as in the screenshot above). You get auto-completion of the names of the launch configurations and the launch modes too!

Example 1 – Fire and forget

In this first example, we simply launch the Client in Debug mode.

loadModule("/System/Launch")

launch("Client", "debug")

Line 1: load the Launch module, this populates the namespace with all the methods defined in the Launch module.
Line 3: launch the existing launch configuration “Client” in debug mode.

Example 2 – Replicate Functionality from Launch Groups

In this example, we prepare our environment with the “Prepare” configuration, then launch the “Server” and “Client” configurations.

loadModule("/System/Launch")

prepare = launch("Prepare")
while (!prepare.isTerminated()) {
 java.lang.Thread.sleep(1)
}

launch("Server")
java.lang.Thread.sleep(3000)

launch("Client", "debug")

Line 1: load the Launch module
Line 3: launch the Prepare configuration
Line 4-6: Busy-wait until the Prepare launch has terminated[1]
Line 8: launch the server
Line 9: Wait 3 seconds for the server to be ready
Line 11: launch the client in Debug mode

Example 3 – Terminating the Server Automatically

Example 1 and 2 are a promising start, but do not yet add any new functionality to Eclipse. So what do you do if you want the server to stop automatically when you finish debugging your client. Well that is really easy now, just monitor the client launch and terminate the server.

loadModule("/System/Launch")

prepare = launch("Program prepare")
while (!prepare.isTerminated()) {
 java.lang.Thread.sleep(1)
}

server = launch("Python Server")
java.lang.Thread.sleep(3000)

client = launch("Java Client", "debug")
while (!client.isTerminated()) {
 java.lang.Thread.sleep(1)
}
server.terminate()

Line 1-7: the same as Example 2
Line 8: launch the Server, but keep a handle of the ILaunch
Line 9: Wait 3 seconds for the server to be ready
Line 11: launch the Client
Line 12-14:Busy-wait until the Client debug session launch has terminated[1]
Line 15: terminate the server

This is a screenshot that shows what the Debug View looks like when we are busy-waiting on line 12.
At the top is the EASE Script launch of the example.
Then is the now terminated Prepare launch.
Followed by the still running Server in Run mode.
And finally, the Java Client, in Debug mode stopped at a breakpoint in main.

More Advanced Options

With the full power of the scripting language you can take these examples to the next step. A good place to start would be to remove the 3 second delay on Line 9 and replace that with some logic that actually determines if the server is ready to accept connections.

Other Functionality in the Launch Module

The Launch module is very new and I invite additional contributions to it to make it more useful. For now this is a quick overview of what it does:

String[] getLaunchConfigurationNames()

Returns an array of all the Launch Configuration Names known to the Launch Manager. These names can be used as the argument to the getLaunchConfiguration, launch and launchUI methods.

ILaunchConfiguration[] getLaunchConfigurations()

Returns an array of all the Launch Configurations known to the Launch Manager. These can be used as the argument to launch and launchUI methods.

ILaunchConfiguration getLaunchConfiguration(String name)

Return the launch configuration given by name parameter. The launch configuration can be edited or otherwise operated on. See ILaunchConfiguration.getWorkingCopy().

ILaunch launch(String launchConfigurationName, String mode)
ILaunch launch(ILaunchConfiguration configuration, String mode)

Launch the configuration either given by name or a launch configuration and return the ILaunch for further processing. This is the way to launch a configuration within a script which is itself launched.

ILaunch launchUI(String launchConfigurationName, String mode)
ILaunch launchUI(ILaunchConfiguration configuration, String mode)

Launch the configuration in the UI thread. This method respects the workspace settings for things like building before launching.

ILaunchManager getLaunchManager()

Obtain the platform launch manager. This allows access to the Eclipse debug core launch manager, allowing control over all non-UI aspects of launches. The most valuable of these should be wrapped for ideal script usage and made available in the module itself.[2]

Footnotes

1. A better API than busy-waiting is probably desired here, but that is for another day (and more Javascript knowledge).
2. Additional UI functionality is within the DebugUITools class, enabling access to this class directly from within the launch module is an option. Additionally, a Debug module would be very useful.