- Home
- About
- Testimonials
- Demos
- Download
- Documentation
- Blogs
- Forum
- Support

Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml
Classes:
IMappedStatement
TCachingStatement
TDeleteMappedStatement
TInsertMappedStatement
TMappedStatement
TPostSelectBinding
TPreparedCommand
TPreparedStatement
TPreparedStatementFactory
TResultSetListItemParameter
TResultSetMapItemParameter
TSelectMappedStatement
TSimpleDynamicSql
TSqlMapObjectCollectionTree
TSqlMapSelect
TStaticSql
TUpdateMappedStatement

Keyword

# Class TMappedStatement

    TComponent
       |
       --TMappedStatement

#### Direct Known Sub-classes:

TSelectMappedStatement , TInsertMappedStatement , TUpdateMappedStatement

TMappedStatement class executes SQL mapped statements. Mapped Statements can hold any SQL statement and use Parameter Maps and Result Maps for input and output.

This class is usualy instantiated during SQLMap configuration by TSqlDomBuilder.

Since: 3.0
Author: Wei Zhuo <weizhuo[at]gmail[dot]com>

Constructor Summary
public | __construct Array Creates a new mapped statement.

Method Summary
protected object result | addResultMapGroupBy ( TResultMap $resultMap, array $row, object the $parent, mixed &$resultObject) ResultMap with GroupBy property. Save object collection graph in a tree and collect the result later.
protected object the | applyResultMap ( array $row, object the &$resultObject) Apply result mapping.
protected void | enquequePostSelect ( string $select, TResultMap $resultMap, TResultProperty $property, array $row, object the $resultObject) Add nested result property to post select queue.
string | executeInsert ( IDbConnection $connection, mixed $parameter) Execute an insert statement. Fill the parameter object with the ouput parameters if any, also could return the insert generated key.
protected void | executePostSelect ( IDbConnection $connection) Process 'select' result properties
array | executeQueryForList ( IDbConnection $connection, mixed $parameter, object result $result, integer $skip, integer $max, callback $delegate) Executes the SQL and retuns a List of result objects.
array | executeQueryForMap ( IDbConnection $connection, mixed $parameter, string $keyProperty, string $valueProperty, callback $skip, mixed $max, mixed $delegate) Executes the SQL and retuns all rows selected in a map that is keyed on the property named in the keyProperty parameter. The value at each key will be the value of the property specified in the valueProperty parameter.
${return} | executeQueryForObject ( IDbConnection $connection, mixed $parameter, mixed $result) Executes an SQL statement that returns a single row as an object of the type of the <tt>$result</tt> passed in as a parameter.
protected string | executeSelectKey ( IDbConnection $connection, mixed $parameter, TSqlMapSelectKey $selectKey) Execute the select key statement, used to obtain last insert ID.
protected mixed | executeSQLQueryLimit ( IDbConnection $connection, array $command, mixed $max, mixed $skip) Execute SQL Query with limits.
integer | executeUpdate ( IDbConnection $connection, mixed $parameter) Execute an update statement. Also used for delete statement.
protected array | fillArrayResultMap ( TResultMap $resultMap, array $row, object the $resultObject) Retrieve the result map as an array.
protected mixed | fillDefaultResultMap ( TResultMap $resultMap, array $row, object the $resultObject) Fill the result map using default settings. If <tt>$resultMap</tt> is null the result object returned will be guessed from <tt>$resultObject</tt>.
protected boolean | fillPropertyWithResultMap ( TResultMap $resultMap, array $row, object the &$resultObject) Fills the property with result mapping results.
protected object result | fillResultArrayList ( array $row, object result $resultObject) Apply the result to a TList or an array.
protected object result | fillResultClass ( string $resultClass, array $row, object the $resultObject) Fill the result using ResultClass, will creates new result object if required.
protected object result | fillResultMap ( string $resultMapName, array $row, object result $parentGroup, mixed &$resultObject) Fills the result object according to result mappings.
protected object result | fillResultObjectProperty ( array $row, object result $resultObject) Apply the result to an object.
TPreparedCommand | getCommand ()
string | getID ()
TSqlMapper | getManager ()
protected string | getPostGeneratedSelectKey ( IDbConnection $connection, mixed $parameter) Gets the inserted row ID after executing an insert statement.
protected array | getPostSelectKeys ( TResultMap $resultMap, TResultProperty $property, array $row) Finds in the post select property the SQL statement primary selection keys.
protected string | getPreGeneratedSelectKey ( IDbConnection $connection, mixed $parameter) Gets the insert generated ID before executing an insert statement.
protected string | getResultMapGroupKey ( TResultMap $resultMap, array $row) Gets the result 'group by' groupping key for each row.
protected mixed | getScalarResult ( array $result, string $type) Converts the first array value to scalar value of given type.
void | getSqlString ()
TSqlMapStatement | getStatement ()
protected void | initialGroupByResults () Empty the group by results cache.
void | onExecuteQuery ( array $sql) Raise the execute query event.
protected void | raiseRowDelegate ( object event $handler, mixed $param) Raises delegate handler.
array | runQueryForList ( IDbConnection $connection, mixed $parameter, array $sql, object result $result, integer $delegate, integer 5, callback 6) Executes the SQL and retuns a List of result objects.
array | runQueryForMap ( IDbConnection $connection, mixed $parameter, array $command, string $keyProperty, string $valueProperty, callback $delegate) Executes the SQL and retuns all rows selected in a map that is keyed on the property named in the keyProperty parameter. The value at each key will be the value of the property specified in the valueProperty parameter.
object the | runQueryForObject ( IDbConnection $connection, array $command, object The &$result) Executes an SQL statement that returns a single row as an object of the type of the <tt>$result</tt> passed in as a parameter.
protected void | setObjectProperty ( TResultMap $resultMap, TResultProperty $property, array $row, object the &$resultObject) Set a property of the result object with appropriate value.

