Wednesday, December 16, 2015

A new interpreter for EASE (4): Provide modules support

EASE is shipped with modules: libraries written in Java, made available for script interpreters. The intention of such modules is to write them once and use them in all available script languages.

Read all tutorials from this series.

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online. 


Introduction

Typically modules are plain java classes. We could easily create an instance in BeanShell and then call instance.method(). While this is perfectly ok for the average programmer, some of our user might expect a more simple, functional interface. What module loading does is:
  • create an instance of the module
  • inject the instance into the interpreter
  • create dynamic script code to wrap method calls
  • execute the created code
For BeanShell we would create code like
method(param1, param2) { 

result = __MOD_module_instance.method(param1, param2);

return result;

}
After loading this fragment we could access method() without the knowledge of modules, instances and object orientation at all.

Step 1: The code factory

To dynamically create code EASE needs an ICodeFactory implementation. To start you may look at existing implementations, basically we just need to build strings containing script code.
package org.eclipse.ease.lang.beanshell;

import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.util.Arrays;
import java.util.List;

import org.eclipse.ease.Logger;
import org.eclipse.ease.modules.AbstractCodeFactory;
import org.eclipse.ease.modules.IEnvironment;
import org.eclipse.ease.modules.IScriptFunctionModifier;
import org.eclipse.ease.modules.ModuleHelper;

public class BeanShellCodeFactory extends AbstractCodeFactory {

 public static final List<String> RESERVED_KEYWORDS = Arrays.asList("abstract", "continue", "for", "new", "switch", "assert", "default", "goto", "package",
   "synchronized", "boolean", "do", "if", "private", "this", "break", "double", "implements", "protected", "throw", "byte", "else", "import", "public",
   "throws", "case", "enum", "instanceof", "return", "transient", "catch", "extends", "int", "short", "try", "char", "final", "interface", "static",
   "void", "class", "finally", "long", "strictfp", "volatile", "const", "float", "native", "super", "while");

 private static boolean isValidMethodName(final String methodName) {
  return BeanShellHelper.isSaveName(methodName) && !RESERVED_KEYWORDS.contains(methodName);
 }

 @Override
 public String getSaveVariableName(final String variableName) {
  return BeanShellHelper.getSaveName(variableName);
 }

 @Override
 public String createFunctionWrapper(final IEnvironment environment, final String moduleVariable, final Method method) {

  final StringBuilder scriptCode = new StringBuilder();

  // parse parameters
  final List<Parameter> parameters = ModuleHelper.getParameters(method);

  // build parameter string
  final StringBuilder parameterList = new StringBuilder();
  for (final Parameter parameter : parameters)
   parameterList.append(", ").append(parameter.getName());

  if (parameterList.length() > 2)
   parameterList.delete(0, 2);

  final StringBuilder body = new StringBuilder();

  // insert hooked pre execution code
  body.append(getPreExecutionCode(environment, method));

  // insert deprecation warnings
  if (ModuleHelper.isDeprecated(method))
   body.append("\tprintError('" + method.getName() + "() is deprecated. Consider updating your code.');\n");

  // insert method call
  body.append("\t ");
  if (!method.getReturnType().equals(Void.TYPE))
   body.append(IScriptFunctionModifier.RESULT_NAME).append(" = ");

  body.append(moduleVariable).append('.').append(method.getName()).append('(');
  body.append(parameterList);
  body.append(");\n");

  // insert hooked post execution code
  body.append(getPostExecutionCode(environment, method));

  // insert return statement
  if (!method.getReturnType().equals(Void.TYPE))
   body.append("\treturn ").append(IScriptFunctionModifier.RESULT_NAME).append(";\n");

  // build function declarations
  for (final String name : getMethodNames(method)) {
   if (!isValidMethodName(name)) {
    Logger.error(IPluginConstants.PLUGIN_ID,
      "The method name \"" + name + "\" from the module \"" + moduleVariable + "\" can not be wrapped because it's name is reserved");

   } else if (!name.isEmpty()) {
    scriptCode.append(name).append("(").append(parameterList).append(") {\n");
    scriptCode.append(body);
    scriptCode.append("}\n");
   }
  }

  return scriptCode.toString();
 }

 @Override
 public String classInstantiation(final Class<?> clazz, final String[] parameters) {
  final StringBuilder code = new StringBuilder();
  code.append("new ").append(clazz.getName()).append("(");

  if (parameters != null) {
   for (final String parameter : parameters)
    code.append(parameter).append(", ");

   if (parameters.length > 0)
    code.delete(code.length() - 2, code.length());
  }

  code.append(")");

  return code.toString();
 }

 @Override
 public String createFinalFieldWrapper(final IEnvironment environment, final String moduleVariable, final Field field) {
  return getSaveVariableName(field.getName()) + " = " + moduleVariable + "." + field.getName() + ";\n";
 }

 @Override
 protected String getNullString() {
  return "null";
 }
}
createFunctionWrapper() is called for each exposed method, createFinalFieldWrapper() is called for each exposed final field. The function wrapper injects preExecutionCode and postExecutionCode. This is interesting for modules implementing IScriptFunctionModifier. If such a module is loaded, it may influence code generation for all other modules. Use cases are creation of log files or unit testing.

Step 2: Register code factory

Now we need to register our code factory, so EASE is able to find it. Open the Extensions tab of org.eclipse.ease.lang.beanshell/plugin.xml. Navigate to the scriptType extension and add the code factory class to the BeanShell type.
Step 3: Bootstrapping

There exists a dedicated Environment module that provides basic commands like loadModule() to load further modules. Lets try to load it in a BeanShell:

run EASE and open a bean shell in the Script Shell View. We will create an instance of EnvironmentModule and advise it to load itself:
new org.eclipse.ease.modules.EnvironmentModule().loadModule("/System/Environment");
If your code factory works as expected, commands like print() and loadModule() should be available.

To automate this task we will add a launch extension to our BeanShell language definition.
Switch to the plugin.xml and add a launchExtension to the org.eclipse.ease.language node.We bind it to the engineID of BeanShell and need to provide an implementation:
public class BootStrapper implements IScriptEngineLaunchExtension {

 @Override
 public void createEngine(final IScriptEngine engine) {
  ICodeFactory codeFactory = ScriptService.getCodeFactory(engine);
  if (codeFactory != null) {
   StringBuilder stringBuilder = new StringBuilder();
   stringBuilder.append(codeFactory.classInstantiation(EnvironmentModule.class, new String[0]));
   stringBuilder.append(".loadModule(\"");
   stringBuilder.append(EnvironmentModule.MODULE_NAME);
   stringBuilder.append("\");\n");

   engine.executeAsync(new Script("Bootloader", stringBuilder.toString()));
  }
 }
}
Of course we could directly use the string we tried manually before, but using the code factory is somewhat nicer. The implementation given above is already available from the BootStrapper class from EASE. If you do want to add more stuff to the bootloader you need to provide your own implementation.

With that in place you should be able to load all available modules into BeanShell and use its functions.

