Scripting Eclipse with the Monkey Project: An Introduction

DOM

Scripts would be useless without ability to interact with Eclipse. In the Monkey world you use DOM - a plain Java object delivered to script's context. This way users may expose any methods and objects they want. DOMs are contributed to the Monkey through extension points. The following sections will explain the details.

Generic DOM

An example is best help to teach. Let's create a simple DOM: ExampleDOM. There will be only two methods in there:

package com.onjava.monkey.dom;

import java.text.SimpleDateFormat;
import java.util.Date;

/**
 * Example DOM for use in monkey scripts.
 */
public class ExampleDOM {

        private static final SimpleDateFormat dateFormat = 
                new SimpleDateFormat();

        /** Print current date . **/
        public void printDateNow(){
                System.out.println(dateFormat.format(new Date()));
        }
        
        /** Print debug message. **/
        public void printDebug(String msg){
                System.out.println("DEBUG: "+msg);      
        }
}

To make this object available for a script, we need to implement org.eclipse.eclipsemonkey.dom.IMonkeyDOMFactory interface. This is a factory interface with only one method to implement:

public interface IMonkeyDOMFactory {
    public Object getDOMroot();
}}

In our example we want return ExampleDOM class instance. It is stateless thus we may always return the same instance.

package com.onjava.monkey.dom;

import org.eclipse.eclipsemonkey.dom.IMonkeyDOMFactory;

/**
 * Simple DOM factory.
 */
public class DOMFactory implements IMonkeyDOMFactory {

        private ExampleDOM dom;
        
        public DOMFactory() {
                dom=new ExampleDOM();
        }

        public Object getDOMroot() {
                return dom;
        }
}

Now we contribute DOMFactory to the org.eclipse.eclipsemonkey.dom extension point to make script runner aware of our DOM. We have to provide following values:

• variableName - name under which the DOM instance will be registered in script's context.
• class - Factory that will produce DOM.
• resource - Class name reflecting DOM root's class

This is what goes into plugin.xml:

<plugin>
   <extension
         point="org.eclipse.eclipsemonkey.dom">
      <dom
            variableName="example"
                class="com.onjava.monkey.dom.DOMFactory"
            resource="com.onjava.monkey.dom.ExampleDOM"
            >
      </dom>
   </extension>
</plugin>

Don't worry if you feel a little bit lost. I made the code above available as a plug-in, try it to fill the gaps in your understanding. There is source and binary distribution available.

Language specific DOM

Apart from generic DOM, JavaScript engine is supporting objects designed to be used with JavaScript. The way how you can contribute them is not too much different from generic DOM contribution. Important thing to know is that DOM contributed to org.eclipse.eclipsemonkey.lang.javascript.javascript_dom extension point, will be available only to Monkey scripts run by JavaScript engine. It is not a big problem for now as this is the only supported scripting language.

DOM usage and summary

DOM have to be packed as a plug-in an published on an update site in advance to use. The ExampleDOM is available at this update site: http://monkey.brain-bakery.com/update-site/ as a com.onjava.monkey.dom plug-in. The reference is established in a script header. Whenever want to use DOM you have to add "DOM" entry. Following is an example with a reference to ExampleDOM. Please, create new script file ExampleDOM.js and paste following content.

/*
 * Menu: OnJava > ExampleDOM
 * Kudos: OnJava
 * License: EPL 1.0
 * DOM: http://monkey.brain-bakery.com/update-site/com.onjava.monkey.dom
 */
function main() {
        example.printDateNow
        example.printDebug(“This is debug message.â€)
}}

What will Monkey do when it sees header from preceding code? Try it yourself, by starting the script. Select from "Scripts" menu OnJava > ExampleDOM item. You should see warning dialog, complaining about missing DOM.

 

 

 

 

 

 

Figure 4. The "Missing DOM" dialog.

Click "Install Plug-in". Assuming above is ExampleDOM we created before, script should put two messages in console view: Current date and debug message.

What just happened is a part of Monkey magic. The plug-in that delivers DOM may be downloaded and made available to a script, thanks to entry in a header. This is what Monkey sees:

• http://monkey.brain-bakery.com/update-site/ - update site location
• com.onjava.monkey.dom - plug-in that contains DOM

The plug-in is downloaded from the update site, DOMs are made available in script's context. This mechanism is not perfect. Be aware of fact there is no support for versioning DOM objects. It may happen that a script will stop working, because of changes in remote DOM.

Now you know how powerful Monkey scripts can be. With proper set of DOM contributions a script can access any part of Eclipse. For your convenience there are some DOM available with Monkey distribution:

• Generic (no need to mention in header)
  • resources - org.eclipse.eclipsemonkey.doms.resources.Resources
  • workspace - org.eclipse.eclipsemonkey.doms.workspace.WorkspaceDOMFactory
• JavaScript specific (DOM url: http://download.eclipse.org/technology/dash/update/org.eclipse.eclipsemonkey.lang.javascript)
  • io - org.eclipse.eclipsemonkey.lang.javascript.doms.io.IO org.eclipse.eclipsemonkey.lang.javascript.doms.io.File wrapper around java.io.File org.eclipse.eclipsemonkey.lang.javascript.doms.io.WebRequest
  • resources - org.eclipse.eclipsemonkey.lang.javascript.doms.resources.Resources
  • views - org.eclipse.eclipsemonkey.lang.javascript.doms.views.Views
  • editors - org.eclipse.eclipsemonkey.lang.javascript.doms.editors.Editors

References

Reference: 

Introduction to Scripting Eclipse With Monkey Project