eu.cdevreeze.yaidom.core

Path

final class Path extends Immutable

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 toCanonicalXPath.

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
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. Path
  2. Immutable
  3. AnyRef
  4. Any
  1. Hide All
  2. Show all
Learn more about member selection
Visibility
  1. Public
  2. All

Instance Constructors

  1. new Path(entries: IndexedSeq[Entry])

Value Members

  1. final def !=(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any

  2. final def ##(): Int

    Definition Classes
    AnyRef → Any

  3. def ++(other: Path): Path

    Appends a given relative Path to this Path.

    Appends a given relative Path to this Path. Alias for append(other).

  4. final def ==(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any

  5. 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

  6. def ancestorPaths: IndexedSeq[Path]

    Returns the ancestor paths, starting with the parent path (if any), and ending with the root path

  7. def append(other: Path): Path

    Appends a given relative Path to this Path

  8. def append(entry: Entry): Path

    Appends a given Entry to this Path

  9. final def asInstanceOf[T0]: T0

    Definition Classes
    Any

  10. def clone(): AnyRef

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  11. def containsName(ename: EName): Boolean

    Convenience method returning true if at least one entry has the given element name

  12. def elementNameOption: Option[EName]

    Returns the element name (as EName) of the last path entry, if any, wrapped in an Option

  13. def endsWithName(ename: EName): Boolean

    Convenience method returning true if the last entry (if any) has the given element name

  14. val entries: IndexedSeq[Entry]

  15. final def eq(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  16. def equals(obj: Any): Boolean

    Definition Classes
    Path → AnyRef → Any

  17. def finalize(): Unit

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )

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

    Returns ancestorOrSelfPaths find { path => p(path) }

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

    Returns ancestorPaths find { path => p(path) }

  20. def firstEntry: Entry

    Returns the first entry, if any, and throws an exception otherwise

  21. def firstEntryOption: Option[Entry]

    Returns the first entry, if any, wrapped in an Option

  22. final def getClass(): Class[_]

    Definition Classes
    AnyRef → Any

  23. def hashCode(): Int

    Definition Classes
    Path → AnyRef → Any

  24. final def isInstanceOf[T0]: Boolean

    Definition Classes
    Any

  25. def isRoot: Boolean

    Returns true if this is the root Path, so if it has no entries

  26. def lastEntry: Entry

    Returns the last entry, if any, and throws an exception otherwise

  27. def lastEntryOption: Option[Entry]

    Returns the last entry, if any, wrapped in an Option

  28. final def ne(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  29. final def notify(): Unit

    Definition Classes
    AnyRef

  30. final def notifyAll(): Unit

    Definition Classes
    AnyRef

  31. def parentPath: Path

    Like parentPathOption, but unwrapping the result (or throwing an exception otherwise)

  32. def parentPathOption: Option[Path]

    Gets the parent path (if any, because the root path has no parent) wrapped in an Option.

    Gets the parent path (if any, because the root 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.

  33. def prepend(other: Path): Path

    Prepends a given Path to this Path

  34. def prepend(entry: Entry): Path

    Prepends a given Entry to this Path

  35. def startsWithName(ename: EName): Boolean

    Convenience method returning true if the first entry (if any) has the given element name

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

    Definition Classes
    AnyRef

  37. def toCanonicalXPath(scope: Scope): String

    Given an invertible Scope, returns the corresponding canonical XPath, but modified for the root element (which is unknown in the Path).

    Given an invertible Scope, returns the corresponding 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.

    See http://ns.inria.org/active-tags/glossary/glossary.html#canonical-path.

  38. def toString(): String

    Definition Classes
    Path → AnyRef → Any

  39. final def wait(): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

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

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  41. final def wait(arg0: Long): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  42. def withoutFirstEntry: Path

    Like withoutFirstEntryOption, but unwrapping the result (or throwing an exception otherwise)

  43. def withoutFirstEntryOption: Option[Path]

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

Inherited from Immutable

Inherited from AnyRef

Inherited from Any

Ungrouped