Path

Unique identification of a descendant (or self) Elem given a root Elem. It represents a unique path to an element, given a root element, independent of other types of nodes, as if the XML tree only consists of elements.

In other words, a Path is a sequence of instructions, each of them stating how to get to a specific child element. Each such instruction is a Path.Entry. So Paths do not contain the root element, and we can talk about Paths in isolation, without referring to any specific DOM-like tree.

For example, consider the following XML:

<book:Bookstore xmlns:book="http://bookstore/book" xmlns:auth="http://bookstore/author">
  <book:Book ISBN="978-0321356680" Price="35" Edition="2">
    <book:Title>Effective Java (2nd Edition)</book:Title>
    <book:Authors>
      <auth:Author>
        <auth:First_Name>Joshua</auth:First_Name>
        <auth:Last_Name>Bloch</auth:Last_Name>
      </auth:Author>
    </book:Authors>
  </book:Book>
  <book:Book ISBN="978-0981531649" Price="35" Edition="2">
    <book:Title>Programming in Scala: A Comprehensive Step-by-Step Guide, 2nd Edition</book:Title>
    <book:Authors>
      <auth:Author>
        <auth:First_Name>Martin</auth:First_Name>
        <auth:Last_Name>Odersky</auth:Last_Name>
      </auth:Author>
      <auth:Author>
        <auth:First_Name>Lex</auth:First_Name>
        <auth:Last_Name>Spoon</auth:Last_Name>
      </auth:Author>
      <auth:Author>
        <auth:First_Name>Bill</auth:First_Name>
        <auth:Last_Name>Venners</auth:Last_Name>
      </auth:Author>
    </book:Authors>
  </book:Book>
</book:Bookstore>

Then the last name of the first author of the Scala book (viz. Odersky) has the following path:

Path.from(
  EName("{http://bookstore/book}Book") -> 1,
  EName("{http://bookstore/book}Authors") -> 0,
  EName("{http://bookstore/author}Author") -> 0,
  EName("{http://bookstore/author}Last_Name") -> 0
)

or:

PathBuilder.from(
  QName("book:Book") -> 1,
  QName("book:Authors") -> 0,
  QName("auth:Author") -> 0,
  QName("auth:Last_Name") -> 0).build(Scope.from("book" -> "http://bookstore/book", "auth" -> "http://bookstore/author"))

Path instances are useful when navigating (see eu.cdevreeze.yaidom.queryapi.IsNavigable), and in "functional updates" (see eu.cdevreeze.yaidom.queryapi.UpdatableElemLike).

An eu.cdevreeze.yaidom.core.Path corresponds to one and only one canonical path of the element (modulo prefix names), which is the corresponding (canonical) XPath expression. See http://ns.inria.org/active-tags/glossary/glossary.html#canonical-path. There is one catch, though. The Path does not know the root element name, so that is not a part of the corresponding canonical XPath expression. See the documentation of method toResolvedCanonicalXPath.

The Path contains an IndexedSeq of path entries for a specific child element, grandchild element etc., but the (root) element itself is referred to by an empty list of path entries.

As an alternative to class Path, each element in a tree could be uniquely identified by "path entries" that only contained a child index instead of an element name plus element child index (of element children with the given name). Yet that would be far less easy to use. Hence Path.Entry instances each contain an element name plus index.

Self Type: Path

Linear Supertypes

Immutable, AnyRef, Any

Instance Constructors

new Path(entries: IndexedSeq[Entry])

Value Members

