hudson.plugins.gradle_repo

Class PathUtils

java.lang.Object

hudson.plugins.gradle_repo.PathUtils

public class PathUtils
extends Object

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

Version:

$Id: PathUtils.java 1702170 2015-09-10 06:35:02Z krosenvold $

Field Summary

Fields

Modifier and Type	Field and Description
static char	EXTENSION_SEPARATOR The extension separator character.
static String	EXTENSION_SEPARATOR_STR The extension separator String.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static int	getPrefixLength(String filename) Returns the length of the filename prefix, such as C:/ or ~/.
static String	normalize(String filename) Normalizes a path, removing double and single dot path steps.
static String	normalize(String filename, boolean unixSeparator) Normalizes a path, removing double and single dot path steps.

Methods inherited from class java.lang.Object

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

Field Detail

EXTENSION_SEPARATOR

public static final char EXTENSION_SEPARATOR

The extension separator character.

Since:

1.4

See Also:

Constant Field Values

EXTENSION_SEPARATOR_STR

public static final String EXTENSION_SEPARATOR_STR

The extension separator String.

Since:

1.4

Constructor Detail

PathUtils

public PathUtils()

Instances should NOT be constructed in standard programming.

Method Detail

normalize

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. Null bytes inside string will be removed

normalize

public static String normalize(String filename,
                               boolean unixSeparator)

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

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
 

The output will be the same on both Unix and Windows including the separator character.

Parameters:

filename - the filename to normalize, null returns null

unixSeparator - true if a unix separator should be used or false if a windows separator should be used.

Returns:

the normalized filename, or null if invalid. Null bytes inside string will be removed

Since:

2.0

getPrefixLength

public static int getPrefixLength(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
 \\\a\b\c.txt        -->  error, length = -1

 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)
 //server/a/b/c.txt  --> "//server/"
 ///a/b/c.txt        --> error, length = -1
 

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.

Note that a leading // (or \\) is used to indicate a UNC name on Windows. These must be followed by a server name, so double-slashes are not collapsed to a single slash at the start of the filename.

Parameters:

filename - the filename to find the prefix in, null returns -1

Returns:

the length of the prefix, -1 if invalid or null