org.openmdx.compatibility.base.naming
Class Path

java.lang.Object
  org.openmdx.compatibility.base.naming.Path

All Implemented Interfaces:

Serializable, Cloneable, Comparable

public final class Path
extends Object
implements Comparable, Cloneable, Serializable

The Path class reperesents a data provider path. The components of a name are numbered. The indexes of a name with N components range from 0 up to, but not including, N. This range may be written as [0,N). The most significant component is at index 0. An empty name has no components. None of the methods in this interface accept null as a valid value for a parameter that is a name or a name component. Likewise, methods that return a name or name component never return null. An instance of a Path is not synchronized against concurrent multithreaded access if that access is not read-only.

See Also:

Serialized Form

Field Summary

static String

URI_SCHEME Deprecated. use org.openmdx.kernel.uri.scheme.OpenMDXSchemes.URI_SCHEME

Constructor Summary

Path(Path path)
Creates a Path object.

Path(String charSequence)
Creates a Path object.

Path(String[] components)
Creates a new path object given by multiple path components.

Path(URI iri)
Creates a Path object.

Method Summary

Path	add(int position, PathComponent component) Adds a single component at a specified position within this path.
Path	add(int position, String component) Adds a single component at a specified position within this path.
Path	add(PathComponent component) Adds a single component to the end of this path.
Path	add(String component) Adds a single component to the end of this path.
Path	addAll(int position, String[] components) Adds the elements of a string array -- in order -- at a specified position within this path.
Path	addAll(String[] suffix) Adds the elements of a string array -- in order -- to the end of this path.
Object	clone() Generates a new copy of this path.
int	compareTo(Object obj) Compares this path with another path for order.
boolean	endsWith(String[] suffix) Determines whether this path ends with a specified suffix.
boolean	equals(Object that) Indicates whether some other object is "equal to" this one.
String	get(int position) Retrieves a component of this path.
String	getBase() Returns the base of the path.
Path	getChild(PathComponent component) Returns a child path
Path	getChild(String component) Returns a child path
PathComponent	getComponent(int position) Return the specified component
Path	getDescendant(String[] suffix) Returns a descendant path.
PathComponent	getLastComponent() Returns the last component of a path.
Path	getParent() Returns the parent path.
Path	getPrefix(int position) Creates a path whose components consist of a prefix of the components of this path.
String[]	getSuffix(int position) Creates a suffix of the components in this path.
String	getUriReference(String fragmentIdentifier) Generates an URI refercence for this Path and the given fragment identifier
int	hashCode() Returns the hash code value for this path.
boolean	isEmpty() Determines whether this path is empty.
boolean	isLike(Path pattern) Determines whether the path corresponds to the pattern.
void	lock() Make this path object unmodifiable
String	remove(int position) Removes a component from this path.
void	setTo(Path source) Set this path to the same value as another one.
int	size() Returns the number of path components for this path.
boolean	startsWith(Path prefix) Determines whether this path starts with a specified prefix.
boolean	startsWith(String[] prefix) Determines whether this path starts with a specified prefix.
URI	toIRI() Generates the XRI 2 based IRI representation of this path.
static Path[]	toPathArray(List source) Store a list's values in a Path array.
String	toString() Generates the string representation of this path.
String	toUri() Generates the URI representation of this path.
String	toXri() Generates the XRI 1 representation of this path.
XRI	toXRI() Generates the XRI 2 representation of this path.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

URI_SCHEME

public static final String URI_SCHEME

Deprecated. use org.openmdx.kernel.uri.scheme.OpenMDXSchemes.URI_SCHEME

A path's URI scheme

See Also:

Constant Field Values

Constructor Detail

Path

public Path(String[] components)

Creates a new path object given by multiple path components. The path is backed by the components list as long as it is not modified by an add, addAll or remove method.

Parameters:

components - path components

Throws:

RuntimeServiceException - in case of invalid components

NullPointerException - if components is null

Path

public Path(String charSequence)

Creates a Path object.

Parameters:

path - The non-null string to parse.

Throws:

RuntimeServiceException - in case of marshalling error

Path

public Path(URI iri)

Creates a Path object.

Parameters:

iri - The non-null IRI.

Throws:

RuntimeServiceException - in case of marshalling error

Path

public Path(Path path)

Creates a Path object.

Parameters:

path - The new path will consist of this name's components

Method Detail

getParent

