Class/Object

eu.cdevreeze.yaidom.indexed.IndexedClarkNode

Elem

Related Docs: object Elem | package IndexedClarkNode

Permalink

final class Elem[U <: Aux[U]] extends AbstractIndexedClarkElem[U] with Node with queryapi.Nodes.Elem

An element within its context. In other words, an element as a pair containing the root element (of an underlying element type) and a path (from that root element) to this element. More precisely, this element implementation contains an underlying root element, a Path, and an underlying element found from the root element following the Path. It also contains an optional URI of the containing document, if any.

See the documentation of the mixed-in query API trait(s) for more details on the uniform query API offered by this class.

An IndexedClarkElem(underlyingRootElem) can be seen as one immutable snapshot of an XML tree. All queries (using the ElemApi uniform query API) on that snapshot return results within the same snapshot. Take care not to mix up query results from different snapshots. (This could have been modeled in an alternative design of the class, but such a design has not been chosen.)

Using IndexedClarkElem objects, it is easy to get the ancestry or siblings of an element, as elements of the underlying element type.

Be careful not to create any memory leaks. After all, an element, even a leaf element, typically keeps the entire underlying document element tree as state. Hence the underlying document element tree will always remain in memory if at least one indexed element contains it in its state. (Yet with mutable org.w3c.dom element trees, it is also easy to cause memory leaks. See http://apmblog.compuware.com/2011/04/20/the-top-java-memory-problems-part-1/.)

The optional parent base URI is stored for very fast (optional) base URI computation. This is helpful in an XBRL context, where URI resolution against a base URI is typically a very frequent operation.

IndexedClarkElem examples

The following example code shows how to query for elements with a known ancestry, regardless of the element implementation, if efficiency is not important:

val iBookstore = IndexedClarkElem(bookstore)

val iTheBookAuthors =
  for {
    iAuthor <- iBookstore.filterElems(withLocalName("Author"))
    bookPath <- iAuthor.path.findAncestorPath(_.elementNameOption.map(_.localPart) == Some("Book"))
    iBook <- iBookstore.findElem(_.path == bookPath)
    if iBook.getChildElem(withLocalName("Title")).elem.text.startsWith("Programming in Scala")
  } yield iAuthor

IndexedClarkElem more formally

In order to use this class, this more formal section can safely be skipped.

The IndexedClarkElem class can be understood in a precise mathematical sense, as shown below.

Some properties of IndexedClarkElems are as follows:

// All elements (obtained from querying other elements) have the same rootElem

iElem.findAllElemsOrSelf.map(_.rootElem).distinct == List(iElem.rootElem)

iElem.findAllElemsOrSelf.map(_.underlyingRootElem).distinct == List(iElem.underlyingRootElem)

// The correspondence between rootElem, path and elem

iElem.findAllElemsOrSelf.forall(e => e.rootElem.findElemOrSelfByPath(e.path).get == e)

iElem.findAllElemsOrSelf.forall(e => e.underlyingRootElem.findElemOrSelfByPath(e.path).get == e.underlyingElem)

The correspondence between queries on IndexedClarkElems and the same queries on the underlying elements is as follows:

// Let p be a function from underlying element type E to Boolean

iElem.rootElem.filterElemsOrSelf(e => p(e.underlyingElem)).map(_.underlyingElem) ==
  iElem.underlyingRootElem.filterElemsOrSelf(p)

Analogous properties hold for the other query methods.

Linear Supertypes
Node, AbstractIndexedClarkElem[U], ClarkElemLike, HasText, HasEName, IsNavigable, ElemLike, IndexedClarkElemApi, ClarkElemApi, HasTextApi, HasENameApi, IsNavigableApi, ElemApi, AnyElemApi, queryapi.Nodes.Elem, CanBeDocumentChild, queryapi.Nodes.Node, AnyRef, Any
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. Elem
  2. Node
  3. AbstractIndexedClarkElem
  4. ClarkElemLike
  5. HasText
  6. HasEName
  7. IsNavigable
  8. ElemLike
  9. IndexedClarkElemApi
  10. ClarkElemApi
  11. HasTextApi
  12. HasENameApi
  13. IsNavigableApi
  14. ElemApi
  15. AnyElemApi
  16. Elem
  17. CanBeDocumentChild
  18. Node
  19. AnyRef
  20. Any
  1. Hide All
  2. Show all
Visibility
  1. Public
  2. All

Type Members

  1. type ThisElem = Elem[U]

    Permalink

    The element type itself.

    The element type itself. It must be restricted to a sub-type of the query API trait in question.

    Concrete element classes will restrict this type to that element class itself.

    Definition Classes
    Elem → AbstractIndexedClarkElem → ClarkElemLike → IsNavigable → ElemLike → IndexedClarkElemApi → ClarkElemApi → IsNavigableApi → ElemApi → AnyElemApi

Value Members

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

    Permalink
    Definition Classes
    AnyRef → Any

  2. final def ##(): Int

    Permalink
    Definition Classes
    AnyRef → Any

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

    Permalink
    Definition Classes
    AnyRef → Any

  4. final def \(p: (ThisElem) ⇒ Boolean): IndexedSeq[ThisElem]

    Permalink

    Shorthand for filterChildElems(p).

    Shorthand for filterChildElems(p). Use this shorthand only if the predicate is a short expression.

    Definition Classes
    ElemLike → ElemApi

  5. final def \@(expandedName: EName): Option[String]

    Permalink

    Shorthand for attributeOption(expandedName).

    Shorthand for attributeOption(expandedName).

    Definition Classes
    HasEName → HasENameApi

  6. final def \\(p: (ThisElem) ⇒ Boolean): IndexedSeq[ThisElem]

    Permalink

    Shorthand for filterElemsOrSelf(p).

    Shorthand for filterElemsOrSelf(p). Use this shorthand only if the predicate is a short expression.

    Definition Classes
    ElemLike → ElemApi

  7. final def \\!(p: (ThisElem) ⇒ Boolean): IndexedSeq[ThisElem]

    Permalink

    Shorthand for findTopmostElemsOrSelf(p).

    Shorthand for findTopmostElemsOrSelf(p). Use this shorthand only if the predicate is a short expression.

    Definition Classes
    ElemLike → ElemApi

  8. final def asInstanceOf[T0]: T0

    Permalink
    Definition Classes
    Any

  9. final def attribute(expandedName: EName): String

    Permalink

    Returns the value of the attribute with the given expanded name, and throws an exception otherwise.

    Returns the value of the attribute with the given expanded name, and throws an exception otherwise.

    Definition Classes
    HasEName → HasENameApi

  10. final def attributeOption(expandedName: EName): Option[String]

    Permalink

    Returns the value of the attribute with the given expanded name, if any, wrapped in an Option.

    Returns the value of the attribute with the given expanded name, if any, wrapped in an Option.

    Definition Classes
    HasEName → HasENameApi

  11. final def baseUri: URI

    Permalink

    Returns the base URI, falling back to the empty URI if absent.

    Returns the base URI, falling back to the empty URI if absent.

    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

  12. final def baseUriOption: Option[URI]

    Permalink

    Returns the optional base URI, computed from the document URI, if any, and the XML base attributes of the ancestors, if any.

    Returns the optional base URI, computed from the document URI, if any, and the XML base attributes of the ancestors, if any.

    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

  13. def clone(): AnyRef

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

  14. final def docUri: URI

    Permalink

    Returns the document URI, falling back to the empty URI if absent.

    Returns the document URI, falling back to the empty URI if absent.

    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

  15. val docUriOption: Option[URI]

    Permalink

    The optional document URI of the containing document, if any

    The optional document URI of the containing document, if any

    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

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

    Permalink
    Definition Classes
    AnyRef

  17. final def equals(obj: Any): Boolean

    Permalink
    Definition Classes
    Elem → AnyRef → Any

  18. final def filterChildElems(p: (ThisElem) ⇒ Boolean): IndexedSeq[ThisElem]

    Permalink

    Returns the child elements obeying the given predicate.

    Returns the child elements obeying the given predicate. This method could be defined as:

    def filterChildElems(p: ThisElem => Boolean): immutable.IndexedSeq[ThisElem] =
  this.findAllChildElems.filter(p)
    Definition Classes
    ElemLike → ElemApi

  19. final def filterElems(p: (ThisElem) ⇒ Boolean): IndexedSeq[ThisElem]

    Permalink

    Returns the descendant elements obeying the given predicate.

    Returns the descendant elements obeying the given predicate. This method could be defined as:

    this.findAllChildElems flatMap (_.filterElemsOrSelf(p))
    Definition Classes
    ElemLike → ElemApi

  20. final def filterElemsOrSelf(p: (ThisElem) ⇒ Boolean): IndexedSeq[ThisElem]

    Permalink

    Returns the descendant-or-self elements obeying the given predicate.

    Returns the descendant-or-self elements obeying the given predicate. This method could be defined as:

    def filterElemsOrSelf(p: ThisElem => Boolean): immutable.IndexedSeq[ThisElem] =
  Vector(this).filter(p) ++ (this.findAllChildElems flatMap (_.filterElemsOrSelf(p)))

    It can be proven that the result is equivalent to findAllElemsOrSelf filter p.

    Definition Classes
    ElemLike → ElemApi

  21. def finalize(): Unit

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

  22. final def findAllChildElems: IndexedSeq[ThisElem]

    Permalink

    Core method that returns all child elements, in the correct order.

    Core method that returns all child elements, in the correct order. Other operations can be defined in terms of this one.

    Definition Classes
    Elem → AbstractIndexedClarkElem → ElemLike → ElemApi

  23. final def findAllChildElemsWithPathEntries: IndexedSeq[(ThisElem, Entry)]

    Permalink

    Returns all child elements paired with their path entries.

    Returns all child elements paired with their path entries.

    This method is final, so more efficient implementations for sub-types are not supported. This implementation is only efficient if finding all child elements as well as computing their resolved names is efficient. That is not the case for DOM wrappers or Scala XML Elem wrappers (due to their expensive Scope computations). On the other hand, those wrapper element implementations are convenient, but not intended for heavy use in production. Hence, this method should typically be fast enough.

    Definition Classes
    ClarkElemLike → IsNavigable → IsNavigableApi

  24. final def findAllElems: IndexedSeq[ThisElem]

    Permalink

    Returns all descendant elements (not including this element).

    Returns all descendant elements (not including this element). This method could be defined as filterElems { e => true }. Equivalent to findAllElemsOrSelf.drop(1).

    Definition Classes
    ElemLike → ElemApi

  25. final def findAllElemsOrSelf: IndexedSeq[ThisElem]

    Permalink

    Returns this element followed by all descendant elements (that is, the descendant-or-self elements).

    Returns this element followed by all descendant elements (that is, the descendant-or-self elements). This method could be defined as filterElemsOrSelf { e => true }.

    Definition Classes
    ElemLike → ElemApi

  26. final def findAttributeByLocalName(localName: String): Option[String]

    Permalink

    Returns the first found attribute value of an attribute with the given local name, if any, wrapped in an Option.

    Returns the first found attribute value of an attribute with the given local name, if any, wrapped in an Option. Because of differing namespaces, it is possible that more than one such attribute exists, although this is not often the case.

    Definition Classes
    HasEName → HasENameApi

  27. final def findChildElem(p: (ThisElem) ⇒ Boolean): Option[ThisElem]

    Permalink

    Returns the first found child element obeying the given predicate, if any, wrapped in an Option.

    Returns the first found child element obeying the given predicate, if any, wrapped in an Option. This method could be defined as filterChildElems(p).headOption.

    Definition Classes
    ElemLike → ElemApi

  28. final def findChildElemByPathEntry(entry: Entry): Option[ThisElem]

    Permalink

    Finds the child element with the given Path.Entry (where this element is the root), if any, wrapped in an Option.

    Finds the child element with the given Path.Entry (where this element is the root), if any, wrapped in an Option.

    This method is final, so more efficient implementations for sub-types are not supported. This implementation is only efficient if finding all child elements as well as computing their resolved names is efficient. That is not the case for DOM wrappers or Scala XML Elem wrappers (due to their expensive Scope computations). On the other hand, those wrapper element implementations are convenient, but not intended for heavy use in production. Hence, this method should typically be fast enough.

    Definition Classes
    ClarkElemLike → IsNavigable → IsNavigableApi

  29. final def findElem(p: (ThisElem) ⇒ Boolean): Option[ThisElem]

    Permalink

    Returns the first found (topmost) descendant element obeying the given predicate, if any, wrapped in an Option.

    Returns the first found (topmost) descendant element obeying the given predicate, if any, wrapped in an Option. This method could be defined as filterElems(p).headOption.

    Definition Classes
    ElemLike → ElemApi

  30. final def findElemOrSelf(p: (ThisElem) ⇒ Boolean): Option[ThisElem]

    Permalink

    Returns the first found (topmost) descendant-or-self element obeying the given predicate, if any, wrapped in an Option.

    Returns the first found (topmost) descendant-or-self element obeying the given predicate, if any, wrapped in an Option. This method could be defined as filterElemsOrSelf(p).headOption.

    Definition Classes
    ElemLike → ElemApi

  31. final def findElemOrSelfByPath(path: Path): Option[ThisElem]

    Permalink

    Finds the element with the given Path (where this element is the root), if any, wrapped in an Option.

    Finds the element with the given Path (where this element is the root), if any, wrapped in an Option.

    That is, returns:

    findReverseAncestryOrSelfByPath(path).map(_.last)

    Note that for each non-empty Path, we have:

    findElemOrSelfByPath(path) == findChildElemByPathEntry(path.firstEntry) flatMap (e => e.findElemOrSelfByPath(path.withoutFirstEntry))
    Definition Classes
    IsNavigable → IsNavigableApi

  32. final def findReverseAncestryOrSelfByPath(path: Path): Option[IndexedSeq[ThisElem]]

    Permalink

    Finds the reversed ancestry-or-self of the element with the given Path (where this element is the root), wrapped in an Option.

    Finds the reversed ancestry-or-self of the element with the given Path (where this element is the root), wrapped in an Option. None is returned if no element can be found at the given Path.

    Hence, the resulting element collection, if any, starts with this element and ends with the element at the given Path, relative to this element.

    This method comes in handy for (efficiently) computing base URIs, where the (reverse) ancestry-or-self is needed as input.

    Definition Classes
    IsNavigable → IsNavigableApi

  33. final def findTopmostElems(p: (ThisElem) ⇒ Boolean): IndexedSeq[ThisElem]

    Permalink

    Returns the descendant elements obeying the given predicate that have no ancestor obeying the predicate.

    Returns the descendant elements obeying the given predicate that have no ancestor obeying the predicate. This method could be defined as:

    this.findAllChildElems flatMap (_.findTopmostElemsOrSelf(p))
    Definition Classes
    ElemLike → ElemApi

  34. final def findTopmostElemsOrSelf(p: (ThisElem) ⇒ Boolean): IndexedSeq[ThisElem]

    Permalink

    Returns the descendant-or-self elements obeying the given predicate, such that no ancestor obeys the predicate.

    Returns the descendant-or-self elements obeying the given predicate, such that no ancestor obeys the predicate. This method could be defined as:

    def findTopmostElemsOrSelf(p: ThisElem => Boolean): immutable.IndexedSeq[ThisElem] =
  if (p(this)) Vector(this)
  else (this.findAllChildElems flatMap (_.findTopmostElemsOrSelf(p)))
    Definition Classes
    ElemLike → ElemApi

  35. final def getChildElem(p: (ThisElem) ⇒ Boolean): ThisElem

    Permalink

    Returns the single child element obeying the given predicate, and throws an exception otherwise.

    Returns the single child element obeying the given predicate, and throws an exception otherwise. This method could be defined as findChildElem(p).get.

    Definition Classes
    ElemLike → ElemApi

  36. final def getChildElemByPathEntry(entry: Entry): ThisElem

    Permalink

    Returns (the equivalent of) findChildElemByPathEntry(entry).get

    Returns (the equivalent of) findChildElemByPathEntry(entry).get

    Definition Classes
    IsNavigable → IsNavigableApi

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

    Permalink
    Definition Classes
    AnyRef → Any

  38. final def getElemOrSelfByPath(path: Path): ThisElem

    Permalink

    Returns (the equivalent of) findElemOrSelfByPath(path).get

    Returns (the equivalent of) findElemOrSelfByPath(path).get

    Definition Classes
    IsNavigable → IsNavigableApi

  39. final def getReverseAncestryOrSelfByPath(path: Path): IndexedSeq[ThisElem]

    Permalink

    Returns (the equivalent of) findReverseAncestryOrSelfByPath(path).get

    Returns (the equivalent of) findReverseAncestryOrSelfByPath(path).get

    Definition Classes
    IsNavigable → IsNavigableApi

  40. final def hashCode(): Int

    Permalink
    Definition Classes
    Elem → AnyRef → Any

  41. final def isInstanceOf[T0]: Boolean

    Permalink
    Definition Classes
    Any

  42. final def localName: String

    Permalink

    The local name, that is, the local part of the EName

    The local name, that is, the local part of the EName

    Definition Classes
    HasEName → HasENameApi

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

    Permalink
    Definition Classes
    AnyRef

  44. final def normalizedText: String

    Permalink

    Returns XmlStringUtils.normalizeString(text).

    Returns XmlStringUtils.normalizeString(text).

    Definition Classes
    HasText → HasTextApi

  45. final def notify(): Unit

    Permalink
    Definition Classes
    AnyRef

  46. final def notifyAll(): Unit

    Permalink
    Definition Classes
    AnyRef

  47. final def parentBaseUriOption: Option[URI]

    Permalink

    Returns the optional parent element base URI, computed from the document URI, if any, and the XML base attributes of the ancestors, if any.

    Returns the optional parent element base URI, computed from the document URI, if any, and the XML base attributes of the ancestors, if any.

    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

  48. val path: Path

    Permalink

    The path of this element, relative to the root element

    The path of this element, relative to the root element

    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

  49. final def resolvedAttributes: Iterable[(EName, String)]

    Permalink

    The resolved attributes of the element as mapping from ENames to values

    The resolved attributes of the element as mapping from ENames to values

    Definition Classes
    AbstractIndexedClarkElem → HasENameApi

  50. final def resolvedName: EName

    Permalink

    The EName of the element

    The EName of the element

    Definition Classes
    AbstractIndexedClarkElem → HasENameApi

  51. final def reverseAncestry: IndexedSeq[ThisElem]

    Permalink

    Returns the reversed ancestor elements.

    Returns the reversed ancestor elements. That is, returns:

    reverseAncestryOrSelf.init
    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

  52. final def reverseAncestryENames: IndexedSeq[EName]

    Permalink

    Returns the ENames of the ancestry reversed, starting with the root element and ending with the parent of this element, if any.

    Returns the ENames of the ancestry reversed, starting with the root element and ending with the parent of this element, if any.

    That is, returns:

    reverseAncestryOrSelfENames.dropRight(1)
    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

  53. final def reverseAncestryOrSelf: IndexedSeq[ThisElem]

    Permalink

    Returns the reversed ancestor-or-self elements.

    Returns the reversed ancestor-or-self elements. That is, returns:

    rootElem.findReverseAncestryOrSelfByPath(path).get
    Definition Classes
    Elem → AbstractIndexedClarkElem → IndexedClarkElemApi

  54. final def reverseAncestryOrSelfENames: IndexedSeq[EName]

    Permalink

    Returns the ENames of the ancestry-or-self reversed, starting with the root element and ending with this element.

    Returns the ENames of the ancestry-or-self reversed, starting with the root element and ending with this element.

    That is, returns:

    rootElem.resolvedName +: path.entries.map(_.elementName)

    This is equal to:

    reverseAncestryOrSelf.map(_.resolvedName)
    Definition Classes
    AbstractIndexedClarkElem → IndexedClarkElemApi

  55. final def rootElem: ThisElem

    Permalink

    The root element

    The root element

    Definition Classes
    Elem → AbstractIndexedClarkElem → IndexedClarkElemApi

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

    Permalink
    Definition Classes
    AnyRef

  57. final def text: String

    Permalink

    Returns the concatenation of the text values of (the implicit) text children, including whitespace and CData.

    Returns the concatenation of the text values of (the implicit) text children, including whitespace and CData. Non-text children are ignored. If there are no text children, the empty string is returned.

    Therefore, element children are ignored and do not contribute to the resulting text string.

    Definition Classes
    AbstractIndexedClarkElem → HasTextApi

  58. def thisElem: ThisElem

    Permalink

    This element itself.

    This element itself.

    Definition Classes
    Elem → AnyElemApi

  59. def toString(): String

    Permalink
    Definition Classes
    AnyRef → Any

  60. final def trimmedText: String

    Permalink

    Returns text.trim.

    Returns text.trim.

    Definition Classes
    HasText → HasTextApi

  61. val underlyingElem: U

    Permalink
    Definition Classes
    AbstractIndexedClarkElem

  62. val underlyingRootElem: U

    Permalink
    Definition Classes
    AbstractIndexedClarkElem

  63. final def wait(): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

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

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

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

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

Deprecated Value Members

  1. final def elem: U

    Permalink
    Definition Classes
    AbstractIndexedClarkElem
    Annotations
    @deprecated
    Deprecated

    (Since version 1.6.0) Use 'underlyingElem' instead

Inherited from Node

Inherited from AbstractIndexedClarkElem[U]

Inherited from ClarkElemLike

Inherited from HasText

Inherited from HasEName

Inherited from IsNavigable

Inherited from ElemLike

Inherited from IndexedClarkElemApi

Inherited from ClarkElemApi

Inherited from HasTextApi

Inherited from HasENameApi

Inherited from IsNavigableApi

Inherited from ElemApi

Inherited from AnyElemApi

Inherited from queryapi.Nodes.Elem

Inherited from CanBeDocumentChild

Inherited from queryapi.Nodes.Node

Inherited from AnyRef

Inherited from Any

Ungrouped