<document>
<header>
  <title>@Entity Table Configuration</title>
  <version>Resin 3.0</version>

  <description>
  <p>Describes the basic annotation for a single-table entity bean.</p>

  </description>
</header>

<summary objsummary='localtoc'/>

<section title="See Also">

<ul>
<li>See <a href="http://wiki.caucho.com/Amber">http://wiki.caucho.com/Amber</a> the Amber wiki.
<li>See <a href="tutorial/cmp-basic/index.xtp">Basic tutorial</a> for
a complete single-table example.
<li>See <a href="tutorial/cmp-many2one/index.xtp">Many-to-one tutorial</a> for
basic relations.
</ul>

</section>

<section title="Table annotations">

<defun title="@Entity">

<p>Annotates the class as an entity bean.</p>

<p>See the <a href="tutorial/cmp-basic/index.xtp">basic property tutorial</a>
and the <a href="tutorial/cmp-basic-field/index.xtp">basic field tutorial</a>
for an introduction.</p>

<deftable-childtags>
<tr><td>name<td>The name of the bean<td>The class name (unqualified)
</deftable-childtags>

<p>The fields or properties will be annotated by @Id, @Basic, etc.
Amber will detect either field or property annotation by the
type for the @Id.  In other words, if Amber sees an @Id on a field,
it will use field access.  If Amber sees @Id on a method, it will use
property access.</p>

<def>
package javax.persistence;

@Target(TYPE)
@Retention(RUNTIME)
public @interface Entity {
  String name() default "";
}
</def>

</defun>

<defun title="@SecondaryTable">

<p>Specifies a secondary database table for an entity bean.
The secondary table will contain the fields with a secondaryTable
in the @Column.</p>

<deftable-childtags>
<tr><td>name<td>The name of the table<td>The unqualified class name.
<tr><td>catalog<td>the table's catalog<td>none
<tr><td>schema<td>the table's schema<td>none
<tr><td>pkJoinColumns<td>join column to the primary table<td>joins the primary key
<tr><td>uniqueConstraint<td>unique constraints during generation<td>none
</deftable-childtags>

<def>
package javax.persistence;

@Target(TYPE)
@Retention(RUNTIME)
public @interface SecondaryTable {
  String name() default "";
  String catalog() default "";
  String schema() default "";
  PrimaryKeyJoinColumn []pkJoinColumns() default {};
  UniqueConstraint []uniqueConstraints() default {};
}
</def>

</defun>

<defun title="@Table">

<p>Specifies the database table for an entity bean.  The
default table name is the class name.</p>

<deftable-childtags>
<tr><td>name<td>The name of the table<td>The unqualified class name.
<tr><td>catalog<td>the table's catalog<td>none
<tr><td>schema<td>the table's schema<td>none
<tr><td>uniqueConstraint<td>unique constraints during generation<td>none
</deftable-childtags>

<def>
package javax.persistence;

@Target(TYPE)
@Retention(RUNTIME)
public @interface Table {
  String name() default "";
  String catalog() default "";
  String schema() default "";
  UniqueConstraint []uniqueConstraints() default {};
}
</def>

</defun>

</section>

<section title="Property Annotations">

<defun title="@Basic">

<p>Marks a field as a persistent field.</p>

<deftable-childtags>
<tr><td>fetch<td>EAGER or LAZY fetching<td>FetchType.EAGER
<tr><td>optional<td>if true, the column may be null<td>true
</deftable-childtags>

<p>The fetch types are:
<ul>
<li>EAGER - fetch the field when the bean is loaded
<li>LAZY - fetch the field only when the field is used
</ul>

<example title="String property ">
@Entity
public class Course {
  @Basic
  public String getName()

  ...
}
</example>

<example title="Lazy-loaded property ">
@Entity
public class Course {
  @Basic(fetch=FetchType.LAZY)
  public String getMassiveText()

  ...
}
</example>

<def title="javax.persistence.Basic">
package javax.persistence;

