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