Methods Inherited From TComponent

TComponent::addParsedObject(), TComponent::attachEventHandler(), TComponent::canGetProperty(), TComponent::canSetProperty(), TComponent::createdOnTemplate(), TComponent::detachEventHandler(), TComponent::evaluateExpression(), TComponent::evaluateStatements(), TComponent::getEventHandlers(), TComponent::getSubProperty(), TComponent::hasEvent(), TComponent::hasEventHandler(), TComponent::hasProperty(), TComponent::raiseEvent(), TComponent::setSubProperty(), TComponent::__get(), TComponent::__set()

Constant Summary
int | QUERY_FOR_ARRAY |
int | QUERY_FOR_LIST |
int | QUERY_FOR_OBJECT |

Constructor Details

## __construct

public __construct | Array

Creates a new mapped statement.

Method Details

## addResultMapGroupBy

protected object result addResultMapGroupBy | (TResultMap $resultMap , array $row , object the $parent , mixed &$resultObject )

ResultMap with GroupBy property. Save object collection graph in a tree and collect the result later.

Input
TResultMap | $resultMap | result mapping details.
array | $row | a result set row retrieved from the database
object the | $parent | result object
mixed | &$resultObject |
Output
object result | object.
Exception

## applyResultMap

protected object the applyResultMap | (array $row , object the &$resultObject )

Apply result mapping.

Input
array | $row | a result set row retrieved from the database
object the | &$resultObject | result object, will create if necessary.
Output
object the | result filled with data, null if not filled.
Exception

## enquequePostSelect

protected void enquequePostSelect | (string $select , TResultMap $resultMap , TResultProperty $property , array $row , object the $resultObject )

Add nested result property to post select queue.

Input
string | $select | post select statement ID
TResultMap | $resultMap | current result mapping details.
TResultProperty | $property | current result property.
array | $row | a result set row retrieved from the database
object the | $resultObject | result object
Output
Exception

## executeInsert

public string executeInsert | (IDbConnection $connection , mixed $parameter )

Execute an insert statement. Fill the parameter object with the ouput parameters if any, also could return the insert generated key.

Input
IDbConnection | $connection | database connection
mixed | $parameter | The parameter object used to fill the statement.
Output
string | the insert generated key.
Exception

## executePostSelect

protected void executePostSelect | (IDbConnection $connection )

Process 'select' result properties

Input
IDbConnection | $connection | database connection
Output
Exception

## executeQueryForList

public array executeQueryForList | (IDbConnection $connection , mixed $parameter , object result $result , integer $skip , integer $max , callback $delegate )

Executes the SQL and retuns a List of result objects.

Input
IDbConnection | $connection | database connection
mixed | $parameter | The object used to set the parameters in the SQL.
object result | $result | collection object.
integer | $skip | The number of rows to skip over.
integer | $max | The maximum number of rows to return.
callback | $delegate | row delegate handler
Output
array | a list of result objects
Exception

## executeQueryForMap

public array executeQueryForMap | (IDbConnection $connection , mixed $parameter , string $keyProperty , string $valueProperty , callback $skip , mixed $max , mixed $delegate )

Executes the SQL and retuns all rows selected in a map that is keyed on the property named in the keyProperty parameter. The value at each key will be the value of the property specified in the valueProperty parameter.

If valueProperty is null, the entire result object will be entered.

Input
IDbConnection | $connection | database connection
mixed | $parameter | The object used to set the parameters in the SQL.
string | $keyProperty | The property of the result object to be used as the key.
string | $valueProperty | The property of the result object to be used as the value (or null).
callback | $skip | row delegate handler
mixed | $max |
mixed | $delegate |
Output
array | An array of object containing the rows keyed by keyProperty.
Exception

