# @dtf:xquery Annotation

The @dtf:xquery annotation with the prologue attribute defines global XQuery functions that can be used by the queries specified in a DTF file. (The call to the function is made in the XQ file that contains the query.) In addition, the @dtf:xquery annotation with the prologue attribute specifies XQuery namespaces that can be used within the scope of the prologue of the DTF file.

Note: The @dtf:xquery annotation is optional.

Syntax

The syntax of the @dtf:xquery annotation is dependant on the number of lines in the annotation as described in the following options:

- For XQuery namespace and function definitions on multiple lines, the following syntax is used:

@dtf:xquery prologue ::

xquery_namespaces_and_function_definitions
::

Where xquery_namespaces_and_function_definitions defines the XQuery namespace and function definitions specified on multiple lines in the annotation.

- For XQuery namespaces and function definitions on a single line, the following syntax can be used:

@dtf:xquery prologue="xquery_namespace_and_function_definition"

Where xquery_namespace_and_function_definition defines the XQuery namespace and function definitions specified on a single line in the annotation.

Note: The only attribute supported for the @dtf:xquery annotation is the prologue attribute.

Remarks

The following example @dtf:xquery annotation defines a namespace and a function on multiple lines:

    /**
     * @dtf:xquery prologue::
     * declare namespace env = "http://www.example.org/envelope"
     *
     * define function wrapInEnvelope(element $e) returns element
     * {
     *    <env:envelope>
     *      {$e}
     *    </env:envelope>
     * }
     * ::
     */

Caution: The namespaces definitions must be listed before the function definitions in the annotation.

Note: The namespace(s) defined in the prologue can only be used in the scope of the prologue (as shown in the preceding example) and cannot be referred to from the query (stored in the XQ file) while function definitions can be used in queries (stored in the XQ file).

You can add the @dtf:prologue annotation using one of the following procedures:

- Using the Property Editor:

1. Open the DTF file in the Design View.
2. Select the DTF name in the Design View.
3. Click prologue in the Property Editor.
4. Click . . . next to the prologue field.

The Property Test Editor is displayed.

5. In the Property Test Editor, enter the desired namespaces and function definitions and click OK.

- Open the DTF file in the Source View and enter the @dtf:prologue annotation after the last import statements but before the class definition statement for the DTF as shown highlighted in bold in the following example code listing:

    package examples;
    import com.bea.xml.XmlObject;
    import com.bea.xml.XmlObjectList;
    /**
     * @dtf:xquery prologue::
     * define function debugFunction(xs:string $str) returns xs:string {
     * concat("DTF XQuery: ", $str)
     * }
     * ::
     */
    public abstract class examplesimplements com.bea.transform.TransformSource
    {
    	static final long serialVersionUID = 1L;
    	/**
    	 * @dtf:transform xquery-ref="myTransMethod.xq"
    	 * @dtf:schema-validate return-value="false" parameters="false"
    	 */
    	public abstract stockquotes.PriceQuoteDocument myTransMethod(stockquotes.PriceQuoteDocument PriceQuoteDoc);
    	/**
    	 * @dtf:transform xquery-ref="mySecondTransMethod.xq"
    	 * @dtf:schema-validate return-value="false" parameters="false"
    	 */
    	 public abstract org.example.quote.QuoteDocument mySecondTransMethod(noNamespace.SupplierDocument SupplierDoc);
    }

The @dtf:xquery annotation is a class level annotation. A function defined in the DTF class can be used by all the queries defined in the DTF file. In the preceding example, the debugFunction function can be used in both the myTransMethod query (stored in the myTransMethod.xq file) and the mySecondTransMethod query (stored in the mySecondTransMethod.xq file).

Related Topics

To learn more see XQuery Prologs.

To learn about the XQuery language, see the XQuery 1.0: An XML Query Language Specification - W3C Working Draft 16 August 2002 available from the W3C web site at the following URL:

http://www.w3.org/TR/2002/WD-xquery-20020816/

To learn data transformations, see the following topics:

Guide to Data Transformations

Tutorial: Building Your First Data Transformation