This week's book giveaway is in the OCAJP 8 forum. We're giving away four copies of OCA Java SE 8 Programmer I Study Guide and have Edward Finegan & Robert Liguori on-line! See this thread for details.
Well, when we're doing Java class to database table mappings, we always talk about one table to one database table. That's the ideal. But sometimes, you have two classes that must map to ONE database table. But we only mark one class as the entity to be associated with the table. The second class, we say is embedded in the first class, and as such, the embedded class will map to the same database table as the embedded class.
On my website, I use an example where a Thing and a ThingDetail class, two separate classes in a Java domain model must map to a single database table, with the database table being named thing.
So, in this situation, I made the Thing the entity class that maps to the thing table.
But we also want the ThingDetail class to map to the same table, so we mark the ThingDetail class as being embeddable, namely, embeddable in the Thing class:
This is a simple example. In more complicated scenarios, compound primary keys are defined in a separate class, and those compound primary key classes become embeddable in the class for which they will act as a primary key. That's where you often see the embeddable annotation being used - in compound primary key classes.
Here's a little tutorial on compound primary keys, if you find yourself needing to use the Embeddable annotation in this type of scenario: