| 1 |
lars |
1 |
<com:TContent ID="body">
|
|
|
2 |
<h1>Result Maps</h1>
|
|
|
3 |
<a href="?page=Manual.ParameterMaps">Parameter Maps</a> and
|
|
|
4 |
<a href="?page=Manual.InlineParameterMaps">Inline parameters</a>
|
|
|
5 |
map object properties to parameters in a database query. Result Maps
|
|
|
6 |
finish the job by mapping the result of a database query (a set of columns) to
|
|
|
7 |
object properties. Next to Mapped Statements, the Result Map is probably one
|
|
|
8 |
of the most commonly used and most important features to understand.</p>
|
|
|
9 |
|
|
|
10 |
<p>A Result Map lets you control how data is extracted from the result of a
|
|
|
11 |
query, and how the columns are mapped to object properties. A Result Map can
|
|
|
12 |
describe the column type, a null value replacement, and complex property
|
|
|
13 |
mappings including Collections. The following example shows the structure
|
|
|
14 |
of a <tt><resultMap></tt> element.</p>
|
|
|
15 |
|
|
|
16 |
<com:TTextHighlighter Language="xml" CssClass="source">
|
|
|
17 |
<resultMap id="resultMapIdentifier"
|
|
|
18 |
[class="class.name"]
|
|
|
19 |
[extends="[sqlMapNamespace.]resultMapId"]>
|
|
|
20 |
|
|
|
21 |
<result property="propertyName"
|
|
|
22 |
column="columnName"
|
|
|
23 |
[columnIndex="columnIndex"]
|
|
|
24 |
[dbType="databaseType"]
|
|
|
25 |
[type="propertyCLRType"]
|
|
|
26 |
[resultMapping="resultMapName"]
|
|
|
27 |
[nullValue="nullValueReplacement"]
|
|
|
28 |
[select="someOtherStatementName"]
|
|
|
29 |
[lazyLoad="true|false"]
|
|
|
30 |
[typeHandler="class.name"]
|
|
|
31 |
/>
|
|
|
32 |
<result ... .../>
|
|
|
33 |
<result ... .../>
|
|
|
34 |
</resultMap>
|
|
|
35 |
</com:TTextHighlighter>
|
|
|
36 |
|
|
|
37 |
<p>In the above example, the <tt>[brackets]</tt> indicate optional attributes.
|
|
|
38 |
The <tt>id</tt> attribute is required and provides a name for the statement to
|
|
|
39 |
reference. The <tt>class</tt> attribute is also required, and specifies the full
|
|
|
40 |
name of a PHP class. This is the class that will be instantiated and populated
|
|
|
41 |
based on the result mappings it contains.</p>
|
|
|
42 |
|
|
|
43 |
<p>The <tt>resultMap</tt> can contain any number of property mappings that map object
|
|
|
44 |
properties to the columns of a result element. The property mappings are
|
|
|
45 |
applied, and the columns are read, in the order that they are defined.
|
|
|
46 |
Maintaining the element order ensures consistent results between different
|
|
|
47 |
drivers and providers.</p>
|
|
|
48 |
|
|
|
49 |
<div class="note"><b class="tip">Note:</b>
|
|
|
50 |
As with parameter classes, the result class must be a PHP class object or
|
|
|
51 |
array instance.
|
|
|
52 |
</div>
|
|
|
53 |
|
|
|
54 |
<h1>Extending <tt>resultMaps</tt></h1>
|
|
|
55 |
<p>The optional <tt>extends</tt> attribute can be set to the name of another
|
|
|
56 |
<tt>resultMap</tt> upon which to base this <tt>resultMap</tt>. All properties of the
|
|
|
57 |
"parent" <tt>resultMap</tt> will be included as part of this <tt>resultMap</tt>, and
|
|
|
58 |
values from the "parent" <tt>resultMap</tt> are set before any values specified
|
|
|
59 |
by this <tt>resultMap</tt>. The effect is similar to extending a class.</p>
|
|
|
60 |
|
|
|
61 |
<div class="tip"><b class="tip">Tip:</b>
|
|
|
62 |
The "parent" <tt>resultMap</tt> must be defined in the file before the extending
|
|
|
63 |
<tt>resultMap</tt>. The classes for the parent and child <tt>resultMaps</tt> need not be
|
|
|
64 |
the same, and do not need to be related in any way.
|
|
|
65 |
</div>
|
|
|
66 |
|
|
|
67 |
</com:TContent>
|