Package org.apache.commons.io

# Enum FileSystem

java.lang.Object
java.lang.Enum<FileSystem>
org.apache.commons.io.FileSystem

All Implemented Interfaces:
  `Serializable`, `Comparable<FileSystem>`

public enum FileSystem extends 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

- ## 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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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).
  `char`
  `getNameSeparator()`
  Gets the name separator, '\\' on Windows, '/' on Linux.
  `String[]`
  `getReservedFileNames()`
  Gets a cloned copy of the reserved file names.
  `boolean`
  `isCasePreserving()`
  Tests whether this file system preserves case.
  `boolean`
  `isCaseSensitive()`
  Tests whether this file system is case-sensitive.
  `boolean`
  `isLegalFileName(CharSequence candidate)`
  Tests if a candidate file name (without a path) is a legal file name.
  `boolean`
  `isLegalFileName(CharSequence candidate, Charset charset)`
  Tests if a candidate file name (without a path) is a legal file name.
  `boolean`
  `isReservedFileName(CharSequence candidate)`
  Tests whether the given string is a reserved file name.
  `String`
  `normalizeSeparators(String path)`
  Converts all separators to the Windows separator of backslash.
  `boolean`
  `supportsDriveLetter()`
  Tests whether this file system support driver letters.
  `String`
  `toLegalFileName(CharSequence candidate, char replacement, Charset charset)`
  Converts a candidate file name (without a path) to a legal file name.
  `String`
  `toLegalFileName(String candidate, char replacement)`
  Converts a candidate file name (without a path) to a legal file name.
  `static FileSystem`
  `valueOf(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`

- ## Enum Constant Details

  - ### GENERIC

    public static final FileSystem GENERIC
    Generic file system.

  - ### LINUX

    public static final FileSystem LINUX
    Linux file system.

  - ### MAC_OSX

    public static final FileSystem MAC_OSX
    MacOS file system.

  - ### WINDOWS

    public static final FileSystem WINDOWS
    Windows file system.

    The reserved characters are defined in the Naming Conventions (microsoft.com).

    See Also:
      - Naming Conventions (microsoft.com)
      - CreateFileA function - Consoles (microsoft.com)

- ## Method Details

  - ### values

    public static FileSystem[] values()
    Returns an array containing the constants of this enum type, in the order they are declared.
    Returns:
      an array containing the constants of this enum type, in the order they are declared

  - ### valueOf

    public static FileSystem valueOf(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:
      `IllegalArgumentException` - if this enum type has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### getCurrent

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

  - ### 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 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.

  - ### isLegalFileName

    public boolean isLegalFileName(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(CharSequence candidate, 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(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 String normalizeSeparators(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 String toLegalFileName(CharSequence candidate, char replacement, 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 String toLegalFileName(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.