Red Hat Training

A Red Hat training course is available for Red Hat JBoss Data Virtualization

3.8. XML Document Generation

3.8.1. XML Document Generation

XML documents can be constructed dynamically using XML Document Models. A document model is generally created from a schema. The document model is bound to relevant SQL statements through mapping classes. See the Red Hat JBoss Data Virtualization User Guide for more information about creating document models.
Querying XML documents is similar to querying relational tables. An idiomatic SQL variant with special scalar functions provides control over which parts of a given document to return.

Note

XML documents may also be created via XQuery with the XMLQuery function or with various other SQL/XML functions. See Section 3.4.14, “XML Functions”.

3.8.2. XML SELECT Command

A valid XML SELECT Command against a document model is of the form:
SELECT ... FROM ... [WHERE ...] [ORDER BY ...]
The use of any other SELECT clause is not allowed.
The fully qualified name for an XML element is:
"model"."document name".[path to element]."element name"
The fully qualified name for an attribute is:
"model"."document name".[path to element]."element name".[@]"attribute name"
Partially qualified names for elements and attributes can be used as long as the partial name is unique.

3.8.3. XML SELECT: FROM Clause

This clause specifies the document to generate. Document names resemble other virtual groups - "model"."document name".

Syntax Rules:

  • The FROM clause must contain only one unary clause specifying the desired document.

3.8.4. XML SELECT: SELECT Clause

The SELECT clause determines which parts of the XML document are generated for output.

Example Syntax:

  • select * from model.doc
  • select model.doc.root.parent.element.* from model.doc
  • select element, element1.@attribute from model.doc

Syntax Rules:

  • SELECT * and SELECT "xml" are equivalent and specify that every element and attribute of the document should be output.
  • The SELECT clause of an XML Query may only contain *, "xml", or element and attribute references from the specified document. Any other expressions are not allowed.
  • If the SELECT clause contains an element or attribute reference (other than * or "xml") then only the specified elements, attributes, and their ancestor elements will be in the generated document.
  • element.* specifies that the element, its attribute, and all child content should be output.

3.8.5. XML SELECT: WHERE Clause

The WHERE clause specifies how to filter content from the generated document based upon values contained in the underlying mapping classes. Most predicates are valid in an XML SELECT Command, however combining value references from different parts of the document may not always be allowed.
Criteria is logically applied to a context which is directly related to a mapping class. Starting with the root mapping class, there is a root context that describes all of the top level repeated elements that will be in the output document. Criteria applied to the root or any other context will change the related mapping class query to apply the affects of the criteria, which can include checking values from any of the descendant mapping classes.

Example Syntax:

  • select element, element1.@attribute from model.doc where element1.@attribute = 1
  • select element, element1.@attribute from model.doc where context(element1, element1.@attribute) = 1

Syntax Rules:

  • Each criteria conjunct must refer to a single context and can be criteria that applies to a mapping class, contain a rowlimit function, or contain rowlimitexception function. Refer to Section 3.8.9, “ROWLIMIT Function” and Section 3.8.10, “ROWLIMITEXCEPTION Function”.
  • Criteria that applies to a mapping class is associated to that mapping class using the context function. The absence of a context function implies the criteria applies to the root context. Refer to Section 3.8.8, “CONTEXT Function”.
  • At a given context the criteria can span multiple mapping classes provided that all mapping classes involved are either parents of the context, the context itself, or a descendant of the context.

Note

Implied root context user criteria against a document model with sibling root mapping classes is not generally semantically correct. It is applied as if each of the conjuncts is applied to only a single root mapping class. This behavior is the same as prior releases but may be fixed in a future release.

3.8.6. XML SELECT: ORDER BY Clause

The XML SELECT Command ORDER BY clause specifies ordering for the referenced mapping class queries.

Syntax Rules:

  • Each ORDER BY item must be an element or attribute reference tied a output value from a mapping class.
  • The order of the ORDER BY items is the relative order applied to their respective mapping classes.

3.8.7. XML SELECT Command Specific Functions

XML SELECT Command functions resemble scalar functions, but act as hints in the WHERE clause:
  • CONTEXT Function
  • ROWLIMIT Function
  • ROWLIMITEXCEPTION Function
These functions are only valid in an XML SELECT Command.

3.8.8. CONTEXT Function

This function selects the context for the containing conjunct.
CONTEXT(arg1, arg2)

Syntax Rules:

  • Context functions apply to the whole conjunct.
  • The first argument must be an element or attribute reference from the mapping class whose context the criteria conjunct will apply to.
  • The second parameter is the return value for the function.

3.8.9. ROWLIMIT Function

This function limits the rows processed for the given context.
ROWLIMIT(arg)

Syntax Rules:

  • The first argument must be an element or attribute reference from the mapping class whose context the row limit applies.
  • The ROWLIMIT function must be used in equality comparison criteria with the right hand expression equal to an positive integer number or rows to limit.
  • Only one row limit or row limit exception may apply to a given context.

3.8.10. ROWLIMITEXCEPTION Function

This function limits the rows processed for the given context and throws an exception if the given number of rows is exceeded.
ROWLIMITEXCEPTION(arg)

Syntax Rules:

  • The first argument must be an element or attribute reference from the mapping class whose context the row limit exception applies.
  • The ROWLIMITEXCEPTION function must be used in equality comparison criteria with the right hand expression equal to an positive integer number or rows to limit.
  • Only one row limit or row limit exception may apply to a given context.

3.8.11. Document Generation

Document generation starts with the root mapping class and proceeds iteratively and hierarchically over all of the child mapping classes. This can result in a large number of query executions. For example if a document has a root mapping class with 3 child mapping classes. Then for each row selected by the root mapping class after the application of the root context criteria, each of the child mapping classes queries will also be executed.

Note

By default, XML generated by XML documents are not checked for correctness vs. the relevant schema. It is possible that the mapping class queries, the usage of specific SELECT or WHERE clause values will generate a document that is not valid with respect to the schema. Refer to Section 3.8.12, “Document Validation” for information to ensure correctness.
Sibling or cousin elements defined by the same mapping class that do not have a common parent in that mapping class will be treated as independent mapping classes during planning and execution. This allows for a more document-centric approach when applying WHERE criteria and ORDER BY clauses to mapping classes.

3.8.12. Document Validation

If the execution property XMLValidation is set to 'true' generated documents will be checked for correctness. However, correctness checking will not prevent invalid documents from being generated, since correctness is checked after generation.