HHH-7626 - Add javadoc to annotations

This commit is contained in:
Steve Ebersole 2012-09-20 10:04:27 -05:00
parent 5aad2bf84b
commit a8a3f9b112
15 changed files with 182 additions and 32 deletions

View File

@ -36,9 +36,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* Prefer the standard {@link javax.persistence.Access} annotation * Prefer the standard {@link javax.persistence.Access} annotation
* *
* @author Emmanuel Bernard * @author Emmanuel Bernard
*
* @deprecated Use {@link AttributeAccessor} instead; renamed to avoid confusion with the JPA
* {@link javax.persistence.AccessType} enum.
*/ */
@Target({ TYPE, METHOD, FIELD }) @Target({ TYPE, METHOD, FIELD })
@Retention(RUNTIME) @Retention(RUNTIME)
@Deprecated
public @interface AccessType { public @interface AccessType {
String value(); String value();
} }

View File

@ -31,11 +31,32 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Define a ToOne association pointing to several entity types. * Defines a ToOne-style association pointing to one of several entity types depending on a local discriminator,
* Matching the according entity type is doe through a metadata discriminator column * as opposed to discriminated inheritance where the discriminator is kept as part of the entity hierarchy.
* This kind of mapping should be only marginal. *
* * For example, if you consider an Order entity containing Payment information where Payment might be of type
* CashPayment or CreditCardPayment the @Any approach would be to keep that discriminator and matching value on the
* Order itself. Thought of another way, the "foreign-key" really is made up of the value and discriminator
* (there is no physical foreign key here as databases do not support this):
* <blockquote><pre>
* &#064;Entity
* class Order {
* ...
* &#064;Any( metaColumn = @Column( name="payment_type" ) )
* &#064;AnyMetDef(
* idType = "long"
* metaValues = {
* &#064;MetaValue( value="C", targetEntity=CashPayment.class ),
* &#064;MetaValue( value="CC", targetEntity=CreditCardPayment.class ),
* }
* )
* pubic Payment getPayment() { ... }
* }
* }
* </pre></blockquote>
*
* @author Emmanuel Bernard * @author Emmanuel Bernard
* @author Steve Ebersole
*/ */
@java.lang.annotation.Target({METHOD, FIELD}) @java.lang.annotation.Target({METHOD, FIELD})
@Retention(RUNTIME) @Retention(RUNTIME)
@ -48,10 +69,10 @@ public @interface Any {
String metaDef() default ""; String metaDef() default "";
/** /**
* Metadata discriminator column description, This column will hold the meta value corresponding to the * Identifies the discriminator column. This column will hold the value that identifies the targeted entity.
* targeted entity.
*/ */
Column metaColumn(); Column metaColumn();
/** /**
* Defines whether the value of the field or property should be lazily loaded or must be * Defines whether the value of the field or property should be lazily loaded or must be
* eagerly fetched. The EAGER strategy is a requirement on the persistence provider runtime * eagerly fetched. The EAGER strategy is a requirement on the persistence provider runtime

View File

@ -31,9 +31,12 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Defines @Any and @manyToAny metadata * Used to provide metadata about an {@link Any} or {@link ManyToAny} mapping.
*
* @see AnyMetaDefs
* *
* @author Emmanuel Bernard * @author Emmanuel Bernard
* @author Steve Ebersole
*/ */
@java.lang.annotation.Target( { PACKAGE, TYPE, METHOD, FIELD } ) @java.lang.annotation.Target( { PACKAGE, TYPE, METHOD, FIELD } )
@Retention( RUNTIME ) @Retention( RUNTIME )
@ -45,18 +48,18 @@ public @interface AnyMetaDef {
String name() default ""; String name() default "";
/** /**
* meta discriminator Hibernate type * Names the discriminator Hibernate Type for this Any/ManyToAny mapping. The default is to use
* {@link org.hibernate.type.StringType}
*/ */
String metaType(); String metaType();
/** /**
* Hibernate type of the id column * Names the identifier Hibernate Type for the entity associated through this Any/ManyToAny mapping.
* @return Hibernate type of the id column
*/ */
String idType(); String idType();
/** /**
* Matching discriminator values with their respective entity * Maps discriminator values to the matching corresponding entity types.
*/ */
MetaValue[] metaValues(); MetaValue[] metaValues();
} }

View File

