Subversion-Projekte lars-tiefland.prado

<com:TContent ID="body">

<h1>Working With Data Maps</h1>

<p>If you want to know how to configure and install SQLMap, 
see the <a href="?page=Manual.Installing">Installation</a> and 
<a href="?page=Manual.Configuring">Configuration</a>. 
But if you want to know how SQLMap really
works, continue from here.</p>

<p>The Data Map definition file is where the interesting stuff happens. Here, you
define how your application interacts with your database. As mentioned, the
Data Map definition is an XML descriptor file. By using a service routine
provided by SQLMap, the XML descriptors are rendered into a client object (or
Mapper). To access your Data Maps, your application calls the client object
and passes in the name of the statement you need.</p>

<p>The real work of using SQLMap is not so much in the application code, but in
the XML descriptors that SQLMap renders. Instead of monkeying with application
source code, you monkey with XML descriptors instead. The benefit is that the
XML descriptors are much better suited to the task of mapping your object
properties to database entities. At least, that's our own experience with our
own applications. Of course, your mileage may vary.</p>

<h1>What's in a Data Map definition file, anyway?</h1>

<p>If you read the <a href="?page=Tutorial.TestFirst">Tutorial</a>, you've already 
seen some simple Data Map examples like the one below.</p>

<com:TTextHighlighter Language="xml" CssClass="source">
<?xml version="1.0" encoding="UTF-8" ?>
  <sqlMap namespace="LineItem">
    <insert id="InsertLineItem" parameterClass="LineItem">
      INSERT INTO [LinesItem]
        (Order_Id, LineItem_LineNum, Item_Id, LineItem_Quantity, LineItem_UnitPrice)
      VALUES
       (#Order.Id#, #LineNumber#, #Item.Id#, #Quantity#, #Item.ListPrice#)
    </insert>
</sqlMap>
</com:TTextHighlighter>

<p>This map takes some properties from a <tt>LineItem</tt> instance and merges the
values into the SQL statement. The value-add is that our SQL in separated from
our program code, and we can pass our <tt>LineItem</tt> instance directly to a
library method:</p>

<com:TTextHighlighter Language="php" CssClass="source">
TMapper::instance()->insert("InsertLineItem",$lineItem);
</com:TTextHighlighter>
<p>No fuss, no muss.</p>

<div class="info"><b class="tip">Info:</b>
<b>A Quick Glance at Inline Parameters</b>
<p>
Say we have a mapped statement element that looks like this:</p>
<com:TTextHighlighter Language="xml" CssClass="source">
<statement id="InsertProduct">
  insert into Products (Product_Id, Product_Description)
  values (#Id#, #Description#);
</statement>
</com:TTextHighlighter>

<p>The inline parameters here are <tt>#Id#</tt> and <tt>#Description#</tt>. Let's
also say that we have an object with the properties <tt>Id</tt> and
<tt>Description</tt>. If we set the object properties to 5 and "dog",
respectively, and passed the object to the mapped statement, we'd end up with
a runtime query that looked like this:
<com:TTextHighlighter Language="sql" CssClass="source">
insert into Products (Product_Id, Product_Description) values (5, 'dog');
</com:TTextHighlighter>
See <a href="?page=Manual.InlineParameterMaps">inline parameters</a> for further details.
</div>

<p>But, what if you wanted some ice cream with that pie? And maybe a cherry on
top? What if we wanted to cache the result of the select? Or, what if we
didn't want to use SQL aliasing or named parameters. (Say, because we were
using pre-existing SQL that we didn't want to touch.)
The following example shows a Data Map that specifies a cache, and uses a
<tt>&lt;parameterMap&gt;</tt> and a <tt>&lt;resultMap&gt;</tt> to keep our SQL pristine.
</p>

<com:TTextHighlighter Language="xml" CssClass="source">
<?xml version="1.0" encoding="UTF-8" ?>
  <sqlMap namespace="Product">

    <cacheModel id="productCache" type="LRU">
      <flushInterval hours="24"/>
      <property name="CacheSize" value="1000" />
    </cacheModel>

    <resultMap id="productResult" class="Product">
      <result property="Id" column="Product_Id"/>
      <result property="Description" column="Product_Description"/>
    </resultMap>

    <select id="GetProduct" parameterMap="productParam" cacheModel="productCache">
      select * from Products where Product_Id = ?
    </select>

    <parameterMap id="productParam" class="Product">
      <parameter property="Id"/>
    </parameterMap>

</sqlMap>
</com:TTextHighlighter>

<p>In the above example, <tt>&lt;parameterMap&gt;</tt> maps the SQL "?" to the
product <tt>Id</tt> property. The <tt>&lt;resultMap&gt;</tt> maps the columns to our object
properties. The <tt>&lt;cacheModel&gt;</tt> keeps the result of the last one thousand of
these queries in active memory for up to 24 hours.</p>

<p>The above example is longer and more complex than
the previous example, but considering what you get in return, it seems
like a fair trade. (A bargain even.)</p>

<p>Many agile developers would start with something like
the first example and add features like caching later. If you changed
the Data Map from the first example to the second example, you
would not have to touch your application source code at all. You can start
simple and add complexity only when it is needed.</p>

<p>A single Data Map definition file can contain as many Cache Models, Result Maps, 
Parameter Maps, and Mapped Statements (including stored
procedures), as you like. Everything is loaded into the same configuration, so
you can define elements in one Data Map and then use them in another. Use
discretion and organize the statements and maps appropriately for your
application by finding some logical way to group them.</p>

</com:TContent>