/thirdparty/qxt/qxtweb-standalone/qxtweb/qxtabstractwebsessionmanager.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 QxtAbstractWebSessionManager
 28
 29\inmodule QxtWeb
 30
 31\brief The QxtAbstractWebSessionManager class is a base class for QxtWeb session managers
 32
 33QxtAbstractWebSessionManager is the base class for all QxtWeb session managers.
 34
 35Session managers are responsible for managing connections between web browsers
 36and web services, for creating sessions and their corresponding service objects,
 37and for managing and dispatching events between browsers and services.
 38
 39Note that the session manager is not responsible for destroying service objects.
 40A service object that wishes to end its corresponding session may destroy itself
 41(see QObject::deleteLater()) and QxtAbstractWebSessionManager will automatically
 42clean up its internal session tracking data.
 43
 44\sa QxtAbstractWebService
 45*/
 46
 47/*!
 48 * \typedef QxtAbstractWebSessionManager::ServiceFactory
 49 * \brief Pointer to a function that generates QxtAbstractWebService objects
 50 *
 51 * \bold TYPEDEF: The ServiceFactory type represents a pointer to a function that takes two
 52 * parameters -- a QxtAbstractWebSessionManager* pointer and an int session ID.
 53 * The function must return a QxtAbstractWebService* pointer.
 54 *
 55 * Usually, an application providing web services will instantiate one
 56 * QxtAbstractWebService object for each session. For services that do not
 57 * require session management, such as those that serve only static pages, a
 58 * single service object may be shared for all requests, or it may use some
 59 * more exotic scheme. See QxtAbstractWebService for more details.
 60 */
 61
 62#include "qxtabstractwebsessionmanager.h"
 63#include "qxtabstractwebsessionmanager_p.h"
 64#include "qxtabstractwebservice.h"
 65#include "qxtmetaobject.h"
 66#include <QtDebug>
 67
 68#ifndef QXT_DOXYGEN_RUN
 69QxtAbstractWebSessionManagerPrivate::QxtAbstractWebSessionManagerPrivate() : factory(0), maxID(1)
 70{
 71    // initializers only
 72}
 73
 74void QxtAbstractWebSessionManagerPrivate::sessionDestroyed(int sessionID)
 75{
 76    if (sessions.contains(sessionID))
 77    {
 78        freeList.enqueue(sessionID);
 79        sessions.remove(sessionID);
 80    }
 81}
 82
 83int QxtAbstractWebSessionManagerPrivate::getNextID()
 84{
 85    if (freeList.empty())
 86    {
 87        int next = maxID;
 88        maxID++;
 89        return next;
 90    }
 91    return freeList.dequeue();
 92}
 93#endif
 94
 95/*!
 96 * Creates a QxtAbstractWebSessionManager with the specified \a parent.
 97 *
 98 * Note that this is an abstract class and cannot be instantiated directly.
 99 */
100QxtAbstractWebSessionManager::QxtAbstractWebSessionManager(QObject* parent) : QObject(parent)
101{
102    QXT_INIT_PRIVATE(QxtAbstractWebSessionManager);
103}
104
105/*!
106 * Sets the service \a factory for the session manager.
107 *
108 * The service factory is invoked every time the session manager creates a new
109 * session. Usually, an application providing web services will instantiate one
110 * QxtAbstractWebService object for each session. For services that do not
111 * require separate sessions, such as those that serve only static pages, the
112 * factory may return a pointer to the same object for multiple requests.
113 *
114 * \sa QxtAbstractWebSessionManager::ServiceFactory
115 */
116void QxtAbstractWebSessionManager::setServiceFactory(ServiceFactory* factory)
117{
118    qxt_d().factory = factory;
119}
120
121/*!
122 * Returns the service factory in use by the session manager.
123 *
124 * \sa setServiceFactory(ServiceFactory*)
125 */
126QxtAbstractWebSessionManager::ServiceFactory* QxtAbstractWebSessionManager::serviceFactory() const
127{
128    return qxt_d().factory;
129}
130
131/*!
132 * Returns the service object corresponding to the provided \a sessionID.
133 */
134QxtAbstractWebService* QxtAbstractWebSessionManager::session(int sessionID) const
135{
136    if (qxt_d().sessions.contains(sessionID))
137        return qxt_d().sessions[sessionID];
138    return 0;
139}
140
141/*!
142 * Creates a new session and returns its session ID.
143 *
144 * This function uses the serviceFactory() to request an instance of the web service.
145 * \sa serviceFactory()
146 */
147int QxtAbstractWebSessionManager::createService()
148{
149    int sessionID = qxt_d().getNextID();
150    if (!qxt_d().factory) return sessionID;
151
152    QxtAbstractWebService* service = serviceFactory()(this, sessionID);
153    qxt_d().sessions[sessionID] = service;
154    // Using QxtBoundFunction to bind the sessionID to the slot invocation
155    QxtMetaObject::connect(service, SIGNAL(destroyed()), QxtMetaObject::bind(&qxt_d(), SLOT(sessionDestroyed(int)), Q_ARG(int, sessionID)), Qt::QueuedConnection);
156    return sessionID; // you can always get the service with this
157}
158
159/*!
160 * \fn virtual bool QxtAbstractWebSessionManager::start()
161 * Starts the session manager.
162 *
163 * Session managers should not create sessions before start() is invoked.
164 * Subclasses are encouraged to refrain from accepting connections until the
165 * session manager is started.
166 */
167
168/*!
169 * \fn virtual void QxtAbstractWebSessionManager::postEvent(QxtWebEvent* event)
170 * Adds the event to the event queue for its associated session.
171 *
172 * Since different protocols may require different event processing behavior,
173 * there is no default implementation in QxtAbstractWebSessionManager. Subclasses
174 * are responsible for maintaining event queues and deciding when and where to
175 * dispatch events.
176 *
177 * Depending on the subclass's implementation posted events may not be dispatched
178 * for some time, and is is possible that an event may never be dispatched if
179 * the session is terminated before the event is handled.
180 *
181 * \sa QxtWebEvent
182 */
183
184/*!
185 * \fn virtual void QxtAbstractWebSessionManager::processEvents()
186 * Processes pending events for all sessions.
187 *
188 * Since different protocols may require different event processing behavior,
189 * there is no default implementation in QxtAbstractWebSessionManager. Subclasses
190 * are responsible for maintaining event queues and deciding when and where to
191 * dispatch events.
192 *
193 * processEvents() is not required to dispatch all events immediately. In
194 * particular, some events may require certain conditions to be met before
195 * they may be fully processed. (For example, because HTTP cookies are sent
196 * as response headers, QxtHttpServerConnector may not dispatch a
197 * QxtWebStoreCookieEvent until a QxtWebPageEvent for the same session is
198 * available.) Unprocessed events may remain in the event queue.
199 *
200 * \sa QxtWebEvent
201 */