@ -22,6 +22,7 @@
* Boston, MA 02110-1301 USA * Boston, MA 02110-1301 USA
*/ */
package org.hibernate.annotations; package org.hibernate.annotations;
import java.lang.annotation.Retention; import java.lang.annotation.Retention;
import static java.lang.annotation.ElementType.PACKAGE; import static java.lang.annotation.ElementType.PACKAGE;
@ -29,10 +30,10 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Defines @Any and @ManyToAny set of metadata. * Used to group together {@link AnyMetaDef} annotations. Can be defined at the entity or package level
* Can be defined at the entity level or the package level
* *
* @author Emmanuel Bernard * @author Emmanuel Bernard
* @author Steve Ebersole
*/ */
@java.lang.annotation.Target( { PACKAGE, TYPE } ) @java.lang.annotation.Target( { PACKAGE, TYPE } )
@Retention( RUNTIME ) @Retention( RUNTIME )

View File

@ -0,0 +1,61 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* Copyright (c) 2012, Red Hat Inc. or third-party contributors as
* indicated by the @author tags or express copyright attribution
* statements applied by the authors. All third-party contributions are
* distributed under license by Red Hat Inc.
*
* This copyrighted material is made available to anyone wishing to use, modify,
* copy, or redistribute it subject to the terms and conditions of the GNU
* Lesser General Public License, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this distribution; if not, write to:
* Free Software Foundation, Inc.
* 51 Franklin Street, Fifth Floor
* Boston, MA 02110-1301 USA
*/
package org.hibernate.annotations;
import java.lang.annotation.Retention;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Names a {@link org.hibernate.property.PropertyAccessor} strategy to use.
*
* Can be specified at either:<ul>
* <li>
* <strong>TYPE</strong> level, which will act as naming the default accessor strategy for
* all attributes on the class which do not explicitly name an accessor strategy
* </li>
* <li>
* <strong>METHOD/FIELD</strong> level, which will be in effect for just that attribute.
* </li>
* </ul>
*
* Should only be used to name custom {@link org.hibernate.property.PropertyAccessor}. For {@code property/field}
* access, the JPA {@link javax.persistence.Access} annotation should be preferred using the appropriate
* {@link javax.persistence.AccessType}. However, if this annotation is used with either {@code value="property"}
* or {@code value="field"}, it will act just as the corresponding usage of {@link javax.persistence.Access}.
*
* @author Steve Ebersole
* @author Emmanuel Bernard
*/
@java.lang.annotation.Target({ TYPE, METHOD, FIELD })
@Retention(RUNTIME)
public @interface AttributeAccessor {
/**
* Names the {@link org.hibernate.property.PropertyAccessor} strategy
*/
String value();
}

View File

@ -22,6 +22,7 @@
* Boston, MA 02110-1301 USA * Boston, MA 02110-1301 USA
*/ */
package org.hibernate.annotations; package org.hibernate.annotations;
import java.lang.annotation.Retention; import java.lang.annotation.Retention;
import java.lang.annotation.Target; import java.lang.annotation.Target;
@ -31,13 +32,31 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Batch size for SQL loading * Defines size for batch loading of collections or lazy entities. For example...
* <blockquote><pre>
* &#064;Entity
* &#064;BatchSize(size=100)
* class Product {
* ...
* }
* </pre></blockquote>
* will initialize up to 100 lazy Product entity proxies at a time.
*
* <blockquote><pre>
* &#064;OneToMany
* &#064;BatchSize(size = 5) /
* Set<Product> getProducts() { ... };
* </pre></blockquote>
* will initialize up to 5 lazy collections of products at a time
* *
* @author Emmanuel Bernard * @author Emmanuel Bernard
* @author Steve Ebersole
*/ */
@Target({TYPE, METHOD, FIELD}) @Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME) @Retention(RUNTIME)
public @interface BatchSize { public @interface BatchSize {
/** Strictly positive integer */ /**
* Strictly positive integer
*/
int size(); int size();
} }

View File

@ -30,7 +30,12 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Apply a cascade strategy on an association * Apply a cascade strategy on an association. Used to apply Hibernate specific cascades. For JPA cascading, prefer
* using {@link javax.persistence.CascadeType} on {@link javax.persistence.OneToOne},
* {@link javax.persistence.OneToMany}, etc. Hibernate will merge together both sets of cascades.
*
* @author Emmanuel Bernard
* @author Steve Ebersole
*/ */
@Target({METHOD, FIELD}) @Target({METHOD, FIELD})
@Retention(RUNTIME) @Retention(RUNTIME)

View File

