Annotates the class as an entity bean.

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

Attribute	Meaning	default
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 ""; }

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

Attribute	Meaning	default
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 {}; }

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

Attribute	Meaning	default
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 {}; }

Marks a field as a persistent field.

Attribute	Meaning	default
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; }

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

Attribute	Meaning	default
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; }

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

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

Attribute	Meaning	default
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 ""; }

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

Attribute	Meaning	default
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 {}; }

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.

Attribute	Meaning	default
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 ""; }

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

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

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.

Attribute	Meaning	default
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 ""; }

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.

Attribute	Meaning	default
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; }

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.

Attribute	Meaning	default
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 ""; }

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.

Attribute	Meaning	default
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 ""; }

Configures the discriminator column.

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

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

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