1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.devacfr.maven.skins.reflow;
20
21 import javax.annotation.Nonnull;
22 import javax.annotation.Nullable;
23
24 import org.apache.maven.doxia.site.SiteModel;
25 import org.apache.maven.project.MavenProject;
26 import org.codehaus.plexus.util.xml.Xpp3Dom;
27 import org.devacfr.maven.skins.reflow.context.Context;
28
29 /**
30 * Interface of skin config.
31 *
32 * @author devacfr
33 * @since 2.1
34 */
35 public interface ISkinConfig {
36
37 /**
38 * A convenience method to check if the value of the {@code property} is {@code "false"}. Useful for properties that
39 * are enabled by default - checks if the property is set to {@code "false"} explicitly.
40 *
41 * @param property
42 * the property of interest
43 * @return {@code true} if the configuration value is set either in page or globally, and is equal to
44 * {@code "false"}. Note that this will return {@code false} if property is not set at all.
45 * @see #get(String)
46 * @since 1.0
47 */
48 boolean not(String property);
49
50 /**
51 * Gets the associated value to {@code key} stored in Velocity context.
52 *
53 * @param key
54 * the key name of associated value in Velocity context.
55 * @param type
56 * the the type of expected value.
57 * @return Returns the associated value to {@code key} stored in Velocity context.
58 * @param <T>
59 * the type of expected value.
60 * @since 2.1
61 */
62 <T> T getContextValue(@Nonnull String key, @Nonnull Class<T> type);
63
64 /**
65 * Sets the value in Velocity context associated to {@code key}.
66 *
67 * @param key
68 * the key name of associated value in Velocity context.
69 * @param value
70 * the new value
71 * @since 2.1
72 */
73 void setContextValue(@Nonnull String key, Object value);
74
75 /**
76 * Gets the associated tool to {@code name} stored in toolbox of Velocity context.
77 *
78 * @param toolName
79 * the name of tool associated in Velocity context.
80 * @param toolType
81 * the expected class of tool.
82 * @return Returns the associated tool to {@code name} stored in toolbox of Velocity context.
83 * @param <T>
84 * the type of expected tool.
85 * @since 2.1
86 */
87 @Nullable <T> T getToolbox(@Nonnull String toolName, @Nonnull Class<T> toolType);
88
89 /**
90 * @return Returns the root level {@link Xpp3Dom}.
91 */
92 @Nonnull
93 Xpp3Dom getGlobalProperties();
94
95 /**
96 * @return Returns the page level {@link Xpp3Dom}.
97 */
98 @Nonnull
99 Xpp3Dom getPageProperties();
100
101 /**
102 * @return Returns a {@link String} representing the namespace.
103 */
104 @Nonnull
105 String getNamespace();
106
107 /**
108 * @return Returns the {@link String} representing the fileId.
109 */
110 @Nullable String getFileId();
111
112 /**
113 * @return the context
114 */
115 @Nonnull
116 Context<?> getContext();
117
118 /**
119 * @return Returns the {@link String} representing the projectId.
120 */
121 @Nullable Object getProjectId();
122
123 /**
124 * @return the project
125 */
126 @Nonnull
127 MavenProject getProject();
128
129 /**
130 * @return the SiteModel
131 */
132 @Nonnull
133 SiteModel getSiteModel();
134
135 /**
136 * Default accessor for config properties. Instead of using {@code $config.get("myproperty")}, one can utilise
137 * Velocity fallback onto the default getter and use {@code $config.myproperty}.
138 *
139 * @param property
140 * the property of interest
141 * @return configuration node if found in the following sequence:
142 * <ol>
143 * <li>In page configuration</li>
144 * <li>In global configuration</li>
145 * <li>{@code null} otherwise</li>
146 * </ol>
147 * @since 1.0
148 */
149 @Nullable Xpp3Dom get(@Nonnull String property);
150
151 /**
152 * Gets the text value of the given {@code property}.
153 *
154 * @param property
155 * the property to use
156 * @param targetType
157 * the returned target type use to convert value.
158 * @param defaultValue
159 * the default value used if property doesn't exist.
160 * @return Returns a converted value of the given {@code property}.
161 * @since 2.0
162 * @param <T>
163 * the type of returned object.
164 */
165 @Nullable <T> T getPropertyValue(@Nonnull String property, @Nonnull Class<T> targetType, @Nullable T defaultValue);
166
167 /**
168 * Gets the attribute value of the given {@code attribute} of {@code property}.
169 *
170 * @param property
171 * the property to use
172 * @param attribute
173 * the attribute to use.
174 * @param targetType
175 * the returned target type use to convert value.
176 * @param defaultValue
177 * the default value used if property doesn't exist.
178 * @return Returns a converted value of the given {@code property}.
179 * @since 2.0
180 * @param <T>
181 * the type of returned object.
182 */
183 @Nullable <T> T getAttributeValue(@Nonnull String property,
184 @Nonnull String attribute,
185 @Nonnull Class<T> targetType,
186 @Nullable T defaultValue);
187
188 /**
189 * Get the value contained in specific attribute of {@code element} parameter.
190 *
191 * @param element
192 * the xml element.
193 * @param attribute
194 * the attribute name.
195 * @param targetType
196 * the class of converted returned value.
197 * @param defaultValue
198 * the value to return if attribute is empty or {@code null}.
199 * @return Returns the converted value of specific attribute of {@code element} parameter if exists, otherwise
200 * returns the default value.
201 * @param <T>
202 * the type of returned value.
203 */
204 @Nullable <T> T getAttributeValue(@Nonnull Xpp3Dom element,
205 @Nonnull String attribute,
206 @Nonnull Class<T> targetType,
207 T defaultValue);
208
209 /**
210 * @param href
211 * link to relative.
212 * @return Returns Relativizes the link.
213 */
214 @Nullable String relativeLink(String href);
215
216 /**
217 * Gets the indicating if the link is active.
218 *
219 * @param href
220 * the link to check.
221 * @return Returns {@code true} the link is active, otherwise {@code false}.
222 */
223 boolean isActiveLink(@Nullable String href);
224
225 /**
226 * Evaluate a velocity expression in the current context.
227 *
228 * @param vtl
229 * The velocity expression to evaluate
230 * @param requiredClass
231 * the class of returned value.
232 * @return Returns the value returned by the evaluated velocity expression.
233 * @param <T>
234 * Tthe type of expected returned value.
235 */
236 @Nullable <T> T eval(@Nullable String vtl, @Nonnull Class<T> requiredClass);
237
238 /**
239 * @return Returns a {@link String} representing the relative path to root site.
240 */
241 @Nonnull
242 public String getResourcePath();
243 }