src/xmlpatterns/api/qabstractmessagehandler.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 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 #include <QMutex>
  43
  44 #include "private/qobject_p.h"
  45 #include "qabstractmessagehandler.h"
  46
  47 QT_BEGIN_NAMESPACE
  48
  49 class QAbstractMessageHandlerPrivate : public QObjectPrivate
  50 {
  51 public:
  52     QMutex mutex;
  53 };
  54
  55 /*!
  56   \class QAbstractMessageHandler
  57   \threadsafe
  58   \since 4.4
  59   \ingroup xml-tools
  60
  61   \brief The QAbstractMessageHandler class provides a callback interface for handling messages.
  62
  63   QAbstractMessageHandler is an abstract base class that provides a
  64   callback interface for handling messages. For example, class
  65   QXmlQuery parses and runs an XQuery. When it detects a compile
  66   or runtime error, it generates an appropriate error message,
  67   but rather than output the message itself, it passes the message to
  68   the message() function of its QAbstractMessageHandler.
  69   See QXmlQuery::setMessageHandler().
  70
  71   You create a message handler by subclassing QAbstractMessageHandler
  72   and implementing handleMessage(). You then pass a pointer to an
  73   instance of your subclass to any classes that must generate
  74   messages. The messages are sent to the message handler via the
  75   message() function, which forwards them to your handleMessge().
  76   The effect is to serialize the handling of all messages, which
  77   means your QAbstractMessageHandler subclass is thread safe.
  78
  79   A single instance of QAbstractMessageHandler can be called on to
  80   handle messages from multiple sources. Hence, the content of a
  81   message, which is the \e description parameter passed to message()
  82   and handleMessage(), must be interpreted in light of the context
  83   that required the message to be sent. That context is specified by
  84   the \e identifier and \e sourceLocation parameters to message()
  85   handleMessage().
  86  */
  87
  88 /*!
  89   Constructs a QAbstractMessageHandler. The \a parent is passed
  90   to the QObject base class constructor.
  91  */
  92 QAbstractMessageHandler::QAbstractMessageHandler(QObject *parent) : QObject(*new QAbstractMessageHandlerPrivate(), parent)
  93 {
  94 }
  95
  96 /*!
  97   Destructs this QAbstractMessageHandler.
  98  */
  99 QAbstractMessageHandler::~QAbstractMessageHandler()
 100 {
 101 }
 102
 103 /*!
 104   Sends a message to this message handler. \a type is the kind of
 105   message being sent. \a description is the message content. The \a
 106   identifier is a URI that identifies the message and is the key to
 107   interpreting the other arguments.
 108
 109   Typically, this class is used for reporting errors, as is the case
 110   for QXmlQuery, which uses a QAbstractMessageHandler to report
 111   compile and runtime XQuery errors. Hence, using a QUrl as the
 112   message \a identifier is was inspired by the explanation of \l{error
 113   handling in the XQuery language}. Because the \a identifier is
 114   composed of a namespace URI and a local part, identifiers with the
 115   same local part are unique.  The caller is responsible for ensuring
 116   that \a identifier is either a valid QUrl or a default constructed
 117   QUrl.
 118
 119   \a sourceLocation identifies a location in a resource (i.e., file or
 120   document) where the need for reporting a message was detected.
 121
 122   This function unconditionally calls handleMessage(), passing all
 123   its parameters unmodified.
 124
 125   \sa {http://www.w3.org/TR/xquery/#errors}
 126  */
 127 void QAbstractMessageHandler::message(QtMsgType type,
 128                                       const QString &description,
 129                                       const QUrl &identifier,
 130                                       const QSourceLocation &sourceLocation)
 131 {
 132     Q_D(QAbstractMessageHandler);
 133     QMutexLocker(&d->mutex);
 134     handleMessage(type, description, identifier, sourceLocation);
 135 }
 136
 137 /*!
 138   \fn void QAbstractMessageHandler::handleMessage(QtMsgType type,
 139                                                   const QString &description,
 140                                                   const QUrl &identifier = QUrl(),
 141                                                   const QSourceLocation &sourceLocation = QSourceLocation()) = 0
 142
 143   This function must be implemented by the sub-class. message() will
 144   call this function, passing in its parameters, \a type,
 145   \a description, \a identifier and \a sourceLocation unmodified.
 146  */
 147
 148 QT_END_NAMESPACE
 149