Optional: Loading external jars

We added support to register URLs to the classloader in our previous tutorial. Now as we have modules working we may try this out by calling
loadJar("http://central.maven.org/maven2/com/github/lalyos/jfiglet/0.0.7/jfiglet-0.0.7.jar")
 true
com.github.lalyos.jfiglet.FigletFont.convertOneLine("I      love      scripting");
  ___        _                                             _         _    _               
 |_ _|      | |  ___  __   __  ___        ___   ___  _ __ (_) _ __  | |_ (_) _ __    __ _ 
  | |       | | / _ \ \ \ / / / _ \      / __| / __|| '__|| || '_ \ | __|| || '_ \  / _` |
  | |       | || (_) | \ V / |  __/      \__ \| (__ | |   | || |_) || |_ | || | | || (_| |
 |___|      |_| \___/   \_/   \___|      |___/ \___||_|   |_|| .__/  \__||_||_| |_| \__, |
                                                             |_|                    |___/ 


Tuesday, December 15, 2015

A new interpreter for EASE (3): Loading native classes

In this tutorial we will teach our interpreter to load all kinds of classes from Eclipse and dedicated URLs. So we will have a closer look on the classloader, but don't worry - it will not get too complicated.

Our BeanShell interpreter is already capable of calling java code, so we only need to make sure that its classloader will have access to all desired resources.

Read all tutorials from this series.

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online. 

Step 1: Access java classes from eclipse

Our BeanShell interpreter already accepts calls to JRE classes like
java.lang.System.out.println("Hello world");
However if we try to access eclipse classes like
org.eclipse.jface.resource.JFaceColors
    Sourced file: inline evaluation of: ``org.eclipse.jface.resource.JFaceColors;'' :
    Class or variable not found: org.eclipse.jface.resource.JFaceColors
We get an exception indicating that the class cannot be found. This is a classloader issue as the interpreter uses the bundle classloader from our org.eclipse.ease.lang.beanshell bundle. We could add dependencies to jface to solve the problem, but how would we introduce dependencies to all plug-ins that might be used by a customer?

Fortunately eclipse has a solution for this. We may allow plug-ins to access classes from all exported packages out there without  adding a dedicated dependency by defining
Eclipse-BuddyPolicy: global
in the MANIFEST.MF file. This comes with a penalty on class loading performance but allows to access all available classes.

Add this setting to the manifest of org.eclipse.ease.lang.beanshell. Afterwards switch to the BeanShellEngine and add following line to setupEngine():
fInterpreter.setClassLoader(getClass().getClassLoader());
This line changes the classloader of the BeanShell with the one from the org.eclipse.ease.lang.beanshell bundle.

Now go and try to load some eclipse classes:
org.eclipse.jface.resource.JFaceColors
    Class Identifier: org.eclipse.jface.resource.JFaceColors

Step 2: Load classes from external URLs

EASE allows to register external jar files and make them available to scripting. This mechanism  is provided by a module - a concept we will introduce in the next tutorial. For now we will make all necessary preparations. EASE provides a generic classloader with all necessary functionality. Go to your BeanShellEngine and modify the code as follows:
public class BeanShellEngine extends AbstractScriptEngine {

 private DelegatingJarClassLoader fClassLoader;

 @Override
 protected boolean setupEngine() {
  fInterpreter = new Interpreter();

  fClassLoader = new DelegatingJarClassLoader(getClass().getClassLoader());
  fInterpreter.setClassLoader(fClassLoader);

  [...]
 }

 @Override
 public void registerJar(final URL url) {
  if (fClassLoader != null)
   fClassLoader.registerURL(url);
 }
}
The DelegatingClassLoader will take care of registered URLs. For everything else its parent classloader will be used. We cannot test this currently, so you need to trust me on this until the next tutorial.

Friday, December 11, 2015

A new interpreter for EASE (2): Shell and script integration

Today we will focus on integrating BeanShell into the script shell and to allow to execute .bsh files.

To follow this tutorial you will either need to install EASE into your development IDE or even better create a target platform containing EASE core plugins. I expect that you are familiar with that process.

Read all tutorials from this series.

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online. 

Step 1: A very basic EASE interpreter

Create a new Plug-in Project called org.eclipse.ease.lang.beanshell. Add dependencies to org.eclipse.ease and to our org.beanshell plug-in.

Switch to the Extensions tab and add a new extension point for org.eclipse.ease.language. Create an engine, provide an ID, a nice name and a link to the implementing class.

Instead of implementing the IScriptEngine interface directly you may inherit from AbstractScriptEngine:
package org.eclipse.ease.lang.beanshell;

import org.eclipse.ease.AbstractScriptEngine;
import org.eclipse.ease.Script;

import bsh.Interpreter;

public class BeanShellEngine extends AbstractScriptEngine {

 private Interpreter fInterpreter = null;

 public BeanShellEngine() {
  super("BeanShell");
 }

 @Override
 protected boolean setupEngine() {
  fInterpreter = new Interpreter();

  fInterpreter.setOut(getOutputStream());
  fInterpreter.setErr(getErrorStream());

  return true;
 }

 @Override
 protected boolean teardownEngine() {
  fInterpreter = null;

  return true;
 }

 @Override
 protected Object execute(final Script script, final Object reference, final String fileName, final boolean uiThread) throws Throwable {
  return fInterpreter.eval(script.getCode());
 }
}
Use the QuickFix to Add unimplemented methods.

Launch a new RCP application adding org.eclipse.ease.* and org.beanshell plugins to your run configuration.

Now open the Script Shell view and use the engine selection to switch to BeanShell. Your console name should change to BeanShellScript Shell and you should be able to enter and execute some beanshell commands.

Step 2: Adding launch target support

To launch files with an engine we need to bind our engine to dedicated content types. That means that we first need a content type for BeanShell files. Open the Plug-in Manifest Editor, switch to the Extensions tab and add a new extension for org.eclipse.contenttype.contentTypes. Add a new content-type based on org.eclipse.core.runtime.text and set file-extensions to bsh.

Now create a new extension for org.eclipse.ease.scriptType. Set name to BeanShell and the defaultExtension to bsh.  Afterwards add a binding to our previously created content type.

Finally switch to your engine definition and create a binding to the scriptType.

When launching you may now run .bsh files from your workspace using the EASE launch target (eg by using Run As/EASE Script from the context menu).

Step 3: Add variables support

Getting and setting variables improves the Script Shell experience but is also needed for modules support, which we investigate in a following tutorial.

Open your BeanShellEngine and replace your default methods for variables with these:
 @Override
 protected Object internalGetVariable(final String name) {
  try {
   return fInterpreter.get(name);
  } catch (EvalError e) {
   Logger.error("org.eclipse.ease.lang.beanshell", "Cannot retrieve variable \"" + name + "\"", e);
  }

  return null;
 }

 @Override
 protected Map<String, Object> internalGetVariables() {
  Map<String, Object> variables = new HashMap<String, Object>();

  for (Variable variable : fInterpreter.getNameSpace().getDeclaredVariables())
   variables.put(variable.getName(), internalGetVariable(variable.getName()));

  return variables;
 }

 @Override
 protected boolean internalHasVariable(final String name) {
  for (Variable variable : fInterpreter.getNameSpace().getDeclaredVariables()) {
   if (variable.getName().equals(name))
    return true;
  }

  return false;
 }

 @Override
 protected void internalSetVariable(final String name, final Object content) {
  try {
   fInterpreter.set(name, content);
  } catch (EvalError e) {
   Logger.error("org.eclipse.ease.lang.beanshell", "Cannot set variable \"" + name + "\"", e);
  }
 }

 @Override
 protected Object internalRemoveVariable(final String name) {
  Object content = internalGetVariable(name);
  fInterpreter.getNameSpace().unsetVariable(name);

  return content;
 }

 @Override
 public String getSaveVariableName(final String name) {
  return BeanShellHelper.getSaveName(name);
 }
We purely dig into the beanshell interpreter and investigate its namespace. The BeanShellHelper class is copied from the JavaScriptHelper and provides basic checks on variable names.

Once launched, the Script Shell will show a list of all available variables in your interpreter attached in the container right to the shell.

Monday, December 7, 2015

A new interpreter for EASE (1): Playing with beanshell

This new series will provide a guide how to integrate your own interpreter in EASE. As a showcase we will implement an interpreter for BeanShell.

Read all tutorials from this series.

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online. 

Step 1: Evaluate interpreter candidates

The bare minimum requirement for an interpreter to do something useful with EASE is to support an execute() method that accepts and executes arbitrary strings of script code. This will allow to use the interpreter in the script shell and to create script files and execute them using the EASE launch target.

Now EASE typically integrates interpreters that run natively on the JRE. This allows scripts to seamlessly interact with the current application. Such interpreters have some additional requirements:
  • access native java objects (eg. java.lang.System)
  • set/get variables in the interpreter
  • allow to define functions/methods
  • redirect input/output/error streams
Interpreters like Rhino or Jython support these extended requirements and therefore allow to write scripts that fully integrate into EASE.

However much simpler interpreters may make sense in some cases. I have played around with such interpreters and built a basic git console and a bash console. Both are in a proof of concept state, but might indicate what can be done with EASE.

Step 2: Integrating BeanShell

We will concentrate on BeanShell, so download the latest stable build.

Now create a new Plug-in from Existing JAR Archives. On the next page hit Add External and add the downloaded bsh-<version>.jar. Set the project name to org.beanshell and select Unzip the JAR archives into the project.

Open the Plug-in Manifest Editor and make sure that the bsh package is correctly exported on the Runtime tab.

Step 3: Play with the interpreter

To learn how the interpreter works we create a Java Project org.beanshell.playground. Add our org.beanshell project to the Java Build Path and create a test class with a main method:
package org.beanshell.playground;

import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.Date;

import bsh.EvalError;
import bsh.Interpreter;

public class RunEmbedded {

 private static final String[] CODE_FRAGMENTS = new String[] { "2+3", "foo*10", "new java.io.File(\"/\").exists()",
   "sum(a,b){\n return a+b;\n }\nsum(40,2)" };

 public static void main(String[] args) throws EvalError, FileNotFoundException, IOException {
  Interpreter interpreter = new Interpreter(); // Construct an interpreter

  // set variables
  interpreter.set("foo", 5);
  interpreter.set("date", new Date());

  // get variables
  Object date = interpreter.get("date");

  // evaluate statements
  for (String code : CODE_FRAGMENTS) {
   System.out.println(interpreter.eval(code));
  }
 }
}

A simple embedding example was quickly found using google, now our tests show how to get/set variables and how to execute various pieces of code. From what we can see so far BeanShell is a perfect candidate for scripting.

The following tutorials will show how to integrate the interpreter in EASE, stay tuned!.

Monday, November 9, 2015

EclipseCon slides on EASE

Thanks to all who attended my talk at EclipseCon Europe last week. It is great to see the community jump on the scripting topic.

Even if I do not like large slidesets, I have put them online for your reference. Remember to have javascript enabled in your browser :)

