View Javadoc

1   package org.apache.velocity.site.doxia.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.io.File;
23  import java.util.List;
24  
25  import org.apache.maven.artifact.repository.ArtifactRepository;
26  import org.apache.maven.plugin.AbstractMojo;
27  import org.apache.maven.plugin.MojoExecutionException;
28  import org.apache.maven.project.MavenProject;
29  import org.apache.velocity.site.doxia.runner.VelocityRunner;
30  import org.apache.velocity.site.doxia.util.VelocityDoxiaRendererException;
31  import org.apache.velocity.site.doxia.util.VelocityTool;
32  import org.apache.velocity.site.doxia.velocity.DoxiaLibraryLoader;
33  import org.apache.velocity.site.doxia.velocity.DoxiaVelocityContextFactory;
34  
35  /**
36   * <p>
37   * This plugin initialized and configures the Velocity engine used to pre-render
38   * templates for the Doxia site. It is tied to the site lifecycle in the
39   * pre-site phase, so it will have run before the site-plugin itself triggers
40   * the Doxia rendering.
41   * </p>
42   *
43   * <p>
44   * Due to the fact that Maven changed its internal container hierarchy starting
45   * with 2.0.5, it is no longer trivially possible to inject information into
46   * anything that runs in a different plugin. This makes it necessary to run all
47   * Velocity related code inside this plugin, else you will end up with
48   * references pulled in from the plexus-velocity component which uses an older
49   * version of Velocity.
50   *
51   * <p>
52   * This plugin can be configured through the POM:
53   * </p>
54   *
55   * <p>
56   * Configuration from the POM about the libraries to use.
57   * </p>
58   *
59   * <pre>
60   *    &lt;libraries&gt;
61   *      &lt;library&gt;macro1.vm&lt;/library&gt;
62   *      &lt;library&gt;macro2.vm&lt;/library&gt;
63   *    &lt;/libraries&gt;
64   * </pre>
65   *
66   * <p>
67   * Can contain multiple libraries. All must exist and are loaded from
68   * <code>${siteDirectory}/velocity/resources</code>.
69   * </p>
70   *
71   * <p>
72   * Configuration from the POM about the Tools to use. Velocity Tools are
73   * instances of Java objects that are available through the Velocity context.
74   * All Tools are instantiated only once and the put in the context. So don't
75   * change the inner state of the Tools!
76   * </p>
77   *
78   * <pre>
79   *    &lt;tools&gt;
80   *      &lt;tool&gt;
81   *        &lt;toolName&gt;tool_a&lt;/toolName&gt;
82   *        &lt;toolClass&gt;java.util.Date&lt;/toolClass&gt;
83   *      &lt;/tool&gt;
84   *      &lt;tool&gt;
85   *        &lt;toolName&gt;tool_b&lt;/toolName&gt;
86   *        &lt;toolClass&gt;java.lang.String&lt;/toolClass&gt;
87   *      &lt;/tool&gt;
88   *    &lt;/tools&gt;
89   * </pre>
90   *
91   * This adds a {@link java.util.Date} and a {@link String} object to the
92   * context. These are accessible as ${tool_a} and ${tool_b} from Velocity
93   * templates.
94   *
95   * @author <a href="mailto:henning@apache.org">Henning P. Schmiedehausen</a>
96   * @version $Revision: 526751 $
97   *
98   * @goal pre-site
99   * @phase pre-site
100  * @requiresDependencyResolution test
101  */
102 public class DoxiaVelocityRendererPlugin extends AbstractMojo
103 {
104     /** Lookup Key for Plexus Container */
105     public static final String CONTAINER_LOOKUP_NAME = "org.apache.velocity.site:velocity-site-doxia-renderer";
106 
107     /**
108      * Directory containing the site files. Will be used to load the Velocity
109      * Macro files through the {@link DoxiaLibraryLoader}.
110      *
111      * @parameter expression="${basedir}/src/site"
112      * @required
113      */
114     private File siteDirectory;
115 
116     /**
117      * The maven project descriptor.
118      *
119      * @parameter expression="${project}"
120      * @required
121      * @readonly
122      */
123     private MavenProject project;
124 
125     /**
126      * The local repository descriptor.
127      *
128      * @parameter expression="${localRepository}"
129      */
130     private ArtifactRepository localRepository;
131 
132     /**
133      * The List of reactor project descriptors.
134      *
135      * @parameter expression="${reactorProjects}"
136      * @required
137      * @readonly
138      */
139     private List reactorProjects;
140 
141     /**
142      * Specifies the input encoding for the templates.
143      *
144      * <p>
145      * TODO: Is that really useful?
146      * </p>
147      *
148      * @parameter expression="${inputEncoding}" default-value="ISO-8859-1"
149      */
150     private String inputEncoding;
151 
152     /**
153      * Specifies the output encoding for the templates.
154      *
155      * <p>
156      * TODO: Is that really useful?
157      * </p>
158      *
159      * @parameter expression="${outputEncoding}" default-value="ISO-8859-1"
160      */
161     private String outputEncoding;
162 
163     /**
164      * Configuration from the POM about the libraries to use.
165      *
166      * <pre>
167      *    &lt;libraries&gt;
168      *      &lt;library&gt;macro1.vm&lt;/library&gt;
169      *      &lt;library&gt;macro2.vm&lt;/library&gt;
170      *    &lt;/libraries&gt;
171      * </pre>
172      *
173      * Can contain multiple libraries. All must exist and are loaded from
174      * <code>${siteDirectory}/velocity/resources</code>.
175      *
176      * @parameter expression="${libraries}"
177      */
178     private String[] libraries;
179 
180     /**
181      * Configuration from the POM about the Tools to use. Velocity Tools are
182      * instances of Java objects that are available through the Velocity
183      * context. All Tools are instantiated only once and the put in the context.
184      * So don't change the inner state of the Tools!
185      *
186      * <pre>
187      *    &lt;tools&gt;
188      *      &lt;tool&gt;
189      *        &lt;toolName&gt;tool_a&lt;/toolName&gt;
190      *        &lt;toolClass&gt;java.util.Date&lt;/toolClass&gt;
191      *      &lt;/tool&gt;
192      *      &lt;tool&gt;
193      *        &lt;toolName&gt;tool_b&lt;/toolName&gt;
194      *        &lt;toolClass&gt;java.lang.String&lt;/toolClass&gt;
195      *      &lt;/tool&gt;
196      *    &lt;/tools&gt;
197      * </pre>
198      *
199      * This adds a {@link java.util.Date} and a {@link String} object to the
200      * context. These are accessible as ${tool_a} and ${tool_b} from Velocity
201      * templates.
202      *
203      * <p>
204      * TODO: Maybe use Velocity Tools.
205      * </p>
206      *
207      * @parameter expression="${tools}"
208      */
209     private VelocityTool[] tools;
210 
211     /**
212      * The Velocity Context Factory. This gets managed by Plexus as a singleton.
213      * However as we are not inside the Mojo API here, we must use the Plexus
214      * requirement annotation, not the Mojo component annotation. Yes, this is
215      * important (and confusing, too).
216      *
217      * @component role="org.apache.velocity.site.doxia.velocity.DoxiaVelocityContextFactory"
218      * @required
219      */
220     private DoxiaVelocityContextFactory doxiaVelocityContextFactory;
221 
222     /**
223      * The Velocity Library Loader. This gets managed by Plexus as a singleton.
224      * However as we are not inside the Mojo API here, we must use the Plexus
225      * requirement annotation, not the Mojo component annotation. Yes, this is
226      * important (and confusing, too).
227      *
228      * @component role="org.apache.velocity.site.doxia.velocity.DoxiaLibraryLoader"
229      * @required
230      */
231     private DoxiaLibraryLoader doxiaLibraryLoader;
232 
233     /**
234      * The Runner object which executes the actual rendering.
235      *
236      * @component role="org.apache.velocity.site.doxia.runner.VelocityRunner"
237      * @required
238      */
239     private VelocityRunner runner;
240 
241     /**
242      * <p>
243      * Plugin Execution. Must be run in the pre-site phase of the site
244      * lifecycle. Copies the injected field parameter into the
245      * {@link DoxiaVelocityContextFactory} and {@link DoxiaLibraryLoader}
246      * singletons so that they are available in the actual Maven extension.
247      * </p>
248      *
249      * <p>
250      * TODO: Find out if that is actually legal and/or the recommended way to
251      * do.
252      * </p>
253      *
254      */
255     public void execute() throws MojoExecutionException
256     {
257         try
258         {
259             doxiaVelocityContextFactory.addContextElement("siteDirectory", siteDirectory);
260             doxiaVelocityContextFactory.addContextElement("project", project);
261             doxiaVelocityContextFactory.addContextElement("localRepository", localRepository);
262             doxiaVelocityContextFactory.addContextElement("reactorProjects", reactorProjects);
263             doxiaVelocityContextFactory.addContextElement("inputEncoding", inputEncoding);
264             doxiaVelocityContextFactory.addContextElement("outputEncoding", outputEncoding);
265             doxiaVelocityContextFactory.setTools(tools);
266 
267             doxiaLibraryLoader.setKnownLibraries(libraries);
268             doxiaLibraryLoader.setSiteDirectory(siteDirectory);
269 
270             runner.initVelocity();
271 
272         }
273         catch (VelocityDoxiaRendererException vdre)
274         {
275             throw new MojoExecutionException("While executing Velocity Render Plugin:", vdre);
276         }
277     }
278 }