indexed

Type Members

1. final class Document extends IndexedDocument[simple.Elem] with Immutable

   

   IndexedDocument, containing an "indexed" document element with simple elements as underlying elements.

2. type Elem = IndexedScopedElem[simple.Elem]

   

3. final class IndexedClarkElem[U <: ClarkElemApi[U]] extends queryapi.Nodes.Elem with IndexedClarkElemLike[IndexedClarkElem[U], U]

   

   An element within its context.

   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(rootElem) 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, using a member type, 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/.)

   Having an IndexedClarkElem, it is always possible to re-create the root element as IndexedClarkElem, because the underlying root element is always available. On the other hand, creating an IndexedClarkElem is expensive. Class IndexedClarkElem is optimized for fast querying, at the expense of costly recursive creation.

   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)
   
   // The correspondence between rootElem, path and elem
   
   iElem.findAllElemsOrSelf.forall(e => e.rootElem.findElemOrSelfByPath(e.path).get == e.elem)

   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
   
   IndexedClarkElem(rootElem).filterElemsOrSelf(e => p(e.elem)).map(_.elem) ==
     rootElem.filterElemsOrSelf(p)

   Analogous properties hold for the other query methods.

   U

   The underlying element type

4. trait IndexedClarkElemApi[E <: IndexedClarkElemApi[E, U], U <: ClarkElemApi[U]] extends ClarkElemApi[E]

   

   Abstract API for "indexed elements".

   Abstract API for "indexed elements".

   Note how this API removes the need for an API which is like the ElemApi API, but taking and returning pairs of elements and paths. This could be seen as that API, re-using ElemApi instead of adding an extra API similar to it. These IndexedClarkElemApi objects "are" the above-mentioned pairs of elements and paths.

   E

   The element type itself

   U

   The underlying element type

5. trait IndexedClarkElemLike[E <: IndexedClarkElemLike[E, U], U <: ClarkElemApi[U]] extends IndexedClarkElemApi[E, U] with ClarkElemLike[E]

   

   Partial implementation of the abstract API for "indexed elements".

   Partial implementation of the abstract API for "indexed elements".

   E

   The element type itself

   U

   The underlying element type

6. abstract class IndexedDocument[U <: ScopedElemApi[U]] extends DocumentApi[IndexedScopedElem[U]] with Immutable

   

   Document, containing an "indexed" document element.

   Document, containing an "indexed" document element.

   Note that class IndexedDocument does not have any query methods for Elem instances. In particular, the ElemApi does not apply to documents. Therefore, given a document, querying for elements (other than the document element itself) always goes via the document element.

7. final class IndexedScopedElem[U <: ScopedElemApi[U]] extends queryapi.Nodes.Elem with IndexedScopedElemLike[IndexedScopedElem[U], U]

   

   Indexed Scoped element.

   Indexed Scoped element. Like IndexedClarkElem but instead of being and indexing a ClarkElemApi, it is and indexes a ScopedElemApi. Other than that, see the documentation for IndexedClarkElem.

   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.

   U

   The underlying element type

8. trait IndexedScopedElemApi[E <: IndexedScopedElemApi[E, U], U <: ScopedElemApi[U]] extends IndexedClarkElemApi[E, U] with ScopedElemApi[E]

   

   Abstract API for "indexed Scoped elements".

   Abstract API for "indexed Scoped elements".

   E

   The element type itself

   U

   The underlying element type

9. trait IndexedScopedElemLike[E <: IndexedScopedElemLike[E, U], U <: ScopedElemApi[U]] extends IndexedScopedElemApi[E, U] with IndexedClarkElemLike[E, U] with ScopedElemLike[E]

   

   Partial implementation of the abstract API for "indexed Scoped elements".

   Partial implementation of the abstract API for "indexed Scoped elements".

   E

   The element type itself

   U

   The underlying element type

10. final class LazyIndexedClarkElem[U <: ClarkElemApi[U]] extends queryapi.Nodes.Elem with IndexedClarkElemLike[LazyIndexedClarkElem[U], U]

    

    Very lightweight lazy indexed element implementation.

    Very lightweight lazy indexed element implementation. It offers the IndexedClarkElemApi query API. It is optimized for fast (just-in-time) element creation, not for fast querying.

    U

    The underlying element type

11. final class LazyIndexedScopedElem[U <: ScopedElemApi[U]] extends queryapi.Nodes.Elem with IndexedScopedElemLike[LazyIndexedScopedElem[U], U]

    

    Very lightweight lazy indexed element implementation.

    Very lightweight lazy indexed element implementation. It offers the IndexedScopedElemApi query API. It is optimized for fast (just-in-time) element creation, not for fast querying.

    U

    The underlying element type