public Path getParent()

Returns the parent path.

Returns:

the parent path.

Throws:

ArrayIndexOutOfBoundsException - if the path is empty

getChild

public Path getChild(String component)

Returns a child path

Parameters:

component - the component to be added

Returns:

a new and longer path

Throws:

RuntimeServiceException - if the component is null or empty

getChild

public Path getChild(PathComponent component)

Returns a child path

Parameters:

component - the component to be added

Returns:

a new and longer path

Throws:

RuntimeServiceException - if the component is null or empty

getDescendant

public Path getDescendant(String[] suffix)

Returns a descendant path.

Parameters:

suffix - the components to be added

Returns:

the descendant path.

Throws:

RuntimeServiceException - if any of the components is null or empty

getBase

public String getBase()

Returns the base of the path. The base is the last component of a path.

Returns:

the base path component.

Throws:

ArrayIndexOutOfBoundsException - if the path is empty

getLastComponent

public PathComponent getLastComponent()

Returns the last component of a path.

Returns:

the last path component.

Throws:

ArrayIndexOutOfBoundsException - if the path is empty

getComponent

public PathComponent getComponent(int position)

Return the specified component

Parameters:

position - the 0-based index of the component to retrieve. Must be in the range [0,size()).

Returns:

the component at index position

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

toUri

public String toUri()

Generates the URI representation of this path. An empty path is represented by "spice:/". The string representation thus generated can be passed to the Path constructor to create a new equivalent path.

Returns:

A non-null string representation of this path.

toXri

public String toXri()

Generates the XRI 1 representation of this path.

The string representation thus generated can be passed to the Path constructor to create a new equivalent path.

Returns:

A non-null string representation of this path.

toXRI

public XRI toXRI()

Generates the XRI 2 representation of this path.

The string representation of the generated XRI can be passed to the Path constructor to create a new equivalent path.

Returns:

An XRI 2 representation of this path.

toIRI

public URI toIRI()

Generates the XRI 2 based IRI representation of this path.

Returns:

An XRI 2 based IRI representation of this path.

getUriReference

public String getUriReference(String fragmentIdentifier)

Generates an URI refercence for this Path and the given fragment identifier

Parameters:

fragmentIdentifier - The fragment identifier

Returns:

A non-null URI reference with the given fragment identifier or the the paths' URI if the fragemtn identifier is null.

compareTo

public int compareTo(Object obj)

Compares this path with another path for order. Returns a negative integer, zero, or a positive integer as this path is less than, equal to, or greater than the given path.

Specified by:

compareTo in interface Comparable

Parameters:

the - non-null object to compare against.

Returns:

a negative integer, zero, or a positive integer as this path is less than, equal to, or greater than the given path

Throws:

ClassCastException - if obj is not an instance of Path

size

public int size()

Returns the number of path components for this path.

Returns:

the number of path components represented by this object.

isEmpty

public boolean isEmpty()

Determines whether this path is empty. An empty path is one with zero components.

get

public String get(int position)

Retrieves a component of this path.

Parameters:

position - the 0-based index of the component to retrieve. Must be in the range [0,size()).

Returns:

the component at index position

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

getPrefix

public Path getPrefix(int position)

Creates a path whose components consist of a prefix of the components of this path. Subsequent changes to this path will not affect the path that is returned and vice versa.

Parameters:

position - the 0-based index of the component at which to stop. Must be in the range [0,size()].

Returns:

a path consisting of the components at indexes in the range [0,position).

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

getSuffix

public String[] getSuffix(int position)

Creates a suffix of the components in this path. Subsequent changes to this path do not affect the string array that is returned and vice versa.

Parameters:

position - the 0-based index of the component at which to start. Must be in the range [0,size()].

Returns:

a string array consisting of the components at indices in the range [position,size()). If position is equal to size(), an empty array is returned.

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

startsWith

public boolean startsWith(String[] prefix)

Determines whether this path starts with a specified prefix. A string array is a prefix if it is equal to getPrefix(prefix.length).

Parameters:

prefix - the path to check

Returns:

true if components is a prefix of this path, false otherwise

startsWith

public boolean startsWith(Path prefix)

Determines whether this path starts with a specified prefix. A path is a prefix if it is equal to getPrefix(prefix.size()).

Parameters:

components - the path to check

Returns:

true if components is a prefix of this path, false otherwise

endsWith

public boolean endsWith(String[] suffix)

