Package org.apache.commons.io

Enum FileSystem

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<FileSystem>
    public enum FileSystem
extends java.lang.Enum<FileSystem>
    Enumerates file system details for operating systems, currently supporting the single use case of converting a file name String to a legal file name with toLegalFileName(String, char).

    The starting point of any operation is getCurrent() which gets you the enum for the file system that matches the OS hosting the running JVM.

    Since:
    2.7

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      (package private) static class  FileSystem.NameLengthStrategy
      Strategy for measuring and truncating file or path names in different units.

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description
      GENERIC
      Generic file system.
      LINUX
      Linux file system.
      MAC_OSX
      MacOS file system.
      WINDOWS
      Windows file system.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private FileSystem​(int blockSize, boolean caseSensitive, boolean casePreserving, int maxFileLength, int maxPathLength, int[] illegalFileNameChars, java.lang.String[] reservedFileNames, boolean reservedFileNamesExtensions, boolean supportsDriveLetter, char nameSeparator, FileSystem.NameLengthStrategy nameLengthStrategy)
      Constructs a new instance.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private static FileSystem current()
      Gets the current file system.
      int getBlockSize()
      Gets the file allocation block size in bytes.
      static FileSystem getCurrent()
      Gets the current file system.
      char[] getIllegalFileNameChars()
      Gets a cloned copy of the illegal characters for this file system.
      int[] getIllegalFileNameCodePoints()
      Gets a cloned copy of the illegal code points for this file system.
      int getMaxFileNameLength()
      Gets the maximum length for file names (excluding any folder path).
      int getMaxPathLength()
      Gets the maximum length for file paths (may include folders).
      (package private) FileSystem.NameLengthStrategy getNameLengthStrategy()  
      char getNameSeparator()
      Gets the name separator, '\\' on Windows, '/' on Linux.
      private static boolean getOsMatchesName​(java.lang.String osNamePrefix)
      Decides if the operating system matches.
      java.lang.String[] getReservedFileNames()
      Gets a cloned copy of the reserved file names.
      private static java.lang.String getSystemProperty​(java.lang.String property)
      Gets a System property, defaulting to null if the property cannot be read.
      private static int indexOfFirstDot​(java.lang.CharSequence cs)  
      boolean isCasePreserving()
      Tests whether this file system preserves case.
      boolean isCaseSensitive()
      Tests whether this file system is case-sensitive.
      private boolean isIllegalFileNameChar​(int c)
      Tests if the given character is illegal in a file name, false otherwise.
      boolean isLegalFileName​(java.lang.CharSequence candidate)
      Tests if a candidate file name (without a path) is a legal file name.
      boolean isLegalFileName​(java.lang.CharSequence candidate, java.nio.charset.Charset charset)
      Tests if a candidate file name (without a path) is a legal file name.
      private static boolean isOsNameMatch​(java.lang.String osName, java.lang.String osNamePrefix)
      Decides if the operating system matches.
      boolean isReservedFileName​(java.lang.CharSequence candidate)
      Tests whether the given string is a reserved file name.
      java.lang.String normalizeSeparators​(java.lang.String path)
      Converts all separators to the Windows separator of backslash.
      private static java.lang.String replace​(java.lang.String path, char oldChar, char newChar)
      Null-safe replace.
      private static java.lang.CharSequence safeTruncate​(java.lang.CharSequence value, int limit)
      Truncates a string respecting grapheme cluster boundaries.
      (package private) static java.lang.CharSequence[] splitExtension​(java.lang.CharSequence value)  
      boolean supportsDriveLetter()
      Tests whether this file system support driver letters.
      java.lang.String toLegalFileName​(java.lang.CharSequence candidate, char replacement, java.nio.charset.Charset charset)
      Converts a candidate file name (without a path) to a legal file name.
      java.lang.String toLegalFileName​(java.lang.String candidate, char replacement)
      Converts a candidate file name (without a path) to a legal file name.
      (package private) static java.lang.CharSequence trimExtension​(java.lang.CharSequence cs)  
      static FileSystem valueOf​(java.lang.String name)
      Returns the enum constant of this type with the specified name.
      static FileSystem[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.

      • Methods inherited from class java.lang.Enum

        clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • IS_OS_LINUX

        private static final boolean IS_OS_LINUX
        Is true if this is Linux.

        The field will return false if OS_NAME is null.

      • IS_OS_MAC

        private static final boolean IS_OS_MAC
        Is true if this is Mac.

        The field will return false if OS_NAME is null.

      • OS_NAME_WINDOWS_PREFIX

        private static final java.lang.String OS_NAME_WINDOWS_PREFIX
        The prefix String for all Windows OS.
        See Also:
        Constant Field Values

      • IS_OS_WINDOWS

        private static final boolean IS_OS_WINDOWS
        Is true if this is Windows.

        The field will return false if OS_NAME is null.

      • CURRENT

        private static final FileSystem CURRENT
        The current FileSystem.

      • blockSize

        private final int blockSize

      • casePreserving

        private final boolean casePreserving

      • caseSensitive

        private final boolean caseSensitive

      • illegalFileNameChars

        private final int[] illegalFileNameChars

      • maxFileNameLength

        private final int maxFileNameLength

      • maxPathLength

        private final int maxPathLength

      • reservedFileNames

        private final java.lang.String[] reservedFileNames

      • reservedFileNamesExtensions

        private final boolean reservedFileNamesExtensions

      • supportsDriveLetter

        private final boolean supportsDriveLetter

      • nameSeparator

        private final char nameSeparator

      • nameSeparatorOther

        private final char nameSeparatorOther

    • Constructor Detail

      • FileSystem

        private FileSystem​(int blockSize,
                   boolean caseSensitive,
                   boolean casePreserving,
                   int maxFileLength,
                   int maxPathLength,
                   int[] illegalFileNameChars,
                   java.lang.String[] reservedFileNames,
                   boolean reservedFileNamesExtensions,
                   boolean supportsDriveLetter,
                   char nameSeparator,
                   FileSystem.NameLengthStrategy nameLengthStrategy)
        Constructs a new instance.
        Parameters:
        blockSize - file allocation block size in bytes.
        caseSensitive - Whether this file system is case-sensitive.
        casePreserving - Whether this file system is case-preserving.
        maxFileLength - The maximum length for file names. The file name does not include folders.
        maxPathLength - The maximum length of the path to a file. This can include folders.
        illegalFileNameChars - Illegal characters for this file system.
        reservedFileNames - The reserved file names.
        reservedFileNamesExtensions - The reserved file name extensions.
        supportsDriveLetter - Whether this file system support driver letters.
        nameSeparator - The name separator, '\\' on Windows, '/' on Linux.
        nameLengthStrategy - The strategy for measuring and truncating file and path names.

    • Method Detail

      • values

        public static FileSystem[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows: 
        for (FileSystem c : FileSystem.values())
    System.out.println(c);
        Returns:
        an array containing the constants of this enum type, in the order they are declared

      • valueOf

        public static FileSystem valueOf​(java.lang.String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.NullPointerException - if the argument is null

      • current

        private static FileSystem current()
        Gets the current file system.
        Returns:
        the current file system.

      • getCurrent

        public static FileSystem getCurrent()
        Gets the current file system.
        Returns:
        the current file system.

      • getOsMatchesName

        private static boolean getOsMatchesName​(java.lang.String osNamePrefix)
        Decides if the operating system matches.
        Parameters:
        osNamePrefix - the prefix for the operating system name.
        Returns:
        true if matches, or false if not or can't determine.

      • getSystemProperty

        private static java.lang.String getSystemProperty​(java.lang.String property)
        Gets a System property, defaulting to null if the property cannot be read.

        If a SecurityException is caught, the return value is null and a message is written to System.err.

        Parameters:
        property - the system property name.
        Returns:
        the system property value or null if a security problem occurs.

      • indexOfFirstDot

        private static int indexOfFirstDot​(java.lang.CharSequence cs)

      • isOsNameMatch

        private static boolean isOsNameMatch​(java.lang.String osName,
                                     java.lang.String osNamePrefix)
        Decides if the operating system matches.

        This method is package private instead of private to support unit test invocation.

        Parameters:
        osName - the actual OS name.
        osNamePrefix - the prefix for the expected OS name.
        Returns:
        true if matches, or false if not or can't determine.

      • replace

        private static java.lang.String replace​(java.lang.String path,
                                        char oldChar,
                                        char newChar)
        Null-safe replace.
        Parameters:
        path - the path to be changed, null ignored.
        oldChar - the old character.
        newChar - the new character.
        Returns:
        the new path.

      • safeTruncate

        private static java.lang.CharSequence safeTruncate​(java.lang.CharSequence value,
                                                   int limit)
        Truncates a string respecting grapheme cluster boundaries.
        Parameters:
        value - The value to truncate.
        limit - The maximum length.
        Returns:
        The truncated value.
        Throws:
        java.lang.IllegalArgumentException - If the first grapheme cluster is longer than the limit.

      • splitExtension

        static java.lang.CharSequence[] splitExtension​(java.lang.CharSequence value)

      • trimExtension

        static java.lang.CharSequence trimExtension​(java.lang.CharSequence cs)

      • getBlockSize

        public int getBlockSize()
        Gets the file allocation block size in bytes.
        Returns:
        the file allocation block size in bytes.
        Since:
        2.12.0

      • getIllegalFileNameChars

        public char[] getIllegalFileNameChars()
        Gets a cloned copy of the illegal characters for this file system.
        Returns:
        the illegal characters for this file system.

      • getIllegalFileNameCodePoints

        public int[] getIllegalFileNameCodePoints()
        Gets a cloned copy of the illegal code points for this file system.
        Returns:
        the illegal code points for this file system.
        Since:
        2.12.0

      • getMaxFileNameLength

        public int getMaxFileNameLength()
        Gets the maximum length for file names (excluding any folder path).

        This limit applies only to the file name itself, excluding any parent directories.

        The value is expressed in Java char units (UTF-16 code units).

        Note: Because many file systems enforce limits in bytes using a specific encoding rather than in UTF-16 code units, a name that fits this limit may still be rejected by the underlying file system.

        Use isLegalFileName(java.lang.CharSequence) to check whether a given name is valid for the current file system and charset.

        However, any file name longer than this limit is guaranteed to be invalid on the current file system.

        Returns:
        the maximum file name length in characters.

      • getMaxPathLength

        public int getMaxPathLength()
        Gets the maximum length for file paths (may include folders).

        This value is inclusive of all path components and separators. For a limit of each path component see getMaxFileNameLength().

        The value is expressed in Java char units (UTF-16 code units) and represents the longest path that can be safely passed to Java File and Path APIs.

        Note: many operating systems and file systems enforce path length limits in bytes using a specific encoding, rather than in UTF-16 code units. As a result, a path that fits within this limit may still be rejected by the underlying platform.

        Conversely, any path longer than this limit is guaranteed to fail with at least some operating system API calls.

        Returns:
        the maximum file path length in characters.

      • getNameSeparator

        public char getNameSeparator()
        Gets the name separator, '\\' on Windows, '/' on Linux.
        Returns:
        '\\' on Windows, '/' on Linux.
        Since:
        2.12.0

      • getReservedFileNames

        public java.lang.String[] getReservedFileNames()
        Gets a cloned copy of the reserved file names.
        Returns:
        the reserved file names.

      • isCasePreserving

        public boolean isCasePreserving()
        Tests whether this file system preserves case.
        Returns:
        Whether this file system preserves case.

      • isCaseSensitive

        public boolean isCaseSensitive()
        Tests whether this file system is case-sensitive.
        Returns:
        Whether this file system is case-sensitive.

      • isIllegalFileNameChar

        private boolean isIllegalFileNameChar​(int c)
        Tests if the given character is illegal in a file name, false otherwise.
        Parameters:
        c - the character to test.
        Returns:
        true if the given character is illegal in a file name, false otherwise.

      • isLegalFileName

        public boolean isLegalFileName​(java.lang.CharSequence candidate)
        Tests if a candidate file name (without a path) is a legal file name.

        Takes a file name like "filename.ext" or "filename" and checks:

        • if the file name length is legal
        • if the file name is not a reserved file name
        • if the file name does not contain illegal characters
        Parameters:
        candidate - A candidate file name (without a path) like "filename.ext" or "filename".
        Returns:
        true if the candidate name is legal.

      • isLegalFileName

        public boolean isLegalFileName​(java.lang.CharSequence candidate,
                               java.nio.charset.Charset charset)
        Tests if a candidate file name (without a path) is a legal file name.

        Takes a file name like "filename.ext" or "filename" and checks:

        • if the file name length is legal
        • if the file name is not a reserved file name
        • if the file name does not contain illegal characters
        Parameters:
        candidate - A candidate file name (without a path) like "filename.ext" or "filename".
        charset - The charset to use when the file name length is measured in bytes.
        Returns:
        true if the candidate name is legal.
        Since:
        2.21.0

      • isReservedFileName

        public boolean isReservedFileName​(java.lang.CharSequence candidate)
        Tests whether the given string is a reserved file name.
        Parameters:
        candidate - the string to test.
        Returns:
        true if the given string is a reserved file name.

      • normalizeSeparators

        public java.lang.String normalizeSeparators​(java.lang.String path)
        Converts all separators to the Windows separator of backslash.
        Parameters:
        path - the path to be changed, null ignored.
        Returns:
        the updated path.
        Since:
        2.12.0

      • supportsDriveLetter

        public boolean supportsDriveLetter()
        Tests whether this file system support driver letters.

        Windows supports driver letters as do other operating systems. Whether these other OS's still support Java like OS/2, is a different matter.

        Returns:
        whether this file system support driver letters.
        Since:
        2.9.0
        See Also:
        Operating systems that use drive letter assignment

      • toLegalFileName

        public java.lang.String toLegalFileName​(java.lang.CharSequence candidate,
                                        char replacement,
                                        java.nio.charset.Charset charset)
        Converts a candidate file name (without a path) to a legal file name.

        Takes a file name like "filename.ext" or "filename" and:

        • replaces illegal characters by the given replacement character
        • truncates the name to getMaxFileNameLength() if necessary
        Parameters:
        candidate - A candidate file name (without a path) like "filename.ext" or "filename".
        replacement - Illegal characters in the candidate name are replaced by this character.
        charset - The charset to use when the file name length is measured in bytes.
        Returns:
        a String without illegal characters.
        Since:
        2.21.0

      • toLegalFileName

        public java.lang.String toLegalFileName​(java.lang.String candidate,
                                        char replacement)
        Converts a candidate file name (without a path) to a legal file name.

        Takes a file name like "filename.ext" or "filename" and:

        • replaces illegal characters by the given replacement character
        • truncates the name to getMaxFileNameLength() if necessary
        Parameters:
        candidate - A candidate file name (without a path) like "filename.ext" or "filename".
        replacement - Illegal characters in the candidate name are replaced by this character.
        Returns:
        a String without illegal characters.