1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2026 the original author or authors.
4 //
5 // This library is free software; you can redistribute it and/or
6 // modify it under the terms of the GNU Lesser General Public
7 // License as published by the Free Software Foundation; either
8 // version 2.1 of the License, or (at your option) any later version.
9 //
10 // This library is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 // Lesser General Public License for more details.
14 //
15 // You should have received a copy of the GNU Lesser General Public
16 // License along with this library; if not, write to the Free Software
17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 ///////////////////////////////////////////////////////////////////////////////////////////////
19
20 package com.puppycrawl.tools.checkstyle.site;
21
22 import java.util.Collection;
23 import java.util.List;
24
25 /**
26 * Immutable data object holding all pre-computed details for a single module property.
27 * Built by {@link SiteUtil#buildPropertyDetails}; consumed by {@link PropertiesMacro}
28 * purely for formatting. No internal Checkstyle AST or Javadoc tree types appear here.
29 */
30 public final class PropertyDetails {
31
32 /**
33 * Describes how the type cell and default-value cell should be rendered
34 * for token-related properties.
35 */
36 public enum TokenPropertyType {
37 /** Normal property — renders a plain link to property_types.xml. */
38 STANDARD,
39 /**
40 * {@code tokens} property that accepts every token —
41 * renders "set of any supported tokens" with a link.
42 */
43 TOKEN_SET,
44 /** {@code tokens} property with a configurable subset of TokenTypes. */
45 TOKEN_SUBSET,
46 /** {@code javadocTokens} property with a configurable subset of JavadocTokenTypes. */
47 JAVADOC_TOKEN_SUBSET,
48 }
49
50 /** The property name. */
51 private final String name;
52
53 /**
54 * The human-readable description, already rendered as xdoc-safe HTML.
55 * Produced by {@code SiteUtil.getPropertyDescriptionForXdoc}.
56 */
57 private final String description;
58
59 /**
60 * The resolved type string, e.g. {@code "boolean"}, {@code "int"},
61 * {@code "subset of tokens TokenTypes"}.
62 * Meaningful only when {@link #tokenPropertyType} is {@link TokenPropertyType#STANDARD}.
63 */
64 private final String type;
65
66 /**
67 * Determines how the type cell is rendered by {@link PropertiesMacro}.
68 * Defaults to {@link TokenPropertyType#STANDARD}.
69 */
70 private final TokenPropertyType tokenPropertyType;
71
72 /**
73 * The list of configurable token names used when
74 * {@link #tokenPropertyType} is {@link TokenPropertyType#TOKEN_SUBSET}
75 * or {@link TokenPropertyType#JAVADOC_TOKEN_SUBSET}.
76 * Empty otherwise.
77 */
78 private final List<String> configurableTokens;
79
80 /**
81 * The pre-resolved default value string, e.g. {@code "{}"}, {@code "true"},
82 * {@code "all files"}, {@code "TokenTypes"}.
83 * When the default value cell must render individual token links,
84 * {@link #defaultValueTokens} is used instead and this field is empty.
85 */
86 private final String defaultValue;
87
88 /**
89 * Pre-resolved list of token names used when the default-value cell must
90 * render each token as an individual link.
91 * Empty when {@link #defaultValue} should be rendered verbatim.
92 */
93 private final List<String> defaultValueTokens;
94
95 /** The "since" version string, e.g. {@code "8.3"}. */
96 private final String sinceVersion;
97
98 /**
99 * Creates a new {@code PropertyDetails} from the given builder.
100 *
101 * @param builder the builder to copy field values from.
102 */
103 private PropertyDetails(Builder builder) {
104 name = builder.buildName;
105 description = builder.buildDescription;
106 type = builder.buildType;
107 tokenPropertyType = builder.buildTokenPropertyType;
108 configurableTokens = List.copyOf(builder.buildConfigurableTokens);
109 defaultValue = builder.buildDefaultValue;
110 defaultValueTokens = List.copyOf(builder.buildDefaultValueTokens);
111 sinceVersion = builder.buildSinceVersion;
112 }
113
114 /**
115 * Returns the property name.
116 *
117 * @return the property name.
118 */
119 public String getName() {
120 return name;
121 }
122
123 /**
124 * Returns the xdoc-safe HTML description.
125 *
126 * @return the description.
127 */
128 public String getDescription() {
129 return description;
130 }
131
132 /**
133 * Returns the resolved type string. Meaningful only when
134 * {@link #getTokenPropertyType()} is {@link TokenPropertyType#STANDARD}.
135 *
136 * @return the type string, or {@code null} for token properties.
137 */
138 public String getType() {
139 return type;
140 }
141
142 /**
143 * Returns the rendering strategy for the type and default-value cells.
144 *
145 * @return the token property type.
146 */
147 public TokenPropertyType getTokenPropertyType() {
148 return tokenPropertyType;
149 }
150
151 /**
152 * Returns the list of configurable token names. Non-empty only when
153 * {@link #getTokenPropertyType()} is {@link TokenPropertyType#TOKEN_SUBSET}
154 * or {@link TokenPropertyType#JAVADOC_TOKEN_SUBSET}.
155 *
156 * @return an unmodifiable list of token names.
157 */
158 public List<String> getConfigurableTokens() {
159 return configurableTokens;
160 }
161
162 /**
163 * Returns the pre-resolved default value string. Empty when
164 * {@link #getDefaultValueTokens()} should be used instead.
165 *
166 * @return the default value string.
167 */
168 public String getDefaultValue() {
169 return defaultValue;
170 }
171
172 /**
173 * Returns the list of token names to render as individual links in the
174 * default-value cell. Empty when {@link #getDefaultValue()} should be used instead.
175 *
176 * @return an unmodifiable list of token names.
177 */
178 public List<String> getDefaultValueTokens() {
179 return defaultValueTokens;
180 }
181
182 /**
183 * Returns the "since" version string.
184 *
185 * @return the since version.
186 */
187 public String getSinceVersion() {
188 return sinceVersion;
189 }
190
191 /**
192 * Builder for {@link PropertyDetails}.
193 */
194 public static final class Builder {
195
196 /** The property name. */
197 private String buildName;
198
199 /** The xdoc-safe HTML description. */
200 private String buildDescription;
201
202 /** The resolved type string. */
203 private String buildType;
204
205 /** The token property type; defaults to STANDARD. */
206 private TokenPropertyType buildTokenPropertyType = TokenPropertyType.STANDARD;
207
208 /** The configurable token names. */
209 private List<String> buildConfigurableTokens = List.of();
210
211 /** The default value string. */
212 private String buildDefaultValue = "";
213
214 /** The default value token names. */
215 private List<String> buildDefaultValueTokens = List.of();
216
217 /** The since version string. */
218 private String buildSinceVersion = "";
219
220 /**
221 * Sets the property name.
222 *
223 * @param val the property name.
224 * @return this builder.
225 */
226 public Builder name(String val) {
227 buildName = val;
228 return this;
229 }
230
231 /**
232 * Sets the xdoc-safe HTML description.
233 *
234 * @param val the description.
235 * @return this builder.
236 */
237 public Builder description(String val) {
238 buildDescription = val;
239 return this;
240 }
241
242 /**
243 * Sets the resolved type string.
244 *
245 * @param val the type string.
246 * @return this builder.
247 */
248 public Builder type(String val) {
249 buildType = val;
250 return this;
251 }
252
253 /**
254 * Sets the token property type.
255 *
256 * @param val the token property type.
257 * @return this builder.
258 */
259 public Builder tokenPropertyType(TokenPropertyType val) {
260 buildTokenPropertyType = val;
261 return this;
262 }
263
264 /**
265 * Sets the configurable token names.
266 *
267 * @param val the list of token names.
268 * @return this builder.
269 */
270 public Builder configurableTokens(Collection<String> val) {
271 buildConfigurableTokens = List.copyOf(val);
272 return this;
273 }
274
275 /**
276 * Sets the default value string.
277 *
278 * @param val the default value string.
279 * @return this builder.
280 */
281 public Builder defaultValue(String val) {
282 buildDefaultValue = val;
283 return this;
284 }
285
286 /**
287 * Sets the default value token names.
288 *
289 * @param val the list of token names.
290 * @return this builder.
291 */
292 public Builder defaultValueTokens(Collection<String> val) {
293 buildDefaultValueTokens = List.copyOf(val);
294 return this;
295 }
296
297 /**
298 * Sets the since version string.
299 *
300 * @param val the since version.
301 * @return this builder.
302 */
303 public Builder sinceVersion(String val) {
304 buildSinceVersion = val;
305 return this;
306 }
307
308 /**
309 * Builds and returns the {@link PropertyDetails}.
310 *
311 * @return a new {@link PropertyDetails} instance.
312 */
313 public PropertyDetails build() {
314 return new PropertyDetails(this);
315 }
316 }
317 }