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}