src/xmlpatterns/data/qresourceloader_p.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  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 **
  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.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  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;
 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