## executeQueryForObject

public ${return} executeQueryForObject | (IDbConnection $connection , mixed $parameter , mixed $result )

Executes an SQL statement that returns a single row as an object of the type of the <tt>$result</tt> passed in as a parameter.

Input
IDbConnection | $connection | database connection
mixed | $parameter | The parameter data (object, arrary, primitive) used to set the parameters in the SQL
mixed | $result | The result object.
Output
Exception

## executeSelectKey

protected string executeSelectKey | (IDbConnection $connection , mixed $parameter , TSqlMapSelectKey $selectKey )

Execute the select key statement, used to obtain last insert ID.

Input
IDbConnection | $connection | database connection
mixed | $parameter | insert statement parameter
TSqlMapSelectKey | $selectKey | select key statement
Output
string | last insert ID.
Exception

## executeSQLQueryLimit

protected mixed executeSQLQueryLimit | (IDbConnection $connection , array $command , mixed $max , mixed $skip )

Execute SQL Query with limits.

Input
IDbConnection | $connection | database connection
array | $command | SQL statement and parameters.
mixed | $max |
mixed | $skip |
Output
mixed | record set if applicable.
Exception
throws | TSqlMapExecutionException if execution error or false record set.
throws | TSqlMapQueryExecutionException if any execution error

## executeUpdate

public integer executeUpdate | (IDbConnection $connection , mixed $parameter )

Execute an update statement. Also used for delete statement.

Return the number of rows effected.

Input
IDbConnection | $connection | database connection
mixed | $parameter | The object used to set the parameters in the SQL.
Output
integer | The number of rows effected.
Exception

## fillArrayResultMap

protected array fillArrayResultMap | (TResultMap $resultMap , array $row , object the $resultObject )

Retrieve the result map as an array.

Input
TResultMap | $resultMap | result mapping details.
array | $row | a result set row retrieved from the database
object the | $resultObject | result object
Output
array | array list of result objects.
Exception

## fillDefaultResultMap

protected mixed fillDefaultResultMap | (TResultMap $resultMap , array $row , object the $resultObject )

Fill the result map using default settings. If <tt>$resultMap</tt> is null the result object returned will be guessed from <tt>$resultObject</tt>.

Input
TResultMap | $resultMap | result mapping details.
array | $row | a result set row retrieved from the database
object the | $resultObject | result object
Output
mixed | the result object filled with data.
Exception

## fillPropertyWithResultMap

protected boolean fillPropertyWithResultMap | (TResultMap $resultMap , array $row , object the &$resultObject )

Fills the property with result mapping results.

Input
TResultMap | $resultMap | nested result mapping details.
array | $row | a result set row retrieved from the database
object the | &$resultObject | result object
Output
boolean | true if the data was found, false otherwise.
Exception

## fillResultArrayList

protected object result fillResultArrayList | (array $row , object result $resultObject )

Apply the result to a TList or an array.

Input
array | $row | a result set row retrieved from the database
object result | $resultObject | object, array or list
Output
object result | filled with data.
Exception

## fillResultClass

protected object result fillResultClass | (string $resultClass , array $row , object the $resultObject )

Fill the result using ResultClass, will creates new result object if required.

Input
string | $resultClass | result object class name
array | $row | a result set row retrieved from the database
object the | $resultObject | result object, will create if necessary.
Output
object result | object filled with data
Exception

## fillResultMap

protected object result fillResultMap | (string $resultMapName , array $row , object result $parentGroup , mixed &$resultObject )

Fills the result object according to result mappings.

Input
string | $resultMapName | result map name.
array | $row | a result set row retrieved from the database
object result | $parentGroup | object to fill, will create new instances if required.
mixed | &$resultObject |
Output
object result | object filled with data.
Exception

## fillResultObjectProperty

protected object result fillResultObjectProperty | (array $row , object result $resultObject )

Apply the result to an object.

Input
array | $row | a result set row retrieved from the database
object result | $resultObject | object, array or list
Output
object result | filled with data.
Exception

## getCommand

public TPreparedCommand getCommand | ()

Output
TPreparedCommand | command to prepare SQL statements.
Exception

## getID

public string getID | ()

Output
string | Name used to identify the TMappedStatement amongst the others. This the name of the SQL statement by default.
Exception

## getManager

public TSqlMapper getManager | ()

Output
TSqlMapper | The SqlMap used by this MappedStatement
Exception

## getPostGeneratedSelectKey

protected string getPostGeneratedSelectKey | (IDbConnection $connection , mixed $parameter )

Gets the inserted row ID after executing an insert statement.

Input
IDbConnection | $connection | database connection
mixed | $parameter | insert statement parameter.
Output
string | last insert ID, null otherwise.
Exception

## getPostSelectKeys

protected array getPostSelectKeys | (TResultMap $resultMap , TResultProperty $property , array $row )

Finds in the post select property the SQL statement primary selection keys.

Input
TResultMap | $resultMap | result mapping details
TResultProperty | $property | result property
array | $row | current row data.
Output
array | list of primary key values.
Exception

## getPreGeneratedSelectKey

protected string getPreGeneratedSelectKey | (IDbConnection $connection , mixed $parameter )

Gets the insert generated ID before executing an insert statement.

Input
IDbConnection | $connection | database connection
mixed | $parameter | insert statement parameter.
Output
string | new insert ID if pre-select key statement was executed, null otherwise.
Exception

## getResultMapGroupKey

protected string getResultMapGroupKey | (TResultMap $resultMap , array $row )

Gets the result 'group by' groupping key for each row.

Input
TResultMap | $resultMap | result mapping details.
array | $row | a result set row retrieved from the database
Output
string | groupping key.
Exception

## getScalarResult

protected mixed getScalarResult | (array $result , string $type )

Converts the first array value to scalar value of given type.

Input
array | $result | list of results
string | $type | scalar type.
Output
mixed | scalar value.
Exception

## getSqlString

public void getSqlString | ()

Output
Exception

## getStatement

public TSqlMapStatement getStatement | ()

Output
TSqlMapStatement | The SQL statment used by this MappedStatement
Exception

## initialGroupByResults

protected void initialGroupByResults | ()

Empty the group by results cache.

Output
Exception

## onExecuteQuery

public void onExecuteQuery | (array $sql )

Raise the execute query event.

Input
array | $sql | prepared SQL statement and subsititution parameters
Output
Exception

## raiseRowDelegate

protected void raiseRowDelegate | (object event $handler , mixed $param )

Raises delegate handler.

This method is invoked for each new list item. It is the responsibility of the handler to add the item to the list.

Input
object event | $handler | parameter
mixed | $param |
Output
Exception

## runQueryForList

public array runQueryForList | (IDbConnection $connection , mixed $parameter , array $sql , object result $result , integer $delegate , integer 5 , callback 6 )

Executes the SQL and retuns a List of result objects.

This method should only be called by internal developers, consider using <tt>executeQueryForList()</tt> first.

Input
IDbConnection | $connection | database connection
mixed | $parameter | The object used to set the parameters in the SQL.
array | $sql | SQL string and subsititution parameters.
object result | $result | collection object.
integer | $delegate | The number of rows to skip over.
integer | 5 | The maximum number of rows to return.
callback | 6 | row delegate handler
Output
array | a list of result objects
Exception

## runQueryForMap

public array runQueryForMap | (IDbConnection $connection , mixed $parameter , array $command , string $keyProperty , string $valueProperty , callback $delegate )

Executes the SQL and retuns all rows selected in a map that is keyed on the property named in the keyProperty parameter. The value at each key will be the value of the property specified in the valueProperty parameter.

If valueProperty is null, the entire result object will be entered.

This method should only be called by internal developers, consider using <tt>executeQueryForMap()</tt> first.

Input
IDbConnection | $connection | database connection
mixed | $parameter | The object used to set the parameters in the SQL.
array | $command | SQL string and subsititution parameters.
string | $keyProperty | The property of the result object to be used as the key.
string | $valueProperty | The property of the result object to be used as the value (or null).
callback | $delegate | row delegate, a callback function
Output
array | An array of object containing the rows keyed by keyProperty.
Exception

## runQueryForObject

public object the runQueryForObject | (IDbConnection $connection , array $command , object The &$result )

Executes an SQL statement that returns a single row as an object of the type of the <tt>$result</tt> passed in as a parameter.

This method should only be called by internal developers, consider using <tt>executeQueryForObject()</tt> first.

Input
IDbConnection | $connection | database connection
array | $command | SQL string and subsititution parameters.
object The | &$result | result object.
Output
object the | object.
Exception

## setObjectProperty

protected void setObjectProperty | (TResultMap $resultMap , TResultProperty $property , array $row , object the &$resultObject )

Set a property of the result object with appropriate value.

Input
TResultMap | $resultMap | result mapping details.
TResultProperty | $property | the result property to fill.
array | $row | a result set row retrieved from the database
object the | &$resultObject | result object
Output
Exception

Constant Details

### QUERY_FOR_ARRAY

#### Type:

int

#### Value:

1
Var: select is to query for list.

### QUERY_FOR_LIST

#### Type:

int

#### Value:

0
Var: select is to query for list.

### QUERY_FOR_OBJECT

#### Type:

int

#### Value:

2
Var: select is to query for object.