@ -25,7 +25,7 @@ package org.hibernate.annotations;
/** /**
* Cascade types (can override default EJB3 cascades * Cascade types (can override default JPA cascades
*/ */
public enum CascadeType { public enum CascadeType {
ALL, ALL,

View File

@ -31,8 +31,7 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Arbitrary SQL check constraints which can be defined at the class, * Arbitrary SQL CHECK constraints which can be defined at the class, property or collection level
* property or collection level
* *
* @author Emmanuel Bernard * @author Emmanuel Bernard
*/ */

View File

@ -30,7 +30,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Names a custom collection type for a persistent collection. * Names a custom collection type for a persistent collection. The collection can also name a @Type, which defines
* the Hibernate Type of the collection elements.
* *
* @see org.hibernate.type.CollectionType * @see org.hibernate.type.CollectionType
* @see org.hibernate.usertype.UserCollectionType * @see org.hibernate.usertype.UserCollectionType

View File

@ -34,7 +34,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* The write expression must contain exactly one '?' placeholder for the value. * The write expression must contain exactly one '?' placeholder for the value.
* *
* For example: <code>read="decrypt(credit_card_num)" write="encrypt(?)"</code> * For example: <code>read="decrypt(credit_card_num)" write="encrypt(?)"</code>
* *
* @see ColumnTransformers
*
* @author Emmanuel Bernard * @author Emmanuel Bernard
*/ */
@java.lang.annotation.Target({FIELD,METHOD}) @java.lang.annotation.Target({FIELD,METHOD})

View File

@ -29,11 +29,15 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Discriminator formula * Used to apply a Hibernate formula (derived value) as the inheritance discriminator "column". Used in place of
* To be placed at the root entity. * the JPA {@link javax.persistence.DiscriminatorColumn} when a formula is wanted.
*
* To be placed on the root entity.
*
* @see Formula
* *
* @author Emmanuel Bernard * @author Emmanuel Bernard
* @see Formula * @author Steve Ebersole
*/ */
@Target({TYPE}) @Target({TYPE})
@Retention(RUNTIME) @Retention(RUNTIME)

View File

@ -30,10 +30,34 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Formula. To be used as a replacement for @Column in most places * Defines a formula (derived value) which is a SQL fragment that acts as a @Column alternative in most cases.
* The formula has to be a valid SQL fragment * Represents read-only state.
*
* In certain cases @ColumnTransformer might be a better option, especially as it leaves open the option of still
* being writable.
*
* <blockquote><pre>
* // perform calculations
* &#064;Formula( "sub_total + (sub_total * tax)" )
* long getTotalCost() { ... }
* </pre></blockquote>
*
* <blockquote><pre>
* // call functions
* &#064;Formula( "upper( substring( middle_name, 1 ) )" )
* Character getMiddleInitial() { ... }
* </pre></blockquote>
*
* <blockquote><pre>
* // this might be better handled through @ColumnTransformer
* &#064;Formula( "decrypt(credit_card_num)" )
* String getCreditCardNumber() { ... }
* </pre></blockquote>
*
* @see ColumnTransformer
* *
* @author Emmanuel Bernard * @author Emmanuel Bernard
* @author Steve Ebersole
*/ */
@Target({METHOD, FIELD}) @Target({METHOD, FIELD})
@Retention(RUNTIME) @Retention(RUNTIME)

View File

@ -22,20 +22,23 @@
* Boston, MA 02110-1301 USA * Boston, MA 02110-1301 USA
*/ */
package org.hibernate.annotations; package org.hibernate.annotations;
import java.lang.annotation.Retention;
import javax.persistence.Column; import javax.persistence.Column;
import javax.persistence.FetchType; import javax.persistence.FetchType;
import java.lang.annotation.Retention;
import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Defined a ToMany association pointing to different entity types. * This is the collection-valued form of @Any definitions. Defines a ToMany-style association pointing
* Matching the according entity type is doe through a metadata discriminator column * to one of several entity types depending on a local discriminator. See {@link Any} for further information.
* This kind of mapping should be only marginal. *
* @see Any
* *
* @author Emmanuel Bernard * @author Emmanuel Bernard
* @author Steve Ebersole
*/ */
@java.lang.annotation.Target({METHOD, FIELD}) @java.lang.annotation.Target({METHOD, FIELD})
@Retention(RUNTIME) @Retention(RUNTIME)

View File

@ -23,10 +23,13 @@
*/ */
package org.hibernate.annotations; package org.hibernate.annotations;
/** /**
* Represent a discriminator value associated to a given entity type * Maps a given discriminator value to the corresponding entity type. See {@link Any} for more information.
*
* @see Any
*
* @author Emmanuel Bernard * @author Emmanuel Bernard
* @author Steve Ebersole
*/ */
public @interface MetaValue { public @interface MetaValue {
/** /**