/thirdparty/qxt/qxtweb-standalone/qxtweb/qxtabstractwebservice.cpp

  1/****************************************************************************
  2 **
  3 ** Copyright (C) Qxt Foundation. Some rights reserved.
  4 **
  5 ** This file is part of the QxtWeb module of the Qxt library.
  6 **
  7 ** This library is free software; you can redistribute it and/or modify it
  8 ** under the terms of the Common Public License, version 1.0, as published
  9 ** by IBM, and/or under the terms of the GNU Lesser General Public License,
 10 ** version 2.1, as published by the Free Software Foundation.
 11 **
 12 ** This file is provided "AS IS", without WARRANTIES OR CONDITIONS OF ANY
 13 ** KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY
 14 ** WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR
 15 ** FITNESS FOR A PARTICULAR PURPOSE.
 16 **
 17 ** You should have received a copy of the CPL and the LGPL along with this
 18 ** file. See the LICENSE file and the cpl1.0.txt/lgpl-2.1.txt files
 19 ** included with the source distribution for more information.
 20 ** If you did not receive a copy of the licenses, contact the Qxt Foundation.
 21 **
 22 ** <http://libqxt.org>  <foundation@libqxt.org>
 23 **
 24 ****************************************************************************/
 25
 26/*!
 27\class QxtAbstractWebService
 28
 29\inmodule QxtWeb
 30
 31\brief The QxtAbstractWebService class is a base interface for web services
 32
 33QxtAbstractWebService provides a common interface for all web service classes.
 34It uses an event-driven design instead of the more traditional request-response
 35design used by many web scripting languages. When the user requests a web
 36page, the service receives a pageRequestedEvent; after the service assembles
 37the response, it must post a QxtWebPageEvent (or a subclass, such as
 38QxtWebRedirectEvent or QxtWebErrorEvent).
 39
 40Usually, an application providing web services will instantiate one
 41QxtAbstractWebService object for each session, but this is not a requirement.
 42For services that do not require session management, such as those that serve
 43only static content, the session factory may return the same pointer for
 44every invocation, or it may use some more exotic scheme.
 45
 46When using one service object per session, each service's data members are
 47independent and may be used to track state across requests. A service object
 48shared among multiple sessions will retain state across requests as well but
 49it must implement its own mechanism for separating non-shared data.
 50
 51The QxtWeb architecture is not multithreaded; that is, QxtAbstractWebService
 52does not automatically spawn a process for every session. However,
 53QxtAbstractWebSessionManager performs thread-safe event dispatching, so
 54subclasses of QxtAbstractWebService are free to create threads themselves.
 55
 56A web service object may delete itself (see QObject::deleteLater()) to end
 57the associated session.
 58
 59\sa QxtAbstractWebSessionManager::ServiceFactory
 60*/
 61
 62/*
 63 * TODO:
 64 * The current architecture only allows for two behaviors: creating a new session
 65 * for every connection without a session cookie, or not using sessions at all.
 66 * This needs to be fixed by adding a function to the session manager to explicitly
 67 * create a new session.
 68 */
 69
 70#include "qxtabstractwebservice.h"
 71
 72#ifndef QXT_DOXYGEN_RUN
 73class QxtAbstractWebServicePrivate : public QxtPrivate<QxtAbstractWebService>
 74{
 75public:
 76    QXT_DECLARE_PUBLIC(QxtAbstractWebService)
 77    QxtAbstractWebServicePrivate() {}
 78
 79    QxtAbstractWebSessionManager* manager;
 80};
 81#endif
 82
 83/*!
 84 * Creates a QxtAbstractWebService with the specified \a parent and session \a manager.
 85 *
 86 * Often, the session manager will also be the parent, but this is not a requirement.
 87 *
 88 * Note that this is an abstract class and cannot be instantiated directly.
 89 */
 90QxtAbstractWebService::QxtAbstractWebService(QxtAbstractWebSessionManager* manager, QObject* parent) : QObject(parent)
 91{
 92    QXT_INIT_PRIVATE(QxtAbstractWebService);
 93    qxt_d().manager = manager;
 94}
 95
 96/*!
 97 * Returns the session manager associated with the web service.
 98 */
 99QxtAbstractWebSessionManager* QxtAbstractWebService::sessionManager() const
100{
101    return qxt_d().manager;
102}
103
104/*!
105 * \fn void QxtAbstractWebService::postEvent(QxtWebEvent* event)
106 * Posts an \a event to a web browser that has made a request to the service.
107 */
108
109/*!
110 * \fn virtual void QxtAbstractWebService::pageRequestedEvent(QxtWebRequestEvent* event)
111 * This \a event handler must be reimplemented in subclasses to receive page
112 * request events.
113 *
114 * Every page request event received MUST be responded to with a QxtWebPageEvent
115 * or a QxtWebPageEvent subclass. This response does not have to be posted
116 * during the execution of this function, to support asynchronous design, but
117 * failure to post an event will cause the web browser making the request to
118 * wait until it times out.
119 *
120 * \sa QxtWebRequestEvent
121 */