src/site/apt/index.apt.vm

 ------
 Introduction
 ------
 Olivier Lamy
 ------
 2013-07-24
 ------

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

${project.name}

  This component provides some utilities to interpret/execute some scripts for various implementations: groovy or beanshell.

* Dependency declaration

+---------
    <dependency>
      <groupId>org.apache.maven.shared</groupId>
      <artifactId>maven-script-interpreter</artifactId>
      <version>${project.version}</version>
    </dependency>
+---------

* Interpret beanshell script

+---------

    ScriptInterpreter interpreter = new BeanShellScriptInterpreter();
    ByteArrayOutputStream out = new ByteArrayOutputStream();
    interpreter.evaluateScript( script content, extra classPath entries,
                              Map<String, ? extends Object> globalVariables, new PrintStream( out ) );
    out.toString() returns script output

+---------

* Interpret a groovy script

+---------

    ScriptInterpreter interpreter = new GroovyScriptInterpreter();
    ByteArrayOutputStream out = new ByteArrayOutputStream();
    interpreter.evaluateScript( script content, extra classPath entries,
                              Map<String, ? extends Object> globalVariables, new PrintStream( out ) );
    out.toString() returns script output

+---------

* Using ScriptRunner

  ScriptRunner class will detect the script file to run based on supported extensions (.bsh,.groovy).

  This class will search in the provided directory the script with the provided fileName and the supported extensions.

  See {{{./apidocs/org/apache/maven/shared/scriptinterpreter/ScriptRunner.html}javadoc}} for run method.

+---------

    ScriptRunner scriptRunner = new ScriptRunner( );
    scriptRunner.run( "test", new File( "src/test/resources/bsh-test" ), "verify", buildContext(),
                      new FileLogger( logFile ) );
+---------

* Mirror output from script interpreter

  In order to do something more with script output, eg. log by your application you must implement FileLoggerMirrorHandler

+---------

class MyMirrorHandler implements FileLoggerMirrorHandler
{
    void consumeOutput( String message )
    {
        // this method is invoked every time when flush occurs on the underlying stream.
    }
}

+---------

  Now use it:

+---------

      ScriptRunner scriptRunner = new ScriptRunner( );
      scriptRunner.run( "test", new File( "src/test/resources/bsh-test" ), "verify", buildContext(),
                        new FileLogger( logFile, new MyMirrorHandler() ) );

+---------

** Global variables

  Your scripts will have by default two global variables:

  * basedir: the base directory of your script

  * context: the build context (see below)

  []

   You can add more global variables as it.

+---------

    ScriptRunner scriptRunner = new ScriptRunner( );
    scriptRunner.setGlobalVariable( name, value );

+---------

** Build context

  You can pass some values to your script using a execution context which have the type <<<Map<String, ? extends Object> context>>>.

+---------
    Map<String, Object> context = new HashMap<String, Object>();
    context.put( "foo", "bar" );
    return context;

    // in your bsh script
    String value = context.get( "foo" );
    value will be "bar"

    // in your groovy script
    context.get("foo")
+---------

** Additionnal classpath entries

  You can add some additional classpath entries for your script execution

+---------

    List<String> classpathEntries = list of jar paths
    ScriptRunner scriptRunner = new ScriptRunner( );
    scriptRunner.setClassPath( classpathEntries );
    scriptRunner.run( "test", new File( "src/test/resources/bsh-test" ), "verify", buildContext(),
                      new FileLogger( logFile ) );
+---------