Package: Entity

Entity

Coverage

1: /*
2: * Copyright (c) 2008, 2023 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Public License v. 2.0 which is available at
6: * http://www.eclipse.org/legal/epl-2.0,
7: * or the Eclipse Distribution License v. 1.0 which is available at
8: * http://www.eclipse.org/org/documents/edl-v10.php.
9: *
10: * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
11: */
12:
13: // Contributors:
14: // Linda DeMichiel - 2.1
15: // Linda DeMichiel - 2.0
16:
17: package jakarta.persistence;
18:
19: import java.lang.annotation.Target;
20: import java.lang.annotation.Retention;
21: import java.lang.annotation.Documented;
22: import static java.lang.annotation.ElementType.TYPE;
23: import static java.lang.annotation.RetentionPolicy.RUNTIME;
24:
25: /**
26: * Declares that the annotated class is an entity. The annotated entity
27: * class must:
28: * <ul>
29: * <li>be a non-{@code final} top-level class or static inner class,
30: * <li>have a {@code public} or {@code protected} constructor with no
31: * parameters, and
32: * <li>have no {@code final} methods or persistent instance variables.
33: * </ul>
34: * <p>An enum, record, or interface may not be designated as an entity.
35: *
36: * <p>An entity has a primary table, mapped using the {@link Table}
37: * annotation, and may have one or more secondary tables, mapped using
38: * the {@link SecondaryTable} annotation.
39: *
40: * <p>An entity class holds state, represented as persistent fields and
41: * properties:
42: * <ul>
43: * <li>a field or property of {@linkplain Basic basic type} maps to a
44: * single {@linkplain Column column} in one of the tables mapped
45: * by the entity,
46: * <li>a field of property of {@linkplain Embedded embeddable type}
47: * has nested mappings to multiple columns in one of the tables
48: * mapped by the entity,
49: * <li>an {@linkplain ElementCollection element collection} usually
50: * maps to a separate {@linkplain CollectionTable collection table},
51: * <li>a {@linkplain ManyToOne many-to-one} association usually maps
52: * to a {@linkplain JoinColumn foreign key column} or columns in
53: * one of the tables mapped by the entity,
54: * <li>a {@linkplain OneToOne one-to-one} association usually maps
55: * to a unique foreign key relationship (sometimes using a shared
56: * primary key),
57: * <li>a {@linkplain OneToMany one-to-many} association usually maps
58: * to a foreign key column or columns in one of the tables mapped
59: * by the <em>associated entity</em>, and
60: * <li>a {@linkplain ManyToMany many-to-many} association usually maps
61: * to a {@linkplain JoinTable join table}.
62: * </ul>
63: *
64: * <p>Every entity class must have at least one field or property
65: * annotated {@link Id} or {@link EmbeddedId} holding the primary key
66: * of the entity. An entity class may optionally have a field or
67: * property annotated {@link Version}, which holds a value used to
68: * detect optimistic lock failure.
69: *
70: * <p>Fields or properties of an entity class are persistent by default.
71: * The {@link Transient} annotation or the Java {@code transient} keyword
72: * must be used to explicitly declare any field or property of an entity
73: * which is <em>not</em> persistent.
74: *
75: * <p>The entity {@linkplain AccessType access type} determines whether
76: * the persistence provider accesses the state of the entity using getter
77: * and setter methods, or via direct field access. It is almost never
78: * necessary to explicitly specify an {@link AccessType}, since the
79: * default access type for an entity is determined by the placement of
80: * mapping annotations on the entity class.
81: *
82: * <p>Apart from its persistent fields and properties, an entity class
83: * may declare callback methods using {@link PrePersist}, {@link PreUpdate},
84: * {@link PreRemove}, {@link PostPersist}, {@link PostUpdate}, and/or
85: * {@link PostRemove}.
86: *
87: * @since 1.0
88: */
89: @Documented
90: @Target(TYPE)
91: @Retention(RUNTIME)
92: public @interface Entity {
93:
94:         /**
95:          * (Optional) The entity name. Defaults to the unqualified
96:          * name of the entity class. This name is used to refer to the
97:          * entity in queries. The name must not be a reserved literal
98:          * in the Jakarta Persistence query language.
99:          */
100:         String name() default "";
101: }