diff options
Diffstat (limited to 'src/xmlpatterns/data/qresourceloader_p.h')
| -rw-r--r-- | src/xmlpatterns/data/qresourceloader_p.h | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/src/xmlpatterns/data/qresourceloader_p.h b/src/xmlpatterns/data/qresourceloader_p.h new file mode 100644 index 0000000000..c11304fa87 --- /dev/null +++ b/src/xmlpatterns/data/qresourceloader_p.h @@ -0,0 +1,320 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the QtXmlPatterns module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +// +// W A R N I N G +// ------------- +// +// This file is not part of the Qt API. It exists purely as an +// implementation detail. This header file may change from version to +// version without notice, or even be removed. +// +// We mean it. + +#ifndef Patternist_ResourceLoader_H +#define Patternist_ResourceLoader_H + +#include "qitem_p.h" +#include "qreportcontext_p.h" +#include "qsequencetype_p.h" +#include "qsourcelocationreflection_p.h" + +QT_BEGIN_HEADER + +QT_BEGIN_NAMESPACE + +class QUrl; + +namespace QPatternist +{ + /** + * @short Responsible for handling requests for opening files and node collections. + * + * ResourceLoader is a callback used for opening files, requested + * via the functions <tt>fn:document()</tt> and <tt>fn:unparsed-text()</tt>; + * and node collections, requested via <tt>fn:collection()</tt>. Patternist uses the + * ResourceLoader at compile time, + * via StaticContext::resourceLoader(), and at runtime, via DynamicContext::resourceLoader(). + * + * The ResourceLoader takes care of loading "external resources" in a way specific to the data + * model Patternist is using. For example, perhaps the opening of documents should pass + * a security policy, or a collection should map to nodes in a virtual filesystem or a database. + * + * From Patternist's perspective, the ResourceLoader provides two things: + * + * - At compile time, it calls announceDocument(), announceCollection() and announceUnparsedText() + * if it knows the URIs at compile time in order to retrieve the static types of the data the URIs + * maps to. This is used for more efficiently compiling the query and to better report errors + * at compile time. + * - To open document and node collections at runtime. + * + * From the user's or the data model's perspective, the ResourceLoader most notably provides + * a hint to what resources a query will load at runtime, and therefore provides an opportunity + * to prepare in advance for that. For example, between the compile and runtime stage, + * the ResourceLoader sub-class can be asked to pre-load documents in an asynchronous + * and simultaneous way, such that the runtime stage is faster and doesn't + * freeze a graphical interface. + * + * The announce functions are not guaranteed to be called. The loading functions can be called + * with an URI that an announce function hasn't been called with. + * + * The default implementations of ResourceLoader's virtual functions all signals that no + * resources can be loaded. This means ResourceLoader must be sub-classed, in order to + * be able to load resources. + * + * @ingroup Patternist_xdm + * @author Frans Englich <fenglich@trolltech.com> + */ + class Q_AUTOTEST_EXPORT ResourceLoader : public QSharedData + { + public: + enum Usage + { + /** + * Communicates that the URI may be used during query evaluation. + * For example, zero times or very many times. + * + * Typically this hint is given when the URI is available at + * compile-time, but it is used inside a conditional statement + * whose branching can't be determined at compile time. + */ + MayUse, + + /** + * Communicates that the URI will always be used at query + * evaluation. + */ + WillUse + }; + + typedef QExplicitlySharedDataPointer<ResourceLoader> Ptr; + inline ResourceLoader() {} + virtual ~ResourceLoader(); + + /** + * @short Calls to this function are generated by calls to the + * <tt>fn:unparsed-text-available()</tt> function. + * + * @param uri A URI identifying the resource to retrieve. The URI is guaranteed + * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative() + * returns @c false). + * @returns @c true if calling openUnparsedText() while passing @p uri will successfully load + * the document. + * @see <a href="http://www.w3.org/TR/xslt20/#unparsed-text">XSL Transformations + * (XSLT) Version 2.0, 16.2 Reading Text Files</a> + */ + virtual bool isUnparsedTextAvailable(const QUrl &uri, + const QString &encoding); + + /** + * @short May be called by the compilation framework at compile time to report that an + * unparsed text(plain text) file referenced by @p uri will be loaded at runtime. + * + * This function can be called an arbitrary amount of times for the same URI. How many times + * it is called for a URI has no meaning(beyond the first call, that is). For what queries + * the compilation framework can determine what always will be loaded is generally undefined. It + * depends on factors such as how simple the query is what information that is statically + * available and subsequently what optimizations that can apply. + * + * Calls to this function are generated by calls to the <tt>fn:unparsed-text()</tt> function. + * + * @param uri A URI identifying the resource to retrieve. The URI is guaranteed + * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative() + * returns @c false). + * @see <a href="http://www.w3.org/TR/xslt20/#unparsed-text">XSL Transformations + * (XSLT) Version 2.0, 16.2 Reading Text Files</a> + * @returns + * - @c null if no unparsed file can be loaded for @p uri + * - The item type that the value loaded by @p uri will be an instance of. This is + * typically @c xs:string + */ + virtual ItemType::Ptr announceUnparsedText(const QUrl &uri); + + /** + * @short Calls to this function are generated by calls to the <tt>fn:unparsed-text()</tt> function. + * + * @param uri A URI identifying the resource to retrieve. The URI is guaranteed + * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative() + * returns @c false). + * @param encoding the encoding to use. If empty, the user hasn't + * expressed any encoding to use. + * @see <a href="http://www.w3.org/TR/xslt20/#unparsed-text">XSL Transformations + * (XSLT) Version 2.0, 16.2 Reading Text Files</a> + * @returns + * - @c null if no unparsed file can be loaded for @p uri + * - An @c xs:string value(or subtype) containing the content of the file identified + * by @p uri as text. Remember that its type must match the sequence type + * returned by announceUnparsedText() + */ + virtual Item openUnparsedText(const QUrl &uri, + const QString &encoding, + const ReportContext::Ptr &context, + const SourceLocationReflection *const where); + + /** + * @short Calls to this function are generated by calls to the <tt>fn:document()</tt> + * or <tt>fn:doc()</tt> function. + * + * @note This function is responsible for execution stability. Subsequent calls + * to this function with the same URI should result in QXmlNodeModelIndex instances that have + * the same identity. However, in some cases this stability is not of interest, see + * the specification for details. + * @param uri A URI identifying the resource to retrieve. The URI is guaranteed + * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative() + * returns @c false). + * @see QXmlNodeModelIndex::identity() + * @see <a href="http://www.w3.org/TR/xpath-functions/#func-doc">XQuery 1.0 + * and XPath 2.0 Functions and Operators, 15.5.4 fn:doc</a> + * @see <a href="http://www.w3.org/TR/xslt20/#document">XSL Transformations + * (XSLT) Version 2.0, 16.1 Multiple Source Documents</a> + * @returns + * - @c null if no document can be loaded for @p uri + * - A QXmlNodeModelIndex representing the document identified by @p uri. Remember that the QXmlNodeModelIndex + * must match the sequence type returned by announceDocument() + */ + virtual Item openDocument(const QUrl &uri, + const ReportContext::Ptr &context); + + /** + * @short May be called by the compilation framework at compile time to report that an + * XML document referenced by @p uri will be loaded at runtime. + * + * This function can be called an arbitrary amount of times for the same URI, but different + * @p usageHint values. How many times it is called for a URI has no meaning(beyond the first call, + * that is). For what queries the compilation framework can determine what always will be + * loaded is generally undefined. It + * depends on factors such as the complexity of the query, what information that is statically + * available and subsequently what optimizations that can be applied. + * + * Calls to this function are generated by calls to the <tt>fn:document()</tt> + * or <tt>fn:doc()</tt> function. + * + * @param uri A URI identifying the resource to retrieve. The URI is guaranteed + * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative() + * returns @c false). + * @param usageHint A hint to how the URI will be used. + * @returns + * - @c null if the ResourceLoader can determine at this stage that no document + * referenced by @p uri will ever be possible to load. + * - The appropriate sequence type if loading @p uri succeeds at runtime. This must be + * CommonSequenceTypes::zeroOrOneDocument, CommonSequenceTypes::exactlyOneDocument or + * a sequence type that is a sub type of it. + * @see <a href="http://www.w3.org/TR/xpath-functions/#func-doc">XQuery 1.0 + * and XPath 2.0 Functions and Operators, 15.5.4 fn:doc</a> + * @see <a href="http://www.w3.org/TR/xslt20/#document">XSL Transformations + * (XSLT) Version 2.0, 16.1 Multiple Source Documents</a> + */ + virtual SequenceType::Ptr announceDocument(const QUrl &uri, const Usage usageHint); + + /** + * @short Calls to this function are generated by calls to the <tt>fn:doc-available()</tt> function. + * + * @param uri A URI identifying the resource to retrieve. The URI is guaranteed + * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative() + * returns @c false). + * @returns @c true if calling openDocument() while passing @p uri will successfully load + * the document. + * @see <a href="http://www.w3.org/TR/xpath-functions/#func-doc-available">XQuery 1.0 + * and XPath 2.0 Functions and Operators, 15.5.5 fn:doc-available</a> + * @see <a href="http://www.w3.org/TR/xslt20/#document">XSL Transformations + * (XSLT) Version 2.0, 16.1 Multiple Source Documents</a> + */ + virtual bool isDocumentAvailable(const QUrl &uri); + + /** + * @short Calls to this function are generated by calls to the <tt>fn:collection()</tt> function. + * + * @param uri A URI identifying the resource to retrieve. The URI is guaranteed + * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative() + * returns @c false). + * @see <a href="http://www.w3.org/TR/xpath-functions/#func-collection">XQuery 1.0 + * and XPath 2.0 Functions and Operators, 15.5.6 fn:collection</a> + * @returns + * - @c null if no node collection can be loaded for @p uri + * - An QAbstractXmlForwardIterator representing the content identified by @p uri. Remember that the content + * of the QAbstractXmlForwardIterator must match the sequence type returned by announceCollection() + */ + virtual Item::Iterator::Ptr openCollection(const QUrl &uri); + + /** + * @short May be called by the compilation framework at compile time to report that an + * node collection referenced by @p uri will be loaded at runtime. + * + * This function can be called an arbitrary amount of times for the same URI. How many times + * it is called for a URI has no meaning(beyond the first call, that is). For what queries + * the compilation framework can determine what always will be loaded is generally undefined. It + * depends on factors such as how simple the query is what information that is statically + * available and subsequently what optimizations that can apply. + * + * Calls to this function are generated by calls to the <tt>fn:collection()</tt> function. + * + * @note This function is responsible for execution stability. Subsequent calls + * to this function with the same URI should result in QXmlNodeModelIndex instances that have + * the same identity. However, in some cases this stability is not of interest, see + * the specification for details. + * @param uri A URI identifying the resource to retrieve. The URI is guaranteed + * to be valid(QUrl::isValid() returns @c true) and to be absolute(QUrl::isRelative() + * returns @c false). + * @returns + * - @c null if the ResourceLoader can determine at this stage that no document + * referenced by @p uri will ever be possible to load. + * - The appropriate sequence type if loading @p uri succeeds at runtime. This must be + * CommonSequenceTypes::zeroOrMoreNodes or a sequence type that is a sub type of it. + * @see <a href="http://www.w3.org/TR/xpath-functions/#func-collection">XQuery 1.0 + * and XPath 2.0 Functions and Operators, 15.5.6 fn:collection</a> + */ + virtual SequenceType::Ptr announceCollection(const QUrl &uri); + + /** + * @short Asks to unload @p uri from its document pool, such that a + * subsequent request will require a new read. + * + * The default implementation does nothing. + */ + virtual void clear(const QUrl &uri); + }; +} + +QT_END_NAMESPACE + +QT_END_HEADER + +#endif |