org.xblackcat.sjpu.utils

Class FilenameUtils

java.lang.Object

org.xblackcat.sjpu.utils.FilenameUtils

public class FilenameUtils
extends java.lang.Object

COPIED FROM apache-commons IO

General filename and filepath manipulation utilities.

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

• the prefix - C:\
• the path - dev\project\
• the full path - C:\dev\project\
• the name - file.txt
• the base name - file
• the extension - txt

Note that this class works best if directory filenames end with a separator. If you omit the last separator, it is impossible to determine if the filename corresponds to a file or a directory. As a result, we have chosen to say it corresponds to a file.

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:

1.1

Constructor Summary

Constructors

Constructor and Description
FilenameUtils() Instances should NOT be constructed in standard programming.

Method Summary

Modifier and Type	Method and Description
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 int	getPrefixLength(java.lang.String filename) Returns the length of the filename prefix, such as C:/ or ~/.
static java.lang.String	normalize(java.lang.String filename) Normalizes a path, removing double and single dot path steps.
static java.lang.String	separatorsToUnix(java.lang.String path) Converts all separators to the Unix separator of forward slash.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FilenameUtils

public FilenameUtils()

Instances should NOT be constructed in standard programming.

Method Detail

normalize

public static java.lang.String normalize(java.lang.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

concat

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

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(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 (!)
 /foo/c.txt + null    -->   /foo/c.txt (!)
 

(*) 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.

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

separatorsToUnix

public static java.lang.String separatorsToUnix(java.lang.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

getPrefixLength

public static int getPrefixLength(java.lang.String filename)

Returns the length of the filename prefix, such as 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