The sample scripts are available from our scripts git repository:
JavaScript Beginner Tutorial

If you have questions or are just interested in the topic, consider joining our mailing list.

Monday, October 5, 2015

Tycho 13: Generating API documentation

If you want to add API documentation to your feature you want to make sure that documentation and implementation are consistent. Running javadoc manually is not ideal, better integrate documentation generation in your tycho build.

Tycho Tutorials

For a list of all tycho related tutorials see Tycho Tutorials Overview

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.

Step 1: Create a help plug-in

We need a hosting plug-in for our API documentation. So create a new Plug-in Project named com.codeandme.tycho.help and mavenize it with Packaging set to eclipse-plugin. Add it to your master pom as usual.

Eclipse help is provided by adding extension points for org.eclipse.help.toc elements and according xml files. I will not go into details here as Lars did an excellent job with his tutorial on eclipse help.

For our project we provide 2 'classic' toc entries along with xml files: main.xml and reference.xml.

The third entry in plugin.xml (referring to help/api_docs.xml) does not have a corresponding xml file as we will create this one on the fly with maven.

We intend to generate documentation to a folder help/api-docs/javadoc. As tycho will not create this folder automatically, we need to add it manually.

Step 2: Configuring tycho

Documentation creation is a step we want to do for the help plug-in only. Therefore the following changes will go to com.codeandme.tycho.help/pom.xml and not to our master pom.
 <properties>
  <platform.api>org.eclipse.platform.doc.isv/reference/api</platform.api>
 </properties>

 <build>
  <plugins>
   <plugin>
    <groupId>org.eclipse.tycho.extras</groupId>
    <artifactId>tycho-document-bundle-plugin</artifactId>
    <version>${tycho.extras.version}</version>
    <executions>
     <execution>
      <id>eclipse-javadoc</id>
      <phase>generate-resources</phase>
      <goals>
       <goal>javadoc</goal>
      </goals>
      <configuration>
       <outputDirectory>${project.basedir}/help/api-docs/javadoc</outputDirectory>
       <tocFile>${project.basedir}/help/api_docs.xml</tocFile>
       <tocOptions>
        <mainLabel>Tycho Tutorial API</mainLabel>
       </tocOptions>
       <javadocOptions>
        <!-- enable in case you need a proxy for web access 
        <jvmOptions>
         <jvmOption>-Dhttp.proxySet=true</jvmOption>
         <jvmOption>-Dhttp.proxyHost=proxy.example.com</jvmOption>
         <jvmOption>-Dhttp.proxyPort=81</jvmOption>
         <jvmOption>-DhttpnonProxyHosts=*.example.com</jvmOption>
        </jvmOptions>
         -->
        <additionalArguments>
         <additionalArgument>${javadoc-args}</additionalArgument>
         <additionalArgument>
          -link
          http://docs.oracle.com/javase/8/docs/api/
         </additionalArgument>
         <additionalArgument>
          -linkoffline
          ../../${platform.api}
          http://help.eclipse.org/mars/topic/org.eclipse.platform.doc.isv/reference/api/
         </additionalArgument>
         <additionalArgument>-public</additionalArgument>
        </additionalArguments>
       </javadocOptions>
      </configuration>
     </execution>
    </executions>
   </plugin>
  </plugins>
 </build>
