1 /*
2 * Copyright 2012-2025 Christophe Friederich
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.devacfr.maven.skins.reflow;
17
18 import java.text.ParseException;
19 import java.util.Date;
20 import java.util.Optional;
21 import javax.annotation.Nonnull;
22 import javax.annotation.Nullable;
23 import org.apache.maven.doxia.site.SiteModel;
24 import org.apache.maven.project.MavenProject;
25 import org.codehaus.plexus.util.xml.Xpp3Dom;
26 import org.devacfr.maven.skins.reflow.context.Context;
27
28 /**
29 * Interface of skin config.
30 *
31 * @author devacfr
32 * @since 2.1
33 */
34 public interface ISkinConfig {
35
36 /**
37 * Renders the snippets found in the body content.
38 *
39 * @param bodyContent
40 * the body content.
41 * @return Returns the {@link String} representing the transformed body content.
42 * @throws Exception
43 * if any.
44 */
45 @Nonnull
46 String renderSnippets(final String bodyContent) throws Exception;
47
48 String renderSnippet(final String snippet) throws Exception;
49
50 /**
51 * A convenience method to check if the value of the {@code property} is {@code "false"}. Useful for properties that
52 * are enabled by default - checks if the property is set to {@code "false"} explicitly.
53 *
54 * @param property
55 * the property of interest
56 * @return {@code true} if the configuration value is set either in page or globally, and is equal to {@code "false"}.
57 * Note that this will return {@code false} if property is not set at all.
58 * @see #get(String)
59 * @since 1.0
60 */
61 boolean not(String property);
62
63 /**
64 * Gets the associated value to {@code key} stored in Velocity context.
65 *
66 * @param key
67 * the key name of associated value in Velocity context.
68 * @param type
69 * the the type of expected value.
70 * @return Returns the associated value to {@code key} stored in Velocity context.
71 * @param <T>
72 * the type of expected value.
73 * @since 2.1
74 */
75 <T> T getContextValue(@Nonnull String key, @Nonnull Class<T> type);
76
77 /**
78 * Sets the value in Velocity context associated to {@code key}.
79 *
80 * @param key
81 * the key name of associated value in Velocity context.
82 * @param value
83 * the new value
84 * @since 2.1
85 */
86 void setContextValue(@Nonnull String key, Object value);
87
88 /**
89 * @return the velocity Context
90 */
91 org.apache.velocity.context.Context getVelocityContext();
92
93 /**
94 * Gets the associated tool to {@code name} stored in toolbox of Velocity context.
95 *
96 * @param toolName
97 * the name of tool associated in Velocity context.
98 * @param toolType
99 * the expected class of tool.
100 * @return Returns the associated tool to {@code name} stored in toolbox of Velocity context.
101 * @param <T>
102 * the type of expected tool.
103 * @since 2.1
104 */
105 @Nullable <T> T getToolbox(@Nonnull String toolName, @Nonnull Class<T> toolType);
106
107 /**
108 * Gets the short title of the site.
109 *
110 * @return Returns the short title of the site.
111 * @since 2.4
112 */
113 @Nonnull
114 String getShortTitle();
115
116 /**
117 * Gets the title of the site.
118 *
119 * @return Returns the title of the site.
120 * @since 2.4
121 */
122 @Nonnull
123 String getTitle();
124
125 /**
126 * Gets the version of the site.
127 *
128 * @return Returns the version of the site.
129 * @since 2.4
130 */
131 @Nonnull
132 String getVersion();
133
134 /**
135 * Gets the position of the version in the site.
136 *
137 * @return Returns the position of the version in the site.
138 * @since 2.4
139 */
140 @Nonnull
141 String getVersionPosition();
142
143 /**
144 * Gets the version message of the site.
145 *
146 * @return Returns the version message of the site.
147 * @since 2.4
148 */
149 @Nonnull
150 String getVersionMessage();
151
152 /**
153 * Gets the publish date of the site.
154 *
155 * @return Returns the publish date of the site.
156 * @since 2.4
157 */
158 @Nullable String getPublishDate();
159
160 /**
161 * Gets the publish date message of the site.
162 *
163 * @return Returns the publish date message of the site.
164 * @since 2.4
165 */
166 @Nonnull
167 String getPublishDateMessage();
168
169 /**
170 * Gets the date position of the site.
171 *
172 * @return Returns the date position of the site.
173 * @since 2.4
174 */
175 @Nonnull
176 String getDatePosition();
177
178 /**
179 * @return Returns the {@link HtmlTool}.
180 * @since 2.0
181 */
182 @Nonnull
183 HtmlTool getHtmlTool();
184
185 /**
186 * @return Returns the body content.
187 * @since 2.0
188 */
189 @Nonnull
190 String getBodyContent();
191
192 /**
193 * @return Returns the root level {@link Xpp3Dom}.
194 */
195 @Nonnull
196 Xpp3Dom getGlobalProperties();
197
198 /**
199 * @return Returns the page level {@link Xpp3Dom}.
200 */
201 @Nonnull
202 Xpp3Dom getPageProperties();
203
204 /**
205 * @return Returns a {@link String} representing the namespace.
206 */
207 @Nonnull
208 String getNamespace();
209
210 /**
211 * @return Returns the {@link String} representing the fileId.
212 */
213 @Nullable String getFileId();
214
215 /**
216 * @return the context
217 */
218 @Nonnull
219 <T extends Context<Context<?>>> T getContext();
220
221 /**
222 * @return Returns the {@link String} representing the projectId.
223 */
224 @Nullable Object getProjectId();
225
226 /**
227 * @return the project
228 */
229 @Nullable MavenProject getProject();
230
231 /**
232 * @return the SiteModel
233 */
234 @Nullable SiteModel getSiteModel();
235
236 /**
237 * Default accessor for config properties. Instead of using {@code $config.get("myproperty")}, one can utilise
238 * Velocity fallback onto the default getter and use {@code $config.myproperty}.
239 *
240 * @param property
241 * the property of interest
242 * @return configuration node if found in the following sequence:
243 * <ol>
244 * <li>In page configuration</li>
245 * <li>In global configuration</li>
246 * <li>{@code null} otherwise</li>
247 * </ol>
248 * @since 1.0
249 */
250 @Nullable Xpp3Dom get(@Nonnull String property);
251
252 /**
253 * Gets the text value of the given {@code property}.
254 *
255 * @param property
256 * the property to use
257 * @param targetType
258 * the returned target type use to convert value.
259 * @param defaultValue
260 * the default value used if property doesn't exist.
261 * @return Returns a converted value of the given {@code property}.
262 * @since 2.0
263 * @param <T>
264 * the type of returned object.
265 */
266 @Nullable <T> T getPropertyValue(@Nonnull String property, @Nonnull Class<T> targetType, @Nullable T defaultValue);
267
268 /**
269 * Gets the text value of the given {@code property}.
270 *
271 * @param property
272 * the property to use
273 * @param targetType
274 * the returned target type use to convert value.
275 * @return Returns a converted value of the given {@code property}.
276 * @since 2.0
277 * @param <T>
278 * the type of returned object.
279 */
280 @Nonnull
281 <T> Optional<T> getPropertyValue(@Nonnull String property, @Nonnull Class<T> targetType);
282
283 /**
284 * Gets the attribute value of the given {@code attribute} of {@code property}.
285 *
286 * @param property
287 * the property to use
288 * @param attribute
289 * the attribute to use.
290 * @param targetType
291 * the returned target type use to convert value.
292 * @param defaultValue
293 * the default value used if property doesn't exist.
294 * @return Returns a converted value of the given {@code property}.
295 * @since 2.0
296 * @param <T>
297 * the type of returned object.
298 */
299 @Nullable <T> T getAttributeValue(@Nonnull String property,
300 @Nonnull String attribute,
301 @Nonnull Class<T> targetType,
302 @Nullable T defaultValue);
303
304 /**
305 * Gets the attribute value of the given {@code attribute} of {@code property}.
306 *
307 * @param property
308 * the property to use
309 * @param attribute
310 * the attribute to use.
311 * @param targetType
312 * the returned target type use to convert value.
313 * @return Returns a converted value of the given {@code property}.
314 * @since 2.0
315 * @param <T>
316 * the type of returned object.
317 */
318 @Nonnull
319 <T> Optional<T> getAttributeValue(@Nonnull String property, @Nonnull String attribute, @Nonnull Class<T> targetType);
320
321 /**
322 * Get the value contained in specific attribute of {@code element} parameter.
323 *
324 * @param element
325 * the xml element.
326 * @param attribute
327 * the attribute name.
328 * @param targetType
329 * the class of converted returned value.
330 * @param defaultValue
331 * the value to return if attribute is empty or {@code null}.
332 * @return Returns the converted value of specific attribute of {@code element} parameter if exists, otherwise returns
333 * the default value.
334 * @param <T>
335 * the type of returned value.
336 */
337 @Nullable <T> T getAttributeValue(@Nonnull Xpp3Dom element,
338 @Nonnull String attribute,
339 @Nonnull Class<T> targetType,
340 T defaultValue);
341
342 /**
343 * Get the value contained in specific attribute of {@code element} parameter.
344 *
345 * @param element
346 * the xml element.
347 * @param attribute
348 * the attribute name.
349 * @param targetType
350 * the class of converted returned value.
351 * @return Returns the converted value of specific attribute of {@code element} parameter if exists, otherwise returns
352 * an empty {@link Optional}.
353 * @param <T>
354 * the type of returned value.
355 */
356 @Nonnull
357 <T> Optional<T> getAttributeValue(@Nonnull Xpp3Dom element, @Nonnull String attribute, @Nonnull Class<T> targetType);
358
359 /**
360 * @param href
361 * link to relative.
362 * @return Returns Relativizes the link.
363 */
364 @Nullable String relativeLink(String href);
365
366 /**
367 * Gets the indicating if the link is active.
368 *
369 * @param href
370 * the link to check.
371 * @return Returns {@code true} the link is active, otherwise {@code false}.
372 */
373 boolean isActiveLink(@Nullable String href);
374
375 /**
376 * @param url
377 * a url.
378 * @return Returns {@code true} whether the link is a external link to the site.
379 */
380 boolean isExternalLink(final String url);
381
382 /**
383 * Evaluate a velocity expression in the current context.
384 *
385 * @param vtl
386 * The velocity expression to evaluate
387 * @param requiredClass
388 * the class of returned value.
389 * @return Returns the value returned by the evaluated velocity expression.
390 * @param <T>
391 * Tthe type of expected returned value.
392 */
393 @Nullable <T> T eval(@Nullable String vtl, @Nonnull Class<T> requiredClass);
394
395 /**
396 * @return Returns a {@link String} representing the relative path to root site.
397 */
398 @Nonnull
399 public String getResourcePath();
400
401 /**
402 * @return Returns the build output timestamp.
403 * @throws ParseException
404 * if the build timestamp can not be parsed.
405 */
406 @Nullable Date getBuildOutputTimestamp() throws ParseException;
407 }