001/*
002 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
003 *
004 * This program and the accompanying materials are made available under the
005 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
006 * which accompanies this distribution.  The Eclipse Public License is available
007 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
008 * is available at http://www.eclipse.org/org/documents/edl-v10.php.
009 */
010package javax.persistence;
011
012import java.lang.annotation.Retention;
013import java.lang.annotation.Target;
014
015import static java.lang.annotation.ElementType.FIELD;
016import static java.lang.annotation.ElementType.METHOD;
017import static java.lang.annotation.RetentionPolicy.RUNTIME;
018import static javax.persistence.FetchType.LAZY;
019
020/**
021 * Defines a many-valued association with many-to-many multiplicity.
022 * <p>
023 * Every many-to-many association has two sides, the owning side and the non-owning, or inverse, side. The
024 * join table is specified on the owning side. If the association is bidirectional, either side may be
025 * designated as the owning side. If the relationship is bidirectional, the non-owning side must use the
026 * <code>mappedBy</code> element of the <code>ManyToMany</code> annotation to specify the relationship field
027 * or property of the owning side.
028 * <p>
029 * The join table for the relationship, if not defaulted, is specified on the owning side.
030 * <p>
031 * The <code>ManyToMany</code> annotation may be used within an embeddable class contained within an entity
032 * class to specify a relationship to a collection of entities. If the relationship is bidirectional and the
033 * entity containing the embeddable class is the owner of the relationship, the non-owning side must use the
034 * <code>mappedBy</code> element of the <code>ManyToMany</code> annotation to specify the relationship field
035 * or property of the embeddable class. The dot (".") notation syntax must be used in the
036 * <code>mappedBy</code> element to indicate the relationship attribute within the embedded attribute. The
037 * value of each identifier used with the dot notation is the name of the respective embedded field or
038 * property.
039 * <p>
040 * <pre>
041 *
042 *    Example 1:
043 *
044 *    // In Customer class:
045 *
046 *    &#064;ManyToMany
047 *    &#064;JoinTable(name="CUST_PHONES")
048 *    public Set&#060;PhoneNumber&#062; getPhones() { return phones; }
049 *
050 *    // In PhoneNumber class:
051 *
052 *    &#064;ManyToMany(mappedBy="phones")
053 *    public Set&#060;Customer&#062; getCustomers() { return customers; }
054 *
055 *    Example 2:
056 *
057 *    // In Customer class:
058 *
059 *    &#064;ManyToMany(targetEntity=com.acme.PhoneNumber.class)
060 *    public Set getPhones() { return phones; }
061 *
062 *    // In PhoneNumber class:
063 *
064 *    &#064;ManyToMany(targetEntity=com.acme.Customer.class, mappedBy="phones")
065 *    public Set getCustomers() { return customers; }
066 *
067 *    Example 3:
068 *
069 *    // In Customer class:
070 *
071 *    &#064;ManyToMany
072 *    &#064;JoinTable(name="CUST_PHONE",
073 *        joinColumns=
074 *            &#064;JoinColumn(name="CUST_ID", referencedColumnName="ID"),
075 *        inverseJoinColumns=
076 *            &#064;JoinColumn(name="PHONE_ID", referencedColumnName="ID")
077 *        )
078 *    public Set&#060;PhoneNumber&#062; getPhones() { return phones; }
079 *
080 *    // In PhoneNumberClass:
081 *
082 *    &#064;ManyToMany(mappedBy="phones")
083 *    public Set&#060;Customer&#062; getCustomers() { return customers; }
084 * </pre>
085 *
086 * @see JoinTable
087 * @since Java Persistence 1.0
088 */
089@Target({METHOD, FIELD})
090@Retention(RUNTIME)
091public @interface ManyToMany {
092
093  /**
094   * (Optional) The entity class that is the target of the association. Optional only if the
095   * collection-valued relationship property is defined using Java generics. Must be specified otherwise.
096   * <p>
097   * Defaults to the parameterized type of the collection when defined using generics.
098   *
099   * @return The target entity
100   */
101  Class targetEntity() default void.class;
102
103  /**
104   * (Optional) The operations that must be cascaded to the target of the association.
105   * <p>
106   * When the target collection is a {@link java.util.Map java.util.Map}, the <code>cascade</code> element
107   * applies to the map value.
108   * <p>
109   * Defaults to no operations being cascaded.
110   *
111   * @return The cascade type
112   */
113  CascadeType[] cascade() default {};
114
115  /**
116   * (Optional) Whether the association should be lazily loaded or must be eagerly fetched. The EAGER
117   * strategy is a requirement on the persistence provider runtime that the associated entities must be
118   * eagerly fetched. The LAZY strategy is a hint to the persistence provider runtime.
119   *
120   * @return The fetch type
121   */
122  FetchType fetch() default LAZY;
123
124  /**
125   * The field that owns the relationship. Required unless the relationship is unidirectional.
126   *
127   * @return The mappedby
128   */
129  String mappedBy() default "";
130}