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.RetentionPolicy.RUNTIME;
017import static javax.persistence.FetchType.EAGER;
018
019/**
020 * Defines a single-valued association to another entity that has one-to-one multiplicity. It is not normally
021 * necessary to specify the associated target entity explicitly since it can usually be inferred from the type
022 * of the object being referenced. If the relationship is bidirectional, the non-owning side must use the
023 * <code>mappedBy</code> element of the <code>OneToOne</code> annotation to specify the relationship field or
024 * property of the owning side.
025 * <p>
026 * The <code>OneToOne</code> annotation may be used within an embeddable class to specify a relationship from
027 * the embeddable class to an entity class. If the relationship is bidirectional and the entity containing the
028 * embeddable class is on the owning side of the relationship, the non-owning side must use the
029 * <code>mappedBy</code> element of the <code>OneToOne</code> annotation to specify the relationship field or
030 * property of the embeddable class. The dot (".") notation syntax must be used in the <code>mappedBy</code>
031 * element to indicate the relationship attribute within the embedded attribute. The value of each identifier
032 * used with the dot notation is the name of the respective embedded field or property.
033 * <p>
034 * <pre>
035 *    Example 1: One-to-one association that maps a foreign key column
036 *
037 *    // On Customer class:
038 *
039 *    &#064;OneToOne(optional=false)
040 *    &#064;JoinColumn(
041 *      name="CUSTREC_ID", unique=true, nullable=false, updatable=false)
042 *    CustomerRecord customerRecord;
043 *
044 *    // On CustomerRecord class:
045 *
046 *    &#064;OneToOne(optional=false, mappedBy="customerRecord")
047 *    Customer customer;
048 *
049 *
050 *    Example 2: One-to-one association that assumes both the source and target share the same primary key values.
051 *
052 *    // On Employee class:
053 *
054 *    &#064;Entity
055 *    public class Employee {
056 *      &#064;Id Integer id;
057 *
058 *      &#064;OneToOne &#064;MapsId
059 *      EmployeeInfo info;
060 *      ...
061 *    }
062 *
063 *    // On EmployeeInfo class:
064 *
065 *    &#064;Entity
066 *    public class EmployeeInfo {
067 *      &#064;Id Integer id;
068 *      ...
069 *    }
070 *
071 *
072 *    Example 3: One-to-one association from an embeddable class to another entity.
073 *
074 *    &#064;Entity
075 *    public class Employee {
076 *       &#064;Id int id;
077 *       &#064;Embedded LocationDetails location;
078 *       ...
079 *    }
080 *
081 *    &#064;Embeddable
082 *    public class LocationDetails {
083 *       int officeNumber;
084 *       &#064;OneToOne ParkingSpot parkingSpot;
085 *       ...
086 *    }
087 *
088 *    &#064;Entity
089 *    public class ParkingSpot {
090 *       &#064;Id int id;
091 *       String garage;
092 *       &#064;OneToOne(mappedBy="location.parkingSpot") Employee assignedTo;
093 *        ...
094 *    }
095 *
096 * </pre>
097 *
098 * @since Java Persistence 1.0
099 */
100@Target({FIELD})
101@Retention(RUNTIME)
102public @interface OneToOne {
103
104  /**
105   * (Optional) The entity class that is the target of the association.
106   * <p>
107   * Defaults to the type of the field or property that stores the association.
108   *
109   * @return target entity
110   */
111  Class targetEntity() default void.class;
112
113  /**
114   * (Optional) The operations that must be cascaded to the target of the association.
115   * <p>
116   * By default no operations are cascaded.
117   *
118   * @return cascade type
119   */
120  CascadeType[] cascade() default {};
121
122  /**
123   * (Optional) Whether the association should be lazily loaded or must be eagerly fetched. The EAGER
124   * strategy is a requirement on the persistence provider runtime that the associated entity must be
125   * eagerly fetched. The LAZY strategy is a hint to the persistence provider runtime.
126   *
127   * @return fetch type
128   */
129  FetchType fetch() default EAGER;
130
131  /**
132   * (Optional) Whether the association is optional. If set to false then a non-null relationship must
133   * always exist.
134   *
135   * @return optional?
136   */
137  boolean optional() default true;
138
139  /**
140   * (Optional) The field that owns the relationship. This element is only specified on the inverse
141   * (non-owning) side of the association.
142   *
143   * @return mappedby
144   */
145  String mappedBy() default "";
146
147  /**
148   * (Optional) Whether to apply the remove operation to entities that have been removed from the
149   * relationship and to cascade the remove operation to those entities.
150   *
151   * @return whether to remove orphans
152   * @since Java Persistence 2.0
153   */
154  boolean orphanRemoval() default false;
155}