--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/xmlpatterns/data/qresourceloader_p.h Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,320 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@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 <frans.englich@nokia.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 cannot 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