repo_zf1/documentation/manual/ja/module_specs/Zend_Db_Table-Relationships.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24831 -->
<sect1 id="zend.db.table.relationships">
    <title>導入</title>
    <!-- Skip-EN-Revisions: 21587 -->
    <para>注意：このドキュメントでは、英語版のリビジョン 21587 の更新内容をスキップしています。</para>
    <sect2 id="zend.db.table.relationships.introduction">

        <title>導入</title>

        <para>
            リレーショナルデータベースでは、テーブル間の関連
            (リレーション) が設定されています。
            あるテーブル内のエンティティが、
            データベーススキーマで定義されている参照整合性制約を使用して
            他のエンティティとリンクしているのです。
        </para>

        <para>
            <classname>Zend_Db_Table_Row</classname> クラスは、他のテーブルの
            関連する行を問い合わせるためのメソッドを持っています。
        </para>

    </sect2>

    <sect2 id="zend.db.table.relationships.defining">

        <title>リレーションの定義</title>

        <para>
            抽象クラス <classname>Zend_Db_Table_Abstract</classname> を継承して、各テーブル用のクラスを作成します。
            詳細は <xref linkend="zend.db.table.defining" /> を参照ください。
            また、以下のコードで使用しているデータベースの構成については
            <xref linkend="zend.db.adapter.example-database" /> を参照ください。
        </para>

        <para>
            以下に、これらのテーブルに対応する <acronym>PHP</acronym> クラス定義を示します。
        </para>

        <programlisting language="php"><![CDATA[
class Accounts extends Zend_Db_Table_Abstract
{
    protected $_name            = 'accounts';
    protected $_dependentTables = array('Bugs');
}

class Products extends Zend_Db_Table_Abstract
{
    protected $_name            = 'products';
    protected $_dependentTables = array('BugsProducts');
}

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name            = 'bugs';

    protected $_dependentTables = array('BugsProducts');

    protected $_referenceMap    = array(
        'Reporter' => array(
            'columns'           => 'reported_by',
            'refTableClass'     => 'Accounts',
            'refColumns'        => 'account_name'
        ),
        'Engineer' => array(
            'columns'           => 'assigned_to',
            'refTableClass'     => 'Accounts',
            'refColumns'        => 'account_name'
        ),
        'Verifier' => array(
            'columns'           => array('verified_by'),
            'refTableClass'     => 'Accounts',
            'refColumns'        => array('account_name')
        )
    );
}

class BugsProducts extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs_products';

    protected $_referenceMap    = array(
        'Bug' => array(
            'columns'           => array('bug_id'),
            'refTableClass'     => 'Bugs',
            'refColumns'        => array('bug_id')
        ),
        'Product' => array(
            'columns'           => array('product_id'),
            'refTableClass'     => 'Products',
            'refColumns'        => array('product_id')
        )
    );

}
]]></programlisting>

        <para>
            <classname>Zend_Db_Table</classname> で UPDATE や DELETE の連鎖操作をエミュレートする場合は、
            配列 <varname>$_dependentTables</varname> を親テーブルで宣言し、
            従属しているテーブルをそこで指定します。
            <acronym>SQL</acronym> でのテーブル名ではなく、クラス名を使用するようにしましょう。
        </para>

        <note>

            <para>
                <acronym>RDBMS</acronym> サーバが実装している参照整合性制約によって連鎖操作を行う場合は、
                <varname>$_dependentTables</varname> を宣言しません。
                詳細は <xref linkend="zend.db.table.relationships.cascading" />
                を参照ください。
            </para>

        </note>

        <para>
            各従属テーブルのクラス内で、配列 <varname>$_referenceMap</varname>
            を宣言します。これは、参照の "ルール" を定義する連想配列となります。
            参照ルールとは、リレーションの親テーブルが何になるのか、
            従属テーブルのどのカラムと親テーブルのどのカラムが対応するのかを示すものです。
        </para>

        <para>
            ルールのキーを、配列 <varname>$_referenceMap</varname>
            のインデックスとして使用します。
            このルールのキーは、各リレーションを指定する際に使用します。
            わかりやすい名前をつけるようにしましょう。
            あとでご覧いただくように、<acronym>PHP</acronym> のメソッド名の一部を使用するとよいでしょう。
        </para>

        <para>
            上のサンプル <acronym>PHP</acronym> コードでは、Bugs テーブルクラスのルールのキーは
            <code>'Reporter'</code>、
            <code>'Engineer'</code>、
            <code>'Verifier'</code> および
            <code>'Product'</code> となります。
        </para>

        <para>
            配列 <varname>$_referenceMap</varname>
            の各ルールエントリの内容もまた、連想配列です。
            このルールエントリの内容について、以下で説明します。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>columns</emphasis> =>
                    文字列あるいは文字列の配列で、従属テーブル内での外部キー列の名前を指定します。
                </para>

                <para>
                    たいていの場合はカラムはひとつだけですが、
                    複数カラムのキーとなるテーブルもあります。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>refTableClass</emphasis> =>
                    親テーブルのクラス名を指定します。
                    <acronym>SQL</acronym> テーブルの物理的な名前ではなく、クラス名を使用します。
                </para>

                <para>
                    通常は、従属テーブルから親テーブルへの参照はひとつだけになります。
                    しかし、テーブルによっては同一の親テーブルへの参照を複数持つものもあります。
                    サンプルのデータベースでは、 <code>bugs</code>
                    テーブルから <code>products</code> テーブルへの参照はひとつだけです。
                    しかし、<code>bugs</code> テーブルから
                    <code>accounts</code> テーブルへの参照は三つあります。
                    それぞれの参照を、配列 <varname>$_referenceMap</varname>
                    の個別のエントリとします。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>refColumns</emphasis> =>
                    文字列あるいは文字列の配列で、親テーブルの主キーのカラム名を指定します。
                </para>

                <para>
                    たいていの場合はカラムはひとつだけですが、
                    複数カラムのキーとなるテーブルもあります。
                    複数カラムのキーを使用する場合は、
                    <code>'columns'</code> エントリでのカラムの順番と
                    <code>'refColumns'</code> エントリでのカラムの順番が一致する必要があります。
                </para>

                <!-- TODO : to be translated -->
                <note>
                    <para>
                        It is recommended that the <property>refColumns</property> element is always declared as 
                        cascading operations will not work unless you do so.
                    </para>
                </note>
            </listitem>

            <listitem>
                <para>
                    <emphasis>onDelete</emphasis> =>
                    親テーブルの行が削除されたときに実行する動作を指定します。詳細は
                    <xref linkend="zend.db.table.relationships.cascading" />
                    を参照ください。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>onUpdate</emphasis> =>
                    親テーブルで主キーカラムの値が更新されたときに実行する動作を指定します。詳細は
                    <xref linkend="zend.db.table.relationships.cascading" />
                    を参照ください。
                </para>
            </listitem>
        </itemizedlist>

    </sect2>

    <sect2 id="zend.db.table.relationships.fetching.dependent">

        <title>従属行セットの取得</title>

        <para>
            親テーブルに対するクエリの結果を Row オブジェクトとして取得すれば、
            その行を参照している従属テーブルの行を取得できます。
            使用するメソッドは、次のようになります。
        </para>

        <programlisting language="php"><![CDATA[
$row->findDependentRowset($table, [$rule]);
]]></programlisting>

        <para>
            このメソッドは <classname>Zend_Db_Table_Rowset_Abstract</classname> オブジェクトを返します。
            その中には、従属テーブル <varname>$table</varname>
            の行のうち、<varname>$row</varname> が指す行を参照しているものが含まれます。
        </para>

        <para>
            最初の引数 <varname>$table</varname> には、
            従属テーブルのクラス名を表す文字列を指定します。
            文字列ではなく、テーブルクラスのオブジェクトで指定することもできます。
        </para>

        <example id="zend.db.table.relationships.fetching.dependent.example">

            <title>従属行セットの取得</title>

            <para>
                この例では、<code>Accounts</code> テーブルから取得した行オブジェクトについて、
                その人が報告したバグを <code>Bugs</code>
                テーブルから探す方法を示します。
            </para>

            <programlisting language="php"><![CDATA[
$accountsTable = new Accounts();
$accountsRowset = $accountsTable->find(1234);
$user1234 = $accountsRowset->current();

$bugsReportedByUser = $user1234->findDependentRowset('Bugs');
]]></programlisting>

        </example>

        <para>
            二番目の引数 <varname>$rule</varname> はオプションです。
            これは、従属テーブルクラスの配列 <varname>$_referenceMap</varname>
            でのルールのキーの名前を指定します。
            ルールを指定しなかった場合は、配列の中で
            その親テーブルを参照している最初のルールを使用します。
            最初のもの以外のルールを使用する必要がある場合は、
            キーを指定しなければなりません。
        </para>

        <para>
            上の例のコードでは、ルールのキーを指定していません。
            したがって、親テーブルにマッチする最初のルールをデフォルトで使用します。
            ここでは <code>'Reporter'</code> がそれにあたります。
        </para>

        <example id="zend.db.table.relationships.fetching.dependent.example-by">

            <title>ルールを指定することによる従属行セットの取得</title>

            <para>
                この例では、<code>Accounts</code> テーブルから取得した行オブジェクトについて、
                修正担当者がその人になっているバグを <code>Bugs</code>
                テーブルから探す方法を示します。この例における、
                このリレーションに対応する参照ルールのキーは
                <code>'Engineer'</code> です。
            </para>

            <programlisting language="php"><![CDATA[
$accountsTable = new Accounts();
$accountsRowset = $accountsTable->find(1234);
$user1234 = $accountsRowset->current();

$bugsAssignedToUser = $user1234->findDependentRowset('Bugs', 'Engineer');
]]></programlisting>

        </example>

        <para>
            条件や並び順の指定、行数の制限を追加するには、
            親の行の select オブジェクトを使用します。
        </para>

        <para>

            <example id="zend.db.table.relationships.fetching.dependent.example-by-select">

                <title>Zend_Db_Table_Select による従属行セットの取得</title>

                <para>
                    この例では <code>Accounts</code> テーブルから行オブジェクトを取得し、
                    修正担当者がその人である <code>Bugs</code> を探し、
                    最大 3 件までを名前の順に取得します。
                </para>

                <programlisting language="php"><![CDATA[
$accountsTable = new Accounts();
$accountsRowset = $accountsTable->find(1234);
$user1234 = $accountsRowset->current();
$select = $accountsTable->select()->order('name ASC')
                                  ->limit(3);

$bugsAssignedToUser = $user1234->findDependentRowset('Bugs',
                                                     'Engineer',
                                                     $select);
]]></programlisting>

            </example>

            別の方法として、"マジックメソッド"
            を使用して従属テーブルの行を問い合わせることもできます。
            以下のパターンのいずれかに該当するメソッドを
            Row オブジェクトでコールすると、
            <classname>Zend_Db_Table_Row_Abstract</classname> は
            <methodname>findDependentRowset('&lt;TableClass&gt;', '&lt;Rule&gt;')</methodname>
            メソッドを実行します。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>$row->find&lt;TableClass&gt;()</code>
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>$row->find&lt;TableClass&gt;By&lt;Rule&gt;()</code>
                </para>
            </listitem>
        </itemizedlist>

        <para>
            上のパターンにおいて、<code>&lt;TableClass&gt;</code> および
            <code>&lt;Rule&gt;</code> は、それぞれ
            従属テーブルのクラス名、親テーブルとの参照関係を表す
            従属テーブルのルールのキーとなります。
        </para>

        <note>

            <para>
                他のアプリケーションフレームワーク、たとえば
                Ruby on Rails などでは、いわゆる "inflection
                (語尾変化)" という仕組みを採用しているものもあります。
                これにより、使用する状況に応じて識別子のスペルを変更できるようになります。
                あまり複雑にならないようにするため、
                <classname>Zend_Db_Table_Row</classname> ではこの仕組みを提供していません。
                メソッドのコール時に指定するテーブルの ID やルールのキーは、
                クラス名やキー名と正確に一致しなければなりません。
            </para>

        </note>

        <example id="zend.db.table.relationships.fetching.dependent.example-magic">

            <title>マジックメソッドの使用による従属行セットの取得</title>

            <para>
                この例では、先ほどの例と同じ従属行セットを見つける方法を示します。
                今回は、テーブルとルールを文字列で指定するのではなく、
                マジックメソッドを使用します。
            </para>

            <programlisting language="php"><![CDATA[
$accountsTable = new Accounts();
$accountsRowset = $accountsTable->find(1234);
$user1234 = $accountsRowset->current();

// デフォルトの参照ルールを使用します
$bugsReportedBy = $user1234->findBugs();

// 参照ルールを指定します
$bugsAssignedTo = $user1234->findBugsByEngineer();
]]></programlisting>

        </example>

    </sect2>

    <sect2 id="zend.db.table.relationships.fetching.parent">

        <title>親の行の取得</title>

        <para>
            従属テーブルに対するクエリの結果を Row オブジェクトとして取得すれば、
            その従属行が参照している親テーブルの行を取得できます。
            使用するメソッドは、次のようになります。
        </para>

        <programlisting language="php"><![CDATA[
$row->findParentRow($table, [$rule]);
]]></programlisting>

        <para>
            従属テーブルに対応する親テーブルの行は、常にひとつだけです。
            したがって、このメソッドは Rowset オブジェクトではなく
            Row オブジェクトを返します。
        </para>

        <para>
            最初の引数 <varname>$table</varname> には、
            親テーブルのクラス名を表す文字列を指定します。
            文字列ではなく、テーブルクラスのオブジェクトで指定することもできます。
        </para>

        <example id="zend.db.table.relationships.fetching.parent.example">

            <title>親の行の取得</title>

            <para>
                この例では、<code>Bugs</code> テーブルから
                (たとえば status が 'NEW' のものなどの)
                行オブジェクトを取得し、そのバグを報告した人に対応する行を
                <code>Accounts</code> テーブルから探す方法を示します。
            </para>

            <programlisting language="php"><![CDATA[
$bugsTable = new Bugs();
$bugsRowset = $bugsTable->fetchAll(array('bug_status = ?' => 'NEW'));
$bug1 = $bugsRowset->current();

$reporter = $bug1->findParentRow('Accounts');
]]></programlisting>

        </example>

        <para>
            二番目の引数 <varname>$rule</varname> はオプションです。
            これは、従属テーブルクラスの配列 <varname>$_referenceMap</varname>
            でのルールのキーの名前を指定します。
            ルールを指定しなかった場合は、配列の中で
            その親テーブルを参照している最初のルールを使用します。
            最初のもの以外のルールを使用する必要がある場合は、
            キーを指定しなければなりません。
        </para>

        <para>
            上の例のコードでは、ルールのキーを指定していません。
            したがって、親テーブルにマッチする最初のルールをデフォルトで使用します。
            ここでは <code>'Reporter'</code> がそれにあたります。
        </para>

        <example id="zend.db.table.relationships.fetching.parent.example-by">

            <title>ルールを指定することによる親の行の取得</title>

            <para>
                この例では、テーブル <code>Bugs</code> から取得した行オブジェクトについて、
                そのバグの修正担当者のアカウント情報を探す方法を示します。
                このリレーションに対応する参照ルールのキーは
                <code>'Engineer'</code> です。
            </para>

            <programlisting language="php"><![CDATA[
$bugsTable = new Bugs();
$bugsRowset = $bugsTable->fetchAll(array('bug_status = ?', 'NEW'));
$bug1 = $bugsRowset->current();

$engineer = $bug1->findParentRow('Accounts', 'Engineer');
]]></programlisting>

        </example>

        <para>
            別の方法として、"マジックメソッド"
            を使用して親テーブルの行を問い合わせることもできます。
            以下のパターンのいずれかに該当するメソッドを
            Row オブジェクトでコールすると、
            <classname>Zend_Db_Table_Row_Abstract</classname> は
            <methodname>findParentRow('&lt;TableClass&gt;', '&lt;Rule&gt;')</methodname>
            メソッドを実行します。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>$row->findParent&lt;TableClass&gt;([Zend_Db_Table_Select $select])</code>
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>$row->findParent&lt;TableClass&gt;By&lt;Rule&gt;([Zend_Db_Table_Select
                    $select])</code>
                </para>
            </listitem>
        </itemizedlist>

        <para>
            上のパターンにおいて、<code>&lt;TableClass&gt;</code> および
            <code>&lt;Rule&gt;()</code> は、それぞれ
            親テーブルのクラス名、親テーブルとの参照関係を表す
            従属テーブルのルールのキーとなります
        </para>

        <note>

            <para>
                メソッドのコール時に指定するテーブルの ID やルールのキーは、
                クラス名やキー名と正確に一致しなければなりません。
            </para>

        </note>

        <example id="zend.db.table.relationships.fetching.parent.example-magic">

            <title>マジックメソッドの使用による親の行の取得</title>

            <para>
                この例では、先ほどの例と同じ親の行を見つける方法を示します。
                今回は、テーブルとルールを文字列で指定するのではなく、
                マジックメソッドを使用します。
            </para>

            <programlisting language="php"><![CDATA[
$bugsTable = new Bugs();
$bugsRowset = $bugsTable->fetchAll(array('bug_status = ?', 'NEW'));
$bug1 = $bugsRowset->current();

// デフォルトの参照ルールを使用します
$reporter = $bug1->findParentAccounts();

// 参照ルールを指定します
$engineer = $bug1->findParentAccountsByEngineer();
]]></programlisting>

        </example>

    </sect2>

    <sect2 id="zend.db.table.relationships.fetching.many-to-many">

        <title>多対多のリレーションを使用した行セットの取得</title>

        <para>
            多対多のリレーションの片方のテーブル (この例では "元テーブル"
            と呼ぶことにします) に対するクエリの結果を Row
            オブジェクトとして取得すれば、もう一方のテーブル (この例では
            "対象テーブル" と呼ぶことにします) の対応する行を取得できます。
            使用するメソッドは、次のようになります。
        </para>

        <programlisting language="php"><![CDATA[
$row->findManyToManyRowset($table,
                           $intersectionTable,
                           [$rule1,
                               [$rule2,
                                   [Zend_Db_Table_Select $select]
                               ]
                           ]);
]]></programlisting>

        <para>
            このメソッドは <classname>Zend_Db_Table_Rowset_Abstract</classname> オブジェクトを返します。
            その中には、テーブル <varname>$table</varname>
            の行のうち、多対多のリレーションを満たすものが含まれます。
            元テーブルの行 <varname>$row</varname> を使用して中間テーブルの行を探し、
            さらにそれを対象テーブルと結合します。
        </para>

        <para>
            最初の引数 <varname>$table</varname> には、
            多対多のリレーションの対象テーブルのクラス名を表す文字列を指定します。
            文字列ではなく、テーブルクラスのオブジェクトで指定することもできます。
        </para>

        <para>
            二番目の引数 <varname>$intersectionTable</varname> には、
            多対多のリレーションの中間テーブルのクラス名を表す文字列を指定します。
            文字列ではなく、テーブルクラスのオブジェクトで指定することもできます。
        </para>

        <example id="zend.db.table.relationships.fetching.many-to-many.example">

            <title>多対多の形式の行セットの取得</title>

            <para>
                この例では、元テーブル <code>Bugs</code>
                から取得した行オブジェクトについて、対象テーブル
                <code>Products</code> の行を探す方法を示します。
                これは、そのバグに関連する製品を表すものです。
            </para>

            <programlisting language="php"><![CDATA[
$bugsTable = new Bugs();
$bugsRowset = $bugsTable->find(1234);
$bug1234 = $bugsRowset->current();

$productsRowset = $bug1234->findManyToManyRowset('Products',
                                                 'BugsProducts');
]]></programlisting>

        </example>

        <para>
            三番目と四番目の引数 <varname>$rule1</varname> および
            <varname>$rule2</varname> はオプションです。
            これは、中間テーブルの配列 <varname>$_referenceMap</varname>
            でのルールのキーの名前を表す文字列です。
        </para>

        <para>
            <varname>$rule1</varname> は、中間テーブルから元テーブルへのリレーションを表す
            ルールのキーです。この例では、<code>BugsProducts</code> から
            <code>Bugs</code> へのリレーションがそれにあたります。
        </para>

        <para>
            <varname>$rule2</varname> は、中間テーブルから対象テーブルへのリレーションを表す
            ルールのキーです。この例では、<code>Bugs</code> から
            <code>Products</code> へのリレーションがそれにあたります。
        </para>

        <para>
            親や従属行を取得するメソッドと同様、もしルールを指定しなければ、
            配列 <varname>$_referenceMap</varname>
            の中でそのリレーションに該当する最初のルールを使用します。
            最初のもの以外のルールを使用する必要がある場合は、
            キーを指定しなければなりません。
        </para>

        <para>
            上の例のコードでは、ルールのキーを指定していません。
            したがって、マッチする最初のルールをデフォルトで使用します。
            ここでは、<varname>$rule1</varname> が <code>'Reporter'</code>、
            そして <varname>$rule2</varname> が <code>'Product'</code> になります。
        </para>

        <example id="zend.db.table.relationships.fetching.many-to-many.example-by">

            <title>ルールを指定することによる多対多の形式の行セットの取得</title>

            <para>
                この例では、元テーブル <code>Bugs</code>
                から取得した行オブジェクトについて、対象テーブル
                <code>Products</code> の行を探す方法を示します。
                これは、そのバグに関連する製品を表すものです。
            </para>

            <programlisting language="php"><![CDATA[
$bugsTable = new Bugs();
$bugsRowset = $bugsTable->find(1234);
$bug1234 = $bugsRowset->current();

$productsRowset = $bug1234->findManyToManyRowset('Products',
                                                 'BugsProducts',
                                                 'Bug');
]]></programlisting>

        </example>

        <para>
            別の方法として、"マジックメソッド"
            を使用して多対多のリレーションの対象テーブルの行を問い合わせることもできます。
            以下のパターンのいずれかに該当するメソッドをコールすると、
            <classname>Zend_Db_Table_Row_Abstract</classname> は
            <code>findManyToManyRowset('&lt;TableClass&gt;', '&lt;IntersectionTableClass&gt;', '&lt;Rule1&gt;', '&lt;Rule2&gt;')</code>
            メソッドを実行します。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>$row->find&lt;TableClass&gt;Via&lt;IntersectionTableClass&gt;
                    ([Zend_Db_Table_Select $select])</code>
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>$row->find&lt;TableClass&gt;Via&lt;IntersectionTableClass&gt;By&lt;Rule1&gt;
                    ([Zend_Db_Table_Select $select])</code>
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>$row->find&lt;TableClass&gt;Via&lt;IntersectionTableClass&gt;By&lt;Rule1&gt;And&lt;Rule2&gt;
                    ([Zend_Db_Table_Select $select])</code>
                </para>
            </listitem>
        </itemizedlist>

        <para>
            上のパターンにおいて、<code>&lt;TableClass&gt;</code> および
            <code>&lt;IntersectionTableClass&gt;</code> は、それぞれ
            対象テーブルのクラス名および中間テーブルのクラス名となります。
            また <code>&lt;Rule1&gt;</code> および <code>&lt;Rule2&gt;</code>
            は、それぞれ中間テーブルから元テーブル、
            週間テーブルから対象テーブルへの参照を表すルールのキーとなります。
        </para>

        <note>

            <para>
                メソッドのコール時に指定するテーブルの ID やルールのキーは、
                クラス名やキー名と正確に一致しなければなりません。
            </para>

        </note>

        <example id="zend.db.table.relationships.fetching.many-to-many.example-magic">

            <title>マジックメソッドの使用による多対多の形式の行セットの取得</title>

            <para>
                この例では、製品からの多対多のリレーションの
                対象テーブルの行を見つける方法を示します。
                そのバグに関連する製品を見つけます。
            </para>

            <programlisting language="php"><![CDATA[
$bugsTable = new Bugs();
$bugsRowset = $bugsTable->find(1234);
$bug1234 = $bugsRowset->current();

// デフォルトの参照ルールを使用します
$products = $bug1234->findProductsViaBugsProducts();

// 参照ルールを指定します
$products = $bug1234->findProductsViaBugsProductsByBug();
]]></programlisting>

        </example>

    </sect2>

    <sect2 id="zend.db.table.relationships.cascading">

        <title>書き込み操作の連鎖</title>

        <note>

            <title>データベースでの DRI の宣言</title>

            <para>
                <classname>Zend_Db_Table</classname> の連鎖操作を宣言するのは、
                <acronym>RDBMS</acronym> が宣言参照整合性 (DRI)
                をサポートしていない場合
                <emphasis>のみ</emphasis> を想定しています。
            </para>

            <para>
                たとえば、MySQL や MariaDB の MyISAM ストレージエンジンや
                SQLite では DRI をサポートしていません。
                このような場合は、<classname>Zend_Db_Table</classname> での連鎖操作の宣言が有用となるでしょう。
            </para>

            <para>
                もし <acronym>RDBMS</acronym> が DRI の <code>ON DELETE</code> 句
                および <code>ON UPDATE</code> 句を実装しているのなら、
                データベーススキーマでそれを宣言すべきです。
                <classname>Zend_Db_Table</classname> の連鎖機能を使ってはいけません。
                <acronym>RDBMS</acronym> が実装する連鎖 DRI を使用したほうが、
                データベースのパフォーマンスや一貫性、整合性の面で有利です。
            </para>

            <para>
                もっとも重要なのは、<acronym>RDBMS</acronym> と <classname>Zend_Db_Table</classname>
                クラスの両方で同時に連鎖操作を宣言してはいけないということです。
            </para>

        </note>

        <para>
            親テーブルに対して <constant>UPDATE</constant> あるいは
            <constant>DELETE</constant> を行った際に、
            従属テーブルに対して行う操作を指定できます。
        </para>

        <example id="zend.db.table.relationships.cascading.example-delete">

            <title>連鎖削除の例</title>

            <para>
                この例では <code>Products</code> テーブルの行を削除します。
                その際に、<code>Bugs</code> テーブルの従属行も
                自動的に削除するように設定されています。
            </para>

            <programlisting language="php"><![CDATA[
$productsTable = new Products();
$productsRowset = $productsTable->find(1234);
$product1234 = $productsRowset->current();

$product1234->delete();
// 自動的に Bugs テーブルにも連鎖し、
// 従属する行が削除されます
]]></programlisting>

        </example>

        <para>
            同様に、<constant>UPDATE</constant> で親テーブルの主キーの値を変更した場合は、
            従属テーブルの外部キーの値も自動的に新しい値に更新したくなることでしょう。
            これにより、その参照を最新の状態にできます。
        </para>

        <para>
            シーケンスなどの機能を用いて主キーを生成している場合は、
            通常はその値を変更する必要はありません。しかし、
            <emphasis>自然キー</emphasis> を使用している場合は、
            値が変わる可能性もあります。そのような場合は、
            従属テーブルに対して連鎖更新を行う必要があるでしょう。
        </para>

        <para>
            <classname>Zend_Db_Table</classname> で連鎖リレーションを宣言するには、
            <varname>$_referenceMap</varname> の中でのルールを編集します。
             連想配列のキー <command>'onDelete'</command> および <command>'onUpdate'</command>
              をそれらのオプションの一つに設定します。
        </para>

        <!-- TODO : to be translated -->
        <itemizedlist>

            <listitem>
                <para>
                    Cascade:  This option configures a single-level cascade (parent table plus all
                    directly-dependent tables).  To enable this option set the appropriate key in
                    <varname>$_referenceMap</varname> to string 'cascade' or use the constant 
                    <constant>self::CASCADE</constant>. 
                </para>
            </listitem>

            <listitem>
                <para>
                    Recursive Cascade:  This option configures a full recursive cascade starting
                    with the parent table.  To enable this option set the appropriate key in
                    <varname>$_referenceMap</varname> to string 'cascadeRecurse' or use the constant 
                    <constant>self::CASCADE_RECURSE</constant>. 
                </para>
            </listitem>

        </itemizedlist>

        <para>
            親テーブルから行が削除されたり、主キーの値が更新されたりする前に、
            その親の行を参照する従属テーブルの行が最初に削除あるいは更新されます。
        </para>

        <example id="zend.db.table.relationships.cascading.example-declaration">

            <title>連鎖操作の宣言の例</title>

            <para>
                以下の例では、<code>Products</code>
                テーブルのある行が削除されたときに、その行を参照している
                <code>Bugs</code> テーブルの行が自動的に削除されます。
                参照マップのエントリの要素 <code>'onDelete'</code> が
                <constant>self::CASCADE</constant> に設定されているからです。
            </para>

            <para>
                以下の例では、親クラスの主キーの値が変更されても
                連鎖更新は起こりません。これは、参照マップのエントリの要素
                <code>'onUpdate'</code> が <constant>self::RESTRICT</constant>
                に設定されているからです。<code>'onUpdate'</code>
                エントリ自体を省略しても同じ結果となります。
            </para>

            <programlisting language="php"><![CDATA[
class BugsProducts extends Zend_Db_Table_Abstract
{
    ...
    protected $_referenceMap = array(
        'Product' => array(
            'columns'           => array('product_id'),
            'refTableClass'     => 'Products',
            'refColumns'        => array('product_id'),
            'onDelete'          => self::CASCADE,
            'onUpdate'          => self::RESTRICT
        ),
        ...
    );
}
]]></programlisting>

        </example>

        <sect3 id="zend.db.table.relationships.cascading.notes">

            <title>連鎖操作に関する注意点</title>

            <para>
                <emphasis><classname>Zend_Db_Table</classname> が実行する連鎖操作はアトミックではありません。</emphasis>
            </para>

            <para>
                つまり、もしデータベース自身が参照整合性制約を実装している場合、
                <classname>Zend_Db_Table</classname> クラスが実行した連鎖 <constant>UPDATE</constant>
                がその制約と競合し、参照整合性に違反してしまうことになるということです。
                <classname>Zend_Db_Table</classname> の連鎖 <constant>UPDATE</constant> を使用できるのは、
                データベース側で参照整合性制約を設定していない場合
                <emphasis>のみ</emphasis> です。
            </para>

            <para>
                連鎖 <constant>DELETE</constant> に関しては、参照整合性に違反してしまう恐れはあまりありません。
                従属行の削除は、参照する親の行が削除される前に
                アトミックでない処理として行うことができます。
            </para>

            <para>
                しかしながら、<constant>UPDATE</constant> および <constant>DELETE</constant>
                のどちらについても、アトミックでない方法でデータを変更すると、
                整合性がない状態のデータを他のユーザに見られてしまうというリスクが発生します。
                たとえば、ある行とそのすべての従属行を削除することを考えましょう。
                ほんの一瞬ですが、「従属行は削除したけれど親行はまだ削除していない」
                という状態を他のクライアントプログラムから見られてしまう可能性があります。
                そのクライアントプログラムは、従属行がない親行を見て、
                それが意図した状態であると考えることでしょう。
                クライアントが読み込んだデータが
                変更の途中の中途半端な状態であることなど、知るすべもありません。
            </para>

            <para>
                アトミックでない変更による問題を軽減するには、
                トランザクションを使用してその変更を他と隔離します。
                しかし <acronym>RDBMS</acronym> によってはトランザクションをサポートしていないものもありますし、
                まだコミットされていない "ダーティな"
                変更を他のクライアントから見られるようにしているものもあります。
            </para>

            <para>
                <emphasis><classname>Zend_Db_Table</classname> の連鎖処理は
                <classname>Zend_Db_Table</classname> からのみ実行できます。</emphasis>
            </para>

            <para>
                <classname>Zend_Db_Table</classname> クラスで定義した連鎖削除や更新は、Row クラスで
                <methodname>save()</methodname> メソッドあるいは
                <methodname>delete()</methodname> メソッドを実行した際に適用されます。
                しかし、クエリツールや別のアプリケーションなどの
                別ルートでデータを更新あるいは削除した場合は、
                連鎖操作は発生しません。<classname>Zend_Db_Adapter</classname> クラスの
                <methodname>update()</methodname> メソッドや <methodname>delete()</methodname>
                メソッドを実行したとしても、<classname>Zend_Db_Table</classname>
                で定義した連鎖操作は実行されません。
            </para>

            <para>
                <emphasis>連鎖 <constant>INSERT</constant> はありません。</emphasis>
            </para>

            <para>
                連鎖 <constant>INSERT</constant> はサポートしていません。
                親テーブルに行を追加したら、
                従属テーブルへの行の追加は別の処理として行う必要があります。
            </para>

        </sect3>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->