[2] | 1 | /****************************************************************************
|
---|
| 2 | **
|
---|
[651] | 3 | ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
|
---|
[561] | 4 | ** All rights reserved.
|
---|
| 5 | ** Contact: Nokia Corporation ([email protected])
|
---|
[2] | 6 | **
|
---|
| 7 | ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
|
---|
| 8 | **
|
---|
| 9 | ** $QT_BEGIN_LICENSE:LGPL$
|
---|
| 10 | ** Commercial Usage
|
---|
| 11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
| 12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
| 13 | ** Software or, alternatively, in accordance with the terms contained in
|
---|
| 14 | ** a written agreement between you and Nokia.
|
---|
| 15 | **
|
---|
| 16 | ** GNU Lesser General Public License Usage
|
---|
| 17 | ** Alternatively, this file may be used under the terms of the GNU Lesser
|
---|
| 18 | ** General Public License version 2.1 as published by the Free Software
|
---|
| 19 | ** Foundation and appearing in the file LICENSE.LGPL included in the
|
---|
| 20 | ** packaging of this file. Please review the following information to
|
---|
| 21 | ** ensure the GNU Lesser General Public License version 2.1 requirements
|
---|
| 22 | ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
|
---|
| 23 | **
|
---|
[561] | 24 | ** In addition, as a special exception, Nokia gives you certain additional
|
---|
| 25 | ** rights. These rights are described in the Nokia Qt LGPL Exception
|
---|
| 26 | ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
|
---|
[2] | 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 | **
|
---|
[561] | 36 | ** If you have questions regarding the use of this file, please contact
|
---|
| 37 | ** Nokia at [email protected].
|
---|
[2] | 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 |
|
---|
| 60 | QT_BEGIN_HEADER
|
---|
| 61 |
|
---|
| 62 | QT_BEGIN_NAMESPACE
|
---|
| 63 |
|
---|
| 64 | class QUrl;
|
---|
| 65 |
|
---|
| 66 | namespace 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
|
---|
[561] | 104 | * @author Frans Englich <[email protected]>
|
---|
[2] | 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
|
---|
[561] | 117 | * whose branching cannot be determined at compile time.
|
---|
[2] | 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 |
|
---|
| 316 | QT_END_NAMESPACE
|
---|
| 317 |
|
---|
| 318 | QT_END_HEADER
|
---|
| 319 |
|
---|
| 320 | #endif
|
---|