HHH-7626 - Add javadoc to annotations
This commit is contained in:
parent
5aad2bf84b
commit
a8a3f9b112
|
@ -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();
|
||||||
}
|
}
|
||||||
|
|
|
@ -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>
|
||||||
|
* @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() { ... }
|
||||||
|
* }
|
||||||
|
* }
|
||||||
|
* </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
|
||||||
|
|
|
@ -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();
|
||||||
}
|
}
|
||||||
|
|
|
@ -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 )
|
||||||
|
|
|
@ -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
|
* 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>
|
||||||
|
* @Entity
|
||||||
|
* @BatchSize(size=100)
|
||||||
|
* class Product {
|
||||||
|
* ...
|
||||||
|
* }
|
||||||
|
* </pre></blockquote>
|
||||||
|
* will initialize up to 100 lazy Product entity proxies at a time.
|
||||||
|
*
|
||||||
|
* <blockquote><pre>
|
||||||
|
* @OneToMany
|
||||||
|
* @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();
|
||||||
}
|
}
|
||||||
|
|
|
@ -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)
|
||||||
|
|
|
@ -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,
|
||||||
|
|
|
@ -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
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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})
|
||||||
|
|
|
@ -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)
|
||||||
|
|
|
@ -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
|
||||||
|
* @Formula( "sub_total + (sub_total * tax)" )
|
||||||
|
* long getTotalCost() { ... }
|
||||||
|
* </pre></blockquote>
|
||||||
|
*
|
||||||
|
* <blockquote><pre>
|
||||||
|
* // call functions
|
||||||
|
* @Formula( "upper( substring( middle_name, 1 ) )" )
|
||||||
|
* Character getMiddleInitial() { ... }
|
||||||
|
* </pre></blockquote>
|
||||||
|
*
|
||||||
|
* <blockquote><pre>
|
||||||
|
* // this might be better handled through @ColumnTransformer
|
||||||
|
* @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)
|
||||||
|
|
|
@ -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)
|
||||||
|
|
|
@ -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 {
|
||||||
/**
|
/**
|
||||||
|
|
Loading…
Reference in New Issue