Determines whether this path ends with a specified suffix. A string array is a suffix if it is equal to getSuffix(size()-suffix.size()).

Parameters:

suffix - the string array to check

Returns:

true if suffix is a suffix of this path, false otherwise

addAll

public Path addAll(String[] suffix)

Adds the elements of a string array -- in order -- to the end of this path.

Parameters:

suffix - the components to add

Returns:

the updated path (not a new one)

Throws:

RuntimeServiceException - if suffix is not a valid name, or if the addition of the components would violate the syntax rules of this path

addAll

public Path addAll(int position,
                   String[] components)

Adds the elements of a string array -- in order -- at a specified position within this path. Components of this path at or after the index of the first new component are shifted up (away from 0) to accommodate the new components.

Parameters:

components - the components to add

position - the index in this path at which to add the new components. Must be in the range [0,size()].

Returns:

the updated path (not a new one)

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

RuntimeServiceException - if components contains invalid path components

add

public Path add(String component)

Adds a single component to the end of this path.

Parameters:

component - the component to add

Returns:

the updated path (not a new one)

Throws:

RuntimeServiceException - if adding component would violate the syntax rules of this path

add

public Path add(PathComponent component)

Adds a single component to the end of this path.

Parameters:

component - the component to add

Returns:

the updated path (not a new one)

Throws:

RuntimeServiceException - if the component is null or empty

add

public Path add(int position,
                String component)

Adds a single component at a specified position within this path. Components of this path at or after the index of the new component are shifted up by one (away from index 0) to accommodate the new component.

Parameters:

component - the component to add

position - the index at which to add the new component. Must be in the range [0,size()].

Returns:

the updated path (not a new one)

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

RuntimeServiceException - if adding component would violate the syntax rules of this path

add

public Path add(int position,
                PathComponent component)

Adds a single component at a specified position within this path. Components of this path at or after the index of the new component are shifted up by one (away from index 0) to accommodate the new component.

Parameters:

component - the component to add

position - the index at which to add the new component. Must be in the range [0,size()].

Returns:

the updated path (not a new one)

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

RuntimeServiceException - if the component is null or empty

remove

public String remove(int position)

Removes a component from this path. The component of this path at the specified position is removed. Components with indexes greater than this position are shifted down (toward index 0) by one.

Parameters:

position - the index of the component to remove. Must be in the range [0,size()).

Returns:

the component removed (a String)

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

RuntimeServiceException - if deleting the component would violate the syntax rules of the path

setTo

public void setTo(Path source)

Set this path to the same value as another one. Subsequent changes to the components of this path will not affect the other one, and vice versa.

Parameters:

source - This path will have the same components as source.

Throws:

ArrayIndexOutOfBoundsException - if position is outside the specified range

RuntimeServiceException - if deleting the component would violate the syntax rules of the path

lock

public void lock()

Make this path object unmodifiable

isLike

public boolean isLike(Path pattern)

Determines whether the path corresponds to the pattern. The following patterns are supported: - The pattern component ":*" matches the corresponding path component starting with . The pattern component ":*" matches therefore the corresponding path component regardless of its content. - Field "%" is only allowed as the last field of the pattern's last path component and matches any number of fields and path components regardless of their content.

clone

public Object clone()

Generates a new copy of this path. Subsequent changes to the components of this path will not affect the new copy, and vice versa.

Overrides:

clone in class Object

Returns:

a clone of this instance.

toString

public String toString()

Generates the string representation of this path. An empty path is represented by an empty string. The string representation thus generated can be passed to the Path constructor to create a new equivalent path.

Overrides:

toString in class Object

Returns:

A non-null string representation of this path.

equals

public boolean equals(Object that)

Indicates whether some other object is "equal to" this one.

Overrides:

equals in class Object

Parameters:

object - - the reference object with which to compare.

Returns:

true if this object is the same as the object argument; false otherwise.

hashCode

public int hashCode()

Returns the hash code value for this path.

This ensures that path1.equals(path2) implies that path1.hashCode()==path2.hashCode() for any two paths, path1 and path2, as required by the general contract of Object.hashCode.

Overrides:

hashCode in class Object

Returns:

the path's hash code

toPathArray

public static Path[] toPathArray(List source)

Store a list's values in a Path array.

Returns:

a Path array with the list's values

Throws:

ClassCastException - If any of the values is not an instance of Path