The property tycho.extras.version was added in our previous tutorial. Please add it to the master pom, if you did not do this already.

Lets look at some of the pom options:

Line 20 defines the TOC xml file to be created. Its display name is defined in line 22. TOC generation might be disabled by setting <skipTocGen>false</skipTocGen>
Lines 35-38 will add links to external documentation for standard java classes.
Lines 39-43 will add links to the eclipse API documentation typically shipped with every release.

Step 3: Define plug-ins for documentation creation

Typically you do not want to create documentation for all plug-ins. Test plug-ins for example should not show up there. Therefore we need to maintain a list of all plug-ins that should be considered by tycho.

This list is stored in com.codeandme.tycho.help/build.properties. Add them as extra classpath entries:
jars.extra.classpath = platform:/plugin/com.codeandme.tycho.plugin
To provide multiple plug-ins, add a comma-separated list (like for the bin.includes entry).

Tycho will create documentation for exported packages only. With the current project configuration com.codeandme.tycho.plugin does not export anything. You have to export a package there or tycho will fail to build.

Finally make sure to add the help folder to your binary build in build.properties.

Congratulations, you API documentation is now up to date for every build.

Thursday, October 1, 2015

Tycho 12: Build source features

Providing update sites containing source code for developers is considered good style. Used in a target platform it allows developers to see your implementation code. This makes debugging far easier as users do not need to checkout your source code from repositories they have to find first.

Tycho allows to package such repositories very easily.

Tycho Tutorials

For a list of all tycho related tutorials see Tycho Tutorials Overview

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.


Step 1: Create a source update site project

Create a new project of type Plug-in Development/Update Site Project. Name it com.codeandme.tycho.releng.p2.source and leave all the other settings to their defaults. You will end up in the Site Manifest Editor of your site.xml file. Instead of editing this file by hand we will immediately delete site.xml and copy over the category.xml file from com.codeandme.tycho.releng.p2.

Mavenize the project the same way as we did in tutorial 5: set Packaging to eclipse-repository and add the project to com.codeandme.tycho.releng/pom.xml.

Step 2: Modify category.xml

Source plug-ins and features will be created by tycho on the fly, so we have no real projects in the workspace we could add with the Site Manifest Editor. Therefore we need to open category.xml with the Text Editor. Tycho does not care about the url property, so remove it. Feature ids need to be changed to <original.id>.source.

If you like you can move all source features to a dedicated category:
<?xml version="1.0" encoding="UTF-8"?>
<site>
   <feature id="com.codeandme.tycho.plugin.feature" version="1.0.0.qualifier">
      <category name="source_components"/>
   </feature>
   <category-def name="source_components" label="Developer Resources"/>
</site>
Step 3: Configure tycho source builds

To enable source builds we need to extend com.codeandme.tycho.releng/pom.xml a bit. The source below contains only the additions to our pom file, so merge them accordingly (full version on github).
 <properties>
  <tycho.extras.version>${tycho.version}</tycho.extras.version>
 </properties>

 <build>
  <plugins>
   <!-- enable source feature generation -->
   <plugin>
    <groupId>org.eclipse.tycho.extras</groupId>
    <artifactId>tycho-source-feature-plugin</artifactId>
    <version>${tycho.extras.version}</version>

    <executions>
     <execution>
      <id>source-feature</id>
      <phase>package</phase>
      <goals>
       <goal>source-feature</goal>
      </goals>
     </execution>
    </executions>

    <configuration>
     <excludes>
      <!-- provide plug-ins not containing any source code -->
      <plugin id="com.codeandme.tycho.product" />
     </excludes>
    </configuration>
   </plugin>

   <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>tycho-source-plugin</artifactId>
    <version>${tycho.version}</version>

    <executions>
     <execution>
      <id>plugin-source</id>
      <goals>
       <goal>plugin-source</goal>
      </goals>
     </execution>
    </executions>
   </plugin>

   <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>tycho-p2-plugin</artifactId>
    <version>${tycho.version}</version>
    <executions>
     <execution>
      <id>attached-p2-metadata</id>
      <phase>package</phase>
      <goals>
       <goal>p2-metadata</goal>
      </goals>
     </execution>
    </executions>
   </plugin>
  </plugins>
 </build>
When building source plug-ins, tycho expects every plug-in project to actually contain source code. If projects do not contain source, we need to exclude them as we do on line 26.

After building the project we will end up with a p2 site containing binary builds and source builds of each feature/plug-in.

Thursday, July 30, 2015

EASE @ EclipseCon Europe 2015



This years EclipseCon will be very exciting for me. Not only was my talk proposal I love scripting accepted as an early bird pick, there are also other parties starting to propose talks concerning EASE.

I love to see this project start to fly and like to give you some insights and an outlook of what to expect at EclipseCon.

How it all began

I remember my first EclipseCon in 2012. I had this intriguing idea in my mind about a scripting framework in Eclipse, but no idea whom to talk to about it. By chance I met Wayne Beaton who offered help and encouraged me to find some interested parties to support my idea.

It took me almost a year to provide a prototype and start advertising this idea, but soon after my first post on this topic on this blog, Polarsys got interested and things started to move very quickly. In summer 2013 we agreed to introduce scripting (called EScript at that time) to the e4 incubator. Thanks to Paul Webster we got a nice place to play and learn about the eclipse way of working on a software project.

When the call for papers openend for EclipseCon Europe 2013 I thought 'What the hell' and sent a proposal for a talk on scripting. I never expected it to get accepted, but few months later I found myself talking about scripting at EclipseCon.

Encouraged by the positive feedback Arthur Daussy and myself worked hard on the implementation. Finally we moved out of the e4 incubator in 2014 and now you may install this great scripting environment in your IDE.

The role of EclipseCon

Meeting users, committers and eclipse staff members in person helped me a  lot  to make this project happen. In the beginning it was the encouragements and good advice I got from experienced members. Now I am looking forward to hear the user side, your success stories, your fresh ideas.

If you read this far you are definitely interested in scripting, so take the chance and meet me in person @ EclipseCon. If there is enough interest, we may have a BOF on scripting topics there. please leave me a note if you would like to see this happen.


I love scripting - what we will cover

This talk will give an overview what scripting can do for you and how you can implement it in your IDE or RCP. We will start to have a short look on the architecture (1%) and then immediately switch to a live demo (99%). There we will start with simple script commands, continue with Java integration and introduce scripting libraries. Next we will learn how to provide custom libraries for your RCP.

Once the basics are clear, we will start to extend the IDE with user scripts, start to write scripted unit tests and finally show rapid prototyping by dynamically instantiating java files from your workspace.

