org.entityfs.el
Interface EntityLocation<T extends EntityLocation<?>>

All Superinterfaces:

Serializable

All Known Implementing Classes:

AbsoluteLocation, AbstractLocation, RelativeLocation

public interface EntityLocation<T extends EntityLocation<?>>
extends Serializable

Interface for an file system entity location. An entity location describes an entity's position in the file system hierarchy (its absolute path) or its position relative to other entities (relative paths). Think of entity locations as the path handling parts of java.io.File.

An entity location consists of entity names separated by a SEPARATOR ("/"). An AbsoluteLocation starts with a "/". The two special entity names, CURRENT_DIRECTORY_STRING and PARENT_DIRECTORY_STRING represents the current directory and the parent directory, respectively. A valid entity name is a name that matches the regular expression [^/\\\\]+.

When an entity location object is created, its path is normalized, which means that all parent and current directory entity strings are expanded. For instance, new AbsoluteLocation("/d1/d2/../d2p/f1").getLocation() returns "/d1/d2p/f1". A canonical entity location is a normalized entity location where symbolic links have been dereferenced (see java.io.File documentation and Entities.getCanonicalLocation(EntityView)). For file systems that don't support symbolic links, an entity's canonical location is always equal to its normalized location.

Entity locations are always case sensitive.

Entity location objects are immutable value objects.

Since:

1.0

Author:

Karl Gustafsson

See Also:

File

Field Summary

static String	CURRENT_DIRECTORY_STRING The special entity name representing the current entity ("." ).
static String	EXTENSION_SEPARATOR The separator in an entity name between the base entity name and the entity name extension ("." ).
static String	PARENT_DIRECTORY_STRING The special entity name representing the parent directory (".." ).
static String	SEPARATOR The separator between relative path entries in an entity location ("/" ).
static char	SEPARATOR_CHAR A char representation of the SEPARATOR (47 ).

Method Summary

String	getBaseName() Return the entity name without extensions.
T	getChildLocation(String name) Get the location of the named child entity relative to this location.
String	getExtension() Get the entity name extension without the separator ( ".").
String	getLocation() Get a string representation of the entity location.
T	getLocation(RelativeLocation loc) Get the location of this entity location combined with the given relative location, represented by the same entity location type as this entity location.
String	getName() Get the name of the entity referenced by this entity location.
T	getParentLocation() Get the parent location of this entity location.
LinkedList<String>	getPathSegmentStack() Get this entity location represented as a list of entity names.
boolean	isRootDir() Is this entity location an absolute entity location referencing the root directory.

Field Detail

SEPARATOR

static final String SEPARATOR

The separator between relative path entries in an entity location ("/" ). This separator is used regardless of what separator is used in the underlying file system implementation.

See Also:

Constant Field Values

SEPARATOR_CHAR

static final char SEPARATOR_CHAR

A char representation of the SEPARATOR (47 ).

See Also:

Constant Field Values

EXTENSION_SEPARATOR

static final String EXTENSION_SEPARATOR

The separator in an entity name between the base entity name and the entity name extension ("." ).

See Also:

Constant Field Values

CURRENT_DIRECTORY_STRING

static final String CURRENT_DIRECTORY_STRING

The special entity name representing the current entity ("." ).

See Also:

Constant Field Values

PARENT_DIRECTORY_STRING

static final String PARENT_DIRECTORY_STRING

The special entity name representing the parent directory (".." ).

See Also:

Constant Field Values

Method Detail

getLocation

String getLocation()

Get a string representation of the entity location.

This always holds: new ELT(s).equals(new ELT(new ELT(s).getLocation())) == true for all valid entity location strings s and concrete entity location classes ELT.

Returns:

The string representation of the entity location.

getName

String getName()

Get the name of the entity referenced by this entity location. (The entity does not have to exist.)

Returns:

The name of the entity, e.g. the file or directory name (including the extension).

getExtension

String getExtension()

Get the entity name extension without the separator ( "."). For instance, new AbsoluteLocation("/d1/f.txt").getExtension() returns txt.

Returns:

The entity name extension or an empty string if the entity name does not have an extension.

getBaseName

String getBaseName()

Return the entity name without extensions. If the entity name has one extension (one dot), then getName().equals(getBaseName() + "." + getExtension()) == true holds.

If the entity name starts with a dot, that first dot is ignored.

Returns:

The entity name without extensions.

isRootDir

boolean isRootDir()

Is this entity location an absolute entity location referencing the root directory. In other words, is el.getLocation().equals(AbsoluteLocation.ROOT_DIR) true?

Returns:

true if this entity location is an absolute location pointing to the root directory, false otherwise.

getParentLocation

T getParentLocation()
                                              throws InvalidEntityLocationException

Get the parent location of this entity location.

Returns:

This entity location's parent location.

Throws:

InvalidEntityLocationException - If this is called on an absolute entity location referencing the file system root.

getChildLocation

T getChildLocation(String name)

Get the location of the named child entity relative to this location.

Parameters:

name - The child entity name.

Returns:

The child entity's location represented with the same entity location type as this entity location.

getLocation

T getLocation(RelativeLocation loc)
                                        throws InvalidEntityLocationException

Get the location of this entity location combined with the given relative location, represented by the same entity location type as this entity location. (In other words: when invoked on an absolute entity location, this returns an absolute entity location. When invoked on a relative entity location, this returns a relative location.)

Parameters:

loc - The location relative to this entity location.

Returns:

The resulting entity location.

Throws:

InvalidEntityLocationException - If the resulting location is an absolute entity location pointing outside of the file system.

getPathSegmentStack

LinkedList<String> getPathSegmentStack()

Get this entity location represented as a list of entity names. For instance, the relative entity location ../foo/bar gives the following path segment stack:

0. ..
1. foo
2. bar

If the path only consists of a dot, an empty stack (length 0) is returned. If the entity location ends with a slash, the last path segment is an empty string.

Returns:

The stack of entity names in this entity location.