View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.maven.plugin;
20  
21  import java.util.Map;
22  
23  import org.apache.maven.plugin.logging.Log;
24  import org.apache.maven.plugin.logging.SystemStreamLog;
25  
26  /**
27   * Abstract class to provide most of the infrastructure required to implement a <code>Mojo</code> except for
28   * the execute method.<br>
29   * The implementation should have a <code>Mojo</code> annotation with the name of the goal:
30   * <pre>
31   *   &#64;Mojo( name = "&lt;goal-name&gt;" )
32   * </pre>
33   * <p>
34   * There are also a number of attributes which can be used to control how and when the
35   * <code>Mojo</code> is executed:
36   * </p>
37   * <table border="1">
38   *  <caption>mojo annotation attributes</caption>
39   *  <tr>
40   *      <th>Descriptor Element</th>
41   *      <th>Annotation</th>
42   *      <th>Required?</th>
43   *      <th>Notes</th>
44   *  </tr>
45   *  <tr>
46   *      <td>goal</td>
47   *      <td>name = "&lt;goal-name&gt;"</td>
48   *      <td>Yes</td>
49   *      <td>The name for the Mojo that users will reference from the command line to execute the Mojo directly,
50   *      or inside a POM in order to provide Mojo-specific configuration.</td>
51   *  </tr>
52   *  <tr>
53   *      <td>implementation</td>
54   *      <td>none (detected)</td>
55   *      <td>Yes</td>
56   *      <td>The Mojo's fully-qualified class name (or script path in the case of non-Java Mojos).</td>
57   *  </tr>
58   *  <tr>
59   *      <td>language</td>
60   *      <td>none (detected)</td>
61   *      <td>No. Default: <code>java</code></td>
62   *      <td>The implementation language for this Mojo (Java, beanshell, etc.).</td>
63   *  </tr>
64   *  <tr>
65   *      <td>configurator</td>
66   *      <td>configurator = "&lt;role-hint&gt;"</td>
67   *      <td>No</td>
68   *      <td>The configurator type to use when injecting parameter values into this Mojo. The value is normally
69   *          deduced from the Mojo's implementation language, but can be specified to allow a custom
70   *          ComponentConfigurator implementation to be used.
71   *          <br>
72   *          <i>NOTE: This will only be used in very special cases, using a highly controlled vocabulary of possible
73   *          values. (Elements like this are why it's a good idea to use the descriptor tools.)</i>
74   *      </td>
75   *   </tr>
76   *   <tr>
77   *      <td>phase</td>
78   *      <td>defaultPhase = LifecyclePhase.&lt;phase&gt;</td>
79   *      <td>No</td>
80   *      <td>Binds this Mojo to a particular phase of the standard build lifecycle, if specified.
81   *          <br>
82   *          <i>NOTE: This is only required if this Mojo is to participate in the standard build process.</i>
83   *      </td>
84   *   </tr>
85   *   <tr>
86   *      <td>execute</td>
87   *      <td>@Execute
88   *       ( phase=LifecyclePhase.&lt;phase&gt;, goal= "&lt;goal-name&gt;", lifecycle="&lt;lifecycle-id&gt;" )</td>
89   *      <td>No</td>
90   *      <td>When this goal is invoked, it will first invoke a parallel lifecycle, ending at the given phase.
91   *          If a goal is provided instead of a phase, that goal will be executed in isolation.
92   *          The execution of either will not affect the current project, but instead make available the
93   *          <code>${executedProject}</code> expression if required. An alternate lifecycle can also be provided:
94   *          for more information see the documentation on the
95   *          <a href="https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html"
96   *             target="_blank">build lifecycle</a>.
97   *      </td>
98   *   </tr>
99   *   <tr>
100  *      <td>requiresDependencyResolution</td>
101  *      <td>requiresDependencyResolution = ResolutionScope.&lt;scope&gt;</td>
102  *      <td>No</td>
103  *      <td>Flags this Mojo as requiring the dependencies in the specified scope (or an implied scope) to be
104  *          resolved before it can execute.
105  *          <br>
106  *          <i>NOTE: Currently supports <b>compile</b>, <b>runtime</b>, and <b>test</b> scopes.</i>
107  *      </td>
108  *   </tr>
109  *   <tr>
110  *      <td>description</td>
111  *      <td>none (detected)</td>
112  *      <td>No</td>
113  *      <td>The description of this Mojo's functionality. Using the toolset, this will be the class-level
114  *          Javadoc description provided.<br>
115  *          <i>NOTE: While this is not a required part of the Mojo specification, it <b>SHOULD</b> be provided to
116  *          enable future tool support for browsing, etc. and for clarity.</i>
117  *      </td>
118  *   </tr>
119  *   <tr>
120  *      <td>parameters</td>
121  *      <td>N/A</td>
122  *      <td>No</td>
123  *      <td>Specifications for the parameters which this Mojo uses will be provided in <b>parameter</b> sub-elements
124  *          in this section.
125  *          <br>
126  *          <i>NOTE: Parameters are discussed in more detail below.</i>
127  *      </td>
128  *   </tr>
129  * </table>
130  * <p>This is only a small set of all the options. A complete list can be found at
131  * <a href="https://maven.apache.org/components/plugin-tools/maven-plugin-tools-annotations/index.html" target="_blank">
132  * Maven Plugin Tool for Annotations</a>.
133  *
134  * @see <a href="https://maven.apache.org/guides/plugin/guide-java-plugin-development.html" target="_blank">Guide to Developing Java Plugins</a>
135  * @see <a href="https://maven.apache.org/guides/mini/guide-configuring-plugins.html" target="_blank">Guide to Configuring Plug-ins</a>
136  * @see <a href="https://maven.apache.org/developers/mojo-api-specification.html" target="_blank">Mojo API Specification</a>
137  *
138  */
139 public abstract class AbstractMojo implements Mojo, ContextEnabled {
140     /** Instance logger */
141     private Log log;
142 
143     /** Plugin container context */
144     private Map pluginContext;
145 
146     /**
147      * @deprecated Use SLF4J directly
148      */
149     @Deprecated
150     @Override
151     public void setLog(Log log) {
152         this.log = log;
153     }
154 
155     /**
156      * <p>
157      * Returns the logger that has been injected into this mojo. If no logger has been setup yet, a
158      * <code>SystemStreamLog</code> logger will be created and returned.
159      * </p>
160      * <strong>Note:</strong>
161      * The logger returned by this method must not be cached in an instance field during the construction of the mojo.
162      * This would cause the mojo to use a wrongly configured default logger when being run by Maven. The proper logger
163      * gets injected by the Plexus container <em>after</em> the mojo has been constructed. Therefore, simply call this
164      * method directly whenever you need the logger, it is fast enough and needs no caching.
165      *
166      * @see org.apache.maven.plugin.Mojo#getLog()
167      * @deprecated Use SLF4J directly
168      */
169     @Deprecated
170     @Override
171     public Log getLog() {
172         if (log == null) {
173             log = new SystemStreamLog();
174         }
175 
176         return log;
177     }
178 
179     @Override
180     public Map getPluginContext() {
181         return pluginContext;
182     }
183 
184     @Override
185     public void setPluginContext(Map pluginContext) {
186         this.pluginContext = pluginContext;
187     }
188 }