001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle; 021 022import java.beans.PropertyDescriptor; 023import java.lang.reflect.InvocationTargetException; 024import java.net.URI; 025import java.util.ArrayList; 026import java.util.Collection; 027import java.util.List; 028import java.util.Locale; 029import java.util.StringTokenizer; 030import java.util.regex.Pattern; 031 032import javax.annotation.Nullable; 033 034import org.apache.commons.beanutils.BeanUtilsBean; 035import org.apache.commons.beanutils.ConversionException; 036import org.apache.commons.beanutils.ConvertUtilsBean; 037import org.apache.commons.beanutils.Converter; 038import org.apache.commons.beanutils.PropertyUtils; 039import org.apache.commons.beanutils.PropertyUtilsBean; 040import org.apache.commons.beanutils.converters.ArrayConverter; 041import org.apache.commons.beanutils.converters.BooleanConverter; 042import org.apache.commons.beanutils.converters.ByteConverter; 043import org.apache.commons.beanutils.converters.CharacterConverter; 044import org.apache.commons.beanutils.converters.DoubleConverter; 045import org.apache.commons.beanutils.converters.FloatConverter; 046import org.apache.commons.beanutils.converters.IntegerConverter; 047import org.apache.commons.beanutils.converters.LongConverter; 048import org.apache.commons.beanutils.converters.ShortConverter; 049 050import com.puppycrawl.tools.checkstyle.api.CheckstyleException; 051import com.puppycrawl.tools.checkstyle.api.Configurable; 052import com.puppycrawl.tools.checkstyle.api.Configuration; 053import com.puppycrawl.tools.checkstyle.api.Context; 054import com.puppycrawl.tools.checkstyle.api.Contextualizable; 055import com.puppycrawl.tools.checkstyle.api.Scope; 056import com.puppycrawl.tools.checkstyle.api.SeverityLevel; 057import com.puppycrawl.tools.checkstyle.checks.naming.AccessModifierOption; 058import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 059 060/** 061 * A Java Bean that implements the component lifecycle interfaces by 062 * calling the bean's setters for all configuration attributes. 063 */ 064public abstract class AbstractAutomaticBean 065 implements Configurable, Contextualizable { 066 067 /** 068 * Enum to specify behaviour regarding ignored modules. 069 */ 070 public enum OutputStreamOptions { 071 072 /** 073 * Close stream in the end. 074 */ 075 CLOSE, 076 077 /** 078 * Do nothing in the end. 079 */ 080 NONE, 081 082 } 083 084 /** Comma separator for StringTokenizer. */ 085 private static final String COMMA_SEPARATOR = ","; 086 087 /** The configuration of this bean. */ 088 private Configuration configuration; 089 090 /** 091 * Provides a hook to finish the part of this component's setup that 092 * was not handled by the bean introspection. 093 * <p> 094 * The default implementation does nothing. 095 * </p> 096 * 097 * @throws CheckstyleException if there is a configuration error. 098 */ 099 protected abstract void finishLocalSetup() throws CheckstyleException; 100 101 /** 102 * Creates a BeanUtilsBean that is configured to use 103 * type converters that throw a ConversionException 104 * instead of using the default value when something 105 * goes wrong. 106 * 107 * @return a configured BeanUtilsBean 108 */ 109 private static BeanUtilsBean createBeanUtilsBean() { 110 final ConvertUtilsBean cub = new ConvertUtilsBean(); 111 112 registerIntegralTypes(cub); 113 registerCustomTypes(cub); 114 115 return new BeanUtilsBean(cub, new PropertyUtilsBean()); 116 } 117 118 /** 119 * Register basic types of JDK like boolean, int, and String to use with BeanUtils. All these 120 * types are found in the {@code java.lang} package. 121 * 122 * @param cub 123 * Instance of {@link ConvertUtilsBean} to register types with. 124 */ 125 private static void registerIntegralTypes(ConvertUtilsBean cub) { 126 cub.register(new BooleanConverter(), Boolean.TYPE); 127 cub.register(new BooleanConverter(), Boolean.class); 128 cub.register(new ArrayConverter( 129 boolean[].class, new BooleanConverter()), boolean[].class); 130 cub.register(new ByteConverter(), Byte.TYPE); 131 cub.register(new ByteConverter(), Byte.class); 132 cub.register(new ArrayConverter(byte[].class, new ByteConverter()), 133 byte[].class); 134 cub.register(new CharacterConverter(), Character.TYPE); 135 cub.register(new CharacterConverter(), Character.class); 136 cub.register(new ArrayConverter(char[].class, new CharacterConverter()), 137 char[].class); 138 cub.register(new DoubleConverter(), Double.TYPE); 139 cub.register(new DoubleConverter(), Double.class); 140 cub.register(new ArrayConverter(double[].class, new DoubleConverter()), 141 double[].class); 142 cub.register(new FloatConverter(), Float.TYPE); 143 cub.register(new FloatConverter(), Float.class); 144 cub.register(new ArrayConverter(float[].class, new FloatConverter()), 145 float[].class); 146 cub.register(new IntegerConverter(), Integer.TYPE); 147 cub.register(new IntegerConverter(), Integer.class); 148 cub.register(new ArrayConverter(int[].class, new IntegerConverter()), 149 int[].class); 150 cub.register(new LongConverter(), Long.TYPE); 151 cub.register(new LongConverter(), Long.class); 152 cub.register(new ArrayConverter(long[].class, new LongConverter()), 153 long[].class); 154 cub.register(new ShortConverter(), Short.TYPE); 155 cub.register(new ShortConverter(), Short.class); 156 cub.register(new ArrayConverter(short[].class, new ShortConverter()), 157 short[].class); 158 cub.register(new RelaxedStringArrayConverter(), String[].class); 159 160 // BigDecimal, BigInteger, Class, Date, String, Time, TimeStamp 161 // do not use defaults in the default configuration of ConvertUtilsBean 162 } 163 164 /** 165 * Register custom types of JDK like URI and Checkstyle specific classes to use with BeanUtils. 166 * None of these types should be found in the {@code java.lang} package. 167 * 168 * @param cub 169 * Instance of {@link ConvertUtilsBean} to register types with. 170 */ 171 private static void registerCustomTypes(ConvertUtilsBean cub) { 172 cub.register(new PatternConverter(), Pattern.class); 173 cub.register(new SeverityLevelConverter(), SeverityLevel.class); 174 cub.register(new ScopeConverter(), Scope.class); 175 cub.register(new UriConverter(), URI.class); 176 cub.register(new RelaxedAccessModifierArrayConverter(), AccessModifierOption[].class); 177 } 178 179 /** 180 * Implements the Configurable interface using bean introspection. 181 * 182 * <p>Subclasses are allowed to add behaviour. After the bean 183 * based setup has completed first the method 184 * {@link #finishLocalSetup finishLocalSetup} 185 * is called to allow completion of the bean's local setup, 186 * after that the method {@link #setupChild setupChild} 187 * is called for each {@link Configuration#getChildren child Configuration} 188 * of {@code configuration}. 189 * 190 * @see Configurable 191 */ 192 @Override 193 public final void configure(Configuration config) 194 throws CheckstyleException { 195 configuration = config; 196 197 final String[] attributes = config.getPropertyNames(); 198 199 for (final String key : attributes) { 200 final String value = config.getProperty(key); 201 202 tryCopyProperty(key, value, true); 203 } 204 205 finishLocalSetup(); 206 207 final Configuration[] childConfigs = config.getChildren(); 208 for (final Configuration childConfig : childConfigs) { 209 setupChild(childConfig); 210 } 211 } 212 213 /** 214 * Recheck property and try to copy it. 215 * 216 * @param key key of value 217 * @param value value 218 * @param recheck whether to check for property existence before copy 219 * @throws CheckstyleException when property defined incorrectly 220 */ 221 private void tryCopyProperty(String key, Object value, boolean recheck) 222 throws CheckstyleException { 223 final BeanUtilsBean beanUtils = createBeanUtilsBean(); 224 225 try { 226 if (recheck) { 227 // BeanUtilsBean.copyProperties silently ignores missing setters 228 // for key, so we have to go through great lengths here to 229 // figure out if the bean property really exists. 230 final PropertyDescriptor descriptor = 231 PropertyUtils.getPropertyDescriptor(this, key); 232 if (descriptor == null) { 233 final String message = String.format(Locale.ROOT, "Property '%s' " 234 + "does not exist, please check the documentation", key); 235 throw new CheckstyleException(message); 236 } 237 } 238 // finally we can set the bean property 239 beanUtils.copyProperty(this, key, value); 240 } 241 catch (final InvocationTargetException | IllegalAccessException 242 | NoSuchMethodException ex) { 243 // There is no way to catch IllegalAccessException | NoSuchMethodException 244 // as we do PropertyUtils.getPropertyDescriptor before beanUtils.copyProperty, 245 // so we have to join these exceptions with InvocationTargetException 246 // to satisfy UTs coverage 247 final String message = String.format(Locale.ROOT, 248 "Cannot set property '%s' to '%s'", key, value); 249 throw new CheckstyleException(message, ex); 250 } 251 catch (final IllegalArgumentException | ConversionException ex) { 252 final String message = String.format(Locale.ROOT, "illegal value '%s' for property " 253 + "'%s'", value, key); 254 throw new CheckstyleException(message, ex); 255 } 256 } 257 258 /** 259 * Implements the Contextualizable interface using bean introspection. 260 * 261 * @see Contextualizable 262 */ 263 @Override 264 public final void contextualize(Context context) 265 throws CheckstyleException { 266 final Collection<String> attributes = context.getAttributeNames(); 267 268 for (final String key : attributes) { 269 final Object value = context.get(key); 270 271 tryCopyProperty(key, value, false); 272 } 273 } 274 275 /** 276 * Returns the configuration that was used to configure this component. 277 * 278 * @return the configuration that was used to configure this component. 279 */ 280 protected final Configuration getConfiguration() { 281 return configuration; 282 } 283 284 /** 285 * Called by configure() for every child of this component's Configuration. 286 * <p> 287 * The default implementation throws {@link CheckstyleException} if 288 * {@code childConf} is {@code null} because it doesn't support children. It 289 * must be overridden to validate and support children that are wanted. 290 * </p> 291 * 292 * @param childConf a child of this component's Configuration 293 * @throws CheckstyleException if there is a configuration error. 294 * @see Configuration#getChildren 295 */ 296 protected void setupChild(Configuration childConf) 297 throws CheckstyleException { 298 if (childConf != null) { 299 throw new CheckstyleException(childConf.getName() + " is not allowed as a child in " 300 + configuration.getName() + ". Please review 'Parent Module' section " 301 + "for this Check in web documentation if Check is standard."); 302 } 303 } 304 305 /** A converter that converts a string to a pattern. */ 306 private static final class PatternConverter implements Converter { 307 308 @SuppressWarnings("unchecked") 309 @Override 310 public Object convert(Class type, Object value) { 311 return CommonUtil.createPattern(value.toString()); 312 } 313 314 } 315 316 /** A converter that converts strings to severity level. */ 317 private static final class SeverityLevelConverter implements Converter { 318 319 @SuppressWarnings("unchecked") 320 @Override 321 public Object convert(Class type, Object value) { 322 return SeverityLevel.getInstance(value.toString()); 323 } 324 325 } 326 327 /** A converter that converts strings to scope. */ 328 private static final class ScopeConverter implements Converter { 329 330 @SuppressWarnings("unchecked") 331 @Override 332 public Object convert(Class type, Object value) { 333 return Scope.getInstance(value.toString()); 334 } 335 336 } 337 338 /** A converter that converts strings to uri. */ 339 private static final class UriConverter implements Converter { 340 341 @SuppressWarnings("unchecked") 342 @Override 343 @Nullable 344 public Object convert(Class type, Object value) { 345 final String url = value.toString(); 346 URI result = null; 347 348 if (!CommonUtil.isBlank(url)) { 349 try { 350 result = CommonUtil.getUriByFilename(url); 351 } 352 catch (CheckstyleException ex) { 353 throw new IllegalArgumentException(ex); 354 } 355 } 356 357 return result; 358 } 359 360 } 361 362 /** 363 * A converter that does not care whether the array elements contain String 364 * characters like '*' or '_'. The normal ArrayConverter class has problems 365 * with these characters. 366 */ 367 private static final class RelaxedStringArrayConverter implements Converter { 368 369 @SuppressWarnings("unchecked") 370 @Override 371 public Object convert(Class type, Object value) { 372 final StringTokenizer tokenizer = new StringTokenizer( 373 value.toString().trim(), COMMA_SEPARATOR); 374 final List<String> result = new ArrayList<>(); 375 376 while (tokenizer.hasMoreTokens()) { 377 final String token = tokenizer.nextToken(); 378 result.add(token.trim()); 379 } 380 381 return result.toArray(CommonUtil.EMPTY_STRING_ARRAY); 382 } 383 384 } 385 386 /** 387 * A converter that converts strings to {@link AccessModifierOption}. 388 * This implementation does not care whether the array elements contain characters like '_'. 389 * The normal {@link ArrayConverter} class has problems with this character. 390 */ 391 private static final class RelaxedAccessModifierArrayConverter implements Converter { 392 393 /** Constant for optimization. */ 394 private static final AccessModifierOption[] EMPTY_MODIFIER_ARRAY = 395 new AccessModifierOption[0]; 396 397 @SuppressWarnings("unchecked") 398 @Override 399 public Object convert(Class type, Object value) { 400 // Converts to a String and trims it for the tokenizer. 401 final StringTokenizer tokenizer = new StringTokenizer( 402 value.toString().trim(), COMMA_SEPARATOR); 403 final List<AccessModifierOption> result = new ArrayList<>(); 404 405 while (tokenizer.hasMoreTokens()) { 406 final String token = tokenizer.nextToken(); 407 result.add(AccessModifierOption.getInstance(token)); 408 } 409 410 return result.toArray(EMPTY_MODIFIER_ARRAY); 411 } 412 413 } 414 415}