TaxonomyElem

Any element in a taxonomy schema or linkbase document. The classes in this class hierarchy offer the yaidom query API, in particular the ScopedElemApi and SubtypeAwareElemApi query API.

==Usage==

Suppose we have an eu.cdevreeze.tqa.base.dom.XsdSchema called schema. Then we can find all global element declarations in this schema as follows:

import scala.reflect.classTag
import eu.cdevreeze.tqa.ENames
import eu.cdevreeze.tqa.base.dom.GlobalElementDeclaration

// Low level yaidom query, returning the result XML elements as TaxonomyElem elements
val globalElemDecls1 = schema.filterChildElems(_.resolvedName == ENames.XsElementEName)

// Higher level yaidom query, querying for the type GlobalElementDeclaration
// Prefer this to the lower level yaidom query above
val globalElemDecls2 = schema.findAllChildElemsOfType(classTag[GlobalElementDeclaration])

// The following query would have given the same result, because all global element declarations
// are child elements of the schema root. Instead of child elements, we now query for all
// descendant-or-self elements that are global element declarations
val globalElemDecls3 = schema.findAllElemsOrSelfOfType(classTag[GlobalElementDeclaration])

// We can query the schema for global element declarations directly, so let's do that
val globalElemDecls4 = schema.findAllGlobalElementDeclarations

==Leniency==

The classes in this type hierarchy have been designed to be very '''lenient when instantiating''' them, even for schema-invalid content. The few builder methods that may throw exceptions have been clearly documented to potentially do so. For schema-invalid taxonomy content, the resulting object may be something like OtherElemInXsdNamespace, OtherElemInLinkNamespace or OtherNonXLinkElem. For example, an element named xs:element with both a name and ref attribute cannot be both an element declaration and element reference, and will be instantiated as an OtherElemInXsdNamespace. A non-standard XLink arc, whether a known generic arc or some unknown and potentially erroneous arc, becomes an instance of NonStandardArc or one of its sub-types, etc.

Some '''instance methods''' may fail, however, if taxonomy content is invalid, and if it is '''schema-invalid''' in particular. All instance methods must not fail on schema-valid content, unless mentioned otherwise.

Typical instance methods that may fail on schema-invalid content are:

• methods that query for one mandatory attribute (as far as the schema is concerned)

• methods that query for one mandatory child element (as far as the schema is concerned)

• methods that query for values of specific types (enumerations, integers etc.)

It is important to keep this in mind. Schema-invalid taxonomies will be instantiated successfully, but after instantiation the API user should fall back to (defensive) yaidom level query methods when needed. This is indeed the responsibility of the API user.

==Other remarks==

The type hierarchy for taxonomy elements is not a strict hierarchy. There are mixin traits for XLink content, "root elements", elements in the xs and link namespaces, etc. Some element types mix in more than one of these traits.

See http://www.datypic.com/sc/xsd/s-xmlschema.xsd.html for schema content in general (as opposed to taxonomy schema content in particular).

It is perfectly fine to embed linkbase content in schema content, and such an element tree will be instantiated correctly.

The underlying backing elements can be any backing element implementation, including BackingNodes.Elem wrappers around Saxon tiny trees! Hence, this taxonomy DOM API is flexible in that it is not bound to one specific backing element implementation.