PME @ Red Hat

• Overview
• Configuration
• Groovy Scripts
  • Invocation stages
• API
• Utility Functions
  • inlineProperty
  • overrideProjectVersion
• Example
• Developing Groovy Scripts

Overview

PME offers the ability to run arbitrary groovy scripts on the sources prior to running the build. This allows PME to be extensible by the user and to process other files not just Maven POMs.

Configuration

If the property -DgroovyScripts=<value>,.... is set, PME will load the remote Groovy script file.

The argument should a comma separated list of either:

• group:artifact:version (with optional type and classifiers).
• A http:// or https:// URL.
• A file:// URL

If using a GAVTC, the remote groovy file can be deployed by e.g.

<build>
  <plugins>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>build-helper-maven-plugin</artifactId>
      <version>1.5</version>
      <inherited>false</inherited>
      <executions>
        <execution>
          <id>attach-artifacts</id>
          <phase>package</phase>
          <goals>
            <goal>attach-artifact</goal>
          </goals>
          <configuration>
            <artifacts>
              <artifact>
                <file>Sample.groovy</file>
                <type>groovy</type>
              </artifact>
            </artifacts>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

The deployed file can then be used with e.g.

mvn -DgroovyScripts=org.commonjava.maven.ext:depMgmt1:groovy:1.0 clean install

Groovy Scripts

Each groovy script will be run on the execution root (i.e. where Maven is invoked).

Each script must use the following annotations:

import org.commonjava.maven.ext.core.groovy.BaseScript
import org.commonjava.maven.ext.core.groovy.InvocationStage
import org.commonjava.maven.ext.core.groovy.PMEBaseScript
import org.commonjava.maven.ext.core.groovy.InvocationPoint
...

@InvocationPoint(invocationPoint = InvocationStage.FIRST)
@PMEBaseScript BaseScript pme

The API can then be invoked by e.g.

pme.getBaseDir()

NOTE : Be careful not to use pme.getProperties() or pme.getProject().getProperties() as that actually calls the Groovy language API

Invocation stages

In the example script, we saw the use of the @InvocationPoint annotation which controls when the script is run. It takes a single argument, invocationPoint, with the type InvocationStage. The possible values for InvocationStage are PREPARSE, FIRST, LAST, and ALL. These values are relative to when the manipulations to the POM files are made. The table below provides a description of the invocation stages available for running a script.

API

The following API is available:

Utility Functions

Currently, two main utility functions are provided:

inlineProperty

This function is typically used to deal with the problem where an upstream may use a single property for several distinct SCM Builds. This can lead to issues, so by ‘inlining’ the property it can avoid them.

overrideProjectVersion

Occasionally upstream projects have circular dependencies in their build. This can typically happen if the first build creates a BOM that is used by multiple subsequent builds. If rebuilds (primarily with a suffix) occur then the versions can get out of sync and build errors arise. This function effectively ‘locks’ the subsequent builds to the suffix value of the first.

The above diagram shows two different SCM builds. The first has a sub-module that is a BOM that references the following SCM builds. This BOM is imported into the parent’s dependencyManagement. The second SCM build inherits this parent. If the first has been rebuilt twice (hence the rebuild-2 suffix) then the BOM will refer to the incorrect version of SCM Build 2 (1.0.rebuild-2 instead of 1.0.rebuild-1). By using overrideProjectVersion it is possible to force SCM Build 2 to use suffix rebuild-2 thereby making it have the correct version.

Example

A typical groovy script that alters a JSON file on disk might be:

import groovy.json.JsonOutput
import groovy.json.JsonSlurper
import groovy.util.logging.Slf4j
import org.commonjava.maven.ext.core.groovy.BaseScript
import org.commonjava.maven.ext.core.groovy.InvocationStage
import org.commonjava.maven.ext.core.groovy.PMEBaseScript
import org.commonjava.maven.ext.core.groovy.InvocationPoint

@InvocationPoint(invocationPoint = InvocationStage.FIRST)
@PMEBaseScript BaseScript pme

@Slf4j
public class Processor
{
    File basedir

    private void processJson(Map n) {
        ...
    }

    def execute() {
        log.info("Running ShrinkwrapProcessor...")

        def shrinkwrap = new File(basedir.toString() + File.separator + "shrink.json")

        log.info("shrinkwrap json is " + shrinkwrap)

        if (shrinkwrap.exists()) {
            log.info ("Found file {}", shrinkwrap)

            LinkedHashMap json = new JsonSlurper().parseText(shrinkwrap.text)

            processJson(json)

            shrinkwrap.write(JsonOutput.prettyPrint(JsonOutput.toJson(json)))
        }
    }
}

def Processor sp = new Processor(basedir:pme.getBaseDir()))
sp.execute()

Developing Groovy Scripts

To make it easier to develop scripts for both PME (this project) and GME an example project has been set up. The manipulator-groovy-examples provides a framework to develop and test such scripts.