FilenameHelper (phloc-commons 4.3.3 API)

java.lang.Object
- com.phloc.commons.io.file.FilenameHelper

```
@Immutable
public final class FilenameHelper
extends Object
```
All kind of file name handling stuff. This class gives you platform independent file name handling.

Author:

Philip Helger

Field Summary

Fields
Modifier and Type	Field and Description
`static char`	`EXTENSION_SEPARATOR` The file extension separation character.
`static char`	`HIDDEN_FILE_PREFIX` The prefix used for Unix hidden files
`static char`	`ILLEGAL_FILENAME_CHAR_REPLACEMENT` The replacement character used for illegal file name characters.
`static String`	`PATH_CURRENT` Special name of the current path
`static String`	`PATH_PARENT` Special name of the parent path
`static char`	`UNIX_SEPARATOR` The Unix path separator character.
`static String`	`UNIX_SEPARATOR_STR` The Unix path separator string.
`static char`	`WINDOWS_SEPARATOR` The Windows separator character.

Method Summary

Methods
Modifier and Type	Method and Description
`static boolean`	`containsPathSeparatorChar(String s)`
`static boolean`	`endsWithPathSeparatorChar(CharSequence s)` Check if the passed character sequence ends with a path separation character.
`static String`	`ensurePathEndingWithoutSeparator(String sPath)` Ensure that the passed path does NOT end with a directory separator character.
`static String`	`ensurePathEndingWithSeparator(String sPath)` Ensure that the passed path ends with a directory separator character.
`static String`	`ensurePathStartingWithSeparator(String sPath)` Ensure that the passed path starts with a directory separator character.
`static String`	`getAbsoluteWithEnsuredParentDirectory(File aParentDirectory, String sFilePath)` Get a concatenated absolute path consisting of the parent directory and the file path.
`static String`	`getAsSecureValidASCIIFilename(String sFilename)` Replace all non-ASCII characters from the filename (e.g.
`static String`	`getAsSecureValidFilename(String sFilename)` Convert the passed filename into a valid filename by performing the following actions: Remove everything after a potential \0 character Remove all characters that are invalid at the end of a file name Replace all characters that are invalid inside a filename with a underscore If the filename is invalid on Windows platforms it is prefixed with an underscore.
`static String`	`getBaseName(File aFile)` Get the passed filename without path and without extension.
`static String`	`getBaseName(String sAbsoluteFilename)` Get the passed filename without path and without extension.
`static String`	`getCleanConcatenatedUrlPath(String sURL, String sPath)` Concatenate a base URL and a sub path incl. the path cleansing.
`static String`	`getCleanPath(File aFile)` Get a clean path of the passed file resolving all "." and ".." paths.
`static String`	`getCleanPath(String sPath)` Clean the path by removing all ".." and "." path elements.
`static String`	`getExtension(File aFile)` Get the extension of the passed file.
`static String`	`getExtension(String sFilename)` Get the extension of the passed filename.
`static int`	`getIndexOfExtension(String sFilename)` Returns the index of the last extension separator character, which is a dot.
`static int`	`getIndexOfLastSeparator(String sFilename)` Returns the index of the last directory separator character.
`static String`	`getPath(String sAbsoluteFilename)` Get the path of the passed file name without any eventually contained filename.
`static String`	`getPathUsingUnixSeparator(File aFile)` Ensure that the path (not the absolute path!)
`static String`	`getPathUsingUnixSeparator(String sAbsoluteFilename)` Ensure that the passed path is using the Unix style separator "/" instead of the Operating System dependent one.
`static String`	`getRelativeToParentDirectory(File aFile, File aParentDirectory)` Tries to express the passed file path relative to the passed parent directory.
`static String`	`getSecureFilename(String sFilename)` Avoid 0 byte attack.
`static String`	`getWithoutExtension(File aFile)` Get the name of the passed file without the extension.
`static String`	`getWithoutExtension(String sFilename)` Get the passed filename without the extension.
`static String`	`getWithoutPath(File aFile)` Get the name of the passed file without any eventually leading path.
`static String`	`getWithoutPath(String sAbsoluteFilename)` Get the name of the passed file without any eventually leading path.
`static boolean`	`hasExtension(File aFile, String... aExtensions)` Check if the passed file has one of the passed extensions.
`static boolean`	`hasExtension(String sFilename, String... aExtensions)` Check if the passed filename has one of the passed extensions.
`static boolean`	`isEqualIgnoreFileSeparator(String sAbsoluteFilename1, String sAbsoluteFilename2)` Check whether the two passed file names are equal, independent of the used separators (/ or \).
`static boolean`	`isHiddenFilename(File aFile)` Check if the passed filename is a Unix hidden filename.
`static boolean`	`isHiddenFilename(String sFilename)` Check if the passed filename is a Unix hidden filename.
`static boolean`	`isPathSeparatorChar(char c)` Check if the passed character is a path separation character.
`static boolean`	`isSecureFilenameCharacter(char c)` Check if the passed character is secure to be used in filenames.
`static boolean`	`isSystemInternalDirectory(CharSequence s)` Check if the passed string is a system directory.
`static boolean`	`isSystemInternalDirectory(File aFile)`
`static boolean`	`isValidFilename(String sFilename)` Check if the passed file name is valid.
`static boolean`	`isValidFilenameWithPaths(String sFilename)` Check if the passed filename path is valid.
`static boolean`	`startsWithPathSeparatorChar(CharSequence s)` Check if the passed character sequence starts with a path separation character.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - EXTENSION_SEPARATOR
```
public static final char EXTENSION_SEPARATOR
```
    The file extension separation character.
    
    See Also:
    Constant Field Values
  - ILLEGAL_FILENAME_CHAR_REPLACEMENT
```
public static final char ILLEGAL_FILENAME_CHAR_REPLACEMENT
```
    The replacement character used for illegal file name characters.
    
    See Also:
    Constant Field Values
  - PATH_CURRENT
```
public static final String PATH_CURRENT
```
    Special name of the current path
    
    See Also:
    Constant Field Values
  - PATH_PARENT
```
public static final String PATH_PARENT
```
    Special name of the parent path
    
    See Also:
    Constant Field Values
  - UNIX_SEPARATOR
```
public static final char UNIX_SEPARATOR
```
    The Unix path separator character.
    
    See Also:
    Constant Field Values
  - UNIX_SEPARATOR_STR
```
public static final String UNIX_SEPARATOR_STR
```
    The Unix path separator string.
  - WINDOWS_SEPARATOR
```
public static final char WINDOWS_SEPARATOR
```
    The Windows separator character.
    
    See Also:
    Constant Field Values
  - HIDDEN_FILE_PREFIX
```
public static final char HIDDEN_FILE_PREFIX
```
    The prefix used for Unix hidden files
    
    See Also:
    Constant Field Values
- Method Detail
  - getIndexOfExtension
```
public static int getIndexOfExtension(@Nullable
                      String sFilename)
```
    Returns the index of the last extension separator character, which is a dot.
    This method also checks that there is no directory separator after the last dot. To do this it uses getIndexOfLastSeparator(String) which will handle a file in either Unix or Windows format.
    The output will be the same irrespective of the machine that the code is running on.
    
    Parameters:
    sFilename - The filename to find the last path separator in. May be null.
    
    Returns:
    the index of the last separator character, or CGlobal.ILLEGAL_UINT if there is no such character or the input parameter is null.
  - getWithoutExtension
```
@Nullable
public static String getWithoutExtension(@Nullable
                                  File aFile)
```
    Get the name of the passed file without the extension. If the file name contains a leading absolute path, the path is returned as well.
    
    Parameters:
    aFile - The file to extract the extension from. May be null.
    
    Returns:
    An empty string if no extension was found, the extension without the leading dot otherwise. If the input file is null the return value is null.
  - getWithoutExtension
```
@Nullable
public static String getWithoutExtension(@Nullable
                                  String sFilename)
```
    Get the passed filename without the extension. If the file name contains a leading absolute path, the path is returned as well.
    
    Parameters:
    sFilename - The filename to extract the extension from. May be null or empty.
    
    Returns:
    An empty string if no extension was found, the extension without the leading dot otherwise. If the input string is null the return value is null.
  - getExtension
```
@Nonnull
public static String getExtension(@Nullable
                          File aFile)
```
    Get the extension of the passed file.
    
    Parameters:
    aFile - The file to extract the extension from. May be null.
    
    Returns:
    An empty string if no extension was found, the extension without the leading dot otherwise. Never null.
  - getExtension
```
@Nonnull
public static String getExtension(@Nullable
                          String sFilename)
```
    Get the extension of the passed filename.
    
    Parameters:
    sFilename - The filename to extract the extension from. May be null or empty.
    
    Returns:
    An empty string if no extension was found, the extension without the leading dot otherwise. Never null.
  - hasExtension
```
public static boolean hasExtension(@Nullable
                   File aFile,
                   @Nonnull
                   String... aExtensions)
```
    Check if the passed file has one of the passed extensions. The comparison is done case insensitive even on Unix machines.
    
    Parameters:
    aFile - The file to check the extension from. May be null or empty.
    aExtensions - An array of extensions (without the leading dot) which are matched case insensitive. May not be null.
    
    Returns:
    true if the file has one of the passed extensions, else false.
  - hasExtension
```
public static boolean hasExtension(@Nullable
                   String sFilename,
                   @Nonnull
                   String... aExtensions)
```
    Check if the passed filename has one of the passed extensions. The comparison is done case insensitive even on Unix machines.
    
    Parameters:
    sFilename - The filename to check the extension from. May be null or empty.
    aExtensions - An array of extensions (without the leading dot) which are matched case insensitive. May not be null.
    
    Returns:
    true if the filename has one of the passed extensions, else false.
  - getIndexOfLastSeparator
```
public static int getIndexOfLastSeparator(@Nullable
                          String sFilename)
```
    Returns the index of the last directory separator character. This method will handle a file in either Unix or Windows format. The position of the last forward or backslash is returned. The output will be the same irrespective of the machine that the code is running on.
    
    Parameters:
    sFilename - The filename to find the last path separator in, null returns CGlobal.ILLEGAL_UINT.
    
    Returns:
    The index of the last separator character, or CGlobal.ILLEGAL_UINT if there is no such character
  - getWithoutPath
```
@Nullable
public static String getWithoutPath(@Nullable
                             File aFile)
```
    Get the name of the passed file without any eventually leading path. Note: if the passed file is a directory, the name of the directory is returned.
    
    Parameters:
    aFile - The file. May be null.
    
    Returns:
    The name only or null if the passed parameter is null.
  - getWithoutPath
```
@Nullable
public static String getWithoutPath(@Nullable
                             String sAbsoluteFilename)
```
    Get the name of the passed file without any eventually leading path.
    
    Parameters:
    sAbsoluteFilename - The fully qualified file name. May be null.
    
    Returns:
    The name only or null if the passed parameter is null.
  - getPath
```
@Nullable
public static String getPath(@Nullable
                      String sAbsoluteFilename)
```
    Get the path of the passed file name without any eventually contained filename.
    
    Parameters:
    sAbsoluteFilename - The fully qualified file name. May be null.
    
    Returns:
    The path only including the last trailing path separator character. Returns null if the passed parameter is null.
  - getBaseName
```
@Nullable
public static String getBaseName(@Nullable
                          File aFile)
```
    Get the passed filename without path and without extension.
    Example: /dir1/dir2/file.txt becomes file
    
    Parameters:
    aFile - The file to get the base name from. May be null.
    
    Returns:
    The base name of the passed parameter. May be null if the parameter was null.
  - getBaseName
```
@Nullable
public static String getBaseName(@Nullable
                          String sAbsoluteFilename)
```
    Get the passed filename without path and without extension.
    Example: /dir1/dir2/file.txt becomes file
    
    Parameters:
    sAbsoluteFilename - The filename to get the base name from. May be null.
    
    Returns:
    The base name of the passed parameter. May be null if the parameter was null.
  - getPathUsingUnixSeparator
```
@Nullable
public static String getPathUsingUnixSeparator(@Nullable
                                        File aFile)
```
    Ensure that the path (not the absolute path!) of the passed file is using the Unix style separator "/" instead of the Operating System dependent one.
    
    Parameters:
    aFile - The file to use. May be null
    
    Returns:
    null if the passed file is null.
  - getPathUsingUnixSeparator
```
@Nullable
public static String getPathUsingUnixSeparator(@Nullable
                                        String sAbsoluteFilename)
```
    Ensure that the passed path is using the Unix style separator "/" instead of the Operating System dependent one.
    
    Parameters:
    sAbsoluteFilename - The file name to use. May be null
    
    Returns:
    null if the passed path is null.
  - isEqualIgnoreFileSeparator
```
public static boolean isEqualIgnoreFileSeparator(@Nullable
                                 String sAbsoluteFilename1,
                                 @Nullable
                                 String sAbsoluteFilename2)
```
    Check whether the two passed file names are equal, independent of the used separators (/ or \).
    
    Parameters:
    sAbsoluteFilename1 - First file name. May be null.
    sAbsoluteFilename2 - Second file name. May be null.
    
    Returns:
    true if they are equal, false otherwise.
  - getSecureFilename
```
@Nullable
public static String getSecureFilename(@Nullable
                                String sFilename)
```
    Avoid 0 byte attack. E.g. file name "test.java.txt" is internally represented as "test.java" but ends with ".txt".
    Note: the passed file name is NOT decoded (e.g. %20 stays %20 and will not be converted to a space).
    
    Parameters:
    sFilename - The file name to check. May be null.
    
    Returns:
    null if the input string is null or everything up to the 0-byte.
  - isValidFilename
```
public static boolean isValidFilename(@Nullable
                      String sFilename)
```
    Check if the passed file name is valid. It checks for illegal prefixes that affects compatibility to Windows, illegal characters within a filename and forbidden suffixes. This method fits only for filenames on one level. If you want to check a full path, use isValidFilenameWithPaths(String).
    
    Parameters:
    sFilename - The filename to check. May be null.
    
    Returns:
    false if the passed filename is null or empty or invalid. true if the filename is not empty and valid.
  - isValidFilenameWithPaths
```
public static boolean isValidFilenameWithPaths(@Nullable
                               String sFilename)
```
    Check if the passed filename path is valid. In contrast to isValidFilename(String) this method can also handle filenames incl. paths.
    
    Parameters:
    sFilename - The filename to be checked for validity.
    
    Returns:
    true if all path elements of the filename are valid, false if at least one element is invalid
  - getAsSecureValidFilename
```
@Nullable
@Nonempty
public static String getAsSecureValidFilename(@Nullable
                                                String sFilename)
```
    Convert the passed filename into a valid filename by performing the following actions:
    1. Remove everything after a potential \0 character
    2. Remove all characters that are invalid at the end of a file name
    3. Replace all characters that are invalid inside a filename with a underscore
    4. If the filename is invalid on Windows platforms it is prefixed with an underscore.
    Parameters:
    sFilename - The filename to be made value. May be null.
    
    Returns:
    null if the input filename was null or if it consisted only of characters invalid for a filename; the potentially modified filename otherwise but never an empy string.
  - isSecureFilenameCharacter
```
public static boolean isSecureFilenameCharacter(char c)
```
    Check if the passed character is secure to be used in filenames. Therefore it must be ≥ 0x20 and < 0x80.
    
    Parameters:
    c - The character to check
    
    Returns:
    true if it is valid, false if not
  - getAsSecureValidASCIIFilename
```
@Nullable
@Nonempty
public static String getAsSecureValidASCIIFilename(@Nullable
                                                     String sFilename)
```
    Replace all non-ASCII characters from the filename (e.g. German Umlauts) with underscores. Before replacing non-ASCII characters the filename is made valid using getAsSecureValidFilename(String).
    
    Parameters:
    sFilename - Input file name. May not be null.
    
    Returns:
    null if the input filename was null. The file name containing only ASCII characters. The returned value is never an empty String.
  - isPathSeparatorChar
```
public static boolean isPathSeparatorChar(char c)
```
    Check if the passed character is a path separation character. This method handles both Windows- and Unix-style path separation characters.
    
    Parameters:
    c - The character to check.
    
    Returns:
    true if the character is a path separation character, false otherwise.
  - startsWithPathSeparatorChar
```
public static boolean startsWithPathSeparatorChar(@Nullable
                                  CharSequence s)
```
    Check if the passed character sequence starts with a path separation character.
    
    Parameters:
    s - The character sequence to check. May be null or empty.
    
    Returns:
    true if the character sequences starts with a Windows- or Unix-style path character.
  - endsWithPathSeparatorChar
```
public static boolean endsWithPathSeparatorChar(@Nullable
                                CharSequence s)
```
    Check if the passed character sequence ends with a path separation character.
    
    Parameters:
    s - The character sequence to check. May be null or empty.
    
    Returns:
    true if the character sequences ends with a Windows- or Unix-style path character.
  - containsPathSeparatorChar
```
public static boolean containsPathSeparatorChar(@Nullable
                                String s)
```
  - isSystemInternalDirectory
```
public static boolean isSystemInternalDirectory(@Nullable
                                File aFile)
```
  - isSystemInternalDirectory
```
public static boolean isSystemInternalDirectory(@Nullable
                                CharSequence s)
```
    Check if the passed string is a system directory. A system directory is either "." or "..".
    
    Parameters:
    s - The value to be checked. May be null.
    
    Returns:
    true if the passed string matches any of the special directory names, false of the passed string is null or does not denote a special directory.
  - getCleanPath
```
@Nonnull
public static String getCleanPath(@Nonnull
                          File aFile)
```
    Get a clean path of the passed file resolving all "." and ".." paths.
    Note: in case File.getCanonicalPath() fails, getCleanPath(String) is used as a fallback.
    Note 2: no cleansing operations beside "." and ".." are returned. You need to ensure yourself, that the returned file name is valid!
    
    Parameters:
    aFile - The file to be cleaned. May not be null.
    
    Returns:
    The cleaned path and never null.
  - getCleanPath
```
@Nullable
public static String getCleanPath(@Nullable
                           String sPath)
```
    Clean the path by removing all ".." and "." path elements.
    
    Parameters:
    sPath - The path to be cleaned.
    
    Returns:
    The cleaned path or null if the input parameter was null.
  - getCleanConcatenatedUrlPath
```
@Nonnull
public static String getCleanConcatenatedUrlPath(@Nonnull
                                         String sURL,
                                         @Nonnull
                                         String sPath)
```
    Concatenate a base URL and a sub path incl. the path cleansing. More or less the same as calling getCleanPath (sURL + sPath)
    
    Parameters:
    sURL - The base URL. May not be null.
    sPath - The path to append. May not be null.
    
    Returns:
    The combined, cleaned path.
    See Also:
    getCleanPath(String)
  - ensurePathStartingWithSeparator
```
@Nullable
@CheckReturnValue
public static String ensurePathStartingWithSeparator(@Nullable
                                                               String sPath)
```
    Ensure that the passed path starts with a directory separator character. If the passed path starts with either 92 or 47 no changes are performed.
    
    Parameters:
    sPath - The path to be checked.
    
    Returns:
    The path that is ensured to start with the directory separator of the current operating system.
  - ensurePathEndingWithoutSeparator
```
@Nullable
@CheckReturnValue
public static String ensurePathEndingWithoutSeparator(@Nullable
                                                                String sPath)
```
    Ensure that the passed path does NOT end with a directory separator character. Any number of trailing 92 or 47 are removed.
    
    Parameters:
    sPath - The path to be checked.
    
    Returns:
    The path that is ensured to NOT end with the directory separator.
  - ensurePathEndingWithSeparator
```
@Nullable
@CheckReturnValue
public static String ensurePathEndingWithSeparator(@Nullable
                                                             String sPath)
```
    Ensure that the passed path ends with a directory separator character. If the passed path ends with either 92 or 47 no changes are performed.
    
    Parameters:
    sPath - The path to be checked.
    
    Returns:
    The path that is ensured to end with the directory separator of the current operating system.
  - getRelativeToParentDirectory
```
@Nullable
public static String getRelativeToParentDirectory(@Nonnull
                                           File aFile,
                                           @Nullable
                                           File aParentDirectory)
```
    Tries to express the passed file path relative to the passed parent directory. If the parent directory is null or not actually a parent of the passed file, the passed file name will be returned unchanged.
    
    Parameters:
    aFile - The file which is to be described relatively. May not be null.
    aParentDirectory - The parent directory of the file to which the relative path expression will relate to. May be null.
    
    Returns:
    The relative path or the unchanged absolute file path using Unix path separators instead of Operating System dependent separator. Or null if the passed file contains a path traversal at the beginning
  - getAbsoluteWithEnsuredParentDirectory
```
@Nullable
public static String getAbsoluteWithEnsuredParentDirectory(@Nonnull
                                                    File aParentDirectory,
                                                    @Nonnull
                                                    String sFilePath)
```
    Get a concatenated absolute path consisting of the parent directory and the file path. It is ensured that the resulting (cleaned) filename is still the same or a child of the passed parent directory. If the file path contains some directory traversal elements (e.g. starting with "..") null is returned.
    
    Parameters:
    aParentDirectory - The parent directory to be ensured. May not be null.
    sFilePath - The file path to be appended to the passed parent directory. May not be null.
    
    Returns:
    null if the parent directory would be changed with the passed file path - the concatenated cleaned path otherwise (using Unix separators).
  - isHiddenFilename
```
public static boolean isHiddenFilename(@Nullable
                       String sFilename)
```
    Check if the passed filename is a Unix hidden filename.
    
    Parameters:
    sFilename - The filename to check. May be null.
    
    Returns:
    true if the filename is neither null nor empty and starts with a dot.
  - isHiddenFilename
```
public static boolean isHiddenFilename(@Nullable
                       File aFile)
```
    Check if the passed filename is a Unix hidden filename.
    
    Parameters:
    aFile - The file to check. May be null.
    
    Returns:
    true if the file is not null and the name starts with a dot.

Class FilenameHelper

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EXTENSION_SEPARATOR

ILLEGAL_FILENAME_CHAR_REPLACEMENT

PATH_CURRENT

PATH_PARENT

UNIX_SEPARATOR

UNIX_SEPARATOR_STR

WINDOWS_SEPARATOR

HIDDEN_FILE_PREFIX

Method Detail

getIndexOfExtension

getWithoutExtension

getWithoutExtension

getExtension

getExtension

hasExtension

hasExtension

getIndexOfLastSeparator

getWithoutPath

getWithoutPath

getPath

getBaseName

getBaseName

getPathUsingUnixSeparator

getPathUsingUnixSeparator

isEqualIgnoreFileSeparator

getSecureFilename

isValidFilename

isValidFilenameWithPaths

getAsSecureValidFilename

isSecureFilenameCharacter

getAsSecureValidASCIIFilename

isPathSeparatorChar

startsWithPathSeparatorChar

endsWithPathSeparatorChar

containsPathSeparatorChar

isSystemInternalDirectory

isSystemInternalDirectory

getCleanPath

getCleanPath

getCleanConcatenatedUrlPath

ensurePathStartingWithSeparator

ensurePathEndingWithoutSeparator

ensurePathEndingWithSeparator

getRelativeToParentDirectory

getAbsoluteWithEnsuredParentDirectory

isHiddenFilename

isHiddenFilename