z2-Environment

h1. Groovy Add-on

The Groovy Add-on allows to use the "Groovy language":http://groovy.codehaus.org/ within z2 applications. It supports pure Groovy modules as well as modules containing both Java and Groovy source code.

h2. Repository

"z2-addons-groovy":https://redmine.z2-environment.net/projects/z2-addons/repository/z2-addons-groovy

h2. Version map

|_. add-on version |_. Groovy version |

| v2.2, v2.3 | 2.0.6 |

| v2.4 | 2.3.11 |

| v2.7 | 2.5.4 |

| v2.8, master | 3.0.1 |

h2. How does it work?

The z2-Groovy compiler checks for each source component (i.e. @java/src.api@ and @java/src.impl@ ) whether it contains pure Groovy source files or Java and Groovy sources and chooses the appropriate compiler.

The Joint-Compiler of Groovy SDK compiles mixed Groovy and Java sources within three passes: In step 1) all Groovy classes are compiled as stubs (i.e. only the signatures w/o any lines of code) so that in step 2) the Java compiler from the JDK can compile all Java classes and resolve all dependencies to Groovy classes using the stubs. In step 3) the Groovy source files are translated into bytecode - since the Java classes are now translated, references from Groovy to Java can be also resolved correctly.

If however no Java sources are found step 1 and 2 are skipped and the compilation process is speed-up by leaving only the plain Groovy compiler!

A mixture of Groovy classes and Java classes across z2 modules is supported as well. Since cyclic dependencies are not allowed this does not even require the Groovy Joint-Compiler.

h2. How do I use it?

h3. 1) Include the Groovy Add-on

At first you need to add the Groovy Add-on repository to your environment with @gitcr.uri=http://git.z2-environment.net/z2-addons.groovy@ (see also the @environment@ module of [[Sample-groovy-in-Z2]]).

@environment/groovyAddon.properties:@

<pre>

com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up

# git stored component repository

com.zfabrik.component.type=com.zfabrik.gitcr

# true <=> optional repository. If gitcr.uri is invalid, then this gitcr will be ignore silently  

gitcr.optional=true

# this can also point to a remote repository like 

# ssh://myserver/some/git/repo

gitcr.uri=https://www.z2-environment.net/git/z2-addons.groovy

# the git branch to use (e.g. 'master')

gitcr.branch=master

</pre>

h3. 2) Write code

Put Groovy source files into the same structure as Java source files - i.e. @<module-name>/java/src.api@ , @<module-name>/java/src.impl@ or @<module-name>/java/src.test@ (see the @com.zfabrik.samples.groovy.web@ module of [[Sample-groovy-in-Z2]]).

h3. 3) Define compile order

Edit the Java component descriptor and change/add the @java.compile.order@ property:

@<module-name>/java/z.properties:@

<pre><code>

com.zfabrik.component.type=com.zfabrik.java

java.privateReferences=...

java.publicReferences=...

java.compile.order = groovy

</code></pre>

When using Spring with AspectJ the compile order will be:

@java.compile.order = groovy, spring_aspectj@

h3. 4) Adjust memory settings

You might need to change the heap and the perm size settings of the web worker in your environment since Groovy is usually more memory hungry than Java.

@environment/webWorker.properties:@

<pre><code>

...

worker.process.vmOptions=\

 -Xmx128m -Xms128m -XX:+HeapDumpOnOutOfMemoryError -XX:MaxPermSize=256m \

...

</code></pre>

h2. Trouble Shooting

h3. Trouble running code in Eclipse

When working with Groovy code in Eclipse and having resolved a module's classpath with the Eclipsoid plugin you will have the Groovy libraries coming with this addon on the Eclipse project classpath. Eclipse's Groovy support plugin brings its own version of the groovy-all library that may (and typically will) differ from the add-on's version.

You will see an error message of the form

<pre>

groovy-all is loaded in version x.y.z and you are trying to load version a.b.c

</pre>

*Fix:* Remove the Groovy Libraries classpath container from your project by opening the project properties, choosing "Java build path" and "Libraries".