001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.io; 019 020import java.util.Arrays; 021import java.util.Locale; 022import java.util.Objects; 023 024/** 025 * Abstracts an OS' file system details, currently supporting the single use case of converting a file name String to a 026 * legal file name with {@link #toLegalFileName(String, char)}. 027 * <p> 028 * The starting point of any operation is {@link #getCurrent()} which gets you the enum for the file system that matches 029 * the OS hosting the running JVM. 030 * </p> 031 * 032 * @since 2.7 033 */ 034public enum FileSystem { 035 036 /** 037 * Generic file system. 038 */ 039 GENERIC(4096, false, false, Integer.MAX_VALUE, Integer.MAX_VALUE, new int[] { 0 }, new String[] {}, false, false, '/'), 040 041 /** 042 * Linux file system. 043 */ 044 LINUX(8192, true, true, 255, 4096, new int[] { 045 // KEEP THIS ARRAY SORTED! 046 // @formatter:off 047 // ASCII NUL 048 0, 049 '/' 050 // @formatter:on 051 }, new String[] {}, false, false, '/'), 052 053 /** 054 * MacOS file system. 055 */ 056 MAC_OSX(4096, true, true, 255, 1024, new int[] { 057 // KEEP THIS ARRAY SORTED! 058 // @formatter:off 059 // ASCII NUL 060 0, 061 '/', 062 ':' 063 // @formatter:on 064 }, new String[] {}, false, false, '/'), 065 066 /** 067 * Windows file system. 068 * <p> 069 * The reserved characters are defined in the 070 * <a href="https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file">Naming Conventions 071 * (microsoft.com)</a>. 072 * </p> 073 * 074 * @see <a href="https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file">Naming Conventions 075 * (microsoft.com)</a> 076 * @see <a href="https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea#consoles"> 077 * CreateFileA function - Consoles (microsoft.com)</a> 078 */ 079 // @formatter:off 080 WINDOWS(4096, false, true, 081 255, 32000, // KEEP THIS ARRAY SORTED! 082 new int[] { 083 // KEEP THIS ARRAY SORTED! 084 // ASCII NUL 085 0, 086 // 1-31 may be allowed in file streams 087 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 088 29, 30, 31, 089 '"', '*', '/', ':', '<', '>', '?', '\\', '|' 090 }, new String[] { 091 "AUX", 092 "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", 093 "COM\u00b2", "COM\u00b3", "COM\u00b9", // Superscript 2 3 1 in that order 094 "CON", "CONIN$", "CONOUT$", 095 "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", 096 "LPT\u00b2", "LPT\u00b3", "LPT\u00b9", // Superscript 2 3 1 in that order 097 "NUL", "PRN" 098 }, true, true, '\\'); 099 // @formatter:on 100 101 /** 102 * <p> 103 * Is {@code true} if this is Linux. 104 * </p> 105 * <p> 106 * The field will return {@code false} if {@code OS_NAME} is {@code null}. 107 * </p> 108 */ 109 private static final boolean IS_OS_LINUX = getOsMatchesName("Linux"); 110 111 /** 112 * <p> 113 * Is {@code true} if this is Mac. 114 * </p> 115 * <p> 116 * The field will return {@code false} if {@code OS_NAME} is {@code null}. 117 * </p> 118 */ 119 private static final boolean IS_OS_MAC = getOsMatchesName("Mac"); 120 121 /** 122 * The prefix String for all Windows OS. 123 */ 124 private static final String OS_NAME_WINDOWS_PREFIX = "Windows"; 125 126 /** 127 * <p> 128 * Is {@code true} if this is Windows. 129 * </p> 130 * <p> 131 * The field will return {@code false} if {@code OS_NAME} is {@code null}. 132 * </p> 133 */ 134 private static final boolean IS_OS_WINDOWS = getOsMatchesName(OS_NAME_WINDOWS_PREFIX); 135 136 /** 137 * The current FileSystem. 138 */ 139 private static final FileSystem CURRENT = current(); 140 141 /** 142 * Gets the current file system. 143 * 144 * @return the current file system 145 */ 146 private static FileSystem current() { 147 if (IS_OS_LINUX) { 148 return LINUX; 149 } 150 if (IS_OS_MAC) { 151 return MAC_OSX; 152 } 153 if (IS_OS_WINDOWS) { 154 return WINDOWS; 155 } 156 return GENERIC; 157 } 158 159 /** 160 * Gets the current file system. 161 * 162 * @return the current file system 163 */ 164 public static FileSystem getCurrent() { 165 return CURRENT; 166 } 167 168 /** 169 * Decides if the operating system matches. 170 * 171 * @param osNamePrefix 172 * the prefix for the os name 173 * @return true if matches, or false if not or can't determine 174 */ 175 private static boolean getOsMatchesName(final String osNamePrefix) { 176 return isOsNameMatch(getSystemProperty("os.name"), osNamePrefix); 177 } 178 179 /** 180 * <p> 181 * Gets a System property, defaulting to {@code null} if the property cannot be read. 182 * </p> 183 * <p> 184 * If a {@link SecurityException} is caught, the return value is {@code null} and a message is written to 185 * {@code System.err}. 186 * </p> 187 * 188 * @param property 189 * the system property name 190 * @return the system property value or {@code null} if a security problem occurs 191 */ 192 private static String getSystemProperty(final String property) { 193 try { 194 return System.getProperty(property); 195 } catch (final SecurityException ex) { 196 // we are not allowed to look at this property 197 System.err.println("Caught a SecurityException reading the system property '" + property 198 + "'; the SystemUtils property value will default to null."); 199 return null; 200 } 201 } 202 203 /** 204 * Copied from Apache Commons Lang CharSequenceUtils. 205 * 206 * Returns the index within {@code cs} of the first occurrence of the 207 * specified character, starting the search at the specified index. 208 * <p> 209 * If a character with value {@code searchChar} occurs in the 210 * character sequence represented by the {@code cs} 211 * object at an index no smaller than {@code start}, then 212 * the index of the first such occurrence is returned. For values 213 * of {@code searchChar} in the range from 0 to 0xFFFF (inclusive), 214 * this is the smallest value <em>k</em> such that: 215 * </p> 216 * <blockquote><pre> 217 * (this.charAt(<em>k</em>) == searchChar) && (<em>k</em> >= start) 218 * </pre></blockquote> 219 * is true. For other values of {@code searchChar}, it is the 220 * smallest value <em>k</em> such that: 221 * <blockquote><pre> 222 * (this.codePointAt(<em>k</em>) == searchChar) && (<em>k</em> >= start) 223 * </pre></blockquote> 224 * <p> 225 * is true. In either case, if no such character occurs in {@code cs} 226 * at or after position {@code start}, then 227 * {@code -1} is returned. 228 * </p> 229 * <p> 230 * There is no restriction on the value of {@code start}. If it 231 * is negative, it has the same effect as if it were zero: the entire 232 * {@link CharSequence} may be searched. If it is greater than 233 * the length of {@code cs}, it has the same effect as if it were 234 * equal to the length of {@code cs}: {@code -1} is returned. 235 * </p> 236 * <p>All indices are specified in {@code char} values 237 * (Unicode code units). 238 * </p> 239 * 240 * @param cs the {@link CharSequence} to be processed, not null 241 * @param searchChar the char to be searched for 242 * @param start the start index, negative starts at the string start 243 * @return the index where the search char was found, -1 if not found 244 * @since 3.6 updated to behave more like {@link String} 245 */ 246 private static int indexOf(final CharSequence cs, final int searchChar, int start) { 247 if (cs instanceof String) { 248 return ((String) cs).indexOf(searchChar, start); 249 } 250 final int sz = cs.length(); 251 if (start < 0) { 252 start = 0; 253 } 254 if (searchChar < Character.MIN_SUPPLEMENTARY_CODE_POINT) { 255 for (int i = start; i < sz; i++) { 256 if (cs.charAt(i) == searchChar) { 257 return i; 258 } 259 } 260 return -1; 261 } 262 //supplementary characters (LANG1300) 263 if (searchChar <= Character.MAX_CODE_POINT) { 264 final char[] chars = Character.toChars(searchChar); 265 for (int i = start; i < sz - 1; i++) { 266 final char high = cs.charAt(i); 267 final char low = cs.charAt(i + 1); 268 if (high == chars[0] && low == chars[1]) { 269 return i; 270 } 271 } 272 } 273 return -1; 274 } 275 276 /** 277 * Decides if the operating system matches. 278 * <p> 279 * This method is package private instead of private to support unit test invocation. 280 * </p> 281 * 282 * @param osName 283 * the actual OS name 284 * @param osNamePrefix 285 * the prefix for the expected OS name 286 * @return true if matches, or false if not or can't determine 287 */ 288 private static boolean isOsNameMatch(final String osName, final String osNamePrefix) { 289 if (osName == null) { 290 return false; 291 } 292 return osName.toUpperCase(Locale.ROOT).startsWith(osNamePrefix.toUpperCase(Locale.ROOT)); 293 } 294 295 /** 296 * Null-safe replace. 297 * 298 * @param path the path to be changed, null ignored. 299 * @param oldChar the old character. 300 * @param newChar the new character. 301 * @return the new path. 302 */ 303 private static String replace(final String path, final char oldChar, final char newChar) { 304 return path == null ? null : path.replace(oldChar, newChar); 305 } 306 307 private final int blockSize; 308 private final boolean casePreserving; 309 private final boolean caseSensitive; 310 private final int[] illegalFileNameChars; 311 private final int maxFileNameLength; 312 private final int maxPathLength; 313 private final String[] reservedFileNames; 314 private final boolean reservedFileNamesExtensions; 315 private final boolean supportsDriveLetter; 316 private final char nameSeparator; 317 private final char nameSeparatorOther; 318 319 /** 320 * Constructs a new instance. 321 * 322 * @param blockSize file allocation block size in bytes. 323 * @param caseSensitive Whether this file system is case-sensitive. 324 * @param casePreserving Whether this file system is case-preserving. 325 * @param maxFileLength The maximum length for file names. The file name does not include folders. 326 * @param maxPathLength The maximum length of the path to a file. This can include folders. 327 * @param illegalFileNameChars Illegal characters for this file system. 328 * @param reservedFileNames The reserved file names. 329 * @param reservedFileNamesExtensions TODO 330 * @param supportsDriveLetter Whether this file system support driver letters. 331 * @param nameSeparator The name separator, '\\' on Windows, '/' on Linux. 332 */ 333 FileSystem(final int blockSize, final boolean caseSensitive, final boolean casePreserving, 334 final int maxFileLength, final int maxPathLength, final int[] illegalFileNameChars, 335 final String[] reservedFileNames, final boolean reservedFileNamesExtensions, final boolean supportsDriveLetter, final char nameSeparator) { 336 this.blockSize = blockSize; 337 this.maxFileNameLength = maxFileLength; 338 this.maxPathLength = maxPathLength; 339 this.illegalFileNameChars = Objects.requireNonNull(illegalFileNameChars, "illegalFileNameChars"); 340 this.reservedFileNames = Objects.requireNonNull(reservedFileNames, "reservedFileNames"); 341 //Arrays.sort(this.reservedFileNames); 342 this.reservedFileNamesExtensions = reservedFileNamesExtensions; 343 this.caseSensitive = caseSensitive; 344 this.casePreserving = casePreserving; 345 this.supportsDriveLetter = supportsDriveLetter; 346 this.nameSeparator = nameSeparator; 347 this.nameSeparatorOther = FilenameUtils.flipSeparator(nameSeparator); 348 } 349 350 /** 351 * Gets the file allocation block size in bytes. 352 * @return the file allocation block size in bytes. 353 * @since 2.12.0 354 */ 355 public int getBlockSize() { 356 return blockSize; 357 } 358 359 /** 360 * Gets a cloned copy of the illegal characters for this file system. 361 * 362 * @return the illegal characters for this file system. 363 */ 364 public char[] getIllegalFileNameChars() { 365 final char[] chars = new char[illegalFileNameChars.length]; 366 for (int i = 0; i < illegalFileNameChars.length; i++) { 367 chars[i] = (char) illegalFileNameChars[i]; 368 } 369 return chars; 370 } 371 372 /** 373 * Gets a cloned copy of the illegal code points for this file system. 374 * 375 * @return the illegal code points for this file system. 376 * @since 2.12.0 377 */ 378 public int[] getIllegalFileNameCodePoints() { 379 return this.illegalFileNameChars.clone(); 380 } 381 382 /** 383 * Gets the maximum length for file names. The file name does not include folders. 384 * 385 * @return the maximum length for file names. 386 */ 387 public int getMaxFileNameLength() { 388 return maxFileNameLength; 389 } 390 391 /** 392 * Gets the maximum length of the path to a file. This can include folders. 393 * 394 * @return the maximum length of the path to a file. 395 */ 396 public int getMaxPathLength() { 397 return maxPathLength; 398 } 399 400 /** 401 * Gets the name separator, '\\' on Windows, '/' on Linux. 402 * 403 * @return '\\' on Windows, '/' on Linux. 404 * @since 2.12.0 405 */ 406 public char getNameSeparator() { 407 return nameSeparator; 408 } 409 410 /** 411 * Gets a cloned copy of the reserved file names. 412 * 413 * @return the reserved file names. 414 */ 415 public String[] getReservedFileNames() { 416 return reservedFileNames.clone(); 417 } 418 419 /** 420 * Tests whether this file system preserves case. 421 * 422 * @return Whether this file system preserves case. 423 */ 424 public boolean isCasePreserving() { 425 return casePreserving; 426 } 427 428 /** 429 * Tests whether this file system is case-sensitive. 430 * 431 * @return Whether this file system is case-sensitive. 432 */ 433 public boolean isCaseSensitive() { 434 return caseSensitive; 435 } 436 437 /** 438 * Tests if the given character is illegal in a file name, {@code false} otherwise. 439 * 440 * @param c 441 * the character to test 442 * @return {@code true} if the given character is illegal in a file name, {@code false} otherwise. 443 */ 444 private boolean isIllegalFileNameChar(final int c) { 445 return Arrays.binarySearch(illegalFileNameChars, c) >= 0; 446 } 447 448 /** 449 * Tests if a candidate file name (without a path) such as {@code "filename.ext"} or {@code "filename"} is a 450 * potentially legal file name. If the file name length exceeds {@link #getMaxFileNameLength()}, or if it contains 451 * an illegal character then the check fails. 452 * 453 * @param candidate 454 * a candidate file name (without a path) like {@code "filename.ext"} or {@code "filename"} 455 * @return {@code true} if the candidate name is legal 456 */ 457 public boolean isLegalFileName(final CharSequence candidate) { 458 if (candidate == null || candidate.length() == 0 || candidate.length() > maxFileNameLength) { 459 return false; 460 } 461 if (isReservedFileName(candidate)) { 462 return false; 463 } 464 return candidate.chars().noneMatch(this::isIllegalFileNameChar); 465 } 466 467 /** 468 * Tests whether the given string is a reserved file name. 469 * 470 * @param candidate 471 * the string to test 472 * @return {@code true} if the given string is a reserved file name. 473 */ 474 public boolean isReservedFileName(final CharSequence candidate) { 475 final CharSequence test = reservedFileNamesExtensions ? trimExtension(candidate) : candidate; 476 return Arrays.binarySearch(reservedFileNames, test) >= 0; 477 } 478 479 /** 480 * Converts all separators to the Windows separator of backslash. 481 * 482 * @param path the path to be changed, null ignored 483 * @return the updated path 484 * @since 2.12.0 485 */ 486 public String normalizeSeparators(final String path) { 487 return replace(path, nameSeparatorOther, nameSeparator); 488 } 489 490 /** 491 * Tests whether this file system support driver letters. 492 * <p> 493 * Windows supports driver letters as do other operating systems. Whether these other OS's still support Java like 494 * OS/2, is a different matter. 495 * </p> 496 * 497 * @return whether this file system support driver letters. 498 * @since 2.9.0 499 * @see <a href="https://en.wikipedia.org/wiki/Drive_letter_assignment">Operating systems that use drive letter 500 * assignment</a> 501 */ 502 public boolean supportsDriveLetter() { 503 return supportsDriveLetter; 504 } 505 506 /** 507 * Converts a candidate file name (without a path) like {@code "filename.ext"} or {@code "filename"} to a legal file 508 * name. Illegal characters in the candidate name are replaced by the {@code replacement} character. If the file 509 * name length exceeds {@link #getMaxFileNameLength()}, then the name is truncated to 510 * {@link #getMaxFileNameLength()}. 511 * 512 * @param candidate 513 * a candidate file name (without a path) like {@code "filename.ext"} or {@code "filename"} 514 * @param replacement 515 * Illegal characters in the candidate name are replaced by this character 516 * @return a String without illegal characters 517 */ 518 public String toLegalFileName(final String candidate, final char replacement) { 519 if (isIllegalFileNameChar(replacement)) { 520 // %s does not work properly with NUL 521 throw new IllegalArgumentException(String.format("The replacement character '%s' cannot be one of the %s illegal characters: %s", 522 replacement == '\0' ? "\\0" : replacement, name(), Arrays.toString(illegalFileNameChars))); 523 } 524 final String truncated = candidate.length() > maxFileNameLength ? candidate.substring(0, maxFileNameLength) : candidate; 525 final int[] array = truncated.chars().map(i -> isIllegalFileNameChar(i) ? replacement : i).toArray(); 526 return new String(array, 0, array.length); 527 } 528 529 CharSequence trimExtension(final CharSequence cs) { 530 final int index = indexOf(cs, '.', 0); 531 return index < 0 ? cs : cs.subSequence(0, index); 532 } 533}