The Maven Embedder

The Maven Embedder is used by the Maven CLI, by IDE integration projects like Mevenide and potentially any tool that needs to embed Maven's capabilities. You could embed Maven in a Continuous Integration application to run Maven build, an application lifecycle management (ALF) tool, or Ant tasks that utilize Maven's functionality. These are just a few examples of what the Maven Embedder can be used for.

A Simple Example

        File projectDirectory = new File( getBasedir(), "src/examples/simple-project" );

        File user = new File( projectDirectory, "settings.xml" );

        Configuration configuration = new DefaultConfiguration()
            .setUserSettingsFile( user )
            .setClassLoader( Thread.currentThread().getContextClassLoader() );

        ConfigurationValidationResult validationResult = MavenEmbedder.validateConfiguration( configuration );

        if ( validationResult.isValid() )
        {
            MavenEmbedder embedder = new MavenEmbedder( configuration );

            MavenExecutionRequest request = new DefaultMavenExecutionRequest()
                .setBaseDirectory( projectDirectory )
                .setGoals( Arrays.asList( new String[]{"clean", "install"} ) );

            MavenExecutionResult result = embedder.execute( request );

            if ( result.hasExceptions() )
            {
                fail( ((Exception)result.getExceptions().get( 0 )).getMessage() );
            }

            // ----------------------------------------------------------------------------
            // You may want to inspect the project after the execution.
            // ----------------------------------------------------------------------------

            MavenProject project = result.getProject();

            // Do something with the project

            String groupId = project.getGroupId();

            String artifactId = project.getArtifactId();

            String version = project.getVersion();

            String name = project.getName();

            String environment = project.getProperties().getProperty( "environment" );

            assertEquals( "development", environment );

            System.out.println( "You are working in the '" + environment + "' environment!" );
        }
        else
        {
            if ( ! validationResult.isUserSettingsFilePresent() )
            {
                System.out.println( "The specific user settings file '" + user + "' is not present." );
            }
            else if ( ! validationResult.isUserSettingsFileParses() )
            {
                System.out.println( "Please check your settings file, it is not well formed XML." );
            }
        }

A Note on Configuring Settings

Currently there is a notion of a user settings, and a global settings where either can specify information about the following:

  • Local Repository
  • Proxies
  • Mirrors
  • Server Configurations
  • Plugin Groups

If you are using the embedder it is entirely your responsibility to take user and global settings information and specify it in the embedder configuration. The embedder carries with it no defaults about where these are located and how they are used. If you want your embedded use of Maven to mimic the behavior of the Maven CLI insofar as settings use then use the following code:

        Configuration configuration = new DefaultConfiguration()
            .setUserSettingsFile( MavenEmbedder.DEFAULT_USER_SETTINGS_FILE )
            .setGlobalSettingsFile( MavenEmbedder.DEFAULT_GLOBAL_SETTINGS_FILE )
            .setClassLoader( Thread.currentThread().getContextClassLoader() );

        ConfigurationValidationResult validationResult = MavenEmbedder.validateConfiguration( configuration );

        if ( validationResult.isValid() )
        {
            // If the configuration is valid then do your thang ...
        }

Also note that the user and global settings are merged, and the user settings are dominant.

Accessing the Underlying Plexus Container

Though it is not recommended for general use, it is possible to get at the underlying Plexus Container instance if you wish to lookup custom components. The Maven Embedder was specifically designed to be used for Maven and not a general purpose use of Plexus. So if you use this method then you use it at your peril. You can access the Plexus Container using the following:

        Configuration configuration = new DefaultConfiguration()
            .setUserSettingsFile( MavenEmbedder.DEFAULT_USER_SETTINGS_FILE )
            .setGlobalSettingsFile( MavenEmbedder.DEFAULT_GLOBAL_SETTINGS_FILE )
            .setClassLoader( Thread.currentThread().getContextClassLoader() );

        ConfigurationValidationResult validationResult = MavenEmbedder.validateConfiguration( configuration );

        if ( validationResult.isValid() )
        {
            // If the configuration is valid then do your thang ...
        }

        MavenEmbedder embedder = new MavenEmbedder( configuration );

        PlexusContainer container = embedder.getPlexusContainer();

        // Do what you like with the container ...