Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
org.apache.commons.io.FilenameUtils
public class FilenameUtils
extends java.lang.Object
File
objects and the two argument constructor
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):
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.
Field Summary | |
private static char |
|
private static char |
|
private static char |
|
private static char |
|
private static char |
|
Constructor Summary | |
|
Method Summary | |
static String |
|
private static String |
|
private static String |
|
private static String |
|
static boolean |
|
private static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static int |
|
static int |
|
static int |
|
static boolean |
|
static boolean |
|
static boolean |
|
private static boolean |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
(package private) static String[] |
|
static boolean |
|
private static boolean |
|
static boolean |
|
private static final char EXTENSION_SEPARATOR
The extension separator character.
- Field Value:
- '.'
private static final char OTHER_SEPARATOR
The separator character that is the opposite of the system separator.
private static final char SYSTEM_SEPARATOR
The system separator character.
private static final char UNIX_SEPARATOR
The Unix separator character.
- Field Value:
- '/'
private static final char WINDOWS_SEPARATOR
The Windows separator character.
- Field Value:
- '\'
public static String concat(String basePath, String fullFilenameToAdd)
Concatenates a filename to a base path using normal command line style rules. 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 vianormalize(String)
, thus..
is handled. IfpathToAdd
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, usegetFullPath(String)
on the base path argument.
- Parameters:
basePath
- the base path to attach to, always treated as a pathfullFilenameToAdd
- the filename (or path) to attach to the base
- Returns:
- the concatenated path, or null if invalid
private static String doGetFullPath(String filename, boolean includeSeparator)
Does the work of getting the path.
- Parameters:
filename
- the filenameincludeSeparator
- true to include the end separator
- Returns:
- the path
private static String doGetPath(String filename, int separatorAdd)
Does the work of getting the path.
- Parameters:
filename
- the filenameseparatorAdd
- 0 to omit the end separator, 1 to return it
- Returns:
- the path
private static String doNormalize(String filename, boolean keepSeparator)
Internal method to perform the normalization.
- Parameters:
filename
- the filenamekeepSeparator
- true to keep the final separator
- Returns:
- the normalized filename
public static boolean equals(String filename1, String filename2)
Checks whether two filenames are equal exactly. 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 nullfilename2
- the second filename to query, may be null
- Returns:
- true if the filenames are equal, null equals null
private static boolean equals(String filename1, String filename2, boolean system, boolean normalized)
Checks whether two filenames are equal after both have been normalized and optionally using the case rules of the system. Both filenames are first passed tonormalize(String)
.
- Parameters:
filename1
- the first filename to query, may be nullfilename2
- the second filename to query, may be nullsystem
- whether to use the system (windows or unix)normalized
- whether to normalize the filenames
- Returns:
- true if the filenames are equal, null equals null
public static boolean equalsNormalized(String filename1, String filename2)
Checks whether two filenames are equal after both have been normalized. Both filenames are first passed tonormalize(String)
. The check is then performed in a case-sensitive manner.
- Parameters:
filename1
- the first filename to query, may be nullfilename2
- the second filename to query, may be null
- Returns:
- true if the filenames are equal, null equals null
public 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. Both filenames are first passed tonormalize(String)
. The check is then performed case-sensitive on Unix and case-insensitive on Windows.
- Parameters:
filename1
- the first filename to query, may be nullfilename2
- the second filename to query, may be null
- Returns:
- true if the filenames are equal, null equals null
public static boolean equalsOnSystem(String filename1, String filename2)
Checks whether two filenames are equal using the case rules of the 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 nullfilename2
- the second filename to query, may be null
- Returns:
- true if the filenames are equal, null equals null
public static String getBaseName(String filename)
Gets the base name, minus the full path and extension, from a full filename. 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
public static String getExtension(String filename)
Gets the extension of a filename. 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.
public static String getFullPath(String filename)
Gets the full path from a full filename, which is the prefix + path. 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
public 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. 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/ --> ~userThe 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
public static String getName(String filename)
Gets the name minus the path from a full filename. 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
public static String getPath(String filename)
Gets the path from a full filename, which excludes the prefix. 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. SeegetFullPath(String)
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
public static String getPathNoEndSeparator(String filename)
Gets the path from a full filename, which excludes the prefix, and also excluding the final directory separator. 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/cThe output will be the same irrespective of the machine that the code is running on. This method drops the prefix from the result. SeegetFullPathNoEndSeparator(String)
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
public static String getPrefix(String filename)
Gets the prefix from a full filename, such asC:/
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
public static int getPrefixLength(String filename)
Returns the length of the filename prefix, such asC:/
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
public static int indexOfExtension(String filename)
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 usesindexOfLastSeparator(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:
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
public static int indexOfLastSeparator(String filename)
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:
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
public static boolean isExtension(String filename, Collection extensions)
Checks whether the extension of the filename is one of those specified. 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 falseextensions
- the extensions to check for, null checks for no extension
- Returns:
- true if the filename is one of the extensions
public static boolean isExtension(String filename, String extension)
Checks whether the extension of the filename is that specified. 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 falseextension
- the extension to check for, null or empty checks for no extension
- Returns:
- true if the filename has the specified extension
public static boolean isExtension(String filename, String[] extensions)
Checks whether the extension of the filename is one of those specified. 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 falseextensions
- the extensions to check for, null checks for no extension
- Returns:
- true if the filename is one of the extensions
private static boolean isSeparator(char ch)
Checks if the character is a separator.
- Parameters:
ch
- the character to check
- Returns:
- true if it is a separator character
public static String normalize(String filename)
Normalizes a path, removing double and single dot path steps. 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
public static String normalizeNoEndSeparator(String filename)
Normalizes a path, removing double and single dot path steps, and removing any final directory separator. 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
public static String removeExtension(String filename)
Removes the extension from a filename. 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\cThe 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
public static String separatorsToSystem(String path)
Converts all separators to the system separator.
- Parameters:
path
- the path to be changed, null ignored
- Returns:
- the updated path
public static String separatorsToUnix(String path)
Converts all separators to the Unix separator of forward slash.
- Parameters:
path
- the path to be changed, null ignored
- Returns:
- the updated path
public static String separatorsToWindows(String path)
Converts all separators to the Windows separator of backslash.
- Parameters:
path
- the path to be changed, null ignored
- Returns:
- the updated path
(package private) static String[] splitOnTokens(String text)
Splits a string into a number of tokens.
- Parameters:
text
- the text to split
- Returns:
- the tokens, never null
public static boolean wildcardMatch(String filename, String wildcardMatcher)
Checks a filename to see if it matches the specified wildcard matcher, always testing case-sensitive. 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 extension check is case-sensitive.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 onwildcardMatcher
- the wildcard string to match against
- Returns:
- true if the filename matches the wilcard string
private static boolean wildcardMatch(String filename, String wildcardMatcher, boolean system)
Checks a filename to see if it matches the specified wildcard matcher. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters.
- Parameters:
filename
- the filename to match onwildcardMatcher
- the wildcard string to match againstsystem
- whether to use the system (windows or unix)
- Returns:
- true if the filename matches the wilcard string
public 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. 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 onwildcardMatcher
- the wildcard string to match against
- Returns:
- true if the filename matches the wilcard string