@Entity Table Configuration

Overview
Installation
Configuration
Quercus
SOA/IoC
JSP
Servlets and Filters
Admin (JMX)
EJB
Amber
Security
Performance
Hessian
XML and XSLT
Third-party
Troubleshooting/FAQ

Amber
Lifecycle
@Table

Lifecycle

Amber

Security

Describes the basic annotation for a single-table entity bean.

Table annotations

@Entity

Annotates the class as an entity bean.

See the basic property tutorial and the basic field tutorial for an introduction.

name

The name of the bean

The class name (unqualified)

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.


package javax.persistence;

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

@SecondaryTable

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

name	The name of the table	The unqualified class name.
catalog	the table's catalog	none
schema	the table's schema	none
pkJoinColumns	join column to the primary table	joins the primary key
uniqueConstraint	unique constraints during generation	none


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 {};
}

@Table

Specifies the database table for an entity bean. The default table name is the class name.

name	The name of the table	The unqualified class name.
catalog	the table's catalog	none
schema	the table's schema	none
uniqueConstraint	unique constraints during generation	none


package javax.persistence;

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

Property Annotations

@Basic

Marks a field as a persistent field.

fetch	EAGER or LAZY fetching	FetchType.EAGER
optional	if true, the column may be null	true

The fetch types are:

EAGER - fetch the field when the bean is loaded
LAZY - fetch the field only when the field is used

String property

@Entity
public class Course {
  @Basic
  public String getName()

  ...
}

Lazy-loaded property

@Entity
public class Course {
  @Basic(fetch=FetchType.LAZY)
  public String getMassiveText()

  ...
}

javax.persistence.Basic
package javax.persistence; @Target({Method, FIELD}) @Retention(RUNTIME) public @interface Basic { FetchType fetch() default EAGER; boolean optional() default true; }

@Column

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

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

String property

@Entity
public class Course {
  @Basic
  @Column(unique=true,
          nullable=false,
          length=32)
  public String getName()

  ...
}

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;
}

Primary Key Annotations

@Id

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

The default column name is "ID".

automatic generation

import javax.persistence.*;

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

  ...
}

javax.persistence.Id
@Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface Id { }

@GeneratedValue

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

strategy	The auto-generation type	AUTO
generator	The sequence or table generator name	\${table}_cseq

The generator types are:

IDENTITY - the database supplies the new key, e.g. auto_increment, SERIAL, or IDENTITY
SEQUENCE - use a SEQUENCE type to generate the key
TABLE - use a @TableGenerator for the key
AUTO - choose the generator based on the database
- MySQL - IDENTITY using auto_increment
- Resin - IDENTITY using auto_increment
- Postgres - SEQUENCE
- Oracle - SEQUENCE

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

automatic generation

import javax.persistence.*;

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

  ...
}

sequence generation

import javax.persistence.*;

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

  ...
}

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

Relation annotations

@JoinTable

Defines an association table for a many-to-many relation.

name	Table definition for the association table	concatening the source and target table names
catalog	Database catalog	""
schema	Database schema	""
joinColumns	Columns from from the association table to the source table	Uses the source table primary key
inverseJoinColumns	Columns from from the association table to the target table	Uses the target table primary key

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 {};
}

@JoinColumn

Defines a join (foreign) columns. Used for @ManyToOne.

See also @Column for corresponding definition for @Basic columns.

See the Many-to-One tutorial for a full example.

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

Student to House link

public class Student {
  @Id
  @Column(name="student_id")
  long getId()

  @ManyToOne
  @JoinColumn(name="house_id")
  public House getHouse()
}

Student SQL

CREATE TABLE Student {
  student_id BIGINT PRIMARY KEY auto_increment

  house_id BIGINT REFERENCES House(id)
)

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 "";
}

@JoinColumns

Defines a set of join (foreign) columns for composite keys.

javax.persistence.ManyToOne
@Target({TYPE,METHOD, FIELD}) @Retention(RUNTIME) public @interface JoinColumns { JoinColumn [] value() default{} }

@ManyToMany

Marks a field as a many-to-many (association) relation.

The column names are the key columns of the source and target tables.

See the many-to-many tutorial for an example.

targetEntity	The class of the target entity	the property's type
cascade	Operations which cascade to the target	none
fetch	EAGER or LAZY fetching	FetchType.EAGER
mappedBy	Specifies the source relation if a target

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()

  ...
}

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 "";
}

@ManyToOne

Marks a field as a many-to-one (link) relation.

The default column name is the column name of the target key.

See the many-to-one tutorial for an example.

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

Simple link

@Entity
public class Student {
  @ManyToOne
  @JoinColumn(name="house")
  public House getHouse()

  ...
}

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;
}

@OneToMany

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.

targetEntity	The class of the target entity	the property's type
cascade	Operations which cascade to the target	none
fetch	EAGER or LAZY fetching	FetchType.EAGER
mappedBy	Specifies the owning @ManyToOne property

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()
}

Collection SQL

CREATE TABLE House {
  id BIGINT PRIMARY KEY
)

CREATE TABLE Student {
  id BIGINT PRIMARY KEY,

  house BIGINT REFERENCES House(id)
)

javax.persistence.OneToMany


@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OneToMany {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default EAGER;
  String mappedBy() default "";
}

@OneToOne

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.

targetEntity	The class of the target entity	the property's type
cascade	Operations which cascade to the target	none
fetch	EAGER or LAZY fetching	FetchType.EAGER
mappedBy	Specifies the owning relation

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 "";
}

Inheritance annotations

@DiscriminatorColumn

Configures the discriminator column.

javax.persistence.DiscriminatorColumn


@Target(TYPE)
@Retention(RUNTIME)
public @interface DiscriminatorColumn {
  String name() default "";
  DiscriminatorType discriminatorType() default STRING;
  String columnDefinition() default "";
  int length() default 31;
}

@Inheritance

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

javax.persistence.Inheritance
@Target(TYPE) @Retention(RUNTIME) public @interface Inheritance { InteritanceType strategy() default SINGLE_TABLE; }

InheritanceType

javax.persistence.InheritanceType
public enum InheritanceType { SINGLE_TABLE, JOINED, TABLE_PER_CLASS }