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

source code of qtxmlpatterns/src/xmlpatterns/data/qresourceloader_p.h