Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

various jdoc format fixes + improve a package-info 

- add some periods
- fix up all the code snippets I messed up
- add some <p>s after lists and code blocks
- improve section of package-info which was hard to understand
- fix jdoc for LobHelper
- fix code example in @ValueGenerationType
This commit is contained in:
Gavin 2022-12-26 21:16:00 +01:00 committed by Gavin King
parent 33c228e715
commit 11760d3ce3
118 changed files with 428 additions and 284 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hibernate-core/src/main/java/org/hibernate/Cache.java
View File

@ -18,6 +18,7 @@ package org.hibernate;
* a given {@link SessionFactory}. It stores the state of an entity instance
* in a destructured format, as a tuple of persistent attribute values.
* </ul>
* <p>
* By nature, a second-level cache tends to undermine the ACID properties of
* transaction processing in a relational database. A second-level cache is often
* by far the easiest way to improve the performance of a system, but only at the
@ -76,6 +77,7 @@ package org.hibernate;
* <li>{@linkplain org.hibernate.annotations.CacheConcurrencyStrategy#TRANSACTIONAL
* transactional access} when concurrent updates are frequent.
* </ul>
* <p>
* It's important to always explicitly specify an appropriate policy, taking into
* account the expected patterns of data access, most importantly, the frequency
* of updates.

1
hibernate-core/src/main/java/org/hibernate/CacheMode.java
View File

