src/xmlpatterns/api/qxmlschema.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 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 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qxmlschema.h"
  43 #include "qxmlschema_p.h"
  44
  45 #include <QtCore/QIODevice>
  46 #include <QtCore/QUrl>
  47
  48 QT_BEGIN_NAMESPACE
  49
  50 /*!
  51   \class QXmlSchema
  52
  53   \brief The QXmlSchema class provides loading and validation of a W3C XML Schema.
  54
  55   \reentrant
  56   \since 4.6
  57   \ingroup xml-tools
  58
  59   The QXmlSchema class loads, compiles and validates W3C XML Schema files
  60   that can be used further for validation of XML instance documents via
  61   \l{QXmlSchemaValidator}.
  62
  63   The following example shows how to load a XML Schema file from the network
  64   and test whether it is a valid schema document:
  65
  66   \snippet doc/src/snippets/qxmlschema/main.cpp 0
  67
  68   \section1 XML Schema Version
  69
  70   This class is used to represent schemas that conform to the \l{XML Schema} 1.0
  71   specification.
  72
  73   \sa QXmlSchemaValidator, {xmlpatterns/schema}{XML Schema Validation Example}
  74 */
  75
  76 /*!
  77   Constructs an invalid, empty schema that cannot be used until
  78   load() is called.
  79  */
  80 QXmlSchema::QXmlSchema()
  81     : d(new QXmlSchemaPrivate(QXmlNamePool()))
  82 {
  83 }
  84
  85 /*!
  86   Constructs a QXmlSchema that is a copy of \a other. The new
  87   instance will share resources with the existing schema
  88   to the extent possible.
  89  */
  90 QXmlSchema::QXmlSchema(const QXmlSchema &other)
  91     : d(other.d)
  92 {
  93 }
  94
  95 /*!
  96   Destroys this QXmlSchema.
  97  */
  98 QXmlSchema::~QXmlSchema()
  99 {
 100 }
 101
 102 /*!
 103   Sets this QXmlSchema to a schema loaded from the \a source
 104   URI.
 105
 106   If the schema \l {isValid()} {is invalid}, \c{false} is returned
 107   and the behavior is undefined.
 108
 109   Example:
 110
 111   \snippet doc/src/snippets/qxmlschema/main.cpp 0
 112
 113   \sa isValid()
 114  */
 115 bool QXmlSchema::load(const QUrl &source)
 116 {
 117     d->load(source, QString());
 118     return d->isValid();
 119 }
 120
 121 /*!
 122   Sets this QXmlSchema to a schema read from the \a source
 123   device. The device must have been opened with at least
 124   QIODevice::ReadOnly.
 125
 126   \a documentUri represents the schema obtained from the \a source
 127   device. It is the base URI of the schema, that is used
 128   internally to resolve relative URIs that appear in the schema, and
 129   for message reporting.
 130
 131   If \a source is \c null or not readable, or if \a documentUri is not
 132   a valid URI, behavior is undefined.
 133
 134   If the schema \l {isValid()} {is invalid}, \c{false} is returned
 135   and the behavior is undefined.
 136
 137   Example:
 138
 139   \snippet doc/src/snippets/qxmlschema/main.cpp 1
 140
 141   \sa isValid()
 142  */
 143 bool QXmlSchema::load(QIODevice *source, const QUrl &documentUri)
 144 {
 145     d->load(source, documentUri, QString());
 146     return d->isValid();
 147 }
 148
 149 /*!
 150   Sets this QXmlSchema to a schema read from the \a data
 151
 152   \a documentUri represents the schema obtained from the \a data.
 153   It is the base URI of the schema, that is used internally to
 154   resolve relative URIs that appear in the schema, and
 155   for message reporting.
 156
 157   If \a documentUri is not a valid URI, behavior is undefined.
 158   \sa isValid()
 159
 160   If the schema \l {isValid()} {is invalid}, \c{false} is returned
 161   and the behavior is undefined.
 162
 163   Example:
 164
 165   \snippet doc/src/snippets/qxmlschema/main.cpp 2
 166
 167   \sa isValid()
 168  */
 169 bool QXmlSchema::load(const QByteArray &data, const QUrl &documentUri)
 170 {
 171     d->load(data, documentUri, QString());
 172     return d->isValid();
 173 }
 174
 175 /*!
 176   Returns true if this schema is valid. Examples of invalid schemas
 177   are ones that contain syntax errors or that do not conform the
 178   W3C XML Schema specification.
 179  */
 180 bool QXmlSchema::isValid() const
 181 {
 182     return d->isValid();
 183 }
 184
 185 /*!
 186   Returns the name pool used by this QXmlSchema for constructing \l
 187   {QXmlName} {names}. There is no setter for the name pool, because
 188   mixing name pools causes errors due to name confusion.
 189  */
 190 QXmlNamePool QXmlSchema::namePool() const
 191 {
 192     return d->namePool();
 193 }
 194
 195 /*!
 196   Returns the document URI of the schema or an empty URI if no
 197   schema has been set.
 198  */
 199 QUrl QXmlSchema::documentUri() const
 200 {
 201     return d->documentUri();
 202 }
 203
 204 /*!
 205   Changes the \l {QAbstractMessageHandler}{message handler} for this
 206   QXmlSchema to \a handler. The schema sends all compile and
 207   validation messages to this message handler. QXmlSchema does not take
 208   ownership of \a handler.
 209
 210   Normally, the default message handler is sufficient. It writes
 211   compile and validation messages to \e stderr. The default message
 212   handler includes color codes if \e stderr can render colors.
 213
 214   When QXmlSchema calls QAbstractMessageHandler::message(),
 215   the arguments are as follows:
 216
 217   \table
 218   \header
 219     \o message() argument
 220     \o Semantics
 221   \row
 222     \o QtMsgType type
 223     \o Only QtWarningMsg and QtFatalMsg are used. The former
 224        identifies a warning, while the latter identifies an error.
 225   \row
 226     \o const QString & description
 227     \o An XHTML document which is the actual message. It is translated
 228        into the current language.
 229   \row
 230     \o const QUrl &identifier
 231     \o Identifies the error with a URI, where the fragment is
 232        the error code, and the rest of the URI is the error namespace.
 233   \row
 234     \o const QSourceLocation & sourceLocation
 235     \o Identifies where the error occurred.
 236   \endtable
 237
 238  */
 239 void QXmlSchema::setMessageHandler(QAbstractMessageHandler *handler)
 240 {
 241     d->setMessageHandler(handler);
 242 }
 243
 244 /*!
 245     Returns the message handler that handles compile and validation
 246     messages for this QXmlSchema.
 247  */
 248 QAbstractMessageHandler *QXmlSchema::messageHandler() const
 249 {
 250     return d->messageHandler();
 251 }
 252
 253 /*!
 254   Sets the URI resolver to \a resolver. QXmlSchema does not take
 255   ownership of \a resolver.
 256
 257   \sa uriResolver()
 258  */
 259 void QXmlSchema::setUriResolver(const QAbstractUriResolver *resolver)
 260 {
 261     d->setUriResolver(resolver);
 262 }
 263
 264 /*!
 265   Returns the schema's URI resolver. If no URI resolver has been set,
 266   QtXmlPatterns will use the URIs in schemas as they are.
 267
 268   The URI resolver provides a level of abstraction, or \e{polymorphic
 269   URIs}. A resolver can rewrite \e{logical} URIs to physical ones, or
 270   it can translate obsolete or invalid URIs to valid ones.
 271
 272   When QtXmlPatterns calls QAbstractUriResolver::resolve() the
 273   absolute URI is the URI mandated by the schema specification, and the
 274   relative URI is the URI specified by the user.
 275
 276   \sa setUriResolver()
 277  */
 278 const QAbstractUriResolver *QXmlSchema::uriResolver() const
 279 {
 280     return d->uriResolver();
 281 }
 282
 283 /*!
 284   Sets the network manager to \a manager.
 285   QXmlSchema does not take ownership of \a manager.
 286
 287   \sa networkAccessManager()
 288  */
 289 void QXmlSchema::setNetworkAccessManager(QNetworkAccessManager *manager)
 290 {
 291     d->setNetworkAccessManager(manager);
 292 }
 293
 294 /*!
 295   Returns the network manager, or 0 if it has not been set.
 296
 297   \sa setNetworkAccessManager()
 298  */
 299 QNetworkAccessManager *QXmlSchema::networkAccessManager() const
 300 {
 301     return d->networkAccessManager();
 302 }
 303
 304 QT_END_NAMESPACE