Class PathUtils
java.lang.Object
com.ibm.wsspi.kernel.service.utils.PathUtils
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Comparator for normalized paths. -
Field Summary
Modifier and TypeFieldDescriptionstatic final Comparator<String>
Singleton instance ofPathUtils.PathComparator
. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic String
Resolve all ".." elements of a path.static boolean
The artifact API is case sensitive even on a file system that is not case sensitive.static boolean
Tell if a path contains a symbolic substitution.fixPathFiles
(Collection<File> files) Collect the results of applyingfixPathString(File)
to a collection of files.static String
fixPathString
(File absPath) Answer the canonical path of a file.static String
fixPathString
(String absPath) Answer a canonical path for a target path usingfixPathString(File)
.static String
getChildUnder
(String path, String parentPath) Answer the first path element of a path which follows a leading sub-path.static String
getFirstPathComponent
(String path) Answer the first file name of a path, using the forward slash character ('/') as the path separator character.getFixedPathFiles
(Collection<String> paths) ApplyfixPathString(File)
to a collection of paths.static String
Answer the last file name of a path, using the forward slash ('/') as the path separator character.static String
Answer the path with the last file name removed, using forward slash ('/') as the path separator character.static String
Answer the first symbolic substitution within a path.static boolean
isNormalizedPathAbsolute
(String nPath) Tell if a path, if applied to a target location, will reach above the target location.static boolean
Tell if a path starts with a symbolic substitution.static boolean
isUnixStylePathAbsolute
(String unixStylePath) Tell if a path, if applied to a target location, will reach above the target location.static String
Normalize a path.static String
Normalize a relative path usingnormalize(String)
and verify that the normalized path does not begin with an upwards path element ("..").static String
normalizeRelative
(String relativePath) Normalize a relative path usingnormalize(String)
and verify that the normalized path is an absolute path.static String
normalizeUnixStylePath
(String path) Normalize a path, resolving as many ".." elements as possible.static boolean
pathIsAbsolute
(String normalizedPath) Tell if a normalized path is an absolute path.static String
Copy a file name, replacing each restricted character with a single period character ('.').static String
Copy the path, replacing backward slashes ('\\') with forward slashes ('/').
-
Field Details
-
PATH_COMPARATOR
Singleton instance ofPathUtils.PathComparator
.
-
-
Constructor Details
-
PathUtils
public PathUtils()
-
-
Method Details
-
slashify
Copy the path, replacing backward slashes ('\\') with forward slashes ('/').- Parameters:
path
- The path in which to replace slashes. An exception will be thrown if the path is null.- Returns:
- The path with backward slashes replaced with forward slashes. Answer the initial file path if no backward slashes are present.
-
normalizeDescendentPath
Normalize a relative path usingnormalize(String)
and verify that the normalized path does not begin with an upwards path element (".."). The path is required to be a relative path which uses forward slashes ('/'). The normalized path is tested as an absolute path according topathIsAbsolute(String)
.- Parameters:
relativePath
- The relative path which is to be normalized.- Returns:
- The normalized path. An empty path if the path was null.
- Throws:
MalformedLocationException
- Thrown if the normalized path starts with an upwards path element ("..").
-
normalizeRelative
Normalize a relative path usingnormalize(String)
and verify that the normalized path is an absolute path. Answer the normalized path. The path is required to be a relative path which uses forward slashes ('/'). The normalized path is an absolute path according to the rules implemented bypathIsAbsolute(String)
.- Parameters:
relativePath
- The relative path which is to be normalized. An exception will be thrown if the path is null.- Returns:
- The normalized path.
- Throws:
MalformedLocationException
- Thrown if the normalized path is not an absolute path.
-
pathIsAbsolute
Tell if a normalized path is an absolute path. A normalized path which starts with a forward slash character ('/') is absolute. A normalized path which starts with a symbolic substitution (seeisSymbol(String)
is absolute. A true result for paths which start with a symbolic substitution is a conservative answer: Whether the resulting path is absolute after performing symbolic substitution depends on what value was placed by the substitution. A normalized path which starts with a drive letter combination followed by a forward slash character, for example, "C\:/", is absolute. A normalized path which starts with a protocol followed by a forward slash character, for example, "file:/", is absolute. Otherwise, the path is not absolute.- Parameters:
normalizedPath
- The normalized path which is to be tested. An exception will be thrown if the path is null.- Returns:
- True or false telling if the path is absolute.
-
normalize
Normalize a path. Remove all "." elements, and resolve all ".." elements. ".." elements are resolved by removing the ".." element along with the higher (preceding) element. Leading ".." elements are not removed. Paths which represent resource locators (which start with "http:", "https:", or "ftp:") are not modified. Paths which represent file resource locators (which start with "file:") are modified. However, the "file:" prefix is preserved. Normalization is performed on the text which follows the "file:" prefix.- Parameters:
path
- The path which is to be normalized. An exception will be thrown if the path is null.- Returns:
- The normalized path.
-
isSymbol
Tell if a path starts with a symbolic substitution. A symbolic substitution is the character sequence "\$\{\}" with at least one character between braces. Other than requiring at least one character, this method does not validate the characters between the braces. This method does not validate that a closing brace is present.- Parameters:
path
- The path to test for a symbolic substitution.- Returns:
- True or false telling if the path contains and starts with a symbolic substitution.
-
containsSymbol
Tell if a path contains a symbolic substitution. A symbolic substitution is the character sequence "\$\{\}" with at least one character between braces. Other than requiring at least one character, this method does not validate the characters between the braces. The return value is unpredictable for a path which contains a malformed substitution, for example, "leading\$\{A/inner/\$\{B\}/trailing".- Parameters:
path
- The path to test for a symbolic substitution.- Returns:
- True or false telling if the path contains a symbolic substitution.
-
getSymbol
Answer the first symbolic substitution within a path. SeecontainsSymbol(String)
for a description of a symbolic substitution. Answer null if the path is null or if the path contains no symbolic substitution. For example, for "leading/trailing" answer null. For example, for "leading/\$\{A\}"/trailing" answer "\$\{A\}". For example, for "leading/\$\{A\}"/inner/\$\{B\}/trailing" answer "\$\{A\}". Paths with badly formed substitutions answer unpredictable values. For example, for "leading\$\{A/inner/\$\{B\}/trailing" answer "\$\{A/inner/\$\{B\}".- Parameters:
path
- The path from which to obtain the first symbol.- Returns:
- The first symbol of the path. Null if the path is null or contains no symbolic substitutions.
-
getParent
Answer the path with the last file name removed, using forward slash ('/') as the path separator character. Answer null for a path which contains no slashes. Answer null for a path which is a single slash character. Answer the path which is a single slash character when the path starts with a slash, which is not a single slash character, and which contains no other slashes. Answer the path with the trailing slash removed for a path which has a trailing slash and which is not a single slash character. Answer the the path up to but not including the trailing slash in all other cases. For example: For "/grandParent/parent/child" answer "/grandParent/parent". For "/grandParent/parent/" answer "/grandParent/parent". For "/parent" answer "/". For "/" answer null. For "child" answer null. For "" answer null.- Parameters:
path
- The path with the last file named removed. An exception will be thrown if the path is null.- Returns:
- The path with the last file name removed.
-
getName
Answer the last file name of a path, using the forward slash ('/') as the path separator character. Answer the path element which follows the last forward slash of the path. Answer the entire path if the path contains no path separator. For example: For "/parent/child" answer "child". For "child" answer "child". An exception will be thrown if the path ends with a trailing slash.- Parameters:
path
- The path from which to answer the last file name.- Returns:
- The last file name of the path.
-
getFirstPathComponent
Answer the first file name of a path, using the forward slash character ('/') as the path separator character. Answer the path element which follows the last forward slash of the path. Answer the entire path if the path contains no path separator. Answer the path element which precedes the first path separator, except, ignore a leading path separator. For example: For "/parent/child" answer "parent". For "parent/child" answer "parent". For "parent" answer "parent". For "/parent" answer "parent". For "/" answer "".- Parameters:
path
- The path from which to answer the first file name. An exception will be thrown if the path is null.- Returns:
- The first file name of the path.
-
getChildUnder
Answer the first path element of a path which follows a leading sub-path. For example, for path "/grandParent/parent/child/grandChild" and leading sub-path "/grandParent/parent", answer "child". The result is unpredictable if the leading path does not start the target path, and does not reach a separator character in the target path. An exception will be thrown if the leading path is longer than the target path.- Parameters:
path
- The path from which to obtain a path element.leadingPath
- A leading sub-path of the target path.- Returns:
- The first path element of the target path following the leading sub-path.
-
isUnixStylePathAbsolute
Tell if a path, if applied to a target location, will reach above the target location. For example, "../siblingParent/child", when applied to "grandParent/parent" reaches "grandParent/siblingParent/child", which is not beneath the initial target location. The test resolves all ".." elements before performing the test. A test which simply examines the starting character of the path is not sufficient. For example, the path "parent/../../siblingParent/child" reaches above target locations. The path must use forward slashes.- Parameters:
path
- The path which is to be tested.- Returns:
- True or false telling if the path reaches above target locations.
-
isNormalizedPathAbsolute
Tell if a path, if applied to a target location, will reach above the target location. The path must use forward slashes and must have all ".." elements resolved. The path reaches above target locations if it is "..", or if it starts with "../" or starts with "/..".- Parameters:
normalizedPath
- The path which is to be tested.- Returns:
- True or false telling if the path reaches above target locations.
-
checkAndNormalizeRootPath
Resolve all ".." elements of a path. The path must use forward slashes. Verify that the path does not reach above target elements (seeisUnixStylePathAbsolute(String)
. Add a leading slash if the path does not have one. Remove any trailing slash. Verify that the resulting path is neither empty nor a single slash character.- Parameters:
path
- The path which is to be normalized.- Returns:
- The normalized path. An exception will result if the path is null.
- Throws:
IllegalArgumentException
- If the resolved path is empty or has just a single slash, or if the resolved path reaches above target locations.
-
normalizeUnixStylePath
Normalize a path, resolving as many ".." elements as possible. Do not remove a leading '/', but remove a trailing '/'. The path must use forward slashes as path separators. After resolution, all unresolved ".." elements will be at the beginning of the path, possibly including a leading '/'.- Parameters:
path
- A path which is to be normalized.- Returns:
- The normalized path.
-
checkCase
The artifact API is case sensitive even on a file system that is not case sensitive. This method will test that the case of the supplied existing file matches the case in the pathToTest. It is assumed that you already tested that the file exists using the pathToTest. Therefore, on a case sensitive files system, the case must match and true is returned without doing any further testing. In other words, the check for file existence is sufficient on a case sensitive file system, and there is no reason to call this checkCase method. If the file system is not case sensitive, then a test for file existence will pass even when the case does not match. So this method will do further testing to ensure the case matches. It assumes that the final part of the file's path will be equal to the whole of the pathToTest. The path to test should be a unix style path with "/" as the separator character, regardless of the operating system. If the file is a directory then a trailing slash or the absence thereof will not affect whether the case matches since the trailing slash on a directory is optional. If you call checkCase(...) with a file that does NOT exist: On case sensitive file system: Always returns true On case insensitive file system: It compares the pathToTest to the file path of the java.io.File that you passed in rather than the file on disk (since it doesn't exist). file.getCanonicalFile() returns the path using the case of the file on disk, if it exists. If the file doesn't exist then it returns the path using the case of the java.io.File itself.- Parameters:
file
- The existing file to compare againstpathToTest
- The path to test if it is the same- Returns:
true
if the case is the same in the file and the pathToTest
-
replaceRestrictedCharactersInFileName
Copy a file name, replacing each restricted character with a single period character ('.'). Restricted characters are control characters and the following:< > : " / \\ | ? *
(SeeFILE_NAME_RESTRICTED_CHARS
. Control characters are character with a value greater than or equal to zero and less than or equal to 31. The set of restricted characters was selected conservatively based on the rules for Windows file names. The parameter should be a file name. Both the forward slash ('/') and the backwards slash ('\\') are restricted characters. Answer null if all characters of the file name are replaced, or if the resulting file name is "." or "..".- Parameters:
name
- The file name in which to replace restricted characters. An exception will be thrown if the file name is null.- Returns:
- The copy of the file name with all restricted characters replaced. Null if all characters were replaced or of the replaced file name is "." or "..".
-
fixPathString
Answer a canonical path for a target path usingfixPathString(File)
.- Parameters:
targetPath
- The path for which to obtain a canonical path.- Returns:
- The canonical path for the target path.
-
fixPathString
Answer the canonical path of a file. How the canonical path is found depends on the current active environment: On a Windows environment, attempt to obtain the canonical value usingFile.getCanonicalPath()
. If that fails, obtain the canonical value usingFile.getAbsolutePath()
. On a non-windows environment, obtain the canonical value usingFile.getAbsolutePath()
. A failure ofFile.getCanonicalPath()
causes an FFDC exception report to be generated. However, processing continues with the call toFile.getAbsolutePath()
. Use of canonical paths enables the use of java case sensitive string comparisons for file name comparisons. SeeIS_OS_CASE_SENSITIVE
.- Parameters:
targetFile
- The file for which to answer the canonical path.- Returns:
- The canonical path for the file.
-
getFixedPathFiles
ApplyfixPathString(File)
to a collection of paths. Create a file on each of the adjusted paths. Collect and return the files created on the adjusted paths. Answer an empty collection if the paths collection is null.- Parameters:
paths
- The paths to which to applyfixPathString(String)
.- Returns:
- The files created from the adjusted paths.
-
fixPathFiles
Collect the results of applyingfixPathString(File)
to a collection of files. Answer an empty collection if the file collection is null.- Parameters:
files
- The files to which to applyfixPathString(File)
.- Returns:
- The collected files.
-