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 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
- Alphabetic
- By Inheritance
- Path
- Immutable
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
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 thisPath
.Appends a given relative
Path
to thisPath
. Alias forappend(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 thisPath
-
def
append(entry: Entry): Path
Appends a given
Entry
to thisPath
-
final
def
asInstanceOf[T0]: T0
- Definition Classes
- Any
-
def
clone(): AnyRef
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @native() @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
- Annotations
- @native()
-
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
- Annotations
- @native()
-
final
def
notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
-
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'sPath
, and therefore its parentPath
(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 thisPath
-
def
prepend(entry: Entry): Path
Prepends a given
Entry
to thisPath
-
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
- @native() @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 anOption
.