From 26608fed5ace883646869b0b51cae0fcb614cca7 Mon Sep 17 00:00:00 2001
From: Luis Cordova <cordoval@gmail.com>
Date: Sun, 29 Jul 2012 00:39:24 -0500
Subject: [PATCH 1/2] [DDC-1872] add tutorial for override annotations mappings

---
 en/index.rst                                  |  1 +
 en/toc.rst                                    |  1 +
 .../override-mappings-with-annotations.rst    | 88 +++++++++++++++++++
 3 files changed, 90 insertions(+)
 create mode 100644 en/tutorials/override-mappings-with-annotations.rst

diff --git a/en/index.rst b/en/index.rst
index e6e90f179..f066b5bc3 100644
--- a/en/index.rst
+++ b/en/index.rst
@@ -93,6 +93,7 @@ Tutorials
   * :doc:`Composite Primary Keys <tutorials/composite-primary-keys>`
   * :doc:`Ordered associations <tutorials/ordered-associations>`
   * :doc:`Pagination <tutorials/pagination>`
+  * :doc:`Override Mappings With Annotations <tutorials/override-mappings-with-annotations>`
 
 Cookbook
 --------
diff --git a/en/toc.rst b/en/toc.rst
index 5cdbe90c7..9e9edd744 100644
--- a/en/toc.rst
+++ b/en/toc.rst
@@ -13,6 +13,7 @@ Tutorials
    tutorials/composite-primary-keys
    tutorials/ordered-associations
    tutorials/in-ten-quick-steps
+   tutorials/override-mappings-with-annotations
 
 Reference Guide
 ---------------
diff --git a/en/tutorials/override-mappings-with-annotations.rst b/en/tutorials/override-mappings-with-annotations.rst
new file mode 100644
index 000000000..eaf316213
--- /dev/null
+++ b/en/tutorials/override-mappings-with-annotations.rst
@@ -0,0 +1,88 @@
+Override Mappings With Annotations
+----------------------------------
+
+Sometimes there is a need to persist entities but override all or part of the
+mapping metadata. Sometimes also the mapping to override comes from entities
+using traits where the traits have mapping metadata.
+This tutorial explains how to override mapping metadata,
+i.e. attributes and associations metadata in particular. The example here shows
+the overriding of a class that uses a trait but is similar when extending a base
+class as shown at the end of this tutorial.
+
+Suppose we have a class ExampleEntityWithOverride. This class uses trait ExampleTrait:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * @Entity
+     *
+     * @AttributeOverrides({
+     *      @AttributeOverride(name="foo",
+     *          column=@Column(
+     *              name     = "foo_overridden",
+     *              type     = "integer",
+     *              length   = 140,
+     *              nullable = false,
+     *              unique   = false
+     *          )
+     *      )
+     * })
+     *
+     * @AssociationOverrides({
+     *      @AssociationOverride(name="bar",
+     *          joinColumns=@JoinColumn(
+     *              name="example_entity_overridden_bar_id", referencedColumnName="id"
+     *          )
+     *      )
+     * })
+     */
+    class ExampleEntityWithOverride
+    {
+        use ExampleTrait;
+    }
+
+    /**
+     * @Entity
+     */
+    class Bar
+    {
+        /** @Id @Column(type="string") */
+        private $id;
+    }
+
+The docblock is showing metadata override of the attribute and association type. It
+basically changes the names of the columns mapped for a property ``foo`` and for
+the association ``bar`` which relates to Bar class shown above. Here is the trait
+which has mapping metadata that is overridden by the annotation above:
+
+.. code-block:: php
+
+    /**
+     * Trait class
+     */
+    trait ExampleTrait
+    {
+        /** @Id @Column(type="string") */
+        private $id;
+
+        /**
+         * @Column(name="trait_foo", type="integer", length=100, nullable=true, unique=true)
+         */
+        protected $foo;
+
+        /**
+         * @OneToOne(targetEntity="Bar", cascade={"persist", "merge"})
+         * @JoinColumn(name="example_trait_bar_id", referencedColumnName="id")
+         */
+        protected $bar;
+    }
+
+The case for just extending a class would be just the same but:
+
+.. code-block:: php
+
+    class ExampleEntityWithOverride extends BaseEntityWithSomeMapping
+    {
+        // ...
+    }

From 6c932af0a0aa53630ca7776824e90de092c8aab3 Mon Sep 17 00:00:00 2001
From: Luis Cordova <cordoval@gmail.com>
Date: Sun, 29 Jul 2012 23:33:18 -0500
Subject: [PATCH 2/2] [DDC-1872] address comments from beberlei

---
 en/index.rst                                                | 2 +-
 en/toc.rst                                                  | 2 +-
 ...> override-field-association-mappings-in-subclasses.rst} | 6 ++++--
 3 files changed, 6 insertions(+), 4 deletions(-)
 rename en/tutorials/{override-mappings-with-annotations.rst => override-field-association-mappings-in-subclasses.rst} (94%)

diff --git a/en/index.rst b/en/index.rst
index f066b5bc3..9536ee56d 100644
--- a/en/index.rst
+++ b/en/index.rst
@@ -93,7 +93,7 @@ Tutorials
   * :doc:`Composite Primary Keys <tutorials/composite-primary-keys>`
   * :doc:`Ordered associations <tutorials/ordered-associations>`
   * :doc:`Pagination <tutorials/pagination>`
-  * :doc:`Override Mappings With Annotations <tutorials/override-mappings-with-annotations>`
+  * :doc:`Override Field/Association Mappings In Subclasses <tutorials/override-field-association-mappings-in-subclasses>`
 
 Cookbook
 --------
diff --git a/en/toc.rst b/en/toc.rst
index 9e9edd744..73f1f25b9 100644
--- a/en/toc.rst
+++ b/en/toc.rst
@@ -13,7 +13,7 @@ Tutorials
    tutorials/composite-primary-keys
    tutorials/ordered-associations
    tutorials/in-ten-quick-steps
-   tutorials/override-mappings-with-annotations
+   tutorials/override-field-association-mappings-in-subclasses
 
 Reference Guide
 ---------------
diff --git a/en/tutorials/override-mappings-with-annotations.rst b/en/tutorials/override-field-association-mappings-in-subclasses.rst
similarity index 94%
rename from en/tutorials/override-mappings-with-annotations.rst
rename to en/tutorials/override-field-association-mappings-in-subclasses.rst
index eaf316213..792d97887 100644
--- a/en/tutorials/override-mappings-with-annotations.rst
+++ b/en/tutorials/override-field-association-mappings-in-subclasses.rst
@@ -1,5 +1,5 @@
-Override Mappings With Annotations
-----------------------------------
+Override Field Association Mappings In Subclasses
+-------------------------------------------------
 
 Sometimes there is a need to persist entities but override all or part of the
 mapping metadata. Sometimes also the mapping to override comes from entities
@@ -86,3 +86,5 @@ The case for just extending a class would be just the same but:
     {
         // ...
     }
+
+Overriding is also supported via XML and YAML.
\ No newline at end of file