View Javadoc

1   package org.apache.maven.plugin;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.util.Map;
23  
24  import org.apache.maven.plugin.logging.Log;
25  import org.apache.maven.plugin.logging.SystemStreamLog;
26  
27  /**
28   * Abstract class to provide most of the infrastructure required to implement a <code>Mojo</code> except for
29   * the execute method.
30   * <br/>
31   * The implementation should have a <code>goal</code> annotation in the class-level javadoc annotation:
32   * <pre>
33   * &#47;&#42;&#42;
34   *  &#42; &#64;goal goalName
35   *  &#42;&#47;
36   * </pre>
37   *
38   * There are also a number of class-level javadoc annotations which can be used to control how and when the
39   * <code>Mojo</code> is executed:
40   * <br/>
41   * <br/>
42   *
43   * <table border="1">
44   *  <tr bgcolor="#CCCCCC">
45   *      <th>Descriptor Element</th>
46   *      <th>Annotation</th>
47   *      <th>Required?</th>
48   *      <th>Notes</th>
49   *  </tr>
50   *  <tr>
51   *      <td>goal</td>
52   *      <td>@goal &lt;goalName&gt;</td>
53   *      <td>Yes</td>
54   *      <td>The name for the Mojo that users will reference from the command line to execute the Mojo directly,
55   *      or inside a POM in order to provide Mojo-specific configuration.</td>
56   *  </tr>
57   *  <tr>
58   *      <td>implementation</td>
59   *      <td>none (detected)</td>
60   *      <td>Yes</td>
61   *      <td>The Mojo's fully-qualified class name (or script path in the case of non-Java Mojos).</td>
62   *  </tr>
63   *  <tr>
64   *      <td>language</td>
65   *      <td>none (detected)</td>
66   *      <td>No. Default: <code>java</code></td>
67   *      <td>The implementation language for this Mojo (Java, beanshell, etc.).</td>
68   *  </tr>
69   *  <tr>
70   *      <td>configurator</td>
71   *      <td>@configurator &lt;roleHint&gt;</td>
72   *      <td>No</td>
73   *      <td>The configurator type to use when injecting parameter values into this Mojo. The value is normally
74   *          deduced from the Mojo's implementation language, but can be specified to allow a custom
75   *          ComponentConfigurator implementation to be used.
76   *          <br/>
77   *          <i>NOTE: This will only be used in very special cases, using a highly controlled vocabulary of possible
78   *          values. (Elements like this are why it's a good idea to use the descriptor tools.)</i>
79   *      </td>
80   *   </tr>
81   *   <tr>
82   *      <td>phase</td>
83   *      <td>@phase &lt;phaseName&gt;</td>
84   *      <td>No</td>
85   *      <td>Binds this Mojo to a particular phase of the standard build lifecycle, if specified.
86   *          <br/>
87   *          <i>NOTE: This is only required if this Mojo is to participate in the standard build process.</i>
88   *      </td>
89   *   </tr>
90   *   <tr>
91   *      <td>execute</td>
92   *      <td>@execute [phase=&lt;phaseName&gt;|goal=&lt;goalName&gt;] [lifecycle=&lt;lifecycleId&gt;]</td>
93   *      <td>No</td>
94   *      <td>When this goal is invoked, it will first invoke a parallel lifecycle, ending at the given phase.
95   *          If a goal is provided instead of a phase, that goal will be executed in isolation.
96   *          The execution of either will not affect the current project, but instead make available the
97   *          <code>${executedProject}</code> expression if required. An alternate lifecycle can also be provided:
98   *          for more information see the documentation on the
99   *          <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  */
144 public 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 }