[dna-commits] DNA SVN: r230 - trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Mon Jun 2 15:56:43 EDT 2008
Author: jverhaeg at redhat.com
Date: 2008-06-02 15:56:43 -0400 (Mon, 02 Jun 2008)
New Revision: 230
Modified:
trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/Path.java
Log:
DNA-81: Changed SELF and PARENT constants to use appropriate instances of BasicXXX
Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/Path.java
===================================================================
--- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/Path.java 2008-06-02 19:54:56 UTC (rev 229)
+++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/Path.java 2008-06-02 19:56:43 UTC (rev 230)
@@ -2,7 +2,7 @@
* JBoss, Home of Professional Open Source.
* Copyright 2008, Red Hat Middleware LLC, and individual contributors
* as indicated by the @author tags. See the copyright.txt file in the
- * distribution for a full listing of individual contributors.
+ * distribution for a full listing of individual contributors.
*
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
@@ -29,6 +29,8 @@
import org.jboss.dna.common.text.NoOpEncoder;
import org.jboss.dna.common.text.TextEncoder;
import org.jboss.dna.common.text.UrlEncoder;
+import org.jboss.dna.spi.graph.impl.BasicName;
+import org.jboss.dna.spi.graph.impl.BasicPathSegment;
/**
* An object representation of a node path within a repository.
@@ -64,718 +66,416 @@
* {@link #isAncestorOf(Path) ancestor} or {@link #isDecendantOf(Path) decendent} of another path, and
* {@link #getCommonAncestor(Path) finding a common ancestor}.
* </p>
+ *
* @author Randall Hauch
+ * @author John Verhaeg
*/
@Immutable
public interface Path extends Comparable<Path>, Iterable<Path.Segment>, Serializable {
- /**
- * The text encoder that does nothing.
- */
- public static final TextEncoder NO_OP_ENCODER = new NoOpEncoder();
+ /**
+ * The text encoder that does nothing.
+ */
+ public static final TextEncoder NO_OP_ENCODER = new NoOpEncoder();
- /**
- * The text encoder that encodes and decodes according to JSR-283.
- */
- public static final TextEncoder JSR283_ENCODER = new Jsr283Encoder();
+ /**
+ * The text encoder that encodes and decodes according to JSR-283.
+ */
+ public static final TextEncoder JSR283_ENCODER = new Jsr283Encoder();
- /**
- * The text encoder that encodes and decodes text according to the rules of <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC
- * 2396</a>.
- */
- public static final TextEncoder URL_ENCODER = new UrlEncoder().setSlashEncoded(true);
+ /**
+ * The text encoder that encodes and decodes text according to the rules of <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC
+ * 2396</a>.
+ */
+ public static final TextEncoder URL_ENCODER = new UrlEncoder().setSlashEncoded(true);
- /**
- * The default text encoder to be used when none is otherwise specified. This is currently the
- * {@link #JSR283_ENCODER JSR-283 encoder}.
- */
- public static final TextEncoder DEFAULT_ENCODER = JSR283_ENCODER;
+ /**
+ * The default text encoder to be used when none is otherwise specified. This is currently the
+ * {@link #JSR283_ENCODER JSR-283 encoder}.
+ */
+ public static final TextEncoder DEFAULT_ENCODER = JSR283_ENCODER;
- /**
- * The delimiter character used to separate segments within a path.
- */
- public static final char DELIMITER = '/';
+ /**
+ * The delimiter character used to separate segments within a path.
+ */
+ public static final char DELIMITER = '/';
- /**
- * String form of the delimiter used to separate segments within a path.
- */
- public static final String DELIMITER_STR = new String(new char[] {DELIMITER});
+ /**
+ * String form of the delimiter used to separate segments within a path.
+ */
+ public static final String DELIMITER_STR = new String(new char[] {DELIMITER});
- /**
- * String representation of the segment that references a parent.
- */
- public static final String PARENT = "..";
+ /**
+ * String representation of the segment that references a parent.
+ */
+ public static final String PARENT = "..";
- /**
- * String representation of the segment that references the same segment.
- */
- public static final String SELF = ".";
+ /**
+ * String representation of the segment that references the same segment.
+ */
+ public static final String SELF = ".";
- /**
- * The index that will be returned for a {@link Segment} that {@link Segment#hasIndex() has no index}.
- */
- public static final int NO_INDEX = -1;
+ /**
+ * The index that will be returned for a {@link Segment} that {@link Segment#hasIndex() has no index}.
+ */
+ public static final int NO_INDEX = -1;
- /**
- * Representation of the segments that occur within a path.
- * @author Randall Hauch
- */
- @Immutable
- public static interface Segment extends Cloneable, Comparable<Segment>, Serializable {
+ /**
+ * Representation of the segments that occur within a path.
+ *
+ * @author Randall Hauch
+ */
+ @Immutable
+ public static interface Segment extends Cloneable, Comparable<Segment>, Serializable {
- /**
- * Get the name component of this segment.
- * @return the segment's name
- */
- public Name getName();
+ /**
+ * Get the name component of this segment.
+ *
+ * @return the segment's name
+ */
+ public Name getName();
- /**
- * Get the index for this segment, which will be {@link Path#NO_INDEX 0} if this segment has no specific index.
- * @return the index
- */
- public int getIndex();
+ /**
+ * Get the index for this segment, which will be {@link Path#NO_INDEX 0} if this segment has no specific index.
+ *
+ * @return the index
+ */
+ public int getIndex();
- /**
- * Return whether this segment has an index.
- * @return true if this segment has an index, or false otherwise.
- */
- public boolean hasIndex();
+ /**
+ * Return whether this segment has an index.
+ *
+ * @return true if this segment has an index, or false otherwise.
+ */
+ public boolean hasIndex();
- /**
- * Return whether this segment is a self-reference.
- * @return true if the segment is a self-reference, or false otherwise.
- */
- public boolean isSelfReference();
+ /**
+ * Return whether this segment is a self-reference.
+ *
+ * @return true if the segment is a self-reference, or false otherwise.
+ */
+ public boolean isSelfReference();
- /**
- * Return whether this segment is a reference to a parent.
- * @return true if the segment is a parent-reference, or false otherwise.
- */
- public boolean isParentReference();
+ /**
+ * Return whether this segment is a reference to a parent.
+ *
+ * @return true if the segment is a parent-reference, or false otherwise.
+ */
+ public boolean isParentReference();
- /**
- * Get the string form of the segment. The {@link #DEFAULT_ENCODER default encoder} is used to encode characters in each
- * of the path segments.
- * @return the encoded string
- * @see #getString(TextEncoder)
- */
- public String getString();
+ /**
+ * Get the string form of the segment. The {@link #DEFAULT_ENCODER default encoder} is used to encode characters in each
+ * of the path segments.
+ *
+ * @return the encoded string
+ * @see #getString(TextEncoder)
+ */
+ public String getString();
- /**
- * Get the encoded string form of the segment, using the supplied encoder to encode characters in each of the path
- * segments.
- * @param encoder the encoder to use, or null if the {@link #DEFAULT_ENCODER default encoder} should be used
- * @return the encoded string
- * @see #getString()
- */
- public String getString( TextEncoder encoder );
+ /**
+ * Get the encoded string form of the segment, using the supplied encoder to encode characters in each of the path
+ * segments.
+ *
+ * @param encoder the encoder to use, or null if the {@link #DEFAULT_ENCODER default encoder} should be used
+ * @return the encoded string
+ * @see #getString()
+ */
+ public String getString( TextEncoder encoder );
- /**
- * Get the string form of the segment, using the supplied namespace registry to convert the name's namespace URI to a
- * prefix. The {@link #DEFAULT_ENCODER default encoder} is used to encode characters in each of the path segments.
- * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
- * {@link Name#getNamespaceUri() namespace URI} in the segment's {@link #getName() name}
- * @return the encoded string
- * @throws IllegalArgumentException if the namespace registry is null
- * @see #getString(NamespaceRegistry,TextEncoder)
- */
- public String getString( NamespaceRegistry namespaceRegistry );
+ /**
+ * Get the string form of the segment, using the supplied namespace registry to convert the name's namespace URI to a
+ * prefix. The {@link #DEFAULT_ENCODER default encoder} is used to encode characters in each of the path segments.
+ *
+ * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
+ * {@link Name#getNamespaceUri() namespace URI} in the segment's {@link #getName() name}
+ * @return the encoded string
+ * @throws IllegalArgumentException if the namespace registry is null
+ * @see #getString(NamespaceRegistry,TextEncoder)
+ */
+ public String getString( NamespaceRegistry namespaceRegistry );
- /**
- * Get the encoded string form of the segment, using the supplied namespace registry to convert the name's namespace URI
- * to a prefix and the supplied encoder to encode characters in each of the path segments.
- * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
- * {@link Name#getNamespaceUri() namespace URI} in the segment's {@link #getName() name}
- * @param encoder the encoder to use, or null if the {@link #DEFAULT_ENCODER default encoder} should be used
- * @return the encoded string
- * @throws IllegalArgumentException if the namespace registry is null
- * @see #getString(NamespaceRegistry)
- */
- public String getString( NamespaceRegistry namespaceRegistry, TextEncoder encoder );
- }
+ /**
+ * Get the encoded string form of the segment, using the supplied namespace registry to convert the name's namespace URI
+ * to a prefix and the supplied encoder to encode characters in each of the path segments.
+ *
+ * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
+ * {@link Name#getNamespaceUri() namespace URI} in the segment's {@link #getName() name}
+ * @param encoder the encoder to use, or null if the {@link #DEFAULT_ENCODER default encoder} should be used
+ * @return the encoded string
+ * @throws IllegalArgumentException if the namespace registry is null
+ * @see #getString(NamespaceRegistry)
+ */
+ public String getString( NamespaceRegistry namespaceRegistry,
+ TextEncoder encoder );
+ }
- /**
- * Singleton instance of the name referencing a self, provided as a convenience.
- */
- public static final Name SELF_NAME = new Name() {
+ /**
+ * Singleton instance of the name referencing a self, provided as a convenience.
+ */
+ public static final Name SELF_NAME = new BasicName(null, SELF);
- /**
- * {@inheritDoc}
- */
- public String getLocalName() {
- return SELF;
- }
+ /**
+ * Singleton instance of the name referencing a parent, provided as a convenience.
+ */
+ public static final Name PARENT_NAME = new BasicName(null, PARENT);
- /**
- * {@inheritDoc}
- */
- public String getNamespaceUri() {
- return "";
- }
+ /**
+ * Singleton instance of the path segment referencing a parent, provided as a convenience.
+ */
+ public static final Path.Segment SELF_SEGMENT = new BasicPathSegment(SELF_NAME);
- /**
- * {@inheritDoc}
- */
- public String getString() {
- return getString(DEFAULT_ENCODER);
- }
+ /**
+ * Singleton instance of the path segment referencing a parent, provided as a convenience.
+ */
+ public static final Path.Segment PARENT_SEGMENT = new BasicPathSegment(PARENT_NAME);
- /**
- * {@inheritDoc}
- */
- public String getString( TextEncoder encoder ) {
- return encoder.encode(SELF);
- }
+ /**
+ * Return the number of segments in this path.
+ *
+ * @return the number of path segments
+ */
+ public int size();
- /**
- * {@inheritDoc}
- */
- public String getString( NamespaceRegistry namespaceRegistry ) {
- return getString(namespaceRegistry, DEFAULT_ENCODER);
- }
+ /**
+ * Return whether this path represents the root path.
+ *
+ * @return true if this path is the root path, or false otherwise
+ */
+ public boolean isRoot();
- /**
- * {@inheritDoc}
- */
- public String getString( NamespaceRegistry namespaceRegistry, TextEncoder encoder ) {
- return encoder.encode(SELF);
- }
+ /**
+ * Determine whether this path represents the same as the supplied path. This is equivalent to calling
+ * <code>this.compareTo(other) == 0 </code>.
+ *
+ * @param other the other path to compare with this path
+ * @return true if the paths are equivalent, or false otherwise
+ */
+ public boolean isSame( Path other );
- /**
- * {@inheritDoc}
- */
- public int compareTo( Name that ) {
- if (this == that) return 0;
- int diff = this.getLocalName().compareTo(that.getLocalName());
- if (diff != 0) return diff;
- return this.getNamespaceUri().compareTo(that.getNamespaceUri());
- }
+ /**
+ * Determine whether this path is an ancestor of the supplied path. A path is considered an ancestor of another path if the
+ * the ancestor path appears in its entirety at the beginning of the decendant path, and where the decendant path contains at
+ * least one additional segment.
+ *
+ * @param decendant the path that may be the decendant
+ * @return true if this path is an ancestor of the supplied path, or false otherwise
+ */
+ public boolean isAncestorOf( Path decendant );
- /**
- * {@inheritDoc}
- */
- @Override
- public boolean equals( Object obj ) {
- if (this == obj) return true;
- if (obj instanceof Name) {
- Name that = (Name)obj;
- if (!this.getLocalName().equals(that.getLocalName())) return false;
- return this.getNamespaceUri().equals(that.getNamespaceUri());
- }
- return false;
- }
+ /**
+ * Determine whether this path is an decendant of the supplied path. A path is considered a decendant of another path if the
+ * the decendant path starts exactly with the entire ancestor path but contains at least one additional segment.
+ *
+ * @param ancestor the path that may be the ancestor
+ * @return true if this path is an decendant of the supplied path, or false otherwise
+ */
+ public boolean isDecendantOf( Path ancestor );
- /**
- * {@inheritDoc}
- */
- @Override
- public String toString() {
- return SELF;
- }
+ /**
+ * Return whether this path is an absolute path. A path is either relative or {@link #isAbsolute() absolute}. An absolute
+ * path starts with a "/".
+ *
+ * @return true if the path is absolute, or false otherwise
+ */
+ public boolean isAbsolute();
- };
+ /**
+ * Return whether this path is normalized and contains no "." segments and as few ".." segments as possible. For example, the
+ * path "../a" is normalized, while "/a/b/c/../d" is not normalized.
+ *
+ * @return true if this path is normalized, or false otherwise
+ */
+ public boolean isNormalized();
- /**
- * Singleton instance of the name referencing a parent, provided as a convenience.
- */
- public static final Name PARENT_NAME = new Name() {
+ /**
+ * Get a normalized path with as many ".." segments and all "." resolved.
+ *
+ * @return the normalized path, or this object if this path is already normalized
+ * @throws InvalidPathException if the normalized form would result in a path with negative length (e.g., "/a/../../..")
+ */
+ public Path getNormalizedPath();
- /**
- * {@inheritDoc}
- */
- public String getLocalName() {
- return PARENT;
- }
+ /**
+ * Get the canonical form of this path. A canonical path has is {@link #isAbsolute() absolute} and {@link #isNormalized()}.
+ *
+ * @return the canonical path, or this object if it is already in its canonical form
+ * @throws InvalidPathException if the path is not absolute and cannot be canonicalized
+ */
+ public Path getCanonicalPath();
- /**
- * {@inheritDoc}
- */
- public String getNamespaceUri() {
- return "";
- }
+ /**
+ * Get a relative path from the supplied path to this path.
+ *
+ * @param startingPath the path specifying the starting point for the new relative path; may not be null
+ * @return the relative path
+ * @throws IllegalArgumentException if the supplied path is null
+ * @throws PathNotFoundException if both this path and the supplied path are not absolute
+ */
+ public Path relativeTo( Path startingPath );
- /**
- * {@inheritDoc}
- */
- public String getString() {
- return getString(DEFAULT_ENCODER);
- }
+ /**
+ * Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path.
+ *
+ * @param relativePath the relative path that is to be resolved against this path
+ * @return the absolute and normalized path resolved from this path and the supplied absolute path
+ * @throws IllegalArgumentException if the supplied path is null
+ * @throws InvalidPathException if the this path is not absolute or if the supplied path is not relative.
+ */
+ public Path resolve( Path relativePath );
- /**
- * {@inheritDoc}
- */
- public String getString( TextEncoder encoder ) {
- return encoder.encode(PARENT);
- }
+ /**
+ * Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path.
+ *
+ * @param absolutePath the absolute path to which this relative path should be resolve
+ * @return the absolute path resolved from this path and the supplied absolute path
+ * @throws IllegalArgumentException if the supplied path is null
+ * @throws InvalidPathException if the supplied path is not absolute or if this path is not relative.
+ */
+ public Path resolveAgainst( Path absolutePath );
- /**
- * {@inheritDoc}
- */
- public String getString( NamespaceRegistry namespaceRegistry ) {
- return getString(namespaceRegistry, DEFAULT_ENCODER);
- }
+ /**
+ * Return the path to the parent, or this path if it is the {@link #isRoot() root}. This is an efficient operation that does
+ * not require copying any data.
+ *
+ * @return the parent path, or this path if it is already the root
+ */
+ public Path getAncestor();
- /**
- * {@inheritDoc}
- */
- public String getString( NamespaceRegistry namespaceRegistry, TextEncoder encoder ) {
- return encoder.encode(PARENT);
- }
+ /**
+ * Return the path to the ancestor of the supplied degree. An ancestor of degree <code>x</code> is the path that is
+ * <code>x</code> levels up along the path. For example, <code>degree = 0</code> returns this path, while
+ * <code>degree = 1</code> returns the parent of this path, <code>degree = 2</code> returns the grandparent of this path,
+ * and so on. Note that the result may be unexpected if this path is not {@link #isNormalized() normalized}, as a
+ * non-normalized path contains ".." and "." segments.
+ *
+ * @param degree
+ * @return the ancestor of the supplied degree
+ * @throws IllegalArgumentException if the degree is negative
+ * @throws PathNotFoundException if the degree is greater than the {@link #size() length} of this path
+ */
+ public Path getAncestor( int degree );
- /**
- * {@inheritDoc}
- */
- public int compareTo( Name that ) {
- if (this == that) return 0;
- int diff = this.getLocalName().compareTo(that.getLocalName());
- if (diff != 0) return diff;
- return this.getNamespaceUri().compareTo(that.getNamespaceUri());
- }
+ /**
+ * Determine whether this path and the supplied path have the same immediate ancestor. In other words, this method determines
+ * whether the node represented by this path is a sibling of the node represented by the supplied path.
+ *
+ * @param that the other path
+ * @return true if this path and the supplied path have the same immediate ancestor.
+ * @throws IllegalArgumentException if the supplied path is null
+ */
+ public boolean hasSameAncestor( Path that );
- /**
- * {@inheritDoc}
- */
- @Override
- public boolean equals( Object obj ) {
- if (this == obj) return true;
- if (obj instanceof Name) {
- Name that = (Name)obj;
- if (!this.getLocalName().equals(that.getLocalName())) return false;
- return this.getNamespaceUri().equals(that.getNamespaceUri());
- }
- return false;
- }
+ /**
+ * Find the lowest common ancestor of this path and the supplied path.
+ *
+ * @param that the other path
+ * @return the lowest common ancestor, which may be the root path if there is no other.
+ * @throws IllegalArgumentException if the supplied path is null
+ */
+ public Path getCommonAncestor( Path that );
- /**
- * {@inheritDoc}
- */
- @Override
- public String toString() {
- return PARENT;
- }
+ /**
+ * Get the last segment in this path.
+ *
+ * @return the last segment, or null if the path is empty
+ */
+ public Segment getLastSegment();
- };
+ /**
+ * Get the segment at the supplied index.
+ *
+ * @param index the index
+ * @return the segment
+ * @throws IndexOutOfBoundsException if the index is out of bounds
+ */
+ public Segment getSegment( int index );
- /**
- * Singleton instance of the path segment referencing a parent, provided as a convenience.
- */
- public static final Path.Segment SELF_SEGMENT = new Path.Segment() {
+ /**
+ * Return a new path consisting of the segments starting at <code>beginIndex</code> index (inclusive). This is equivalent to
+ * calling <code>path.subpath(beginIndex,path.size()-1)</code>.
+ *
+ * @param beginIndex the beginning index, inclusive.
+ * @return the specified subpath
+ * @exception IndexOutOfBoundsException if the <code>beginIndex</code> is negative or larger than the length of this
+ * <code>Path</code> object
+ */
+ public Path subpath( int beginIndex );
- /**
- * {@inheritDoc}
- */
- public int getIndex() {
- return NO_INDEX;
- }
+ /**
+ * Return a new path consisting of the segments between the <code>beginIndex</code> index (inclusive) and the
+ * <code>endIndex</code> index (exclusive).
+ *
+ * @param beginIndex the beginning index, inclusive.
+ * @param endIndex the ending index, exclusive.
+ * @return the specified subpath
+ * @exception IndexOutOfBoundsException if the <code>beginIndex</code> is negative, or <code>endIndex</code> is larger
+ * than the length of this <code>Path</code> object, or <code>beginIndex</code> is larger than
+ * <code>endIndex</code>.
+ */
+ public Path subpath( int beginIndex,
+ int endIndex );
- /**
- * {@inheritDoc}
- */
- public Name getName() {
- return SELF_NAME;
- }
+ /**
+ * {@inheritDoc}
+ */
+ public Iterator<Segment> iterator();
- /**
- * {@inheritDoc}
- */
- public String getString() {
- return SELF_NAME.getString();
- }
+ /**
+ * Obtain a copy of the segments in this path. None of the segments are encoded.
+ *
+ * @return the array of segments as a copy
+ */
+ public Segment[] getSegmentsArray();
- /**
- * {@inheritDoc}
- */
- public String getString( TextEncoder encoder ) {
- return SELF_NAME.getString(encoder);
- }
+ /**
+ * Get an unmodifiable list of the path segments.
+ *
+ * @return the unmodifiable list of path segments; never null
+ */
+ public List<Segment> getSegmentsList();
- /**
- * {@inheritDoc}
- */
- public String getString( NamespaceRegistry namespaceRegistry ) {
- return SELF_NAME.getString(namespaceRegistry);
- }
+ /**
+ * Get the string form of the path. The {@link #DEFAULT_ENCODER default encoder} is used to encode characters in each of the
+ * path segments.
+ *
+ * @return the encoded string
+ * @see #getString(TextEncoder)
+ */
+ public String getString();
- /**
- * {@inheritDoc}
- */
- public String getString( NamespaceRegistry namespaceRegistry, TextEncoder encoder ) {
- return SELF_NAME.getString(namespaceRegistry, encoder);
- }
+ /**
+ * Get the encoded string form of the path, using the supplied encoder to encode characters in each of the path segments.
+ *
+ * @param encoder the encoder to use, or null if the {@link #DEFAULT_ENCODER default encoder} should be used
+ * @return the encoded string
+ * @see #getString()
+ */
+ public String getString( TextEncoder encoder );
- /**
- * {@inheritDoc}
- */
- public boolean hasIndex() {
- return false;
- }
+ /**
+ * Get the string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes.
+ * The {@link #DEFAULT_ENCODER default encoder} is used to encode characters in each of the path segments.
+ *
+ * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
+ * {@link Name#getNamespaceUri() namespace URIs} in the segment {@link Segment#getName() names}
+ * @return the encoded string
+ * @throws IllegalArgumentException if the namespace registry is null
+ * @see #getString(NamespaceRegistry,TextEncoder)
+ */
+ public String getString( NamespaceRegistry namespaceRegistry );
- /**
- * {@inheritDoc}
- */
- public boolean isParentReference() {
- return false;
- }
+ /**
+ * Get the encoded string form of the path, using the supplied namespace registry to convert the names' namespace URIs to
+ * prefixes and the supplied encoder to encode characters in each of the path segments.
+ *
+ * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
+ * {@link Name#getNamespaceUri() namespace URIs} in the segment {@link Segment#getName() names}
+ * @param encoder the encoder to use, or null if the {@link #DEFAULT_ENCODER default encoder} should be used
+ * @return the encoded string
+ * @throws IllegalArgumentException if the namespace registry is null
+ * @see #getString(NamespaceRegistry)
+ */
+ public String getString( NamespaceRegistry namespaceRegistry,
+ TextEncoder encoder );
- /**
- * {@inheritDoc}
- */
- public boolean isSelfReference() {
- return true;
- }
-
- /**
- * {@inheritDoc}
- */
- public int compareTo( Segment that ) {
- if (this == that) return 0;
- int diff = this.getName().compareTo(that.getName());
- if (diff != 0) return diff;
- return this.getIndex() - that.getIndex();
- }
-
- /**
- * {@inheritDoc}
- */
- @Override
- public boolean equals( Object obj ) {
- if (this == obj) return true;
- if (obj instanceof Segment) {
- Segment that = (Segment)obj;
- if (!this.getName().equals(that.getName())) return false;
- return this.hasIndex() == that.hasIndex();
- }
- return false;
- }
-
- /**
- * {@inheritDoc}
- */
- @Override
- public String toString() {
- return SELF_NAME.toString();
- }
- };
-
- /**
- * Singleton instance of the path segment referencing a parent, provided as a convenience.
- */
- public static final Path.Segment PARENT_SEGMENT = new Path.Segment() {
-
- /**
- * {@inheritDoc}
- */
- public int getIndex() {
- return NO_INDEX;
- }
-
- /**
- * {@inheritDoc}
- */
- public Name getName() {
- return PARENT_NAME;
- }
-
- /**
- * {@inheritDoc}
- */
- public String getString() {
- return PARENT_NAME.getString();
- }
-
- /**
- * {@inheritDoc}
- */
- public String getString( TextEncoder encoder ) {
- return PARENT_NAME.getString(encoder);
- }
-
- /**
- * {@inheritDoc}
- */
- public String getString( NamespaceRegistry namespaceRegistry ) {
- return PARENT_NAME.getString(namespaceRegistry);
- }
-
- /**
- * {@inheritDoc}
- */
- public String getString( NamespaceRegistry namespaceRegistry, TextEncoder encoder ) {
- return PARENT_NAME.getString(namespaceRegistry, encoder);
- }
-
- /**
- * {@inheritDoc}
- */
- public boolean hasIndex() {
- return false;
- }
-
- /**
- * {@inheritDoc}
- */
- public boolean isParentReference() {
- return true;
- }
-
- /**
- * {@inheritDoc}
- */
- public boolean isSelfReference() {
- return false;
- }
-
- /**
- * {@inheritDoc}
- */
- public int compareTo( Segment that ) {
- if (this == that) return 0;
- int diff = this.getName().compareTo(that.getName());
- if (diff != 0) return diff;
- return this.getIndex() - that.getIndex();
- }
-
- /**
- * {@inheritDoc}
- */
- @Override
- public boolean equals( Object obj ) {
- if (this == obj) return true;
- if (obj instanceof Segment) {
- Segment that = (Segment)obj;
- if (!this.getName().equals(that.getName())) return false;
- return this.hasIndex() == that.hasIndex();
- }
- return false;
- }
-
- /**
- * {@inheritDoc}
- */
- @Override
- public String toString() {
- return PARENT_NAME.toString();
- }
- };
-
- /**
- * Return the number of segments in this path.
- * @return the number of path segments
- */
- public int size();
-
- /**
- * Return whether this path represents the root path.
- * @return true if this path is the root path, or false otherwise
- */
- public boolean isRoot();
-
- /**
- * Determine whether this path represents the same as the supplied path. This is equivalent to calling
- * <code>this.compareTo(other) == 0 </code>.
- * @param other the other path to compare with this path
- * @return true if the paths are equivalent, or false otherwise
- */
- public boolean isSame( Path other );
-
- /**
- * Determine whether this path is an ancestor of the supplied path. A path is considered an ancestor of another path if the
- * the ancestor path appears in its entirety at the beginning of the decendant path, and where the decendant path contains at
- * least one additional segment.
- * @param decendant the path that may be the decendant
- * @return true if this path is an ancestor of the supplied path, or false otherwise
- */
- public boolean isAncestorOf( Path decendant );
-
- /**
- * Determine whether this path is an decendant of the supplied path. A path is considered a decendant of another path if the
- * the decendant path starts exactly with the entire ancestor path but contains at least one additional segment.
- * @param ancestor the path that may be the ancestor
- * @return true if this path is an decendant of the supplied path, or false otherwise
- */
- public boolean isDecendantOf( Path ancestor );
-
- /**
- * Return whether this path is an absolute path. A path is either relative or {@link #isAbsolute() absolute}. An absolute
- * path starts with a "/".
- * @return true if the path is absolute, or false otherwise
- */
- public boolean isAbsolute();
-
- /**
- * Return whether this path is normalized and contains no "." segments and as few ".." segments as possible. For example, the
- * path "../a" is normalized, while "/a/b/c/../d" is not normalized.
- * @return true if this path is normalized, or false otherwise
- */
- public boolean isNormalized();
-
- /**
- * Get a normalized path with as many ".." segments and all "." resolved.
- * @return the normalized path, or this object if this path is already normalized
- * @throws InvalidPathException if the normalized form would result in a path with negative length (e.g., "/a/../../..")
- */
- public Path getNormalizedPath();
-
- /**
- * Get the canonical form of this path. A canonical path has is {@link #isAbsolute() absolute} and {@link #isNormalized()}.
- * @return the canonical path, or this object if it is already in its canonical form
- * @throws InvalidPathException if the path is not absolute and cannot be canonicalized
- */
- public Path getCanonicalPath();
-
- /**
- * Get a relative path from the supplied path to this path.
- * @param startingPath the path specifying the starting point for the new relative path; may not be null
- * @return the relative path
- * @throws IllegalArgumentException if the supplied path is null
- * @throws PathNotFoundException if both this path and the supplied path are not absolute
- */
- public Path relativeTo( Path startingPath );
-
- /**
- * Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path.
- * @param relativePath the relative path that is to be resolved against this path
- * @return the absolute and normalized path resolved from this path and the supplied absolute path
- * @throws IllegalArgumentException if the supplied path is null
- * @throws InvalidPathException if the this path is not absolute or if the supplied path is not relative.
- */
- public Path resolve( Path relativePath );
-
- /**
- * Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path.
- * @param absolutePath the absolute path to which this relative path should be resolve
- * @return the absolute path resolved from this path and the supplied absolute path
- * @throws IllegalArgumentException if the supplied path is null
- * @throws InvalidPathException if the supplied path is not absolute or if this path is not relative.
- */
- public Path resolveAgainst( Path absolutePath );
-
- /**
- * Return the path to the parent, or this path if it is the {@link #isRoot() root}. This is an efficient operation that does
- * not require copying any data.
- * @return the parent path, or this path if it is already the root
- */
- public Path getAncestor();
-
- /**
- * Return the path to the ancestor of the supplied degree. An ancestor of degree <code>x</code> is the path that is
- * <code>x</code> levels up along the path. For example, <code>degree = 0</code> returns this path, while
- * <code>degree = 1</code> returns the parent of this path, <code>degree = 2</code> returns the grandparent of this path,
- * and so on. Note that the result may be unexpected if this path is not {@link #isNormalized() normalized}, as a
- * non-normalized path contains ".." and "." segments.
- * @param degree
- * @return the ancestor of the supplied degree
- * @throws IllegalArgumentException if the degree is negative
- * @throws PathNotFoundException if the degree is greater than the {@link #size() length} of this path
- */
- public Path getAncestor( int degree );
-
- /**
- * Determine whether this path and the supplied path have the same immediate ancestor. In other words, this method determines
- * whether the node represented by this path is a sibling of the node represented by the supplied path.
- * @param that the other path
- * @return true if this path and the supplied path have the same immediate ancestor.
- * @throws IllegalArgumentException if the supplied path is null
- */
- public boolean hasSameAncestor( Path that );
-
- /**
- * Find the lowest common ancestor of this path and the supplied path.
- * @param that the other path
- * @return the lowest common ancestor, which may be the root path if there is no other.
- * @throws IllegalArgumentException if the supplied path is null
- */
- public Path getCommonAncestor( Path that );
-
- /**
- * Get the last segment in this path.
- * @return the last segment, or null if the path is empty
- */
- public Segment getLastSegment();
-
- /**
- * Get the segment at the supplied index.
- * @param index the index
- * @return the segment
- * @throws IndexOutOfBoundsException if the index is out of bounds
- */
- public Segment getSegment( int index );
-
- /**
- * Return a new path consisting of the segments starting at <code>beginIndex</code> index (inclusive). This is equivalent to
- * calling <code>path.subpath(beginIndex,path.size()-1)</code>.
- * @param beginIndex the beginning index, inclusive.
- * @return the specified subpath
- * @exception IndexOutOfBoundsException if the <code>beginIndex</code> is negative or larger than the length of this
- * <code>Path</code> object
- */
- public Path subpath( int beginIndex );
-
- /**
- * Return a new path consisting of the segments between the <code>beginIndex</code> index (inclusive) and the
- * <code>endIndex</code> index (exclusive).
- * @param beginIndex the beginning index, inclusive.
- * @param endIndex the ending index, exclusive.
- * @return the specified subpath
- * @exception IndexOutOfBoundsException if the <code>beginIndex</code> is negative, or <code>endIndex</code> is larger
- * than the length of this <code>Path</code> object, or <code>beginIndex</code> is larger than <code>endIndex</code>.
- */
- public Path subpath( int beginIndex, int endIndex );
-
- /**
- * {@inheritDoc}
- */
- public Iterator<Segment> iterator();
-
- /**
- * Obtain a copy of the segments in this path. None of the segments are encoded.
- * @return the array of segments as a copy
- */
- public Segment[] getSegmentsArray();
-
- /**
- * Get an unmodifiable list of the path segments.
- * @return the unmodifiable list of path segments; never null
- */
- public List<Segment> getSegmentsList();
-
- /**
- * Get the string form of the path. The {@link #DEFAULT_ENCODER default encoder} is used to encode characters in each of the
- * path segments.
- * @return the encoded string
- * @see #getString(TextEncoder)
- */
- public String getString();
-
- /**
- * Get the encoded string form of the path, using the supplied encoder to encode characters in each of the path segments.
- * @param encoder the encoder to use, or null if the {@link #DEFAULT_ENCODER default encoder} should be used
- * @return the encoded string
- * @see #getString()
- */
- public String getString( TextEncoder encoder );
-
- /**
- * Get the string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes.
- * The {@link #DEFAULT_ENCODER default encoder} is used to encode characters in each of the path segments.
- * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
- * {@link Name#getNamespaceUri() namespace URIs} in the segment {@link Segment#getName() names}
- * @return the encoded string
- * @throws IllegalArgumentException if the namespace registry is null
- * @see #getString(NamespaceRegistry,TextEncoder)
- */
- public String getString( NamespaceRegistry namespaceRegistry );
-
- /**
- * Get the encoded string form of the path, using the supplied namespace registry to convert the names' namespace URIs to
- * prefixes and the supplied encoder to encode characters in each of the path segments.
- * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
- * {@link Name#getNamespaceUri() namespace URIs} in the segment {@link Segment#getName() names}
- * @param encoder the encoder to use, or null if the {@link #DEFAULT_ENCODER default encoder} should be used
- * @return the encoded string
- * @throws IllegalArgumentException if the namespace registry is null
- * @see #getString(NamespaceRegistry)
- */
- public String getString( NamespaceRegistry namespaceRegistry, TextEncoder encoder );
-
}
More information about the dna-commits
mailing list