Result Map Attributes
The <resultMap> element accepts three attributes: id (required),
class (optional), and extends (optional).
The required id attribute provides a unique identifier for the
<resultMap> within this Data Map.
The optional class attribute specifies an object class to use with this
<resultMap>. The full classname must be specified. Any class can be used.
As with parameter classes, the result class must be a PHP class object or
The optional extends attribute allows the result map to inherit all of
the properties of the "parent" resultMap that it extends.
<result> Element attributes
The <resultMap> element holds one or more <result> child elements
that map SQL result sets to object properties.
The property attribute is the name of a property of the result object
that will be returned by the Mapped Statement. The name can be used more than
once depending on the number of times it is needed to populate the results.
The column attribute value is the name of the column in the result set
from which the value will be used to populate the property.
The columnIndex attribute value is the index of the column in the
ResultSet from which the value will be used to populate the object property.
This is not likely needed in 99\% of applications and sacrifices
maintainability and readability for speed. Some providers may not realize any
performance benefit, while others will speed up dramatically.
The dbType attribute is used to explicitly specify the database column
type of the ResultSet column that will be used to populate the object
property. Although Result Maps do not have the same difficulties with null
values, specifying the type can be useful for certain mapping types such as
Date properties. Because an application language has one Date value type and
SQL databases may have many (usually at least 3), specifying the date may
become necessary in some cases to ensure that dates (or other types) are set
correctly. Similarly, String types may be populated by a VarChar,
Char or CLOB, so specifying the type might be needed in those cases
The type attribute is used to explicitly specify the property type of the
parameter to be set. If the attribute type is not set and the framework
cannot otherwise determine the type, the type is assumed to be StdObject.
The resultMapping attribute can be set to the name of another
resultMap used to fill the property. If the resultMap is in an other
mapping file, you must specified the fully qualified name as :
<!--resultMapping with a fully qualified name.-->
The nullValue attribute can be set to any valid value (based on property
type). The nullValue attribute is used to specify an outgoing null value
replacement. What this means is that when the value is detected in the object
property, a NULL will be written to the database (the opposite behavior of an
inbound null value replacement). This allows you to use a "magic" null
number in your application for types that do not support null values (such as
int, double, float). When these types of properties contain a matching null
value (say, -9999), a NULL will be written to the database instead of the
If your database has a NULLABLE column, but you want your application to
represent NULL with a constant value, you can specify it in the Result Map as
shown in the following example.
<resultMap id="get-product-result" class="product">
<result property="id" column="PRD_ID"/>
<result property="description" column="PRD_DESCRIPTION"/>
<result property="subCode" column="PRD_SUB_CODE" nullValue="-9999"/>
In the above example, PRD_SUB_CODE is read as NULL, then the
subCode property will be set to the value of -9999. This allows you to
use a primitive type to represent a NULLABLE column in the database. Remember
that if you want this to work for queries as well as updates/inserts, you must
also specify the nullValue in the Parameter Map.
The select attribute is used to describe a relationship between objects
and to automatically load complex (i.e. user defined) property types. The
value of the statement property must be the name of another mapped statement.
The value of the database column (the column attribute) that is defined in the
same property element as this statement attribute will be passed to the
related mapped statement as the parameter. More information about supported
primitive types and complex property mappings/relationships is discussed later
in this document. The lazyLoad attribute can be specified with the
Use the lazyLoad attribute with the select attribute to indicate
whether or not the select statement's results should be lazy loaded. This can
provide a performance boost by delaying the loading of the select statement's
results until they are needed/accessed.
The typeHandler attribute allows the use of a
Custom Type Handler.
This allows you to extend
the DataMapper's capabilities in handling types that are specific to your
database provider, are not handled by your database provider, or just happen
to be a part of your application design. You can create custom type handlers
to deal with storing and retrieving booleans from your database for example.