001package org.apache.maven.plugin;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.util.Map;
023
024import org.apache.maven.plugin.logging.Log;
025import org.apache.maven.plugin.logging.SystemStreamLog;
026
027/**
028 * Abstract class to provide most of the infrastructure required to implement a <code>Mojo</code> except for
029 * the execute method.
030 * <br/>
031 * The implementation should have a <code>goal</code> annotation in the class-level javadoc annotation:
032 * <pre>
033 * &#47;&#42;&#42;
034 *  &#42; &#64;goal goalName
035 *  &#42;&#47;
036 * </pre>
037 *
038 * There are also a number of class-level javadoc annotations which can be used to control how and when the
039 * <code>Mojo</code> is executed:
040 * <br/>
041 * <br/>
042 *
043 * <table border="1">
044 *  <tr bgcolor="#CCCCCC">
045 *      <th>Descriptor Element</th>
046 *      <th>Annotation</th>
047 *      <th>Required?</th>
048 *      <th>Notes</th>
049 *  </tr>
050 *  <tr>
051 *      <td>goal</td>
052 *      <td>@goal &lt;goalName&gt;</td>
053 *      <td>Yes</td>
054 *      <td>The name for the Mojo that users will reference from the command line to execute the Mojo directly,
055 *      or inside a POM in order to provide Mojo-specific configuration.</td>
056 *  </tr>
057 *  <tr>
058 *      <td>implementation</td>
059 *      <td>none (detected)</td>
060 *      <td>Yes</td>
061 *      <td>The Mojo's fully-qualified class name (or script path in the case of non-Java Mojos).</td>
062 *  </tr>
063 *  <tr>
064 *      <td>language</td>
065 *      <td>none (detected)</td>
066 *      <td>No. Default: <code>java</code></td>
067 *      <td>The implementation language for this Mojo (Java, beanshell, etc.).</td>
068 *  </tr>
069 *  <tr>
070 *      <td>configurator</td>
071 *      <td>@configurator &lt;roleHint&gt;</td>
072 *      <td>No</td>
073 *      <td>The configurator type to use when injecting parameter values into this Mojo. The value is normally
074 *          deduced from the Mojo's implementation language, but can be specified to allow a custom
075 *          ComponentConfigurator implementation to be used.
076 *          <br/>
077 *          <i>NOTE: This will only be used in very special cases, using a highly controlled vocabulary of possible
078 *          values. (Elements like this are why it's a good idea to use the descriptor tools.)</i>
079 *      </td>
080 *   </tr>
081 *   <tr>
082 *      <td>phase</td>
083 *      <td>@phase &lt;phaseName&gt;</td>
084 *      <td>No</td>
085 *      <td>Binds this Mojo to a particular phase of the standard build lifecycle, if specified.
086 *          <br/>
087 *          <i>NOTE: This is only required if this Mojo is to participate in the standard build process.</i>
088 *      </td>
089 *   </tr>
090 *   <tr>
091 *      <td>execute</td>
092 *      <td>@execute [phase=&lt;phaseName&gt;|goal=&lt;goalName&gt;] [lifecycle=&lt;lifecycleId&gt;]</td>
093 *      <td>No</td>
094 *      <td>When this goal is invoked, it will first invoke a parallel lifecycle, ending at the given phase.
095 *          If a goal is provided instead of a phase, that goal will be executed in isolation.
096 *          The execution of either will not affect the current project, but instead make available the
097 *          <code>${executedProject}</code> expression if required. An alternate lifecycle can also be provided:
098 *          for more information see the documentation on the
099 *          <a href="http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html"
100 *             target="_blank">build lifecycle</a>.
101 *      </td>
102 *   </tr>
103 *   <tr>
104 *      <td>requiresDependencyResolution</td>
105 *      <td>@requiresDependencyResolution &lt;requiredScope&gt;</td>
106 *      <td>No</td>
107 *      <td>Flags this Mojo as requiring the dependencies in the specified scope (or an implied scope) to be
108 *          resolved before it can execute.
109 *          <br/>
110 *          <i>NOTE: Currently supports <b>compile</b>, <b>runtime</b>, and <b>test</b> scopes.</i>
111 *      </td>
112 *   </tr>
113 *   <tr>
114 *      <td>description</td>
115 *      <td>none (detected)</td>
116 *      <td>No</td>
117 *      <td>The description of this Mojo's functionality. <i>Using the toolset, this will be the class-level
118 *          Javadoc description provided.
119 *          <br/>
120 *          <i>NOTE: While this is not a required part of the Mojo specification, it <b>SHOULD</b> be provided to
121 *          enable future tool support for browsing, etc. and for clarity.</i>
122 *      </td>
123 *   </tr>
124 *   <tr>
125 *      <td>parameters</td>
126 *      <td>N/A</td>
127 *      <td>No</td>
128 *      <td>Specifications for the parameters which this Mojo uses will be provided in <b>parameter</b> sub-elements
129 *          in this section.
130 *          <br/>
131 *          <i>NOTE: Parameters are discussed in more detail below.</i>
132 *      </td>
133 *   </tr>
134 * </table>
135 *
136 * @see <a href="http://maven.apache.org/guides/plugin/guide-java-plugin-development.html" target="_blank">Guide to Developing Java Plugins</a>
137 * @see <a href="http://maven.apache.org/guides/mini/guide-configuring-plugins.html" target="_blank">Guide to Configuring Plug-ins</a>
138 * @see <a href="http://maven.apache.org/developers/mojo-api-specification.html" target="_blank">Mojo API Specification</a>
139 *
140 * @author <a href="mailto:brett@apache.org">Brett Porter</a>
141 * @author jdcasey
142 * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
143 */
144public abstract class AbstractMojo
145    implements Mojo, ContextEnabled
146{
147    /** Instance logger */
148    private Log log;
149
150    /** Plugin container context */
151    private Map pluginContext;
152
153    /**
154     * @see org.apache.maven.plugin.Mojo#setLog(org.apache.maven.plugin.logging.Log)
155     */
156    public void setLog( Log log )
157    {
158        this.log = log;
159    }
160
161    /**
162     * Returns the logger that has been injected into this mojo. If no logger has been setup yet, a
163     * <code>SystemStreamLog</code> logger will be created and returned.
164     * <br/><br/>
165     * <strong>Note:</strong>
166     * The logger returned by this method must not be cached in an instance field during the construction of the mojo.
167     * This would cause the mojo to use a wrongly configured default logger when being run by Maven. The proper logger
168     * gets injected by the Plexus container <em>after</em> the mojo has been constructed. Therefore, simply call this
169     * method directly whenever you need the logger, it is fast enough and needs no caching.
170     *
171     * @see org.apache.maven.plugin.Mojo#getLog()
172     */
173    public Log getLog()
174    {
175        if ( log == null )
176        {
177            log = new SystemStreamLog();
178        }
179
180        return log;
181    }
182
183    /**
184     * @see org.apache.maven.plugin.ContextEnabled#getPluginContext()
185     */
186    public Map getPluginContext()
187    {
188        return pluginContext;
189    }
190
191    /**
192     * @see org.apache.maven.plugin.ContextEnabled#setPluginContext(java.util.Map)
193     */
194    public void setPluginContext( Map pluginContext )
195    {
196        this.pluginContext = pluginContext;
197    }
198}