Source code

001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2025 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.checks;
021
022import java.io.File;
023import java.io.IOException;
024import java.io.InputStream;
025import java.io.Serial;
026import java.nio.file.Files;
027import java.util.ArrayList;
028import java.util.Collections;
029import java.util.Enumeration;
030import java.util.Iterator;
031import java.util.List;
032import java.util.Properties;
033import java.util.regex.Matcher;
034import java.util.regex.Pattern;
035
036import com.puppycrawl.tools.checkstyle.StatelessCheck;
037import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck;
038import com.puppycrawl.tools.checkstyle.api.FileText;
039
040/**
041 * <div>
042 * Detects if keys in properties files are in correct order.
043 * </div>
044 *
045 * <p>
046 *   Rationale: Sorted properties make it easy for people to find required properties by name
047 *   in file. This makes it easier to merge. While there are no problems at runtime.
048 *   This check is valuable only on files with string resources where order of lines
049 *   does not matter at all, but this can be improved.
050 *   E.g.: checkstyle/src/main/resources/com/puppycrawl/tools/checkstyle/messages.properties
051 *   You may suppress warnings of this check for files that have a logical structure like
052 *   build files or log4j configuration files. See SuppressionFilter.
053 *   {@code
054 *   &lt;suppress checks="OrderedProperties"
055 *     files="log4j.properties|ResourceBundle/Bug.*.properties|logging.properties"/&gt;
056 *   }
057 * </p>
058 *
059 * <p>Known limitation: The key should not contain a newline.
060 * The string compare will work, but not the line number reporting.</p>
061 *
062 * @since 8.22
063 */
064@StatelessCheck
065public class OrderedPropertiesCheck extends AbstractFileSetCheck {
066
067    /**
068     * Localization key for check violation.
069     */
070    public static final String MSG_KEY = "properties.notSorted.property";
071    /**
072     * Localization key for IO exception occurred on file open.
073     */
074    public static final String MSG_IO_EXCEPTION_KEY = "unable.open.cause";
075    /**
076     * Pattern matching single space.
077     */
078    private static final Pattern SPACE_PATTERN = Pattern.compile(" ");
079
080    /**
081     * Construct the check with default values.
082     */
083    public OrderedPropertiesCheck() {
084        setFileExtensions("properties");
085    }
086
087    /**
088     * Setter to specify the file extensions of the files to process.
089     *
090     * @param extensions the set of file extensions. A missing
091     *         initial '.' character of an extension is automatically added.
092     * @throws IllegalArgumentException is argument is null
093     */
094    @Override
095    public final void setFileExtensions(String... extensions) {
096        super.setFileExtensions(extensions);
097    }
098
099    /**
100     * Processes the file and check order.
101     *
102     * @param file the file to be processed
103     * @param fileText the contents of the file.
104     */
105    @Override
106    protected void processFiltered(File file, FileText fileText) {
107        final SequencedProperties properties = new SequencedProperties();
108        try (InputStream inputStream = Files.newInputStream(file.toPath())) {
109            properties.load(inputStream);
110        }
111        catch (IOException | IllegalArgumentException exc) {
112            log(1, MSG_IO_EXCEPTION_KEY, file.getPath(), exc.getLocalizedMessage());
113        }
114
115        String previousProp = "";
116        int startLineNo = 0;
117
118        final Iterator<Object> propertyIterator = properties.keys().asIterator();
119
120        while (propertyIterator.hasNext()) {
121
122            final String propKey = (String) propertyIterator.next();
123
124            if (String.CASE_INSENSITIVE_ORDER.compare(previousProp, propKey) > 0) {
125
126                final int lineNo = getLineNumber(startLineNo, fileText, previousProp, propKey);
127                log(lineNo + 1, MSG_KEY, propKey, previousProp);
128                // start searching at position of the last reported validation
129                startLineNo = lineNo;
130            }
131
132            previousProp = propKey;
133        }
134    }
135
136    /**
137     * Method returns the index number where the key is detected (starting at 0).
138     * To assure that we get the correct line it starts at the point
139     * of the last occurrence.
140     * Also, the previousProp should be in file before propKey.
141     *
142     * @param startLineNo start searching at line
143     * @param fileText {@link FileText} object contains the lines to process
144     * @param previousProp key name found last iteration, works only if valid
145     * @param propKey key name to look for
146     * @return index number of first occurrence. If no key found in properties file, 0 is returned
147     */
148    private static int getLineNumber(int startLineNo, FileText fileText,
149                                     String previousProp, String propKey) {
150        final int indexOfPreviousProp = getIndex(startLineNo, fileText, previousProp);
151        return getIndex(indexOfPreviousProp, fileText, propKey);
152    }
153
154    /**
155     * Inner method to get the index number of the position of keyName.
156     *
157     * @param startLineNo start searching at line
158     * @param fileText {@link FileText} object contains the lines to process
159     * @param keyName key name to look for
160     * @return index number of first occurrence. If no key found in properties file, 0 is returned
161     */
162    private static int getIndex(int startLineNo, FileText fileText, String keyName) {
163        final Pattern keyPattern = getKeyPattern(keyName);
164        int indexNumber = 0;
165        final Matcher matcher = keyPattern.matcher("");
166        for (int index = startLineNo; index < fileText.size(); index++) {
167            final String line = fileText.get(index);
168            matcher.reset(line);
169            if (matcher.matches()) {
170                indexNumber = index;
171                break;
172            }
173        }
174        return indexNumber;
175    }
176
177    /**
178     * Method returns regular expression pattern given key name.
179     *
180     * @param keyName
181     *            key name to look for
182     * @return regular expression pattern given key name
183     */
184    private static Pattern getKeyPattern(String keyName) {
185        final String keyPatternString = "^" + SPACE_PATTERN.matcher(keyName)
186                .replaceAll(Matcher.quoteReplacement("\\\\ ")) + "[\\s:=].*";
187        return Pattern.compile(keyPatternString);
188    }
189
190    /**
191     * Private property implementation that keeps order of properties like in file.
192     *
193     * @noinspection ClassExtendsConcreteCollection
194     * @noinspectionreason ClassExtendsConcreteCollection - we require order from
195     *      file to be maintained by {@code put} method
196     */
197    private static final class SequencedProperties extends Properties {
198
199        /** A unique serial version identifier. */
200        @Serial
201        private static final long serialVersionUID = 1L;
202
203        /**
204         * Holding the keys in the same order as in the file.
205         */
206        private final List<Object> keyList = new ArrayList<>();
207
208        /**
209         * Returns a copy of the keys.
210         */
211        @Override
212        public Enumeration<Object> keys() {
213            return Collections.enumeration(keyList);
214        }
215
216        /**
217         * Puts the value into list by its key.
218         *
219         * @param key the hashtable key
220         * @param value the value
221         * @return the previous value of the specified key in this hashtable,
222         *      or null if it did not have one
223         * @throws NullPointerException - if the key or value is null
224         */
225        @Override
226        public synchronized Object put(Object key, Object value) {
227            keyList.add(key);
228
229            return null;
230        }
231    }
232}