Annotation Interface OneToMany

@Target({METHOD,FIELD}) @Retention(RUNTIME) public @interface OneToMany
Specifies a many-valued association to another entity class that has one-to-many multiplicity. If the target entity class cannot be inferred from the type arguments of the declared type of the annotated field or property, then targetEntity() must be explicitly specified.

A OneToMany association usually maps a foreign key column or columns in the table of the associated entity. This mapping may be specified using the JoinColumn annotation. 

@OneToMany
@JoinColumn(name = "ORD_ID)
Set<Order> orders;

Alternatively, a unidirectional OneToMany association is sometimes mapped to a join table using the JoinTable annotation. 

@OneToMany
@JoinTable(name = "CUSTOMER_ORDERS",
           joinColumns = @JoinColumn("CUST_ID"),
           inverseJoinColumns = @JoinColumn("ORD_ID"))
Set<Order> orders;

The annotated field or property usually represents one side of a bidirectional association. Every bidirectional association has an owning side and an inverse (alternatively, non-owning or unowned) side. Modifications to the owning side of an association determine the updates made to the relationship in the database. If the inverse side of an association is modified without a corresponding modification to the owning side, the behavior is undefined. The persistence provider is permitted to ignore any modification made only to the inverse side of a bidirectional association.

In a bidirectional association, a OneToMany must be the inverse side. The owning side of a bidirectional one-to-many association must be a field or property annotated @ManyToOne of the target entity, and the non-owning OneToMany side must specify the relationship field or property annotated @ManyToOne via mappedBy(). The foreign key or join table must be specified on the owning side. 

@Entity
public class Customer {
    @Id
    @GeneratedValue
    long id;

    // inverse (unowned) side
    @OneToMany(cascade = ALL,
               orphanRemoval = true,
               mappedBy = Order_.CUSTOMER)
    @OrderBy
    List<Order> orders;
    ...
}

@Entity
public class Order {
    @Id
    @GeneratedValue
    long id;

    // owning side
    @ManyToOne(optional = false,
               fetch = LAZY)
    @JoinColumn(name = "CUST_ID")
    Customer customer;
    ...
}

The OneToMany annotation may be used within an embeddable class contained within an entity class to specify a relationship to a collection of entities. If the relationship is bidirectional, the mappedBy() element must be used to specify the relationship field or property of the entity that is the owner of the relationship.

When the collection is a Map, the cascade() element and the orphanRemoval() element apply to the map value.

Since:
1.0
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    CascadeType[]
    cascade
    (Optional) The operations that must be cascaded to the target of the association.
    FetchType
    fetch
    (Optional) Whether the association should be lazily loaded or must be eagerly fetched.
    String
    mappedBy
    The field or property of the target entity that owns the relationship and specifies its mapping to the database.
    boolean
    orphanRemoval
    (Optional) Whether to apply the remove operation to entities that have been removed from the relationship and to cascade the remove operation to those entities.
    Class<?>
    targetEntity
    (Optional) The entity class that is the target of the association.

  • Element Details

    • targetEntity

      Class<?> targetEntity
      (Optional) The entity class that is the target of the association. Required if the target entity type cannot be inferred from the declared type of the annotated field or property, for example, if the declared type is a raw collection type.

      Defaults to the type argument of the collection type when the declared type of the annotated field or property is a non-raw collection type.

      Default:
      void.class

    • cascade

      CascadeType[] cascade
      (Optional) The operations that must be cascaded to the target of the association.

      By default, no operations are cascaded.

      When the target collection is a Map, the cascade element applies to the map value.

      Default:
      {}

    • fetch

      FetchType fetch
      (Optional) Whether the association should be lazily loaded or must be eagerly fetched.
      • The EAGER policy is a requirement on the persistence provider runtime that the associated entity must be eagerly fetched.
      • The LAZY policy is a hint to the persistence provider runtime.

      If not specified, defaults to LAZY.

      Default:
      LAZY

    • mappedBy

      String mappedBy
      The field or property of the target entity that owns the relationship and specifies its mapping to the database. Required unless the relationship is unidirectional.

      The static metamodel of the target entity may be used to obtain a reference to the owning side, for example, mappedBy = Order_.CUSTOMER.

      Default:
      ""

    • orphanRemoval

      boolean orphanRemoval
      (Optional) Whether to apply the remove operation to entities that have been removed from the relationship and to cascade the remove operation to those entities.
      Since:
      2.0
      Default:
      false