@ -63,6 +63,7 @@ public enum CacheMode {
* <li>enabled for a cache where writes are much more expensive than
* reads, which is usually the case for a distributed cache.
* </ul>
* <p>
* It's not usually necessary to specify this setting explicitly because,
* by default, it's set to a sensible value by the second-level cache
* implementation.

2
hibernate-core/src/main/java/org/hibernate/Interceptor.java
View File

@ -29,6 +29,7 @@ import org.hibernate.type.Type;
* specify that there is a dedicated instance of the interceptor for each
* session.
* </ul>
* <p>
* Whichever approach is used, the interceptor must be serializable for the
* {@code Session} to be serializable. This means that {@code SessionFactory}-scoped
* interceptors should implement {@code readResolve()}.
@ -347,6 +348,7 @@ public interface Interceptor {
* <li>{@code null} - Hibernate uses the {@code unsaved-value} mapping and other heuristics to
* determine if the object is unsaved
* </ul>
*
* @param entity a transient or detached entity
* @return Boolean or {@code null} to choose default behaviour
*/

2
hibernate-core/src/main/java/org/hibernate/LobHelper.java
View File

@ -13,7 +13,7 @@ import java.sql.Clob;
import java.sql.NClob;
/**
* A {@link Session session's} helper for creating LOB data.
* A factory for instances of {@link Blob} and {@link Clob} used for writing LOB data.
*
* @author Steve Ebersole
*/

1
hibernate-core/src/main/java/org/hibernate/LockOptions.java
View File

@ -34,6 +34,7 @@ import static java.util.Collections.unmodifiableSet;
* <li>the {@link #getLockScope() lock scope}, that is, whether the
* lock extends to rows of owned collections.
* </ul>
* <p>
* Timeout and lock scope are ignored if the specified {@code LockMode}
* represents a flavor of {@linkplain LockMode#OPTIMISTIC optimistic}
* locking.

1
hibernate-core/src/main/java/org/hibernate/PropertyValueException.java
View File

@ -17,6 +17,7 @@ import org.hibernate.internal.util.StringHelper;
* is null, or
* <li>an association references an unsaved transient instance.
* </ul>
*
* @author Gavin King
*/
public class PropertyValueException extends HibernateException {

21
hibernate-core/src/main/java/org/hibernate/Session.java
View File

@ -39,6 +39,7 @@ import jakarta.persistence.criteria.CriteriaUpdate;
* <li><em>detached:</em> previously persistent, but not currently associated with the
* {@code Session}.
* </ul>
* <p>
* At any given time, an instance may be associated with at most one open session.
* <p>
* Any instance returned by {@link #get(Class, Object)} or by a query is persistent.
@ -63,11 +64,11 @@ import jakarta.persistence.criteria.CriteriaUpdate;
* detached instance to the persistent state are now deprecated, and clients should now
* migrate to the use of {@code merge()}.
* <p>
* From {@link FlushMode time to time}, the session performs a {@linkplain #flush() flushing}
* operation, and synchronizes state held in memory with persistent state held in the
* database by executing SQL {@code insert}, {@code update}, and {@code delete} statements.
* Note that SQL statements are often not executed synchronously by the methods of the
* {@code Session} interface. If synchronous execution of SQL is desired, the
* From {@linkplain FlushMode time to time}, a {@linkplain #flush() flush operation} is
* triggered, and the session synchronizes state held in memory with persistent state
* held in the database by executing SQL {@code insert}, {@code update}, and {@code delete}
* statements. Note that SQL statements are often not executed synchronously by the methods
* of the {@code Session} interface. If synchronous execution of SQL is desired, the
* {@link StatelessSession} allows this.
* <p>
* A persistence context holds hard references to all its entities and prevents them
@ -706,6 +707,7 @@ public interface Session extends SharedSessionContract, EntityManager {
* <li>perform a version check with {@link LockMode#READ}, or
* <li>upgrade to a pessimistic lock with {@link LockMode#PESSIMISTIC_WRITE}).
* </ul>
* <p>
* This operation cascades to associated instances if the association is
* mapped with {@link org.hibernate.annotations.CascadeType#LOCK}.
*
@ -735,6 +737,7 @@ public interface Session extends SharedSessionContract, EntityManager {
* <li>perform a version check with {@link LockMode#READ}, or
* <li>upgrade to a pessimistic lock with {@link LockMode#PESSIMISTIC_WRITE}).
* </ul>
* <p>
* This operation cascades to associated instances if the association is
* mapped with {@link org.hibernate.annotations.CascadeType#LOCK}.
*
@ -756,6 +759,7 @@ public interface Session extends SharedSessionContract, EntityManager {
* <li>the {@linkplain LockRequest#setLockScope(PessimisticLockScope) scope}
* that is, whether the lock extends to rows of owned collections.
* </ul>
* <p>
* Timeout and scope are ignored if the specified {@code LockMode} represents
* a flavor of {@linkplain LockMode#OPTIMISTIC optimistic} locking.
* <p>
@ -782,6 +786,7 @@ public interface Session extends SharedSessionContract, EntityManager {
* SQL statement
* <li>after inserting a {@link java.sql.Blob} or {@link java.sql.Clob}
* </ul>
* <p>
* This operation cascades to associated instances if the association is mapped
* with {@link jakarta.persistence.CascadeType#REFRESH}.
* <p>
@ -803,6 +808,7 @@ public interface Session extends SharedSessionContract, EntityManager {
* SQL statement
* <li>after inserting a {@link java.sql.Blob} or {@link java.sql.Clob}
* </ul>
* <p>
* This operation cascades to associated instances if the association is mapped
* with {@link jakarta.persistence.CascadeType#REFRESH}.
*
@ -1264,9 +1270,10 @@ public interface Session extends SharedSessionContract, EntityManager {
void disableFetchProfile(String name) throws UnknownProfileException;
/**
* Retrieve this session's helper/delegate for creating LOB instances.
* Obtain a {@linkplain LobHelper factory} for instances of {@link java.sql.Blob}
* and {@link java.sql.Clob}.
*
* @return this session's {@link LobHelper LOB helper}
* @return an instance of {@link LobHelper}
*/
LobHelper getLobHelper();

5
hibernate-core/src/main/java/org/hibernate/SessionFactory.java
View File

@ -31,7 +31,7 @@ import jakarta.persistence.EntityManagerFactory;
* affects the runtime behavior of Hibernate, and instances of services that
* Hibernate needs to perform its duties.
* <p>
* Crucially, this is where a program comes to obtain {@link Session sessions}.
* Crucially, this is where a program comes to obtain {@linkplain Session sessions}.
* Typically, a program has a single {@link SessionFactory} instance, and must
* obtain a new {@link Session} instance from the factory each time it services
* a client request.
@ -51,7 +51,7 @@ import jakarta.persistence.EntityManagerFactory;
* There are some interesting exceptions to this principle:
* <ul>
* <li>Each {@code SessionFactory} has its own isolated second-level cache,
* shared between the sessions it creates, and it {@link #getCache()
* shared between the sessions it creates, and it {@linkplain #getCache()
* exposes the cache} to clients as a stateful object with entries that
* may be queried and managed directly.
* <li>Similarly, the factory {@linkplain #getStatistics() exposes} a
@ -67,6 +67,7 @@ import jakarta.persistence.EntityManagerFactory;
* motivation to call either method later, when the factory already has
* active sessions.
* </ul>
* <p>
* The {@code SessionFactory} exposes part of the information in the runtime
* metamodel via an {@linkplain #getMetamodel() instance} of the JPA-defined
* {@link jakarta.persistence.metamodel.Metamodel}. This object is sometimes

2
hibernate-core/src/main/java/org/hibernate/StatelessSession.java
View File

@ -27,12 +27,14 @@ package org.hibernate;
* checking, and
* <li>nor do operations cascade to associated instances.
* </ul>
* <p>
* Furthermore:
* <ul>
* <li>collections are completely ignored by a stateless session, and
* <li>operations performed via a stateless session bypass Hibernate's event
* model, lifecycle callbacks, and interceptors.
* </ul>
* <p>
* Stateless sessions are vulnerable to data aliasing effects, due to the
* lack of a first-level cache.
* <p>

23
hibernate-core/src/main/java/org/hibernate/annotations/Any.java
View File

@ -29,27 +29,28 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* An {@code @Any} mapping would store the discriminator value identifying the concrete
* type of {@code Payment} along with the state of the associated {@code Order}, instead
* of storing it with the {@code Payment} entity itself.
* <pre>{@code
* <pre>
* interface Payment { ... }
*
* @Entity
* &#64;Entity
* class CashPayment { ... }
*
* @Entity
* &#64;Entity
* class CreditCardPayment { ... }
*
* @Entity
* &#64;Entity
* class Order {
* ...
* @Any
* @JoinColumn(name="payment_id") //the foreign key column
* @Column(name="payment_type") //the discriminator column
* @AnyDiscriminatorValue(discriminator="CASH", entity=CashPayment.class)
* @AnyDiscriminatorValue(discriminator="CREDIT", entity=CreditCardPayment.class)
* &#64;Any
* &#64;JoinColumn(name="payment_id") //the foreign key column
* &#64;Column(name="payment_type") //the discriminator column
* &#64;AnyDiscriminatorValue(discriminator="CASH", entity=CashPayment.class)
* &#64;AnyDiscriminatorValue(discriminator="CREDIT", entity=CreditCardPayment.class)
* Payment payment;
* ...
* }
* }</pre>
* </pre>
* <p>
* In this example, {@code Payment} is <em>not</em> be declared as an entity type, and
* is not annotated {@link jakarta.persistence.Entity @Entity}. It might even be an
* interface, or at most just a {@linkplain jakarta.persistence.MappedSuperclass mapped
@ -74,6 +75,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* {@link AnyKeyJdbcTypeCode} specifies the type of the foreign key.
* <li>{@link jakarta.persistence.JoinColumn} specifies the foreign key column.
* </ul>
* <p>
* Of course, {@code Any} mappings are disfavored, except in extremely special cases,
* since it's much more difficult to enforce referential integrity at the database
* level.
@ -92,6 +94,7 @@ public @interface Any {
* <li>{@link FetchType#LAZY LAZY} allows the association to be fetched lazily, but
* this is possible only when bytecode enhancement is used.
* </ul>
* <p>
* If not explicitly specified, the default is {@code EAGER}.
*/
FetchType fetch() default FetchType.EAGER;

2
hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.java
View File

@ -35,6 +35,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* ...
* }
* </pre>
* <p>
* will initialize up to 100 unfetched {@code Product} proxies in each
* trip to the database.
* <p>
@ -44,6 +45,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* &#64;BatchSize(size = 5) /
* Set&lt;Product&gt; getProducts() { ... };
* </pre>
* <p>
* will initialize up to 5 unfetched collections of {@code Product}s in
* each SQL {@code select}.
*

21
hibernate-core/src/main/java/org/hibernate/annotations/Cache.java
View File

@ -24,6 +24,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* given the expected data access patterns affecting the entity
* or collection.
* </ul>
* <p>
* This annotation should always be used in preference to the less
* useful JPA-defined annotation {@link jakarta.persistence.Cacheable},
* since JPA provides no means to specify anything about the semantics
@ -34,17 +35,19 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* cache inherit the cache belonging to the root entity.
* <p>
* For example, the following entity is eligible for caching:
* <pre>{@code
* @Entity
* @Cache(usage = NONSTRICT_READ_WRITE)
* <pre>
* &#64;Entity
* &#64;Cache(usage = NONSTRICT_READ_WRITE)
* public static class Person { ... }
* }</pre>
* </pre>
* <p>
* Similarly, this collection is cached:
* <pre>{@code
* @OneToMany(mappedBy = "person")
* @Cache(usage = NONSTRICT_READ_WRITE)
* private List<Phone> phones = new ArrayList<>();
* }</pre>
* <pre>
* &#64;OneToMany(mappedBy = "person")
* &#64;Cache(usage = NONSTRICT_READ_WRITE)
* private List&lt;Phone&gt; phones = new ArrayList&lt;&gt;();
* </pre>
* <p>
* Note that the second-level cache is disabled unless
* {@value org.hibernate.cfg.AvailableSettings#CACHE_REGION_FACTORY}
* is explicitly specified, and so, by default, this annotation has

2
hibernate-core/src/main/java/org/hibernate/annotations/CacheConcurrencyStrategy.java
View File

@ -26,6 +26,7 @@ import org.hibernate.cache.spi.access.AccessType;
* <li>read extremely frequently, and
* <li>written infrequently.
* </ul>
* <p>
* When an entity or collection is marked {@linkplain Cache cacheable},
* it must indicate the policy which governs concurrent access to its
* second-level cache, by selecting a {@code CacheConcurrencyStrategy}
@ -108,6 +109,7 @@ public enum CacheConcurrencyStrategy {
* with something that might not quite be the latest
* version.
* </ul>
* <p>
* This concurrency strategy is not compatible with
* serializable transaction isolation.
*

8
hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java
View File

@ -24,11 +24,9 @@ import org.hibernate.ReplicationMode;
* To enable cascade {@code LOCK}, use {@link Cascade @Cascade}, for
* example:
* <pre>
* {@code
* @OneToMany(mappedBy="parent")
* @Cascade({PERSIST,REFRESH,REMOVE,LOCK})
* Set<Child> children;
* }
* &#64;OneToMany(mappedBy="parent")
* &#64;Cascade({PERSIST,REFRESH,REMOVE,LOCK})
* Set&lt;Child&gt; children;
* </pre>
*
* @see Cascade

11
hibernate-core/src/main/java/org/hibernate/annotations/CollectionId.java
View File

@ -26,12 +26,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Retention(RUNTIME)
public @interface CollectionId {
/**
* The column containing the collection-id
* The column containing the collection id.
*/
Column column() default @Column;
/**
* Implementation for generating values
* Implementation for generating values.
*
* @apiNote Mutually exclusive with {@link #generator()}
*/
@ -39,10 +39,9 @@ public @interface CollectionId {
/**
* The generator name.
*
* Can specify either a built-in strategy ("sequence", e.g.)
* or a named generatorIdentifierGenerator
* ({@link jakarta.persistence.SequenceGenerator}, e.g.)
* <p>
* Can specify either a built-in strategy ({@code "sequence"}, for example)
* or a named JPA id generator.
*
* @apiNote Mutually exclusive with {@link #generatorImplementation()}
*/

2
hibernate-core/src/main/java/org/hibernate/annotations/CollectionIdJavaType.java
View File

@ -18,7 +18,7 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Form of {@link JavaType} for describing the id of an id-bag mapping
* Form of {@link JavaType} for describing the id of an id-bag mapping.
*
* @since 6.0
*/

2
hibernate-core/src/main/java/org/hibernate/annotations/CollectionIdJdbcType.java
View File

@ -18,7 +18,7 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Form of {@link org.hibernate.annotations.JdbcType} for describing the id of an id-bag mapping
* Form of {@link org.hibernate.annotations.JdbcType} for describing the id of an id-bag mapping.
*
* @since 6.0
*/

2
hibernate-core/src/main/java/org/hibernate/annotations/CollectionIdJdbcTypeCode.java
View File

@ -16,7 +16,7 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Form of {@link JdbcTypeCode} for describing the id of an id-bag mapping
* Form of {@link JdbcTypeCode} for describing the id of an id-bag mapping.
*
* @since 6.0
*/

2
hibernate-core/src/main/java/org/hibernate/annotations/CollectionIdType.java
View File

@ -16,7 +16,7 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Form of {@link Type} for describing the id of an id-bag mapping
* Form of {@link Type} for describing the id of an id-bag mapping.
*
* @since 6.0
*/

1
hibernate-core/src/main/java/org/hibernate/annotations/ColumnDefault.java
View File

@ -23,6 +23,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>{@link Generated @Generated}, to populate an entity attribute with
* the defaulted value of a database column.
* </ul>
* <p>
* If {@code @Generated} is not used, a {@code default} value can cause state
* held in memory to lose synchronization with the database.
*

9
hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java
View File

@ -22,15 +22,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>A {@link #write} expression must contain exactly one JDBC-style '?' placeholder.
* <li>A {@link #read} expression may not contain JDBC-style placeholders.
* </ul>
* <p>
* For example:
* <pre>
* {@code
* @Column(name="credit_card_num")
* @ColumnTransformer(read="decrypt(credit_card_num)"
* &#64;Column(name="credit_card_num")
* &#64;ColumnTransformer(read="decrypt(credit_card_num)"
* write="encrypt(?)")
* String creditCardNumber;
* }
* </pre>
* <p>
* A column transformer {@link #write} expression transforms the value of a persistent
* attribute of an entity as it is being written to the database.
* <ul>
@ -43,6 +43,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* in-memory state of the Java entity instance should be considered unsynchronized
* with the database after every SQL {@code insert} or {@code update} is executed.
* </ul>
* <p>
* In the second scenario, we may ask Hibernate to resynchronize the in-memory state
* with the database after each {@code insert} or {@code update} by annotating the
* persistent attribute {@link Generated @Generated(event={INSERT,UPDATE}, writable=true)}.

1
hibernate-core/src/main/java/org/hibernate/annotations/CurrentTimestamp.java
View File

@ -32,6 +32,7 @@ import static org.hibernate.generator.EventType.UPDATE;
* <li>{@link SourceType#DB source = DB} indicates that the database
* {@code current_timestamp} function should be used.
* </ul>
* <p>
* By default, the timestamp is generated by the database, which requires
* an extra round trip to the database to fetch the generated value.
* <p>

37
hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorFormula.java
View File

@ -23,38 +23,39 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* Used in place of the JPA {@link jakarta.persistence.DiscriminatorColumn}.
* <p>
* For example, we might declare a supertype as follows:
* <pre>{@code
* @Entity
* @DiscriminatorFormula(discriminatorType = INTEGER,
* <pre>
* &#64;Entity
* &#64;DiscriminatorFormula(discriminatorType = INTEGER,
* value = "case when value1 is not null then 1 when value2 is not null then 2 end")
* public abstract class AbstractChild {
* @Id
* @GeneratedValue
* &#64;Id
* &#64;GeneratedValue
* Integer id;
* ...
* }
* }</pre>
* </pre>
* <p>
* and then each concrete subclass must specify a matching discriminator value:
* <pre>{@code
* @Entity
* @DiscriminatorValue("1")
* <pre>
* &#64;Entity
* &#64;DiscriminatorValue("1")
* public class ConcreteChild1 extends AbstractChild {
* @Basic(optional = false)
* @Column(name = "VALUE1")
* &#64;Basic(optional = false)
* &#64;Column(name = "VALUE1")
* String value;
* ...
* }
* }</pre>
* <pre>{@code
* @Entity
* @DiscriminatorValue("2")
* </pre>
* <pre>
* &#64;Entity
* &#64;DiscriminatorValue("2")
* public class ConcreteChild2 extends AbstractChild {
* @Basic(optional = false)
* @Column(name = "VALUE2")
* &#64;Basic(optional = false)
* &#64;Column(name = "VALUE2")
* String value;
* ...
* }
* }</pre>
* </pre>
*
* @see Formula
* @see DialectOverride.DiscriminatorFormula

1
hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java
View File

@ -22,6 +22,7 @@ import java.lang.annotation.Target;
* <li>{@linkplain FetchMode#JOIN join fetching} is used for
* {@linkplain jakarta.persistence.FetchType#EAGER eager} fetching.
* </ul>
* <p>
* The default fetching strategy specified by this annotation may be
* overridden in a given {@linkplain FetchProfile fetch profile}.
*

1
hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java
View File

@ -37,6 +37,7 @@ public enum FetchMode {
* <li>ensuring that the associated entity or collection may be
* retrieved from the {@linkplain Cache second-level cache}.
* </ul>
* <p>
* This fetching strategy is, in principle, compatible with both
* {@linkplain jakarta.persistence.FetchType#EAGER eager} and
* {@linkplain jakarta.persistence.FetchType#LAZY lazy} fetching.

1
hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java
View File

@ -39,6 +39,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>an entity graph is explicit, and simply specifies that each path
* from the root of the graph should be fetched.
* </ul>
* <p>
* However, a fetch profile is not by nature rooted at any one particular
* entity, and so {@code @FetchProfile} is not required to annotate the
* entity classes it affects. It may even occur as a package-level

8
hibernate-core/src/main/java/org/hibernate/annotations/Filter.java
View File

@ -24,17 +24,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* For example, we might apply a filter named {@code Current} to
* an entity like this:
* <pre>
* {@code
* @Entity
* @Filter(name = "Current",
* &#64;Entity
* &#64;Filter(name = "Current",
* deduceAliasInjectionPoints = false,
* condition = "{alias}.year = extract(year from current_date)")
* class Course {
* @Id @GeneratedValue Long id;
* &#64;Id &#64;GeneratedValue Long id;
* int year;
* ...
* }
* }
* </pre>
* <p>
* If an entity or collection has no {@code @Filter} annotation

17
hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java
View File

@ -28,30 +28,27 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <p>
* For example, if a filter is declared as follows:
* <pre>
* {@code
* @FilterDef(name = "Current",
* &#64;FilterDef(name = "Current",
* defaultCondition = "status<>'DELETED'")
* package org.hibernate.domain;
* }
* </pre>
* <p>
* Then the filter may be applied to an entity type like this:
* <pre>
* {@code
* @Entity
* @Filter(name = "Current")
* &#64;Entity
* &#64;Filter(name = "Current")
* class Record {
* @Id @GeneratedValue Long id;
* @Enumerated(STRING) Status status;
* &#64;Id @GeneratedValue Long id;
* &#64;Enumerated(STRING) Status status;
* ...
* }
* }
* </pre>
* <p>
* At runtime, a filter may be enabled in a particular session by
* calling {@link org.hibernate.Session#enableFilter(String)},
* passing the name of the filter, and then setting its parameters.
* <pre>
* {@code session.enableFilter("Current");}
* session.enableFilter("Current");
* </pre>
*
* @author Matthew Inger

32
hibernate-core/src/main/java/org/hibernate/annotations/Formula.java
View File

@ -19,26 +19,26 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* A {@code Formula} mapping defines a "derived" attribute, whose state is determined
* from other columns and functions when an entity is read from the database.
*
* <pre><code>
* // perform calculations using SQL operators
* &#064;Formula("sub_total + (sub_total * tax)")
* long getTotalCost() { ... }
* </code></pre>
*
* <pre><code>
* // call native SQL functions
* &#064;Formula("upper(substring(middle_name, 1))")
* Character getMiddleInitial() { ... }
* </code></pre>
* <pre>
* // perform calculations using SQL operators
* &#64;Formula("sub_total + (sub_total * tax)")
* long getTotalCost() { ... }
* </pre>
*
* <pre>
* // call native SQL functions
* &#64;Formula("upper(substring(middle_name, 1))")
* Character getMiddleInitial() { ... }
* </pre>
* <p>
* {@link ColumnTransformer} is an alternative, allowing the use of native SQL to
* read and write values.
*
* <pre><code>
* // it might be better to use @ColumnTransformer in this case
* &#064;Formula("decrypt(credit_card_num)")
* String getCreditCardNumber() { ... }
* </code></pre>
* <pre>
* // it might be better to use &#64;ColumnTransformer in this case
* &#064;Formula("decrypt(credit_card_num)")
* String getCreditCardNumber() { ... }
* </pre>
*
* @see ColumnTransformer
* @see DiscriminatorFormula

2
hibernate-core/src/main/java/org/hibernate/annotations/Generated.java
View File

@ -39,6 +39,7 @@ import static org.hibernate.generator.EventType.INSERT;
* property of the entity, or {@linkplain #writable() transforms} the
* value currently assigned to the annotated property.
* </ul>
* <p>
* On the other hand:
* <ul>
* <li>for identity/autoincrement columns mapped to an identifier property,
@ -85,6 +86,7 @@ public @interface Generated {
* selected after each SQL {@code insert} or {@code update}
* statement is executed.
* </ul>
*
* @deprecated use {@link #event()}
*/
@Deprecated(since = "6.2")

12
hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java
View File

@ -36,21 +36,23 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* to specify the {@link #name()} of the generator defined using this
* annotation.
* </ul>
* <p>
* If neither {@link #type} not {@link #strategy} is specified, Hibernate asks
* {@linkplain org.hibernate.dialect.Dialect#getNativeIdentifierGeneratorStrategy
* the dialect} to decide an appropriate strategy. This is equivalent to using
* {@link jakarta.persistence.GenerationType#AUTO AUTO} in JPA.
* <p>
* For example, if we define a generator using:
* <pre>{@code
* @GenericGenerator(name = "custom-generator",
* <pre>
* &#64;GenericGenerator(name = "custom-generator",
* type = org.hibernate.eg.CustomStringGenerator.class)
* }</pre>
* <p>
* Then we may make use of it by annotating an identifier field as follows:
* <pre>{@code
* @Id @GeneratedValue(generator = "custom-generator")
* <pre>
* &#64;Id &#64;GeneratedValue(generator = "custom-generator")
* private String id;
* }</pre>
* </pre>
* <p>
* The disadvantage of this approach is the use of stringly-typed names. An
* alternative, completely typesafe, way to declare a generator and associate

22
hibernate-core/src/main/java/org/hibernate/annotations/IdGeneratorType.java
View File

@ -22,7 +22,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* way to work with customized identifier generation in Hibernate.
* <p>
* For example, if we have a custom identifier generator:
* <pre>{@code
* <pre>
* public class CustomSequenceGenerator implements BeforeExecutionGenerator {
* public CustomSequenceGenerator(CustomSequence config, Member annotatedMember,
* CustomIdGeneratorCreationContext context) {
@ -30,23 +30,26 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* }
* ...
* }
* }</pre>
* </pre>
* <p>
* Then we may also define an annotation which associates this generator with
* an entity and supplies configuration parameters:
* <pre>{@code
* @IdGeneratorType(CustomSequenceGenerator.class)
* @Retention(RUNTIME) @Target({METHOD,FIELD})
* <pre>
* &#64;IdGeneratorType(CustomSequenceGenerator.class)
* &#64;Retention(RUNTIME) @Target({METHOD,FIELD})
* public @interface CustomSequence {
* String name();
* int startWith() default 1;
* int incrementBy() default 50;
* }
* }</pre>
* </pre>
* <p>
* and we may use it as follows:
* <pre>{@code
* @Id @CustomSequence(name = "mysequence", startWith = 0)
* <pre>
* &#64;Id &#64;CustomSequence(name = "mysequence", startWith = 0)
* private Integer id;
* }</pre>
* </pre>
* <p>
* We did not use the JPA-defined {@link jakarta.persistence.GeneratedValue}
* here, since that API is designed around the use of stringly-typed names.
* The {@code @CustomSequence} annotation itself implies that {@code id} is
@ -59,6 +62,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>the id generator class has a constructor with the same signature as
* {@link AnnotationBasedGenerator#initialize}.
* </ul>
* <p>
* For a more complete example, see the annotation {@link UuidGenerator} and
* the corresponding generator class {@link org.hibernate.id.uuid.UuidGenerator}.
* <p>

1
hibernate-core/src/main/java/org/hibernate/annotations/LazyGroup.java
View File

@ -30,6 +30,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* lazy fields at once. This annotation provides control over that
* behavior.
* </ul>
* <p>
* A fetch group identifies a set of related attributes that should be loaded
* together when any one of them is accessed. By default, all non-collection
* attributes belong to a single fetch group named {@code "DEFAULT"}. The

1
hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java
View File

@ -76,6 +76,7 @@ public enum LazyToOneOption {
* <li>Bytecode enhancement is required. If the class is not
* enhanced, this option is equivalent to {@link #PROXY}.
* </ul>
* <p>
* Hibernate does not support this setting for polymorphic
* associations, and instead falls back to {@link #PROXY}.
*

1
hibernate-core/src/main/java/org/hibernate/annotations/ListIndexBase.java
View File

@ -20,6 +20,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>When an element is written to the database, the base value is added to
* the list or array index to determine the order column value.
*</ul>
* <p>
* By default, the base value for an order column is zero, as required by JPA.
* <p>
* This annotation is usually used in conjunction with the JPA-defined

3
hibernate-core/src/main/java/org/hibernate/annotations/ListIndexJavaType.java
View File

@ -18,7 +18,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Form of {@link JavaType} for describing the column mapping for the index of a List or array
* Form of {@link JavaType} for describing the column mapping
* for the index of a {@code List} or array.
*
* @since 6.0
*/

3
hibernate-core/src/main/java/org/hibernate/annotations/ListIndexJdbcType.java
View File

@ -16,7 +16,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Form of {@link org.hibernate.annotations.JdbcType} for describing the column mapping for the index of a List or array
* Form of {@link org.hibernate.annotations.JdbcType} for describing
* the column mapping for the index of a {@code List} or array.
*
* @since 6.0
*/

3
hibernate-core/src/main/java/org/hibernate/annotations/ListIndexJdbcTypeCode.java
View File

@ -16,7 +16,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Form of {@link JdbcTypeCode} for describing the column mapping for the index of a List or array
* Form of {@link JdbcTypeCode} for describing the column mapping
* for the index of a {@code List} or array.
*
* @since 6.0
*/

21
hibernate-core/src/main/java/org/hibernate/annotations/ManyToAny.java
View File

@ -27,18 +27,19 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* entities.
* <p>
* For example:
* <pre>{@code
* @ManyToAny
* @Column(name = "property_type")
* @AnyKeyJavaClass(Long.class)
* @AnyDiscriminatorValue(discriminator = "S", entity = StringProperty.class)
* @AnyDiscriminatorValue(discriminator = "I", entity = IntegerProperty.class)
* @JoinTable(name = "repository_properties",
* <pre>
* &#64;ManyToAny
* &#64;Column(name = "property_type")
* &#64;AnyKeyJavaClass(Long.class)
* &#64;AnyDiscriminatorValue(discriminator = "S", entity = StringProperty.class)
* &#64;AnyDiscriminatorValue(discriminator = "I", entity = IntegerProperty.class)
* &#64;JoinTable(name = "repository_properties",
* joinColumns = @JoinColumn(name = "repository_id"),
* inverseJoinColumns = @JoinColumn(name = "property_id"))
* @Cascade(PERSIST)
* private List<Property<?>> properties = new ArrayList<>();
* }</pre>
* &#64;Cascade(PERSIST)
* private List&lt;Property&lt;?&gt;&gt; properties = new ArrayList&lt;&gt;();
* </pre>
* <p>
* In this example, {@code Property} is not required to be an entity type,
* it might even just be an interface, but its subtypes {@code StringProperty}
* and {@code IntegerProperty} must be entity classes with the same identifier

2
hibernate-core/src/main/java/org/hibernate/annotations/MapKeyType.java
View File

@ -18,7 +18,7 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Form of {@link Type} for use with map-keys
* Form of {@link Type} for use with map keys.
*
* @since 6.0
*/

16
hibernate-core/src/main/java/org/hibernate/annotations/Mutability.java
View File

@ -23,8 +23,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* Specifies a {@link MutabilityPlan} for a basic value mapping.
* <ul>
* <li>
* When applied to a Map-valued attribute, describes the
* {@code Map} value. Use {@link MapKeyMutability} to
* When applied to a {@code Map}-valued attribute, describes
* the {@code Map} value. Use {@link MapKeyMutability} to
* describe the key instead.
* </li>
* <li>
@ -44,15 +44,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* {@link ManyToAny}), describes the discriminator value.
* </li>
* </ul>
*
* <p>
* Resolved as a {@link org.hibernate.resource.beans.spi.ManagedBean}.
*
* See <a href="package-summary.html#basic-value-mapping">basic-value-mapping</a> for a
* high-level discussion of basic value mapping.
* <p>
* See <a href="package-summary.html#basic-value-mapping">basic-value-mapping</a>
* for a high-level discussion of basic value mapping.
*
* @apiNote Valid on {@link ElementType#TYPE} in very limited cases.
* At the moment it is only supported on implementations of
* {@link jakarta.persistence.AttributeConverter}.
* At the moment it is only supported on implementations of
* {@link jakarta.persistence.AttributeConverter}.
*
* @see Immutable
*

32
hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java
View File

@ -24,47 +24,49 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* user of the system. This is the <em>natural id</em> of the entity.
* <p>
* A natural id may be a single field or property of the entity:
* <pre>{@code
* @Entity
* @Cache @NaturalIdCache
* <pre>
* &#64;Entity
* &#64;Cache &#64;NaturalIdCache
* class Person {
*
* //synthetic id
* @GeneratedValue @Id
* &#64;GeneratedValue @Id
* Long id;
*
* @NotNull
* &#64;NotNull
* String name;
*
* //simple natural id
* @NotNull @NaturalId
* &#64;NotNull @NaturalId
* String ssn;
*
* ...
* }
* }</pre>
* </pre>
* <p>
* or it may be a composite value:
* <pre>{@code
* @Entity
* @Cache @NaturalIdCache
* <pre>
* &#64;Entity
* &#64;Cache &#64;NaturalIdCache
* class Vehicle {
*
* //synthetic id
* @GeneratedValue @Id
* &#64;GeneratedValue @Id
* Long id;
*
* //composite natural id
*
* @Enumerated
* @NotNull @NaturalId
* &#64;Enumerated
* &#64;NotNull &#64;NaturalId
* Region region;
*
* @NotNull @NaturalId
* &#64;NotNull &#64;NaturalId
* String registration;
*
* ...
* }
* }</pre>
* </pre>
* <p>
* The {@link org.hibernate.Session} interface offers several methods
* that allow an entity instance to be retrieved by its
* {@linkplain org.hibernate.Session#bySimpleNaturalId(Class) simple}

1
hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java
View File

@ -30,6 +30,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>{@link NotFoundAction#IGNORE} specifies that this situation should
* be tolerated and treated as if the foreign key were null.
* </ul>
* <p>
* Note that this annotation has the side effect of making a to-one
* association non-lazy. It does not affect the laziness of a many-to-many
* association.

1
hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLocking.java
View File

@ -22,6 +22,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* entity instance, or
* <li>{@linkplain OptimisticLockType#ALL all fields} of the entity.
* </ul>
* <p>
* An optimistic lock is usually checked by including a restriction in a
* SQL {@code update} or {@code delete} statement. If the database reports
* that zero rows were updated, it is inferred that another transaction

3
hibernate-core/src/main/java/org/hibernate/annotations/Polymorphism.java
View File

@ -23,7 +23,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* is neither an entity class nor a mapped superclass. The
* query will return all entities which inherit the type.
* For example, the query
* <pre>{@code from java.lang.Object}</pre>
* <pre>from java.lang.Object</pre>
* <p>
* will return every entity mapped by Hibernate!
* <p>
* This can be thought of as allowing a sort of "poor man's"

2
hibernate-core/src/main/java/org/hibernate/annotations/SQLDelete.java
View File

@ -20,7 +20,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* generated by Hibernate when an entity or collection row is deleted from the
* database.
* <p>
* The given {@link #sql SQL statement} must have exactly the number of JDBC
* The given {@linkplain #sql SQL statement} must have exactly the number of JDBC
* {@code ?} parameters that Hibernate expects, in the exact order Hibernate
* expects. The primary key columns come before the version column if the
* entity is versioned.

4
hibernate-core/src/main/java/org/hibernate/annotations/SQLInsert.java
View File

@ -20,10 +20,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* generated by Hibernate when an entity or collection row is inserted in the
* database.
* <p>
* The given {@link #sql SQL statement} must have exactly the number of JDBC
* The given {@linkplain #sql SQL statement} must have exactly the number of JDBC
* {@code ?} parameters that Hibernate expects, that is, one for each column
* mapped by the entity, in the exact order Hibernate expects. In particular,
* the {@link jakarta.persistence.Id primary key} columns must come last.
* the {@linkplain jakarta.persistence.Id primary key} columns must come last.
* <p>
* If a column should <em>not</em> be written as part of the insert statement,
* and has no corresponding JDBC parameter in the custom SQL, it must be mapped

6
hibernate-core/src/main/java/org/hibernate/annotations/SQLUpdate.java
View File

@ -20,11 +20,11 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* generated by Hibernate when an entity or collection row is updated in the
* database.
* <p>
* The given {@link #sql SQL statement} must have exactly the number of JDBC
* The given {@linkplain #sql SQL statement} must have exactly the number of JDBC
* {@code ?} parameters that Hibernate expects, that is, one for each column
* mapped by the entity, in the exact order Hibernate expects. In particular,
* the {@link jakarta.persistence.Id primary key} columns come last unless
* the entity is {@link jakarta.persistence.Version versioned}, in which case
* the {@linkplain jakarta.persistence.Id primary key} columns come last unless
* the entity is {@linkplain jakarta.persistence.Version versioned}, in which case
* there must be a second JDBC parameter for the version column, which comes
* after the primary key.
* <p>

2
hibernate-core/src/main/java/org/hibernate/annotations/SortComparator.java
View File

@ -20,7 +20,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* Sorting is performed in memory, by Java's {@link java.util.TreeSet} or {@link java.util.TreeMap},
* and is maintained by any operation that mutates the collection.
* <ul>
* <li>Use {@link SortNatural} in its {@link java.util.Comparator natural order}.
* <li>Use {@link SortNatural} to sort by {@linkplain java.util.Comparator natural order}.
* <li>Use {@link jakarta.persistence.OrderBy} to order using an expression written in HQL.
* <li>Use {@link OrderBy} to order using an expression written in native SQL.
* </ul>

6
hibernate-core/src/main/java/org/hibernate/annotations/Source.java
View File

@ -27,14 +27,14 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>{@link SourceType#DB} indicates that the database
* {@code current_timestamp} function should be used.
* </ul>
* <p>
* For example, the following timestamp is generated by the
* database:
* <pre>
* {@code
* @Version @Source(DB)
* &#64;Version &#64;Source(DB)
* private LocalDateTime version;
* }
* </pre>
* <p>
* This annotation is always used in conjunction with the JPA
* {@link jakarta.persistence.Version @Version} annotation.
*

14
hibernate-core/src/main/java/org/hibernate/annotations/TimeZoneStorage.java
View File

@ -25,21 +25,19 @@ import static java.lang.annotation.ElementType.METHOD;
* <p>
* For example:
* <pre>
* {@code
* @Entity
* &#64;Entity
* public class Person {
*
* @Column(name = "birth_timestamp")
* @TimeZoneColumn(name = "birth_zone")
* @TimeZoneStorage(COLUMN)
* &#64;Column(name = "birth_timestamp")
* &#64;TimeZoneColumn(name = "birth_zone")
* &#64;TimeZoneStorage(COLUMN)
* public OffsetDateTime birthDate;
*
* @TimeZoneStorage(NATIVE)
* &#64;TimeZoneStorage(NATIVE)
* public OffsetDateTime registrationDate;
*
* ...
* }
*}
* }
* </pre>
*
* @author Christian Beikov

3
hibernate-core/src/main/java/org/hibernate/annotations/TimeZoneStorageType.java
View File

@ -29,6 +29,7 @@ import org.hibernate.dialect.Dialect;
* {@linkplain java.time.ZonedDateTime#getZone() zone} in which the
* instant is represented.
* </ul>
* <p>
* We must also consider the physical representation of the zoned datetime
* in the database table.
* <p>
@ -43,6 +44,7 @@ import org.hibernate.dialect.Dialect;
* so that datetimes retrieved from the database will be represented in
* UTC.
* </ul>
* <p>
* When this default strategy is not appropriate, recommended alternatives
* are:
* <ul>
@ -82,6 +84,7 @@ public enum TimeZoneStorageType {
* <li>passes them through in the JVM default time zone
* otherwise.
* </ul>
* <p>
* Provided partly for backward compatibility with older
* versions of Hibernate
*/

26
hibernate-core/src/main/java/org/hibernate/annotations/Type.java
View File

@ -26,23 +26,27 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* applied to various properties and fields, or
* <li>by default, via a {@linkplain TypeRegistration registration}.
* </ul>
* <p>
* For example, as an alternative to:
* <pre>{@code
* @Type(MonetaryAmountUserType.class)
* <pre>
* &#64;Type(MonetaryAmountUserType.class)
* BigDecimal amount;
* }</pre>
* </pre>
* <p>
* we may define an annotation type:
* <pre>{@code
* @Retention(RUNTIME)
* @Target({METHOD,FIELD})
* @Type(MonetaryAmountUserType.class)
* <pre>
* &#64;Retention(RUNTIME)
* &#64;Target({METHOD,FIELD})
* &#64;Type(MonetaryAmountUserType.class)
* public @interface MonetaryAmount {}
* }</pre>
* </pre>
* <p>
* and then write:
* <pre>{@code
* @MonetaryAmount
* <pre>
* &#64;MonetaryAmount
* BigDecimal amount;
* }</pre>
* </pre>
* <p>
* which is much cleaner.
* <p>
* The use of a {@code UserType} is usually mutually exclusive with the

30
hibernate-core/src/main/java/org/hibernate/annotations/ValueGenerationType.java
View File

@ -25,22 +25,30 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* best way to work with customized value generation in Hibernate.
* <p>
* For example, if we have a custom value generator:
* <pre>{@code
* <pre>
* public class SKUGeneration
* implements InMemoryValueGenerationStrategy,
* ValueGenerator<String> {
* implements BeforeExecutionGenerator {
* public SKUGeneration(SKU sku, Member annotatedMember,
* GeneratorCreationContext context) {
* ...
* }
* ...
* }
* }</pre>
* </pre>
* <p>
* Then we may also define an annotation which associates this generator with
* a field or property of an entity and supplies configuration parameters:
* <pre>{@code
* @ValueGenerationType(generatedBy = SKUGeneration.class)
* @Retention(RUNTIME) @Target({METHOD,FIELD})
* public @interface SKU {}
* }</pre>
* <pre>
* &#64;ValueGenerationType(generatedBy = SKUGeneration.class)
* &#64;Retention(RUNTIME) &#64;Target({METHOD,FIELD})
* public &#64;interface SKU {}
* </pre>
* <p>
* and we may use it as follows:
* <pre>{@code @SKU String sku;}</pre>
* <pre>
* &#64;SKU String sku;
* </pre>
* <p>
* No more than one generator annotation may be placed on a given property.
* <p>
* Adding a generator annotation to an entity property causes the value of the
@ -55,6 +63,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>an {@link OnExecutionGenerator}, for values which are generated by the
* database.
* </ul>
* <p>
* A generator annotation may have members, which are used to configure the
* value generator, if either:
* <ul>
@ -62,6 +71,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>the value generator class has a constructor with the same signature as
* {@link AnnotationBasedGenerator#initialize}.
* </ul>
* <p>
* There are several excellent examples of the use of this machinery right
* here in this package. {@link TenantId} and its corresponding generator
* {@link TenantIdGeneration} are a good place to start.

22
hibernate-core/src/main/java/org/hibernate/annotations/Where.java
View File

@ -20,22 +20,24 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <p>
* For example, {@code @Where} could be used to hide entity instances which
* have been soft-deleted, either for the entity class itself:
* <pre>{@code
* @Entity
* @Where(clause = "status <> 'DELETED'")
* <pre>
* &#64;Entity
* &#64;Where(clause = "status &lt;&gt; 'DELETED'")
* class Document {
* ...
* @Enumerated(STRING)
* &#64;Enumerated(STRING)
* Status status;
* ...
* }
* }</pre>
* </pre>
* <p>
* or, at the level of an association to the entity:
* <pre>{@code
* @OneToMany(mappedBy = "owner")
* @Where(clause = "status <> 'DELETED'")
* List<Document> documents;
* }</pre>
* <pre>
* &#64;OneToMany(mappedBy = "owner")
* &#64;Where(clause = "status &lt;&gt; 'DELETED'")
* List&lt;Document&gt; documents;
* </pre>
* <p>
* By default, {@code @Where} restrictions declared for an entity are not
* applied when loading a collection of that entity type. This behavior is
* controlled by:

9
hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java
View File

@ -12,12 +12,13 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Specifies a restriction written in native SQL to add to the generated
* SQL when querying the {@link jakarta.persistence.JoinTable join table}
* Specifies a restriction written in native SQL to add to the generated SQL
* when querying the {@linkplain jakarta.persistence.JoinTable join table}
* of a collection.
* <p>
* For example, {@code @Where("status <> 'DELETED'")} could be used to hide
* associations which have been soft-deleted from an association table.
* For example, <code>&#64;Where("status &lt;&gt; 'DELETED'")</code> could be
* used to hide associations which have been soft-deleted from an association
* table.
*
* @author Emmanuel Bernard
*

72
hibernate-core/src/main/java/org/hibernate/annotations/package-info.java
View File

@ -8,39 +8,53 @@
/**
* A set of mapping annotations which extend the O/R mapping annotations defined by JPA.
*
* <h2 id="basic-value-mapping">Basic value mapping</h2>
* <h2 id="basic-value-mapping">Basic value type mappings</h2>
*
* Hibernate supports two approaches to defining a mapping strategy for basic values:
* JPA supports a very limited set of built-in {@linkplain jakarta.persistence.Basic basic}
* types, and provides only {@linkplain jakarta.persistence.AttributeConverter converters}
* as a solution when the built-in types are insufficient.
* <p>
* By contrast, Hibernate has an embarrassingly rich set of abstractions for modelling
* "basic" types, which can be initially confusing. Note that the venerable interface
* {@link org.hibernate.type.Type} abstracts over all sorts of field and property types,
* not only basic types. In modern Hibernate, programs should avoid directly implementing
* this interface.
* <p>
* Instead, a program should use either a "compositional" basic type, or in more extreme
* cases, a {@code UserType}.
* <ul>
* <li>
* A "compositional" approach using a combination of the following influencers for
* various parts of mapping<ul>
* <li>{@link org.hibernate.annotations.JavaType}</li>
* <li>{@link org.hibernate.annotations.JdbcType}</li>
* <li>{@link org.hibernate.annotations.JdbcTypeCode}</li>
* <li>{@link org.hibernate.annotations.Mutability}</li>
* <li>{@link jakarta.persistence.AttributeConverter} / {@link jakarta.persistence.Convert}</li>
* <li>{@link jakarta.persistence.Lob}</li>
* <li>{@link jakarta.persistence.Enumerated}</li>
* <li>{@link jakarta.persistence.Temporal}</li>
* <li>{@link org.hibernate.annotations.Nationalized}</li>
* </ul>
* Note that {@link org.hibernate.annotations.JavaType}, {@link org.hibernate.annotations.JdbcType},
* {@link org.hibernate.annotations.JdbcTypeCode} and {@link org.hibernate.annotations.Mutability}
* all have specialized forms for the various model parts such as map-key, list-index, (id-bag)
* collection-id, etc.
* </li>
* <li>
* Contracted via the {@link org.hibernate.usertype.UserType} interface and specified using
* {@link org.hibernate.annotations.Type}.
* As with the compositional approach, there are model-part specific annotations for specifying
* custom-types as well.
* <li>
* A basic type is a composition of a {@link org.hibernate.type.descriptor.java.JavaType}
* with a {@link org.hibernate.type.descriptor.jdbc.JdbcType}, and possibly a JPA
* {@link jakarta.persistence.AttributeConverter}, and the process of composition is
* usually somewhat implicit. A program may influence the choice of {@code JavaType}
* or {@code JdbcType} using any of the following annotations:
* <ul>
* <li>{@link org.hibernate.annotations.JavaType}
* <li>{@link org.hibernate.annotations.JdbcType}
* <li>{@link org.hibernate.annotations.JdbcTypeCode}
* <li>{@link org.hibernate.annotations.Mutability}
* <li>{@link jakarta.persistence.Convert}
* <li>{@link jakarta.persistence.Lob}
* <li>{@link jakarta.persistence.Enumerated}
* <li>{@link jakarta.persistence.Temporal}
* <li>{@link org.hibernate.annotations.Nationalized}
* </ul>
* Note that {@link org.hibernate.annotations.JavaType}, {@link org.hibernate.annotations.JdbcType},
* {@link org.hibernate.annotations.JdbcTypeCode} and {@link org.hibernate.annotations.Mutability}
* all come in specialized flavors for handling map keys, list indexes, and so on.
* <li>
* Alternatively, a program may implement the {@link org.hibernate.usertype.UserType}
* interface and associate it with a field or property explicitly using the
* {@link org.hibernate.annotations.Type @Type} annotation, or implicitly using the
* {@link org.hibernate.annotations.TypeRegistration @TypeRegistration} annotation.
* There are some specialized flavors of the {@code @Type} annotation too.
* </li>
* </ul>
* These two approaches are not intended to be mixed. Specifying a custom-type takes precedence over
* the compositional approach. Although the compositional approach is recommended, both forms are
* fully supported.
* <p>
* Please see the user guide for a more in-depth discussion.
* These two approaches cannot be used together. A {@code UserType} always takes precedence
* over the compositional approach.
* <p>
* Please see the User Guide for a more in-depth discussion.
*/
package org.hibernate.annotations;

2
hibernate-core/src/main/java/org/hibernate/boot/archive/spi/ArchiveDescriptor.java
View File

@ -13,7 +13,7 @@ package org.hibernate.boot.archive.spi;
* <li>an exploded directory</li>
* <li>etc</li>
* </ul>
* <p/>
* <p>
* Used mainly for scanning purposes via {@linkplain #visitArchive visitation}
*
* @author Steve Ebersole

1
hibernate-core/src/main/java/org/hibernate/boot/model/internal/BinderHelper.java
View File

@ -119,6 +119,7 @@ public class BinderHelper {
* the model that aggregates these properties and is considered
* the target of the association.
* </ul>
* <p>
* Certain limitations arise from the way this solution is currently
* implemented: for example, if a referenced column belongs to a
* property of an {@code @Embeddable}, then every column of that

4
hibernate-core/src/main/java/org/hibernate/boot/model/internal/ComponentPropertyHolder.java
View File

@ -35,7 +35,7 @@ import static org.hibernate.boot.model.internal.HCANNHelper.hasAnnotation;
import static org.hibernate.internal.util.StringHelper.isEmpty;
/**
* PropertyHolder for composites (Embeddable/Embedded).
* {@link PropertyHolder} for composites (Embeddable/Embedded).
* <p>
* To facilitate code comments, I'll often refer to this example:
* <pre>
@ -56,7 +56,7 @@ import static org.hibernate.internal.util.StringHelper.isEmpty;
* public Address homeAddress;
* }
* </pre>
*
* <p>
* As you can see, lots of ways to specify the conversion for embeddable attributes :(
*
* @author Steve Ebersole

1
hibernate-core/src/main/java/org/hibernate/boot/model/naming/PhysicalNamingStrategy.java
View File

@ -19,6 +19,7 @@ import org.hibernate.engine.jdbc.env.spi.JdbcEnvironment;
* <li>A <em>logical name</em> is a name used to within annotations of Java
* code and XML mapping documents.
* </ul>
* <p>
* Logical names provide an additional level of indirection between the mappings
* and the database schema, and a {@code PhysicalNamingStrategy} even allows the
* use of more "natural" naming within the mappings in cases where the relational

6
hibernate-core/src/main/java/org/hibernate/boot/model/relational/Database.java
View File

@ -91,13 +91,13 @@ public class Database {
}
/**
* Wrap the raw name of a database object in it's Identifier form accounting for quoting from
* Wrap the raw name of a database object in its Identifier form accounting for quoting from
* any of:<ul>
* <li>explicit quoting in the name itself</li>
* <li>global request to quote all identifiers</li>
* </ul>
* <p>
* NOTE : quoting from database keywords happens only when building physical identifiers
*
* @implNote Quoting from database keywords happens only when building physical identifiers.
*
* @param text The raw object name
*

4
hibernate-core/src/main/java/org/hibernate/boot/model/source/spi/RelationalValueSourceContainer.java
View File

@ -17,10 +17,10 @@ import java.util.List;
* <li>plural attribute mappings</li>
* <li>etc</li>
* </ul>
*
* <p>
* Not only does it provide access to the relational value sources ({@link #getRelationalValueSources()}, it also defines
* contextual information for those sources in terms of default values.
*
* <p>
* See {@link RelationalValueSource} for additional details.
*
* @author Steve Ebersole

2
hibernate-core/src/main/java/org/hibernate/cache/spi/DomainDataRegion.java vendored
View File

@ -18,12 +18,14 @@ import org.hibernate.metamodel.model.domain.NavigableRole;
* <li>the destructured state of entity instances and collections, and
* <li>mappings from natural id to primary key.
* </ul>
* <p>
* This type of data has:
* <ul>
* <li>key and value wrapping that should to be applied, and
* <li>defined policies for managing concurrent data access, possibly
* including some form of locking.
* </ul>
* <p>
* These behaviors are defined by an instance of {@link EntityDataAccess},
* {@link CollectionDataAccess}, or {@link NaturalIdDataAccess}).
*

2
hibernate-core/src/main/java/org/hibernate/cache/spi/RegionFactory.java vendored
View File

@ -29,11 +29,13 @@ import org.hibernate.service.spi.Stoppable;
* <li>{@linkplain #buildTimestampsRegion timestamps} used to
* determine when a cached query result set is stale.
* </ul>
* <p>
* Implementors should define a constructor in one of two forms:
* <ul>
* <li>{@code MyRegionFactoryImpl(java.util.Properties)}</li>
* <li>{@code MyRegionFactoryImpl()}</li>
* </ul>
* <p>
* Use the first when we need to read config properties prior to
* {@link #start} being called.
* <p>

1
hibernate-core/src/main/java/org/hibernate/cache/spi/access/NaturalIdDataAccess.java vendored
View File

@ -18,6 +18,7 @@ import org.hibernate.persister.entity.EntityPersister;
* <li><b>DELETES</b> : {@link #lockItem} -> {@link #remove} -> {@link #unlockItem}</li>
* <li><b>LOADS</b> : {@link #putFromLoad}</li>
* </ul>
* <p>
* Note the special case of <b>UPDATES</b> above. Because the cache key itself has changed here we need to remove the
* old entry as well
* <p>

1
hibernate-core/src/main/java/org/hibernate/cache/spi/access/package-info.java vendored
View File

@ -24,6 +24,7 @@
* item.
* </li>
* </ul>
* <p>
* The <i>asynchronous</i> access strategies are: {@link org.hibernate.cache.spi.access.AccessType#READ_ONLY read-only},
* {@link org.hibernate.cache.spi.access.AccessType#READ_WRITE read-write} and
* {@link org.hibernate.cache.spi.access.AccessType#NONSTRICT_READ_WRITE nonstrict-read-write}. The only

1
hibernate-core/src/main/java/org/hibernate/cache/spi/support/package-info.java vendored
View File

@ -22,6 +22,7 @@
* <li>{@link org.hibernate.cache.spi.support.RegionFactoryTemplate#createTimestampsRegionStorageAccess}
* </ul>
* </ol>
* <p>
* Voila! Functioning cache provider.
* <p>
* The preferred approach to "provide an integration" is through a custom

17
hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
View File

@ -401,6 +401,7 @@ public interface AvailableSettings {
* <li>an instance of {@link javax.sql.DataSource}, or
* <li>a JNDI name under which to obtain the {@link javax.sql.DataSource}.
* </ul>
* <p>
* For JNDI names, see also {@link #JNDI_CLASS}, {@link #JNDI_URL}, {@link #JNDI_PREFIX}, etc.
*
* @see javax.sql.DataSource
@ -459,6 +460,7 @@ public interface AvailableSettings {
* <li>a {@link Class} representing a class that extends {@code Dialect}, or
* <li>the name of a class that extends {@code Dialect}.
* </ul>
* <p>
* By default, Hibernate will attempt to automatically determine the dialect from the
* {@linkplain #URL JDBC URL} and JDBC metadata, so this setting is not usually necessary.
*
@ -817,6 +819,7 @@ public interface AvailableSettings {
* <li>{@code "component-path"} is an abbreviation for
* {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyComponentPathImpl}
* </ul>
* <p>
* By default, the {@code ImplicitNamingStrategy} registered under the key
* {@code "default"} is used. If no strategy is explicitly registered under that key,
* {@link org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl} is used.
@ -867,6 +870,7 @@ public interface AvailableSettings {
* <li>{@code "legacy"} is an abbreviation for
* {@link org.hibernate.boot.model.relational.ColumnOrderingStrategyLegacy}
* </ul>
* <p>
* By default, the {@linkplain org.hibernate.boot.model.relational.ColumnOrderingStrategy} registered under the key
* {@code "default"} is used. If no strategy is explicitly registered under that key,
* {@link org.hibernate.boot.model.relational.ColumnOrderingStrategyStandard} is used.
@ -924,7 +928,6 @@ public interface AvailableSettings {
* <li>the (case insensitive) name of a {@code CollectionClassification} (list e.g.)
* <li>a {@link Class} representing either {@link java.util.List} or {@link java.util.Collection}
* </ul>
* <p>
*
* @since 6.0
*/
@ -1049,7 +1052,7 @@ public interface AvailableSettings {
String BATCH_STRATEGY = "hibernate.jdbc.factory_class";
/**
* When enabled, specifies that {@link jakarta.persistence.Version versioned}
* When enabled, specifies that {@linkplain jakarta.persistence.Version versioned}
* data should be included in batching.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyJdbcBatchingForVersionedEntities(boolean)
@ -1069,6 +1072,7 @@ public interface AvailableSettings {
* <li>an instance of {@link java.time.ZoneId}, or
* <li>a time zone ID string to be passed to {@link java.time.ZoneId#of(String)}.
* </ul>
* <p>
* By default, the {@linkplain java.util.TimeZone#getDefault() JVM default time zone}
* is assumed by the JDBC driver.
*
@ -1101,6 +1105,7 @@ public interface AvailableSettings {
* or
* <li>the name of one of its instances.
* </ul>
* <p>
* The default is {@code DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION}.
*
* @see org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode
@ -1367,6 +1372,7 @@ public interface AvailableSettings {
* <li>a {@link Class} implementing {@link org.hibernate.cache.spi.RegionFactory}, or
* <li>he name of a class implementing {@link org.hibernate.cache.spi.RegionFactory}.
* </ul>
* <p>
* Defaults to {@link NoCachingRegionFactory}, so that caching is disabled.
*
* @see #USE_SECOND_LEVEL_CACHE
@ -2053,6 +2059,7 @@ public interface AvailableSettings {
* <li>a {@link Class} representing a class that implements {@code Interceptor}, or
* <li>the name of a class that implements {@code Interceptor}.
* </ul>
* <p>
* This setting identifies an {@code Interceptor} which is effectively a singleton
* across all the sessions opened from the {@code SessionFactory} to which it is
* applied; the same instance will be passed to each {@code Session}. If there
@ -2074,6 +2081,7 @@ public interface AvailableSettings {
* <li>the name of a class that implements {@code Interceptor}, or
* <li>an instance of {@link Supplier} used to obtain the interceptor.
* </ul>
* <p>
* Note that this setting cannot specify an {@code Interceptor} instance.
* <p>
* This setting identifies an {@code Interceptor} implementation that is to be
@ -2303,6 +2311,7 @@ public interface AvailableSettings {
* setting requires DEBUG logging be enabled for
* {@link org.hibernate.event.internal.EntityCopyAllowedLoggedObserver}.
* </ul>
* <p>
* Alternatively, the application may customize the behavior by providing an
* implementation of {@link org.hibernate.event.spi.EntityCopyObserver} and setting
* the property {@value #MERGE_ENTITY_COPY_OBSERVER} to the class name.
@ -2328,6 +2337,7 @@ public interface AvailableSettings {
* <li>The {@link org.hibernate.query.criteria.ValueHandlingMode#INLINE "inline"}
* mode inlines values as SQL literals.
* </ul>
* <p>
* The default value is {@link org.hibernate.query.criteria.ValueHandlingMode#BIND}.
*
* @since 6.0.0
@ -2580,6 +2590,7 @@ public interface AvailableSettings {
* <li>{@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#EXCEPTION "exception"}
* specifies that a {@link org.hibernate.HibernateException} should be thrown.
* </ul>
* <p>
* By default, a warning is logged.
*
* @since 5.2.17
@ -2705,6 +2716,7 @@ public interface AvailableSettings {
* <li>the name of a class that implements {@code FormatMapper}, or
* <li>one of the shorthand constants {@code jackson} or {@code jsonb}.
* </ul>
* <p>
* By default, the first of the possible providers that is available at runtime is
* used, according to the listing order.
*
@ -2721,6 +2733,7 @@ public interface AvailableSettings {
* <li>the name of a class that implements {@code FormatMapper}, or
* <li>one of the shorthand constants {@code jackson} or {@code jaxb}.
* </ul>
* <p>
* By default, the first of the possible providers that is available at runtime is
* used, according to the listing order.
*

6
hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java
View File

@ -72,11 +72,12 @@ import jakarta.persistence.SharedCacheMode;
* <li>entity O/R mappings, defined in either {@linkplain #addAnnotatedClass
* annotated classes}, or {@linkplain #addFile XML mapping documents}.
* </ul>
* <p>
* Note that XML mappings may be expressed using the JPA {@code orm.xml}
* format, or in Hibernate's legacy {@code .hbm.xml} format.
* <p>
* Configuration properties are enumerated by {@link AvailableSettings}.
* <pre>{@code
* <pre>
* SessionFactory factory = new Configuration()
* // scan classes for mapping annotations
* .addAnnotatedClass(Item.class)
@ -88,7 +89,8 @@ import jakarta.persistence.SharedCacheMode;
* .setProperty(AvailableSettings.DATASOURCE,
* "java:comp/env/jdbc/test")
* .getSessionFactory();
* }</pre>
* </pre>
* <p>
* In addition, there are convenience methods for adding
* {@link #addAttributeConverter attribute converters},
* {@link #registerTypeContributor type contributors},

1
hibernate-core/src/main/java/org/hibernate/cfg/Environment.java
View File

@ -34,6 +34,7 @@ import static org.hibernate.internal.log.DeprecationLogger.DEPRECATION_LOGGER;
* <li><em>System-level</em> properties are shared by all factory instances and are
* always determined by the {@code Environment} properties in {@link #getProperties()}.
* </ul>
* <p>
* The only system-level properties are {@value #USE_REFLECTION_OPTIMIZER} and
* {@value #BYTECODE_PROVIDER}.
* <p>

3
hibernate-core/src/main/java/org/hibernate/context/internal/ManagedSessionContext.java
View File

@ -33,9 +33,10 @@ import org.hibernate.engine.spi.SessionFactoryImplementor;
* current session it is scoping. This portion is static to allow easy
* reference from that external thing.
* </ul>
* <p>
* The underlying storage of the current sessions here is a static
* {@link ThreadLocal}-based map where the sessions are keyed by the
* the owning session factory.
* owning session factory.
*
* @author Steve Ebersole
*/

2
hibernate-core/src/main/java/org/hibernate/dialect/DerbyDialect.java
View File

@ -867,7 +867,7 @@ public class DerbyDialect extends Dialect {
* <pre>
* The DECLARE GLOBAL TEMPORARY TABLE statement defines a temporary table for the current connection.
* </pre>
*
* <p>
* {@link DB2Dialect} returns a {@link GlobalTemporaryTableMutationStrategy} that
* will make temporary tables created at startup and hence unavailable for subsequent connections.<br/>
* see HHH-10238.

2
hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java
View File

@ -254,6 +254,7 @@ import static org.hibernate.type.descriptor.DateTimeUtils.appendAsTimestampWithN
* mappings for standard HQL functions with the
* {@link org.hibernate.query.sqm.function.SqmFunctionRegistry}.
* </ul>
* <p>
* A subclass representing a dialect of SQL which deviates significantly
* from ANSI SQL will certainly override many additional operations.
* <p>
@ -4410,6 +4411,7 @@ public abstract class Dialect implements ConversionContext {
* <li>s: seconds</li>
* <li>z,Z,x: timezone offset</li>
* </ul>
* <p>
* In addition, punctuation characters and
* single-quoted literal strings are accepted.
* <p>

12
hibernate-core/src/main/java/org/hibernate/dialect/TypeNames.java
View File

@ -25,36 +25,32 @@ import java.util.TreeMap;
* unmarked default type otherwise.
* <p>
* For example, setting:
*
* <pre>
* names.put( type, "TEXT" );
* names.put( type, 255, "VARCHAR($l)" );
* names.put( type, 65534, "LONGVARCHAR($l)" );
* </pre>
*
* <p>
* will give you back the following:
*
* <pre>
* names.get( type ) // --> "TEXT" (default)
* names.get( type, 100 ) // --> "VARCHAR(100)" (100 is in [0:255])
* names.get( type, 1000 ) // --> "LONGVARCHAR(1000)" (1000 is in [256:65534])
* names.get( type, 100000 ) // --> "TEXT" (default)
* </pre>
*
* <p>
* On the other hand, simply putting:
*
* <pre>
* names.put( type, "VARCHAR($l)" );
* </pre>
*
* <p>
* would result in:
*
* <pre>
* names.get( type ) // --> "VARCHAR($l)" (will cause trouble)
* names.get( type, 100 ) // --> "VARCHAR(100)"
* names.get( type, 10000 ) // --> "VARCHAR(10000)"
* </pre>
*
* <p>
* Registered type names may contain the placemarkers {@code $l}, {@code $p},
* and {@code $s}, which will be replaced by the length, precision, and size
* passed to {@link #get(int, Long, Integer, Integer)}.

1
hibernate-core/src/main/java/org/hibernate/dialect/package-info.java
View File

@ -17,6 +17,7 @@
* in this package in order to customize certain aspects of
* the SQL generated by Hibernate.
* </ul>
* <p>
* A concrete {@code Dialect} may be explicitly selected using
* {@value org.hibernate.cfg.AvailableSettings#DIALECT}, but
* this is not usually necessary unless a program uses a custom

2
hibernate-core/src/main/java/org/hibernate/dialect/pagination/SQLServer2005LimitHandler.java
View File

@ -69,7 +69,7 @@ public class SQLServer2005LimitHandler extends AbstractLimitHandler {
* select [alias-list] from query_
* where rownumber_ &gt;= ? and rownumber_ &lt; ?
* </pre>
*
* <p>
* Where {@code [original-query]} is the original SQL query, with a
* {@code top()} clause added iff the query has an {@code order by}
* clause, and with generated aliases added to any elements of the

1
hibernate-core/src/main/java/org/hibernate/dialect/unique/CreateTableUniqueDelegate.java
View File

@ -24,6 +24,7 @@ import org.hibernate.mapping.UniqueKey;
* <li>For unique keys with no explicit name, it results in {@code unique(x, y)} after the
* column list.
* </ul>
* <p>
* Counterintuitively, this class extends {@link AlterTableUniqueDelegate}, since it falls back
* to using {@code alter table} for {@linkplain org.hibernate.tool.schema.spi.SchemaMigrator
* schema migration}.

1
hibernate-core/src/main/java/org/hibernate/dialect/unique/UniqueDelegate.java
View File

@ -65,6 +65,7 @@ public interface UniqueDelegate {
* Get the SQL fragment used to specify the unique constraints on the given table as part of
* the {@code create table} command, with a leading comma, usually something like:
* <pre>{@code , unique(x,y), constraint abc unique(a,b,c)}</pre>
* <p>
* or return an empty string if there are no unique constraints or if the unique constraints
* do not belong in the table definition.
* <p>

1
hibernate-core/src/main/java/org/hibernate/engine/internal/AbstractEntityEntry.java
View File

@ -73,6 +73,7 @@ public abstract class AbstractEntityEntry implements Serializable, EntityEntry {
*
* 0000 0000 | 0000 0000 | 0654 3333 | 2222 1111
* </pre>
* <p>
* Use {@link #setCompressedValue(EnumState, Enum)},
* {@link #getCompressedValue(EnumState)} etc
* to access the enums and booleans stored in this value.

1
hibernate-core/src/main/java/org/hibernate/engine/internal/EntityEntryContext.java
View File

@ -42,7 +42,6 @@ import static org.hibernate.engine.internal.ManagedTypeHelper.isManagedEntity;
* either directly or through bytecode enhancement.
* </li>
* </ul>
* <p>
*
* @author Steve Ebersole
*/

4
hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/MutationStatementPreparer.java
View File

@ -26,10 +26,12 @@ public interface MutationStatementPreparer {
/**
* Prepare an INSERT statement, specifying how auto-generated (by the database) keys should be handled. Really this
* is a boolean, but JDBC opted to define it instead using 2 int constants:<ul>
* is a boolean, but JDBC opted to define it instead using 2 int constants:
* <ul>
* <li>{@link PreparedStatement#RETURN_GENERATED_KEYS}</li>
* <li>{@link PreparedStatement#NO_GENERATED_KEYS}</li>
* </ul>
* <p>
* Generated keys are accessed afterwards via {@link PreparedStatement#getGeneratedKeys}
*
* @param sql The INSERT SQL

4
hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/StatementPreparer.java
View File

@ -46,10 +46,12 @@ public interface StatementPreparer {
/**
* Prepare an INSERT statement, specifying how auto-generated (by the database) keys should be handled. Really this
* is a boolean, but JDBC opted to define it instead using 2 int constants:<ul>
* is a boolean, but JDBC opted to define it instead using 2 int constants:
* <ul>
* <li>{@link PreparedStatement#RETURN_GENERATED_KEYS}</li>
* <li>{@link PreparedStatement#NO_GENERATED_KEYS}</li>
* </ul>
* <p>
* Generated keys are accessed afterwards via {@link PreparedStatement#getGeneratedKeys}
*
* @param sql The INSERT SQL

1
hibernate-core/src/main/java/org/hibernate/engine/spi/EntityEntry.java
View File

@ -115,6 +115,7 @@ public interface EntityEntry {
* <li>the entity is not read-only</li>
* <li>if the current status is Status.DELETED, then the entity was not read-only when it was deleted</li>
* </ul>
*
* @return true, if the entity is modifiable; false, otherwise,
*/
boolean isModifiableEntity();

2
hibernate-core/src/main/java/org/hibernate/engine/spi/LoadQueryInfluencers.java
View File

@ -22,7 +22,7 @@ import org.hibernate.loader.ast.spi.CascadingFetchProfile;
/**
* Centralize all options which can influence the SQL query needed to load an
* entity. Currently such influencers are defined as:<ul>
* entity. Currently, such influencers are defined as:<ul>
* <li>filters</li>
* <li>fetch profiles</li>
* <li>internal fetch profile (merge profile, etc)</li>

1
hibernate-core/src/main/java/org/hibernate/engine/spi/SharedSessionContractImplementor.java
View File

@ -287,6 +287,7 @@ public interface SharedSessionContractImplementor
* though it might return an existing proxy; if it does not exist, a
* {@code null} value is returned.
* </ul>
* <p>
* When {@code eager = true}, the object is eagerly fetched from the database.
*/
Object internalLoad(String entityName, Object id, boolean eager, boolean nullable)

2
hibernate-core/src/main/java/org/hibernate/event/spi/MergeContext.java
View File

@ -26,6 +26,7 @@ import org.hibernate.pretty.MessageHelper;
* <li>A <em>managed entity</em> (the {@code managedEntity} method parameter) is
* the managed entity that is the result of merging an entity.
* </ul>
* <p>
* A merge entity can be transient, detached, or managed. If it is managed, then
* it is identical to its resulting managed entity.
* <p>
@ -53,6 +54,7 @@ import org.hibernate.pretty.MessageHelper;
* <li>The map returned by {@link #invertMap()} will only contain the "newest"
* (most recently added) managed-to-merge cross-reference to its merge entity.
* </ul>
* <p>
* The following method is intended to be used by an implementation of
* {@link org.hibernate.event.spi.MergeEventListener} to add a merge entity and its
* corresponding managed entity to a {@code MergeContext} and indicate if the merge

5
hibernate-core/src/main/java/org/hibernate/generator/AnnotationBasedGenerator.java
View File

@ -21,10 +21,11 @@ import java.lang.reflect.Member;
* <p>
* For example, implementing {@code AnnotationBasedGenerator<AnnotationType>} is the
* same as providing a constructor with this signature:
* <pre>{@code
* <pre>
* public GeneratorClass(AnnotationType config, Member idMember,
* CustomIdGeneratorCreationContext creationContext)
* }</pre>
* </pre>
* <p>
* where {@code GeneratorClass} is the class that implements {@code Generator}, and
* {@code AnnotationType} is the generator annotation type used to configure the
* generator.

1
hibernate-core/src/main/java/org/hibernate/generator/BeforeExecutionGenerator.java
View File

@ -26,6 +26,7 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
* <li>the meta-annotation {@link org.hibernate.annotations.IdGeneratorType} or
* <li>the annotation {@link org.hibernate.annotations.GenericGenerator}.
* </ul>
* <p>
* On the other hand, generators for regular fields and properties may be integrated using
* {@link org.hibernate.annotations.ValueGenerationType}, as for any {@link Generator}.
*

2
hibernate-core/src/main/java/org/hibernate/generator/Generator.java
View File

@ -34,6 +34,7 @@ import static org.hibernate.generator.EventType.UPDATE;
* SQL {@code select}, though in certain cases this additional round trip may be avoided.
* An important example is id generation using an identity column.
* </ul>
* <p>
* Generically, a generator may be integrated with the program using the meta-annotation
* {@link org.hibernate.annotations.ValueGenerationType}, which associates the generator with
* a Java annotation type, called the <em>generator annotation</em>. A generator may receive
@ -45,6 +46,7 @@ import static org.hibernate.generator.EventType.UPDATE;
* <li>declare a constructor which accepts just the annotation instance, or
* <li>declare a only default constructor, in which case it will not receive parameters.
* </ul>
* <p>
* A generator must implement {@link #getEventTypes()} to specify the events for which it should be
* called to produce a new value. {@link EventTypeSets} provides a convenient list of possibilities.
* <p>

1
hibernate-core/src/main/java/org/hibernate/generator/OnExecutionGenerator.java
View File

@ -107,6 +107,7 @@ public interface OnExecutionGenerator extends Generator {
* <li>a second unique key of the entity, that is, a property annotated
* {@link org.hibernate.annotations.NaturalId @NaturalId}.
* </ul>
* <p>
* Alternatively, if the generated id is an identity/"autoincrement" column, we can take
* advantage of special platform-specific functionality to retrieve it. Taking advantage
* of the specialness of identity columns is the job of one particular implementation:

1
hibernate-core/src/main/java/org/hibernate/generator/internal/VersionGeneration.java
View File

@ -25,6 +25,7 @@ import static org.hibernate.generator.EventTypeSets.INSERT_AND_UPDATE;
* <li>{@link org.hibernate.type.descriptor.java.VersionJavaType#seed} to seed an initial version, and
* <li>{@link org.hibernate.type.descriptor.java.VersionJavaType#next} to increment a version.
* </ul>
* <p>
* Thus, this implementation reproduces the "classic" behavior of Hibernate. A custom generator specified
* using a {@linkplain org.hibernate.annotations.ValueGenerationType generator annotation} will override
* this implementation, allowing customized versioning.

1
hibernate-core/src/main/java/org/hibernate/id/IdentifierGenerator.java
View File

@ -50,6 +50,7 @@ import static org.hibernate.generator.EventTypeSets.INSERT_ONLY;
* <li>{@linkplain org.hibernate.annotations.Parameter parameters} specified
* using {@link org.hibernate.annotations.GenericGenerator#parameters()}.
* </ul>
* <p>
* Instances of {@code IdentifierGenerator} are usually created and configured
* by the {@link org.hibernate.id.factory.IdentifierGeneratorFactory} service.
* It is not usually correct to use an {@code IdentifierGenerator} with the

25
hibernate-core/src/main/java/org/hibernate/id/SelectGenerator.java
View File

@ -25,39 +25,42 @@ import static org.hibernate.generator.internal.NaturalIdHelper.getNaturalIdPrope
* <li>the mapped {@linkplain org.hibernate.annotations.NaturalId} of the entity, or
* <li>a property specified using the parameter named {@code "key"}.
* </ul>
* <p>
* The second approach is provided for backward compatibility with older versions of
* Hibernate.
* <p>
* This generator is intended for use with primary keys assigned by a database trigger
* or something similar, for example:
* <pre>{@code
* @Entity @Table(name="TableWithPKAssignedByTrigger")
* @GenericGenerator(name = "triggered", type = SelectGenerator.class)
* <pre>
* &#64;Entity &#64;Table(name="TableWithPKAssignedByTrigger")
* &#64;GenericGenerator(name = "triggered", type = SelectGenerator.class)
* public class TriggeredEntity {
* @Id @GeneratedValue(generator = "triggered")
* &#64;Id @GeneratedValue(generator = "triggered")
* private Long id;
*
* @NaturalId
* &#64;NaturalId
* private String name;
*
* ...
* }
* }</pre>
* </pre>
* <p>
* However, after a very long working life, this generator is now handing over its
* work to {@link org.hibernate.generator.internal.GeneratedGeneration}, and the
* above code may be written as:
* <pre>{@code
* @Entity @Table(name="TableWithPKAssignedByTrigger")
* <pre>
* &#64;Entity &#64;Table(name="TableWithPKAssignedByTrigger")
* public class TriggeredEntity {
* @Id @Generated
* &#64;Id &#64;Generated
* private Long id;
*
* @NaturalId
* &#64;NaturalId
* private String name;
*
* ...
* }
* }</pre>
* </pre>
* <p>
* For tables with identity/autoincrement columns, use {@link IdentityGenerator}.
* <p>
* The actual work involved in retrieving the primary key value is the job of

1
hibernate-core/src/main/java/org/hibernate/id/UUIDGenerationStrategy.java
View File

@ -27,6 +27,7 @@ public interface UUIDGenerationStrategy extends Serializable {
* <li>4 = random numbers based</li>
* <li>5 = name based (sha-1 hash)</li>
* </ul>
* <p>
* Returning the values above should be reserved to those generators creating variants compliant with the
* corresponding RFC definition; others can feel free to return other values as they see fit.
* <p>

2
hibernate-core/src/main/java/org/hibernate/id/UUIDGenerator.java
View File

@ -32,7 +32,7 @@ import org.hibernate.type.descriptor.java.UUIDJavaType;
* <li>{@link #UUID_GEN_STRATEGY_CLASS} - names the {@link UUIDGenerationStrategy} class to use</li>
* </ul>
* <p>
* Currently there are 2 standard implementations of {@link UUIDGenerationStrategy}:<ul>
* Currently, there are 2 standard implementations of {@link UUIDGenerationStrategy}:<ul>
* <li>{@link StandardRandomStrategy} (the default, if none specified)</li>
* <li>{@link org.hibernate.id.uuid.CustomVersionOneStrategy}</li>
* </ul>

1
hibernate-core/src/main/java/org/hibernate/id/factory/IdentifierGeneratorFactory.java
View File

@ -35,6 +35,7 @@ import jakarta.persistence.GenerationType;
* by the {@code @GenericGenerator} annotation, or
* <li>a JPA-defined {@link GenerationType}.
* </ul>
* <p>
* A new generator passed a {@link Properties} object containing parameters via the
* method {@link IdentifierGenerator#configure(Type, Properties, ServiceRegistry)}.
* <p>

1
hibernate-core/src/main/java/org/hibernate/id/insert/InsertGeneratedIdentifierDelegate.java
View File

@ -30,6 +30,7 @@ import org.hibernate.sql.model.ast.builder.TableInsertBuilder;
* <li>building the SQL {@code insert} statement, and
* <li>retrieving the generated identifier value using JDBC.
* </ul>
* <p>
* The implementation should be written to handle any instance of
* {@link org.hibernate.generator.OnExecutionGenerator}.
*

1
hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java
View File

@ -142,6 +142,7 @@ import static java.util.Collections.unmodifiableSet;
* <li> delegates JDBC {@code Connection} management to the {@code ConnectionProvider}
* <li>factory for instances of {@code SessionImpl}
* </ul>
* <p>
* This class must appear immutable to clients, even if it does all kinds of caching
* and pooling under the covers. It is crucial that the class is not only thread
* safe, but also highly concurrent. Synchronization must be used extremely sparingly.

1
hibernate-core/src/main/java/org/hibernate/jpa/package-info.java
View File

@ -17,6 +17,7 @@
* default (something Hibernate only does if it has a really good
* reason to do so).
* </ul>
* <p>
* Enumerates the {@linkplain jakarta.persistence.Query#setHint hints}
* recognized by Hibernate:
* <ul>

Some files were not shown because too many files have changed in this diff Show More