@Target({Method, FIELD})
@Retention(RUNTIME)
public @interface Basic {
  FetchType fetch() default EAGER;
  boolean optional() default true;
}
</def>

</defun>

<defun title="@Column">

<p>Specifies the field's SQL column name as well as any CREATE TABLE
properties for auto generation.</p>

<deftable-childtags>
<tr><td>name<td>The SQL name of the column<td>the field name
<tr><td>unique<td>True for UNIQUE columns<td>false
<tr><td>nullable<td>False for IS NOT NULL columns<td>true
<tr><td>insertable<td>True if column is inserted on a <code>create</code> call<td>true
<tr><td>updatable<td>True if column is updated when the field is modified<td>false
<tr><td>columnDefinition<td>SQL to create the column in a CREATE TABLE<td>none
<tr><td>table<td>specified if column is stored in a secondary table<td>none
<tr><td>length<td>the default length for a VARCHAR for a CREATE TABLE<td>255
<tr><td>precision<td>the default length for a number definition for a CREATE TABLE<td>0
<tr><td>scale<td>the default length for a number definition for a CREATE TABLE<td>0
</deftable-childtags>

<example title="String property ">
@Entity
public class Course {
  @Basic
  @Column(unique=true,
          nullable=false,
          length=32)
  public String getName()

  ...
}
</example>

<def title="javax.persistence.Column">
@Target({Method, FIELD})
@Retention(RUNTIME)
public @interface Column {
  String name() default "";
  boolean unique() default false;
  boolean nullable() default true;
  boolean insertable() default true;
  boolean updateable() default true;
  String columnDefinition() default "";
  String table() default "";
  int length() default 255;
  int precision() default 0;
  int scale() default 0;
  boolean specified() default true;
}
</def>

</defun>

</section>

<section title="Primary Key Annotations">

<defun title="@Id">

<p>Marks a field as a primary key.  The <code>@Id</code>
may be used in combination with <code>@GeneratedValue</code> to specify a generator for automatic key generation when new
objects are created.</p>

<p>The default column name is "ID".</p>

<example title="automatic generation">
import javax.persistence.*;

@Entity
public class Course {
  @Id
  @Column(name="t_id")
  @GeneratedValue
  public long getId()

  ...
}
</example>

<def title="javax.persistence.Id">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Id {
}
</def>

</defun>

<defun title="@GeneratedValue">

<p>Used with @Id to specify a generator for automatic key generation when new
objects are created.</p>

<deftable-childtags>
<tr><td>strategy<td>The auto-generation type<td>AUTO
<tr><td>generator<td>The sequence or table generator name<td>\${table}_cseq
</deftable-childtags>

<p>The generator types are:
<ul>
<li>IDENTITY - the database supplies the new key, e.g. auto_increment, SERIAL, or IDENTITY
<li>SEQUENCE - use a SEQUENCE type to generate the key
<li>TABLE - use a @TableGenerator for the key
<li>AUTO - choose the generator based on the database
<ul>
<li>MySQL - IDENTITY using auto_increment
<li>Resin - IDENTITY using auto_increment
<li>Postgres - SEQUENCE
<li>Oracle - SEQUENCE
</ul>
</ul>

<p>For SEQUENCE and TABLE, Resin will create the sequence
name as "\${table}_cseq".</p>

<example title="automatic generation">
import javax.persistence.*;

@Entity
public class Course {
  @Id
  @GeneratedValue
  public long getId()

  ...
}
</example>

<example title="sequence generation">
import javax.persistence.*;

@Entity
public class Course {
  @Id
  @GeneratedValue(strategy=GeneratorType.AUTO
                  generator="COURSE_SEQ")
  public long getId()

  ...
}
</example>

<def title="javax.persistence.GeneratedValue">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface GeneratedValue {
  GenerationType strategy() default AUTO;
  String generator() default "";
}
</def>

</defun>

</section>

<section title="Relation annotations">

<defun title="@JoinTable">

<p>Defines an association table for a many-to-many relation.</p>

