|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.commons.io.FilenameUtils
Utility class that provides methods to manipulate filenames and filepaths.
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.
Most methods on this class are designed to work the same on both Unix and Windows. Both separators (forward and back) are recognised, and both sets of prefixes. The comparison methods do differ by machine however, comparing case insensitive on Windows and case sensitive on Unix. 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 style: a\b\c.txt --> "" --> relative \a\b\c.txt --> "\" --> drive relative C:\a\b\c.txt --> "C:\" --> absolute \\server\a\b\c.txt --> "\\server\" --> UNC Unix style: a/b/c.txt --> "" --> relative /a/b/c.txt --> "/" --> absolute ~/a/b/c.txt --> "~/" --> current user relative ~user/a/b/c.txt --> "~user/" --> named user relativeBoth prefix styles are matched always, irrespective of the machine that you are currently running on.
Field Summary | |
private static char |
EXTENSION_SEPARATOR
The extension separator character. |
private static char |
OTHER_SEPARATOR
The separator character that is the opposite of the system separator. |
private static char |
SYSTEM_SEPARATOR
The system separator character. |
private static char |
UNIX_SEPARATOR
The Unix separator character. |
private static char |
WINDOWS_SEPARATOR
The Windows separator character. |
Constructor Summary | |
FilenameUtils()
Instances should NOT be constructed in standard programming. |
Method Summary | |
static java.lang.String |
concat(java.lang.String basePath,
java.lang.String fullFilenameToAdd)
Concatenates a filename to a base path using normal command line style rules. |
static boolean |
equals(java.lang.String filename1,
java.lang.String filename2)
Checks whether two filenames are equal using the case rules of the system. |
static boolean |
equalsNormalized(java.lang.String filename1,
java.lang.String filename2)
Checks whether two filenames are equal after both have been normalized and using the case rules of the system. |
static java.lang.String |
getBaseName(java.lang.String filename)
Gets the base name, minus the full path and extension, from a full filename. |
static java.lang.String |
getExtension(java.lang.String filename)
Gets the extension of a filename. |
static java.lang.String |
getFullPath(java.lang.String filename)
Gets the full path from a full filename, which is the prefix + path. |
static java.lang.String |
getName(java.lang.String filename)
Gets the name minus the path from a full filename. |
static java.lang.String |
getPath(java.lang.String filename)
Gets the path from a full filename, which excludes the prefix. |
static java.lang.String |
getPrefix(java.lang.String filename)
Gets the prefix from a full filename, such as C:/ or ~/ . |
static int |
getPrefixLength(java.lang.String filename)
Returns the length of the filename prefix, such as C:/ or ~/ . |
static int |
indexOfExtension(java.lang.String filename)
Returns the index of the last extension separator character, which is a dot. |
static int |
indexOfLastSeparator(java.lang.String filename)
Returns the index of the last directory separator character. |
static boolean |
isExtension(java.lang.String filename,
java.util.Collection extensions)
Checks whether the extension of the filename is one of those specified using the case rules of the system. |
static boolean |
isExtension(java.lang.String filename,
java.lang.String extension)
Checks whether the extension of the filename is that specified using the case rules of the system. |
static boolean |
isExtension(java.lang.String filename,
java.lang.String[] extensions)
Checks whether the extension of the filename is one of those specified using the case rules of the system. |
private static boolean |
isSeparator(char ch)
Checks if the character is a separator. |
static java.lang.String |
normalize(java.lang.String filename)
Normalizes a path, removing double and single dot path steps. |
static java.lang.String |
removeExtension(java.lang.String filename)
Removes the extension from a filename. |
static java.lang.String |
separatorsToSystem(java.lang.String path)
Converts all separators to the system separator. |
static java.lang.String |
separatorsToUnix(java.lang.String path)
Converts all separators to the Unix separator of forward slash. |
static java.lang.String |
separatorsToWindows(java.lang.String path)
Converts all separators to the Windows separator of backslash. |
(package private) static java.lang.String[] |
splitOnTokens(java.lang.String text)
|
static boolean |
wildcardMatch(java.lang.String filename,
java.lang.String wildcardMatcher)
Checks a filename to see if it matches the specified wildcard matcher. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
private static final char EXTENSION_SEPARATOR
private static final char UNIX_SEPARATOR
private static final char WINDOWS_SEPARATOR
private static final char SYSTEM_SEPARATOR
private static final char OTHER_SEPARATOR
Constructor Detail |
public FilenameUtils()
Method Detail |
private static boolean isSeparator(char ch)
ch
- the character to check
public static java.lang.String normalize(java.lang.String filename)
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 --> 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)
filename
- the filename to normalize, null returns null
public static java.lang.String concat(java.lang.String basePath, java.lang.String fullFilenameToAdd)
The first argument is the base path, the second is the path to concatenate.
The returned path is always normalized via normalize(String)
,
thus ..
is handled.
If pathToAdd
is absolute (has a 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/a + bar --> /foo/a/bar /foo/ + ../bar --> /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 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(String)
on the base path argument.
basePath
- the base path to attach to, always treated as a pathfullFilenameToAdd
- the filename (or path) to attach to the base
public static java.lang.String separatorsToUnix(java.lang.String path)
path
- the path to be changed, null ignored
public static java.lang.String separatorsToWindows(java.lang.String path)
path
- the path to be changed, null ignored
public static java.lang.String separatorsToSystem(java.lang.String path)
path
- the path to be changed, null ignored
public static int getPrefixLength(java.lang.String filename)
C:/
or ~/
.
This method will handle a file in either Unix or Windows format. The prefix includes the first slash in the full filename.
Windows: a\b\c.txt --> "" --> relative \a\b\c.txt --> "\" --> 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 relative ~user/a/b/c.txt --> "~user/" --> named user relative
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.
filename
- the filename to find the prefix in, null returns -1
public static int indexOfLastSeparator(java.lang.String filename)
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.
filename
- the filename to find the last path separator in, null returns -1
public static int indexOfExtension(java.lang.String filename)
This method also checks that there is no directory separator after the last dot.
To do this it uses indexOfLastSeparator(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.
filename
- the filename to find the last path separator in, null returns -1
public static java.lang.String getPrefix(java.lang.String filename)
C:/
or ~/
.
This method will handle a file in either Unix or Windows format. The prefix includes the first slash in the full filename.
Windows: a\b\c.txt --> "" --> relative \a\b\c.txt --> "\" --> 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 relative ~user/a/b/c.txt --> "~user/" --> named user relative
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.
filename
- the filename to query, null returns null
public static java.lang.String getPath(java.lang.String filename)
This method will handle a file in either Unix or Windows format. The text before the last forward or backslash is returned.
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.
filename
- the filename to query, null returns null
public static java.lang.String getFullPath(java.lang.String filename)
This method will handle a file in either Unix or Windows format. The text before the last forward or backslash is returned.
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
The output will be the same irrespective of the machine that the code is running on.
filename
- the filename to query, null returns null
public static java.lang.String getName(java.lang.String 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.
filename
- the filename to query, null returns null
public static java.lang.String getBaseName(java.lang.String 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.
filename
- the filename to query, null returns null
public static java.lang.String getExtension(java.lang.String 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.
filename
- the filename to retrieve the extension of.
public static java.lang.String removeExtension(java.lang.String 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\c
The output will be the same irrespective of the machine that the code is running on.
filename
- the filename to query, null returns null
public static boolean equals(java.lang.String filename1, java.lang.String filename2)
No processing is performed on the filenames other than comparison. The check is case sensitive on Unix and case insensitive on Windows.
filename1
- the first filename to query, may be nullfilename2
- the second filename to query, may be null
public static boolean equalsNormalized(java.lang.String filename1, java.lang.String filename2)
Both filenames are first passed to normalize(String)
.
The check is then performed case sensitive on Unix and case insensitive on Windows.
filename1
- the first filename to query, may be nullfilename2
- the second filename to query, may be null
public static boolean isExtension(java.lang.String filename, java.lang.String 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 Unix and case insensitive on Windows.
filename
- the filename to query, null returns falseextension
- the extension to check for, null or empty checks for no extension
public static boolean isExtension(java.lang.String filename, java.lang.String[] 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 Unix and case insensitive on Windows.
filename
- the filename to query, null returns falseextensions
- the extensions to check for, null checks for no extension
public static boolean isExtension(java.lang.String filename, java.util.Collection 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 Unix and case insensitive on Windows.
filename
- the filename to query, null returns falseextensions
- the extensions to check for, null checks for no extension
public static boolean wildcardMatch(java.lang.String filename, java.lang.String wildcardMatcher)
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 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
filename
- the filename to match onwildcardMatcher
- the wildcard string to match against
static java.lang.String[] splitOnTokens(java.lang.String text)
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |