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

Javadoc for various annotations

This commit is contained in:
Gavin King 2022-01-22 20:24:57 +01:00
parent 766483e46d
commit b189d4e9c4
21 changed files with 149 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -5,10 +5,12 @@
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
*/
package org.hibernate.annotations;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import jakarta.persistence.Column;
import jakarta.persistence.FetchType;
import jakarta.persistence.Inheritance;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
@ -18,26 +20,28 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* Maps a discriminated to-one style associations pointing to one of several entity types
* depending on a local discriminator, as opposed to discriminated inheritance where the
* discriminator is kept as part of the entity hierarchy (see {@link jakarta.persistence.Inheritance}
* and {@link jakarta.persistence.InheritanceType#SINGLE_TABLE} for details about discriminated inheritance
* mappings).
*
* For example, if you consider an Order entity containing Payment information where Payment might be of type
* CashPayment or CreditCardPayment the @Any approach would be to keep that discriminator and matching value on the
* Order itself. Thought of another way, the "foreign-key" really is made up of the value and discriminator.
*
* Use {@link Column} or {@link Formula} to define the "column" to which the discriminator is mapped.
*
* Use {@link jakarta.persistence.JoinColumn} to describe the key column
*
* Use {@link AnyDiscriminator}, {@link JdbcType} or {@link JdbcTypeCode} to describe the mapping for the discriminator
*
* Use {@link AnyKeyJavaType}, {@link AnyKeyJavaClass}, {@link AnyKeyJdbcType} or {@link AnyKeyJdbcTypeCode} to describe the mapping for the key
*
* Use {@link AnyDiscriminatorValues} to specify the discriminator {@code <->} entity mappings
*
* and {@link jakarta.persistence.InheritanceType#SINGLE_TABLE} for details about discriminated
* inheritance mappings).
* <p>
* For example, if you consider an {@code Order} entity containing {@code Payment} information
* where {@code Payment} might be of type {@code CashPayment} or {@code CreditCardPayment},
* the {@code @Any} approach would be to keep that discriminator and matching value on the
* {@code Order} itself. Thought of another way, the "foreign key" is really made up of the
* value and discriminator.
* <ul>
* <li>Use {@link Column} or {@link Formula} to define the "column" to which the
* discriminator is mapped.
* <li>Use {@link jakarta.persistence.JoinColumn} to describe the key column
* <li>Use {@link AnyDiscriminator}, {@link JdbcType} or {@link JdbcTypeCode} to
* describe the mapping for the discriminator
* <li>Use {@link AnyKeyJavaType}, {@link AnyKeyJavaClass}, {@link AnyKeyJdbcType}
* or {@link AnyKeyJdbcTypeCode} to describe the mapping for the key
* <li>Use {@link AnyDiscriminatorValues} to specify how discriminator values map
* to entity types
* </ul>
* @see ManyToAny
*/
@java.lang.annotation.Target({METHOD, FIELD})
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Any {
/**
@ -49,7 +53,9 @@ public @interface Any {
FetchType fetch() default FetchType.EAGER;
/**
* Whether the association is optional. If set to false then a non-null relationship must always exist.
* Whether the association is optional.
*
* If set to false then a non-null relationship must always exist.
*/
boolean optional() default true;
}

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

@ -15,22 +15,26 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Defines size for batch loading of collections or lazy entities. For example...
* <blockquote><pre>{@code
* Specifies a batch size for batch fetching of the annotated entity or
* collection.
* <p>
* For example:
* <pre>{@code
* @Entity
* @BatchSize(size=100)
* @BatchSize(size = 100)
* class Product {
* ...
* }
* }</pre></blockquote>
* will initialize up to 100 lazy Product entity proxies at a time.
*
* <blockquote><pre>{@code
* }</pre>
* will initialize up to 100 lazy Product entity proxies at a time, but:
* <pre>{@code
* @OneToMany
* @BatchSize(size = 5) /
* Set<Product> getProducts() { ... };
* }</pre></blockquote>
* will initialize up to 5 lazy collections of products at a time
* }</pre>
* will initialize up to 5 lazy collections of products at a time.
*
* @see org.hibernate.cfg.AvailableSettings#DEFAULT_BATCH_FETCH_SIZE
*
* @author Emmanuel Bernard
* @author Steve Ebersole

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

@ -16,6 +16,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Add caching strategy to a root entity or a collection.
*
* @see jakarta.persistence.Cacheable
*
* @author Emmanuel Bernard
*/
@Target({TYPE, METHOD, FIELD})

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

@ -18,10 +18,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Describe an identifier column for a bag (ie an idbag).
* Describe an identifier column for a bag.
*
* EXPERIMENTAL: the structure of this annotation might slightly change (generator() mix strategy and generator
*
* @author Emmanuel Bernard
*/
@Target({METHOD, FIELD})
@ -42,10 +40,11 @@ public @interface CollectionId {
/**
* The generator name.
*
* Can specify either a built-in strategy ("sequence", e.g.) or a named generatorIdentifierGenerator
* Can specify either a built-in strategy ("sequence", e.g.)
* or a named generatorIdentifierGenerator
* ({@link jakarta.persistence.SequenceGenerator}, e.g.)
*
* @apiNote Mutually exclusive with {@link #generatorImplementation()} ()}
* @apiNote Mutually exclusive with {@link #generatorImplementation()}
*/
String generator() default "";
}

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

@ -19,9 +19,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* {@code @ColumnDefault} may be used in combination with:
* <ul>
* <li>{@code DynamicInsert}, to let the database fill in the value of
* a null entity attribute, or
* a null entity attribute, or
* <li>{@code @Generated(INSERT)}, to populate an entity attribute with
* the defaulted value of a database column.
* the defaulted value of a database column.
* </ul>
*
* @author Steve Ebersole

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

@ -15,8 +15,8 @@ import java.lang.annotation.Target;
import org.hibernate.tuple.GenerationTiming;
/**
* Specifies to use the database `current_timestamp` function for generating
* values for the associated attribute based on {@link #timing()}
* Specifies that the database {@code current_timestamp} function is used to
* generate values of the annotated attribute, based on {@link #timing()}.
*
* @see CurrentTimestampGeneration
*

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

@ -13,10 +13,11 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Used to apply a Hibernate formula (derived value) as the inheritance discriminator "column". Used in place of
* the JPA {@link jakarta.persistence.DiscriminatorColumn} when a formula is wanted.
*
* To be placed on the root entity.
* Specifies an expression written in native SQL as the discriminator for an
* entity inheritance hierarchy. Must be used to annotate the root entity of
* the hierarchy.
* <p>
* Used in place of the JPA {@link jakarta.persistence.DiscriminatorColumn}.
*
* @see Formula
*

13
hibernate-core/src/main/java/org/hibernate/annotations/DynamicInsert.java
View File

@ -13,8 +13,13 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* For inserting, should this entity use dynamic sql generation where only non-null columns get referenced in the
* prepared sql statement?
* Specifies that SQL {@code insert} statements for the annotated entity
* are generated dynamically, and only include the columns to which a
* non-null value must be assigned.
* <p>
* This might result in improved performance if an entity is likely to
* have many null attributes when it is first made persistent. However,
* there is a cost associated with generating the SQL at runtime.
*
* @author Steve Ebersole
*/
@ -22,8 +27,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Retention( RUNTIME )
public @interface DynamicInsert {
/**
* Should dynamic insertion be used for this entity? {@code true} says dynamic insertion will be used.
* Default is {@code true} (since generally this annotation is not used unless the user wants dynamic insertion).
* @deprecated When {@code false}, this annotation has no effect.
*/
@Deprecated
boolean value() default true;
}

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

@ -13,10 +13,18 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* For updating, should this entity use dynamic sql generation where only changed columns get referenced in the
* prepared sql statement?
* <p/>
* Note, for re-attachment of detached entities this is not possible without select-before-update being enabled.
* Specifies that SQL {@code update} statements for the annotated entity
* are generated dynamically, and only include columns which are actually
* being updated.
* <p>
* This might result in improved performance if it is common to change
* only some of the attributes of the entity. However, there is a cost
* associated with generating the SQL at runtime.
* <p>
* When detached entities are reattached using
* {@link org.hibernate.Session#update(Object)}, the entity must also be
* annotated {@link SelectBeforeUpdate} for this annotation to have any
* effect.
*
* @author Steve Ebersole
*
@ -26,9 +34,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Retention( RUNTIME )
public @interface DynamicUpdate {
/**
* Should dynamic update generation be used for this entity? {@code true} says the update sql will be dynamic
* generated. Default is {@code true} (since generally this annotation is not used unless the user wants dynamic
* generation).
* @deprecated When {@code false}, this annotation has no effect.
*/
@Deprecated
boolean value() default true;
}

29
hibernate-core/src/main/java/org/hibernate/annotations/Nationalized.java
View File

@ -16,19 +16,22 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Used to indicate that the annotated character data should be stored with
* nationalization support.
*
* The annotation's affect depends on {@link Dialect#getNationalizationSupport()}
*
* Some databases support storing nationalized data in their "normal" character data types
* (CHAR, VARCHAR, LONGVARCHAR, CLOB). In such cases this annotation is effectively ignored.
* See {@link org.hibernate.dialect.NationalizationSupport#IMPLICIT}
*
* Some databases support storing nationalized data only through the specialized, standard SQL
* variants (NCHAR, NVARCHAR, LONGNVARCHAR, NCLOB). In such cases this annotation will adjust
* the JDBC type code to the specialized variant. See
* {@link org.hibernate.dialect.NationalizationSupport#EXPLICIT}
* Specifies that the annotated character data should be stored with
* nationalization support. The effect of this annotation depends on
* {@link Dialect#getNationalizationSupport() the SQL dialect}.
* <ul>
* <li>Some databases support storing nationalized data using their
* "normal" character data types
* ({@code CHAR, VARCHAR, LONGVARCHAR, CLOB}).
* For these dialects, this annotation is effectively ignored.
* See {@link org.hibernate.dialect.NationalizationSupport#IMPLICIT}.
* <li>Other databases support storing nationalized data only via the
* specialized, standard SQL variants
* ({@code NCHAR, NVARCHAR, LONGNVARCHAR, NCLOB)}.
* For these dialects, this annotation will adjust the JDBC type
* code to use the specialized variant.
* See {@link org.hibernate.dialect.NationalizationSupport#EXPLICIT}.
* </ul>
*
* @author Steve Ebersole
*/

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

@ -13,8 +13,8 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Used to specify that the natural id values associated with the annotated entity should be cached in Hibernate's
* shared (L2) cache. Can optionally name a custom cache region.
* Specifies that the natural id values associated with the annotated
* entity should be cached in the shared second-level cache.
*
* @author Eric Dalquist
* @author Steve Ebersole
@ -25,8 +25,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Retention(RUNTIME)
public @interface NaturalIdCache {
/**
* The cache region name. {@code null} or empty-string (the default) are interpreted as
* {@code {entity-name}##NaturalId}
* Specifies an explicit cache region name.
* <p>
* By default, the region name is {@code EntityName##NaturalId}.
*/
String region() default "";
}

13
hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLock.java
View File

@ -12,17 +12,20 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Whether or not a change of the annotated property will trigger an entity version increment.
*
* If the annotation is not present, the property is involved in the optimistic lock strategy (default).
* Specifies whether updating the annotated attribute should trigger an increment
* to the {@link jakarta.persistence.Version version} of the entity instance.
* <p>
* If this annotation is not present, updating an attribute does cause the version
* to be incremented.
*
* @author Logi Ragnarsson
*/
@Target( { ElementType.METHOD, ElementType.FIELD })
@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface OptimisticLock {
/**
* Whether the annotated property should be included in optimistic locking determinations for the owner.
* {@code true} if changing the annotated attribute should <em>not</em> cause
* the version to be incremented.
*/
boolean excluded();
}

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

@ -13,7 +13,8 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Used to define the style of optimistic locking to be applied to an entity. In a hierarchy, only valid on the
* Used to define the style of optimistic locking to be applied to an entity.
* In an inheritance hierarchy, this annotation may only be applies to the
* root entity.
*
* @author Steve Ebersole

7
hibernate-core/src/main/java/org/hibernate/annotations/ParamDef.java
View File

@ -25,12 +25,7 @@ public @interface ParamDef {
String name();
/**
* The type to be used for the parameter. See {@link Type#type} for a list of
* expected values
*
*
*
*
* The type of the parameter.
*/
String type();
}

10
hibernate-core/src/main/java/org/hibernate/annotations/RowId.java
View File

@ -7,20 +7,24 @@
package org.hibernate.annotations;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Support for {@code ROWID} mapping feature of Hibernate.
* Specifies that an Oracle-style {@code rowid} should be used in SQL
* {@code update} statements for an entity, instead of the primary key.
*
* @author Steve Ebersole
*/
@java.lang.annotation.Target( { TYPE })
@Target(TYPE)
@Retention(RUNTIME)
public @interface RowId {
/**
* Names the {@code ROWID} identifier.
* Specifies the {@code rowid} identifier.
* <p>
* For example, on Oracle, this should be just {@code "rowid"}.
*/
String value();
}

10
hibernate-core/src/main/java/org/hibernate/annotations/SelectBeforeUpdate.java
View File

@ -13,8 +13,9 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Should the entity's current state be selected from the database when determining whether to perform an update when
* re-attaching detached entities?
* Specifies that the current persistent state of a detached entity instance
* should be fetched from the database when the entity is reattached using
* {@link org.hibernate.Session#update(Object)}.
*
* @author Steve Ebersole
*/
@ -22,9 +23,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Retention( RUNTIME )
public @interface SelectBeforeUpdate {
/**
* {@code true} (which is the default when this annotation is present) indicates that
* {@code select-before-update} processing should occur. {@code false} indicates
* {@code select-before-update} processing should not occur.
* @deprecated When {@code false}, this annotation has no effect.
*/
@Deprecated
boolean value() default true;
}

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

@ -13,7 +13,7 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Map an immutable and read-only entity to a given SQL select expression.
* Maps an immutable and read-only entity to a given SQL {@code select} expression.
*
* @see Synchronize
*

7
hibernate-core/src/main/java/org/hibernate/annotations/UuidGenerator.java
View File

@ -14,6 +14,13 @@ import java.util.UUID;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
/**
* Specifies that an entity identifier is generated as an RFC 4122 UUID.
* <p>
* The type of the identifier attribute may be {@link UUID} or {@link String}.
*
* @author Steve Ebersole
*/
@IdGeneratorType( org.hibernate.id.uuid.UuidGenerator.class )
@Retention(RetentionPolicy.RUNTIME)
@Target({ FIELD, METHOD })

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

@ -15,8 +15,16 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Where clause to add to the element Entity or target entity of a collection. The clause is written in SQL.
* A common use case here is for soft-deletes.
* Specifies a restriction written in native SQL to add to the generated
* SQL when querying an entity or collection.
* <p>
* For example, {@code @Where("deleted = false")} could be used to hide
* entity instances which have been soft-deleted.
* <p>
* Note that {@code Where} restrictions are always applied and cannot be
* disabled. They're therefore much less flexible than {@link Filter filters}.
*
* @see Filter
*
* @author Emmanuel Bernard
*/
@ -24,7 +32,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Retention(RUNTIME)
public @interface Where {
/**
* The where-clause predicate.
* A predicate, written in native SQL.
*/
String clause();
}

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

@ -12,8 +12,12 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Where clause to add to the collection join table. The clause is written in SQL. Just as with
* {@link Where}, a common use case is for implementing soft-deletes.
* Specifies a restriction written in native SQL to add to the generated
* SQL when querying the {@link jakarta.persistence.JoinTable join table}
* of a collection.
* <p>
* For example, {@code @Where("deleted = false")} could be used to hide
* associations which have been soft-deleted from an association table.
*
* @author Emmanuel Bernard
*/
@ -21,7 +25,7 @@ import java.lang.annotation.Target;
@Retention(RetentionPolicy.RUNTIME)
public @interface WhereJoinTable {
/**
* The where-clause predicate.
* A predicate, written in native SQL.
*/
String clause();
}

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

@ -829,6 +829,8 @@ public interface AvailableSettings {
/**
* Specifies the default batch size for batch fetching.
*
* @see org.hibernate.annotations.BatchSize
*/
String DEFAULT_BATCH_FETCH_SIZE = "hibernate.default_batch_fetch_size";