1 /**************************************************************************** 2 ** 3 ** Copyright (C) 2015 The Qt Company Ltd. 4 ** Contact: http://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 http://www.qt.io/terms-conditions. For further 15 ** information use the contact form at http://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 2.1 or version 3 as published by the Free 20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and 21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the 22 ** following information to ensure the GNU Lesser General Public License 23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and 24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. 25 ** 26 ** As a special exception, The Qt Company gives you certain additional 27 ** rights. These rights are described in The Qt Company LGPL Exception 28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. 29 ** 30 ** GNU General Public License Usage 31 ** Alternatively, this file may be used under the terms of the GNU 32 ** General Public License version 3.0 as published by the Free Software 33 ** Foundation and appearing in the file LICENSE.GPL included in the 34 ** packaging of this file. Please review the following information to 35 ** ensure the GNU General Public License version 3.0 requirements will be 36 ** met: http://www.gnu.org/copyleft/gpl.html. 37 ** 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 104 * @author Frans Englich <frans.englich@nokia.com> 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 cannot 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; ResourceLoader()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 321