Subversion-Projekte lars-tiefland.prado

<com:TContent ID="body">

<h1>Inheritance Mapping</h1>

<p>The SQLMap PHP DataMapper supports the implementation

of object-oriented inheritance (subclassing) in your object model. There are

several developer options for mapping entity classes and subclasses to

database results:</p>

<p>You can use the most

efficient mapping strategies from a SQL and query performance perspective when

using the inheritance mappings of the DataMapper. To implement an inheritance

mapping, the <tt>resultMap</tt> must define one or more columns in your query's

resultset that will serve to identify which <tt>resultMap</tt> should be used to map

each result record to a specific subclass. In many cases, you will use one

column value for the DataMapper to use in identifying the proper resultMap and

subclass. This column is known as a discriminator.</p>

<p>For example, we have a table defined in a database that contains <tt>Document</tt>

records. There are five table columns used to store Document IDs, Titles,

Types, PageNumbers, and Cities. Perhaps this table belongs to a legacy

database, and we need to create an application using this table with a domain

model that defines a class hierarchy of different types of Documents. Or

perhaps we are creating a new application and database and just want to

persist the data found in a set of related classes into one table. In either

case, the DataMapper's inheritance mapping feature can help.</p>

<com:TTextHighlighter Language="sql" CssClass="source">

CREATE TABLE Documents (

    Document_ID int NOT NULL ,

    Document_Title varchar(32) NULL ,

    Document_Type varchar(32)  NULL ,

    Document_PageNumber int NULL  ,

    Document_City varchar(32)  NULL

)

</com:TTextHighlighter>

<p>To illustrate this, let's take a look at a few example classes shown below

that have a relationship through inheritance and whose properties can be

persisted into our Documents table. First, we have a base Document class that

has Id and Title properties. Next, we have a Book class that inherits from

Document and contains an additional property called PageNumber. Last, we have

a Newspaper class that also inherits from Document and contains a City

property.</p>

<com:TTextHighlighter Language="php" CssClass="source">

class Document

{

    public $ID = -1;

    public $Title = '';

}

class Book extends Document

{

    public $PageNumber = -1;

}

class Newspaper extends Document

{

    public $City = '';

}

</com:TTextHighlighter>

<p>Now that we have our classes and database table, we can start working on our

mappings. We can create one <tt>&lt;select&gt;</tt> statement that returns all columns in the

table. To help the DataMapper discriminate between the different Document

records, we're going to indicate that the <tt>Document_Type</tt> column holds values

that will distinguish one record from another for mapping the results into our

class hierarchy.</p>

<com:TTextHighlighter Language="xml" CssClass="source">

<select id="GetAllDocument" resultMap="document">

   select

     Document_Id, Document_Title, Document_Type,

     Document_PageNumber, Document_City

   from Documents

   order by Document_Type, Document_Id

</select>

<resultMap id="document" class="Document">

  <result property="Id" column="Document_ID"/>

  <result property="Title" column="Document_Title"/>

  <discriminator column="Document_Type" type="string"/>

  <subMap value="Book" resultMapping="book"/>

  <subMap value="Newspaper" resultMapping="newspaper"/>

</resultMap>

<resultMap id="book" class="Book" extends="document">

  <property="PageNumber" column="Document_PageNumber"/>

</resultMap>

<resultMap id="newspaper" class="Newspaper"  extends="document">

  <property="City" column="Document_City"/>

</resultMap>

</com:TTextHighlighter>

<p>The DataMapper compares the data found in the discriminator column to the

different <tt>&lt;submap&gt;</tt> values using the column value's string equivalence. Based

on this string value, SQLMap DataMapper will use the resultMap named "<tt>Book</tt>" or

"<tt>Newspaper</tt>" as defined in the <tt>&lt;submap&gt;</tt> elements or it will use the

"parent" resultMap "<tt>Document</tt>" if neither of the submap values satisfy the comparison.

With these resultMaps, we can implement an object-oriented inheritance mapping

to our database table.</p>

<p>If you want to use custom logic, you can use the typeHandler attribute of the

<tt>&lt;discriminator&gt;</tt> element to specify a custom type handler for the discriminator

column.</p>

<com:TTextHighlighter Language="xml" CssClass="source">

  <resultMap id="document-custom-formula" class="Document">

    <result property="Id" column="Document_ID"/>

    <result property="Title" column="Document_Title"/>

    <discriminator column="Document_Type" typeHandler="CustomInheritance"/>

    <subMap value="Book" resultMapping="book"/>

    <subMap value="Newspaper" resultMapping="newspaper"/>

  </resultMap>

</resultMaps>

</com:TTextHighlighter>

<p>The value of the <tt>typeHandler</tt> attribute specifies which of our classes

implements the <tt>ITypeHandlerCallback</tt> interface. This interface furnishes a

<tt>getResult</tt> method for coding custom logic to read the column result value and

return a value for the DataMapper to use in its comparison to the resultMap's

defined <tt>&lt;submap&gt;</tt> values.</p>

<com:TTextHighlighter Language="php" CssClass="source">

class CustomInheritance implements ITypeHandlerCallback

{

    public function getResult($type)

    {

        if ($type=="Monograph" || $type=="Book")

            return "Book";

        else if ($type=="Tabloid" || $type=="Broadsheet" || $type=="Newspaper")

            return "Newspaper";

        else

            return "Document";

    }

    public function getParameter($object)

    {

        throw new Exception('unimplemented');

    }

    public function createNewInstance()

    {

        throw new Exception('unimplemented');

    }

}

</com:TTextHighlighter>

</com:TContent>