eu.cdevreeze.yaidom

ElemApi

trait ElemApi[E <: ElemApi[E]] extends ParentElemApi[E]

This is the best known part of the yaidom uniform query API. It is a sub-trait of trait eu.cdevreeze.yaidom.ParentElemApi. Many DOM-like element implementations in yaidom mix in this trait (indirectly, because some implementing sub-trait is mixed in), thus sharing this query API.

This trait typically does not show up in application code using yaidom, yet its (uniform) API does. Hence, it makes sense to read the documentation of this trait, knowing that the API is offered by multiple element implementations.

This trait is purely abstract. The most common implementation of this trait is eu.cdevreeze.yaidom.ElemLike. That trait only knows about elements (and not about other nodes), and only knows the following about elements:

Using this minimal knowledge alone, that trait offers methods to query for descendant elements, descendant-or-self methods, or sub-collections thereof. Element sub-collections can be queried by passing a predicate (as offered by the super-trait), or simply by passing an element EName.

It is this minimal knowledge that makes this API uniform. On the one hand, that minimal knowledge is enough knowledge for providing a rather rich ElemApi query API, and on the other hand, that minimal knowledge is so fundamental to DOM-like elements that most yaidom DOM-like element implementations indeed offer this API.

This query API leverages the Scala Collections API. Query results can be manipulated using the Collections API, and the query API implementation (in ElemLike) uses the Collections API internally.

ElemApi examples

It is easy to show that this small query API is already very useful. Consider the following example 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>

Suppose this XML has been parsed into eu.cdevreeze.yaidom.Elem instance bookstoreElem. Then we can perform the following queries:

val bookstoreNamespace = "http://bookstore/book"
val authorNamespace = "http://bookstore/author"
require(bookstoreElem.resolvedName == EName(bookstoreNamespace, "Bookstore"))

val cheapBookElems =
  for {
    bookElem <- bookstoreElem \ EName(bookstoreNamespace, "Book")
    price <- bookElem \@ EName("Price")
    if price.toInt < 90
  } yield bookElem

val cheapBookAuthors = {
  val result =
    for {
      cheapBookElem <- cheapBookElems
      authorElem <- cheapBookElem \\ EName(authorNamespace, "Author")
    } yield {
      val firstName = authorElem \ EName(authorNamespace, "First_Name") map (_.text) mkString ""
      val lastName = authorElem \ EName(authorNamespace, "Last_Name") map (_.text) mkString ""
      (firstName + " " + lastName).trim
    }
  result.toSet
}

Using more ParentElemApi query methods, we could instead have written:

val cheapBookElems =
  for {
    bookElem <- bookstoreElem \ (e => e.resolvedName == EName(bookstoreNamespace, "Book"))
    price <- bookElem \@ EName("Price")
    if price.toInt < 90
  } yield bookElem

val cheapBookAuthors = {
  val result =
    for {
      cheapBookElem <- cheapBookElems
      authorElem <- cheapBookElem \\ (e => e.resolvedName == EName(authorNamespace, "Author"))
    } yield {
      val firstName =
        authorElem \ (e => e.resolvedName == EName(authorNamespace, "First_Name")) map (_.text) mkString ""
      val lastName =
        authorElem \ (e => e.resolvedName == EName(authorNamespace, "Last_Name")) map (_.text) mkString ""
      (firstName + " " + lastName).trim
    }
  result.toSet
}

By replacing operator notation, we get the following equivalent queries:

val cheapBookElems =
  for {
    bookElem <- bookstoreElem filterChildElems (e => e.resolvedName == EName(bookstoreNamespace, "Book"))
    price <- bookElem.attributeOption(EName("Price"))
    if price.toInt < 90
  } yield bookElem

val cheapBookAuthors = {
  val result =
    for {
      cheapBookElem <- cheapBookElems
      authorElem <- cheapBookElem filterElemsOrSelf (e => e.resolvedName == EName(authorNamespace, "Author"))
    } yield {
      val firstName =
        authorElem filterChildElems (e => e.resolvedName == EName(authorNamespace, "First_Name")) map (_.text) mkString ""
      val lastName =
        authorElem filterChildElems (e => e.resolvedName == EName(authorNamespace, "Last_Name")) map (_.text) mkString ""
      (firstName + " " + lastName).trim
    }
  result.toSet
}

