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 * <suppress checks="OrderedProperties"
55 * files="log4j.properties|ResourceBundle/Bug.*.properties|logging.properties"/>
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 }