Java Doc for FilenameUtils.java in  » Library » apache-common-IO » org » apache » commons » io » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.Filejava.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):

• the prefix - C:\
• the path - dev\project\
• the full path - C:\dev\project\
• the name - file.txt
• the base name - file
• the extension - 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)
 

Origin of code: Excalibur, Alexandria, Tomcat, Commons-Utils.
author:
   Kevin A. Burton
author:
   Scott Sanders
author:
   Daniel Rall
author:
   Christoph.Reck
author:
   Peter Donald
author:
   Jeff Turner
author:
   Matthew Hawthorne
author:
   Martin Cooper
author:
   Jeremias Maerki
author:
   Stephen Colebourne
version:
   $Id: FilenameUtils.java 490424 2006-12-27 01:20:43Z bayard $
since:
   Commons IO 1.1

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 FilenameUtils.normalize(String) , 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/..

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.

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.

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.

This method obtains the extension as the textual part of the filename after the last dot.

This method obtains the extension as the textual part of the filename after the last dot.

This method obtains the extension as the textual part of the filename after the last dot.

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

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

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 FilenameUtils.normalize(String) , 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 (!)
 

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
Parameters:
  filename2 - the second filename to query, may be null true if the filenames are equal, null equals null
See Also:   IOCase.SENSITIVE

Both filenames are first passed to FilenameUtils.normalize(String) . The check is then performed in a case-sensitive manner.
Parameters:
  filename1 - the first filename to query, may be null
Parameters:
  filename2 - the second filename to query, may be null true if the filenames are equal, null equals null
See Also:   IOCase.SENSITIVE

Both filenames are first passed to FilenameUtils.normalize(String) . The check is then performed case-sensitive on Unix and case-insensitive on Windows.
Parameters:
  filename1 - the first filename to query, may be null
Parameters:
  filename2 - the second filename to query, may be null true if the filenames are equal, null equals null
See Also:   IOCase.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
Parameters:
  filename2 - the second filename to query, may be null true if the filenames are equal, null equals null
See Also:   IOCase.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 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. 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 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 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 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 FilenameUtils.getFullPath(String) for the method that retains the prefix.
Parameters:
  filename - the filename to query, null returns null 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 FilenameUtils.getFullPathNoEndSeparator(String) for the method that retains the prefix.
Parameters:
  filename - the filename to query, null returns null 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 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 the prefix of the file, null if invalid

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 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 FilenameUtils.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.
Parameters:
  filename - the filename to find the last path separator in, null returns -1 the index of the last separator character, or -1 if thereis 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 the index of the last separator character, or -1 if thereis 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
Parameters:
  extension - the extension to check for, null or empty checks for no extension 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
Parameters:
  extensions - the extensions to check for, null checks for no extension 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
Parameters:
  extensions - the extensions to check for, null checks for no extension true if the filename is one of the extensions

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
 

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
 

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 the filename minus the extension

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
 

The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters.
Parameters:
  filename - the filename to match on
Parameters:
  wildcardMatcher - the wildcard string to match against
Parameters:
  caseSensitivity - what case sensitivity rule to use, null means case-sensitive 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