source: trunk/src/xmlpatterns/data/qresourceloader_p.h@ 5

Last change on this file since 5 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 16.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the QtXmlPatterns module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42//
43// W A R N I N G
44// -------------
45//
46// This file is not part of the Qt API. It exists purely as an
47// implementation detail. This header file may change from version to
48// version without notice, or even be removed.
49//
50// We mean it.
51
52#ifndef Patternist_ResourceLoader_H
53#define Patternist_ResourceLoader_H
54
55#include "qitem_p.h"
56#include "qreportcontext_p.h"
57#include "qsequencetype_p.h"
58#include "qsourcelocationreflection_p.h"
59
60QT_BEGIN_HEADER
61
62QT_BEGIN_NAMESPACE
63
64class QUrl;
65
66namespace QPatternist
67{
68 /**
69 * @short Responsible for handling requests for opening files and node collections.
70 *
71 * ResourceLoader is a callback used for opening files, requested
72 * via the functions <tt>fn:document()</tt> and <tt>fn:unparsed-text()</tt>;
73 * and node collections, requested via <tt>fn:collection()</tt>. Patternist uses the
74 * ResourceLoader at compile time,
75 * via StaticContext::resourceLoader(), and at runtime, via DynamicContext::resourceLoader().
76 *
77 * The ResourceLoader takes care of loading "external resources" in a way specific to the data
78 * model Patternist is using. For example, perhaps the opening of documents should pass
79 * a security policy, or a collection should map to nodes in a virtual filesystem or a database.
80 *
81 * From Patternist's perspective, the ResourceLoader provides two things:
82 *
83 * - At compile time, it calls announceDocument(), announceCollection() and announceUnparsedText()
84 * if it knows the URIs at compile time in order to retrieve the static types of the data the URIs
85 * maps to. This is used for more efficiently compiling the query and to better report errors
86 * at compile time.
87 * - To open document and node collections at runtime.
88 *
89 * From the user's or the data model's perspective, the ResourceLoader most notably provides
90 * a hint to what resources a query will load at runtime, and therefore provides an opportunity
91 * to prepare in advance for that. For example, between the compile and runtime stage,
92 * the ResourceLoader sub-class can be asked to pre-load documents in an asynchronous
93 * and simultaneous way, such that the runtime stage is faster and doesn't
94 * freeze a graphical interface.
95 *
96 * The announce functions are not guaranteed to be called. The loading functions can be called
97 * with an URI that an announce function hasn't been called with.
98 *
99 * The default implementations of ResourceLoader's virtual functions all signals that no
100 * resources can be loaded. This means ResourceLoader must be sub-classed, in order to
101 * be able to load resources.
102 *
103 * @ingroup Patternist_xdm
104 * @author Frans Englich <[email protected]>
105 */
106 class Q_AUTOTEST_EXPORT ResourceLoader : public QSharedData
107 {
108 public:
109 enum Usage
110 {
111 /**
112 * Communicates that the URI may be used during query evaluation.
113 * For example, zero times or very many times.
114 *
115 * Typically this hint is given when the URI is available at
116 * compile-time, but it is used inside a conditional statement
117 * whose branching can't be determined at compile time.
118 */
119 MayUse,
120
121 /**
122 * Communicates that the URI will always be used at query
123 * evaluation.
124 */
125 WillUse
126 };
127
128 typedef QExplicitlySharedDataPointer<ResourceLoader> Ptr;
129 inline ResourceLoader() {}
130 virtual ~ResourceLoader();
131
132 /**
133 * @short Calls to this function are generated by calls to the
134 * <tt>fn:unparsed-text-available()</tt> function.
135 *
136 * @param uri A URI identifying the resource to retrieve. The URI is guaranteed
137 * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative()
138 * returns @c false).
139 * @returns @c true if calling openUnparsedText() while passing @p uri will successfully load
140 * the document.
141 * @see <a href="http://www.w3.org/TR/xslt20/#unparsed-text">XSL Transformations
142 * (XSLT) Version 2.0, 16.2 Reading Text Files</a>
143 */
144 virtual bool isUnparsedTextAvailable(const QUrl &uri,
145 const QString &encoding);
146
147 /**
148 * @short May be called by the compilation framework at compile time to report that an
149 * unparsed text(plain text) file referenced by @p uri will be loaded at runtime.
150 *
151 * This function can be called an arbitrary amount of times for the same URI. How many times
152 * it is called for a URI has no meaning(beyond the first call, that is). For what queries
153 * the compilation framework can determine what always will be loaded is generally undefined. It
154 * depends on factors such as how simple the query is what information that is statically
155 * available and subsequently what optimizations that can apply.
156 *
157 * Calls to this function are generated by calls to the <tt>fn:unparsed-text()</tt> function.
158 *
159 * @param uri A URI identifying the resource to retrieve. The URI is guaranteed
160 * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative()
161 * returns @c false).
162 * @see <a href="http://www.w3.org/TR/xslt20/#unparsed-text">XSL Transformations
163 * (XSLT) Version 2.0, 16.2 Reading Text Files</a>
164 * @returns
165 * - @c null if no unparsed file can be loaded for @p uri
166 * - The item type that the value loaded by @p uri will be an instance of. This is
167 * typically @c xs:string
168 */
169 virtual ItemType::Ptr announceUnparsedText(const QUrl &uri);
170
171 /**
172 * @short Calls to this function are generated by calls to the <tt>fn:unparsed-text()</tt> function.
173 *
174 * @param uri A URI identifying the resource to retrieve. The URI is guaranteed
175 * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative()
176 * returns @c false).
177 * @param encoding the encoding to use. If empty, the user hasn't
178 * expressed any encoding to use.
179 * @see <a href="http://www.w3.org/TR/xslt20/#unparsed-text">XSL Transformations
180 * (XSLT) Version 2.0, 16.2 Reading Text Files</a>
181 * @returns
182 * - @c null if no unparsed file can be loaded for @p uri
183 * - An @c xs:string value(or subtype) containing the content of the file identified
184 * by @p uri as text. Remember that its type must match the sequence type
185 * returned by announceUnparsedText()
186 */
187 virtual Item openUnparsedText(const QUrl &uri,
188 const QString &encoding,
189 const ReportContext::Ptr &context,
190 const SourceLocationReflection *const where);
191
192 /**
193 * @short Calls to this function are generated by calls to the <tt>fn:document()</tt>
194 * or <tt>fn:doc()</tt> function.
195 *
196 * @note This function is responsible for execution stability. Subsequent calls
197 * to this function with the same URI should result in QXmlNodeModelIndex instances that have
198 * the same identity. However, in some cases this stability is not of interest, see
199 * the specification for details.
200 * @param uri A URI identifying the resource to retrieve. The URI is guaranteed
201 * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative()
202 * returns @c false).
203 * @see QXmlNodeModelIndex::identity()
204 * @see <a href="http://www.w3.org/TR/xpath-functions/#func-doc">XQuery 1.0
205 * and XPath 2.0 Functions and Operators, 15.5.4 fn:doc</a>
206 * @see <a href="http://www.w3.org/TR/xslt20/#document">XSL Transformations
207 * (XSLT) Version 2.0, 16.1 Multiple Source Documents</a>
208 * @returns
209 * - @c null if no document can be loaded for @p uri
210 * - A QXmlNodeModelIndex representing the document identified by @p uri. Remember that the QXmlNodeModelIndex
211 * must match the sequence type returned by announceDocument()
212 */
213 virtual Item openDocument(const QUrl &uri,
214 const ReportContext::Ptr &context);
215
216 /**
217 * @short May be called by the compilation framework at compile time to report that an
218 * XML document referenced by @p uri will be loaded at runtime.
219 *
220 * This function can be called an arbitrary amount of times for the same URI, but different
221 * @p usageHint values. How many times it is called for a URI has no meaning(beyond the first call,
222 * that is). For what queries the compilation framework can determine what always will be
223 * loaded is generally undefined. It
224 * depends on factors such as the complexity of the query, what information that is statically
225 * available and subsequently what optimizations that can be applied.
226 *
227 * Calls to this function are generated by calls to the <tt>fn:document()</tt>
228 * or <tt>fn:doc()</tt> function.
229 *
230 * @param uri A URI identifying the resource to retrieve. The URI is guaranteed
231 * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative()
232 * returns @c false).
233 * @param usageHint A hint to how the URI will be used.
234 * @returns
235 * - @c null if the ResourceLoader can determine at this stage that no document
236 * referenced by @p uri will ever be possible to load.
237 * - The appropriate sequence type if loading @p uri succeeds at runtime. This must be
238 * CommonSequenceTypes::zeroOrOneDocument, CommonSequenceTypes::exactlyOneDocument or
239 * a sequence type that is a sub type of it.
240 * @see <a href="http://www.w3.org/TR/xpath-functions/#func-doc">XQuery 1.0
241 * and XPath 2.0 Functions and Operators, 15.5.4 fn:doc</a>
242 * @see <a href="http://www.w3.org/TR/xslt20/#document">XSL Transformations
243 * (XSLT) Version 2.0, 16.1 Multiple Source Documents</a>
244 */
245 virtual SequenceType::Ptr announceDocument(const QUrl &uri, const Usage usageHint);
246
247 /**
248 * @short Calls to this function are generated by calls to the <tt>fn:doc-available()</tt> function.
249 *
250 * @param uri A URI identifying the resource to retrieve. The URI is guaranteed
251 * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative()
252 * returns @c false).
253 * @returns @c true if calling openDocument() while passing @p uri will successfully load
254 * the document.
255 * @see <a href="http://www.w3.org/TR/xpath-functions/#func-doc-available">XQuery 1.0
256 * and XPath 2.0 Functions and Operators, 15.5.5 fn:doc-available</a>
257 * @see <a href="http://www.w3.org/TR/xslt20/#document">XSL Transformations
258 * (XSLT) Version 2.0, 16.1 Multiple Source Documents</a>
259 */
260 virtual bool isDocumentAvailable(const QUrl &uri);
261
262 /**
263 * @short Calls to this function are generated by calls to the <tt>fn:collection()</tt> function.
264 *
265 * @param uri A URI identifying the resource to retrieve. The URI is guaranteed
266 * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative()
267 * returns @c false).
268 * @see <a href="http://www.w3.org/TR/xpath-functions/#func-collection">XQuery 1.0
269 * and XPath 2.0 Functions and Operators, 15.5.6 fn:collection</a>
270 * @returns
271 * - @c null if no node collection can be loaded for @p uri
272 * - An QAbstractXmlForwardIterator representing the content identified by @p uri. Remember that the content
273 * of the QAbstractXmlForwardIterator must match the sequence type returned by announceCollection()
274 */
275 virtual Item::Iterator::Ptr openCollection(const QUrl &uri);
276
277 /**
278 * @short May be called by the compilation framework at compile time to report that an
279 * node collection referenced by @p uri will be loaded at runtime.
280 *
281 * This function can be called an arbitrary amount of times for the same URI. How many times
282 * it is called for a URI has no meaning(beyond the first call, that is). For what queries
283 * the compilation framework can determine what always will be loaded is generally undefined. It
284 * depends on factors such as how simple the query is what information that is statically
285 * available and subsequently what optimizations that can apply.
286 *
287 * Calls to this function are generated by calls to the <tt>fn:collection()</tt> function.
288 *
289 * @note This function is responsible for execution stability. Subsequent calls
290 * to this function with the same URI should result in QXmlNodeModelIndex instances that have
291 * the same identity. However, in some cases this stability is not of interest, see
292 * the specification for details.
293 * @param uri A URI identifying the resource to retrieve. The URI is guaranteed
294 * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative()
295 * returns @c false).
296 * @returns
297 * - @c null if the ResourceLoader can determine at this stage that no document
298 * referenced by @p uri will ever be possible to load.
299 * - The appropriate sequence type if loading @p uri succeeds at runtime. This must be
300 * CommonSequenceTypes::zeroOrMoreNodes or a sequence type that is a sub type of it.
301 * @see <a href="http://www.w3.org/TR/xpath-functions/#func-collection">XQuery 1.0
302 * and XPath 2.0 Functions and Operators, 15.5.6 fn:collection</a>
303 */
304 virtual SequenceType::Ptr announceCollection(const QUrl &uri);
305
306 /**
307 * @short Asks to unload @p uri from its document pool, such that a
308 * subsequent request will require a new read.
309 *
310 * The default implementation does nothing.
311 */
312 virtual void clear(const QUrl &uri);
313 };
314}
315
316QT_END_NAMESPACE
317
318QT_END_HEADER
319
320#endif
Note: See TracBrowser for help on using the repository browser.