Result Map Attributes

The <resultMap> element accepts three attributes: id (required), class (optional), and extends (optional).

id attribute

The required id attribute provides a unique identifier for the <resultMap> within this Data Map.

class attribute

The optional class attribute specifies an object class to use with this <resultMap>. The full classname must be specified. Any class can be used.

Note: As with parameter classes, the result class must be a PHP class object or array instance.

extends attribute

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.

property attribute

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.

column attribute

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.

columnIndex attribute

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.

dbType attribute

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 too.

type attribute

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.

resultMapping attribute

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.-->

nullValue attribute

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 value.

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.

select attribute

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 select.

lazyLoad attribute

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.

typeHandler attribute

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.