---
  Usage
  ---
  John Casey
  ---
  2008-08-02
  ---

 ~~ 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

Usage

  This page documents the basic usage of the Maven invocation API.

* Hello, World

  The simplest possible way to use the invocation API is to construct the
  invoker and request at the same time, and simply call
  <<<invoker.execute(request)>>>. In this example, we don't care about the build
  result:

+---+
InvocationRequest request = new DefaultInvocationRequest();
request.setPomFile( new File( "/path/to/pom.xml" ) );
request.setGoals( Collections.singletonList( "install" ) );

Invoker invoker = new DefaultInvoker();
invoker.execute( request );
+---+

  This code will execute a new Maven build to the <<<install>>> lifecycle phase
  for the project defined at <<</path/to/pom.xml>>>. If the build fails, we will
  remain blissfully ignorant...
  
* Checking the Exit Code

  If we wanted to detect a build failure in the above example, we could simply
  add the following lines:
  
+---+
InvocationResult result = invoker.execute( request );

if ( result.getExitCode() != 0 )
{
    throw new IllegalStateException( "Build failed." );
}
+---+

  This will retrieve the exit code from the invocation result, and throw
  an exception if it's not <<<0>>> (the traditional all-clear code). Note that
  we could capture the build output by adding an <<<InvocationOutputHandler>>>
  instance to either the <<<invoker>>> or the <<<request>>>.
  
* Caching the Invoker

  Since you can specify global options for Maven invocations via the
  <<<Invoker>>> configuration, it will often make sense to configure a single
  <<<Invoker>>> instance, and reuse it over multiple method calls:
  
+---+
// we will always call the same goals...
private static final List<String> PUBLISH_GOALS = Arrays.asList( "clean", "site-deploy" );

// define a field for the Invoker instance.
private final Invoker invoker;

// now, instantiate the invoker in the class constructor...
public SomeClass( File localRepositoryDir )
{
    Invoker newInvoker = new DefaultInvoker();
    newInvoker.setLocalRepositoryDirectory( localRepositoryDir );
    
    this.invoker = newInvoker;
}

// this method will be called repeatedly, and fire off new builds...
public void publishSite( File siteDirectory ) throws PublishException
{
    InvocationRequest request = new DefaultInvocationRequest();
    request.setBaseDirectory( siteDirectory );
    request.setInteractive( false );
    request.setGoals( PUBLISH_GOALS );
    
    InvocationResult result = invoker.execute( request );
    
    if ( result.getExitCode() != 0 )
    {
        if ( result.getExecutionException() != null )
        {
            throw new PublishException( "Failed to publish site.",
                                        result.getExecutionException() );
        }
        else
        {
            throw new PublishException( "Failed to publish site. Exit code: " + 
                                         result.getExitCode() );
        }
    }
}
+---+

  As you can see, we're using the same local repository location (since the
  site-generation artifacts will most likely be common to most sites), the same
  invoker instance (it's configured, we may as well reuse it), and the same set
  of goals per build. We can actually accommodate a fairly complex configuration
  of the Invoker without adding complexity to the <<<publishSite>>> method in this manner.

* Configuring the Maven Home Directory

  You can use the method <<<Invoker.setMavenHome()>>> to specify which Maven executable it should use.
  If you don't provide an explicit value for this setting, the <<<Invoker>>> will automatically try to detect
  a Maven installation by evaluating the system property <<<maven.home>>> and the environment variable <<<M2_HOME>>>.

  <<Note:>> If you use the invocation API in tests run by the {{{../../plugins/maven-surefire-plugin}Maven Surefire Plugin}},
  you need to tell Surefire to pass the system property <<<maven.home>>> to the tests in order for the automatic Maven
  detection to work:

+---+
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.12.4</version> <!-- see surefire-page for available versions -->
        <configuration>
          <systemPropertyVariables>
            <maven.home>${maven.home}</maven.home>
          </systemPropertyVariables>
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>
+---+