<deftable-childtags>
<tr><td>name<td>Table definition for the association table<td>concatening the source and target table names
<tr><td>catalog<td>Database catalog<td>""
<tr><td>schema<td>Database schema<td>""
<tr><td>joinColumns<td>Columns from from the association table to the source table<td>Uses the source table primary key
<tr><td>inverseJoinColumns<td>Columns from from the association table to the target table<td>Uses the target table primary key
</deftable-childtags>

<def title="javax.persistence.JoinTable">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinTable {
  String table() default "";
  String catalog() default "";
  String schema() default "";
  JoinColumn []joinColumns() default {};
  JoinColumn []inverseJoinColumns() default {};
  UniqueContraint []uniqueConstraint() default {};
}
</def>

</defun>

<defun title="@JoinColumn">

<p>Defines a join (foreign) columns.  Used for <a href="#@ManyToOne">@ManyToOne</a>.</p>

<p>See also <a href="#@Column">@Column</a> for
corresponding definition for <a href="#@Basic">@Basic</a> columns.</p>

<p>See the <a href="tutorial/cmp-many2one/index.xtp">Many-to-One
tutorial</a> for a full example.</p>

<deftable-childtags>
<tr><td>name<td>The column name of the source table<td>the column name of the target key
<tr><td>referencedColumnName<td>The target column for composite keys<td>the single primary key
<tr><td>unique<td>True if unique<td>false
<tr><td>nullable<td>False if IS NOT NULL<td>true
<tr><td>insertable<td>True if the column is inserted on a <code>create</code><td>true
<tr><td>updateable<td>True if the column is updated on field changes<td>true
<tr><td>columnDefinition<td>SQL column definition<td>false
<tr><td>table<td>specifies a secondary table if not in the primary<td>none
</deftable-childtags>

<example title="Student to House link">
public class Student {
  @Id
  @Column(name="student_id")
  long getId()

  @ManyToOne
  @JoinColumn(name="house_id")
  public House getHouse()
}
</example>

<example title="Student SQL">
CREATE TABLE Student {
  student_id BIGINT PRIMARY KEY auto_increment

  house_id BIGINT REFERENCES House(id)
)
</example>

<def title="javax.persistence.JoinColumn">
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinColumn {
  String name() default "";
  String referencedColumnName() default "";
  boolean unique() default false;
  boolean nullable() default false;
  boolean insertable() default true;
  boolean updateable() default true;
  String columnDefinition() default "";
  String table() default "";
}
</def>

</defun>

<defun title="@JoinColumns">

<p>Defines a set of join (foreign) columns for composite keys.</p>

