Project

Profile

Help

How to connect?
Download (9.39 KB) Statistics
| Branch: | Tag: | Revision:

he / latest9.9 / hej / net / sf / saxon / query / package.html @ a2490f66

1
<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
2
<!-- Copyright (c) 2014 Saxonica Limited. -->
3
<!-- This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. -->
4
<!-- If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
5
<!-- This Source Code Form is "Incompatible With Secondary Licenses", as defined by the Mozilla Public License, v. 2.0. -->
6
<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
7

    
8
<html>
9

    
10
<head>
11
    <title>Package overview for net.sf.saxon.query</title>
12
</head>
13

    
14
<body>
15

    
16
<p>This package provides a relatively low-level API for executing XQuery queries
17
    directly from a Java application. This is no longer the recommended API for writing Java
18
    applications using XQuery: there are two higher-level APIs, s9api ({@link net.sf.saxon.s9api}),
19
    and XQJ ({@link javax.xml.xquery}). This package also includes internal supporting code
20
    that implements XQuery within Saxon.</p>
21

    
22
<p>For details of the API, see the JavaDoc documentation of individual classes, starting
23
    with the {@link net.sf.saxon.query.StaticQueryContext}.</p>
24

    
25
<p>The first thing you need to do is to create a {@link net.sf.saxon.Configuration} object.
26
    This holds values of all the system settings, corresponding to flags available on the command line.
27
    You don't need to set any properties in the <code>Configuration</code> object if you are happy
28
    with the default settings. For schema-aware processing, you will need to create a
29
    {@link com.saxonica.config.EnterpriseConfiguration} instead.</p>
30

    
31
<p>Then you need to create a {@link net.sf.saxon.query.StaticQueryContext} object, which you can
32
    do using the <code>newStaticQueryContext()</code> method on the <code>Configuration</code>. As the name
33
    implies, this holds information about the static (compile-time) context for a query. Most aspects
34
    of the static context can be defined in the Query Prolog, but this object allows you to initialize
35
    the static context from the application instead if you need to. Some of the facilities provided are
36
    very much for advanced users only, for example the ability to declare variables and functions, and
37
    the ability to specify a <code>NamePool</code> to be used. One aspect of the static context that you may need
38
    to use is the ability to declare collations. Using the method <code>declareCollation</code> you can
39
    create a mapping between a collation URI (which can then be used anywhere in the Query) and a Java
40
    <code>StringCollator</code> object used to implement that collation.</p>
41

    
42
<p>Having created, and possibly configured, the <code>Configuration</code> and
43
    <code>StaticQueryContext</code> objects, you can now compile a Query using the <code>compileQuery</code>
44
    method on the <code>StaticQueryContext</code>. The text of the
45
    Query can be supplied either as a <code>String</code> or as a Java <code>Reader</code>. There
46
    are thus two different <code>compileQuery</code> methods. Each of them returns the compiled
47
    query in the form of a <code>XQueryExpression</code>. The <code>XQueryExpression</code>, as you would expect,
48
    can be executed repeatedly, as often as you want, in the same or in different threads.</p>
49

    
50
<p>Before you run your query, you may want to build one or more trees representing
51
    XML documents that can be used as input to your query. You don't need to do this: if the query
52
    loads its source documents using the <code>doc()</code> function then this will be done
53
    automatically, but doing it yourself gives you more control. A document node at the root of
54
    a tree is represented in Saxon by the {@link net.sf.saxon.om.DocumentInfo} interface.
55
    The <code>Configuration</code> provides a convenience method, <code>buildDocument()</code>,
56
    that allows an instance of <code>DocumentInfo</code> to be constructed. The input parameter to
57
    this is defined by the class <code>javax.xml.transform.Source</code>, which is part of the
58
    standard Java JAXP API: the <code>Source</code> interface is an umbrella for different kinds of
59
    XML document source, including a <code>StreamSource</code> which parses raw XML from a byte
60
    or character stream, <code>SAXSource</code> which takes the input from a SAX parser (or an
61
    object that is simulating a SAX parser), and <code>DOMSource</code> which provides the input
62
    from a DOM. Saxon-PE also provides wrappers for third-party document models, for example a
63
    {@link net.sf.saxon.option.jdom.DocumentWrapper} which allows
64
    the input to be taken from a JDOM document.</p>
65

    
66
<p>To execute your compiled query, you need to create a {@link net.sf.saxon.query.DynamicQueryContext} object
67
    that holds the run-time context information. The main things you can set in the run-time context are:</p>
68

    
69
<ul>
70
    <li>Values of parameters (external global variables). You can set these using the <code>setParameter()</code>
71
        method. The mappings from Java classes to XQuery/XPath data types is the same as the mapping used for the
72
        returned values from an external Java method call, and is described under
73
        <a href="extensibility.html#function-result">Result of an Extension Function</a>.
74
    </li>
75
    <li>The context item can be set using the method <code>setContextItem()</code>.
76
    </li>
77
    <li>You can also set a URIResolver and/or ErrorListener. These default to the ones that were
78
        used during Query compilation.
79
    </li>
80
</ul>
81

    
82
<p>You are now ready to evaluate the query. There are several methods on the <code>QueryExpression</code>
83
    object that you can use to achieve this. The <code>evaluate()</code> method returns the result sequence
84
    as a Java <code>java.util.List</code>. The <code>evaluateSingle()</code> method is suitable when you know
85
    that the result sequence will contain a single item: this returns this item as an Object, or returns null
86
    if the result is an empty sequence. There is also an <code>iterator</code> method that returns an iterator
87
    over the results. This is a Saxon object of class <code>net.sf.saxon.SequenceIterator</code>: it is similar
88
    to the standard Java iterator, but not quite identical; for example, it can throw exceptions.</p>
89

    
90
<p>The <code>evaluate()</code> and <code>evaluateSingle()</code> methods return the result as a Java object
91
    of the most appropriate type: for example a String is returned as a <code>java.lang.String</code>, a
92
    boolean as a <code>java.lang.Boolean</code>. A node is returned using the Saxon representation of a node,
93
    <code>net.sf.saxon.om.NodeInfo</code>. With the standard and tinytree models, this object also implements
94
    the DOM <code>Node</code> interface (but any attempt to update the node throws an error).</p>
95

    
96
<p>The <code>iterator()</code> method, by contrast, does not do any conversion of the result. It is returned
97
    using its native Saxon representation, for example a String is returned as an instance of
98
    <code>sf.net.saxon.value.StringValue</code>. You can then use all the methods available on this class
99
    to process the returned value.</p>
100

    
101
<p>If you want to process the results of the query in your application, that's all there is to it. But you
102
    may want to output the results as serialized XML. Saxon provides two ways of doing this: you can produce
103
    wrapped output, or raw output. Raw output works only if the result consists of a single document or element
104
    node, and it outputs the subtree rooted at that element node in the form of a serialized XML document. Wrapped
105
    output works for any result sequence, for example a sequence of integers or a sequence of attribute and
106
    comment nodes; this works by wrapping each item in the result sequence as an XML element, with details
107
    of its type and value.</p>
108

    
109
<p>To produce wrapped output, you first wrap the result sequence as an XML tree, and then serialize the
110
    tree. To produce unwrapped output, you skip the wrapping stage and just call the serializer directly.</p>
111

    
112
<p>Both steps can be done using the <code>QueryResult</code> class. This class doesn't need to be
113
    instantiated, its methods are static. The method <code>QueryResult.wrap</code> takes as input the iterator
114
    produced by evaluating the query using the <code>iterator()</code> method, and produces as output
115
    a <code>DocumentInfo</code> object representing the results wrapped as an XML tree. The method
116
    <code>QueryResult.serialize</code> takes any document or element node as input, and writes it to
117
    a specified destination, using specified output properties. The destination is supplied as an object
118
    of class <code>javax.xml.transform.Result</code>. Like the <code>Source</code>, this is part of the
119
    JAXP API, and allows the destination to be specified as a StreamResult (representing a byte stream or
120
    character stream), a SAXResult (which wraps a SAX ContentHandler), or a DOMResult
121
    (which delivers the result as a DOM). The output properties are used only when writing to
122
    a StreamResult: they correspond to the properties available in the <code>xsl:output</code> element
123
    for XSLT. The property names are defined by constants in the JAXP <code>javax.xml.transform.OutputKeys</code>
124
    class (or <code>net.sf.saxon.event.SaxonOutputKeys</code> for Saxon extensions): for details of the
125
    values that are accepted, see the JavaDoc documentation or the JAXP specification.</p>
126

    
127

    
128
</body>
129
</html>
(20-20/20)