org.apache.maven.plugin.AbstractMojo Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of maven-plugin-api Show documentation

The API for plugins - Mojos - development.

There is a newer version: 4.0.0-rc-2

/*
 * 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.
 */
package org.apache.maven.plugin;

import java.util.Map;

import org.apache.maven.plugin.logging.Log;
import org.apache.maven.plugin.logging.SystemStreamLog;

/**
 * Abstract class to provide most of the infrastructure required to implement a Mojo except for
 * the execute method.

 * The implementation should have a Mojo annotation with the name of the goal:
 *  *   @Mojo( name = "<goal-name>" )
 * 
 * 
 * There are also a number of attributes which can be used to control how and when the
 * Mojo is executed:
 * 
 * 
 *  
 *  
 *      
 *      
 *      
 *      
 *  
 *  
 *      
 *      
 *      
 *      
 *  
 *  
 *      
 *      
 *      
 *      
 *  
 *  
 *      
 *      
 *      
 *      
 *  
 *  
 *      
 *      
 *      
 *      
 *   
 *   
 *      
 *      
 *      
 *      
 *   
 *   
 *      
 *      
 *      
 *      
 *   
 *   
 *      
 *      
 *      
 *      
 *   
 *   
 *      
 *      
 *      
 *      
 *   
 *   
 *      
 *      
 *      
 *      
 *   
 * mojo annotation attributesDescriptor Element Annotation Required? Notes
goal name = "<goal-name>" Yes The name for the Mojo that users will reference from the command line to execute the Mojo directly,
 *      or inside a POM in order to provide Mojo-specific configuration.
implementation none (detected) Yes The Mojo's fully-qualified class name (or script path in the case of non-Java Mojos).
language none (detected) No. Default: java The implementation language for this Mojo (Java, beanshell, etc.).
configurator configurator = "<role-hint>" No The configurator type to use when injecting parameter values into this Mojo. The value is normally
 *          deduced from the Mojo's implementation language, but can be specified to allow a custom
 *          ComponentConfigurator implementation to be used.
 *          

 *          NOTE: This will only be used in very special cases, using a highly controlled vocabulary of possible
 *          values. (Elements like this are why it's a good idea to use the descriptor tools.)
 *      
phase defaultPhase = LifecyclePhase.<phase> No Binds this Mojo to a particular phase of the standard build lifecycle, if specified.
 *          

 *          NOTE: This is only required if this Mojo is to participate in the standard build process.
 *      
execute @Execute
 *       ( phase=LifecyclePhase.<phase>, goal= "<goal-name>", lifecycle="<lifecycle-id>" ) No When this goal is invoked, it will first invoke a parallel lifecycle, ending at the given phase.
 *          If a goal is provided instead of a phase, that goal will be executed in isolation.
 *          The execution of either will not affect the current project, but instead make available the
 *          ${executedProject} expression if required. An alternate lifecycle can also be provided:
 *          for more information see the documentation on the
 *          build lifecycle.
 *      
requiresDependencyResolution requiresDependencyResolution = ResolutionScope.<scope> No Flags this Mojo as requiring the dependencies in the specified scope (or an implied scope) to be
 *          resolved before it can execute.
 *          

 *          NOTE: Currently supports compile, runtime, and test scopes.
 *      
description none (detected) No The description of this Mojo's functionality. Using the toolset, this will be the class-level
 *          Javadoc description provided.

 *          NOTE: While this is not a required part of the Mojo specification, it SHOULD be provided to
 *          enable future tool support for browsing, etc. and for clarity.
 *      
parameters N/A No Specifications for the parameters which this Mojo uses will be provided in parameter sub-elements
 *          in this section.
 *          

 *          NOTE: Parameters are discussed in more detail below.
 *      
 * This is only a small set of all the options. A complete list can be found at
 * 
 * Maven Plugin Tool for Annotations.
 *
 * @see Guide to Developing Java Plugins
 * @see Guide to Configuring Plug-ins
 * @see Mojo API Specification
 *
 */
public abstract class AbstractMojo implements Mojo, ContextEnabled {
    /** Instance logger */
    private Log log;

    /** Plugin container context */
    private Map pluginContext;

    /**
     * @deprecated Use SLF4J directly
     */
    @Deprecated
    @Override
    public void setLog(Log log) {
        this.log = log;
    }

    /**
     * 

     * Returns the logger that has been injected into this mojo. If no logger has been setup yet, a
     * SystemStreamLog logger will be created and returned.
     * 
     * Note:
     * The logger returned by this method must not be cached in an instance field during the construction of the mojo.
     * This would cause the mojo to use a wrongly configured default logger when being run by Maven. The proper logger
     * gets injected by the Plexus container after the mojo has been constructed. Therefore, simply call this
     * method directly whenever you need the logger, it is fast enough and needs no caching.
     *
     * @see org.apache.maven.plugin.Mojo#getLog()
     * @deprecated Use SLF4J directly
     */
    @Deprecated
    @Override
    public Log getLog() {
        if (log == null) {
            log = new SystemStreamLog();
        }

        return log;
    }

    @Override
    public Map getPluginContext() {
        return pluginContext;
    }

    @Override
    public void setPluginContext(Map pluginContext) {
        this.pluginContext = pluginContext;
    }
}

Descriptor Element	Annotation	Required?	Notes
goal	name = "<goal-name>"	Yes	The name for the Mojo that users will reference from the command line to execute the Mojo directly, * or inside a POM in order to provide Mojo-specific configuration.
implementation	none (detected)	Yes	The Mojo's fully-qualified class name (or script path in the case of non-Java Mojos).
language	none (detected)	No. Default: `java`	The implementation language for this Mojo (Java, beanshell, etc.).
configurator	configurator = "<role-hint>"	No	The configurator type to use when injecting parameter values into this Mojo. The value is normally * deduced from the Mojo's implementation language, but can be specified to allow a custom * ComponentConfigurator implementation to be used. * * NOTE: This will only be used in very special cases, using a highly controlled vocabulary of possible values. (Elements like this are why it's a good idea to use the descriptor tools.)* *
phase	defaultPhase = LifecyclePhase.<phase>	No	Binds this Mojo to a particular phase of the standard build lifecycle, if specified. * * NOTE: This is only required if this Mojo is to participate in the standard build process. *
execute	@Execute * ( phase=LifecyclePhase.<phase>, goal= "<goal-name>", lifecycle="<lifecycle-id>" )	No	When this goal is invoked, it will first invoke a parallel lifecycle, ending at the given phase. * If a goal is provided instead of a phase, that goal will be executed in isolation. * The execution of either will not affect the current project, but instead make available the * `${executedProject}` expression if required. An alternate lifecycle can also be provided: * for more information see the documentation on the * build lifecycle. *
requiresDependencyResolution	requiresDependencyResolution = ResolutionScope.<scope>	No	Flags this Mojo as requiring the dependencies in the specified scope (or an implied scope) to be * resolved before it can execute. * * NOTE: Currently supports compile, runtime, and test* scopes.* *
description	none (detected)	No	The description of this Mojo's functionality. Using the toolset, this will be the class-level * Javadoc description provided. * NOTE: While this is not a required part of the Mojo specification, it SHOULD* be provided to * enable future tool support for browsing, etc. and for clarity.* *
parameters	N/A	No	Specifications for the parameters which this Mojo uses will be provided in parameter sub-elements * in this section. * * NOTE: Parameters are discussed in more detail below. *