Marcin has posted 1 posts at DZone. You can read more from them at their website. View Full User Profile

Scripting Eclipse with the Monkey Project: An Introduction

  • submit to reddit

Whenever it comes to non standard tasks, scripting is handy. Linux has shell scripting, GIMP supports Python, modern text editors support macros. Now Eclipse users have no longer to be ashamed. There is new star in constellation - the Monkey project. This new, yet mature project, gives you the way to automate and speed up development using scripts.

How many times you were switching to shell only to use grep/sed/awk team? How often you had and idea for new functionality, but complex Eclipse architecture stopped you from extending the platform? This article will give a brief look over this new capability, introduced to wide audience in Europa (Eclipse 3.3) release.

This article expects from you to have at least basic knowledge about Eclipse, and extension points.
Should you lack this knowledge, the following short publications are very useful:


Best way to start with Monkey is to use Eclipse 3.3. When you download a copy, start it up and use update site to install the project. Check Europa Discovery Site > Other Tools > Eclipse Monkey on features selection screen (see following screen)


















Figure 1. The Monkey project - installation

Press "Select Required" button if you see an error message, that adds required dependencies. Proceed with installation and restart Eclipse if required.

After the installation is finished take a look at menu bar, you should notice new item named "Scripts" - all available scripts are exposed here. You may try one of the examples. To do this, click on "Scripts" menu and select "Examples". "Eclipse Monkey Examples" project gets created in your workspace. This is a set of example scripts, created to familiarize users with Monkey project. Again go to "Scripts" menu, this time select Hello > Bjorn item. Pop-up dialog with a message is shown as a result of script execution. Congratulations! The Monkey is working.

Anatomy of a Monkey script

Take a closer look at "Eclipse Monkey Examples" project. When you expand, you will see a "scripts" folder with files inside. Those are script files - one script per file. Whenever new script is added, deleted or there is a change to existing file, the Monkey rebuilds its menu. Now I will explain the scripts structure.

The example we just launched is stored in Hello__Bjorn.js file. Open it in an editor:

* Menu: Hello > Bjorn
* Kudos: Ward Cunningham & Bjorn Freeman-Benson
* License: EPL 1.0
function main() {
text = "Hello Bjorn\n\n";
text += "The quick brown fox jumped over the lazy dog's back.";
text += "Now is the time for all good men to come to the aid of their country."
"Monkey Dialog",
text )

First thing to notice is JavaScript comment, this is a header. You have to remember that Menu field is mandatory. Its content is straightforward: elements separated by > character form menu location, last element is a script name.




Figure 2. Location defined in a header makes script available in the menu.

Although other header fields are optional, it is a good manner to add Kudos and License.

Function main goes after the header. This is where the Monkey will start script execution. First the text variable with the message is created. Then you see a reference to a Java class: MessageDialog. This is use of Rhino concept: fully qualified Java class name prefixed with Package keyword. Rhino is one of the first scripting engines that brought JavaScript to Java world, and it's used in current Monkey implementation. The window keyword is a variable provided by scripting engine. It is one of many predefined variables, giving a way to interact with Eclipse. Later you will learn more about this, now just assume the window variable is an object giving an access to Eclipse workbench (org.eclipse.ui.IWorkbenchWindow). The window.getShell() method returns workbench window's shell - Shell is an Eclipse concept, representing window visible to the user - necessary to create MessageDialog.


After first bite of the Monkey it is time to show you how it works inside. Look at the following UML diagram.















Figure 3. UML diagram presenting major Monkey elements.

When Eclipse platform starts, EclipsePlugin creates the "Scripts" menu and its content, then registers a listener (UpdateMonkeyActionsResourceChangeListener), to keep menu content synchronized with scripts. Menu items are represented by MenuRunMonkeyScript class, derived from org.eclipse.jface.action.IAction. Whenever you select from the menu a script to run, the action obtains script runner from the corresponding IMonkeyLanguageFactory implementation, and delegates request to IMonkeyScriptRunner implementation. Apart from producing script runner, the language factory's role is to understand the script's header and produce a ScriptMetadata object as a result from the getScriptMetadata method. Generally speaking ScriptMetadata represents fields defined in the header. Script runner is the one to run the script. For now there is only a JavaScriptRunner implementation available, allowing to create the Monkey scripts in JavaScript. Other languages are supported by forked project GroovyMonkey, which I will cover later.
Published at DZone with permission of its author, Marcin Maciukiewicz. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)