The queries above only use the following knowledge about the DOM-like elements: they offer the ElemApi and HasText APIs. As a consequence, the exact same queries work for other DOM-like element implementations as well. That is, bookstoreElem could instead have been of type eu.cdevreeze.yaidom.indexed.Elem, eu.cdevreeze.yaidom.resolved.Elem, eu.cdevreeze.yaidom.dom.DomElem or eu.cdevreeze.yaidom.scalaxml.ScalaXmlElem. Hence the ElemApi trait indeed offers a uniform element query API.

ElemApi more formally

From a formal point of view, ElemApi offers little of interest. After all, given super-trait ParentElemApi, as well as methods resolvedName and resolvedAttributes, the other methods are trivial to implement.

For example, the semantics of method filterChildElems (taking an EName) is trivially defined as follows:

elem.filterChildElems(ename) == elem.filterChildElems(e => e.resolvedName == ename)

Other ParentElemApi methods taking a predicate also have a counterpart in ElemApi taking just an EName, and the latter ones are trivially defined in terms of the former ones, just like filterChildElems (taking an EName) above. After all, parent trait ParentElemApi is the foundation of the yaidom query API, yet sub-trait ElemApi makes it much more useful in practice, by adding some knowledge about element names and attributes.

E

The captured element subtype

Self Type
E
Linear Supertypes
ParentElemApi[E], AnyRef, Any
Known Subclasses
DomElem, Elem, Elem, Elem, Elem, ElemLike, NavigableElemApi, NavigableElemLike, PathAwareElemApi, PathAwareElemLike, ScalaXmlElem, UpdatableElemApi, UpdatableElemLike
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. ElemApi
  2. ParentElemApi
  3. AnyRef
  4. Any
  1. Hide All
  2. Show all
Learn more about member selection
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def \(expandedName: EName): IndexedSeq[E]

    Shorthand for filterChildElems(expandedName).

  2. abstract def \(p: (E) ⇒ Boolean): IndexedSeq[E]

    Shorthand for filterChildElems(p).

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

    Definition Classes
    ParentElemApi

  3. abstract def \@(expandedName: EName): Option[String]

    Shorthand for attributeOption(expandedName)

  4. abstract def \\(expandedName: EName): IndexedSeq[E]

    Shorthand for filterElemsOrSelf(expandedName).

  5. abstract def \\(p: (E) ⇒ Boolean): IndexedSeq[E]

    Shorthand for filterElemsOrSelf(p).

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

    Definition Classes
    ParentElemApi

  6. abstract def \\!(expandedName: EName): IndexedSeq[E]

    Shorthand for findTopmostElemsOrSelf(expandedName).

  7. abstract def \\!(p: (E) ⇒ Boolean): IndexedSeq[E]

    Shorthand for findTopmostElemsOrSelf(p).

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

    Definition Classes
    ParentElemApi

  8. abstract def attribute(expandedName: EName): String

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

  9. abstract def attributeOption(expandedName: EName): Option[String]

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

  10. abstract def filterChildElems(expandedName: EName): IndexedSeq[E]

    Returns the child elements with the given expanded name

  11. abstract def filterChildElems(p: (E) ⇒ Boolean): IndexedSeq[E]

    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: E => Boolean): immutable.IndexedSeq[E] =
this.findAllChildElems.filter(p)
    Definition Classes
    ParentElemApi

  12. abstract def filterElems(expandedName: EName): IndexedSeq[E]

    Returns the descendant elements with the given expanded name

  13. abstract def filterElems(p: (E) ⇒ Boolean): IndexedSeq[E]

    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
    ParentElemApi

  14. abstract def filterElemsOrSelf(expandedName: EName): IndexedSeq[E]

    Returns the descendant-or-self elements that have the given expanded name

  15. abstract def filterElemsOrSelf(p: (E) ⇒ Boolean): IndexedSeq[E]

    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: E => Boolean): immutable.IndexedSeq[E] =
