UpdatableElemApi

This is the functional update part of the yaidom uniform query API. It is a sub-trait of trait eu.cdevreeze.yaidom.queryapi.IsNavigableApi. Only a few 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.queryapi.UpdatableElemLike. The trait has all the knowledge of its super-trait, but in addition to that knows the following:

• An element has child nodes, which may or may not be elements. Hence the extra type parameter for nodes.
• An element knows the child node indexes of the path entries of the child elements.

Obviously methods children, withChildren and childNodeIndex must be consistent with methods such as findAllChildElems.

Using this minimal knowledge alone, trait UpdatableElemLike not only offers the methods of its parent trait, but also:

• methods to functionally update an element by replacing, adding or deleting child nodes
• methods to functionally update an element by replacing descendant-or-self elements at specified paths

For the conceptual difference with "transformable" elements, see trait eu.cdevreeze.yaidom.queryapi.TransformableElemApi.

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

UpdatableElemApi examples

To illustrate the use of this API, 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.simple.Elem variable named bookstoreElem. Then we can add a book as follows, where we "forget" the 2nd author for the moment:

import convert.ScalaXmlConversions._

val bookstoreNamespace = "http://bookstore/book"
val authorNamespace = "http://bookstore/author"

val fpBookXml =
  <book:Book xmlns:book="http://bookstore/book" xmlns:auth="http://bookstore/author" ISBN="978-1617290657" Price="33">
    <book:Title>Functional Programming in Scala</book:Title>
    <book:Authors>
      <auth:Author>
        <auth:First_Name>Paul</auth:First_Name>
        <auth:Last_Name>Chiusano</auth:Last_Name>
      </auth:Author>
    </book:Authors>
  </book:Book>
val fpBookElem = convertToElem(fpBookXml)

bookstoreElem = bookstoreElem.plusChild(fpBookElem)

Note that the namespace declarations for prefixes book and auth had to be repeated in the Scala XML literal for the added book, because otherwise the convertToElem method would throw an exception (since Elem instances cannot be created unless all element and attribute QNames can be resolved as ENames).

The resulting bookstore seems ok, but if we print convertElem(bookstoreElem), the result does not look pretty. This can be fixed if the last assignment is replaced by:

bookstoreElem = bookstoreElem.plusChild(fpBookElem).prettify(2)

knowing that an indentation of 2 spaces has been used throughout the original XML. Method prettify is expensive, so it is best not to invoke it within a tight loop. As an alternative, formatting can be left to the DocumentPrinter, of course.

The assignment above is the same as the following one:

bookstoreElem = bookstoreElem.withChildren(bookstoreElem.children :+ fpBookElem).prettify(2)

There are several methods to functionally update the children of an element. For example, method plusChild is overloaded, and the other variant can insert a child at a given 0-based position. Other "children update" methods are minusChild, withPatchedChildren and withUpdatedChildren.

Let's now turn to functional update methods that take Path instances or collections thereof. In the example above the second author of the added book is missing. Let's fix that:

val secondAuthorXml =
  <auth:Author xmlns:auth="http://bookstore/author">
    <auth:First_Name>Runar</auth:First_Name>
    <auth:Last_Name>Bjarnason</auth:Last_Name>
  </auth:Author>
val secondAuthorElem = convertToElem(secondAuthorXml)

val fpBookAuthorsPaths =
  for {
    authorsPath <- indexed.Elem(bookstoreElem) filterElems { e => e.resolvedName == EName(bookstoreNamespace, "Authors") } map (_.path)
    if authorsPath.findAncestorPath(path => path.endsWithName(EName(bookstoreNamespace, "Book")) &&
      bookstoreElem.getElemOrSelfByPath(path).attribute(EName("ISBN")) == "978-1617290657").isDefined
  } yield authorsPath

require(fpBookAuthorsPaths.size == 1)
val fpBookAuthorsPath = fpBookAuthorsPaths.head

bookstoreElem = bookstoreElem.updated(fpBookAuthorsPath) { elem =>
  require(elem.resolvedName == EName(bookstoreNamespace, "Authors"))
  val rawResult = elem.plusChild(secondAuthorElem)
  rawResult transformElemsOrSelf (e => e.copy(scope = elem.scope.withoutDefaultNamespace ++ e.scope))
}
bookstoreElem = bookstoreElem.prettify(2)

Clearly the resulting bookstore element is nicely formatted, but there was another possible issue that was taken into account. See the line of code transforming the "raw result". That line was added in order to prevent namespace undeclarations, which for XML version 1.0 are not allowed (with the exception of the default namespace). After all, the XML for the second author was created with only the auth namespace declared. Without the above-mentioned line of code, a namespace undeclaration for prefix book would have occurred in the resulting XML, thus leading to an invalid XML 1.0 element tree.

To illustrate functional update methods taking collections of paths, let's remove the added book from the book store. Here is one (somewhat inefficient) way to do that:

val bookPaths = indexed.Elem(bookstoreElem) filterElems (_.resolvedName == EName(bookstoreNamespace, "Book")) map (_.path)

bookstoreElem = bookstoreElem.updatedWithNodeSeqAtPaths(bookPaths.toSet) { (elem, path) =>
  if ((elem \@ EName("ISBN")) == Some("978-1617290657")) Vector() else Vector(elem)
}
bookstoreElem = bookstoreElem.prettify(2)

There are very many ways to write this functional update, using different functional update methods in trait UpdatableElemApi, or even only using transformation methods in trait TransformableElemApi (thus not using paths).

The example code above is enough to get started using the UpdatableElemApi methods, but it makes sense to study the entire API, and practice with it. Always keep in mind that functional updates typically mess up formatting and/or namespace (un)declarations, unless these aspects are taken into account.