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