Doctrine 2 - ORM
  1. Doctrine 2 - ORM
  2. DDC-473

Inadequate description for @MappedSuperclass in Annotations Reference

    Details

    • Type: Improvement Improvement
    • Status: Open
    • Priority: Minor Minor
    • Resolution: Unresolved
    • Affects Version/s: 2.0-ALPHA4
    • Fix Version/s: 2.0
    • Component/s: Documentation
    • Security Level: All
    • Labels:
      None

      Description

      See: http://www.doctrine-project.org/documentation/manual/2_0/en/annotations-reference#ann_mappedsuperclass

      @MappedSuperclass

      An mapped superclass is an abstract or concrete class that provides persistent entity state and mapping information for its subclasses, but which is not itself an entity. This annotation is specified on the Class docblock and has no additional attributes.

      This doesn't adequately communicate how to use it. It took me several minutes of failing before I downloaded the PDF and did a search for @MappedSuperclass to find an example of how it's used.

      Specifically the following were unclear:

      • Is this defined on the superclass or on the children classes?
      • If it's defined on the child classes, does it take parameters? The name of the super class?
      • It was not at all apparent to me that it was mutually exclusive with the @Entity tag

        Activity

        Hide
        Roman S. Borschel added a comment -

        David,

        @"Is this defined on the superclass or on the children classes?"

        It doesnt matter. A @MappedSuperclass can be anywhere in an inheritance hierarchy and it always does the same thing, inherit its mapping information to subclasses (but its not itself an entity). The docs say:

        Mapped superclasses, just as regular, non-mapped classes, can appear in the middle of an otherwise mapped inheritance hierarchy (through Single Table Inheritance or Class Table Inheritance).
        

        as well as

        Entities support inheritance, polymorphic associations, and polymorphic queries. Both abstract and concrete classes can be entities. Entities may extend non-entity classes as well as entity classes, and non-entity classes may extend entity classes.
        

        So entities, mapped superclasses and plain non-mapped classes can appear mixed in an inheritance hierarchy. Nevertheless all the classes in a hierarchy that are entities must use 1 inheritance strategy, you can not mix inheritance mapping strategies in a single class hierarchy.

        @"If it's defined on the child classes, does it take parameters? The name of the super class?"

        No, it doesnt. The docs dont mention any parameters either which is correct.

        @"It was not at all apparent to me that it was mutually exclusive with the @Entity tag"

        OK, that needs to be made clearer in the docs then.

        Show
        Roman S. Borschel added a comment - David, @"Is this defined on the superclass or on the children classes?" It doesnt matter. A @MappedSuperclass can be anywhere in an inheritance hierarchy and it always does the same thing, inherit its mapping information to subclasses (but its not itself an entity). The docs say: Mapped superclasses, just as regular, non-mapped classes, can appear in the middle of an otherwise mapped inheritance hierarchy (through Single Table Inheritance or Class Table Inheritance). as well as Entities support inheritance, polymorphic associations, and polymorphic queries. Both abstract and concrete classes can be entities. Entities may extend non-entity classes as well as entity classes, and non-entity classes may extend entity classes. So entities, mapped superclasses and plain non-mapped classes can appear mixed in an inheritance hierarchy. Nevertheless all the classes in a hierarchy that are entities must use 1 inheritance strategy, you can not mix inheritance mapping strategies in a single class hierarchy. @"If it's defined on the child classes, does it take parameters? The name of the super class?" No, it doesnt. The docs dont mention any parameters either which is correct. @"It was not at all apparent to me that it was mutually exclusive with the @Entity tag" OK, that needs to be made clearer in the docs then.
        Hide
        Roman S. Borschel added a comment -

        A mapped superclass has not many restrictions and these are mentioned in the docs (i.e. only unidirectional associations), what David mentions above should work, if it doesnt its a bug, I think DDC-511 looks like that same issue.

        Show
        Roman S. Borschel added a comment - A mapped superclass has not many restrictions and these are mentioned in the docs (i.e. only unidirectional associations), what David mentions above should work, if it doesnt its a bug, I think DDC-511 looks like that same issue.
        Hide
        Benjamin Eberlei added a comment -

        I updated the documentation, the question is if we should check for the mapped superclass attribute and throw exceptions if other entity level annotations are specified.

        Show
        Benjamin Eberlei added a comment - I updated the documentation, the question is if we should check for the mapped superclass attribute and throw exceptions if other entity level annotations are specified.
        Hide
        David Abdemoulaie added a comment -

        Apparently it's also incompatible with several other tag as well.

        I thought it made sense to try the following and see if the @InheritanceType and @Discriminator___ tags would apply to the children classes:

        /**
         * @MappedSuperclass
         * @InheritanceType("SINGLE_TABLE")
         * @DiscriminatorColumn(name="type", type="string")
         * @DiscriminatorMap({"User" = "User", "Group" = "Group"})
         */
        abstract class Principal
        

        But apparently this flags D2 to treat it as an Entity anyway, resulting in the following error:

        PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'sentact5.principal'
        
        Show
        David Abdemoulaie added a comment - Apparently it's also incompatible with several other tag as well. I thought it made sense to try the following and see if the @InheritanceType and @Discriminator___ tags would apply to the children classes: /** * @MappedSuperclass * @InheritanceType("SINGLE_TABLE") * @DiscriminatorColumn(name="type", type="string") * @DiscriminatorMap({"User" = "User", "Group" = "Group"}) */ abstract class Principal But apparently this flags D2 to treat it as an Entity anyway, resulting in the following error: PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'sentact5.principal'

          People

          • Assignee:
            Jonathan H. Wage
            Reporter:
            David Abdemoulaie
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated: