/usr/include/Wt/Dbo/collection is in libwtdbo-dev 3.3.4+dfsg-6ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 | // This may look like C code, but it's really -*- C++ -*-
/*
* Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
*
* See the LICENSE file for terms of use.
*/
#ifndef WT_DBO_COLLECTION_H_
#define WT_DBO_COLLECTION_H_
#include <cstddef>
#include <iterator>
#include <set>
#include <Wt/Dbo/ptr>
#include <Wt/Dbo/Session>
namespace Wt {
namespace Dbo {
struct DirectBinding;
struct DynamicBinding;
template <class Result, typename BindStrategy> class Query;
class SqlStatement;
/*! \class collection Wt/Dbo/collection Wt/Dbo/collection
* \brief An STL container for iterating query results.
*
* This is an STL-compatible container that is backed by an SQL
* query for fetching data.
*
* A %collection has two uses in Wt::Dbo:
* - to iterate the results of a Query;
* - to map the many-side of a Many-to-One or Many-to-Many relation.
*
* Its iterators implement the InputIterator requirements, meaning
* you have to traverse the results from begin() to end() solely by
* alternating between reading an element and incrementing the
* iterator. When the collection represents the results of a Query,
* you can only iterate the results just once: i.e. you can have
* only one begin() call.
*
* \code
* typedef dbo::collection< dbo::ptr<User> > Users;
* Users allUsers = session.find<User> ();
* for (Users::const_iterator i = allUsers.begin();
* i != allUsers.end(); ++i){
* dbo::ptr<User> user = *i;
* }
*
* The container is read only when it reflects results of a query.
* Otherwise, when involved in a Many-to-One or Many-to-Many
* relation, you may also insert() and erase() objects in it.
*
* You will typically iterate the container results for local
* processing, or copy the results into a standard STL container for
* extended processing. Not only the weak guarantees of the
* iterators make this recommended, but also in the current
* implementation of the library, all sql statements are
* non-reentrant prepared statements (this limitation is likely to
* be removed in the future): only one %collection, which is backed
* by the same SQL statement may be used at once per session. Thus,
* the following will fail:
*
* \code
* void iterateChildren(Wt::Dbo::ptr<Comment> comment)
* {
* typedef Wt::Dbo::collection<Wt::Dbo::ptr<Comment> > Comments;
* Comments children = comment->children;
*
* for (Comments::const_iterator i = children.begin(); i != children.end(); ++i) {
* std::cerr << "Comment: " << i->text << std::endl;
* iterateChildren(*i); // Illegal since will result in nested use of the same query.
* }
* }
* \endcode
*
* If you cannot gaurantee that during its iteration the same query
* will be reused, you should copy the results in a standard
* container. Note that this is no big overhead since dbo pointers
* are lightweight.
*
* \code
* void iterateChildren(Wt::Dbo::ptr<Comment> comment)
* {
* typedef std::vector<Wt::Dbo::ptr<Comment> > Comments;
*
* Comments children(comment->children.begin(), comment->children.end()); // copy into an STL container, freeing the underlying query for reuse
*
* for (Comments::const_iterator i = children.begin(); i != children.end(); ++i) {
* std::cerr << "Comment: " << i->text << std::endl;
* iterateChildren(*i); // Okay now.
* }
* }
* \endcode
*
* Before iterating a %collection, the session is flushed. In this
* way, the %collection will reflect any pending dirty changes.
*
* \ingroup dbo
*/
template <class C>
class collection
{
struct Activity {
std::set<C> inserted, erased;
std::set<C> transactionInserted, transactionErased;
};
public:
/*! \brief Value type.
*/
typedef C value_type;
typedef value_type key_type;
typedef const value_type& const_reference;
typedef std::size_t size_type;
typedef std::ptrdiff_t difference_type;
typedef value_type *pointer;
typedef const value_type *const_pointer;
class const_iterator;
/*! \brief Iterator.
*/
class iterator : public std::iterator<std::input_iterator_tag, C>
{
public:
/*! \brief Copy constructor.
*/
iterator(const iterator& other);
/*! \brief Destructor.
*/
~iterator();
/*! \brief Assignment operator.
*/
iterator& operator= (const iterator& other);
/*! \brief Dereference operator.
*/
C& operator*();
/*! \brief Dereference operator.
*/
C *operator->();
/*! \brief Comparison operator.
*
* Returns true if two iterators point to the same value in the
* same %collection, or point both to the end of a collection.
*/
bool operator== (const iterator& other) const;
/*! \brief Comparison operator.
*/
bool operator!= (const iterator& other) const;
/*! \brief Pre increment operator.
*/
iterator& operator++ ();
/*! \brief Post increment operator.
*/
iterator operator++ (int);
struct shared_impl {
const collection<C>& collection_;
SqlStatement *statement_;
value_type current_;
int useCount_;
bool queryEnded_;
unsigned posPastQuery_;
bool ended_;
shared_impl(const collection<C>& collection, SqlStatement *statement);
~shared_impl();
void fetchNextRow();
typename collection<C>::value_type& current();
};
private:
shared_impl *impl_;
iterator();
iterator(const collection<C>& collection, SqlStatement *statement);
void takeImpl();
void releaseImpl();
friend class collection<C>;
friend class const_iterator;
};
/*! \brief Const Iterator.
*/
class const_iterator : public std::iterator<std::input_iterator_tag, C>
{
public:
/*! \brief Copy constructor.
*/
const_iterator(const const_iterator& other);
/*! \brief Copy constructor.
*/
const_iterator(const typename collection<C>::iterator& other);
/*! \brief Assignment operator.
*/
const_iterator& operator= (const const_iterator& other);
/*! \brief Assignment operator.
*/
const_iterator& operator= (const iterator& other);
/*! \brief Dereference operator.
*/
C operator*();
/*! \brief Dereference operator.
*/
const C *operator->();
/*! \brief Comparison operator.
*
* Returns true if two iterators point to the same value in the
* same %collection.
*/
bool operator== (const const_iterator& other) const;
/*! \brief Comparison operator.
*/
bool operator!= (const const_iterator& other) const;
/*! \brief Pre increment operator.
*/
const_iterator& operator++ ();
/*! \brief Post increment operator.
*/
const_iterator operator++ (int);
private:
typename collection<C>::iterator impl_;
const_iterator();
const_iterator(const collection<C>& collection, SqlStatement *statement);
friend class collection<C>;
};
/*! \brief Default constructor.
*
* Constructs an empty %collection that is not bound to a database
* session or query.
*/
collection();
/*! \brief Copy constructor.
*/
collection(const collection<C>& other);
/*! \brief Assignment operator.
*/
collection<C>& operator=(const collection<C>& other);
/*! \brief Destructor.
*/
~collection();
/*! \brief Returns an iterator to the begin of the %collection.
*
* \sa end()
*/
iterator begin();
/*! \brief Returns an iterator to the end of the %collection.
*
* \sa begin()
*/
iterator end();
/*! \brief Returns a const iterator to the begin of the %collection.
*
* \sa end()
*/
const_iterator begin() const;
/*! \brief Returns a const iterator to the end of the %collection.
*
* \sa begin()
*/
const_iterator end() const;
/*! \brief Returns a reference to the first object.
*
* This is equivalent to:
* \code
* *(collection.begin())
* \endcode
*/
C front() const;
/*! \brief Returns the size.
*
* This will execute an SQL <tt>count(*)</tt> statement to fetch the
* size of the %collection without fetching all results.
*
* If the %collection represents the result of a Query, the underlying
* query is run only once, and its result is cached so that size() always
* returns the same value.
*/
size_type size() const;
/*! \brief Inserts an object.
*
* \note This is only implemented for %collections that are
* involved in a ManyToOne or ManyToMany relation, and not for
* collections that are used to iterated the result of a query.
*
* \sa erase()
*/
void insert(C c);
/*! \brief Removes an object.
*
* \note This is only implemented for %collections that are
* involved in a ManyToOne or ManyToMany relation, and not for
* collections that are used to iterated the result of a query.
*
* \sa insert()
*/
void erase(C c);
/*! \brief Clears the collection.
*
* \note This is only implemented for %collections that are
* involved in a ManyToOne or ManyToMany relation, and not for
* collections that are used to iterated the result of a query.
*
* \sa erase()
*/
void clear();
/*! \brief Returns the whether the collection contains an object.
*
* This creates a suitable query that checks whether the collection
* contains ptr<X> objects (without getting the entire collection from
* the database). The returned value is the number of times the collection
* contains the object (0 or 1).
*
* \sa find()
*
* \note This is (currently) only implemented for %collections that are
* involved in a ManyToOne or ManyToMany relation, and not for
* collections that are used to iterate the result of a query.
*/
int count(C c) const;
/*! \brief Returns the session to which this %collection is bound.
*/
Session *session() const { return session_; }
/*! \brief Returns the query that backs the collection.
*
* Returns the query that backs the collection. This can be used to
* search for a subset or to browse the results in a particular order.
*
* \sa count()
*
* \note This is (currently) only implemented for %collections that are
* involved in a ManyToOne or ManyToMany relation, and not for
* collections that are used to iterate the result of a query.
*/
Query<C, DynamicBinding> find() const;
const std::vector<C>& manualModeInsertions() const { return manualModeInsertions_; }
std::vector<C>& manualModeInsertions() { return manualModeInsertions_; }
const std::vector<C>& manualModeRemovals() const { return manualModeRemovals_; }
std::vector<C>& manualModeRemovals() { return manualModeRemovals_; }
private:
Session *session_;
enum { QueryCollection, RelationCollection } type_;
// Structure for a relation query
struct RelationData {
const std::string *sql;
MetaDboBase *dbo;
Session::SetInfo *setInfo;
Activity *activity; // only for ManyToMany collections
};
struct QueryData {
SqlStatement *statement, *countStatement;
int size;
int useCount;
};
union {
QueryData *query;
RelationData relation;
} data_;
std::vector<C> manualModeInsertions_;
std::vector<C> manualModeRemovals_;
friend class DboAction;
friend class SessionAddAction;
friend class LoadBaseAction;
friend class SaveBaseAction;
friend class TransactionDoneAction;
template <class D> friend class weak_ptr;
template <class Result, typename BindStrategy> friend class Query;
collection(Session *session, SqlStatement *selectStatement,
SqlStatement *countStatement);
void setRelationData(MetaDboBase *dbo, const std::string *sql,
Session::SetInfo *info);
Activity *activity() const { return data_.relation.activity; }
void resetActivity();
void releaseQuery();
SqlStatement *executeStatement() const;
void iterateDone() const;
};
}
}
#endif // WT_DBO_COLLECTION_H_
|