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 WINDOWS(4096, false, true, 080 255, 32000, // KEEP THIS ARRAY SORTED! 081 new int[] { 082 // KEEP THIS ARRAY SORTED! 083 // @formatter:off 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 // @formatter:on 091 }, new String[] { "AUX", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "CON", "CONIN$", "CONOUT$", 092 "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", "NUL", "PRN" }, true, true, '\\'); 093 094 /** 095 * <p> 096 * Is {@code true} if this is Linux. 097 * </p> 098 * <p> 099 * The field will return {@code false} if {@code OS_NAME} is {@code null}. 100 * </p> 101 */ 102 private static final boolean IS_OS_LINUX = getOsMatchesName("Linux"); 103 104 /** 105 * <p> 106 * Is {@code true} if this is Mac. 107 * </p> 108 * <p> 109 * The field will return {@code false} if {@code OS_NAME} is {@code null}. 110 * </p> 111 */ 112 private static final boolean IS_OS_MAC = getOsMatchesName("Mac"); 113 114 /** 115 * The prefix String for all Windows OS. 116 */ 117 private static final String OS_NAME_WINDOWS_PREFIX = "Windows"; 118 119 /** 120 * <p> 121 * Is {@code true} if this is Windows. 122 * </p> 123 * <p> 124 * The field will return {@code false} if {@code OS_NAME} is {@code null}. 125 * </p> 126 */ 127 private static final boolean IS_OS_WINDOWS = getOsMatchesName(OS_NAME_WINDOWS_PREFIX); 128 129 /** 130 * The current FileSystem. 131 */ 132 private static final FileSystem CURRENT = current(); 133 134 /** 135 * Gets the current file system. 136 * 137 * @return the current file system 138 */ 139 private static FileSystem current() { 140 if (IS_OS_LINUX) { 141 return LINUX; 142 } 143 if (IS_OS_MAC) { 144 return MAC_OSX; 145 } 146 if (IS_OS_WINDOWS) { 147 return WINDOWS; 148 } 149 return GENERIC; 150 } 151 152 /** 153 * Gets the current file system. 154 * 155 * @return the current file system 156 */ 157 public static FileSystem getCurrent() { 158 return CURRENT; 159 } 160 161 /** 162 * Decides if the operating system matches. 163 * 164 * @param osNamePrefix 165 * the prefix for the os name 166 * @return true if matches, or false if not or can't determine 167 */ 168 private static boolean getOsMatchesName(final String osNamePrefix) { 169 return isOsNameMatch(getSystemProperty("os.name"), osNamePrefix); 170 } 171 172 /** 173 * <p> 174 * Gets a System property, defaulting to {@code null} if the property cannot be read. 175 * </p> 176 * <p> 177 * If a {@link SecurityException} is caught, the return value is {@code null} and a message is written to 178 * {@code System.err}. 179 * </p> 180 * 181 * @param property 182 * the system property name 183 * @return the system property value or {@code null} if a security problem occurs 184 */ 185 private static String getSystemProperty(final String property) { 186 try { 187 return System.getProperty(property); 188 } catch (final SecurityException ex) { 189 // we are not allowed to look at this property 190 System.err.println("Caught a SecurityException reading the system property '" + property 191 + "'; the SystemUtils property value will default to null."); 192 return null; 193 } 194 } 195 196 /** 197 * Copied from Apache Commons Lang CharSequenceUtils. 198 * 199 * Returns the index within {@code cs} of the first occurrence of the 200 * specified character, starting the search at the specified index. 201 * <p> 202 * If a character with value {@code searchChar} occurs in the 203 * character sequence represented by the {@code cs} 204 * object at an index no smaller than {@code start}, then 205 * the index of the first such occurrence is returned. For values 206 * of {@code searchChar} in the range from 0 to 0xFFFF (inclusive), 207 * this is the smallest value <i>k</i> such that: 208 * </p> 209 * <blockquote><pre> 210 * (this.charAt(<i>k</i>) == searchChar) && (<i>k</i> >= start) 211 * </pre></blockquote> 212 * is true. For other values of {@code searchChar}, it is the 213 * smallest value <i>k</i> such that: 214 * <blockquote><pre> 215 * (this.codePointAt(<i>k</i>) == searchChar) && (<i>k</i> >= start) 216 * </pre></blockquote> 217 * <p> 218 * is true. In either case, if no such character occurs in {@code cs} 219 * at or after position {@code start}, then 220 * {@code -1} is returned. 221 * </p> 222 * <p> 223 * There is no restriction on the value of {@code start}. If it 224 * is negative, it has the same effect as if it were zero: the entire 225 * {@link CharSequence} may be searched. If it is greater than 226 * the length of {@code cs}, it has the same effect as if it were 227 * equal to the length of {@code cs}: {@code -1} is returned. 228 * </p> 229 * <p>All indices are specified in {@code char} values 230 * (Unicode code units). 231 * </p> 232 * 233 * @param cs the {@link CharSequence} to be processed, not null 234 * @param searchChar the char to be searched for 235 * @param start the start index, negative starts at the string start 236 * @return the index where the search char was found, -1 if not found 237 * @since 3.6 updated to behave more like {@link String} 238 */ 239 private static int indexOf(final CharSequence cs, final int searchChar, int start) { 240 if (cs instanceof String) { 241 return ((String) cs).indexOf(searchChar, start); 242 } 243 final int sz = cs.length(); 244 if (start < 0) { 245 start = 0; 246 } 247 if (searchChar < Character.MIN_SUPPLEMENTARY_CODE_POINT) { 248 for (int i = start; i < sz; i++) { 249 if (cs.charAt(i) == searchChar) { 250 return i; 251 } 252 } 253 return -1; 254 } 255 //supplementary characters (LANG1300) 256 if (searchChar <= Character.MAX_CODE_POINT) { 257 final char[] chars = Character.toChars(searchChar); 258 for (int i = start; i < sz - 1; i++) { 259 final char high = cs.charAt(i); 260 final char low = cs.charAt(i + 1); 261 if (high == chars[0] && low == chars[1]) { 262 return i; 263 } 264 } 265 } 266 return -1; 267 } 268 269 /** 270 * Decides if the operating system matches. 271 * <p> 272 * This method is package private instead of private to support unit test invocation. 273 * </p> 274 * 275 * @param osName 276 * the actual OS name 277 * @param osNamePrefix 278 * the prefix for the expected OS name 279 * @return true if matches, or false if not or can't determine 280 */ 281 private static boolean isOsNameMatch(final String osName, final String osNamePrefix) { 282 if (osName == null) { 283 return false; 284 } 285 return osName.toUpperCase(Locale.ROOT).startsWith(osNamePrefix.toUpperCase(Locale.ROOT)); 286 } 287 288 /** 289 * Null-safe replace. 290 * 291 * @param path the path to be changed, null ignored. 292 * @param oldChar the old character. 293 * @param newChar the new character. 294 * @return the new path. 295 */ 296 private static String replace(final String path, final char oldChar, final char newChar) { 297 return path == null ? null : path.replace(oldChar, newChar); 298 } 299 300 private final int blockSize; 301 private final boolean casePreserving; 302 private final boolean caseSensitive; 303 private final int[] illegalFileNameChars; 304 private final int maxFileNameLength; 305 private final int maxPathLength; 306 private final String[] reservedFileNames; 307 private final boolean reservedFileNamesExtensions; 308 private final boolean supportsDriveLetter; 309 private final char nameSeparator; 310 private final char nameSeparatorOther; 311 312 /** 313 * Constructs a new instance. 314 * 315 * @param blockSize file allocation block size in bytes. 316 * @param caseSensitive Whether this file system is case-sensitive. 317 * @param casePreserving Whether this file system is case-preserving. 318 * @param maxFileLength The maximum length for file names. The file name does not include folders. 319 * @param maxPathLength The maximum length of the path to a file. This can include folders. 320 * @param illegalFileNameChars Illegal characters for this file system. 321 * @param reservedFileNames The reserved file names. 322 * @param reservedFileNamesExtensions TODO 323 * @param supportsDriveLetter Whether this file system support driver letters. 324 * @param nameSeparator The name separator, '\\' on Windows, '/' on Linux. 325 */ 326 FileSystem(final int blockSize, final boolean caseSensitive, final boolean casePreserving, 327 final int maxFileLength, final int maxPathLength, final int[] illegalFileNameChars, 328 final String[] reservedFileNames, final boolean reservedFileNamesExtensions, final boolean supportsDriveLetter, final char nameSeparator) { 329 this.blockSize = blockSize; 330 this.maxFileNameLength = maxFileLength; 331 this.maxPathLength = maxPathLength; 332 this.illegalFileNameChars = Objects.requireNonNull(illegalFileNameChars, "illegalFileNameChars"); 333 this.reservedFileNames = Objects.requireNonNull(reservedFileNames, "reservedFileNames"); 334 this.reservedFileNamesExtensions = reservedFileNamesExtensions; 335 this.caseSensitive = caseSensitive; 336 this.casePreserving = casePreserving; 337 this.supportsDriveLetter = supportsDriveLetter; 338 this.nameSeparator = nameSeparator; 339 this.nameSeparatorOther = FilenameUtils.flipSeparator(nameSeparator); 340 } 341 342 /** 343 * Gets the file allocation block size in bytes. 344 * @return the file allocation block size in bytes. 345 * 346 * @since 2.12.0 347 */ 348 public int getBlockSize() { 349 return blockSize; 350 } 351 352 /** 353 * Gets a cloned copy of the illegal characters for this file system. 354 * 355 * @return the illegal characters for this file system. 356 */ 357 public char[] getIllegalFileNameChars() { 358 final char[] chars = new char[illegalFileNameChars.length]; 359 for (int i = 0; i < illegalFileNameChars.length; i++) { 360 chars[i] = (char) illegalFileNameChars[i]; 361 } 362 return chars; 363 } 364 365 /** 366 * Gets a cloned copy of the illegal code points for this file system. 367 * 368 * @return the illegal code points for this file system. 369 * @since 2.12.0 370 */ 371 public int[] getIllegalFileNameCodePoints() { 372 return this.illegalFileNameChars.clone(); 373 } 374 375 /** 376 * Gets the maximum length for file names. The file name does not include folders. 377 * 378 * @return the maximum length for file names. 379 */ 380 public int getMaxFileNameLength() { 381 return maxFileNameLength; 382 } 383 384 /** 385 * Gets the maximum length of the path to a file. This can include folders. 386 * 387 * @return the maximum length of the path to a file. 388 */ 389 public int getMaxPathLength() { 390 return maxPathLength; 391 } 392 393 /** 394 * Gets the name separator, '\\' on Windows, '/' on Linux. 395 * 396 * @return '\\' on Windows, '/' on Linux. 397 * 398 * @since 2.12.0 399 */ 400 public char getNameSeparator() { 401 return nameSeparator; 402 } 403 404 /** 405 * Gets a cloned copy of the reserved file names. 406 * 407 * @return the reserved file names. 408 */ 409 public String[] getReservedFileNames() { 410 return reservedFileNames.clone(); 411 } 412 413 /** 414 * Tests whether this file system preserves case. 415 * 416 * @return Whether this file system preserves case. 417 */ 418 public boolean isCasePreserving() { 419 return casePreserving; 420 } 421 422 /** 423 * Tests whether this file system is case-sensitive. 424 * 425 * @return Whether this file system is case-sensitive. 426 */ 427 public boolean isCaseSensitive() { 428 return caseSensitive; 429 } 430 431 /** 432 * Tests if the given character is illegal in a file name, {@code false} otherwise. 433 * 434 * @param c 435 * the character to test 436 * @return {@code true} if the given character is illegal in a file name, {@code false} otherwise. 437 */ 438 private boolean isIllegalFileNameChar(final int c) { 439 return Arrays.binarySearch(illegalFileNameChars, c) >= 0; 440 } 441 442 /** 443 * Tests if a candidate file name (without a path) such as {@code "filename.ext"} or {@code "filename"} is a 444 * potentially legal file name. If the file name length exceeds {@link #getMaxFileNameLength()}, or if it contains 445 * an illegal character then the check fails. 446 * 447 * @param candidate 448 * a candidate file name (without a path) like {@code "filename.ext"} or {@code "filename"} 449 * @return {@code true} if the candidate name is legal 450 */ 451 public boolean isLegalFileName(final CharSequence candidate) { 452 if (candidate == null || candidate.length() == 0 || candidate.length() > maxFileNameLength) { 453 return false; 454 } 455 if (isReservedFileName(candidate)) { 456 return false; 457 } 458 return candidate.chars().noneMatch(this::isIllegalFileNameChar); 459 } 460 461 /** 462 * Tests whether the given string is a reserved file name. 463 * 464 * @param candidate 465 * the string to test 466 * @return {@code true} if the given string is a reserved file name. 467 */ 468 public boolean isReservedFileName(final CharSequence candidate) { 469 final CharSequence test = reservedFileNamesExtensions ? trimExtension(candidate) : candidate; 470 return Arrays.binarySearch(reservedFileNames, test) >= 0; 471 } 472 473 /** 474 * Converts all separators to the Windows separator of backslash. 475 * 476 * @param path the path to be changed, null ignored 477 * @return the updated path 478 * @since 2.12.0 479 */ 480 public String normalizeSeparators(final String path) { 481 return replace(path, nameSeparatorOther, nameSeparator); 482 } 483 484 /** 485 * Tests whether this file system support driver letters. 486 * <p> 487 * Windows supports driver letters as do other operating systems. Whether these other OS's still support Java like 488 * OS/2, is a different matter. 489 * </p> 490 * 491 * @return whether this file system support driver letters. 492 * @since 2.9.0 493 * @see <a href="https://en.wikipedia.org/wiki/Drive_letter_assignment">Operating systems that use drive letter 494 * assignment</a> 495 */ 496 public boolean supportsDriveLetter() { 497 return supportsDriveLetter; 498 } 499 500 /** 501 * Converts a candidate file name (without a path) like {@code "filename.ext"} or {@code "filename"} to a legal file 502 * name. Illegal characters in the candidate name are replaced by the {@code replacement} character. If the file 503 * name length exceeds {@link #getMaxFileNameLength()}, then the name is truncated to 504 * {@link #getMaxFileNameLength()}. 505 * 506 * @param candidate 507 * a candidate file name (without a path) like {@code "filename.ext"} or {@code "filename"} 508 * @param replacement 509 * Illegal characters in the candidate name are replaced by this character 510 * @return a String without illegal characters 511 */ 512 public String toLegalFileName(final String candidate, final char replacement) { 513 if (isIllegalFileNameChar(replacement)) { 514 // %s does not work properly with NUL 515 throw new IllegalArgumentException(String.format("The replacement character '%s' cannot be one of the %s illegal characters: %s", 516 replacement == '\0' ? "\\0" : replacement, name(), Arrays.toString(illegalFileNameChars))); 517 } 518 final String truncated = candidate.length() > maxFileNameLength ? candidate.substring(0, maxFileNameLength) : candidate; 519 final int[] array = truncated.chars().map(i -> isIllegalFileNameChar(i) ? replacement : i).toArray(); 520 return new String(array, 0, array.length); 521 } 522 523 CharSequence trimExtension(final CharSequence cs) { 524 final int index = indexOf(cs, '.', 0); 525 return index < 0 ? cs : cs.subSequence(0, index); 526 } 527}