Permalink
Browse files

HHH-7626 - Add javadoc to annotations

  • Loading branch information...
1 parent 5aad2bf commit a8a3f9b11287ff2350aef9bc976ae990918a6f91 @sebersole sebersole committed Sep 20, 2012
@@ -36,9 +36,13 @@
* 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();
}
@@ -31,11 +31,32 @@
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):
+ * <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 Steve Ebersole
*/
@java.lang.annotation.Target({METHOD, FIELD})
@Retention(RUNTIME)
@@ -48,10 +69,10 @@
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
@@ -31,9 +31,12 @@
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 @@
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();
}
@@ -22,17 +22,18 @@
* Boston, MA 02110-1301 USA
*/
package org.hibernate.annotations;
+
import java.lang.annotation.Retention;
import static java.lang.annotation.ElementType.PACKAGE;
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 )
@@ -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();
+}
@@ -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.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 Steve Ebersole
*/
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface BatchSize {
- /** Strictly positive integer */
+ /**
+ * Strictly positive integer
+ */
int size();
}
@@ -30,7 +30,12 @@
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)
@@ -25,7 +25,7 @@
/**
- * Cascade types (can override default EJB3 cascades
+ * Cascade types (can override default JPA cascades
*/
public enum CascadeType {
ALL,
@@ -31,8 +31,7 @@
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
*/
@@ -30,7 +30,8 @@
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
@@ -34,7 +34,9 @@
* The write expression must contain exactly one '?' placeholder for the value.
*
* For example: <code>read="decrypt(credit_card_num)" write="encrypt(?)"</code>
- *
+ *
+ * @see ColumnTransformers
+ *
* @author Emmanuel Bernard
*/
@java.lang.annotation.Target({FIELD,METHOD})
@@ -29,11 +29,15 @@
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.
*
- * @author Emmanuel Bernard
* @see Formula
+ *
+ * @author Emmanuel Bernard
+ * @author Steve Ebersole
*/
@Target({TYPE})
@Retention(RUNTIME)
@@ -30,10 +30,34 @@
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.
+ *
+ * <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 Steve Ebersole
*/
@Target({METHOD, FIELD})
@Retention(RUNTIME)
@@ -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)
@@ -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 {
/**

0 comments on commit a8a3f9b

Please sign in to comment.