dtl


DB_iterator<DataObj, ParamObj>

Category: iterators Component type: type

Description

DB_iterator<DataObj, ParamObj> is an abstract base class that manipulates objects of type DataObj with a particular DBView (and thus the database). The SQL query used by the iterator is generated automatically based on the DBView and postfix parameters specified by the BPA. Each of the subclasses of DB_iterator generates the type of SQL query as suggested by its name. There are six classes that inherit from DB_iterator:

All of these subclasses inherit from the std::iterator template defined in the C++ standard library and thus support the public typedefs DB_iterator::iterator_category, DB_iterator::value_type, DB_iterator::distance_type, DB_iterator::pointer, and DB_iterator::reference.

Definition

Defined in the DB_iterator.h header file.

Example

Inapplicable - abstract base class.

Template parameters

Parameter Description Default
DataObj The type of object that will be written to the DBView. This object will be bound through use of the BCA to the appropriate columns in the database. The set of value types of an DBView::insert_iterator consists of a single type, DataObj.  
ParamObj The type of object that will be used to specify the postfix parameters to the DBView. DefaultParamObj<DataObj> 

Model of

Trivial Iterator.

Type requirements

DataObj and ParamObj must each fulfill the following requirements:.

Public base classes

dtl_ios_base.

Members

Member Where defined Description
DB_iterator() DB_iterator Default constructor.
DB_iterator(DBView<DataObj, ParamObj> &view, bool bPrepare) DB_iterator See below.
DB_iterator(const DB_iterator&) Trivial Iterator The copy constructor.
DB_iterator& operator=(const DB_iterator<DataObj, ParamObj>&) Trivial Iterator The assignment operator
DataObj &operator*() or const DataObj &operator*() const Trivial Iterator Dereferencing operator. Returns (a reference to) the DataObj pointed to in the DBView. See Note [2].
DB_iterator& operator++() Trivial Iterator Preincrement. See Note [1].
const DB_iterator operator++(int) Trivial Iterator Postincrement. See Note [1].
CountedPtr<DataObj> *operator->() Trivial Iterator Dereferencing operator. Returns a pointer to the DataObj pointed to by the DBView.. See Note [2].
ParamObj &Params() DB_iterator See below.
void Params(const ParamObj &params) DB_iterator See below.
const DBView<DataObj, ParamObj> &GetView() DB_iterator See below.
string GetQuery() const DB_iterator See below.
long GetCount() const DB_iterator See below.
long GetLastCount() const DB_iterator See below.
void set_io_handler(IOHandler<DataObj, ParamObj>) DB_iterator See below.
template<class UserHandler> const UserHandler & get_io_handler(UserHandler *dummy) const DB_iterator See below.
IOHandler<DataObj, ParamObj> &get_io_handler() const DB_iterator See below.
dtl_iostate rdstate() const dtl_ios_base See below.
void setstate(dtl_iostate state) dtl_ios_base See below.
void clear(dtl_iostate state = goodbit) dtl_ios_base See below.
bool good() const dtl_ios_base See below.
bool bad() const dtl_ios_base See below.
bool fail() const dtl_ios_base See below.
void swap(DB_iterator<DataObj, ParamObj> &other) DB_iterator See below.
void SetPrepare(bool bPrepare) DB_iterator See below.

New members

These members are not defined in the Trivial Iterator requirements, but are specific to DB_iterator.

Function Description
DB_iterator(DBView<DataObj, ParamObj> &view, bool bPrepare) Creates a DB_iterator which refers to view. If bPrepare is true, uses SQLPrepare() and SQLExecute() to ultimately run the query, otherwise the iterator will use SQLExecDirect().
ParamObj &Params() Returns a reference to the ParamObj which is bound to the postfix parameters used in the query to the database based on the BPA.
void Params(const ParamObj &params) Sets the ParamObj, which is bound to the postfix parameters used in the query to the database based on the BPA, to value params.
const DBView<DataObj, ParamObj> &GetView() Returns a reference to the DBView referred to by this DB_iterator.
string GetQuery() const Returns the SQL query string associated with this DB_iterator.
long GetCount() const Returns the number of DataObj's processed from the database since this select_iterator or the one it was copied or assigned from was first opened. Think of this result as the total number of DataObj's processed in this conceptual iterator's lifetime.
long GetLastCount() const Returns the number of DataObj's processed from the database in last operation. For non-bulk operations for select and insert, this will return 1 as the iterator is operating on a single row. For bulk operations, updates, and deletes, the count returned is the actual number of rows processed by the single operation.
void set_io_handler(IOHandler<DataObj, ParamObj>) Sets the IOHandler for this iterator. The IOHandler will try to handle exceptions thrown by the iterator and tell the code which caught the exception whether to suppress the error or still throw.
template<class UserHandler> const UserHandler & get_io_handler(UserHandler *dummy) Returns the current IOHandler for this object cast to the actual type of the handler based on the dummy pointer passed in. If the dynamic cast of the IOHandler object fails, an exception will be thrown.
IOHandler<DataObj, ParamObj> &get_io_handler() const Returns the current IOHandler for this object as a raw IOHandler object. You must cast to the actual type of the handler to be able to access any of your handler's public members.
dtl_iostate rdstate() const Returns the state of the iterator as a bit field (as in the facilities for iostreams): goodbit == 0, failbit = 0x01, badbit = 0x02, bad_and_fail_bit = 0x03.
void setstate(dtl_iostate state) Sets the state of the iterator to rdstate() | state using a bit field.
void clear(dtl_iostate state = goodbit) Sets the state of the iterator to state using a bit field.
bool good() const Is the iterator in an OK state? Equivalent to rdstate() == goodbit.
bool bad() const Is the iterator in a completely irreconcilable (such as a lost database connection or bad underlying SQL query)? Equivalent to (rdstate() & badbit) != 0.
bool fail() const Is the iterator in a temporary failure state? This means the iterator is still usable, but the last operation on it failed (such as a validation on an element just read or written). Equivalent to ((rdstate() & failbit) != 0) || bad().
void swap(DB_iterator<DataObj, ParamObj> &other) Swaps *this with other.
void SetPrepare(bool bPrepare) If bPrepare is true, then the iterator will use SQLPrepare() and SQLExecute() to run the query. Otherwise, SQLExecDirect() will be used. Must be called before the iterator is opened to take effect.

Notes

[1] This is the operation that actually processes the DataObj with the database via the DBView. Each DB_iterator internally owns a DBStmt object which is allocated and prepared when the underlying ODBC statement handle is first needed and not before. The handle is not opened until absolutely needed in order to make copying and assigning these iterators an inexpensive operation. The DBStmt is executed on each call to operator++(), whether the prefix or postfix version. The iterator implicitly commits all updates upon destruction unless an exception is thrown.

[2] This is not an operation actually declared in DB_iteratordue to the fact that operator*() returns a reference to the iterator itself for insert_iterator, update_iterator, and delete_iterator, but it returns a const reference to the value for select_iterator's. This operator is listed here for completeness.

 

See also

BCA, BPA, DBView, Output Iterator, Input Iterator, Trivial Iterator


[DTL Home]

Copyright © 2002, Michael Gradman and Corwin Joy.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Corwin Joy and Michael Gradman make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

SourceForge Logo

This site written using the ORB. [The ORB]