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 org.apache.maven.plugin.logging.Log;
23 import org.apache.maven.plugin.logging.SystemStreamLog;
24
25 import java.util.Map;
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 * /**
34 * * @goal goalName
35 * */
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 <goalName></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 <roleHint></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 <phaseName></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=<phaseName>|goal=<goalName>] [lifecycle=<lifecycleId>]</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" target="_blank">build lifecycle</a>.
100 * </td>
101 * </tr>
102 * <tr>
103 * <td>requiresDependencyResolution</td>
104 * <td>@requiresDependencyResolution <requiredScope></td>
105 * <td>No</td>
106 * <td>Flags this Mojo as requiring the dependencies in the specified scope (or an implied scope) to be
107 * resolved before it can execute.
108 * <br/>
109 * <i>NOTE: Currently supports <b>compile</b>, <b>runtime</b>, and <b>test</b> scopes.</i>
110 * </td>
111 * </tr>
112 * <tr>
113 * <td>description</td>
114 * <td>none (detected)</td>
115 * <td>No</td>
116 * <td>The description of this Mojo's functionality. <i>Using the toolset, this will be the class-level
117 * Javadoc description provided.
118 * <br/>
119 * <i>NOTE: While this is not a required part of the Mojo specification, it <b>SHOULD</b> be provided to
120 * enable future tool support for browsing, etc. and for clarity.</i>
121 * </td>
122 * </tr>
123 * <tr>
124 * <td>parameters</td>
125 * <td>N/A</td>
126 * <td>No</td>
127 * <td>Specifications for the parameters which this Mojo uses will be provided in <b>parameter</b> sub-elements
128 * in this section.
129 * <br/>
130 * <i>NOTE: Parameters are discussed in more detail below.</i>
131 * </td>
132 * </tr>
133 * </table>
134 *
135 * @see <a href="http://maven.apache.org/guides/plugin/guide-java-plugin-development.html" target="_blank">Guide to Developing Java Plugins</a>
136 * @see <a href="http://maven.apache.org/guides/mini/guide-configuring-plugins.html" target="_blank">Guide to Configuring Plug-ins</a>
137 * @see <a href="http://maven.apache.org/developers/mojo-api-specification.html" target="_blank">Mojo API Specification</a>
138 *
139 * @author <a href="mailto:brett@apache.org">Brett Porter</a>
140 * @author jdcasey
141 * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
142 * @version $Id: AbstractMojo.java 612012 2008-01-15 04:17:35Z vsiveton $
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 <code>SystemStreamLog</code>
163 * 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 }