View Javadoc
1   ///////////////////////////////////////////////////////////////////////////////////////////////
2   // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3   // Copyright (C) 2001-2025 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.checks;
21  
22  import java.io.File;
23  import java.io.IOException;
24  import java.io.InputStream;
25  import java.io.Serial;
26  import java.nio.file.Files;
27  import java.util.ArrayList;
28  import java.util.Collections;
29  import java.util.Enumeration;
30  import java.util.Iterator;
31  import java.util.List;
32  import java.util.Properties;
33  import java.util.regex.Matcher;
34  import java.util.regex.Pattern;
35  
36  import com.puppycrawl.tools.checkstyle.StatelessCheck;
37  import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck;
38  import com.puppycrawl.tools.checkstyle.api.FileText;
39  
40  /**
41   * <div>
42   * Detects if keys in properties files are in correct order.
43   * </div>
44   *
45   * <p>
46   *   Rationale: Sorted properties make it easy for people to find required properties by name
47   *   in file. This makes it easier to merge. While there are no problems at runtime.
48   *   This check is valuable only on files with string resources where order of lines
49   *   does not matter at all, but this can be improved.
50   *   E.g.: checkstyle/src/main/resources/com/puppycrawl/tools/checkstyle/messages.properties
51   *   You may suppress warnings of this check for files that have a logical structure like
52   *   build files or log4j configuration files. See SuppressionFilter.
53   *   {@code
54   *   &lt;suppress checks="OrderedProperties"
55   *     files="log4j.properties|ResourceBundle/Bug.*.properties|logging.properties"/&gt;
56   *   }
57   * </p>
58   *
59   * <p>Known limitation: The key should not contain a newline.
60   * The string compare will work, but not the line number reporting.</p>
61   *
62   * @since 8.22
63   */
64  @StatelessCheck
65  public class OrderedPropertiesCheck extends AbstractFileSetCheck {
66  
67      /**
68       * Localization key for check violation.
69       */
70      public static final String MSG_KEY = "properties.notSorted.property";
71      /**
72       * Localization key for IO exception occurred on file open.
73       */
74      public static final String MSG_IO_EXCEPTION_KEY = "unable.open.cause";
75      /**
76       * Pattern matching single space.
77       */
78      private static final Pattern SPACE_PATTERN = Pattern.compile(" ");
79  
80      /**
81       * Construct the check with default values.
82       */
83      public OrderedPropertiesCheck() {
84          setFileExtensions("properties");
85      }
86  
87      /**
88       * Setter to specify the file extensions of the files to process.
89       *
90       * @param extensions the set of file extensions. A missing
91       *         initial '.' character of an extension is automatically added.
92       * @throws IllegalArgumentException is argument is null
93       */
94      @Override
95      public final void setFileExtensions(String... extensions) {
96          super.setFileExtensions(extensions);
97      }
98  
99      /**
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 }