+ * Note that the name of this class is historical and unfortunate. An embeddable class holds a "component" + * of the state of an entity. It has absolutely nothing to do with modularity in software engineering. * * @author Gavin King * @author Steve Ebersole diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Constraint.java b/hibernate-core/src/main/java/org/hibernate/mapping/Constraint.java index feec32e0e1..8f1386e1ae 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Constraint.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Constraint.java @@ -26,7 +26,7 @@ import org.hibernate.engine.spi.Mapping; import static org.hibernate.internal.util.StringHelper.isEmpty; /** - * A constraint on a relational database table. + * A mapping model object representing a constraint on a relational database table. * * @author Gavin King * @author Brett Meyer diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/DependantValue.java b/hibernate-core/src/main/java/org/hibernate/mapping/DependantValue.java index 8b724920a2..bf1779dcfe 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/DependantValue.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/DependantValue.java @@ -11,14 +11,13 @@ import org.hibernate.boot.spi.MetadataBuildingContext; import org.hibernate.type.Type; /** - * A value which is "typed" by reference to some other - * value (for example, a foreign key is typed by the - * referenced primary key). + * A mapping model object representing a {@linkplain Value value} which is "typed" by reference + * to some other value (for example, a foreign key is typed by the referenced primary key). * * @author Gavin King */ public class DependantValue extends SimpleValue implements Resolvable, SortableValue { - private KeyValue wrappedValue; + private final KeyValue wrappedValue; private boolean nullable; private boolean updateable; private boolean sorted; diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java b/hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java index 9df1b15760..2a7d82e4e1 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java @@ -16,7 +16,7 @@ import org.hibernate.dialect.Dialect; import org.hibernate.internal.util.StringHelper; /** - * A foreign key constraint. + * A mapping model object representing a {@linkplain jakarta.persistence.ForeignKey foreign key} constraint. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Formula.java b/hibernate-core/src/main/java/org/hibernate/mapping/Formula.java index 16efcf67a9..fea982f7ba 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Formula.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Formula.java @@ -19,7 +19,9 @@ import org.hibernate.type.spi.TypeConfiguration; import static org.hibernate.internal.util.StringHelper.safeInterning; /** - * A formula is a derived column value + * A mapping model object representing a SQL {@linkplain org.hibernate.annotations.Formula formula} + * which is used as a "derived" {@link Column} in an entity mapping. + * * @author Gavin King */ public class Formula implements Selectable, Serializable { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/IdentifierBag.java b/hibernate-core/src/main/java/org/hibernate/mapping/IdentifierBag.java index 40adb5c093..fe530ea2ea 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/IdentifierBag.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/IdentifierBag.java @@ -15,8 +15,7 @@ import org.hibernate.type.IdentifierBagType; import org.hibernate.usertype.UserCollectionType; /** - * An {@code IdentifierBag} has a primary key consisting of - * just the identifier column + * A bag with a generated (surrogate) key. Its primary key is just the identifier column. */ public class IdentifierBag extends IdentifierCollection { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/IdentifierCollection.java b/hibernate-core/src/main/java/org/hibernate/mapping/IdentifierCollection.java index 846f1dae3a..553f09022e 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/IdentifierCollection.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/IdentifierCollection.java @@ -15,7 +15,8 @@ import org.hibernate.resource.beans.spi.ManagedBean; import org.hibernate.usertype.UserCollectionType; /** - * A collection with a synthetic "identifier" column + * A mapping model object representing a collection with a synthetic "identifier" column, + * that is, a surrogate key. */ public abstract class IdentifierCollection extends Collection { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Index.java b/hibernate-core/src/main/java/org/hibernate/mapping/Index.java index ee2ff44900..6e5e33978b 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Index.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Index.java @@ -26,7 +26,7 @@ import static org.hibernate.internal.util.StringHelper.isNotEmpty; import static org.hibernate.internal.util.StringHelper.qualify; /** - * A relational table index + * A mapping model object representing an {@linkplain jakarta.persistence.Index index} on a relational database table. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Join.java b/hibernate-core/src/main/java/org/hibernate/mapping/Join.java index 7ba5649de8..fe5ca485e0 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Join.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Join.java @@ -15,6 +15,12 @@ import org.hibernate.engine.spi.ExecuteUpdateResultCheckStyle; import org.hibernate.sql.Alias; /** + * A mapping model object representing some sort of auxiliary table, for + * example, an {@linkplain jakarta.persistence.JoinTable association table}, + * a {@linkplain jakarta.persistence.SecondaryTable secondary table}, or a + * table belonging to a {@linkplain jakarta.persistence.InheritanceType#JOINED + * joined subclass}. + * * @author Gavin King */ public class Join implements AttributeContainer, Serializable { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/JoinedSubclass.java b/hibernate-core/src/main/java/org/hibernate/mapping/JoinedSubclass.java index 72e5c01dd7..c3c627438a 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/JoinedSubclass.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/JoinedSubclass.java @@ -13,7 +13,10 @@ import org.hibernate.boot.Metadata; import org.hibernate.boot.spi.MetadataBuildingContext; /** - * A subclass in a table-per-subclass mapping + * A mapping model object that represents a subclass in a "joined" or + * {@linkplain jakarta.persistence.InheritanceType#JOINED "table per subclass"} + * inheritance hierarchy. + * * @author Gavin King */ public class JoinedSubclass extends Subclass implements TableOwner { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/KeyValue.java b/hibernate-core/src/main/java/org/hibernate/mapping/KeyValue.java index dc3c5329ae..dca3377aa0 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/KeyValue.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/KeyValue.java @@ -12,9 +12,11 @@ import org.hibernate.id.IdentifierGenerator; import org.hibernate.id.factory.IdentifierGeneratorFactory; /** - * Represents an identifying key of a table: the value for primary key - * of an entity, or a foreign key of a collection or join table or - * joined subclass table. + * A mapping model {@link Value} which may be treated as an identifying key of a + * relational database table. A {@code KeyValue} might represent the primary key + * of an entity or the foreign key of a collection, join table, secondary table, + * or joined subclass table. + * * @author Gavin King */ public interface KeyValue extends Value { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/List.java b/hibernate-core/src/main/java/org/hibernate/mapping/List.java index 9fc0eb2bda..8b641d70c6 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/List.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/List.java @@ -16,6 +16,7 @@ import org.hibernate.type.ListType; import org.hibernate.usertype.UserCollectionType; /** + * A mapping model object representing a collection of type {@link java.util.List}. * A list mapping has a primary key consisting of the key columns + index column. * * @author Gavin King diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/ManyToOne.java b/hibernate-core/src/main/java/org/hibernate/mapping/ManyToOne.java index 6cc05a5f87..194d8141a1 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/ManyToOne.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/ManyToOne.java @@ -16,7 +16,8 @@ import org.hibernate.type.EntityType; import org.hibernate.type.Type; /** - * A many-to-one association mapping + * A mapping model object representing a {@linkplain jakarta.persistence.ManyToOne many-to-one association}. + * * @author Gavin King */ public class ManyToOne extends ToOne { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Map.java b/hibernate-core/src/main/java/org/hibernate/mapping/Map.java index 0b65f332f4..89592ddb01 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Map.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Map.java @@ -18,8 +18,8 @@ import org.hibernate.type.SortedMapType; import org.hibernate.usertype.UserCollectionType; /** - * A map has a primary key consisting of - * the key columns + index columns. + * A mapping model object representing a collection of type {@link java.util.Map}. + * A map has a primary key consisting of the key columns + index columns. */ public class Map extends IndexedCollection { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/MappedSuperclass.java b/hibernate-core/src/main/java/org/hibernate/mapping/MappedSuperclass.java index a5668a153e..75ec6c032c 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/MappedSuperclass.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/MappedSuperclass.java @@ -11,19 +11,9 @@ import java.util.Iterator; import java.util.List; /** - * Represents a @MappedSuperclass. - * A @MappedSuperclass can be a superclass of an @Entity (root or not) - * - * This class primary goal is to give a representation to @MappedSuperclass - * in the metamodel in order to reflect them in the JPA 2 metamodel. - * - * Do not use outside this use case. - * - * - * A proper redesign will be evaluated in Hibernate 4 - * - * Implementation details: - * properties are copies of their closest sub-persistentClass versions + * A mapping model object representing a {@linkplain jakarta.persistence.MappedSuperclass mapped superclass} + * of an entity class. A mapped superclass is not itself an entity, but it may declare persistent + * attributes which are inherited by entity subclasses. * * @author Emmanuel Bernard */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/OneToMany.java b/hibernate-core/src/main/java/org/hibernate/mapping/OneToMany.java index 077241db0e..cddcc6c543 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/OneToMany.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/OneToMany.java @@ -20,7 +20,7 @@ import org.hibernate.type.EntityType; import org.hibernate.type.Type; /** - * A mapping for a one-to-many association + * A mapping model object representing a {@linkplain jakarta.persistence.OneToMany many-to-one association}. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/OneToOne.java b/hibernate-core/src/main/java/org/hibernate/mapping/OneToOne.java index a7d02606df..9706e1446a 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/OneToOne.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/OneToOne.java @@ -17,7 +17,8 @@ import org.hibernate.type.ForeignKeyDirection; import org.hibernate.type.Type; /** - * A one-to-one association mapping + * A mapping model object representing a {@linkplain jakarta.persistence.OneToOne many-to-one association}. + * * @author Gavin King */ public class OneToOne extends ToOne { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java b/hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java index 249141f926..6e266dbf02 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java @@ -38,7 +38,7 @@ import org.hibernate.sql.Alias; import org.hibernate.type.Type; /** - * The mapping for an entity. + * A mapping model object that represents an {@linkplain jakarta.persistence.Entity entity class}. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/PrimaryKey.java b/hibernate-core/src/main/java/org/hibernate/mapping/PrimaryKey.java index 6b5e771be6..9c40b516af 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/PrimaryKey.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/PrimaryKey.java @@ -13,7 +13,7 @@ import org.hibernate.internal.util.StringHelper; import org.jboss.logging.Logger; /** - * A primary key constraint. + * A mapping model object representing a primary key constraint. * * @author Gavin King * @author Steve Ebersole diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Property.java b/hibernate-core/src/main/java/org/hibernate/mapping/Property.java index 6fabc4684a..459b6fe1b2 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Property.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Property.java @@ -32,7 +32,7 @@ import org.hibernate.type.CompositeType; import org.hibernate.type.Type; /** - * Represents a property or field of an {@link PersistentClass entity} + * A mapping model object representing a property or field of an {@link PersistentClass entity} * or {@link Component embeddable class}. * * @author Gavin King diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/RelationalModel.java b/hibernate-core/src/main/java/org/hibernate/mapping/RelationalModel.java index b3655fd324..31ec24aba1 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/RelationalModel.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/RelationalModel.java @@ -10,7 +10,8 @@ import org.hibernate.boot.model.relational.SqlStringGenerationContext; import org.hibernate.engine.spi.Mapping; /** - * A relational object which may be created using DDL + * A mapping model object representing a relational object which may be created using DDL. + * * @author Gavin King * * @deprecated not needed anymore. diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/RootClass.java b/hibernate-core/src/main/java/org/hibernate/mapping/RootClass.java index 0cb94ec67d..9a11790ad5 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/RootClass.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/RootClass.java @@ -22,7 +22,8 @@ import org.hibernate.internal.util.collections.SingletonIterator; import org.hibernate.persister.entity.EntityPersister; /** - * The root class of an inheritance hierarchy + * A mapping model object that represents the root class in an entity class + * {@linkplain jakarta.persistence.Inheritance inheritance} hierarchy. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Selectable.java b/hibernate-core/src/main/java/org/hibernate/mapping/Selectable.java index 86b281db4a..80dac00654 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Selectable.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Selectable.java @@ -11,7 +11,7 @@ import org.hibernate.query.sqm.function.SqmFunctionRegistry; import org.hibernate.type.spi.TypeConfiguration; /** - * Models the commonality between a column and a formula (computed value). + * Models the commonality between a {@link Column} and a {@link Formula} (computed value). */ public interface Selectable { /** diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Set.java b/hibernate-core/src/main/java/org/hibernate/mapping/Set.java index 9b55e01191..d4600d0a32 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Set.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Set.java @@ -19,8 +19,10 @@ import org.hibernate.type.SortedSetType; import org.hibernate.usertype.UserCollectionType; /** - * A set with no nullable element columns. It will have a primary key - * consisting of all table columns (ie. key columns + element columns). + * A mapping model object representing a collection of type {@link java.util.List}. + * A set has no nullable element columns (unless it is a one-to-many association). + * It has a primary key consisting of all columns (i.e. key columns + element columns). + * * @author Gavin King */ public class Set extends Collection { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java b/hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java index 7ee45f8cb0..57b081fa61 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java @@ -66,7 +66,8 @@ import org.hibernate.type.spi.TypeConfiguration; import org.hibernate.usertype.DynamicParameterizedType; /** - * Any value that maps to columns. + * A mapping model object that represents any value that maps to columns. + * * @author Gavin King */ public abstract class SimpleValue implements KeyValue { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/SingleTableSubclass.java b/hibernate-core/src/main/java/org/hibernate/mapping/SingleTableSubclass.java index 7aa5a3dc30..909da89e01 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/SingleTableSubclass.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/SingleTableSubclass.java @@ -16,6 +16,10 @@ import org.hibernate.internal.util.collections.JoinedIterator; import org.hibernate.internal.util.collections.JoinedList; /** + * A mapping model object that represents a subclass in a + * {@linkplain jakarta.persistence.InheritanceType#SINGLE_TABLE single table} + * inheritance hierarchy. + * * @author Gavin King */ public class SingleTableSubclass extends Subclass { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Subclass.java b/hibernate-core/src/main/java/org/hibernate/mapping/Subclass.java index 2544dfb378..bb177d5fdb 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Subclass.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Subclass.java @@ -21,7 +21,9 @@ import org.hibernate.internal.util.collections.SingletonIterator; import org.hibernate.persister.entity.EntityPersister; /** - * A subclass in a table-per-class-hierarchy mapping + * A mapping model object that represents a subclass in an entity class + * {@linkplain jakarta.persistence.Inheritance inheritance} hierarchy. + * * @author Gavin King */ public class Subclass extends PersistentClass { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Table.java b/hibernate-core/src/main/java/org/hibernate/mapping/Table.java index 9e4e335293..b9222fe66b 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Table.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Table.java @@ -38,7 +38,7 @@ import static java.util.Collections.unmodifiableList; import static java.util.Collections.unmodifiableMap; /** - * A relational database table. + * A mapping model object representing a relational database {@linkplain jakarta.persistence.Table table}. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/ToOne.java b/hibernate-core/src/main/java/org/hibernate/mapping/ToOne.java index aa800e9037..9bed00ae25 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/ToOne.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/ToOne.java @@ -16,7 +16,8 @@ import org.hibernate.internal.util.ReflectHelper; import java.util.Objects; /** - * A simple-point association (ie. a reference to another entity). + * A mapping model object representing an association where the target side has cardinality one. + * * @author Gavin King */ public abstract class ToOne extends SimpleValue implements Fetchable, SortableValue { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/UnionSubclass.java b/hibernate-core/src/main/java/org/hibernate/mapping/UnionSubclass.java index 49a1a65694..08967e874d 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/UnionSubclass.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/UnionSubclass.java @@ -11,7 +11,10 @@ import java.util.List; import org.hibernate.boot.spi.MetadataBuildingContext; /** - * A subclass in a table-per-concrete-class mapping + * A mapping model object that represents a subclass in a "union" or + * {@linkplain jakarta.persistence.InheritanceType#TABLE_PER_CLASS "table per concrete class"} + * inheritance hierarchy. + * * @author Gavin King */ public class UnionSubclass extends Subclass implements TableOwner { diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/UniqueKey.java b/hibernate-core/src/main/java/org/hibernate/mapping/UniqueKey.java index 811ddb5755..7383893f52 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/UniqueKey.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/UniqueKey.java @@ -14,7 +14,7 @@ import org.hibernate.engine.spi.Mapping; import org.hibernate.internal.util.StringHelper; /** - * A unique key constraint. + * A mapping model object representing a unique key constraint on a relational database table. * * @author Brett Meyer */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/Value.java b/hibernate-core/src/main/java/org/hibernate/mapping/Value.java index c468b33de8..4f34465ba5 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/Value.java +++ b/hibernate-core/src/main/java/org/hibernate/mapping/Value.java @@ -17,11 +17,13 @@ import org.hibernate.service.ServiceRegistry; import org.hibernate.type.Type; /** - * A value is anything that is persisted by value, instead of by - * reference. It is essentially a Hibernate {@link Type}, together - * with zero or more columns. Values are wrapped by things with - * higher level semantics, for example properties, collections, - * classes. + * A mapping model object which represents something that's persisted "by value", + * instead of "by reference", that is, anything with no primary key. + *
+ * A {@code Value} is essentially a Hibernate {@link Type}, together with zero or + * more {@link Column columns}. In the mapping model, a {@code Value} always comes + * wrapped in something with higher-level semantics, for example, a property, a + * collection, or a class. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/mapping/package.html b/hibernate-core/src/main/java/org/hibernate/mapping/package.html index 9b219ede84..846ff54c58 100644 --- a/hibernate-core/src/main/java/org/hibernate/mapping/package.html +++ b/hibernate-core/src/main/java/org/hibernate/mapping/package.html @@ -9,7 +9,10 @@
- This package defines the Hibernate configuration-time metamodel. + This package defines the Hibernate configuration-time mapping model. + The objects defined in this package are produced by the annotation + binding process, and consumed by the code with builds persisters and + loaders. They do not outlive the configuration process.