Enterprise JavaBeans 3.1, 6th Edition

Mapping Collection-Based Relationships

The one-to-many and many-to-many examples we’ve seen so far have used the java.util.Collection and java.util.Set types. The Java Persistence specification also allows you to represent a relationship with a java.util.List or a java.util.Map.

Ordered List-Based Relationship

The java.util.List interface can express collection-based relationships. You do not need any special metadata if you want to use a List rather than a Set or Collection type. (In this case, the List actually gives you a bag semantic, an unordered collection that allows duplicates). A List type can give you the additional ability to order the returned relationship based on a specific set of criteria. This requires the additional metadata provided by the @javax.persistence.OrderBy annotation:

package javax.persistence;

@Target({METHOD, FIELD}) @Retention(RUNTIME)
public @interface OrderBy
{
   String value( ) default "";
}

The value() attribute allows you to declare partial JPA QL that specifies how you want the relationship to be ordered when it is fetched from the database. If the value() attribute is left empty, the List is sorted in ascending order based on the value of the primary key.

Let’s take the Employee/Team relationship, which is a many-to-many bidirectional relationship, and have the teams attribute of Employee return a List that is sorted alphabetically by the Team entity’s name:

@Entity
public class Employee
{
    ...
    @ManyToMany
    @OrderBy("name ASC") private List<Team> teams; ...