Expect a fast roller coaster ride through the features of EASE. I am sure you want more of it after your first ride!

see you at EclipseCon

Friday, July 24, 2015

A custom search provider

In this tutorial we will implement a custom search for your RCP. Therefore we will first create the search logic and add UI components in a second step.
I found few resources on search functionality, here are some from the Eclipse FAQs:
To have something to search for we will look for files on the local file system. So this is our target for today:
 

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.

Step 1: Search Results


First create a new Plug-in Project and create a class FileSearchResult that implements ISearchResult. Therefore you need a dependency to org.eclipse.search.
package com.codeandme.searchprovider;

import java.io.File;
import java.util.Collection;
import java.util.HashSet;

import org.eclipse.core.runtime.ListenerList;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.search.ui.ISearchQuery;
import org.eclipse.search.ui.ISearchResult;
import org.eclipse.search.ui.ISearchResultListener;
import org.eclipse.search.ui.SearchResultEvent;

public class FileSearchResult implements ISearchResult {

 private final ISearchQuery fQuery;
 private final ListenerList fListeners = new ListenerList();

 private final Collection<File> fResult = new HashSet<File>();

 public FileSearchResult(ISearchQuery query) {
  fQuery = query;
 }

 @Override
 public String getLabel() {
  return fResult.size() + " file(s) found";
 }

 @Override
 public String getTooltip() {
  return "Found files in the filesystem";
 }

 @Override
 public ImageDescriptor getImageDescriptor() {
  return null;
 }

 @Override
 public ISearchQuery getQuery() {
  return fQuery;
 }

 @Override
 public void addListener(ISearchResultListener l) {
  fListeners.add(l);
 }

 @Override
 public void removeListener(ISearchResultListener l) {
  fListeners.remove(l);
 }

 private void notifyListeners(File file) {
  SearchResultEvent event = new FileSearchResultEvent(this, file);

  for (Object listener : fListeners.getListeners())
   ((ISearchResultListener) listener).searchResultChanged(event);
 }

 public void addFile(File file) {
  fResult.add(file);
  notifyListeners(file);
 }
}
Nothing special here, we will use addFile() later in this tutorial to add more and more files to our result set. Whenever the result changes, we need to inform interested listeners. So lets see how FileSearchResultEvent looks like:
package com.codeandme.searchprovider;

import java.io.File;

import org.eclipse.search.ui.ISearchResult;
import org.eclipse.search.ui.SearchResultEvent;

public class FileSearchResultEvent extends SearchResultEvent {

 private final File fAddedFile;

 protected FileSearchResultEvent(ISearchResult searchResult, File addedFile) {
  super(searchResult);
  fAddedFile = addedFile;
 }

 public File getAddedFile() {
  return fAddedFile;
 }
}
Even simpler! To update results incrementally we hold a reference to the added file.

Step 2: The search query

The main logic for a search is implemented as an ISearchQuery. It has 2 jobs: do the actual search and populate the search result.
package com.codeandme.searchprovider;

import java.io.File;
import java.io.FileFilter;
import java.util.Collection;
import java.util.HashSet;

import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.OperationCanceledException;
import org.eclipse.core.runtime.Status;
import org.eclipse.search.ui.ISearchQuery;
import org.eclipse.search.ui.ISearchResult;

public class FileSearchQuery implements ISearchQuery {

 private final File fRoot;
 private final String fFilter;
 private final boolean fRecursive;

 private final FileSearchResult fSearchResult;

 public FileSearchQuery(String root, String filter, boolean recursive) {
  fRoot = (root.isEmpty()) ? File.listRoots()[0] : new File(root);
  fFilter = filter;
  fRecursive = recursive;
  fSearchResult = new FileSearchResult(this);
 }

 @Override
 public IStatus run(IProgressMonitor monitor) throws OperationCanceledException {
  Collection<File> entries = new HashSet<File>();
  entries.add(fRoot);

  do {
   File entry = entries.iterator().next();
   entries.remove(entry);

   entry.listFiles(new FileFilter() {

    @Override
    public boolean accept(File pathname) {
     if ((pathname.isFile()) && (pathname.getName().contains(fFilter))) {
      // accept file
      fSearchResult.addFile(pathname);

      return true;
     }

     if ((pathname.isDirectory()) && (fRecursive))
      entries.add(pathname);

     return false;
    }
   });

  } while (!entries.isEmpty());

  return Status.OK_STATUS;
 }

 @Override
 public String getLabel() {
  return "Filesystem search";
 }

 @Override
 public boolean canRerun() {
  return true;
 }

 @Override
 public boolean canRunInBackground() {
  return true;
 }

 @Override
 public ISearchResult getSearchResult() {
  return fSearchResult;
 }
}
Our query needs 3 parameters:
  • a root object
  • a file name filter
  • a recursive flag to scan subfolders
In the constructor we create the FileSearchResult and link it to our query. Then we traverse folders and add file by file to our search result. We do not check our input parameters very thoroughly for the sake of simplicity.

The logic is implemented, now lets add some nice UI elements.

Step 3: Search Dialog

To add a new search page to the search dialog (main menu/Search/Search...) we use the extension point org.eclipse.search.searchPages.
 
Just provide id, label and a class reference to:
package com.codeandme.searchprovider.ui;

import org.eclipse.jface.dialogs.DialogPage;
import org.eclipse.search.ui.ISearchPage;
import org.eclipse.search.ui.ISearchPageContainer;
import org.eclipse.search.ui.NewSearchUI;
import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Composite;

import com.codeandme.searchprovider.FileSearchQuery;

public class FileSearchPage extends DialogPage implements ISearchPage {

 private ISearchPageContainer fContainer;

 @Override
 public boolean performAction() {
  FileSearchQuery searchQuery = new FileSearchQuery("/home", "txt", true);
  NewSearchUI.runQueryInForeground(fContainer.getRunnableContext(), searchQuery);

  return true;
 }

 @Override
 public void setContainer(ISearchPageContainer container) {
  fContainer = container;
 }

 @Override
 public void createControl(Composite parent) {
  Composite root = new Composite(parent, SWT.NULL);

  [...]

  // need to set the root element
  setControl(root);
 }
}
I have removed the UI code from createControl() as it is not relevant here. If interested you can find it on github. The only important thing here is to set the root control using setControl().

performAction() starts the actual search. Therefore we create a query and run it either as foreground or as background job. By returning true we indicate that the search dialog shall be closed.

Step 4: Display search results

To add a new page to the Search View we need another extension point: org.eclipse.search.searchResultViewPages.

Add a new viewPage with an id and label. To link this page with search results of a certain kind we provide the class of search results this page can display. Set it to our FileSearchResult type. Finally we provide a class implementation for the page:
package com.codeandme.searchprovider.ui;

