From 34e7512c76b4634fbb264df5e71fcf5fa12d447f Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Tue, 9 Apr 2013 19:38:12 -0500 Subject: [PATCH] HHH-8159 - Apply fixups indicated by analysis tools --- build.gradle | 18 +++ .../main/java/org/hibernate/ScrollMode.java | 4 +- .../hibernate/StaleObjectStateException.java | 2 +- .../org/hibernate/action/spi/Executable.java | 7 +- .../hibernate/action/spi/package-info.java | 5 + .../org/hibernate/annotations/AccessType.java | 9 +- .../org/hibernate/annotations/AnyMetaDef.java | 5 +- .../hibernate/annotations/AnyMetaDefs.java | 3 + .../annotations/AttributeAccessor.java | 2 +- .../org/hibernate/annotations/BatchSize.java | 2 +- .../java/org/hibernate/annotations/Cache.java | 20 ++- .../annotations/CacheConcurrencyStrategy.java | 58 ++++++- .../hibernate/annotations/CacheModeType.java | 87 ++++++++++- .../org/hibernate/annotations/Cascade.java | 3 + .../hibernate/annotations/CascadeType.java | 45 +++++- .../java/org/hibernate/annotations/Check.java | 6 +- .../hibernate/annotations/CollectionId.java | 17 +- .../hibernate/annotations/CollectionType.java | 12 +- .../annotations/ColumnTransformer.java | 8 +- .../annotations/ColumnTransformers.java | 4 + .../org/hibernate/annotations/Columns.java | 4 + .../annotations/DiscriminatorFormula.java | 4 + .../annotations/DiscriminatorOptions.java | 13 +- .../hibernate/annotations/DynamicInsert.java | 4 + .../hibernate/annotations/DynamicUpdate.java | 5 + .../org/hibernate/annotations/Entity.java | 23 ++- .../java/org/hibernate/annotations/Fetch.java | 8 +- .../org/hibernate/annotations/FetchMode.java | 12 +- .../hibernate/annotations/FetchProfile.java | 26 +++- .../hibernate/annotations/FetchProfiles.java | 13 +- .../org/hibernate/annotations/Filter.java | 19 ++- .../org/hibernate/annotations/FilterDef.java | 11 +- .../org/hibernate/annotations/FilterDefs.java | 5 +- .../annotations/FilterJoinTable.java | 21 ++- .../annotations/FilterJoinTables.java | 8 +- .../org/hibernate/annotations/Filters.java | 5 +- .../hibernate/annotations/FlushModeType.java | 19 ++- .../org/hibernate/annotations/ForeignKey.java | 12 +- .../org/hibernate/annotations/Formula.java | 4 + .../org/hibernate/annotations/Generated.java | 8 +- .../hibernate/annotations/GenerationTime.java | 14 +- .../annotations/GenericGenerator.java | 10 +- .../annotations/GenericGenerators.java | 6 +- .../java/org/hibernate/annotations/Index.java | 9 +- .../hibernate/annotations/IndexColumn.java | 26 +++- .../annotations/JoinColumnOrFormula.java | 13 +- .../annotations/JoinColumnsOrFormulas.java | 5 + .../hibernate/annotations/JoinFormula.java | 13 +- .../hibernate/annotations/LazyCollection.java | 8 +- .../annotations/LazyCollectionOption.java | 17 +- .../org/hibernate/annotations/LazyToOne.java | 9 +- .../annotations/LazyToOneOption.java | 24 +-- .../org/hibernate/annotations/Loader.java | 6 +- .../org/hibernate/annotations/MapKeyType.java | 4 + .../org/hibernate/annotations/MetaValue.java | 4 +- .../annotations/NamedNativeQueries.java | 9 +- .../annotations/NamedNativeQuery.java | 61 ++++++-- .../hibernate/annotations/NamedQueries.java | 9 +- .../org/hibernate/annotations/NamedQuery.java | 24 +-- .../org/hibernate/annotations/NaturalId.java | 6 +- .../org/hibernate/annotations/NotFound.java | 3 + .../hibernate/annotations/NotFoundAction.java | 7 +- .../org/hibernate/annotations/OnDelete.java | 7 +- .../hibernate/annotations/OnDeleteAction.java | 7 +- .../hibernate/annotations/OptimisticLock.java | 3 +- .../annotations/OptimisticLockType.java | 16 +- .../annotations/OptimisticLocking.java | 3 + .../org/hibernate/annotations/OrderBy.java | 9 +- .../org/hibernate/annotations/ParamDef.java | 11 +- .../org/hibernate/annotations/Parameter.java | 8 +- .../org/hibernate/annotations/Parent.java | 2 +- .../org/hibernate/annotations/Persister.java | 2 +- .../hibernate/annotations/Polymorphism.java | 3 + .../annotations/PolymorphismType.java | 7 +- .../java/org/hibernate/annotations/Proxy.java | 7 +- .../org/hibernate/annotations/QueryHints.java | 75 ++++++++- .../annotations/ResultCheckStyle.java | 11 +- .../java/org/hibernate/annotations/RowId.java | 6 +- .../org/hibernate/annotations/SQLDelete.java | 7 +- .../hibernate/annotations/SQLDeleteAll.java | 7 +- .../org/hibernate/annotations/SQLInsert.java | 7 +- .../org/hibernate/annotations/SQLUpdate.java | 8 +- .../annotations/SelectBeforeUpdate.java | 5 + .../java/org/hibernate/annotations/Sort.java | 17 +- .../org/hibernate/annotations/SortType.java | 12 +- .../org/hibernate/annotations/Source.java | 9 +- .../org/hibernate/annotations/SourceType.java | 13 +- .../annotations/SqlFragmentAlias.java | 14 +- .../org/hibernate/annotations/Subselect.java | 10 +- .../hibernate/annotations/Synchronize.java | 7 +- .../java/org/hibernate/annotations/Table.java | 18 +-- .../org/hibernate/annotations/Tables.java | 7 +- .../org/hibernate/annotations/Target.java | 8 +- .../org/hibernate/annotations/Tuplizer.java | 17 +- .../org/hibernate/annotations/Tuplizers.java | 9 +- .../java/org/hibernate/annotations/Type.java | 21 ++- .../org/hibernate/annotations/TypeDef.java | 28 +++- .../org/hibernate/annotations/TypeDefs.java | 6 +- .../java/org/hibernate/annotations/Where.java | 8 +- .../hibernate/annotations/WhereJoinTable.java | 10 +- .../hibernate/annotations/package-info.java | 4 + shared/config/checkstyle/public_checks.xml | 145 ++++++++++++++++++ 102 files changed, 1103 insertions(+), 299 deletions(-) create mode 100644 hibernate-core/src/main/java/org/hibernate/action/spi/package-info.java create mode 100644 hibernate-core/src/main/java/org/hibernate/annotations/package-info.java create mode 100644 shared/config/checkstyle/public_checks.xml diff --git a/build.gradle b/build.gradle index 2ea0319202..ea9f8b682e 100644 --- a/build.gradle +++ b/build.gradle @@ -308,6 +308,24 @@ subprojects { subProject -> // eclipseClasspath will not add sources to classpath unless the dirs actually exist. eclipseClasspath.dependsOn("generateSources") + // specialized API/SPI checkstyle tasks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + task checkstylePublicSources(type: Checkstyle) { + checkstyleClasspath = checkstyleMain.checkstyleClasspath + classpath = checkstyleMain.classpath + configFile = rootProject.file( 'shared/config/checkstyle/public_checks.xml' ) + source subProject.sourceSets.main.originalJavaSrcDirs + exclude '**/internal/**' + exclude '**/internal/*' + ignoreFailures = false + showViolations = true + reports { + xml { + destination "$buildDir/reports/checkstyle/public.xml" + } + } + } + // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + // Report configs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ checkstyle { configFile = rootProject.file( 'shared/config/checkstyle/checkstyle.xml' ) diff --git a/hibernate-core/src/main/java/org/hibernate/ScrollMode.java b/hibernate-core/src/main/java/org/hibernate/ScrollMode.java index 223f6018da..17d227748f 100755 --- a/hibernate-core/src/main/java/org/hibernate/ScrollMode.java +++ b/hibernate-core/src/main/java/org/hibernate/ScrollMode.java @@ -40,14 +40,14 @@ public enum ScrollMode { FORWARD_ONLY( ResultSet.TYPE_FORWARD_ONLY ), /** - * Requests a scrollable result which is sensitive to changes in the underlying data + * Requests a scrollable result which is sensitive to changes in the underlying data. * * @see java.sql.ResultSet#TYPE_SCROLL_SENSITIVE */ SCROLL_SENSITIVE( ResultSet.TYPE_SCROLL_SENSITIVE ), /** - * Requests a scrollable result which is insensitive to changes in the underlying data + * Requests a scrollable result which is insensitive to changes in the underlying data. * * Note that since the Hibernate session acts as a cache, you * might need to explicitly evict objects, if you need to see diff --git a/hibernate-core/src/main/java/org/hibernate/StaleObjectStateException.java b/hibernate-core/src/main/java/org/hibernate/StaleObjectStateException.java index 49f59c8ab1..e10ccd6cb2 100644 --- a/hibernate-core/src/main/java/org/hibernate/StaleObjectStateException.java +++ b/hibernate-core/src/main/java/org/hibernate/StaleObjectStateException.java @@ -38,7 +38,7 @@ public class StaleObjectStateException extends StaleStateException { private final Serializable identifier; /** - * Constructs a StaleObjectStateException using the supplied information + * Constructs a StaleObjectStateException using the supplied information. * * @param entityName The name of the entity * @param identifier The identifier of the entity diff --git a/hibernate-core/src/main/java/org/hibernate/action/spi/Executable.java b/hibernate-core/src/main/java/org/hibernate/action/spi/Executable.java index d44c3b4f96..737544c69f 100644 --- a/hibernate-core/src/main/java/org/hibernate/action/spi/Executable.java +++ b/hibernate-core/src/main/java/org/hibernate/action/spi/Executable.java @@ -28,9 +28,8 @@ import java.io.Serializable; import org.hibernate.HibernateException; /** - * An operation which may be scheduled for later execution. - * Usually, the operation is a database insert/update/delete, - * together with required second-level cache management. + * An operation which may be scheduled for later execution. Usually, the operation is a database + * insert/update/delete, together with required second-level cache management. * * @author Gavin King * @author Steve Ebersole @@ -51,7 +50,7 @@ public interface Executable { public void beforeExecutions() throws HibernateException; /** - * Execute this action + * Execute this action. * * @throws HibernateException Indicates a problem during execution. */ diff --git a/hibernate-core/src/main/java/org/hibernate/action/spi/package-info.java b/hibernate-core/src/main/java/org/hibernate/action/spi/package-info.java new file mode 100644 index 0000000000..b364028e4c --- /dev/null +++ b/hibernate-core/src/main/java/org/hibernate/action/spi/package-info.java @@ -0,0 +1,5 @@ +/** + * Defines SPI hooks into the {@link org.hibernate.engine.spi.ActionQueue}. Mainly for registering custom + * {@link AfterTransactionCompletionProcess} and {@link BeforeTransactionCompletionProcess} hooks. + */ +package org.hibernate.action.spi; diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AccessType.java b/hibernate-core/src/main/java/org/hibernate/annotations/AccessType.java index af2e72b8ca..94c5eb0329 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/AccessType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/AccessType.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,9 +32,8 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Property Access type - * - * Prefer the standard {@link javax.persistence.Access} annotation + * Property Access type. Prefer the standard {@link javax.persistence.Access} annotation; however, + * {@code @Access} is limited to field/property access definitions. * * @author Emmanuel Bernard * @@ -44,5 +44,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) @Deprecated public @interface AccessType { + /** + * The access strategy name. + */ String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDef.java b/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDef.java index e7cac8a031..6df8303ec1 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDef.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDef.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; @@ -42,8 +43,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention( RUNTIME ) public @interface AnyMetaDef { /** - * If defined, assign a global meta definition name to be used in an @Any or @ManyToAny annotation - * If not defined, the metadata applies to the current property or field + * If defined, assign a global meta definition name to be used in an @Any or @ManyToAny annotation. If + * not defined, the metadata applies to the current property or field. */ String name() default ""; diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDefs.java b/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDefs.java index 0de690efa7..6db78268da 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDefs.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDefs.java @@ -38,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @java.lang.annotation.Target( { PACKAGE, TYPE } ) @Retention( RUNTIME ) public @interface AnyMetaDefs { + /** + * The collective set of any meta-defs. + */ AnyMetaDef[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java b/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java index 32991f4865..0b33363101 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java @@ -55,7 +55,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface AttributeAccessor { /** - * Names the {@link org.hibernate.property.PropertyAccessor} strategy + * Names the {@link org.hibernate.property.PropertyAccessor} strategy. */ String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.java b/hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.java index 414af5199c..49c3e625ef 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.java @@ -56,7 +56,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface BatchSize { /** - * Strictly positive integer + * Strictly positive integer. */ int size(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Cache.java b/hibernate-core/src/main/java/org/hibernate/annotations/Cache.java index 8fd717be64..77f943c2bd 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Cache.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Cache.java @@ -31,20 +31,26 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Add caching strategy to a root entity or a collection + * Add caching strategy to a root entity or a collection. * * @author Emmanuel Bernard */ @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) public @interface Cache { - /** concurrency strategy chosen */ - CacheConcurrencyStrategy usage(); - /** cache region name */ - String region() default ""; /** - * whether or not lazy-properties are included in the second level cache - * default all, other value: non-lazy + * The concurrency strategy chosen. + */ + CacheConcurrencyStrategy usage(); + + /** + * The cache region name. + */ + String region() default ""; + + /** + * How lazy properties are included in the second level cache. Default value is "all"; other allowable + * value: "non-lazy" */ String include() default "all"; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/CacheConcurrencyStrategy.java b/hibernate-core/src/main/java/org/hibernate/annotations/CacheConcurrencyStrategy.java index 10d15d2384..ab2c26aaa6 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/CacheConcurrencyStrategy.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/CacheConcurrencyStrategy.java @@ -26,15 +26,38 @@ package org.hibernate.annotations; import org.hibernate.cache.spi.access.AccessType; /** - * Cache concurrency strategy + * Cache concurrency strategy. * * @author Emmanuel Bernard */ public enum CacheConcurrencyStrategy { + /** + * Indicates no concurrency strategy should be applied. + */ NONE( null ), + /** + * Indicates that read-only strategy should be applied. + * + * @see AccessType#READ_ONLY + */ READ_ONLY( AccessType.READ_ONLY ), + /** + * Indicates that the non-strict read-write strategy should be applied. + * + * @see AccessType#NONSTRICT_READ_WRITE + */ NONSTRICT_READ_WRITE( AccessType.NONSTRICT_READ_WRITE ), + /** + * Indicates that the read-write strategy should be applied. + * + * @see AccessType#READ_WRITE + */ READ_WRITE( AccessType.READ_WRITE ), + /** + * Indicates that the transaction strategy should be applied. + * + * @see AccessType#TRANSACTIONAL + */ TRANSACTIONAL( AccessType.TRANSACTIONAL ); private final AccessType accessType; @@ -43,13 +66,26 @@ public enum CacheConcurrencyStrategy { this.accessType = accessType; } - private boolean isMatch(String name) { - return ( accessType != null && accessType.getExternalName().equalsIgnoreCase( name ) ) - || name().equalsIgnoreCase( name ); + /** + * Get the AccessType corresponding to this concurrency strategy. + * + * @return The corresponding concurrency strategy. Note that this will return {@code null} for + * {@link #NONE} + */ + public AccessType toAccessType() { + return accessType; } + /** + * Conversion from {@link AccessType} to {@link CacheConcurrencyStrategy}. + * + * @param accessType The access type to convert + * + * @return The corresponding enum value. {@link #NONE} is returned by default if unable to + * recognize {@code accessType} or if {@code accessType} is {@code null}. + */ public static CacheConcurrencyStrategy fromAccessType(AccessType accessType) { - if (null == accessType) { + if ( null == accessType ) { return NONE; } @@ -72,6 +108,13 @@ public enum CacheConcurrencyStrategy { } } + /** + * Parse an external representation of a CacheConcurrencyStrategy value. + * + * @param name The external representation + * + * @return The corresponding enum value, or {@code null} if not match was found. + */ public static CacheConcurrencyStrategy parse(String name) { if ( READ_ONLY.isMatch( name ) ) { return READ_ONLY; @@ -93,7 +136,8 @@ public enum CacheConcurrencyStrategy { } } - public AccessType toAccessType() { - return accessType; + private boolean isMatch(String name) { + return ( accessType != null && accessType.getExternalName().equalsIgnoreCase( name ) ) + || name().equalsIgnoreCase( name ); } } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/CacheModeType.java b/hibernate-core/src/main/java/org/hibernate/annotations/CacheModeType.java index bd35ba9dec..d9fa888121 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/CacheModeType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/CacheModeType.java @@ -23,6 +23,7 @@ */ package org.hibernate.annotations; +import org.hibernate.CacheMode; /** * Enumeration for the different interaction modes between the session and @@ -31,11 +32,83 @@ package org.hibernate.annotations; * @author Emmanuel Bernard * @author Carlos Gonzalez-Cadenas */ - public enum CacheModeType { - GET, - IGNORE, - NORMAL, - PUT, - REFRESH -} \ No newline at end of file + /** + * Corresponds to {@link CacheMode#GET}. + * + * @see CacheMode#GET + */ + GET( CacheMode.GET ), + + /** + * Corresponds to {@link CacheMode#IGNORE}. + * + * @see CacheMode#IGNORE + */ + IGNORE( CacheMode.IGNORE ), + + /** + * Corresponds to {@link CacheMode#NORMAL}. + * + * @see CacheMode#NORMAL + */ + NORMAL( CacheMode.NORMAL ), + + /** + * Corresponds to {@link CacheMode#PUT}. + * + * @see CacheMode#PUT + */ + PUT( CacheMode.PUT ), + + /** + * Corresponds to {@link CacheMode#REFRESH}. + * + * @see CacheMode#REFRESH + */ + REFRESH( CacheMode.REFRESH ); + + private final CacheMode cacheMode; + + private CacheModeType(CacheMode cacheMode) { + this.cacheMode = cacheMode; + } + + public CacheMode getCacheMode() { + return cacheMode; + } + + /** + * Conversion from {@link CacheMode} to {@link CacheModeType}. + * + * @param cacheMode The cache mode to convert + * + * @return The corresponding enum value. Will be {@code null} if the given {@code accessType} is {@code null}. + */ + public static CacheModeType fromCacheMode(CacheMode cacheMode) { + if ( null == cacheMode ) { + return null; + } + + switch ( cacheMode ) { + case NORMAL: { + return NORMAL; + } + case GET: { + return GET; + } + case PUT: { + return PUT; + } + case REFRESH: { + return REFRESH; + } + case IGNORE: { + return IGNORE; + } + default: { + throw new IllegalArgumentException( "Unrecognized CacheMode : " + cacheMode ); + } + } + } +} diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java b/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java index 406adb7948..1c5f35d895 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java @@ -40,5 +40,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface Cascade { + /** + * The cascade value. + */ CascadeType[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java b/hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java index 2767b824c2..96ad7ec1f7 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java @@ -23,25 +23,62 @@ */ package org.hibernate.annotations; - /** - * Cascade types (can override default JPA cascades + * Cascade types (can override default JPA cascades). */ public enum CascadeType { + /** + * Includes all types listed here. + */ ALL, + /** + * Corresponds to {@link javax.persistence.CascadeType#PERSIST}. + */ PERSIST, + /** + * Corresponds to {@link javax.persistence.CascadeType#MERGE}. + */ MERGE, + /** + * Corresponds to {@link javax.persistence.CascadeType#REMOVE}. + */ REMOVE, + /** + * Corresponds to {@link javax.persistence.CascadeType#REFRESH}. + */ REFRESH, + /** + * Corresponds to the Hibernate native DELETE action. + */ DELETE, + /** + * Corresponds to the Hibernate native SAVE_UPDATE (direct reattachment) action. + */ SAVE_UPDATE, + /** + * Corresponds to the Hibernate native REPLICATE action. + */ REPLICATE, - /** @deprecated use @OneToOne(orphanRemoval=true) or @OneToMany(orphanRemoval=true) */ + /** + * Hibernate originally handled orphan removal as a specialized cascade. + * + * @deprecated use @OneToOne(orphanRemoval=true) or @OneToMany(orphanRemoval=true) + */ @Deprecated DELETE_ORPHAN, + /** + * Corresponds to the Hibernate native LOCK action. + */ LOCK, - /** @deprecated use javax.persistence.CascadeType.DETACH */ + /** + * JPA originally planned on calling DETACH EVICT. + * + * @deprecated use javax.persistence.CascadeType.DETACH + */ @Deprecated EVICT, + /** + * Corresponds to {@link javax.persistence.CascadeType#REFRESH}. + */ DETACH } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Check.java b/hibernate-core/src/main/java/org/hibernate/annotations/Check.java index 4929f71fbd..fd3ceb761d 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Check.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Check.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,12 +32,15 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Arbitrary SQL CHECK constraints which can be defined at the class, property or collection level + * Arbitrary SQL CHECK constraints which can be defined at the class, property or collection level. * * @author Emmanuel Bernard */ @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) public @interface Check { + /** + * The check constraints string. + */ String constraints(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/CollectionId.java b/hibernate-core/src/main/java/org/hibernate/annotations/CollectionId.java index 54aee08fa8..a6d7e57fe5 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/CollectionId.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/CollectionId.java @@ -31,7 +31,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 (ie an idbag). + * * EXPERIMENTAL: the structure of this annotation might slightly change (generator() mix strategy and generator * * @author Emmanuel Bernard @@ -39,10 +40,18 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface CollectionId { - /** Collection id column(s) */ + /** + * Collection id column(s). + */ Column[] columns(); - /** id type, type.type() must be set */ + + /** + * id type, type.type() must be set. + */ Type type(); - /** generator name: 'identity' or a defined generator name */ + + /** + * The generator name. For example 'identity' or a defined generator name + */ String generator(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/CollectionType.java b/hibernate-core/src/main/java/org/hibernate/annotations/CollectionType.java index 5bbe42d538..31c5c759f4 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/CollectionType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/CollectionType.java @@ -42,11 +42,11 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface CollectionType { /** - * Names the type (either {@link org.hibernate.type.CollectionType} or - * {@link org.hibernate.usertype.UserCollectionType} implementation class. Could also name a - * custom type defined via a {@link TypeDef @TypeDef} - * - * @return The implementation class to use. + * Names the type. + * + * Could name the implementation class (an implementation of {@link org.hibernate.type.CollectionType} or + * {@link org.hibernate.usertype.UserCollectionType}). Could also name a custom type defined via a + * {@link TypeDef @TypeDef} */ String type(); @@ -54,8 +54,6 @@ public @interface CollectionType { * Specifies configuration information for the type. Note that if the named type is a * {@link org.hibernate.usertype.UserCollectionType}, it must also implement * {@link org.hibernate.usertype.ParameterizedType} in order to receive these values. - * - * @return The configuration parameters. */ Parameter[] parameters() default {}; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java b/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java index 0d9c1c4486..870215a734 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java @@ -43,20 +43,20 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface ColumnTransformer { /** - * (Logical) column name for which the expression is used + * (Logical) column name for which the expression is used. * * This can be left out if the property is bound to a single column */ String forColumn() default ""; /** - * Custom SQL expression used to read from the column + * Custom SQL expression used to read from the column. */ String read() default ""; /** - * Custom SQL expression used to write to the column. - * The write expression must contain exactly one '?' placeholder for the value. + * Custom SQL expression used to write to the column. The write expression must contain exactly + * one '?' placeholder for the value. */ String write() default ""; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformers.java b/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformers.java index 6bd9681fe5..1d86d24b50 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformers.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformers.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; @@ -37,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @java.lang.annotation.Target({FIELD,METHOD}) @Retention(RUNTIME) public @interface ColumnTransformers { + /** + * The aggregated transformers. + */ ColumnTransformer[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Columns.java b/hibernate-core/src/main/java/org/hibernate/annotations/Columns.java index 2e597074a5..28c70acdd4 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Columns.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Columns.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; import javax.persistence.Column; @@ -38,5 +39,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface Columns { + /** + * The aggregated columns. + */ Column[] columns(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorFormula.java b/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorFormula.java index c272298480..7020c4df8d 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorFormula.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorFormula.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -42,5 +43,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({TYPE}) @Retention(RUNTIME) public @interface DiscriminatorFormula { + /** + * The formula string. + */ String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorOptions.java b/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorOptions.java index 3a1c2da57d..8d9888cc26 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorOptions.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorOptions.java @@ -38,18 +38,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface DiscriminatorOptions { /** - * "Forces" Hibernate to specify the allowed discriminator values, even when retrieving all instances of the root class. - * - * @return {@code true} in case the discriminator value should be forces, {@code false} otherwise. Default is {@code false}. + * "Forces" Hibernate to specify the allowed discriminator values, even when retrieving all instances of + * the root class. {@code true} indicates that the discriminator value should be forced; Default is + * {@code false}. */ boolean force() default false; /** - * Set this to {@code false}, if your discriminator column is also part of a mapped composite identifier. - * It tells Hibernate not to include the column in SQL INSERTs. - * - * @return {@code true} in case the discriminator value should be included in inserts, {@code false} otherwise. - * Default is {@code true}. + * Set this to {@code false} if your discriminator column is also part of a mapped composite identifier. + * It tells Hibernate not to include the column in SQL INSERTs. Default is {@code true}. */ boolean insert() default true; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/DynamicInsert.java b/hibernate-core/src/main/java/org/hibernate/annotations/DynamicInsert.java index 11446e8725..730a98844c 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/DynamicInsert.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/DynamicInsert.java @@ -38,5 +38,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target( TYPE ) @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). + */ boolean value() default true; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/DynamicUpdate.java b/hibernate-core/src/main/java/org/hibernate/annotations/DynamicUpdate.java index b873ce9974..66297af5e9 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/DynamicUpdate.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/DynamicUpdate.java @@ -42,5 +42,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target( TYPE ) @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). + */ boolean value() default true; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Entity.java b/hibernate-core/src/main/java/org/hibernate/annotations/Entity.java index 11758e6750..00527d5092 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Entity.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Entity.java @@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Extends {@link javax.persistence.Entity} with Hibernate features + * Extends {@link javax.persistence.Entity} with Hibernate features. * * @author Emmanuel Bernard * @@ -41,39 +41,46 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Deprecated public @interface Entity { /** - * Is this entity mutable (read only) or not + * Is this entity mutable (read only) or not. * * @deprecated use {@link org.hibernate.annotations.Immutable} */ + @Deprecated boolean mutable() default true; /** - * Needed column only in SQL on insert + * Needed column only in SQL on insert. * @deprecated use {@link DynamicInsert} instead */ + @Deprecated boolean dynamicInsert() default false; /** - * Needed column only in SQL on update + * Needed column only in SQL on update. * @deprecated Use {@link DynamicUpdate} instead */ + @Deprecated boolean dynamicUpdate() default false; /** - * Do a select to retrieve the entity before any potential update + * Do a select to retrieve the entity before any potential update. * @deprecated Use {@link SelectBeforeUpdate} instead */ + @Deprecated boolean selectBeforeUpdate() default false; /** - * polymorphism strategy for this entity + * polymorphism strategy for this entity. * @deprecated use {@link Polymorphism} instead */ + @Deprecated PolymorphismType polymorphism() default PolymorphismType.IMPLICIT; /** - * optimistic locking strategy + * optimistic locking strategy. * @deprecated use {@link OptimisticLocking} instead. */ + @Deprecated OptimisticLockType optimisticLock() default OptimisticLockType.VERSION; /** - * persister of this entity, default is hibernate internal one + * persister of this entity, default is hibernate internal one. * @deprecated use {@link Persister} instead */ + @Deprecated String persister() default ""; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java b/hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java index afbeaa5ec6..598033e26e 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java @@ -21,19 +21,23 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; +package org.hibernate.annotations; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Define the fetching strategy used for the given association + * Define the fetching strategy used for the given association. * * @author Emmanuel Bernard */ @Target({ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface Fetch { + /** + * The style of fetch to use. + */ FetchMode value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java b/hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java index 703e8ecdc0..84e25db1f4 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java @@ -21,25 +21,25 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; - +package org.hibernate.annotations; /** - * Fetch options on associations + * Fetch options on associations. Defines more of the "how" of fetching, whereas JPA {@link javax.persistence.FetchType} + * focuses on the "when". * * @author Emmanuel Bernard */ public enum FetchMode { /** - * use a select for each individual entity, collection, or join load + * use a select for each individual entity, collection, or join load. */ SELECT, /** - * use an outer join to load the related entities, collections or joins + * use an outer join to load the related entities, collections or joins. */ JOIN, /** - * use a subselect query to load the additional collections + * use a subselect query to load the additional collections. */ SUBSELECT } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java index 6dd1e086b2..9a91467be1 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java @@ -21,10 +21,8 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ - -// $Id$ - package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -40,17 +38,35 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({ TYPE, PACKAGE }) @Retention(RUNTIME) public @interface FetchProfile { + /** + * The name of the fetch profile. + */ String name(); + /** + * The association fetch overrides. + */ FetchOverride[] fetchOverrides(); + /** + * Descriptor for a particular association override. + */ @Target({ TYPE, PACKAGE }) @Retention(RUNTIME) - @interface FetchOverride { + @interface FetchOverride { + /** + * The entity containing the association whose fetch is being overridden. + */ Class entity(); + /** + * The association whose fetch is being overridden. + */ String association(); + /** + * The fetch mode to apply to the association. + */ FetchMode mode(); } -} \ No newline at end of file +} diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfiles.java b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfiles.java index a52c290343..0b093c6742 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfiles.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfiles.java @@ -21,10 +21,8 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ - -// $Id$ - package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -33,10 +31,15 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** + * Collects together multiple fetch profiles. + * * @author Hardy Ferentschik */ @Target({ TYPE, PACKAGE }) @Retention(RUNTIME) public @interface FetchProfiles { - public abstract FetchProfile[] value(); -} \ No newline at end of file + /** + * The aggregated fetch profiles. + */ + public FetchProfile[] value(); +} diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Filter.java b/hibernate-core/src/main/java/org/hibernate/annotations/Filter.java index 997baccfc5..eea2379bac 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Filter.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Filter.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,7 +32,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Add filters to an entity or a target entity of a collection + * Add filters to an entity or a target entity of a collection. * * @author Emmanuel Bernard * @author Matthew Inger @@ -41,8 +42,24 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) public @interface Filter { + /** + * The filter name. + */ String name(); + + /** + * The filter condition. If empty, the default condition from the correspondingly named {@link FilterDef} is used. + */ String condition() default ""; + + /** + * Do we need to determine all points within the condition fragment that are alias injection points? Or + * are injection points already marked? + */ boolean deduceAliasInjectionPoints() default true; + + /** + * The alias descriptors for injection. + */ SqlFragmentAlias[] aliases() default {}; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java b/hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java index 252a4a6a21..df5e311664 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java @@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Filter definition + * Filter definition. Defines a name, default condition and parameter types (if any). * * @author Matthew Inger * @author Emmanuel Bernard @@ -38,9 +38,18 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({TYPE, PACKAGE}) @Retention(RUNTIME) public @interface FilterDef { + /** + * The filter name. + */ String name(); + /** + * The default filter condition. + */ String defaultCondition() default ""; + /** + * The filter parameter definitions. + */ ParamDef[] parameters() default {}; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FilterDefs.java b/hibernate-core/src/main/java/org/hibernate/annotations/FilterDefs.java index a407e1c721..7dc2032c5d 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FilterDefs.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FilterDefs.java @@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Array of filter definitions + * Array of filter definitions. * * @author Matthew Inger * @author Emmanuel Bernard @@ -38,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({PACKAGE, TYPE}) @Retention(RUNTIME) public @interface FilterDefs { + /** + * The aggregated filter definitions. + */ FilterDef[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTable.java b/hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTable.java index 10f730b8e8..a8f4d1f3bc 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTable.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTable.java @@ -21,16 +21,15 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ +package org.hibernate.annotations; -//$Id$ -package org.hibernate.annotations; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Add filters to a join table collection + * Add filters to a join table collection. * * @author Emmanuel Bernard * @author Rob Worsnop @@ -38,8 +37,24 @@ import java.lang.annotation.Target; @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface FilterJoinTable { + /** + * The filter name. + */ String name(); + + /** + * The filter condition. If empty, the default condition from the correspondingly named {@link FilterDef} is used. + */ String condition() default ""; + + /** + * Do we need to determine all points within the condition fragment that are alias injection points? Or + * are injection points already marked? + */ boolean deduceAliasInjectionPoints() default true; + + /** + * The alias descriptors for injection. + */ SqlFragmentAlias[] aliases() default {}; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTables.java b/hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTables.java index 568a37783e..741b551843 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTables.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTables.java @@ -21,19 +21,23 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; +package org.hibernate.annotations; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Add multiple @FilterJoinTable to a collection + * Add multiple {@code @FilterJoinTable} to a collection. * * @author Emmanuel Bernard */ @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface FilterJoinTables { + /** + * The aggregated filters. + */ FilterJoinTable[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Filters.java b/hibernate-core/src/main/java/org/hibernate/annotations/Filters.java index 89432ad680..9777a3bec5 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Filters.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Filters.java @@ -31,7 +31,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Add multiple @Filters + * Add multiple {@code @Filters}. * * @author Emmanuel Bernard * @author Matthew Inger @@ -40,5 +40,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) public @interface Filters { + /** + * The aggregated filters. + */ Filter[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java b/hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java index c50190b8b9..69bc487d83 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java @@ -23,38 +23,37 @@ */ package org.hibernate.annotations; - /** * Enumeration extending javax.persistence flush modes. * * @author Carlos Gonz�lez-Cadenas */ - public enum FlushModeType { /** - * see {@link org.hibernate.FlushMode#ALWAYS} + * Corresponds to {@link org.hibernate.FlushMode#ALWAYS}. */ ALWAYS, /** - * see {@link org.hibernate.FlushMode#AUTO} + * Corresponds to {@link org.hibernate.FlushMode#AUTO}. */ AUTO, /** - * see {@link org.hibernate.FlushMode#COMMIT} + * Corresponds to {@link org.hibernate.FlushMode#COMMIT}. */ COMMIT, /** - * see {@link org.hibernate.FlushMode#NEVER} + * Corresponds to {@link org.hibernate.FlushMode#NEVER}. + * * @deprecated use MANUAL, will be removed in a subsequent release */ + @Deprecated NEVER, /** - * see {@link org.hibernate.FlushMode#MANUAL} + * Corresponds to {@link org.hibernate.FlushMode#MANUAL}. */ MANUAL, - /** - * Current flush mode of the persistence context at the time the query is executed + * Current flush mode of the persistence context at the time the query is executed. */ PERSISTENCE_CONTEXT -} \ No newline at end of file +} diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/ForeignKey.java b/hibernate-core/src/main/java/org/hibernate/annotations/ForeignKey.java index c1a77410d8..61b4f5b3f0 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/ForeignKey.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/ForeignKey.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -30,12 +31,13 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; +/** + * Define the foreign key name. + * + * Prefer the JPA 2.1 introduced {@link javax.persistence.ForeignKey} instead. + */ @Target({FIELD, METHOD, TYPE}) @Retention(RUNTIME) - -/** - * Define the foreign key name - */ public @interface ForeignKey { /** * Name of the foreign key. Used in OneToMany, ManyToOne, and OneToOne @@ -48,4 +50,4 @@ public @interface ForeignKey { * in other relationships */ String inverseName() default ""; -} \ No newline at end of file +} diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java b/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java index 813d8fd94b..9639d00619 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -62,5 +63,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface Formula { + /** + * The formula string. + */ String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Generated.java b/hibernate-core/src/main/java/org/hibernate/annotations/Generated.java index 0899c5f059..3885c78ef5 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Generated.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Generated.java @@ -21,19 +21,23 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; +package org.hibernate.annotations; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * The annotated property is generated by the database + * The annotated property is generated by the database. * * @author Emmanuel Bernard */ @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface Generated { + /** + * The enum value representing when the value is generated. + */ GenerationTime value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/GenerationTime.java b/hibernate-core/src/main/java/org/hibernate/annotations/GenerationTime.java index bf54b0ba6e..ecc98c53df 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/GenerationTime.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/GenerationTime.java @@ -21,16 +21,24 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; - +package org.hibernate.annotations; /** - * When should the generation occurs + * At what time(s) will the generation occur? * * @author Emmanuel Bernard */ public enum GenerationTime { + /** + * Indicates the value is never generated. + */ NEVER, + /** + * Indicates the value is generated on insert. + */ INSERT, + /** + * Indicates the value is generated on insert and on update. + */ ALWAYS } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java b/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java index bbe0967916..64e66a53ac 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java @@ -32,8 +32,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Generator annotation describing any kind of Hibernate - * generator in a detyped manner + * Generator annotation describing any kind of Hibernate generator in a generic (de-typed) manner. * * @author Emmanuel Bernard */ @@ -41,16 +40,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface GenericGenerator { /** - * unique generator name + * unique generator name. */ String name(); /** - * Generator strategy either a predefined Hibernate - * strategy or a fully qualified class name. + * Generator strategy either a predefined Hibernate strategy or a fully qualified class name. */ String strategy(); /** - * Optional generator parameters + * Optional generator parameters. */ Parameter[] parameters() default {}; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerators.java b/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerators.java index 7ed4cc2249..28e8fa82cc 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerators.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerators.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -30,13 +31,16 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Array of generic generator definitions + * Array of generic generator definitions. * * @author Paul Cowan */ @Target({PACKAGE, TYPE}) @Retention(RUNTIME) public @interface GenericGenerators { + /** + * The aggregated generators. + */ GenericGenerator[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Index.java b/hibernate-core/src/main/java/org/hibernate/annotations/Index.java index 6779606255..5b6a9ea0db 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Index.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Index.java @@ -30,16 +30,23 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Define a DB index + * Define a DB index. * * @author Emmanuel Bernard + * * @deprecated Using {@link javax.persistence.Index} instead. */ @Target({FIELD, METHOD}) @Retention(RUNTIME) @Deprecated public @interface Index { + /** + * The index name. + */ String name(); + /** + * The column(s) that are indexed. + */ String[] columnNames() default {}; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/IndexColumn.java b/hibernate-core/src/main/java/org/hibernate/annotations/IndexColumn.java index 5c1689452e..f26076e6a8 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/IndexColumn.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/IndexColumn.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -30,20 +31,33 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Describe an index column of a List - * Prefer the standard {@link javax.persistence.OrderColumn} annotation + * Describe an index column of a List. + * + * Prefer the standard {@link javax.persistence.OrderColumn} annotation. Currently the only time to use + * this annotation is to specify {@link #base()}. * * @author Matthew Inger */ @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface IndexColumn { - /** column name */ + /** + * The column name. + */ String name(); - /** index in DB start from base */ + + /** + * The starting index value. Zero (0) by default, since Lists indexes start at zero (0). + */ int base() default 0; - /** is the index nullable */ + + /** + * Is the column nullable? + */ boolean nullable() default true; - /** column definition, default to an appropriate integer */ + + /** + * An explicit column definition. + */ String columnDefinition() default ""; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnOrFormula.java b/hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnOrFormula.java index cf77887675..c34438393e 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnOrFormula.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnOrFormula.java @@ -21,9 +21,8 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ - - package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; import javax.persistence.JoinColumn; @@ -33,11 +32,21 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** + * Allows joins based on column or a formula. One of {@link #formula()} or {@link #column()} should be + * specified, but not both. + * * @author Sharath Reddy */ @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface JoinColumnOrFormula { + /** + * The formula to use in joining. + */ JoinFormula formula() default @JoinFormula(value="", referencedColumnName=""); + + /** + * The column to use in joining. + */ JoinColumn column() default @JoinColumn(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnsOrFormulas.java b/hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnsOrFormulas.java index d73fe41420..c69bb4a1c0 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnsOrFormulas.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnsOrFormulas.java @@ -31,10 +31,15 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** + * Collection of {@code @JoinColumnOrFormula} definitions. + * * @author Sharath Reddy */ @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface JoinColumnsOrFormulas { + /** + * The aggregated values. + */ JoinColumnOrFormula [] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/JoinFormula.java b/hibernate-core/src/main/java/org/hibernate/annotations/JoinFormula.java index 07a7b122cb..1dc87debdd 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/JoinFormula.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/JoinFormula.java @@ -21,8 +21,8 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ - package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,14 +31,21 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * JoinFormula. To be used as a replacement for @JoinColumn in most places - * The formula has to be a valid SQL fragment + * To be used as a replacement for {@code @JoinColumn} in most places. The formula has to be a valid + * SQL fragment * * @author Sharath Reddy */ @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface JoinFormula { + /** + * The formula. + */ String value(); + + /** + * The column this formula references. + */ String referencedColumnName() default ""; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/LazyCollection.java b/hibernate-core/src/main/java/org/hibernate/annotations/LazyCollection.java index 685edced72..fd1676b0fa 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/LazyCollection.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/LazyCollection.java @@ -21,19 +21,23 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; +package org.hibernate.annotations; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Define the lazy status of a collection + * Define the lazy status of a collection. * * @author Emmanuel Bernard */ @Target({ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface LazyCollection { + /** + * The laziness option for the collection. + */ LazyCollectionOption value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/LazyCollectionOption.java b/hibernate-core/src/main/java/org/hibernate/annotations/LazyCollectionOption.java index da06858880..86661c6dd6 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/LazyCollectionOption.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/LazyCollectionOption.java @@ -21,19 +21,24 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; - +package org.hibernate.annotations; /** - * Lazy options available for a collection + * Lazy options available for a collection. * * @author Emmanuel Bernard */ public enum LazyCollectionOption { - /** eagerly load it */ + /** + * Eagerly load it. + */ FALSE, - /** load it when the state is requested */ + /** + * Load it when the state is requested. + */ TRUE, - /** prefer extra queries over fill collection loading */ + /** + * Prefer extra queries over full collection loading. + */ EXTRA } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java b/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java index a41e2ac4c4..92dbbbfc9b 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java @@ -21,20 +21,23 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; +package org.hibernate.annotations; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Define the lazy status of a ToOne association - * (ie OneToOne or ManyToOne) + * Define the laziness options available for a ToOne (ie OneToOne or ManyToOne) association. * * @author Emmanuel Bernard */ @Target({ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface LazyToOne { + /** + * Specify the laziness option. + */ LazyToOneOption value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java b/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java index b7b8df229b..eaaeccdef6 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java @@ -21,26 +21,30 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; - +package org.hibernate.annotations; /** - * Lazy options available for a ToOne association + * Lazy options available for a ToOne association. * * @author Emmanuel Bernard */ public enum LazyToOneOption { - /** eagerly load the association */ + /** + * Eagerly load the association. + */ FALSE, /** - * Lazy, give back a proxy which will be loaded when the state is requested - * This should be the prefered option + * Lazy, give back a proxy which will be loaded when the state is requested. + * + * This should be the preferred option. */ PROXY, - /** Lazy, give back the real object loaded when a reference is requested - * (Bytecode enhancement is mandatory for this option, fall back to PROXY - * if the class is not enhanced) - * This option should be avoided unless you can't afford the use of proxies + /** + * Lazy, give back the real object loaded when a reference is requested. + * + * Bytecode enhancement is mandatory for this option. Falls back to {@link #PROXY} + * if the class is not enhanced. This option should be avoided unless you can't afford + * the use of proxies */ NO_PROXY } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Loader.java b/hibernate-core/src/main/java/org/hibernate/annotations/Loader.java index 57c74fa282..8e2e3b2619 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Loader.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Loader.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,7 +32,8 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Loader Annotation for overwriting Hibernate default FIND method + * Used to override how Hibernate performs load operations. naming a named query to use instead of + * its generated SELECT SQL. * * @author L�szl� Benke */ @@ -39,7 +41,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention( RUNTIME ) public @interface Loader { /** - * namedQuery to use for loading + * THe namedQuery to use for loading. */ String namedQuery() default ""; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/MapKeyType.java b/hibernate-core/src/main/java/org/hibernate/annotations/MapKeyType.java index 4d07fd7805..d3392e2e98 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/MapKeyType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/MapKeyType.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; @@ -36,5 +37,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @java.lang.annotation.Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface MapKeyType { + /** + * The map key type definition. + */ Type value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/MetaValue.java b/hibernate-core/src/main/java/org/hibernate/annotations/MetaValue.java index e9428b019d..ec435e66c9 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/MetaValue.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/MetaValue.java @@ -33,12 +33,12 @@ package org.hibernate.annotations; */ public @interface MetaValue { /** - * entity type + * The entity type. */ Class targetEntity(); /** - * discriminator value stored in database + * The corresponding discriminator value stored in database. */ String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQueries.java b/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQueries.java index f9a2ce6c12..7df7eb4e68 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQueries.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQueries.java @@ -30,13 +30,16 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Extends {@link javax.persistence.NamedNativeQueries} to hold hibernate NamedNativeQuery - * objects + * A grouping of Hibernate-specific {@link NamedNativeQuery} definitions. Effectively extends the named native + * query definitions made available through {@link javax.persistence.NamedNativeQueries}. * * @author Emmanuel Bernard */ @Target({TYPE, PACKAGE}) @Retention(RUNTIME) public @interface NamedNativeQueries { + /** + * The grouping of Hibernate named native SQL queries. + */ NamedNativeQuery[] value(); -} \ No newline at end of file +} diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java b/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java index 8c90153d52..fdf4beba2a 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java @@ -30,36 +30,77 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Extends {@link javax.persistence.NamedNativeQuery} with Hibernate features + * Extends {@link javax.persistence.NamedNativeQuery} with Hibernate features. * * @author Emmanuel Bernard + * + * @see org.hibernate.SQLQuery */ @Target({TYPE, PACKAGE}) @Retention(RUNTIME) public @interface NamedNativeQuery { + /** + * The name. It is a named query after all :) + */ String name(); + /** + * The SQL query string. + */ String query(); + /** + * The result Class. Should not be used in conjunction with {@link #resultSetMapping()} + */ Class resultClass() default void.class; - String resultSetMapping() default ""; // name of SQLResultSetMapping - /** the flush mode for the query */ + /** + * The name of a SQLResultSetMapping to use. Should not be used in conjunction with {@link #resultClass()}. + */ + String resultSetMapping() default ""; + + /** + * The flush mode for the query. + */ FlushModeType flushMode() default FlushModeType.PERSISTENCE_CONTEXT; - /** mark the query as cacheable or not */ + + /** + * Whether the query (results) is cacheable or not. Default is {@code false}, that is not cacheable. + */ boolean cacheable() default false; - /** the cache region to use */ + + /** + * If the query results are cacheable, name the query cache region to use. + */ String cacheRegion() default ""; - /** the number of rows fetched by the JDBC Driver per roundtrip */ + + /** + * The number of rows fetched by the JDBC Driver per trip. + */ int fetchSize() default -1; - /**the query timeout in seconds*/ + + /** + * The query timeout (in seconds). Default is no timeout. + */ int timeout() default -1; + /** + * Does the SQL ({@link #query()}) represent a call to a procedure/function? + */ boolean callable() default false; - /**comment added to the SQL query, useful for the DBA */ + + /** + * A comment added to the SQL query. Useful when engaging with DBA. + */ String comment() default ""; - /**the cache mode used for this query*/ + + /** + * The cache mode used for this query. This refers to entities/collections returned from the query. + */ CacheModeType cacheMode() default CacheModeType.NORMAL; - /**marks whether the results are fetched in read-only mode or not*/ + + /** + * Whether the results should be read-only. Default is {@code false}. + */ boolean readOnly() default false; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NamedQueries.java b/hibernate-core/src/main/java/org/hibernate/annotations/NamedQueries.java index caee4694e0..f5f90130e0 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NamedQueries.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NamedQueries.java @@ -30,8 +30,8 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Extends {@link javax.persistence.NamedQueries} to hold hibernate NamedQuery - * objects + * A grouping of Hibernate-specific {@link NamedQuery} definitions. Effectively extends the named query + * definitions made available through {@link javax.persistence.NamedQueries}. * * @author Emmanuel Bernard * @author Carlos Gonz�lez-Cadenas @@ -39,5 +39,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({TYPE, PACKAGE}) @Retention(RUNTIME) public @interface NamedQueries { + /** + * The grouping of named queries. + */ NamedQuery[] value(); -} \ No newline at end of file +} diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java b/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java index cf8abdc83f..8a73574c38 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java @@ -31,61 +31,63 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Extends {@link javax.persistence.NamedQuery} with Hibernate features + * Extends {@link javax.persistence.NamedQuery} with Hibernate features. * * @author Carlos Gonzalez-Cadenas + * + * @see org.hibernate.Query */ @Target( { TYPE, PACKAGE }) @Retention(RUNTIME) public @interface NamedQuery { /** - * @return returns the name of this {@code NamedQuery} + * The name of this {@code NamedQuery}. */ String name(); /** - * @return returns the query string for this {@code NamedQuery} + * The query string for this {@code NamedQuery}. */ String query(); /** - * @return returns the flush mode for this query + * The flush mode for this query. */ FlushModeType flushMode() default FlushModeType.PERSISTENCE_CONTEXT; /** - * @return returns whether this query is cacheable or not + * Whether the query (results) is cacheable or not. Default is {@code false}, that is not cacheable. */ boolean cacheable() default false; /** - * @return returns the the cache region to use + * If the query results are cacheable, name the query cache region to use. */ String cacheRegion() default ""; /** - * @return returns the number of rows fetched by the JDBC Driver per database round-trip + * The number of rows fetched by the JDBC Driver per trip. */ int fetchSize() default -1; /** - * @return return the query timeout in seconds + * The query timeout (in seconds). Default is no timeout. */ int timeout() default -1; /** - * @return returns the comment added to the SQL query (useful for the DBA) + * A comment added to the generated SQL query. Useful when engaging with DBA. */ String comment() default ""; /** - * @return returns the cache mode used for this query + * The cache mode used for this query. This refers to entities/collections returned from the query. */ CacheModeType cacheMode() default CacheModeType.NORMAL; /** - * @return returns whether the results are fetched in read-only mode or not. Default is {@code false} + * Whether the results should be read-only. Default is {@code false}. */ boolean readOnly() default false; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java b/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java index 84cf003f0f..b5e35d77d0 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java @@ -34,15 +34,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * This specifies that a property is part of the natural id of the entity. * * @author Nicol�s Lichtmaier + * * @see NaturalIdCache */ @Target( { METHOD, FIELD } ) @Retention( RUNTIME ) public @interface NaturalId { /** - * Is this natural id mutable (or immutable)? - * - * @return {@code true} indicates the natural id is mutable; {@code false} (the default) that it is immutable. + * Whether the natural id is mutable (or immutable)? {@code false} (the default) indicates it is immutable; + * {@code true} indicates it is mutable. */ boolean mutable() default false; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java b/hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java index 18e7484e77..8f795911b6 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java @@ -38,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target( { METHOD, FIELD }) @Retention(RUNTIME) public @interface NotFound { + /** + * The action to perform when an associated entity is not found. By default an exception is thrown. + */ NotFoundAction action() default NotFoundAction.EXCEPTION; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NotFoundAction.java b/hibernate-core/src/main/java/org/hibernate/annotations/NotFoundAction.java index c2fbb985f5..7460471e7b 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NotFoundAction.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NotFoundAction.java @@ -25,17 +25,18 @@ package org.hibernate.annotations; /** - * Actoin to use when an element is not found in DB while beeing expected + * Possible actions when an associated entity is not found in the database. Often seen with "legacy" foreign-key + * schemes which do not use {@code NULL} to indicate a missing reference, instead using a "magic value". * * @author Emmanuel Bernard */ public enum NotFoundAction { /** - * raise an exception when an element is not found (default and recommended) + * Raise an exception when an element is not found (default and recommended). */ EXCEPTION, /** - * ignore the element when not found in DB + * Ignore the element when not found in database. */ IGNORE } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/OnDelete.java b/hibernate-core/src/main/java/org/hibernate/annotations/OnDelete.java index 12d2bf414a..2278bed2fb 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/OnDelete.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/OnDelete.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -32,7 +33,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Strategy to use on collections, arrays and on joined subclasses delete + * Strategy to use on collections, arrays and on joined subclasses delete. + * * OnDelete of secondary tables currently not supported. * * @author Emmanuel Bernard @@ -40,5 +42,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({METHOD, FIELD, TYPE}) @Retention(RUNTIME) public @interface OnDelete { + /** + * The on-delete action. + */ OnDeleteAction action(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/OnDeleteAction.java b/hibernate-core/src/main/java/org/hibernate/annotations/OnDeleteAction.java index af53d0077d..3b839878c3 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/OnDeleteAction.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/OnDeleteAction.java @@ -23,19 +23,18 @@ */ package org.hibernate.annotations; - /** - * Possible actions on deletes + * Possible actions for on-delete. * * @author Emmanuel Bernard */ public enum OnDeleteAction { /** - * the default + * Take no action. The default. */ NO_ACTION, /** - * use cascade delete capabilities of the DD + * Use cascade delete capabilities of the database foreign-key. */ CASCADE } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLock.java b/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLock.java index 876efa84c6..ce3492d044 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLock.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLock.java @@ -30,6 +30,7 @@ import java.lang.annotation.Target; /** * Whether or not a change of the annotated property will trigger a entity version increment. + * * If the annotation is not present, the property is involved in the optimistic lock strategy (default). * * @author Logi Ragnarsson @@ -38,7 +39,7 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) public @interface OptimisticLock { /** - * @return If {@code true}, the annotated property change will not trigger a version increment. + * Whether the annotated property should be included in optimistic locking determinations for the owner. */ boolean excluded(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLockType.java b/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLockType.java index a6df6dd3a0..ce2ca87306 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLockType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLockType.java @@ -23,28 +23,30 @@ */ package org.hibernate.annotations; - /** - * Optimistic locking strategy - * VERSION is the default and recommended one + * Possible optimistic locking strategies. * * @author Emmanuel Bernard */ public enum OptimisticLockType { /** - * no optimistic locking + * Perform no optimistic locking. */ NONE, /** - * use a column version + * Perform optimistic locking using a dedicated version column. + * + * @see javax.persistence.Version */ VERSION, /** - * dirty columns are compared + * Perform optimistic locking based on *dirty* fields as part of an expanded WHERE clause restriction for the + * UPDATE/DELETE SQL statement. */ DIRTY, /** - * all columns are compared + * Perform optimistic locking based on *all* fields as part of an expanded WHERE clause restriction for the + * UPDATE/DELETE SQL statement. */ ALL } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLocking.java b/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLocking.java index 49278d2aca..564c6faba2 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLocking.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLocking.java @@ -38,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target( TYPE ) @Retention( RUNTIME ) public @interface OptimisticLocking { + /** + * Defines the style of optimistic locking for the entity. + */ OptimisticLockType type() default OptimisticLockType.VERSION; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java b/hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java index 70f4595f8b..4143b3b74c 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java @@ -30,13 +30,18 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Order a collection using SQL ordering (not HQL ordering) + * Order a collection using SQL ordering (not HQL ordering). * * @author Emmanuel Bernard + * + * @see javax.persistence.OrderBy + * @see Sort */ @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface OrderBy { - /** SQL orderby clause */ + /** + * SQL ordering clause. + */ String clause(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/ParamDef.java b/hibernate-core/src/main/java/org/hibernate/annotations/ParamDef.java index 57e457b098..d3bd662511 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/ParamDef.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/ParamDef.java @@ -22,20 +22,29 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * A parameter definition + * A parameter definition. * * @author Emmanuel Bernard */ @Target({}) @Retention(RUNTIME) public @interface ParamDef { + /** + * The name of the parameter definition. + */ String name(); + /** + * The type being defined, Typically this is the fully-qualified name of the {@link org.hibernate.type.Type}, + * {@link org.hibernate.usertype.UserType} or {@link org.hibernate.usertype.CompositeUserType} implementation + * class. + */ String type(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Parameter.java b/hibernate-core/src/main/java/org/hibernate/annotations/Parameter.java index 596292f020..9141a74af3 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Parameter.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Parameter.java @@ -28,14 +28,20 @@ import java.lang.annotation.Target; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Parameter (basically key/value pattern) + * Generic parameter (basically a key/value combination) used to parametrize other annotations. * * @author Emmanuel Bernard */ @Target({}) @Retention(RUNTIME) public @interface Parameter { + /** + * The parameter name. + */ String name(); + /** + * The parameter value. + */ String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Parent.java b/hibernate-core/src/main/java/org/hibernate/annotations/Parent.java index 7407a50268..3f8d398666 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Parent.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Parent.java @@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Reference the property as a pointer back to the owner (generally the owning entity) + * Reference the property as a pointer back to the owner (generally the owning entity). * * @author Emmanuel Bernard */ diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Persister.java b/hibernate-core/src/main/java/org/hibernate/annotations/Persister.java index 73897a5246..749978a37c 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Persister.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Persister.java @@ -36,7 +36,7 @@ import java.lang.annotation.RetentionPolicy; @Retention(RetentionPolicy.RUNTIME) public @interface Persister { /** - * @return The custom persister class + * The custom persister class. */ Class impl(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Polymorphism.java b/hibernate-core/src/main/java/org/hibernate/annotations/Polymorphism.java index 1be03925e5..08790562ab 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Polymorphism.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Polymorphism.java @@ -37,5 +37,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target( TYPE ) @Retention( RUNTIME ) public @interface Polymorphism { + /** + * Specifies the polymorphism type. + */ PolymorphismType type() default PolymorphismType.IMPLICIT; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/PolymorphismType.java b/hibernate-core/src/main/java/org/hibernate/annotations/PolymorphismType.java index 3b59889690..0d8558584c 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/PolymorphismType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/PolymorphismType.java @@ -23,19 +23,18 @@ */ package org.hibernate.annotations; - /** - * Type of available polymorphism for a particular entity + * Type of available polymorphism for a particular entity. * * @author Emmanuel Bernard */ public enum PolymorphismType { /** - * default, this entity is retrieved if any of its super entity is asked + * This entity is retrieved if any of its super entity are retrieved. The default, */ IMPLICIT, /** - * this entity is retrieved only if explicitly asked + * This entity is retrieved only if explicitly asked. */ EXPLICIT } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Proxy.java b/hibernate-core/src/main/java/org/hibernate/annotations/Proxy.java index 7e11c5637f..380f832a7d 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Proxy.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Proxy.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -29,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Lazy and proxy configuration of a particular class + * Lazy and proxy configuration of a particular class. * * @author Emmanuel Bernard */ @@ -37,12 +38,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface Proxy { /** - * Whether this class is lazy or not (default to true) + * Whether this class is lazy or not. Default to true. */ boolean lazy() default true; /** - * Proxy class or interface used. Default entity class name. + * Proxy class or interface used. Default is to use the entity class name. */ Class proxyClass() default void.class; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java b/hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java index 19635cd12c..d16e8015a5 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java @@ -24,21 +24,90 @@ package org.hibernate.annotations; /** - * + * Consolidation of hints available to Hibernate JPA queries. Mainly used to define features available on + * Hibernate queries that have no corollary in JPA queries. */ public class QueryHints { + /** + * Disallow instantiation. + */ + private QueryHints() { + } + /** + * The cache mode to use. + * + * @see org.hibernate.Query#setCacheMode + * @see org.hibernate.SQLQuery#setCacheMode + */ public static final String CACHE_MODE = "org.hibernate.cacheMode"; + + /** + * The cache region to use. + * + * @see org.hibernate.Query#setCacheRegion + * @see org.hibernate.SQLQuery#setCacheRegion + */ public static final String CACHE_REGION = "org.hibernate.cacheRegion"; + + /** + * Are the query results cacheable? + * + * @see org.hibernate.Query#setCacheable + * @see org.hibernate.SQLQuery#setCacheable + */ public static final String CACHEABLE = "org.hibernate.cacheable"; + + /** + * Is the query callable? Note: only valid for named native sql queries. + */ public static final String CALLABLE = "org.hibernate.callable"; + + /** + * Defines a comment to be applied to the SQL sent to the database. + * + * @see org.hibernate.Query#setComment + * @see org.hibernate.SQLQuery#setComment + */ public static final String COMMENT = "org.hibernate.comment"; + + /** + * Defines the JDBC fetch size to use. + * + * @see org.hibernate.Query#setFetchSize + * @see org.hibernate.SQLQuery#setFetchSize + */ public static final String FETCH_SIZE = "org.hibernate.fetchSize"; + + /** + * The flush mode to associate with the execution of the query. + * + * @see org.hibernate.Query#setFlushMode + * @see org.hibernate.SQLQuery#setFlushMode + * @see org.hibernate.Session#setFlushMode + */ public static final String FLUSH_MODE = "org.hibernate.flushMode"; + + /** + * Should entities returned from the query be set in read only mode? + * + * @see org.hibernate.Query#setReadOnly + * @see org.hibernate.SQLQuery#setReadOnly + * @see org.hibernate.Session#setReadOnly + */ public static final String READ_ONLY = "org.hibernate.readOnly"; + + /** + * Apply a Hibernate query timeout, which is defined in seconds. + * + * @see org.hibernate.Query#setTimeout + * @see org.hibernate.SQLQuery#setTimeout + */ public static final String TIMEOUT_HIBERNATE = "org.hibernate.timeout"; + + /** + * Apply a JPA query timeout, which is defined in milliseconds. + */ public static final String TIMEOUT_JPA = "javax.persistence.query.timeout"; - private QueryHints() { - } } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/ResultCheckStyle.java b/hibernate-core/src/main/java/org/hibernate/annotations/ResultCheckStyle.java index f0667636a2..8904909ecd 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/ResultCheckStyle.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/ResultCheckStyle.java @@ -23,18 +23,17 @@ */ package org.hibernate.annotations; - /** - * Possible checks on Sql Insert, Delete, Update + * Possible styles of checking return codes on SQL INSERT, UPDATE and DELETE queries. * * @author L�szl� Benke */ public enum ResultCheckStyle { /** - * Do not perform checking. Either user simply does not want checking, or is - * indicating a {@link java.sql.CallableStatement} execution in which the - * checks are being performed explicitly and failures are handled through - * propogation of {@link java.sql.SQLException}s. + * Do not perform checking. Might mean that the user really just does not want any checking. Might + * also mean that the user is expecting a failure to be indicated by a {@link java.sql.SQLException} being + * thrown (presumably from a {@link java.sql.CallableStatement} which is performing explicit checks and + * propagating failures back through the driver). */ NONE, /** diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/RowId.java b/hibernate-core/src/main/java/org/hibernate/annotations/RowId.java index 5405f20689..2556e30707 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/RowId.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/RowId.java @@ -29,7 +29,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Support for {@literal ROWID} mapping feature of Hibernate. + * Support for {@code ROWID} mapping feature of Hibernate. * * @author Steve Ebersole */ @@ -37,9 +37,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface RowId { /** - * Names the {@literal ROWID} identifier - * - * @return The {@literal ROWID} identifier + * Names the {@code ROWID} identifier. */ String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SQLDelete.java b/hibernate-core/src/main/java/org/hibernate/annotations/SQLDelete.java index db50b21540..8066b07ed0 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/SQLDelete.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/SQLDelete.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,7 +32,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * SqlDelete Annotation for overwriting Hibernate default DELETE method + * Custom SQL statement for delete of an entity/collection. * * @author L�szl� Benke */ @@ -39,12 +40,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention( RUNTIME ) public @interface SQLDelete { /** - * Procedure name or DELETE STATEMENT + * Procedure name or SQL DELETE statement. */ String sql(); /** - * Is the statement using stored procedure or not + * Is the statement callable (aka a {@link java.sql.CallableStatement})? */ boolean callable() default false; diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SQLDeleteAll.java b/hibernate-core/src/main/java/org/hibernate/annotations/SQLDeleteAll.java index 96ed9b9d8c..236024ada8 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/SQLDeleteAll.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/SQLDeleteAll.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; @@ -31,7 +32,7 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.TYPE; /** - * SqlDelete Annotation for overwriting Hibernate default DELETE ALL method + * Custom SQL statement for delete of all of a collection's elements. * * @author L�szl� Benke */ @@ -39,12 +40,12 @@ import static java.lang.annotation.ElementType.TYPE; @Retention( RetentionPolicy.RUNTIME ) public @interface SQLDeleteAll { /** - * Procedure name or DELETE STATEMENT + * Procedure name or SQL DELETE statement. */ String sql(); /** - * Is the statement using stored procedure or not + * Is the statement callable (aka a {@link java.sql.CallableStatement})? */ boolean callable() default false; diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SQLInsert.java b/hibernate-core/src/main/java/org/hibernate/annotations/SQLInsert.java index ea668043e1..ce2553c212 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/SQLInsert.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/SQLInsert.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,7 +32,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * SqlInsert Annotation for overwriting Hibernate default INSERT INTO method + * Custom SQL statement for insertion of an entity/collection. * * @author L�szl� Benke */ @@ -39,12 +40,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention( RUNTIME ) public @interface SQLInsert { /** - * Procedure name or INSERT STATEMENT + * Procedure name or SQL INSERT statement. */ String sql(); /** - * Is the statement using stored procedure or not + * Is the statement callable (aka a {@link java.sql.CallableStatement})? */ boolean callable() default false; diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SQLUpdate.java b/hibernate-core/src/main/java/org/hibernate/annotations/SQLUpdate.java index ea5e2ba260..9a10f42c0d 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/SQLUpdate.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/SQLUpdate.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,21 +32,20 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * SqlUpdate Annotation for overwriting Hibernate default UPDATE method + * Custom SQL statement for update of an entity/collection. * * @author L�szl� Benke */ @Target( {TYPE, FIELD, METHOD} ) @Retention( RUNTIME ) public @interface SQLUpdate { - /** - * Procedure name or UPDATE STATEMENT + * Procedure name or SQL UPDATE statement. */ String sql(); /** - * Is the statement using stored procedure or not + * Is the statement callable (aka a {@link java.sql.CallableStatement})? */ boolean callable() default false; diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SelectBeforeUpdate.java b/hibernate-core/src/main/java/org/hibernate/annotations/SelectBeforeUpdate.java index 5e4464ed17..9c4fe2c9fa 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/SelectBeforeUpdate.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/SelectBeforeUpdate.java @@ -38,5 +38,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target( TYPE ) @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. + */ boolean value() default true; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Sort.java b/hibernate-core/src/main/java/org/hibernate/annotations/Sort.java index 0070dcb9a2..0fe5faa70e 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Sort.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Sort.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -30,22 +31,24 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Collection sort - * (Java level sorting) + * Collection sort (in-memory sorting). Different that ordering, which is applied during the SQL select. * * @author Emmanuel Bernard + * + * @see OrderBy */ @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface Sort { /** - * sort type + * The type of sorting to use. The default is to not use sorting. */ SortType type() default SortType.UNSORTED; - /** - * Sort comparator implementation - */ - //TODO find a way to use Class + /** + * Specifies the comparator to use. Only valid when {@link #type} specifies {@link SortType#COMPARATOR}. + * + * TODO find a way to use Class -> see HHH-8164 + */ Class comparator() default void.class; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SortType.java b/hibernate-core/src/main/java/org/hibernate/annotations/SortType.java index b33c772189..18f7aa8727 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/SortType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/SortType.java @@ -23,14 +23,22 @@ */ package org.hibernate.annotations; - /** - * Sort strategies + * Possible collection sorting strategies. * * @author Emmanuel Bernard */ public enum SortType { + /** + * The collection is unsorted. + */ UNSORTED, + /** + * The collection is sorted using its natural sorting. + */ NATURAL, + /** + * The collection is sorted using a supplied comparator. + */ COMPARATOR } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Source.java b/hibernate-core/src/main/java/org/hibernate/annotations/Source.java index 5152d04198..30d575beef 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Source.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Source.java @@ -21,8 +21,8 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ - package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,13 +31,16 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Optional annotation in conjunction with {@link javax.persistence.Version} and timestamp version properties. - * The annotation value decides where the timestamp is generated. + * Optional annotation in conjunction with {@link javax.persistence.Version} and timestamp version properties + * indicating the source of the timestamp value. * * @author Hardy Ferentschik */ @Target({ METHOD, FIELD }) @Retention(RUNTIME) public @interface Source { + /** + * How is the timestamp generated? Default is a JVM generated value. + */ SourceType value() default SourceType.VM; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java b/hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java index 907d1722f2..f9468923a8 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java @@ -21,10 +21,8 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ - package org.hibernate.annotations; - /** * Where should Hibernate retrieve the value from? From the database, or from the current JVM? * @@ -34,19 +32,24 @@ public enum SourceType { /** * Get the timestamp from the current VM. */ - VM("timestamp"), + VM( "timestamp" ), /** * Get the timestamp from the database. */ - DB("dbtimestamp"); + DB( "dbtimestamp" ); private final String typeName; - SourceType(String typeName ) { + private SourceType(String typeName ) { this.typeName = typeName; } + /** + * Get the corresponding Hibernate {@link org.hibernate.type.VersionType} name. + * + * @return The corresponding type name. + */ public String typeName() { return typeName; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SqlFragmentAlias.java b/hibernate-core/src/main/java/org/hibernate/annotations/SqlFragmentAlias.java index 031ff6417d..b850a5559b 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/SqlFragmentAlias.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/SqlFragmentAlias.java @@ -29,15 +29,27 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Retention; import java.lang.annotation.Target; + /** - * Describe aliases for filters + * Describe aliases for filters. * * @author Rob Worsnop */ @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface SqlFragmentAlias { + /** + * The alias within the fragment. + */ String alias(); + + /** + * The table corresponding to the alias. + */ String table() default ""; + + /** + * The entity class associated with the alias. + */ Class entity() default void.class; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Subselect.java b/hibernate-core/src/main/java/org/hibernate/annotations/Subselect.java index 28cd043006..8ed3cd758d 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Subselect.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Subselect.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -29,12 +30,17 @@ 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 subselect expression: - * @author Sharath Reddy + * Map an immutable and read-only entity to a given SQL select expression. * + * @see Synchronize + * + * @author Sharath Reddy */ @Target(TYPE) @Retention(RUNTIME) public @interface Subselect { + /** + * The query. + */ String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Synchronize.java b/hibernate-core/src/main/java/org/hibernate/annotations/Synchronize.java index 25e99e0958..fcdb41bedc 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Synchronize.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Synchronize.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -32,7 +33,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * Ensures that auto-flush happens correctly and that queries against the derived * entity do not return stale data. * - * Mostly used with Subselect. + * Mostly used with {@link Subselect}. * * @author Sharath Reddy */ @@ -40,7 +41,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface Synchronize { /** - * Table names + * Table names. */ - String [] value(); + String[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Table.java b/hibernate-core/src/main/java/org/hibernate/annotations/Table.java index f4c1119b6a..43338e0dc1 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Table.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Table.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -29,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Complementary information to a table either primary or secondary + * Complementary information to a table either primary or secondary. * * @author Emmanuel Bernard */ @@ -37,23 +38,22 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Retention(RUNTIME) public @interface Table { /** - * name of the targeted table + * name of the targeted table. */ String appliesTo(); /** - * Indexes + * Indexes. */ Index[] indexes() default {}; /** - * define a table comment + * define a table comment. */ String comment() default ""; /** - * Defines the Foreign Key name of a secondary table - * pointing back to the primary table + * Defines the Foreign Key name of a secondary table pointing back to the primary table. */ ForeignKey foreignKey() default @ForeignKey( name="" ); @@ -86,21 +86,21 @@ public @interface Table { boolean optional() default true; /** - * Defines a custom SQL insert statement + * Defines a custom SQL insert statement. * * Only applies to secondary tables */ SQLInsert sqlInsert() default @SQLInsert(sql=""); /** - * Defines a custom SQL update statement + * Defines a custom SQL update statement. * * Only applies to secondary tables */ SQLUpdate sqlUpdate() default @SQLUpdate(sql=""); /** - * Defines a custom SQL delete statement + * Defines a custom SQL delete statement. * * Only applies to secondary tables */ diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Tables.java b/hibernate-core/src/main/java/org/hibernate/annotations/Tables.java index 2df5b35e47..6159ec2ceb 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Tables.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Tables.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -29,13 +30,15 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Plural of Table + * A grouping of tables. * * @author Emmanuel Bernard - * @see Table */ @Target({TYPE}) @Retention(RUNTIME) public @interface Tables { + /** + * The table grouping. + */ Table[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Target.java b/hibernate-core/src/main/java/org/hibernate/annotations/Target.java index 480b273161..72dab62eb6 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Target.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Target.java @@ -21,18 +21,22 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; +package org.hibernate.annotations; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; /** - * Define an explicit target,a voiding reflection and generics resolving + * Define an explicit target, avoiding reflection and generics resolving. * * @author Emmanuel Bernard */ @java.lang.annotation.Target({ElementType.FIELD, ElementType.METHOD}) @Retention( RetentionPolicy.RUNTIME ) public @interface Target { + /** + * The target entity type. + */ Class value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Tuplizer.java b/hibernate-core/src/main/java/org/hibernate/annotations/Tuplizer.java index 1f8037cf33..c692a36455 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Tuplizer.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Tuplizer.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import org.hibernate.EntityMode; @@ -32,19 +33,27 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Define a tuplizer for an entity or a component + * Define a tuplizer for an entity or a component. + * * @author Emmanuel Bernard */ @java.lang.annotation.Target( {TYPE, FIELD, METHOD} ) @Retention( RUNTIME ) public @interface Tuplizer { - /** tuplizer implementation */ - Class impl(); /** - * either pojo, dynamic-map or dom4j + * Tuplizer implementation. + */ + Class impl(); + + /** + * either pojo, dynamic-map or dom4j. * @deprecated should use #entityModeType instead */ @Deprecated String entityMode() default "pojo"; + + /** + * The entity mode. + */ EntityMode entityModeType() default EntityMode.POJO; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Tuplizers.java b/hibernate-core/src/main/java/org/hibernate/annotations/Tuplizers.java index 78924b842d..6a14061d01 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Tuplizers.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Tuplizers.java @@ -21,17 +21,22 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; +package org.hibernate.annotations; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; /** - * Define a set of tuplizer for an entity or a component + * Grouping of tuplizers. + * * @author Emmanuel Bernard */ @java.lang.annotation.Target( {ElementType.TYPE, ElementType.FIELD, ElementType.METHOD} ) @Retention( RetentionPolicy.RUNTIME ) public @interface Tuplizers { + /** + * The grouping of tuplizers. + */ Tuplizer[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Type.java b/hibernate-core/src/main/java/org/hibernate/annotations/Type.java index 3ca6583dc0..a3fc6d3ea7 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Type.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Type.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -30,14 +31,30 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * hibernate type + * Defines a Hibernate type mapping. + * + * @see org.hibernate.type.Type + * @see org.hibernate.usertype.UserType + * @see org.hibernate.usertype.CompositeUserType + * + * @see TypeDef * * @author Emmanuel Bernard + * @author Steve Ebersole */ @Target({FIELD, METHOD}) @Retention(RUNTIME) public @interface Type { + /** + * The Hibernate type name. Usually the fully qualified name of an implementation class for + * {@link org.hibernate.type.Type}, {@link org.hibernate.usertype.UserType} or + * {@link org.hibernate.usertype.CompositeUserType}. May also refer to a type definition by name + * {@link TypeDef#name()} + */ String type(); + /** + * Any configuration parameters for the named type. + */ Parameter[] parameters() default {}; -} \ No newline at end of file +} diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/TypeDef.java b/hibernate-core/src/main/java/org/hibernate/annotations/TypeDef.java index 8b2d355266..f25825fec9 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/TypeDef.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/TypeDef.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -30,15 +31,38 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Type definition + * A type definition. Much like {@link Type}, but here we can centralize the definition under a name and + * refer to that name elsewhere. + * + * @see org.hibernate.type.Type + * @see org.hibernate.usertype.UserType + * @see org.hibernate.usertype.CompositeUserType + * + * @see Type * * @author Emmanuel Bernard + * @author Steve Ebersole */ @Target({TYPE, PACKAGE}) @Retention(RUNTIME) public @interface TypeDef { + /** + * The type name. This is the name that would be used in other locations. + */ String name() default ""; - Class defaultForType() default void.class; + + /** + * The type implementation class. + */ Class typeClass(); + + /** + * Name a java type for which this defined type should be the default mapping. + */ + Class defaultForType() default void.class; + + /** + * Any configuration parameters for this type definition. + */ Parameter[] parameters() default {}; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/TypeDefs.java b/hibernate-core/src/main/java/org/hibernate/annotations/TypeDefs.java index 9e562b4246..55542ad01b 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/TypeDefs.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/TypeDefs.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -30,12 +31,15 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Type definition array + * Grouping of type definitions. * * @author Emmanuel Bernard */ @Target({TYPE, PACKAGE}) @Retention(RUNTIME) public @interface TypeDefs { + /** + * The grouping of type defs. + */ TypeDef[] value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Where.java b/hibernate-core/src/main/java/org/hibernate/annotations/Where.java index 3d60347b43..bd3e032d57 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Where.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Where.java @@ -22,6 +22,7 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; + import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -31,13 +32,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 + * 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. * * @author Emmanuel Bernard */ @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) public @interface Where { + /** + * The where-clause predicate. + */ String clause(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java b/hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java index 9b9adf3d7d..f6f8357da9 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java @@ -21,20 +21,24 @@ * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA */ -package org.hibernate.annotations; +package org.hibernate.annotations; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Where clause to add to the colleciton join table - * The clause is written in SQL + * 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. * * @author Emmanuel Bernard */ @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface WhereJoinTable { + /** + * The where-clause predicate. + */ String clause(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java b/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java new file mode 100644 index 0000000000..a01041a44b --- /dev/null +++ b/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java @@ -0,0 +1,4 @@ +/** + * Package containing all the Hibernate specific annotations. + */ +package org.hibernate.annotations; diff --git a/shared/config/checkstyle/public_checks.xml b/shared/config/checkstyle/public_checks.xml new file mode 100644 index 0000000000..8cdad56c57 --- /dev/null +++ b/shared/config/checkstyle/public_checks.xml @@ -0,0 +1,145 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +