src/xmlpatterns/api/qxmlschema.cpp

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