Vector(this).filter(p) ++ (this.findAllChildElems flatMap (_.filterElemsOrSelf(p)))

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

    Definition Classes
    ParentElemApi

  16. abstract def findAllChildElems: IndexedSeq[E]

    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
    ParentElemApi

  17. abstract def findAllElems: IndexedSeq[E]

    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
    ParentElemApi

  18. abstract def findAllElemsOrSelf: IndexedSeq[E]

    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
    ParentElemApi

  19. abstract def findAttributeByLocalName(localName: String): Option[String]

    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.

  20. abstract def findChildElem(expandedName: EName): Option[E]

    Returns the first found child element with the given expanded name, if any, wrapped in an Option

  21. abstract def findChildElem(p: (E) ⇒ Boolean): Option[E]

    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
    ParentElemApi

  22. abstract def findElem(expandedName: EName): Option[E]

    Returns the first found (topmost) descendant element with the given expanded name, if any, wrapped in an Option

  23. abstract def findElem(p: (E) ⇒ Boolean): Option[E]

    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
    ParentElemApi

  24. abstract def findElemOrSelf(expandedName: EName): Option[E]

    Returns the first found (topmost) descendant-or-self element with the given expanded name, if any, wrapped in an Option

  25. abstract def findElemOrSelf(p: (E) ⇒ Boolean): Option[E]

    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
    ParentElemApi

  26. abstract def findTopmostElems(expandedName: EName): IndexedSeq[E]

    Returns the descendant elements with the given expanded name that have no ancestor with the same name

  27. abstract def findTopmostElems(p: (E) ⇒ Boolean): IndexedSeq[E]

    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
    ParentElemApi

  28. abstract def findTopmostElemsOrSelf(expandedName: EName): IndexedSeq[E]

    Returns the descendant-or-self elements with the given expanded name that have no ancestor with the same name

  29. abstract def findTopmostElemsOrSelf(p: (E) ⇒ Boolean): IndexedSeq[E]

    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: E => Boolean): immutable.IndexedSeq[E] =
if (p(this)) Vector(this)
else (this.findAllChildElems flatMap (_.findTopmostElemsOrSelf(p)))
    Definition Classes
    ParentElemApi

  30. abstract def getChildElem(expandedName: EName): E

    Returns the single child element with the given expanded name, and throws an exception otherwise

  31. abstract def getChildElem(p: (E) ⇒ Boolean): E

    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
    ParentElemApi

  32. abstract def localName: String

    The local name (or local part).

    The local name (or local part). Convenience method.

  33. abstract def resolvedAttributes: Iterable[(EName, String)]

    The attributes as a mapping from ENames (instead of QNames) to values.

    The attributes as a mapping from ENames (instead of QNames) to values.

    The implementation must ensure that resolvedAttributes.toMap.size == resolvedAttributes.size.

    Namespace declarations are not considered attributes in yaidom, so are not included in the result.

  34. abstract def resolvedName: EName

    Resolved name of the element, as EName

Concrete Value Members

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

    Definition Classes
    AnyRef

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

    Definition Classes
    Any

  3. final def ##(): Int

    Definition Classes
    AnyRef → Any

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

    Definition Classes
    AnyRef

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

    Definition Classes
    Any

  6. final def asInstanceOf[T0]: T0

    Definition Classes
    Any

  7. def clone(): AnyRef

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

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

    Definition Classes
    AnyRef

  9. def equals(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any

  10. def finalize(): Unit

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

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

    Definition Classes
    AnyRef → Any

  12. def hashCode(): Int

    Definition Classes
    AnyRef → Any

  13. final def isInstanceOf[T0]: Boolean

    Definition Classes
    Any

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

    Definition Classes
    AnyRef

  15. final def notify(): Unit

    Definition Classes
    AnyRef

  16. final def notifyAll(): Unit

    Definition Classes
    AnyRef

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

    Definition Classes
    AnyRef

  18. def toString(): String

    Definition Classes
    AnyRef → Any

  19. final def wait(): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

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

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

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

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

Inherited from ParentElemApi[E]

Inherited from AnyRef

Inherited from Any

Ungrouped