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.EAGER;
019
020/**
021 * Defines a single-valued association to another entity class that has many-to-one multiplicity. It is not
022 * normally necessary to specify the target entity explicitly since it can usually be inferred from the type
023 * of the object being referenced. If the relationship is bidirectional, the non-owning <code>OneToMany</code>
024 * entity side must used the <code>mappedBy</code> element to specify the relationship field or property of
025 * the entity that is the owner of the relationship.
026 * <p>
027 * The <code>ManyToOne</code> annotation may be used within an embeddable class to specify a relationship from
028 * the embeddable class to an entity class. If the relationship is bidirectional, the non-owning
029 * <code>OneToMany</code> entity side must use the <code>mappedBy</code> element of the <code>OneToMany</code>
030 * annotation to specify the relationship field or property of the embeddable field or property on the owning
031 * side of the relationship. The dot (".") notation syntax must be used in the <code>mappedBy</code> element
032 * to indicate the relationship attribute within the embedded attribute. The value of each identifier used
033 * with the dot notation is the name of the respective embedded field or property.
034 * <p>
035 * <pre>
036 *
037 *     Example 1:
038 *
039 *     &#064;ManyToOne(optional=false)
040 *     &#064;JoinColumn(name="CUST_ID", nullable=false, updatable=false)
041 *     public Customer getCustomer() { return customer; }
042 *
043 *
044 *     Example 2:
045 *
046 *     &#064;Entity
047 *        public class Employee {
048 *        &#064;Id int id;
049 *        &#064;Embedded JobInfo jobInfo;
050 *        ...
051 *     }
052 *
053 *     &#064;Embeddable
054 *        public class JobInfo {
055 *        String jobDescription;
056 *        &#064;ManyToOne ProgramManager pm; // Bidirectional
057 *     }
058 *
059 *     &#064;Entity
060 *        public class ProgramManager {
061 *        &#064;Id int id;
062 *        &#064;OneToMany(mappedBy="jobInfo.pm")
063 *        Collection&#060;Employee&#062; manages;
064 *     }
065 *
066 * </pre>
067 *
068 * @since Java Persistence 1.0
069 */
070@Target({METHOD, FIELD})
071@Retention(RUNTIME)
072public @interface ManyToOne {
073
074  /**
075   * (Optional) The entity class that is the target of the association.
076   * <p>
077   * Defaults to the type of the field or property that stores the association.
078   *
079   * @return The target entity
080   */
081  Class targetEntity() default void.class;
082
083  /**
084   * (Optional) The operations that must be cascaded to the target of the association.
085   * <p>
086   * By default no operations are cascaded.
087   *
088   * @return The cascade type
089   */
090  CascadeType[] cascade() default {};
091
092  /**
093   * (Optional) Whether the association should be lazily loaded or must be eagerly fetched. The EAGER
094   * strategy is a requirement on the persistence provider runtime that the associated entity must be
095   * eagerly fetched. The LAZY strategy is a hint to the persistence provider runtime.
096   *
097   * @return The fetch type
098   */
099  FetchType fetch() default EAGER;
100
101  /**
102   * (Optional) Whether the association is optional. If set to false then a non-null relationship must
103   * always exist.
104   *
105   * @return Whether this is optional
106   */
107  boolean optional() default true;
108}