import org.eclipse.search.ui.ISearchResult;
import org.eclipse.search.ui.ISearchResultListener;
import org.eclipse.search.ui.ISearchResultPage;
import org.eclipse.search.ui.ISearchResultViewPart;
import org.eclipse.search.ui.SearchResultEvent;
import org.eclipse.swt.SWT;
import org.eclipse.swt.layout.FillLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Display;
import org.eclipse.swt.widgets.Text;
import org.eclipse.ui.IActionBars;
import org.eclipse.ui.IMemento;
import org.eclipse.ui.PartInitException;
import org.eclipse.ui.part.IPageSite;

import com.codeandme.searchprovider.FileSearchResultEvent;

public class SearchResultPage implements ISearchResultPage, ISearchResultListener {

 private String fId;
 private Composite fRootControl;
 private IPageSite fSite;
 private Text ftext;

 @Override
 public Object getUIState() {
  return null;
 }

 @Override
 public void setInput(ISearchResult search, Object uiState) {
  search.addListener(this);
 }

 @Override
 public void setViewPart(ISearchResultViewPart part) {
 }

 @Override
 public void setID(String id) {
  fId = id;
 }

 @Override
 public String getID() {
  return fId;
 }

 @Override
 public String getLabel() {
  return "Filesystem Search Results";
 }

 @Override
 public IPageSite getSite() {
  return fSite;
 }

 @Override
 public void init(IPageSite site) throws PartInitException {
  fSite = site;
 }

 @Override
 public void createControl(Composite parent) {
  fRootControl = new Composite(parent, SWT.NULL);
  fRootControl.setLayout(new FillLayout(SWT.HORIZONTAL));

  ftext = new Text(fRootControl, SWT.BORDER | SWT.READ_ONLY | SWT.H_SCROLL | SWT.V_SCROLL | SWT.CANCEL | SWT.MULTI);
 }

 @Override
 public void dispose() {
  // nothing to do
 }

 @Override
 public Control getControl() {
  return fRootControl;
 }

 @Override
 public void setActionBars(IActionBars actionBars) {
 }

 @Override
 public void setFocus() {
  fRootControl.setFocus();
 }

 @Override
 public void restoreState(IMemento memento) {
  // nothing to do
 }

 @Override
 public void saveState(IMemento memento) {
  // nothing to do
 }

 @Override
 public void searchResultChanged(SearchResultEvent event) {
  if (event instanceof FileSearchResultEvent) {
   Display.getDefault().asyncExec(new Runnable() {
    @Override
    public void run() {
     String newText = ftext.getText() + "\n" + ((FileSearchResultEvent) event).getAddedFile().getAbsolutePath();
     ftext.setText(newText);
    }
   });
  }
 }
}
Lots of getters and setters, but nothing complicated. For this example we use a simple text control to add the names of found files. setInput() will be called by the framework to link this view with a search result. Now we attach a listeners to get notified on changes on the result.

I found one caveat while implementing: when your query code (from there we trigger searchResultChanged()) raises an exception, you do not get the output on the console as you might expect. Basically this means that your result page remains empty without any notification that something went wrong. Use the debugger to single step through your code in that case.

Wednesday, June 3, 2015

Generic drag and drop in eclipse

The default drag and drop from SWT relies on the fact that source and target both agree on certain transfer types. The source adds the drop data, the target has to know how to deal with that data.

A drop target in eclipse therefore cannot deal with unknown objects by default. Eg you cannot drop your plugin local objects on a Navigator view. This article describes how you can drop your own objects into existing eclipse views and how to enrich your local drop target with generic drop support.

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.

Step 1: Simple drag support

Lets start with default SWT drag support. Create a new Plug-in Project named com.codeandme.draganddrop. Add a new view with a Text element to it. Name the text element txtInput. I expect you are familiar with that procedure.

Now we add TextTransfer support:
  int operations = DND.DROP_MOVE | DND.DROP_COPY;
  DragSource source = new DragSource(txtInput, operations);

  Transfer[] types = new Transfer[] { TextTransfer.getInstance() };
  source.setTransfer(types);

  source.addDragListener(new DragSourceListener() {
   @Override
   public void dragStart(DragSourceEvent event) {
    if (txtInput.getText().length() == 0)
     event.doit = false;
   }

   @Override
   public void dragSetData(DragSourceEvent event) {
    // for text drag to editors
    if (TextTransfer.getInstance().isSupportedType(event.dataType))
     event.data = txtInput.getSelectionText();
   }

   @Override
   public void dragFinished(DragSourceEvent event) {
   }
  });
This is default SWT dnd code, nothing special so far.

Step 1: Add drag support for generic objects

By default the action to be performed on a drop is implemented by the DropListener of the target. Fortunately eclipse provides a special transfer type that delegates the drop action to a dedicated class which we may provide in our plugin.

Switch to your plugin.xml and add a new Extension of type org.eclipse.ui.dropActions. Add an action element to it, set the id to com.codeandme.draganddrop.dropText and implement a class TextDropActionDelegate:
package com.codeandme.draganddrop;

import java.io.ByteArrayInputStream;

import org.eclipse.core.resources.IContainer;
import org.eclipse.core.resources.IFile;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.NullProgressMonitor;
import org.eclipse.core.runtime.Path;
import org.eclipse.swt.widgets.Text;
import org.eclipse.ui.part.IDropActionDelegate;

public class TextDropActionDelegate implements IDropActionDelegate {

 public static final String ID = "com.codeandme.draganddrop.dropText";

 @Override
 public boolean run(Object source, Object target) {
  if (source instanceof byte[]) {
   if (target instanceof IContainer) {
    IContainer parent = (IContainer) target;
    IFile file = parent.getFile(new Path("dropped text.txt"));
    if (!file.exists()) {
     try {
      file.create(new ByteArrayInputStream((byte[]) source), true, new NullProgressMonitor());
     } catch (CoreException e) {
      e.printStackTrace();
     }
    }

    return true;

   } else if (target instanceof Text)
    ((Text) target).setText(new String((byte[]) source));
  }

  return false;
 }
}
The run() method gets called when the drop action is to be performed. The target is automatically set to the object under the mouse when we perform the drop, eg a folder in a Navigator view. The provided code is a bit simplified, eg we do not try to adapt the target in case it is not an IContainer.

Now we need to add our drop delegate to our source object. Switch back to your view and modify the code:
  Transfer[] types = new Transfer[] { TextTransfer.getInstance(), PluginTransfer.getInstance() };
add a new transfer type: PluginTransfer.
   public void dragSetData(DragSourceEvent event) {
    // for text drag to editors
    if (TextTransfer.getInstance().isSupportedType(event.dataType))
     event.data = txtInput.getSelectionText();

    // for plugin transfer drags to navigator views
    if (PluginTransfer.getInstance().isSupportedType(event.dataType))
     event.data = new PluginTransferData(TextDropActionDelegate.ID, txtInput.getSelectionText().getBytes());
   }
When a plugin transfer is accepted by the target we need to set a PluginTransferData object that links to our action delegate and provides the source data.

Everything is in place, so give it a try: type and select some text in your view and drop it on a folder in the Project Explorer view.

Step 3: Add generic drop support to your own views