<def title="javax.persistence.ManyToOne">
@Target({TYPE,METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinColumns {
  JoinColumn [] value() default{}
}
</def>

</defun>

<defun title="@ManyToMany">

<p>Marks a field as a many-to-many (association) relation.</p>

<p>The column names are the key columns of the source and target tables.</p>

<p>See the <a href="tutorial/cmp-many2many/index.xtp">many-to-many tutorial</a> for an example.</p>

<deftable-childtags>
<tr><td>targetEntity<td>The class of the target entity<td>the property's type
<tr><td>cascade<td>Operations which cascade to the target<td>none
<tr><td>fetch<td>EAGER or LAZY fetching<td>FetchType.EAGER
<tr><td>mappedBy<td>Specifies the source relation if a target<td>
</deftable-childtags>

<example title="Simple link ">
@Entity
public class Student {
  @ManyToMany
  @JoinTable(
    name="student_course_map",
    joinColumns={@JoinColumn(name="student_id")},
    inverseJoinColumns={@JoinColumn(name="course_id")}
  )
  public Collection getCourses()

  ...
}
</example>

<def title="javax.persistence.ManyToMany">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface ManyToMany {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default LAZY;
  String mappedBy isInverse() default "";
}
</def>

</defun>

<defun title="@ManyToOne">

<p>Marks a field as a many-to-one (link) relation.</p>

<p>The default column name is the column name of the target key.</p>

<p>See the <a href="tutorial/cmp-many2one/index.xtp">many-to-one tutorial</a> for an example.</p>

<deftable-childtags>
<tr><td>targetEntity<td>The class of the target entity<td>the property's type
<tr><td>cascade<td>Operations which cascade to the target<td>none
<tr><td>fetch<td>EAGER or LAZY fetching<td>FetchType.EAGER
<tr><td>optional<td>If false, the relation must always have a value<td>true
</deftable-childtags>

<example title="Simple link ">
@Entity
public class Student {
  @ManyToOne
  @JoinColumn(name="house")
  public House getHouse()

  ...
}
</example>

<def title="javax.persistence.ManyToOne">
@Target({Method, FIELD})
@Retention(RUNTIME)
public @interface ManyToOne {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default EAGER;
  boolean optional() default true;
}
</def>

</defun>

<defun title="@OneToMany">

<p>Marks a field as a one-to-many (collection) relation.
Because a one-to-many field is dependent, it
needs a @ManyToOne relation on the source table which defines the column.</p>

<deftable-childtags>
<tr><td>targetEntity<td>The class of the target entity<td>the property's type
<tr><td>cascade<td>Operations which cascade to the target<td>none
<tr><td>fetch<td>EAGER or LAZY fetching<td>FetchType.EAGER
<tr><td>mappedBy<td>Specifies the owning @ManyToOne property<td>
</deftable-childtags>

<example title="Collection java">
@Entity
public class House {
  ...
  @OneToMany(targetEntity=Student.class,
             mappedBy="house")
  public Collection getStudents()
}

@Entity
public class Student {
  ...
  @ManyToOne
  @JoinColumn(name="house")
  public House getHouse()
}
</example>

<example title="Collection SQL">
CREATE TABLE House {
  id BIGINT PRIMARY KEY
)

CREATE TABLE Student {
  id BIGINT PRIMARY KEY,

  house BIGINT REFERENCES House(id)
)
</example>

<def title="javax.persistence.OneToMany">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OneToMany {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default EAGER;
  String mappedBy() default "";
}
</def>

</defun>

<defun title="@OneToOne">

<p>Marks a field as a one-to-one (dependent link) relation.
Because a one-to-one field is dependent, it
needs a @ManyToOne relation on the source table which defines the column.</p>

<deftable-childtags>
<tr><td>targetEntity<td>The class of the target entity<td>the property's type
<tr><td>cascade<td>Operations which cascade to the target<td>none
<tr><td>fetch<td>EAGER or LAZY fetching<td>FetchType.EAGER
<tr><td>mappedBy<td>Specifies the owning relation<td>
</deftable-childtags>

<def title="javax.persistence.OneToOne">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OneToOne {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default EAGER;
  boolean optional() default true;
  String mappedBy() default "";
}
</def>

</defun>

</section>

<section title="Inheritance annotations">

<defun title="@DiscriminatorColumn">

<p>Configures the discriminator column.</p>

<def title="javax.persistence.DiscriminatorColumn">
@Target(TYPE)
@Retention(RUNTIME)
public @interface DiscriminatorColumn {
  String name() default "";
  DiscriminatorType discriminatorType() default STRING;
  String columnDefinition() default "";
  int length() default 31;
}
</def>

</defun>

<defun title="@Inheritance">

<p>@Inheritance marks the entity bean as supporting inheritance,
i.e. the database maps to different Java classes depending on
a discriminator value.</p>

<def title="javax.persistence.Inheritance">
@Target(TYPE)
@Retention(RUNTIME)
public @interface Inheritance {
  InteritanceType strategy() default SINGLE_TABLE;
}
</def>

</defun>

<defun title="InheritanceType">

<def title="javax.persistence.InheritanceType">
public enum InheritanceType {
  SINGLE_TABLE,
  JOINED,
  TABLE_PER_CLASS
}
</def>

</defun>

</section>

</document>
