[DDC-473] Inadequate description for @MappedSuperclass in Annotations Reference Created: 25/Mar/10  Updated: 26/Aug/10

Status: Open
Project: Doctrine 2 - ORM
Component/s: Documentation
Affects Version/s: 2.0-ALPHA4
Fix Version/s: 2.0
Security Level: All

Type: Improvement Priority: Minor
Reporter: David Abdemoulaie Assignee: Jonathan H. Wage
Resolution: Unresolved Votes: 0
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


 Comments   
Comment by David Abdemoulaie [ 25/Mar/10 ]

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'
Comment by Benjamin Eberlei [ 28/Mar/10 ]

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.

Comment by Roman S. Borschel [ 15/Apr/10 ]

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.

Comment by Roman S. Borschel [ 15/Apr/10 ]

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.

Generated at Fri Oct 24 15:07:48 UTC 2014 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.