Generic drop support does not come entirely for free. If you want to add it to a JFace tree or table it is dead simple as that:

  int operations = DND.DROP_MOVE | DND.DROP_COPY;
  DropTarget target = new DropTarget(viewer.getControl(), operations);

  Transfer[] types = new Transfer[] { PluginTransfer.getInstance() };
  target.setTransfer(types);

  target.addDropListener(new PluginDropAdapter(viewer));
We may also reuse the PluginDropAdapter on simple Controls like text boxes. Therefore we need to overwrite some methods:
  target.addDropListener(new PluginDropAdapter(null) {
   @Override
   protected int determineLocation(DropTargetEvent event) {
    return LOCATION_ON;
   }

   @Override
   protected Object getCurrentTarget() {
    return txtTarget;
   }
  });
If you provide drop support in general it is advised to add the plugin transfer type to allow other plugins to use your drop support.

Friday, May 22, 2015

Unit Testing with scripts in EASE


In the company I work for we do lots of regression testing, mostly for interface testing of hardware devices. Therefore we needed a unit testbench similar to JUnit without the complexity of writing java code for our tests. So we implemented a simple Unit test framework for EASE.

Source code for this tutorial is available in the EASE scripts repository.

Step 1: Create a simple test script

Create a new Project in your workspace named JavaScript Unit Testing Tutorial. Create a new file Tests/Simple/01 Valid tests.js
// starts a simple test
startTest("empty", "an empty test case");
// ends a test
endTest();

// start another test
startTest("no test code", "a test containing no assertions");
print("Hi from valid test");
endTest();

// third test
startTest("valid assertions", "a test containing valid assertions");
// check
assertTrue(true);
endTest();

// code outside of a testcase
print('"' + getTestFile() + '" completed');
You might ask where these test functions come from as we do not load any modules. The unit test framework comes with a module called Unittest. It is hidden by default but will be loaded automatically when we execute EASE UnitTests. To unhide go to the Preferences/Scripting/Modules (Note: this is not necessary to use the module, it will only display it in UI components).

If you are familiar with unit testing in general you also know assertions and according methods like assertTrue(). In general these methods perform a check for validity. In case an expected result does not match with a current result, an error is generated for the containing test case.

So test cases are encapsulated between a startTest() and an endTest(). It is recommended to not use assertions outside test cases, yet not mandatory.

Step 2: Create and execute a test suite

To execute test files, we need to create a Test Suite, that sets up a test environment for us. Create a new Scripting/Script Testsuite named Testsuite.suite.  The editor will allow you to select test files you want to execute. Therefore we look for script files in the same project where the suite is located.

Select our previously created test file and hit the Run Test Suite button in the top right corner.



 A new view is opened that displays unit test results.



The top tree view reflects the file structure of our test files and displays decorators indicating the test execution result. If you select a test file, detailed results are displayed in the bottom section.

Step 3: Test errors

Create a new file Tests/Simple/02 Test errors.js.
// test containing assertions that fail
startTest("invalid assertions", "a test containing invalid assertions");
assertTrue(true);
assertTrue(false);
assertFalse(true);
assertFalse(false);
endTest();

// manually create a failure
startTest("failure", "test throwing a failure");
failure("test broken, stop execution here");

// an exception would also create a failure
throw new java.lang.Exception("code exception");
endTest();

startTest("never to be reached");
// not being reached as the failure above terminates test file execution
endTest();
Save the test, add it to your suite and run the suite right away. When an assertion fails, error markers are generated on your script files on the according code location. You will also see the most critical assertion reflected in the Script Unit Test view. Double clicking on errors will open the source editor on the corresponding location.



Similar to JUnit there exist two different types of things that can go wrong: errors and failures. Errors are assertions that do not meet their criteria. They are recoverable, meaning script execution of the test file continues.

Failures on the other hand are not recoverable, so script execution of that test file is terminated immediately.

Step 4: Test Suite configuration

Typically tests need to be adapted to a certain environment. In general you do not want test engineers to modify your script code. So the test suite supports setting of Variables that are automatically available in all test files. The Setup section allows to execute arbitrary code on the Test Suite start, Test File start, startTest() call and also for the corresponding teardown sections. As you may provide multiple suite files within a project, these secions are a good place to adapt tests according to your environment.

Optional: Test automation

Often tests need to be executed automatically, eg for a nightly test run. The Unittest module allows to run a testsuite from a script. Together with the headless application from EASE you can run a suite from the commandline and create a report (we currently support the JUnit xml format that can be picked up from Hudson/Jenkins).

Optional: Additional assertions

If you want to provide your own assertion methods, simply create your own module and let your wrapped method return an IAssertion. If you call your method from within a test script it will automatically validate your assertion method.

So why do I want to write scripted tests?

In the company I work for we use these kind of tests for interface verification of hardware devices. Therefore we provide our own modules that allow us to send stimuli and validate expected responses. We also use it in combination with analog measurement devices to verify that certain hardware parameters are within valid ranges.

Currently Script Unit Testing is supported for the Rhino script engine only.

Wednesday, April 8, 2015

Live charting with EASE

Recently we added charting support to EASE using the Nebula XY chart widget. Say you have a script acquiring some data you now may plot them as your measurement advances.

Step 1: Installation

For this tutorial you need to register the nebula update site:
http://download.eclipse.org/technology/nebula/snapshot
in Preferences/Install/Update/Available Software Sites.

Afterwards install EASE and add EASE Charting Support to install all required modules. This component depends on Nebula Visualization Widgets, therefore we added the nebula update site before. Currently you have to stick to the nighty update site of EASE as charting is not part of the current release.

Step 2: Some example plots

 
Try out this little script to get these sample plots:
loadModule('/Charting');

figure("Simple Charts");
clear();

series("linear", "m+");
for (x = 0; x <= 20; x += 1)
 plotPoint(x, x / 10 - 1);

series("1/x", "ko:");
for (x = 1; x <= 20; x += 0.2)
 plotPoint(x, 4/x);

series("sine", "bx");
for (x = 0; x < 20; x += 0.05)
 plotPoint(x, Math.sin(x) * Math.sin(3 * x));

figure("Advanced");
clear();

series("drop", "gd");
for (t = 0; t < 2; t += 0.01)
 plotPoint(t, Math.pow(Math.E, t * -3) * Math.cos(t * 30));

series("upper limit", "rf--");
plot([0, 2], [0.4, 0.4]);

series("lower limit", "rf--");
plot([0, 2], [-0.4, -0.4]);
Run the script either in the Script Shell or execute it using launch targets.

Step 3: Charting Module API

The API of the charting module tries to keep close to MatLab style, so the format string for a series is almost identical. You may even omit to create figures or series and start plotting right away and we create everything necessary on the fly.

For a better user experience we extended the XYChart a bit by allowing to zoom directly using the scroll wheel either over the plot or its axis. Use a double click for an auto-zoom.

Sunday, February 22, 2015

Reformatting multiple source files

Recently I had to apply a new code formatter template to a project. Changing 50+ files by hand seemed to be too much monkey work. Writing a custom plug-in seemed to be too much work. Fortunately there is this great scripting framework to accomplish this task quite easily.

Step 1: Detecting affected source files

I have already blogged about EASE and how to install it. So I went directly to the script shell to fetch all java files form a certan project:
loadModule('/System/Resources');

 org.eclipse.ease.modules.platform.ResourcesModule@5f8466b4
files = findFiles("*.java", getProject("org.eclipse.some.dedicated.project"), true)
 [Ljava.lang.Object;@1b61effc
Now we have an array of IFile instances. Easy, isn't it?

Step 2: The formatter script

Ideas how to format source files can be found in the forum. Taking the script and porting it to JS is simple:
function formatUnitSourceCode(file) {
 unit = org.eclipse.jdt.core.JavaCore.create(file);

 unit.becomeWorkingCopy(null);

 formatter = org.eclipse.jdt.core.ToolFactory.createCodeFormatter(null);
 range = unit.getSourceRange();
 formatEdit = formatter
   .format(
     org.eclipse.jdt.core.formatter.CodeFormatter.K_COMPILATION_UNIT
       | org.eclipse.jdt.core.formatter.CodeFormatter.F_INCLUDE_COMMENTS,
     unit.getSource(), 0, unit.getSource().length(), 0, null);
 if (formatEdit.hasChildren()) {
  unit.applyTextEdit(formatEdit, null);
  unit.reconcile(org.eclipse.jdt.core.dom.AST.JLS4, false, null, null);
 }

 unit.commitWorkingCopy(true, null);
}

Step 3: glueing it all together

Load the function into your script shell, fetch the list of files as in step 1 and then process all files in a loop:
for each (file in files) formatUnitSourceCode(file);
That's it. This short script uses your current source formatter settings and applies it to all selected files.

This little helper is available online in the EASE script repository.

Wednesday, January 14, 2015

EASE 0.1.0 - the very first release

I am proud to announce the very first release of the Eclipse Advanced Scripting Environment (EASE).

In case you have no idea what this is about, check out the project page. Afterwards you definitely need to install it right away in your IDE and start scripting.

Some facts: 
  • executes script code in your IDE, providing access to the running JRE and thus to the whole Eclipse API
  • supports JavaScript, Jython, Groovy and JRuby (see details)
  • allows to dynamically integrate scripts into toolbars and menus
  • extensible via script libraries (write your own)

This project started as an in house company solution some years ago. When I released it as open source back in 2013 I was quite astonished about the interest from the community. Soon this project moved into the e4 incubator which gave us a great chance to evolve and build up an infrastructure.
Last summer EASE was accepted as an Eclipse incubation project. With our first release we feel to be part of the eclipse community.

Let me take this opportunity to thank all the people who helped to make this happen. When I started out almost 2 years ago I did not expect to meet such an open minded community. So if you think of starting your own project I can just encourage you to take the first step. There are helping hands everywhere, trying to push you forward. Did I already say that I love this community?

XMLMemento: a simpe way to process XML files


Reading and writing simple XML files is a common task nowadays. Java comes with some powerful frameworks like SAX or Xerces to accomplish this task. But sometimes we look for something simpler. Today we will have a look at XMLMemento, a utility class by Eclipse that hides most of the complicated stuff from us.

Source code for this tutorial is available on googlecode as a single zip archive, as a Team Project Set or you can checkout the SVN projects directly. 

Preparations

We will use following XML file for this tutorial
<?xml version="1.0" encoding="UTF-8"?>
<root>
 <project name="org.eclipse.ease">
  <description>EASE is a scripting environment for Eclipse. It allows to
   create, maintain and execute script code in the context of the
   running Eclipse instance.</description>
  <releases>
   <release version="0.1.0" />
   <release version="0.2.0" />
  </releases>
 </project>
 <project name="org.eclipse.tycho">
  <releases>
   <release version="0.16.0" />
   <release version="0.17.0" />
  </releases>
 </project>
</root>

The code samples below use a slightly modified version of XMLMemento. To reuse it more easily in non-Eclipse projects I removed Eclipse specific exceptions, messages and interfaces. If you intend to use XMLMemento within Eclipse, simply stick to the original version contained in the org.eclipse.ui.workbench plugin. For pure Java projects simply copy XMLMemento as it is used in this tutorial.

Step 1: Writing XML

First we need to create a root node. Afterwards we create child nodes and set their attributes.
package com.codeandme.xmlmemento;

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;

import org.eclipse.ui.XMLMemento;

public class WriteXML {

 public static void main(String[] args) {

  XMLMemento rootNode = XMLMemento.createWriteRoot("root");

  // first project
  XMLMemento projectNode = rootNode.createChild("project");
  projectNode.putString("name", "org.eclipse.ease");
  projectNode
  .createChild("description")
  .putTextData(
    "EASE is a scripting environment for Eclipse. It allows to create, maintain and execute script code in the context of the running Eclipse instance.");

  XMLMemento releasesNode = projectNode.createChild("releases");
  releasesNode.createChild("release").putString("version", "0.1.0");
  releasesNode.createChild("release").putString("version", "0.2.0");

  // second project
  projectNode = rootNode.createChild("project");
  projectNode.putString("name", "org.eclipse.tycho");

  releasesNode = projectNode.createChild("releases");
  releasesNode.createChild("release").putString("version", "0.16.0");
  releasesNode.createChild("release").putString("version", "0.17.0");

  // output to console
  System.out.println(rootNode);

  // write to file
  try {
   File tempFile = new File("XML sample.xml");
   FileWriter fileWriter = new FileWriter(tempFile);
   rootNode.save(fileWriter);

  } catch (IOException e) {
   e.printStackTrace();
  }
 }
}
Line 13: create the root node
Line 16: create a child node below root
Line 17: set an attribute on project node
Line 20: set text content of a node
Line 36: serialize XML to String (uses node.toString())
Line 42: write XML to File


Step 2: reading XML

Reading XML is also very easy. Just create a read root and start traversing child elements:
package com.codeandme.xmlmemento;

import java.io.FileReader;

import org.eclipse.ui.XMLMemento;

public class ReadXML {

 public static void main(String[] args) {
  try {
   XMLMemento rootNode = XMLMemento.createReadRoot(new FileReader("XML sample.xml"));

   System.out.println("Projcts:");
   for (XMLMemento node : rootNode.getChildren())
    System.out.println("\t" + node.getString("name"));

   System.out.println("EASE versions:");
   for (XMLMemento node : rootNode.getChildren("project")) {
    if ("org.eclipse.ease".equals(node.getString("name"))) {
     for (XMLMemento versionNode : node.getChild("releases").getChildren("release")) {
      System.out.println("\t" + versionNode.getString("version"));
     }
    }
   }

  } catch (Exception e) {
   e.printStackTrace();
  }
 }
}
LIne 11: parse input and extract the root node
Line 14: iterate over all child nodes
Line 15: read node attribute