drogon
C++14/17-based HTTP application framework
Loading...
Searching...
No Matches
drogon::orm::Mapper< T > Class Template Reference

The mapper template. More...

#include <drogon/orm/Mapper.h>

Collaboration diagram for drogon::orm::Mapper< T >:

Public Types

using SingleRowCallback = std::function<void(T)>
using MultipleRowsCallback = std::function<void(std::vector<T>)>
using CountCallback = std::function<void(const size_t)>
using TraitsPKType

Public Member Functions

 Mapper (DbClientPtr client)
 Construct a new Mapper object.
Mapper< T > & limit (size_t limit)
 Add a limit to the query.
Mapper< T > & offset (size_t offset)
 Add a offset to the query.
Mapper< T > & orderBy (const std::string &colName, const SortOrder &order=SortOrder::ASC)
 Set the order of the results.
Mapper< T > & orderBy (size_t colIndex, const SortOrder &order=SortOrder::ASC)
 Set the order of the results.
Mapper< T > & paginate (size_t page, size_t perPage)
 Set limit and offset to achieve pagination. This method will override limit() and offset(), and will be overridden by them.
Mapper< T > & forUpdate ()
 Lock the result for updating.
Mapper< T > & innerJoin (const std::string &table, const std::string &onLeft, const std::string &onRight)
 Add an INNER JOIN clause to the query.
Mapper< T > & leftJoin (const std::string &table, const std::string &onLeft, const std::string &onRight)
 Add a LEFT JOIN clause to the query.
Mapper< T > & rightJoin (const std::string &table, const std::string &onLeft, const std::string &onRight)
 Add a RIGHT JOIN clause to the query.
template<typename U = T>
findByPrimaryKey (const TraitsPKType &key) noexcept(false)
 Find a record by the primary key.
