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 * <libraries>
61 * <library>macro1.vm</library>
62 * <library>macro2.vm</library>
63 * </libraries>
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 * <tools>
80 * <tool>
81 * <toolName>tool_a</toolName>
82 * <toolClass>java.util.Date</toolClass>
83 * </tool>
84 * <tool>
85 * <toolName>tool_b</toolName>
86 * <toolClass>java.lang.String</toolClass>
87 * </tool>
88 * </tools>
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 * <libraries>
168 * <library>macro1.vm</library>
169 * <library>macro2.vm</library>
170 * </libraries>
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 * <tools>
188 * <tool>
189 * <toolName>tool_a</toolName>
190 * <toolClass>java.util.Date</toolClass>
191 * </tool>
192 * <tool>
193 * <toolName>tool_b</toolName>
194 * <toolClass>java.lang.String</toolClass>
195 * </tool>
196 * </tools>
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 }