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 ddb2703690..af2e72b8ca 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/AccessType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/AccessType.java @@ -36,9 +36,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * Prefer the standard {@link javax.persistence.Access} annotation * * @author Emmanuel Bernard + * + * @deprecated Use {@link AttributeAccessor} instead; renamed to avoid confusion with the JPA + * {@link javax.persistence.AccessType} enum. */ @Target({ TYPE, METHOD, FIELD }) @Retention(RUNTIME) +@Deprecated public @interface AccessType { String value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Any.java b/hibernate-core/src/main/java/org/hibernate/annotations/Any.java index 8ab0e1a308..7ec5a179f5 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Any.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Any.java @@ -31,11 +31,32 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Define a ToOne association pointing to several entity types. - * Matching the according entity type is doe through a metadata discriminator column - * This kind of mapping should be only marginal. - * + * Defines a ToOne-style association pointing to one of several entity types depending on a local discriminator, + * as opposed to discriminated inheritance where the discriminator is kept as part of the entity hierarchy. + * + * 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): + * 
+ *    @Entity
+ *    class Order {
+ *        ...
+ *        @Any( metaColumn = @Column( name="payment_type" ) )
+ *        @AnyMetDef(
+ *                idType = "long"
+ *                metaValues = {
+ *                        @MetaValue( value="C", targetEntity=CashPayment.class ),
+ *                        @MetaValue( value="CC", targetEntity=CreditCardPayment.class ),
+ *                }
+ *        )
+ *        pubic Payment getPayment() { ... }
+ *    }
+ * }
+ *
+ * * @author Emmanuel Bernard + * @author Steve Ebersole */ @java.lang.annotation.Target({METHOD, FIELD}) @Retention(RUNTIME) @@ -48,10 +69,10 @@ public @interface Any { String metaDef() default ""; /** - * Metadata discriminator column description, This column will hold the meta value corresponding to the - * targeted entity. + * Identifies the discriminator column. This column will hold the value that identifies the targeted entity. */ Column metaColumn(); + /** * 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 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 cc50fa9425..e7cac8a031 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDef.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDef.java @@ -31,9 +31,12 @@ import static java.lang.annotation.ElementType.TYPE; 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 Steve Ebersole */ @java.lang.annotation.Target( { PACKAGE, TYPE, METHOD, FIELD } ) @Retention( RUNTIME ) @@ -45,18 +48,18 @@ public @interface AnyMetaDef { 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(); /** - * Hibernate type of the id column - * @return Hibernate type of the id column + * Names the identifier Hibernate Type for the entity associated through this Any/ManyToAny mapping. */ String idType(); /** - * Matching discriminator values with their respective entity + * Maps discriminator values to the matching corresponding entity types. */ MetaValue[] metaValues(); } 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 268418bd0e..0de690efa7 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDefs.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDefs.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.PACKAGE; @@ -29,10 +30,10 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Defines @Any and @ManyToAny set of metadata. - * Can be defined at the entity level or the package level + * Used to group together {@link AnyMetaDef} annotations. Can be defined at the entity or package level * * @author Emmanuel Bernard + * @author Steve Ebersole */ @java.lang.annotation.Target( { PACKAGE, TYPE } ) @Retention( RUNTIME ) diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java b/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java new file mode 100644 index 0000000000..32991f4865 --- /dev/null +++ b/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java @@ -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: + * + * 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(); +} 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 0219574aaf..414af5199c 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.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,31 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Batch size for SQL loading + * Defines size for batch loading of collections or lazy entities. For example... + * 
+ *     @Entity
+ *     @BatchSize(size=100)
+ *     class Product {
+ *         ...
+ *     }
+ *
+ * will initialize up to 100 lazy Product entity proxies at a time. + * + * 
+ *     	@OneToMany
+ *     	@BatchSize(size = 5) /
+ *     	Set getProducts() { ... };
+ *
+ * will initialize up to 5 lazy collections of products at a time * * @author Emmanuel Bernard + * @author Steve Ebersole */ @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) public @interface BatchSize { - /** Strictly positive integer */ + /** + * Strictly positive integer + */ int size(); } 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 2e3762292e..406adb7948 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java @@ -30,7 +30,12 @@ import static java.lang.annotation.ElementType.METHOD; 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}) @Retention(RUNTIME) 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 0cf7b204fd..2767b824c2 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java @@ -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 { ALL, 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 ee14d715df..4929f71fbd 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Check.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Check.java @@ -31,8 +31,7 @@ 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 */ 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 199ab14ff9..5bbe42d538 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/CollectionType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/CollectionType.java @@ -30,7 +30,8 @@ import static java.lang.annotation.ElementType.METHOD; 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.usertype.UserCollectionType 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 810d2b5dbf..0d9c1c4486 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java @@ -34,7 +34,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * The write expression must contain exactly one '?' placeholder for the value. * * For example: read="decrypt(credit_card_num)" write="encrypt(?)" - * + * + * @see ColumnTransformers + * * @author Emmanuel Bernard */ @java.lang.annotation.Target({FIELD,METHOD}) 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 6761631fa9..c272298480 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorFormula.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorFormula.java @@ -29,11 +29,15 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Discriminator formula - * To be placed at the root entity. + * Used to apply a Hibernate formula (derived value) as the inheritance discriminator "column". Used in place of + * the JPA {@link javax.persistence.DiscriminatorColumn} when a formula is wanted. + * + * To be placed on the root entity. + * + * @see Formula * * @author Emmanuel Bernard - * @see Formula + * @author Steve Ebersole */ @Target({TYPE}) @Retention(RUNTIME) 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 73a496276e..813d8fd94b 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java @@ -30,10 +30,34 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Formula. To be used as a replacement for @Column in most places - * The formula has to be a valid SQL fragment + * Defines a formula (derived value) which is a SQL fragment that acts as a @Column alternative in most cases. + * Represents read-only state. + * + * In certain cases @ColumnTransformer might be a better option, especially as it leaves open the option of still + * being writable. + * + * 
+ *     // perform calculations
+ *     @Formula( "sub_total + (sub_total * tax)" )
+ *     long getTotalCost() { ... }
+ *
+ * + * 
+ *     // call functions
+ *     @Formula( "upper( substring( middle_name, 1 ) )" )
+ *     Character getMiddleInitial() { ... }
+ *
+ * + * 
+ *     // this might be better handled through @ColumnTransformer
+ *     @Formula( "decrypt(credit_card_num)" )
+ *     String getCreditCardNumber() { ... }
+ *
+ * + * @see ColumnTransformer * * @author Emmanuel Bernard + * @author Steve Ebersole */ @Target({METHOD, FIELD}) @Retention(RUNTIME) diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/ManyToAny.java b/hibernate-core/src/main/java/org/hibernate/annotations/ManyToAny.java index bb20cc1e00..6fae415eb1 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/ManyToAny.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/ManyToAny.java @@ -22,20 +22,23 @@ * Boston, MA 02110-1301 USA */ package org.hibernate.annotations; -import java.lang.annotation.Retention; + import javax.persistence.Column; import javax.persistence.FetchType; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Defined a ToMany association pointing to different entity types. - * Matching the according entity type is doe through a metadata discriminator column - * This kind of mapping should be only marginal. + * This is the collection-valued form of @Any definitions. Defines a ToMany-style association pointing + * to one of several entity types depending on a local discriminator. See {@link Any} for further information. + * + * @see Any * * @author Emmanuel Bernard + * @author Steve Ebersole */ @java.lang.annotation.Target({METHOD, FIELD}) @Retention(RUNTIME) 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 d6fa60c89e..e9428b019d 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/MetaValue.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/MetaValue.java @@ -23,10 +23,13 @@ */ 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 Steve Ebersole */ public @interface MetaValue { /**