Chapter 12. Mapping Metadata
Prev | Part 2. Java Persistence API | Next

## Chapter 12. Mapping Metadata

Object-relational mapping is the process of mapping entities to relational database tables. In EJB persistence, you perform object/relational mapping through mapping metadata. Mapping metadata uses annotations to describe how to link your object model to your relational model.

| Note
Kodo offers tools to automate mapping and schema creation. See Chapter 7, Mapping in the Reference Guide.

Throughout this chapter, we will draw on the object model introduced in Chapter 5, Metadata. We present that model again below. As we discuss various aspects of mapping metadata, we will zoom in on specific areas of the model and show how we map the object layer to the relational layer.

All mapping metadata is optional. Where no explicit mapping metadata is given, EJB 3 persistence uses the defaults defined by the specification. As we present each mapping throughout this chapter, we also describe the defaults that apply when the mapping is absent.

## 12.1. Table

The `Table` annotation specifies the table for an entity class. If you omit the `Table` annotation, base entity classes default to a table with their unqualified class name. The default table of an entity subclass depends on the inheritance strategy, as you will see in Section 12.6, “Inheritance”.

`Table`s have the following properties:

- `String name`: The name of the table. Defaults to the unqualified entity class name.

- `String schema`: The table's schema. If you do not name a schema, EJB uses the default schema for the database connection.

- `String catalog`: The table's catalog. If you do not name a catalog, EJB uses the default catalog for the database connection.

- `UniqueConstraint[] uniqueConstraints`: An array of unique constraints to place on the table. We cover unique constraints below. Defaults to an empty array.

The equivalent XML element is `table`. It has the following attributes, which correspond to the annotation properties above:

- `name`

- `schema`

- `catalog`

The `table` element also accepts nested `unique-constraint` elements representing unique constraints. We will detail unique constraints shortly.

Sometimes, some of the fields in a class are mapped to secondary tables. In that case, use the class' `Table` annotation to name what you consider the class' primary table. Later, we will see how to map certain fields to other tables.

The example below maps classes to tables according to the following diagram. The `CONTRACT`, `SUB`, and `LINE_ITEM` tables are in the `CNTRCT` schema; all other tables are in the default schema.

Note that the diagram does not include our model's `Document` and `Address` classes. Mapped superclasses and embeddable classes are never mapped to tables.

Example 12.1. Mapping Classes

    package org.mag;

    @Entity
    @IdClass(Magazine.MagazineId.class)
    @Table(name="MAG")
    public class Magazine
    {
        ...

        public static class MagazineId
        {
            ...
        }
    }

    @Entity
    @Table(name="ART")
    public class Article
    {
        ...
    }

    package org.mag.pub;

    @Entity
    @Table(name="COMP")
    public class Company
    {
        ...
    }

    @Entity
    @Table(name="AUTH")
    public class Author
    {
        ...
    }

    @Embeddable
    public class Address
    {
        ...
    }

    package org.mag.subscribe;

    @MappedSuperclass
    public abstract class Document
    {
        ...
    }

    @Entity
    @Table(schema="CNTRCT")
    public class Contract
        extends Document
    {
        ...
    }

    @Entity
    @Table(name="SUB", schema="CNTRCT")
    public class Subscription
    {
        ...

        @Entity
        @Table(name="LINE_ITEM", schema="CNTRCT")
        public static class LineItem
            extends Contract
        {
            ...
        }
    }

    @Entity(name="Lifetime")
    public class LifetimeSubscription
        extends Subscription
    {
        ...
    }

    @Entity(name="Trial")
    public class TrialSubscription
        extends Subscription
    {
        ...
    }

The same mapping information expressed in XML:

    <entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
        version="1.0">
        <mapped-superclass class="org.mag.subscribe.Document">
            ...
        </mapped-superclass>
        <entity class="org.mag.Magazine">
            <table name="MAG"/>
            <id-class="org.mag.Magazine.MagazineId"/>
            ...
        </entity>
        <entity class="org.mag.Article">
            <table name="ART"/>
            ...
        </entity>
        <entity class="org.mag.pub.Company">
            <table name="COMP"/>
            ...
        </entity>
        <entity class="org.mag.pub.Author">
            <table name="AUTH"/>
            ...
        </entity>
        <entity class="org.mag.subcribe.Contract">
            <table schema="CNTRCT"/>
            ...
        </entity>
        <entity class="org.mag.subcribe.Subscription">
            <table name="SUB" schema="CNTRCT"/>
            ...
        </entity>
        <entity class="org.mag.subscribe.Subscription.LineItem">
            <table name="LINE_ITEM" schema="CNTRCT"/>
            ...
        </entity>
        <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime">
            ...
        </entity>
        <entity class="org.mag.subscribe.TrialSubscription" name="Trial">
            ...
        </entity>
        <embeddable class="org.mag.pub.Address">
            ...
        </embeddable>
    </entity-mappings>

Prev | Up | Next
11.2. Retrieving Persistent Objects with SQL | Home | 12.2. Unique Constraints