com.github.fge.filesystem.path

Class PathElementsFactory

java.lang.Object

com.github.fge.filesystem.path.PathElementsFactory

Direct Known Subclasses:

UnixPathElementsFactory

@ParametersAreNonnullByDefault
public abstract class PathElementsFactory
extends Object

Abstract factory for PathElements instances

This class is in charge of all the heavy PathElements operations: creating them from input strings, but also resolving, relativizing and normalizing them. An instance of (an implementation of) this class is passed to all GenericPath instances.

Implementations have to override the necessary methods to extract the root components and name elements from a string, but also telling whether a name element is valid at all, or represents the current or parent directory (in typical filesystems, those would be testing that the name is either of "." or "..").

This package provides an implementation for Unix paths.

Important note: this class adheres as closely as possible to the Path contract with regards to resolution and relativization; this means that for both of these operations, normalization is not performed. You will therefore have to ensure that paths you submit to these methods are normalized.

Field Summary

Fields

Modifier and Type	Field and Description
protected static String[]	NO_NAMES
protected String	parentToken

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PathElementsFactory(String rootSeparator, String separator, String parentToken) Constructor

Method Summary

Methods

Modifier and Type	Method and Description
abstract PathElements	getRootPathElements()
String	getSeparator()
protected abstract boolean	isAbsolute(PathElements pathElements) Check whether a PathElements represents an absolute path
protected abstract boolean	isParent(String name) Check whether a name element represents the parent directory
protected abstract boolean	isSelf(String name) Check whether a name element represents the current directory
protected abstract boolean	isValidName(String name) Check whether a name element is valid
protected PathElements	normalize(PathElements elements) Normalize a PathElements
protected PathElements	relativize(PathElements first, PathElements second) Relativize a path against another
protected PathElements	resolve(PathElements first, PathElements second) Resolve a PathElements against another
protected PathElements	resolveSibling(PathElements first, PathElements second) Resolve a PathElements's parent against another
protected abstract String[]	rootAndNames(String path) Split an input path into the root component and all name elements
protected abstract String[]	splitNames(String names) Split a names-only input into individual name elements
PathElements	toPathElements(String path) Convert an input string into a PathElements
protected String	toString(PathElements elements) Return a string representation of a PathElements instance
protected String	toUriPath(String prefix, PathElements elements) Make a valid, raw URI path from a path's elements and a path prefix

Methods inherited from class java.lang.Object

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

Field Detail

NO_NAMES

protected static final String[] NO_NAMES

parentToken

protected final String parentToken

Constructor Detail

PathElementsFactory

protected PathElementsFactory(String rootSeparator,
                   String separator,
                   String parentToken)

Constructor

Parameters:

rootSeparator - the separator to insert between the root component, if any, and the first name element, if any

separator - the separator to insert between two name elements

parentToken - a canonical path token to represent the parent of the current path

Method Detail

getSeparator

public final String getSeparator()

rootAndNames

protected abstract String[] rootAndNames(String path)

Split an input path into the root component and all name elements

This method returns a two-element string array, where the first element is the root component and the second element is a string with all name elements and any trailing characters (if any) removed.

If the path has no root, the first element of the returned array must be null.

Parameters:

path - the path

Returns:

see description

splitNames

protected abstract String[] splitNames(String names)

Split a names-only input into individual name elements

The input is guaranteed to be well-formed (no root component, no root separator and no trailing characters). The name elements must be in their order of appearance in the input.

Parameters:

names - the input string

Returns:

an array of the name elements, in their order of appearance

isValidName

protected abstract boolean isValidName(String name)

Check whether a name element is valid

Parameters:

name - the name to check

Returns:

true if the name is valid

isSelf

protected abstract boolean isSelf(String name)

Check whether a name element represents the current directory

Parameters:

name - the name to check

Returns:

true if the name represents the current directory

See Also:

normalize(PathElements)

isParent

protected abstract boolean isParent(String name)

Check whether a name element represents the parent directory

Parameters:

name - the name to check

Returns:

true if the name represents the parent directory

See Also:

normalize(PathElements)

isAbsolute

protected abstract boolean isAbsolute(PathElements pathElements)

Check whether a PathElements represents an absolute path

Parameters:

pathElements - the instance to check

Returns:

true if the instance is an absolute path

See Also:

Path.isAbsolute()

getRootPathElements

public abstract PathElements getRootPathElements()

toPathElements

@Nonnull
public final PathElements toPathElements(String path)

Convert an input string into a PathElements

Parameters:

path - the string to convert

Returns:

a new PathElements instance

Throws:

InvalidPathException - one name element is invalid

See Also:

rootAndNames(String), isValidName(String)

normalize

@Nonnull
protected final PathElements normalize(PathElements elements)

Normalize a PathElements

Parameters:

elements - the instance to normalize

Returns:

a new, normalized instance

See Also:

isSelf(String), isParent(String), Path.normalize()

resolve

@Nonnull
protected final PathElements resolve(PathElements first,
                           PathElements second)

Resolve a PathElements against another

This method replicates the contract of Path.resolve(Path). In this method, the first argument is the instance performing the resolution and the second argument is the method's argument.

• if the second argument is absolute, it is returned;
• if the second argument has no name components, the first argument is returned;
• otherwise, resolution is performed by just appending the name components of the first argument to the second argument.

NOTES:

• as per the original method, no normalization of any argument is performed;
• if the second argument is deemed to be absolute but it does not have a root component, this method throws an UnsupportedOperationException.

Parameters:

first - the path performing the operation

second - the path on which the operation is performed

Returns:

the resulting path

See Also:

Path.resolve(Path)

resolveSibling

@Nonnull
protected final PathElements resolveSibling(PathElements first,
                                  PathElements second)

Resolve a PathElements's parent against another

This method replicates the contract of Path.resolveSibling(Path). In this method, the first argument is the instance performing the resolution and the second argument is the method's argument.

The rules are the same as the equivalent Path method:

• if the second argument is absolute, it is returned;
• if the first argument has no parent, the second is returned;
• if the second argument is an empty path, the first argument's parent is returned, or the empty path if parent is null.

Parameters:

first - the path performing the operation

second - the path on which the operation is performed

Returns:

the resulting path

relativize

@Nonnull
protected final PathElements relativize(PathElements first,
                              PathElements second)

Relativize a path against another

This mirrors the behaviour of Path.relativize(Path); in this method, first is the path performing the operation and second is the method's argument.

NOTE: in the event that both path elements have root components and they are not equal, an IllegalArgumentException is thrown unconditionally.

Parameters:

first - the path performing the operation

second - the path on which the operation is performed

Returns:

the resulting path

See Also:

Path.relativize(Path)

toString

@Nonnull
protected final String toString(PathElements elements)

Return a string representation of a PathElements instance

PathElements does not define .toString(), as the string representation of a path is highly system dependent.

Parameters:

elements - the instance

Returns:

a string representation

toUriPath

@Nonnull
protected final String toUriPath(@Nullable
                       String prefix,
                       PathElements elements)

Make a valid, raw URI path from a path's elements and a path prefix

The validity of the path prefix is NOT checked, it is supposed to be valid. Note that it must be "raw", that is not URI-encoded.

The elements must represent an absolute path according to that factory.

This method will perform normalization on the path elements before returning the result. If any parent tokens are found at the head of the name elements, they are removed. Name tokens are then appended and joined with a slash (/) character, as required by RFC 3986.

Trailing slashes, if any, are removed.

Parameters:

prefix - the URI path prefix (may be null)

elements - the path elements

Returns:

a raw (unencoded) path suitable for use in a URI

See Also:

URI