template<typename U = T>
void findByPrimaryKey (const TraitsPKType &key, const SingleRowCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously find a record by the primary key.
template<typename U = T>
std::future< T > findFutureByPrimaryKey (const TraitsPKType &key) noexcept
 Asynchronously find a record by the primary key.
std::vector< T > findAll () noexcept(false)
 Find all the records in the table.
void findAll (const MultipleRowsCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously find all the records in the table.
std::future< std::vector< T > > findFutureAll () noexcept
 Asynchronously find all the records in the table.
size_t count (const Criteria &criteria=Criteria()) noexcept(false)
 Get the count of rows that match the given criteria.
void count (const Criteria &criteria, const CountCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously get the number of rows that match the given criteria.
std::future< size_t > countFuture (const Criteria &criteria=Criteria()) noexcept
 Asynchronously get the number of rows that match the given criteria.
findOne (const Criteria &criteria) noexcept(false)
 Find one record that matches the given criteria.
void findOne (const Criteria &criteria, const SingleRowCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously find one record that matches the given criteria.
std::future< T > findFutureOne (const Criteria &criteria) noexcept
 Asynchronously find one record that matches the given criteria.
std::vector< T > findBy (const Criteria &criteria) noexcept(false)
 Select the rows that match the given criteria.
void findBy (const Criteria &criteria, const MultipleRowsCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously select the rows that match the given criteria.
std::future< std::vector< T > > findFutureBy (const Criteria &criteria) noexcept
 Asynchronously select the rows that match the given criteria.
void insert (T &obj) noexcept(false)
 Insert a row into the table.
void insert (const T &obj, const SingleRowCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously insert a row into the table.
std::future< T > insertFuture (const T &) noexcept
 Asynchronously insert a row into the table.
size_t update (const T &obj) noexcept(false)
 Update a record.
void update (const T &obj, const CountCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously update a record.
std::future< size_t > updateFuture (const T &obj) noexcept
 Asynchronously update a record.
template<typename... Arguments>
size_t updateBy (const std::vector< std::string > &colNames, const Criteria &criteria, Arguments &&...args) noexcept(false)
 Update a record that match both the primary key and the given criteria.
template<typename... Arguments>
void updateBy (const std::vector< std::string > &colNames, const CountCallback &rcb, const ExceptionCallback &ecb, const Criteria &criteria, Arguments &&...args) noexcept
 Asynchronously select the rows that match both the primary key and the given criteria.
template<typename... Arguments>
std::future< size_t > updateFutureBy (const std::vector< std::string > &colNames, const Criteria &criteria, Arguments &&...args) noexcept
 Asynchronously update a record that match both the primary key and the given criteria.
template<typename... Arguments>
size_t increment (const std::vector< std::string > &colNames, const Criteria &criteria, Arguments... args) noexcept(false)
 Update some records that match the given criteria.
template<typename... Arguments>
void increment (const std::vector< std::string > &colNames, const CountCallback &rcb, const ExceptionCallback &ecb, const Criteria &criteria, Arguments... args) noexcept
 Asynchronously update some records that match the given criteria.
template<typename... Arguments>
std::future< size_t > incrementFuture (const std::vector< std::string > &colNames, const Criteria &criteria, Arguments... args) noexcept
 Asynchronously update some records that match the given criteria.
size_t deleteOne (const T &obj) noexcept(false)
 Delete a record from the table.
void deleteOne (const T &obj, const CountCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously delete a record from the table.
std::future< size_t > deleteFutureOne (const T &obj) noexcept
 Asynchronously delete a record from the table.
size_t deleteBy (const Criteria &criteria) noexcept(false)
 Delete records that satisfy the given criteria.
void deleteBy (const Criteria &criteria, const CountCallback &rcb, const ExceptionCallback &ecb) noexcept
 Delete records that match the given criteria asynchronously.
std::future< size_t > deleteFutureBy (const Criteria &criteria) noexcept
 Delete records that match the given criteria asynchronously.
size_t deleteByPrimaryKey (const TraitsPKType &key) noexcept(false)
 Delete the record that matches the given primary key.
void deleteByPrimaryKey (const TraitsPKType &key, const CountCallback &rcb, const ExceptionCallback &ecb) noexcept
 Asynchronously delete the record that matches the given primary key.
std::future< size_t > deleteFutureByPrimaryKey (const TraitsPKType &key) noexcept
 Delete the record that matches the given primary key asynchronously.

Protected Member Functions

void clear ()
template<typename PKType = decltype(T::primaryKeyName)>
void makePrimaryKeyCriteria (std::string &sql)
template<typename PKType = decltype(T::primaryKeyName)>
void outputPrimaryKeyToBinder (const TraitsPKType &pk, internal::SqlBinder &binder)
template<typename TP, ssize_t N = std::tuple_size<TP>::value>
void tupleToBinder (const TP &t, internal::SqlBinder &binder)
std::string replaceSqlPlaceHolder (const std::string &sqlStr, const std::string &holderStr) const

Protected Attributes

DbClientPtr client_
size_t limit_ {0}
size_t offset_ {0}
std::string orderByString_
std::string joinString_
bool forUpdate_ {false}

Detailed Description

template<typename T>
class drogon::orm::Mapper< T >

The mapper template.

Template Parameters
TThe type of the model to be mapped.

The mapping between the model object and the database table is performed by the Mapper class template. The Mapper class template encapsulates common operations such as adding, deleting, and changing, so that the user can perform the above operations without writing a SQL statement.

The construction of the Mapper object is very simple. The template parameter is the type of the model you want to access. The constructor has only one parameter, which is the DbClient smart pointer mentioned earlier. As mentioned earlier, the Transaction class is a subclass of DbClient, so you can also construct a Mapper object with a smart pointer to a transaction, which means that the Mapper mapping also supports transactions.

Like DbClient, Mapper also provides asynchronous and synchronous interfaces. The synchronous interface is blocked and may throw an exception. The returned future object is blocked in the get() method and may throw an exception. The normal asynchronous interface does not throw an exception, but returns the result through two callbacks (result callback and exception callback). The type of the exception callback is the same as that in the DbClient interface. The result callback is also divided into several categories according to the interface function.

Member Typedef Documentation

◆ TraitsPKType

template<typename T>
using drogon::orm::Mapper< T >::TraitsPKType
Initial value:
typename internal::
Traits<T, !std::is_same_v<typename T::PrimaryKeyType, void>>::type

Constructor & Destructor Documentation

◆ Mapper()

template<typename T>
drogon::orm::Mapper< T >::Mapper ( DbClientPtr client)
inlineexplicit

Construct a new Mapper object.

Parameters
clientThe smart pointer to the database client object.

Member Function Documentation

◆ count() [1/2]

template<typename T>
void drogon::orm::Mapper< T >::count ( const Criteria & criteria,
const CountCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Asynchronously get the number of rows that match the given criteria.

Parameters
criteriaThe criteria.
rcbis clalled with the result.
ecbis called when an error occurs.

◆ count() [2/2]

template<typename T>
size_t drogon::orm::Mapper< T >::count ( const Criteria & criteria = Criteria())
inline

Get the count of rows that match the given criteria.

Parameters
criteriaThe criteria.
Returns
size_t The number of rows.

◆ countFuture()

template<typename T>
std::future< size_t > drogon::orm::Mapper< T >::countFuture ( const Criteria & criteria = Criteria())
inlinenoexcept

Asynchronously get the number of rows that match the given criteria.

Parameters
criteriaThe criteria.
Returns
std::future<size_t> The future object with which user can get the number of rows

◆ deleteBy() [1/2]

template<typename T>
size_t drogon::orm::Mapper< T >::deleteBy ( const Criteria & criteria)
inline

Delete records that satisfy the given criteria.

Parameters
criteriaThe criteria.
Returns
size_t The number of deleted records.

◆ deleteBy() [2/2]

template<typename T>
void drogon::orm::Mapper< T >::deleteBy ( const Criteria & criteria,
const CountCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Delete records that match the given criteria asynchronously.

Parameters
criteriaThe criteria
rcbis called with the number of deleted records.
ecbis called when an error occurs.

◆ deleteByPrimaryKey() [1/2]

template<typename T>
size_t drogon::orm::Mapper< T >::deleteByPrimaryKey ( const TraitsPKType & key)

Delete the record that matches the given primary key.

Parameters
keyThe primary key.
Returns
size_t The number of deleted records (1 or 0).

◆ deleteByPrimaryKey() [2/2]

template<typename T>
void drogon::orm::Mapper< T >::deleteByPrimaryKey ( const TraitsPKType & key,
const CountCallback & rcb,
const ExceptionCallback & ecb )
noexcept

Asynchronously delete the record that matches the given primary key.

Parameters
keyThe primary key.
rcbis called with the number of deleted records.
ecbis called when an error occurs.

◆ deleteFutureBy()

template<typename T>
std::future< size_t > drogon::orm::Mapper< T >::deleteFutureBy ( const Criteria & criteria)
inlinenoexcept

Delete records that match the given criteria asynchronously.

Parameters
criteriaThe criteria
Returns
std::future<size_t> The future object with which user can get the number of deleted records

◆ deleteFutureByPrimaryKey()

template<typename T>
std::future< size_t > drogon::orm::Mapper< T >::deleteFutureByPrimaryKey ( const TraitsPKType & key)
inlinenoexcept

Delete the record that matches the given primary key asynchronously.

Parameters
keyThe primary key.
Returns
std::future<size_t> The future object with which user can get the number of deleted records

◆ deleteFutureOne()

template<typename T>
std::future< size_t > drogon::orm::Mapper< T >::deleteFutureOne ( const T & obj)
inlinenoexcept

Asynchronously delete a record from the table.

Parameters
objThe record.
Returns
std::future<size_t> The future object with which user can get the number of deleted records.
Note
The table must have a primary key.

◆ deleteOne() [1/2]

template<typename T>
size_t drogon::orm::Mapper< T >::deleteOne ( const T & obj)
inline

Delete a record from the table.

Parameters
objThe record.
Returns
size_t The number of deleted records.
Note
The table must have a primary key.

◆ deleteOne() [2/2]

template<typename T>
void drogon::orm::Mapper< T >::deleteOne ( const T & obj,
const CountCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Asynchronously delete a record from the table.

Parameters
objThe record.
rcbis called with the number of deleted records.
ecbis called when an error occurs.
Note
The table must have a primary key.

◆ findAll() [1/2]

template<typename T>
std::vector< T > drogon::orm::Mapper< T >::findAll ( )
inline

Find all the records in the table.

Returns
std::vector<T> The vector of all the records.

◆ findAll() [2/2]

template<typename T>
void drogon::orm::Mapper< T >::findAll ( const MultipleRowsCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Asynchronously find all the records in the table.

Parameters
rcbis called with the result.
ecbis called when an error occurs.

◆ findBy() [1/2]

template<typename T>
std::vector< T > drogon::orm::Mapper< T >::findBy ( const Criteria & criteria)
inlinenoexcept

Select the rows that match the given criteria.

Parameters
criteriaThe criteria.
Returns
std::vector<T> The vector of rows that match the given criteria.

◆ findBy() [2/2]

template<typename T>
void drogon::orm::Mapper< T >::findBy ( const Criteria & criteria,
const MultipleRowsCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Asynchronously select the rows that match the given criteria.

Parameters
criteriaThe criteria.
rcbis called with the result.
ecbis called when an error occurs.

◆ findByPrimaryKey() [1/2]

template<typename T>
template<typename U = T>
T drogon::orm::Mapper< T >::findByPrimaryKey ( const TraitsPKType & key)
inline

Find a record by the primary key.

Parameters
keyThe value of the primary key.
Returns
T The record of the primary key.
Note
If no hit record exists, an UnexpectedRows exception is thrown.

◆ findByPrimaryKey() [2/2]

template<typename T>
template<typename U = T>
void drogon::orm::Mapper< T >::findByPrimaryKey ( const TraitsPKType & key,
const SingleRowCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Asynchronously find a record by the primary key.

Parameters
keyThe value of the primary key.
rcbIs called when a record is found.
ecbIs called when an error occurs or a record cannot be found.

◆ findFutureAll()

template<typename T>
std::future< std::vector< T > > drogon::orm::Mapper< T >::findFutureAll ( )
inlinenoexcept

Asynchronously find all the records in the table.

Returns
std::future<std::vector<T>> The future object with which user can get the result.

◆ findFutureBy()

template<typename T>
std::future< std::vector< T > > drogon::orm::Mapper< T >::findFutureBy ( const Criteria & criteria)
inlinenoexcept

Asynchronously select the rows that match the given criteria.

Parameters
criteriaThe criteria.
Returns
std::future<std::vector<T>> The future object with which user can get the result.

◆ findFutureByPrimaryKey()

template<typename T>
template<typename U = T>
std::future< T > drogon::orm::Mapper< T >::findFutureByPrimaryKey ( const TraitsPKType & key)
inlinenoexcept

Asynchronously find a record by the primary key.

Parameters
keyThe value of the primary key.
Returns
std::future<T> The future object with which user can get the result.
Note
If no hit record exists, an UnexpectedRows exception is thrown when user calls the get() method of the future object.

◆ findFutureOne()

template<typename T>
std::future< T > drogon::orm::Mapper< T >::findFutureOne ( const Criteria & criteria)
inlinenoexcept

Asynchronously find one record that matches the given criteria.

Parameters
criteriaThe criteria.
Returns
std::future<T> The future object with which user can get the result.
Note
if the number of rows is greater than one or equal to zero, an UnexpectedRows exception is thrown when the get() method of the future object is called.

◆ findOne() [1/2]

template<typename T>
T drogon::orm::Mapper< T >::findOne ( const Criteria & criteria)
inline

Find one record that matches the given criteria.

Parameters
criteriaThe criteria.
Returns
T The result record.
Note
if the number of rows is greater than one or equal to zero, an UnexpectedRows exception is thrown.

◆ findOne() [2/2]

template<typename T>
void drogon::orm::Mapper< T >::findOne ( const Criteria & criteria,
const SingleRowCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Asynchronously find one record that matches the given criteria.

Parameters
criteriaThe criteria.
rcbis called with the result.
ecbis called when an error occurs.

◆ forUpdate()

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::forUpdate ( )
inline

Lock the result for updating.

Returns
Mapper<T>& The Mapper itself.

◆ increment() [1/2]

template<typename T>
template<typename... Arguments>
void drogon::orm::Mapper< T >::increment ( const std::vector< std::string > & colNames,
const CountCallback & rcb,
const ExceptionCallback & ecb,
const Criteria & criteria,
Arguments... args )
inlinenoexcept

Asynchronously update some records that match the given criteria.

Parameters
colNamesColumns to increment.
criteriaThe criteria.
rcbis called with the result.
ecbis called when an error occurs.
argsSpecify the amount by which the columns should be incremented.

◆ increment() [2/2]

template<typename T>
template<typename... Arguments>
size_t drogon::orm::Mapper< T >::increment ( const std::vector< std::string > & colNames,
const Criteria & criteria,
Arguments... args )
inline

Update some records that match the given criteria.

Parameters
colNamesColumns to increment.
criteriaThe criteria.
argsSpecify the amount by which the columns should be incremented.
Returns
size_t The number of updated records.

◆ incrementFuture()

template<typename T>
template<typename... Arguments>
std::future< size_t > drogon::orm::Mapper< T >::incrementFuture ( const std::vector< std::string > & colNames,
const Criteria & criteria,
Arguments... args )
inlinenoexcept

Asynchronously update some records that match the given criteria.

Parameters
colNamesColumns to increment.
criteriaThe criteria.
argsSpecify the amount by which the columns should be incremented.
Returns
std::future<size_t> The future object with which user can get the number of updated records.

◆ innerJoin()

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::innerJoin ( const std::string & table,
const std::string & onLeft,
const std::string & onRight )
inline

Add an INNER JOIN clause to the query.

Parameters
tableThe table to join.
onLeftThe left side of ON (e.g. "users.id").
onRightThe right side of ON (e.g. "posts.user_id").
Returns
Mapper<T>& The Mapper itself.

◆ insert() [1/2]

template<typename T>
void drogon::orm::Mapper< T >::insert ( const T & obj,
const SingleRowCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Asynchronously insert a row into the table.

Parameters
objThe object to be inserted.
rcbis called with the result (with the auto-increased primary key (if it exists)).
ecbis called when an error occurs.

◆ insert() [2/2]

template<typename T>
void drogon::orm::Mapper< T >::insert ( T & obj)
inline

Insert a row into the table.

Parameters
objThe object to be inserted.
Note
The auto-increased primary key (if it exists) is set to the obj argument after the method returns.

◆ insertFuture()

template<typename T>
std::future< T > drogon::orm::Mapper< T >::insertFuture ( const T & obj)
inlinenoexcept

Asynchronously insert a row into the table.

Returns
std::future<T> The future object with which user can get the result (with the auto-increased primary key (if it exists)).

◆ leftJoin()

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::leftJoin ( const std::string & table,
const std::string & onLeft,
const std::string & onRight )
inline

Add a LEFT JOIN clause to the query.

Parameters
tableThe table to join.
onLeftThe left side of ON (e.g. "users.id").
onRightThe right side of ON (e.g. "posts.user_id").
Returns
Mapper<T>& The Mapper itself.

◆ limit()

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::limit ( size_t limit)
inline

Add a limit to the query.

Parameters
limitThe limit
Returns
Mapper<T>& The Mapper itself.

◆ offset()

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::offset ( size_t offset)
inline

Add a offset to the query.

Parameters
offsetThe offset.
Returns
Mapper<T>& The Mapper itself.

◆ orderBy() [1/2]

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::orderBy ( const std::string & colName,
const SortOrder & order = SortOrder::ASC )
inline

Set the order of the results.

Parameters
colNamethe column name, the results are sorted by that column
orderAscending or descending order
Returns
Mapper<T>& The Mapper itself.

◆ orderBy() [2/2]

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::orderBy ( size_t colIndex,
const SortOrder & order = SortOrder::ASC )
inline

Set the order of the results.

Parameters
colIndexthe column index, the results are sorted by that column
orderAscending or descending order
Returns
Mapper<T>& The Mapper itself.

◆ paginate()

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::paginate ( size_t page,
size_t perPage )
inline

Set limit and offset to achieve pagination. This method will override limit() and offset(), and will be overridden by them.

Parameters
pageThe page number
perPageThe number of columns per page
Returns
Mapper<T>& The Mapper itself.

◆ rightJoin()

template<typename T>
Mapper< T > & drogon::orm::Mapper< T >::rightJoin ( const std::string & table,
const std::string & onLeft,
const std::string & onRight )
inline

Add a RIGHT JOIN clause to the query.

Parameters
tableThe table to join.
onLeftThe left side of ON (e.g. "users.id").
onRightThe right side of ON (e.g. "posts.user_id").
Returns
Mapper<T>& The Mapper itself.

◆ update() [1/2]

template<typename T>
size_t drogon::orm::Mapper< T >::update ( const T & obj)
inline

Update a record.

Parameters
objThe record.
Returns
size_t The number of updated records. It only could be 0 or 1.
Note
The table must have a primary key.

◆ update() [2/2]

template<typename T>
void drogon::orm::Mapper< T >::update ( const T & obj,
const CountCallback & rcb,
const ExceptionCallback & ecb )
inlinenoexcept

Asynchronously update a record.

Parameters
objThe record.
rcbis called with the number of updated records.
ecbis called when an error occurs.
Note
The table must have a primary key.

◆ updateBy() [1/2]

template<typename T>
template<typename... Arguments>
void drogon::orm::Mapper< T >::updateBy ( const std::vector< std::string > & colNames,
const CountCallback & rcb,
const ExceptionCallback & ecb,
const Criteria & criteria,
Arguments &&... args )
noexcept

Asynchronously select the rows that match both the primary key and the given criteria.

Parameters
colNamesColumns to update.
criteriaThe criteria.
rcbis called with the result.
ecbis called when an error occurs.
argsNew value of target columns.

◆ updateBy() [2/2]

template<typename T>
template<typename... Arguments>
size_t drogon::orm::Mapper< T >::updateBy ( const std::vector< std::string > & colNames,
const Criteria & criteria,
Arguments &&... args )

Update a record that match both the primary key and the given criteria.

Parameters
colNamesColumns to update.
criteriaThe criteria.
argsNew value of target columns.
Returns
size_t The number of updated records. It only could be 0 or 1.
Note
The table must have a primary key.

◆ updateFuture()

template<typename T>
std::future< size_t > drogon::orm::Mapper< T >::updateFuture ( const T & obj)
inlinenoexcept

Asynchronously update a record.

Parameters
objThe record.
Returns
std::future<size_t> The future object with which user can get the number of updated records.
Note
The table must have a primary key.

◆ updateFutureBy()

template<typename T>
template<typename... Arguments>
std::future< size_t > drogon::orm::Mapper< T >::updateFutureBy ( const std::vector< std::string > & colNames,
const Criteria & criteria,
Arguments &&... args )
inlinenoexcept

Asynchronously update a record that match both the primary key and the given criteria.

Parameters
colNamesColumns to update.
criteriaThe criteria.
argsNew value of target columns.
Returns
std::future<size_t> The future object with which user can get the number of updated records.
Note
The table must have a primary key.

The documentation for this class was generated from the following file: