org.apache.commons.io
public class FilenameUtils extends Object
When dealing with filenames you can hit problems when moving from a Windows based development machine to a Unix based production machine. This class aims to help avoid those problems.
NOTE: You may be able to avoid using this class entirely simply by
using JDK java.io.File File
objects and the two argument constructor
java.io.File#File(java.io.File, java.lang.String) File(File,String)
.
Most methods on this class are designed to work the same on both Unix and Windows. Those that don't include 'System', 'Unix' or 'Windows' in their name.
Most methods recognise both separators (forward and back), and both sets of prefixes. See the javadoc of each method for details.
This class defines six components within a filename (example C:\dev\project\file.txt):
This class only supports Unix and Windows style names. Prefixes are matched as follows:
Windows: a\b\c.txt --> "" --> relative \a\b\c.txt --> "\" --> current drive absolute C:a\b\c.txt --> "C:" --> drive relative C:\a\b\c.txt --> "C:\" --> absolute \\server\a\b\c.txt --> "\\server\" --> UNC Unix: a/b/c.txt --> "" --> relative /a/b/c.txt --> "/" --> absolute ~/a/b/c.txt --> "~/" --> current user ~ --> "~/" --> current user (slash added) ~user/a/b/c.txt --> "~user/" --> named user ~user --> "~user/" --> named user (slash added)Both prefix styles are matched always, irrespective of the machine that you are currently running on.
Origin of code: Excalibur, Alexandria, Tomcat, Commons-Utils.
Since: Commons IO 1.1
Version: $Id: FilenameUtils.java 609870 2008-01-08 04:46:26Z niallp $
Field Summary | |
---|---|
static char | EXTENSION_SEPARATOR
The extension separator character. |
static String | EXTENSION_SEPARATOR_STR
The extension separator String. |
static char | OTHER_SEPARATOR
The separator character that is the opposite of the system separator. |
static char | SYSTEM_SEPARATOR
The system separator character. |
static char | UNIX_SEPARATOR
The Unix separator character. |
static char | WINDOWS_SEPARATOR
The Windows separator character. |
Constructor Summary | |
---|---|
FilenameUtils()
Instances should NOT be constructed in standard programming. |
Method Summary | |
---|---|
static String | concat(String basePath, String fullFilenameToAdd)
Concatenates a filename to a base path using normal command line style rules.
|
static String | doGetFullPath(String filename, boolean includeSeparator)
Does the work of getting the path.
|
static String | doGetPath(String filename, int separatorAdd)
Does the work of getting the path.
|
static String | doNormalize(String filename, boolean keepSeparator)
Internal method to perform the normalization.
|
static boolean | equals(String filename1, String filename2)
Checks whether two filenames are equal exactly.
|
static boolean | equals(String filename1, String filename2, boolean normalized, IOCase caseSensitivity)
Checks whether two filenames are equal, optionally normalizing and providing
control over the case-sensitivity.
|
static boolean | equalsNormalized(String filename1, String filename2)
Checks whether two filenames are equal after both have been normalized.
|
static boolean | equalsNormalizedOnSystem(String filename1, String filename2)
Checks whether two filenames are equal after both have been normalized
and using the case rules of the system.
|
static boolean | equalsOnSystem(String filename1, String filename2)
Checks whether two filenames are equal using the case rules of the system.
|
static String | getBaseName(String filename)
Gets the base name, minus the full path and extension, from a full filename.
|
static String | getExtension(String filename)
Gets the extension of a filename.
|
static String | getFullPath(String filename)
Gets the full path from a full filename, which is the prefix + path.
|
static String | getFullPathNoEndSeparator(String filename)
Gets the full path from a full filename, which is the prefix + path,
and also excluding the final directory separator.
|
static String | getName(String filename)
Gets the name minus the path from a full filename.
|
static String | getPath(String filename)
Gets the path from a full filename, which excludes the prefix.
|
static String | getPathNoEndSeparator(String filename)
Gets the path from a full filename, which excludes the prefix, and
also excluding the final directory separator.
|
static String | getPrefix(String filename)
Gets the prefix from a full filename, such as C:/
or ~/ .
|
static int | getPrefixLength(String filename)
Returns the length of the filename prefix, such as C:/ or ~/ .
|
static int | indexOfExtension(String filename)
Returns the index of the last extension separator character, which is a dot.
|
static int | indexOfLastSeparator(String filename)
Returns the index of the last directory separator character.
|
static boolean | isExtension(String filename, String extension)
Checks whether the extension of the filename is that specified.
|
static boolean | isExtension(String filename, String[] extensions)
Checks whether the extension of the filename is one of those specified.
|
static boolean | isExtension(String filename, Collection extensions)
Checks whether the extension of the filename is one of those specified.
|
static boolean | isSeparator(char ch)
Checks if the character is a separator.
|
static boolean | isSystemWindows()
Determines if Windows file system is in use.
|
static String | normalize(String filename)
Normalizes a path, removing double and single dot path steps.
|
static String | normalizeNoEndSeparator(String filename)
Normalizes a path, removing double and single dot path steps,
and removing any final directory separator.
|
static String | removeExtension(String filename)
Removes the extension from a filename.
|
static String | separatorsToSystem(String path)
Converts all separators to the system separator.
|
static String | separatorsToUnix(String path)
Converts all separators to the Unix separator of forward slash.
|
static String | separatorsToWindows(String path)
Converts all separators to the Windows separator of backslash.
|
static String[] | splitOnTokens(String text)
Splits a string into a number of tokens.
|
static boolean | wildcardMatch(String filename, String wildcardMatcher)
Checks a filename to see if it matches the specified wildcard matcher,
always testing case-sensitive.
|
static boolean | wildcardMatch(String filename, String wildcardMatcher, IOCase caseSensitivity)
Checks a filename to see if it matches the specified wildcard matcher
allowing control over case-sensitivity.
|
static boolean | wildcardMatchOnSystem(String filename, String wildcardMatcher)
Checks a filename to see if it matches the specified wildcard matcher
using the case rules of the system.
|
Since: Commons IO 1.4
Since: Commons IO 1.4
The effect is equivalent to resultant directory after changing directory to the first argument, followed by changing directory to the second argument.
The first argument is the base path, the second is the path to concatenate.
The returned path is always normalized via normalize,
thus ..
is handled.
If pathToAdd
is absolute (has an absolute prefix), then
it will be normalized and returned.
Otherwise, the paths will be joined, normalized and returned.
The output will be the same on both Unix and Windows except for the separator character.
/foo/ + bar --> /foo/bar /foo + bar --> /foo/bar /foo + /bar --> /bar /foo + C:/bar --> C:/bar /foo + C:bar --> C:bar (*) /foo/a/ + ../bar --> foo/bar /foo/ + ../../bar --> null /foo/ + /bar --> /bar /foo/.. + /bar --> /bar /foo + bar/c.txt --> /foo/bar/c.txt /foo/c.txt + bar --> /foo/c.txt/bar (!)(*) Note that the Windows relative drive prefix is unreliable when used with this method. (!) Note that the first parameter must be a path. If it ends with a name, then the name will be built into the concatenated path. If this might be a problem, use getFullPath on the base path argument.
Parameters: basePath the base path to attach to, always treated as a path fullFilenameToAdd the filename (or path) to attach to the base
Returns: the concatenated path, or null if invalid
Parameters: filename the filename includeSeparator true to include the end separator
Returns: the path
Parameters: filename the filename separatorAdd 0 to omit the end separator, 1 to return it
Returns: the path
Parameters: filename the filename keepSeparator true to keep the final separator
Returns: the normalized filename
No processing is performed on the filenames other than comparison, thus this is merely a null-safe case-sensitive equals.
Parameters: filename1 the first filename to query, may be null filename2 the second filename to query, may be null
Returns: true if the filenames are equal, null equals null
See Also: SENSITIVE
Parameters: filename1 the first filename to query, may be null filename2 the second filename to query, may be null normalized whether to normalize the filenames caseSensitivity what case sensitivity rule to use, null means case-sensitive
Returns: true if the filenames are equal, null equals null
Since: Commons IO 1.3
Both filenames are first passed to normalize. The check is then performed in a case-sensitive manner.
Parameters: filename1 the first filename to query, may be null filename2 the second filename to query, may be null
Returns: true if the filenames are equal, null equals null
See Also: SENSITIVE
Both filenames are first passed to normalize. The check is then performed case-sensitive on Unix and case-insensitive on Windows.
Parameters: filename1 the first filename to query, may be null filename2 the second filename to query, may be null
Returns: true if the filenames are equal, null equals null
See Also: SYSTEM
No processing is performed on the filenames other than comparison. The check is case-sensitive on Unix and case-insensitive on Windows.
Parameters: filename1 the first filename to query, may be null filename2 the second filename to query, may be null
Returns: true if the filenames are equal, null equals null
See Also: SYSTEM
This method will handle a file in either Unix or Windows format. The text after the last forward or backslash and before the last dot is returned.
a/b/c.txt --> c a.txt --> a a/b/c --> c a/b/c/ --> ""
The output will be the same irrespective of the machine that the code is running on.
Parameters: filename the filename to query, null returns null
Returns: the name of the file without the path, or an empty string if none exists
This method returns the textual part of the filename after the last dot. There must be no directory separator after the dot.
foo.txt --> "txt" a/b/c.jpg --> "jpg" a/b.txt/c --> "" a/b/c --> ""
The output will be the same irrespective of the machine that the code is running on.
Parameters: filename the filename to retrieve the extension of.
Returns: the extension of the file or an empty string if none exists.
This method will handle a file in either Unix or Windows format. The method is entirely text based, and returns the text before and including the last forward or backslash.
C:\a\b\c.txt --> C:\a\b\ ~/a/b/c.txt --> ~/a/b/ a.txt --> "" a/b/c --> a/b/ a/b/c/ --> a/b/c/ C: --> C: C:\ --> C:\ ~ --> ~/ ~/ --> ~/ ~user --> ~user/ ~user/ --> ~user/
The output will be the same irrespective of the machine that the code is running on.
Parameters: filename the filename to query, null returns null
Returns: the path of the file, an empty string if none exists, null if invalid
This method will handle a file in either Unix or Windows format. The method is entirely text based, and returns the text before the last forward or backslash.
C:\a\b\c.txt --> C:\a\b ~/a/b/c.txt --> ~/a/b a.txt --> "" a/b/c --> a/b a/b/c/ --> a/b/c C: --> C: C:\ --> C:\ ~ --> ~ ~/ --> ~ ~user --> ~user ~user/ --> ~user
The output will be the same irrespective of the machine that the code is running on.
Parameters: filename the filename to query, null returns null
Returns: the path of the file, an empty string if none exists, null if invalid
This method will handle a file in either Unix or Windows format. The text after the last forward or backslash is returned.
a/b/c.txt --> c.txt a.txt --> a.txt a/b/c --> c a/b/c/ --> ""
The output will be the same irrespective of the machine that the code is running on.
Parameters: filename the filename to query, null returns null
Returns: the name of the file without the path, or an empty string if none exists
This method will handle a file in either Unix or Windows format. The method is entirely text based, and returns the text before and including the last forward or backslash.
C:\a\b\c.txt --> a\b\ ~/a/b/c.txt --> a/b/ a.txt --> "" a/b/c --> a/b/ a/b/c/ --> a/b/c/
The output will be the same irrespective of the machine that the code is running on.
This method drops the prefix from the result. See getFullPath for the method that retains the prefix.
Parameters: filename the filename to query, null returns null
Returns: the path of the file, an empty string if none exists, null if invalid
This method will handle a file in either Unix or Windows format. The method is entirely text based, and returns the text before the last forward or backslash.
C:\a\b\c.txt --> a\b ~/a/b/c.txt --> a/b a.txt --> "" a/b/c --> a/b a/b/c/ --> a/b/c
The output will be the same irrespective of the machine that the code is running on.
This method drops the prefix from the result. See getFullPathNoEndSeparator for the method that retains the prefix.
Parameters: filename the filename to query, null returns null
Returns: the path of the file, an empty string if none exists, null if invalid
C:/
or ~/
.
This method will handle a file in either Unix or Windows format. The prefix includes the first slash in the full filename where applicable.
Windows: a\b\c.txt --> "" --> relative \a\b\c.txt --> "\" --> current drive absolute C:a\b\c.txt --> "C:" --> drive relative C:\a\b\c.txt --> "C:\" --> absolute \\server\a\b\c.txt --> "\\server\" --> UNC Unix: a/b/c.txt --> "" --> relative /a/b/c.txt --> "/" --> absolute ~/a/b/c.txt --> "~/" --> current user ~ --> "~/" --> current user (slash added) ~user/a/b/c.txt --> "~user/" --> named user ~user --> "~user/" --> named user (slash added)
The output will be the same irrespective of the machine that the code is running on. ie. both Unix and Windows prefixes are matched regardless.
Parameters: filename the filename to query, null returns null
Returns: the prefix of the file, null if invalid
C:/
or ~/
.
This method will handle a file in either Unix or Windows format.
The prefix length includes the first slash in the full filename if applicable. Thus, it is possible that the length returned is greater than the length of the input string.
Windows: a\b\c.txt --> "" --> relative \a\b\c.txt --> "\" --> current drive absolute C:a\b\c.txt --> "C:" --> drive relative C:\a\b\c.txt --> "C:\" --> absolute \\server\a\b\c.txt --> "\\server\" --> UNC Unix: a/b/c.txt --> "" --> relative /a/b/c.txt --> "/" --> absolute ~/a/b/c.txt --> "~/" --> current user ~ --> "~/" --> current user (slash added) ~user/a/b/c.txt --> "~user/" --> named user ~user --> "~user/" --> named user (slash added)
The output will be the same irrespective of the machine that the code is running on. ie. both Unix and Windows prefixes are matched regardless.
Parameters: filename the filename to find the prefix in, null returns -1
Returns: the length of the prefix, -1 if invalid or null
This method also checks that there is no directory separator after the last dot. To do this it uses indexOfLastSeparator 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: filename the filename to find the last path separator in, null returns -1
Returns: the index of the last separator character, or -1 if there is no such 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: filename the filename to find the last path separator in, null returns -1
Returns: the index of the last separator character, or -1 if there is no such character
This method obtains the extension as the textual part of the filename after the last dot. There must be no directory separator after the dot. The extension check is case-sensitive on all platforms.
Parameters: filename the filename to query, null returns false extension the extension to check for, null or empty checks for no extension
Returns: true if the filename has the specified extension
This method obtains the extension as the textual part of the filename after the last dot. There must be no directory separator after the dot. The extension check is case-sensitive on all platforms.
Parameters: filename the filename to query, null returns false extensions the extensions to check for, null checks for no extension
Returns: true if the filename is one of the extensions
This method obtains the extension as the textual part of the filename after the last dot. There must be no directory separator after the dot. The extension check is case-sensitive on all platforms.
Parameters: filename the filename to query, null returns false extensions the extensions to check for, null checks for no extension
Returns: true if the filename is one of the extensions
Parameters: ch the character to check
Returns: true if it is a separator character
Returns: true if the system is Windows
This method normalizes a path to a standard format. The input may contain separators in either Unix or Windows format. The output will contain separators in the format of the system.
A trailing slash will be retained.
A double slash will be merged to a single slash (but UNC names are handled).
A single dot path segment will be removed.
A double dot will cause that path segment and the one before to be removed.
If the double dot has no parent path segment to work with, null
is returned.
The output will be the same on both Unix and Windows except for the separator character.
/foo// --> /foo/ /foo/./ --> /foo/ /foo/../bar --> /bar /foo/../bar/ --> /bar/ /foo/../bar/../baz --> /baz //foo//./bar --> /foo/bar /../ --> null ../foo --> null foo/bar/.. --> foo/ foo/../../bar --> null foo/../bar --> bar //server/foo/../bar --> //server/bar //server/../bar --> null C:\foo\..\bar --> C:\bar C:\..\bar --> null ~/foo/../bar/ --> ~/bar/ ~/../bar --> null(Note the file separator returned will be correct for Windows/Unix)
Parameters: filename the filename to normalize, null returns null
Returns: the normalized filename, or null if invalid
This method normalizes a path to a standard format. The input may contain separators in either Unix or Windows format. The output will contain separators in the format of the system.
A trailing slash will be removed.
A double slash will be merged to a single slash (but UNC names are handled).
A single dot path segment will be removed.
A double dot will cause that path segment and the one before to be removed.
If the double dot has no parent path segment to work with, null
is returned.
The output will be the same on both Unix and Windows except for the separator character.
/foo// --> /foo /foo/./ --> /foo /foo/../bar --> /bar /foo/../bar/ --> /bar /foo/../bar/../baz --> /baz //foo//./bar --> /foo/bar /../ --> null ../foo --> null foo/bar/.. --> foo foo/../../bar --> null foo/../bar --> bar //server/foo/../bar --> //server/bar //server/../bar --> null C:\foo\..\bar --> C:\bar C:\..\bar --> null ~/foo/../bar/ --> ~/bar ~/../bar --> null(Note the file separator returned will be correct for Windows/Unix)
Parameters: filename the filename to normalize, null returns null
Returns: the normalized filename, or null if invalid
This method returns the textual part of the filename before the last dot. There must be no directory separator after the dot.
foo.txt --> foo a\b\c.jpg --> a\b\c a\b\c --> a\b\c a.b\c --> a.b\c
The output will be the same irrespective of the machine that the code is running on.
Parameters: filename the filename to query, null returns null
Returns: the filename minus the extension
Parameters: path the path to be changed, null ignored
Returns: the updated path
Parameters: path the path to be changed, null ignored
Returns: the updated path
Parameters: path the path to be changed, null ignored
Returns: the updated path
Parameters: text the text to split
Returns: the tokens, never null
The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-sensitive always.
wildcardMatch("c.txt", "*.txt") --> true wildcardMatch("c.txt", "*.jpg") --> false wildcardMatch("a/b/c.txt", "a/b/*") --> true wildcardMatch("c.txt", "*.???") --> true wildcardMatch("c.txt", "*.????") --> false
Parameters: filename the filename to match on wildcardMatcher the wildcard string to match against
Returns: true if the filename matches the wilcard string
See Also: SENSITIVE
The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters.
Parameters: filename the filename to match on wildcardMatcher the wildcard string to match against caseSensitivity what case sensitivity rule to use, null means case-sensitive
Returns: true if the filename matches the wilcard string
Since: Commons IO 1.3
The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-sensitive on Unix and case-insensitive on Windows.
wildcardMatch("c.txt", "*.txt") --> true wildcardMatch("c.txt", "*.jpg") --> false wildcardMatch("a/b/c.txt", "a/b/*") --> true wildcardMatch("c.txt", "*.???") --> true wildcardMatch("c.txt", "*.????") --> false
Parameters: filename the filename to match on wildcardMatcher the wildcard string to match against
Returns: true if the filename matches the wilcard string
See Also: SYSTEM