final def !=(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def ##(): Int

Definition Classes
AnyRef → Any
def ++(other: Path): Path

Appends a given relative Path to this Path.
Appends a given relative Path to this Path. Alias for append(other).
final def ==(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def ancestorOrSelfPaths: IndexedSeq[Path]

Returns the ancestor-or-self paths, starting with this path, then the parent (if any), and ending with the root path
def ancestorPaths: IndexedSeq[Path]

Returns the ancestor paths, starting with the parent path (if any), and ending with the root path
def append(other: Path): Path

Appends a given relative Path to this Path
def append(entry: Entry): Path

Appends a given Entry to this Path
final def asInstanceOf[T0]: T0

Definition Classes
Any
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
def containsName(ename: EName): Boolean

Convenience method returning true if at least one entry has the given element name
def elementNameOption: Option[EName]

Returns the element name (as EName) of the last path entry, if any, wrapped in an Option
def endsWithName(ename: EName): Boolean

Convenience method returning true if the last entry (if any) has the given element name
val entries: IndexedSeq[Entry]
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(obj: Any): Boolean

Definition Classes
Path → AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
def findAncestorOrSelfPath(p: (Path) ⇒ Boolean): Option[Path]

Returns ancestorOrSelfPaths find { path => p(path) }
def findAncestorPath(p: (Path) ⇒ Boolean): Option[Path]

Returns ancestorPaths find { path => p(path) }
def firstEntry: Entry

Returns the first entry, if any, and throws an exception otherwise
def firstEntryOption: Option[Entry]

Returns the first entry, if any, wrapped in an Option
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def hashCode(): Int

Definition Classes
Path → AnyRef → Any
def isEmpty: Boolean

Returns true if this is the empty Path, so if it has no entries
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
def lastEntry: Entry

Returns the last entry, if any, and throws an exception otherwise
def lastEntryOption: Option[Entry]

Returns the last entry, if any, wrapped in an Option
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def nonEmpty: Boolean

Returns true if this is not the empty Path, so if it has at least one entry
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
def parentPath: Path

Like parentPathOption, but unwrapping the result (or throwing an exception otherwise)
def parentPathOption: Option[Path]

Gets the parent path (if any, because the empty path has no parent) wrapped in an Option.
Gets the parent path (if any, because the empty path has no parent) wrapped in an Option.
This method shows much of the reason why class Path exists. If we know an element's Path, and therefore its parent Path (using this method), then we can obtain the parent element by following the parent path from the root of the tree.
def prepend(other: Path): Path

Prepends a given Path to this Path
def prepend(entry: Entry): Path

Prepends a given Entry to this Path
def skippingPath(otherPath: Path): Path

Returns the Path resulting from skipping ("consuming") the entries of the parameter Path.
Returns the Path resulting from skipping ("consuming") the entries of the parameter Path. If this Path does not start with the parameter Path, an exception is thrown.
def startsWithName(ename: EName): Boolean

Convenience method returning true if the first entry (if any) has the given element name
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def toResolvedCanonicalXPath: String

Returns the corresponding "resolved" canonical XPath, but modified for the root element (which is unknown in the Path).
Returns the corresponding "resolved" canonical XPath, but modified for the root element (which is unknown in the Path). The modification is that the root element is written as a slash followed by an asterisk. Unlike real XPath, QNames are resolved as ENames, and shown in James Clark notation for ENames.
See http://ns.inria.org/active-tags/glossary/glossary.html#canonical-path for (real) canonical XPath.
The "resolved" XPath-like expressions returned by this method need no context to convey their semantics, unlike real XPath expressions (canonical or otherwise). This is an important advantage of these expressions, in spite of their relative verbosity. A good use case is error reporting about parts of XML documents. For example, Saxon-EE uses a similar notation for error reporting (in XML format) in its schema validator.
def toString(): String

Definition Classes
Path → AnyRef → Any
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
def withoutFirstEntry: Path

Like withoutFirstEntryOption, but unwrapping the result (or throwing an exception otherwise)
def withoutFirstEntryOption: Option[Path]

Returns the Path with the first path entry (if any) removed, wrapped in an Option.

Related Docs: object Path | package core

final class Path extends Immutable

Instance Constructors

new Path(entries: IndexedSeq[Entry])

Value Members

final def !=(arg0: Any): Boolean

final def ##(): Int

def ++(other: Path): Path

final def ==(arg0: Any): Boolean

def ancestorOrSelfPaths: IndexedSeq[Path]

def ancestorPaths: IndexedSeq[Path]

def append(other: Path): Path

def append(entry: Entry): Path

final def asInstanceOf[T0]: T0

def clone(): AnyRef

def containsName(ename: EName): Boolean

def elementNameOption: Option[EName]

def endsWithName(ename: EName): Boolean

val entries: IndexedSeq[Entry]

final def eq(arg0: AnyRef): Boolean

def equals(obj: Any): Boolean

def finalize(): Unit

def findAncestorOrSelfPath(p: (Path) ⇒ Boolean): Option[Path]

def findAncestorPath(p: (Path) ⇒ Boolean): Option[Path]

def firstEntry: Entry

def firstEntryOption: Option[Entry]

final def getClass(): Class[_]

def hashCode(): Int

def isEmpty: Boolean

final def isInstanceOf[T0]: Boolean

def lastEntry: Entry

def lastEntryOption: Option[Entry]

final def ne(arg0: AnyRef): Boolean

def nonEmpty: Boolean

final def notify(): Unit

final def notifyAll(): Unit

def parentPath: Path

def parentPathOption: Option[Path]

def prepend(other: Path): Path

def prepend(entry: Entry): Path

def skippingPath(otherPath: Path): Path

def startsWithName(ename: EName): Boolean

final def synchronized[T0](arg0: ⇒ T0): T0

def toResolvedCanonicalXPath: String

def toString(): String

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

def withoutFirstEntry: Path

def withoutFirstEntryOption: Option[Path]

Inherited from Immutable

Inherited from AnyRef

Inherited from Any

Ungrouped