Author: steve.ebersole(a)jboss.com Date: 2009-10-14 21:19:21 -0400 (Wed, 14 Oct 2009) New Revision: 17752 Added: jpa-api/trunk/build.gradle jpa-api/trunk/settings.gradle jpa-api/trunk/src/main/java/javax/persistence/MapKeyEnumerated.java jpa-api/trunk/src/main/java/javax/persistence/MapKeyTemporal.java jpa-api/trunk/src/main/java/javax/persistence/MapsId.java jpa-api/trunk/src/main/java/javax/persistence/SharedCacheMode.java jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaBuilder.java jpa-api/trunk/src/main/java/javax/persistence/spi/ProviderUtil.java Removed: jpa-api/trunk/src/main/java/javax/persistence/Caching.java jpa-api/trunk/src/main/java/javax/persistence/MappedById.java jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java Modified: jpa-api/trunk/src/main/java/javax/persistence/Access.java jpa-api/trunk/src/main/java/javax/persistence/AccessType.java jpa-api/trunk/src/main/java/javax/persistence/AssociationOverride.java jpa-api/trunk/src/main/java/javax/persistence/AssociationOverrides.java jpa-api/trunk/src/main/java/javax/persistence/AttributeOverride.java jpa-api/trunk/src/main/java/javax/persistence/AttributeOverrides.java jpa-api/trunk/src/main/java/javax/persistence/Basic.java jpa-api/trunk/src/main/java/javax/persistence/Cache.java jpa-api/trunk/src/main/java/javax/persistence/CacheRetrieveMode.java jpa-api/trunk/src/main/java/javax/persistence/CacheStoreMode.java jpa-api/trunk/src/main/java/javax/persistence/Cacheable.java jpa-api/trunk/src/main/java/javax/persistence/CascadeType.java jpa-api/trunk/src/main/java/javax/persistence/CollectionTable.java jpa-api/trunk/src/main/java/javax/persistence/Column.java jpa-api/trunk/src/main/java/javax/persistence/ColumnResult.java jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorColumn.java jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorType.java jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorValue.java jpa-api/trunk/src/main/java/javax/persistence/ElementCollection.java jpa-api/trunk/src/main/java/javax/persistence/Embeddable.java jpa-api/trunk/src/main/java/javax/persistence/Embedded.java jpa-api/trunk/src/main/java/javax/persistence/EmbeddedId.java jpa-api/trunk/src/main/java/javax/persistence/Entity.java jpa-api/trunk/src/main/java/javax/persistence/EntityExistsException.java jpa-api/trunk/src/main/java/javax/persistence/EntityListeners.java jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java jpa-api/trunk/src/main/java/javax/persistence/EntityNotFoundException.java jpa-api/trunk/src/main/java/javax/persistence/EntityResult.java jpa-api/trunk/src/main/java/javax/persistence/EntityTransaction.java jpa-api/trunk/src/main/java/javax/persistence/EnumType.java jpa-api/trunk/src/main/java/javax/persistence/Enumerated.java jpa-api/trunk/src/main/java/javax/persistence/ExcludeDefaultListeners.java jpa-api/trunk/src/main/java/javax/persistence/ExcludeSuperclassListeners.java jpa-api/trunk/src/main/java/javax/persistence/FetchType.java jpa-api/trunk/src/main/java/javax/persistence/FieldResult.java jpa-api/trunk/src/main/java/javax/persistence/FlushModeType.java jpa-api/trunk/src/main/java/javax/persistence/GeneratedValue.java jpa-api/trunk/src/main/java/javax/persistence/GenerationType.java jpa-api/trunk/src/main/java/javax/persistence/Id.java jpa-api/trunk/src/main/java/javax/persistence/IdClass.java jpa-api/trunk/src/main/java/javax/persistence/Inheritance.java jpa-api/trunk/src/main/java/javax/persistence/InheritanceType.java jpa-api/trunk/src/main/java/javax/persistence/JoinColumn.java jpa-api/trunk/src/main/java/javax/persistence/JoinColumns.java jpa-api/trunk/src/main/java/javax/persistence/JoinTable.java jpa-api/trunk/src/main/java/javax/persistence/Lob.java jpa-api/trunk/src/main/java/javax/persistence/LockModeType.java jpa-api/trunk/src/main/java/javax/persistence/LockTimeoutException.java jpa-api/trunk/src/main/java/javax/persistence/ManyToMany.java jpa-api/trunk/src/main/java/javax/persistence/ManyToOne.java jpa-api/trunk/src/main/java/javax/persistence/MapKey.java jpa-api/trunk/src/main/java/javax/persistence/MapKeyClass.java jpa-api/trunk/src/main/java/javax/persistence/MapKeyColumn.java jpa-api/trunk/src/main/java/javax/persistence/MapKeyJoinColumn.java jpa-api/trunk/src/main/java/javax/persistence/MapKeyJoinColumns.java jpa-api/trunk/src/main/java/javax/persistence/MappedSuperclass.java jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQueries.java jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQuery.java jpa-api/trunk/src/main/java/javax/persistence/NamedQueries.java jpa-api/trunk/src/main/java/javax/persistence/NamedQuery.java jpa-api/trunk/src/main/java/javax/persistence/NoResultException.java jpa-api/trunk/src/main/java/javax/persistence/NonUniqueResultException.java jpa-api/trunk/src/main/java/javax/persistence/OneToMany.java jpa-api/trunk/src/main/java/javax/persistence/OneToOne.java jpa-api/trunk/src/main/java/javax/persistence/OptimisticLockException.java jpa-api/trunk/src/main/java/javax/persistence/OrderBy.java jpa-api/trunk/src/main/java/javax/persistence/OrderColumn.java jpa-api/trunk/src/main/java/javax/persistence/Parameter.java jpa-api/trunk/src/main/java/javax/persistence/Persistence.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceContext.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceContextType.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceContexts.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceException.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceProperty.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnit.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnitUtil.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnits.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceUtil.java jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockException.java jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockScope.java jpa-api/trunk/src/main/java/javax/persistence/PostLoad.java jpa-api/trunk/src/main/java/javax/persistence/PostPersist.java jpa-api/trunk/src/main/java/javax/persistence/PostRemove.java jpa-api/trunk/src/main/java/javax/persistence/PostUpdate.java jpa-api/trunk/src/main/java/javax/persistence/PrePersist.java jpa-api/trunk/src/main/java/javax/persistence/PreRemove.java jpa-api/trunk/src/main/java/javax/persistence/PreUpdate.java jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumn.java jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumns.java jpa-api/trunk/src/main/java/javax/persistence/Query.java jpa-api/trunk/src/main/java/javax/persistence/QueryHint.java jpa-api/trunk/src/main/java/javax/persistence/QueryTimeoutException.java jpa-api/trunk/src/main/java/javax/persistence/RollbackException.java jpa-api/trunk/src/main/java/javax/persistence/SecondaryTable.java jpa-api/trunk/src/main/java/javax/persistence/SecondaryTables.java jpa-api/trunk/src/main/java/javax/persistence/SequenceGenerator.java jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMapping.java jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMappings.java jpa-api/trunk/src/main/java/javax/persistence/Table.java jpa-api/trunk/src/main/java/javax/persistence/TableGenerator.java jpa-api/trunk/src/main/java/javax/persistence/Temporal.java jpa-api/trunk/src/main/java/javax/persistence/TemporalType.java jpa-api/trunk/src/main/java/javax/persistence/TransactionRequiredException.java jpa-api/trunk/src/main/java/javax/persistence/Transient.java jpa-api/trunk/src/main/java/javax/persistence/Tuple.java jpa-api/trunk/src/main/java/javax/persistence/TupleElement.java jpa-api/trunk/src/main/java/javax/persistence/TypedQuery.java jpa-api/trunk/src/main/java/javax/persistence/UniqueConstraint.java jpa-api/trunk/src/main/java/javax/persistence/ValidationMode.java jpa-api/trunk/src/main/java/javax/persistence/Version.java jpa-api/trunk/src/main/java/javax/persistence/criteria/AbstractQuery.java jpa-api/trunk/src/main/java/javax/persistence/criteria/CollectionJoin.java jpa-api/trunk/src/main/java/javax/persistence/criteria/CompoundSelection.java jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaQuery.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Expression.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Fetch.java jpa-api/trunk/src/main/java/javax/persistence/criteria/FetchParent.java jpa-api/trunk/src/main/java/javax/persistence/criteria/From.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Join.java jpa-api/trunk/src/main/java/javax/persistence/criteria/JoinType.java jpa-api/trunk/src/main/java/javax/persistence/criteria/ListJoin.java jpa-api/trunk/src/main/java/javax/persistence/criteria/MapJoin.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Order.java jpa-api/trunk/src/main/java/javax/persistence/criteria/ParameterExpression.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Path.java jpa-api/trunk/src/main/java/javax/persistence/criteria/PluralJoin.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Predicate.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Root.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Selection.java jpa-api/trunk/src/main/java/javax/persistence/criteria/SetJoin.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Subquery.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/Attribute.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/BasicType.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/Bindable.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/CollectionAttribute.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/EmbeddableType.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/EntityType.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/IdentifiableType.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/ListAttribute.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/ManagedType.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/MapAttribute.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/MappedSuperclassType.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/Metamodel.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/PluralAttribute.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/SetAttribute.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/SingularAttribute.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/StaticMetamodel.java jpa-api/trunk/src/main/java/javax/persistence/metamodel/Type.java jpa-api/trunk/src/main/java/javax/persistence/spi/ClassTransformer.java jpa-api/trunk/src/main/java/javax/persistence/spi/LoadState.java jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProvider.java jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProviderResolver.java jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProviderResolverHolder.java jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitInfo.java jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitTransactionType.java Log: validated definitions against spec version dated 2009.10.08; added gradle build script Added: jpa-api/trunk/build.gradle =================================================================== --- jpa-api/trunk/build.gradle (rev 0) +++ jpa-api/trunk/build.gradle 2009-10-15 01:19:21 UTC (rev 17752) @@ -0,0 +1,39 @@ +usePlugin('java') + +configurations { + mavenDeployers +} + +dependencies { + mavenDeployers 'org.apache.maven.wagon:wagon-webdav:1.0-beta-2' +} + +group = 'org.hibernate.java-persistence' +version = '2.0-cr-1' + +// gradle uses 'build/' by default +buildDirName = "target" + +manifest.mainAttributes( + provider: 'gradle', + 'Built-By': 'Hibernate.org', + 'Specification-Title': 'Java Persistence API, Version 2.0', + 'Specification-Version': '2.0', + 'Specification-Vendor': 'Sun Microsystems, Inc.', + 'Implementation-Version': version, + 'Implementation-Vendor': 'hibernate.org', + 'Implementation-Title': 'Java Persistence API' +) + +if ( !hasProperty('jbossReleaseRepositoryRoot') ) { + jbossReleaseRepositoryRoot = '/tmp' +} +uploadArchives { + repositories { + deployer = mavenDeployer { + configuration = configurations.mavenDeployers + repository(url: "file://${jbossReleaseRepositoryRoot}") + snapshotRepository(url: "dav:https://snapshots.jboss.org/maven2") + } + } +} Added: jpa-api/trunk/settings.gradle =================================================================== --- jpa-api/trunk/settings.gradle (rev 0) +++ jpa-api/trunk/settings.gradle 2009-10-15 01:19:21 UTC (rev 17752) @@ -0,0 +1,3 @@ +// this is expected to be moved into the build file prior +// to Gradle 1.0, but needs to be here for now +rootProject.name = 'jpa-api' \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/Access.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Access.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Access.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -10,10 +10,18 @@ import java.lang.annotation.Target; /** - * @author Hardy Ferentschik + * Used to specify an access type to be applied to an entity class, + * mapped superclass, or embeddable class, or to a specific attribute + * of such a class. + * + * @since Java Persistence 2.0 */ -@Target({ TYPE, METHOD, FIELD }) +@Target( { TYPE, METHOD, FIELD }) @Retention(RUNTIME) public @interface Access { - AccessType value(); + + /** + * (Required) Specification of field- or property-based access. + */ + AccessType value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/AccessType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AccessType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/AccessType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,9 +3,19 @@ package javax.persistence; /** - * @author Hardy Ferentschik + * Is used with the {@link Access} annotation to specify an access + * type to be applied to an entity class, mapped superclass, or + * embeddable class, or to a specific attribute of such a class. + * + * @see Access + * + * @since Java Persistence 2.0 */ public enum AccessType { - FIELD, - PROPERTY + + /** Field-based access is used. */ + FIELD, + + /** Property-based access is used. */ + PROPERTY } Modified: jpa-api/trunk/src/main/java/javax/persistence/AssociationOverride.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AssociationOverride.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/AssociationOverride.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,30 +1,145 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.FIELD; -import static java.lang.annotation.ElementType.METHOD; -import static java.lang.annotation.ElementType.TYPE; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * This annotation is used to override a many-to-one or one-to-one mapping of property or field for - * an entity relationship. - * The AssociationOverride annotation may be applied to an entity that extends a mapped superclass - * to override a many-to-one or one-to-one mapping defined by the mapped superclass. If the - * AssociationOverride annotation is not specified, the join column is mapped the same as in - * the original mapping. + * Used to override a mapping for an entity relationship. * - * @author Emmanuel Bernard + * <p> May be applied to an entity that extends a mapped superclass to + * override a relationship mapping defined by the mapped + * superclass. If not specified, the association is mapped the same as + * in the original mapping. When used to override a mapping defined by + * a mapped superclass, <code>AssociationOverride</code> is applied to + * the entity class. + * + * <p> May be used to override a relationship mapping from an + * embeddable within an entity to another entity when the embeddable + * is on the owning side of the relationship. When used to override a + * relationship mapping defined by an embeddable class (including an + * embeddable class embedded within another embeddable class), + * <code>AssociationOverride</code> is applied to the field or + * property containing the embeddable. + * + * <p> When <code>AssociationOverride</code> is used to override a + * relationship mapping from an embeddable class, the + * <code>name</code> element specifies the referencing relationship + * field or property within the embeddable class. To override mappings + * at multiple levels of embedding, a dot (".") notation syntax must + * be used in the <code>name</code> element to indicate an attribute + * within an embedded attribute. The value of each identifier used + * with the dot notation is the name of the respective embedded field + * or property. + * + * <p> When <code>AssociationOverride</code> is applied to override + * the mappings of an embeddable class used as a map value, + * "<code>value.</code>" must be used to prefix the name of the + * attribute within the embeddable class that is being overridden in + * order to specify it as part of the map value. + * + * <p> If the relationship mapping is a foreign key mapping, the + * <code>joinColumns</code> element is used. If the relationship + * mapping uses a join table, the <code>joinTable</code> element must + * be specified to override the mapping of the join table and/or its + * join columns. + * + * <p> + * <pre> + * Example 1: Overriding the mapping of a relationship defined by a mapped superclass + * + * &#064;MappedSuperclass + * public class Employee { + * ... + * &#064;ManyToOne + * protected Address address; + * ... + * } + * + * &#064;Entity + * &#064;AssociationOverride(name="address", + * joinColumns=&#064;JoinColumn(name="ADDR_ID")) + * // address field mapping overridden to ADDR_ID foreign key + * public class PartTimeEmployee extends Employee { + * ... + * } + * </pre> + * + * <pre> + * Example 2: Overriding the mapping for phoneNumbers defined in the ContactInfo class + * + * &#064;Entity + * public class Employee { + * &#064;Id int id; + * &#064;AssociationOverride( + * name="phoneNumbers", + * joinTable=&#064;JoinTable( + * name="EMPPHONES", + * joinColumns=&#064;JoinColumn(name="EMP"), + * inverseJoinColumns=&#064;JoinColumn(name="PHONE") + * ) + * ) + * &#064;Embedded ContactInfo contactInfo; + * ... + * } + * + * &#064;Embeddable + * public class ContactInfo { + * &#064;ManyToOne Address address; // Unidirectional + * &#064;ManyToMany(targetEntity=PhoneNumber.class) List phoneNumbers; + * } + * + * &#064;Entity + * public class PhoneNumber { + * &#064;Id int number; + * &#064;ManyToMany(mappedBy="contactInfo.phoneNumbers") + * Collection&#060;Employee&#062; employees; + * } + * </pre> + * + * @see Embedded + * @see Embeddable + * @see MappedSuperclass + * @see AttributeOverride + * + * @since Java Persistence 1.0 */ -@Target({ TYPE, METHOD, FIELD }) +@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) + public @interface AssociationOverride { - String name(); - JoinColumn[] joinColumns() default { }; + /** + * (Required) The name of the relationship property whose mapping is + * being overridden if property-based access is being used, + * or the name of the relationship field if field-based access is used. + */ + String name(); - JoinTable joinTable() default @JoinTable; -} + /** + * The join column(s) being mapped to the persistent attribute(s). + * The <code>joinColumns</code> elements must be specified if a + * foreign key mapping is used in the overriding of the mapping of + * the relationship. The <code>joinColumns</code> element must + * not be specified if a join table is used in the overriding of + * the mapping of the relationship. + */ + JoinColumn[] joinColumns() default {}; + + /** + * The join table that maps the relationship. + * The <code>joinTable</code> element must be specified if a join table + * is used in the overriding of the mapping of the + * relationship. The <code>joinTable</code> element must not be specified + * if a foreign key mapping is used in the overriding of + * the relationship. + * + * @since Java Persistence 2.0 + */ + JoinTable joinTable() default @JoinTable; +} \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/AssociationOverrides.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AssociationOverrides.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/AssociationOverrides.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,24 +1,62 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; import java.lang.annotation.Target; import java.lang.annotation.Retention; -import static java.lang.annotation.RetentionPolicy.RUNTIME; import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * This annotation is used to override mappings of multiple many-to-one - * or one-to-one relationship properties or fields. + * Used to override mappings of multiple relationship properties or fields. * - * @author Emmanuel Bernard + * <pre> + * + * Example: + * + * &#064;MappedSuperclass + * public class Employee { + * + * &#064;Id protected Integer id; + * &#064;Version protected Integer version; + * &#064;ManyToOne protected Address address; + * &#064;OneToOne protected Locker locker; + * + * public Integer getId() { ... } + * public void setId(Integer id) { ... } + * public Address getAddress() { ... } + * public void setAddress(Address address) { ... } + * public Locker getLocker() { ... } + * public void setLocker(Locker locker) { ... } + * ... + * } + * + * &#064;Entity + * &#064;AssociationOverrides({ + * &#064;AssociationOverride( + * name="address", + * joinColumns=&#064;JoinColumn("ADDR_ID")), + * &#064;AttributeOverride( + * name="locker", + * joinColumns=&#064;JoinColumn("LCKR_ID")) + * }) + * public PartTimeEmployee { ... } + * </pre> + * + *@see AssociationOverride + * + * @since Java Persistence 1.0 */ -@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +@Target({TYPE, METHOD, FIELD}) +@Retention(RUNTIME) + public @interface AssociationOverrides { - /** - * Mapping overrides of relationship properties or fields - */ - AssociationOverride[] value(); + + /** + *(Required) The association override mappings that are to be + * applied to the relationship field or property . + */ + AssociationOverride[] value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/AttributeOverride.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AttributeOverride.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/AttributeOverride.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,34 +1,140 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.RetentionPolicy.*; -import static java.lang.annotation.ElementType.*; - - /** - * The AttributeOverride annotation is used to override the mapping of a Basic (whether explicit - * or default) property or field or Id property or field. + * Used to override the mapping of a <code>Basic</code> (whether + * explicit or default) property or field or <code>Id</code> property or + * field. * - * The AttributeOverride annotation may be applied to an entity that extends a mapped superclass - * or to an embedded field or property to override a basic mapping defined by the mapped superclass - * or embeddable class. If the AttributeOverride annotation is not specified, the column is mapped - * the same as in the original mapping. + * <p> May be applied to an entity that extends a mapped superclass or + * to an embedded field or property to override a basic mapping or id + * mapping defined by the mapped superclass or embeddable class (or + * embeddable class of one of its attributes). + + * <p> May be applied to an element collection containing instances of + * an embeddable class or to a map collection whose key and/or value + * is an embeddable class. When <code>AttributeOverride</code> is + * applied to a map, "<code>key.</code>" or "<code>value.</code>" must + * be used to prefix the name of the attribute that is being + * overridden in order to specify it as part of the map key or map + * value. * - * @author Emmanuel Bernard + * <p> To override mappings at multiple levels of embedding, a dot (".") + * notation form must be used in the <code>name</code> element to indicate an + * attribute within an embedded attribute. The value of each identifier + * used with the dot notation is the name of the respective embedded + * field or property. + * + * <p> If <code>AttributeOverride</code> is not specified, the column + * is mapped the same as in the original mapping. + * + * <pre> + * Example 1: + * + * &#064;MappedSuperclass + * public class Employee { + * &#064;Id protected Integer id; + * &#064;Version protected Integer version; + * protected String address; + * public Integer getId() { ... } + * public void setId(Integer id) { ... } + * public String getAddress() { ... } + * public void setAddress(String address) { ... } + * } + * + * &#064;Entity + * &#064;AttributeOverride(name="address", column=&#064;Column(name="ADDR")) + * public class PartTimeEmployee extends Employee { + * // address field mapping overridden to ADDR + * protected Float wage(); + * public Float getHourlyWage() { ... } + * public void setHourlyWage(Float wage) { ... } + * } + * + * + * Example 2: + * + * &#064;Embeddable public class Address { + * protected String street; + * protected String city; + * protected String state; + * &#064;Embedded protected Zipcode zipcode; + * } + * + * &#064;Embeddable public class Zipcode { + * protected String zip; + * protected String plusFour; + * } + * + * &#064;Entity public class Customer { + * &#064;Id protected Integer id; + * protected String name; + * &#064;AttributeOverrides({ + * &#064;AttributeOverride(name="state", + * column=&#064;Column(name="ADDR_STATE")), + * &#064;AttributeOverride(name="zipcode.zip", + * column=&#064;Column(name="ADDR_ZIP")) + * }) + * &#064;Embedded protected Address address; + * ... + * } + * + * + * Example 3: + * + * &#064;Entity public class PropertyRecord { + * &#064;EmbeddedId PropertyOwner owner; + * &#064;AttributeOverrides({ + * &#064;AttributeOverride(name="key.street", + * column=&#064;Column(name="STREET_NAME")), + * &#064;AttributeOverride(name="value.size", + * column=&#064;Column(name="SQUARE_FEET")), + * &#064;AttributeOverride(name="value.tax", + * column=&#064;Column(name="ASSESSMENT")) + * }) + * &#064;ElementCollection + * Map&#060;Address, PropertyInfo&#062; parcels; + * } + * + * &#064;Embeddable public class PropertyInfo { + * Integer parcelNumber; + * Integer size; + * BigDecimal tax; + * } + * + * </pre> + * + * @see Embedded + * @see Embeddable + * @see MappedSuperclass + * @see AssociationOverride + * + * @since Java Persistence 1.0 */ -@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +@Target({TYPE, METHOD, FIELD}) +@Retention(RUNTIME) + public @interface AttributeOverride { - /** - * The name of the property whose mapping is being overridden if property-based access is being - * used, or the name of the field if field-based access is used. - */ - String name(); - /** - * The column that is being mapped to the persistent attribute - */ - Column column(); + + /** + * (Required) The name of the property whose mapping is being + * overridden if property-based access is being used, or the + * name of the field if field-based access is used. + */ + String name(); + + /** + * (Required) The column that is being mapped to the persistent + * attribute. The mapping type will remain the same as is + * defined in the embeddable class or mapped superclass. + */ + Column column(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/AttributeOverrides.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AttributeOverrides.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/AttributeOverrides.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,23 +1,42 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.RetentionPolicy.*; -import static java.lang.annotation.ElementType.*; - - /** - * Is used to override mappings of multiple properties or fields + * Used to override mappings of multiple properties or fields. * - * @author Emmanuel Bernard + * <pre> + * + * Example: + * + * &#064;Embedded + * &#064;AttributeOverrides({ + * &#064;AttributeOverride(name="startDate", + * column=&#064;Column("EMP_START")), + * &#064;AttributeOverride(name="endDate", + * column=&#064;Column("EMP_END")) + * }) + * public EmploymentPeriod getEmploymentPeriod() { ... } + * + * </pre> + * + * + * @see AttributeOverride + * + * @since Java Persistence 1.0 */ -@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +@Target({TYPE, METHOD, FIELD}) +@Retention(RUNTIME) + public @interface AttributeOverrides { - /** - * One or more mapping override - */ - AttributeOverride[] value(); + + /** (Required) One or more field or property mapping overrides. */ + AttributeOverride[] value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/Basic.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Basic.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Basic.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,39 +1,68 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.FIELD; -import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; import static javax.persistence.FetchType.EAGER; /** - * The Basic annotation is the simplest type of mapping to a database column. The Basic - * annotation can be applied to a persistent property or instance variable of any of the - * following types: Java primitive types, wrappers of the primitive types, String, - * java.math.BigInteger, java.math.BigDecimal, java.util.Date, java.util.Calendar, - * java.sql.Date, java.sql.Time, java.sql.Timestamp, byte[], Byte[], char[], Character[], - * enums, and any other type that implements Serializable. + * The simplest type of mapping to a database column. The + * <code>Basic</code> annotation can be applied to a persistent + * property or instance variable of any of the following types: Java + * primitive types, wrappers of the primitive types, <code>String</code>, + * <code>java.math.BigInteger</code>, + * <code>java.math.BigDecimal</code>, + * <code>java.util.Date</code>, + * <code>java.util.Calendar</code>, + * <code>java.sql.Date</code>, + * <code>java.sql.Time</code>, + * <code>java.sql.Timestamp</code>, <code>byte[]</code>, <code>Byte[]</code>, + * <code>char[]</code>, <code>Character[]</code>, enums, and any other type that + * implements <code>java.io.Serializable</code>. * - * The use of the Basic annotation is optional for persistent fields and properties of these types. - - * @author Emmanuel Bernard + * <p> The use of the <code>Basic</code> annotation is optional for + * persistent fields and properties of these types. If the + * <code>Basic</code> annotation is not specified for such a field or + * property, the default values of the <code>Basic</code> annotation + * will apply. + * + * <pre> + * Example 1: + * + * &#064;Basic + * protected String name; + * + * Example 2: + * + * &#064;Basic(fetch=LAZY) + * protected String getName() { return name; } + * + * </pre> + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) public @interface Basic { - /** - * 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 - * that the value must be eagerly fetched. The LAZY strategy is a hint to the persistence - * provider runtime. If not specified, defaults to EAGER. - */ - FetchType fetch() default EAGER; - /** - * Defines whether the value of the field or property may be null. This is a hint and is - * disregarded for primitive types; it may be used in schema generation. If not specified, - * defaults to true. - */ - boolean optional() default true; + + /** + * (Optional) Defines whether the value of the field or property should + * be lazily loaded or must be eagerly fetched. The <code>EAGER</code> + * strategy is a requirement on the persistence provider runtime + * that the value must be eagerly fetched. The <code>LAZY</code> + * strategy is a hint to the persistence provider runtime. + * If not specified, defaults to <code>EAGER</code>. + */ + FetchType fetch() default EAGER; + + /** + * (Optional) Defines whether the value of the field or property may be null. + * This is a hint and is disregarded for primitive types; it may + * be used in schema generation. + * If not specified, defaults to <code>true</code>. + */ + boolean optional() default true; } Modified: jpa-api/trunk/src/main/java/javax/persistence/Cache.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Cache.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Cache.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -5,27 +5,36 @@ /** * Interface used to interact with the second-level cache. * If a cache is not in use, the methods of this interface have - * no effect, except for contains, which returns false. + * no effect, except for <code>contains</code>, which returns false. + * + * @since Java Persistence 2.0 */ public interface Cache { - /** - * Whether the cache contains data for the given entity. - */ - public boolean contains(Class cls, Object primaryKey); - /** - * Remove the data for the given entity from the cache. - */ - public void evict(Class cls, Object primaryKey); + /** + * Whether the cache contains data for the given entity. + * @param cls entity class + * @param primaryKey primary key + * @return boolean indicating whether the entity is in the cache + */ + public boolean contains(Class cls, Object primaryKey); - /** - * Remove the data for entities of the specified class (and its - * subclasses) from the cache. - */ - public void evict(Class cls); + /** + * Remove the data for the given entity from the cache. + * @param cls entity class + * @param primaryKey primary key + */ + public void evict(Class cls, Object primaryKey); - /** - * Clear the cache. - */ - public void evictAll(); + /** + * Remove the data for entities of the specified class (and its + * subclasses) from the cache. + * @param cls entity class + */ + public void evict(Class cls); + + /** + * Clear the cache. + */ + public void evictAll(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/CacheRetrieveMode.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/CacheRetrieveMode.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/CacheRetrieveMode.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,17 +2,26 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +/** + * Used as the value of the + * <code>javax.persistence.cache.retrieveMode</code> property to + * specify the behavior when data is retrieved by the + * <code>find</code> methods and by queries. + * + * @since Java Persistence 2.0 + */ public enum CacheRetrieveMode { - /** - * Read entity data from the cache: this is - * the default behavior. - */ - USE, + /** + * Read entity data from the cache: this is + * the default behavior. + */ + USE, - /** - * Bypass the cache: get data directly from - * the database. - */ - BYPASS + /** + * Bypass the cache: get data directly from + * the database. + */ + BYPASS } + Modified: jpa-api/trunk/src/main/java/javax/persistence/CacheStoreMode.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/CacheStoreMode.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/CacheStoreMode.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,25 +2,33 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +/** + * Used as the value of the + * <code>javax.persistence.cache.storeMode</code> property to specify + * the behavior when data is read from the database and when data is + * committed into the database. + * + * @since Java Persistence 2.0 + */ public enum CacheStoreMode { - /** - * Insert/update entity data into cache when read - * from database and when committed into database: - * this is the default behavior. Does not force refresh - * of already cached items when reading from database. - */ - USE, + /** + * Insert/update entity data into cache when read + * from database and when committed into database: + * this is the default behavior. Does not force refresh + * of already cached items when reading from database. + */ + USE, - /** - * Don't insert into cache. - */ - BYPASS, + /** + * Don't insert into cache. + */ + BYPASS, - /** - * Insert/update entity data into cache when read - * from database and when committed into database. - * Forces refresh of cache for items read from database. - */ - REFRESH + /** + * Insert/update entity data into cache when read + * from database and when committed into database. + * Forces refresh of cache for items read from database. + */ + REFRESH } Modified: jpa-api/trunk/src/main/java/javax/persistence/Cacheable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Cacheable.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Cacheable.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,15 +3,30 @@ package javax.persistence; import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Retention; -import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Target; /** - * @author Hardy Ferentschik + * Specifies whether an entity should be cached if caching is enabled + * when the value of the <code>persistence.xml</code> caching element + * is <code>ENABLE_SELECTIVE</code> or <code>DISABLE_SELECTIVE</code>. + * The value of the <code>Cacheable</code> annotation is inherited by + * subclasses; it can be overridden by specifying + * <code>Cacheable</code> on a subclass. + * + * <p> <code>Cacheable(false)</code> means that the entity and its state must + * not be cached by the provider. + * + * @since Java Persistence 2.0 */ -@Target({ TYPE }) +@Target( { TYPE }) @Retention(RUNTIME) public @interface Cacheable { - boolean value() default true; + + /** + * (Optional) Whether or not the entity should be cached. + */ + boolean value() default true; } + Deleted: jpa-api/trunk/src/main/java/javax/persistence/Caching.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Caching.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Caching.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,14 +0,0 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -/** - * @author Hardy Ferentschik - */ -public enum Caching { - ALL, - NONE, - ENABLE_SELECTIVE, - DISABLE_SELECTIVE, - UNSPECIFIED -} Modified: jpa-api/trunk/src/main/java/javax/persistence/CascadeType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/CascadeType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/CascadeType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,32 +1,37 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Defines the set of cascadable operations that are propagated to the associated entity. - * The value cascade=ALL is equivalent to cascade={PERSIST, MERGE, REMOVE, REFRESH}. + * Defines the set of cascadable operations that are propagated + * to the associated entity. + * The value <code>cascade=ALL</code> is equivalent to + * <code>cascade={PERSIST, MERGE, REMOVE, REFRESH, DETACH}</code>. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ public enum CascadeType { - /** - * Cascade all operations - */ - ALL, - /** - * Cascade persist operations - */ - PERSIST, - /** - * Cascade merge operations - */ - MERGE, - /** - * Cascade remove operations - */ - REMOVE, - /** - * Cascade refresh operations - */ - REFRESH + + /** Cascade all operations */ + ALL, + + /** Cascade persist operation */ + PERSIST, + + /** Cascade merge operation */ + MERGE, + + /** Cascade remove operation */ + REMOVE, + + /** Cascade refresh operation */ + REFRESH, + + /** + * Cascade detach operation + * + * @since Java Persistence 2.0 + * + */ + DETACH } Modified: jpa-api/trunk/src/main/java/javax/persistence/CollectionTable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/CollectionTable.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/CollectionTable.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,25 +2,133 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.FIELD; -import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * @author Hardy Ferentschik + * Specifies the table that is used for the mapping of + * collections of basic or embeddable types. Applied + * to the collection-valued field or property. + * + * <p>By default, the columns of the collection table that correspond + * to the embeddable class or basic type are derived from the + * attributes of the embeddable class or from the basic type according + * to the default values of the <code>Column</code> annotation. In the case + * of a basic type, the column name is derived from the name of the + * collection-valued field or property. In the case of an embeddable + * class, the column names are derived from the field or property + * names of the embeddable class. + * <ul> + * <li> To override the default properties of the column used for a + * basic type, the <code>Column</code> annotation is used on the + * collection-valued attribute in addition to the + * <code>ElementCollection</code> annotation. + * + * <li> To override these defaults for an embeddable class, the + * <code>AttributeOverride</code> and/or + * <code>AttributeOverrides</code> annotations can be used in + * addition to the <code>ElementCollection</code> annotation. If the + * embeddable class contains references to other entities, the default + * values for the columns corresponding to those references may be + * overridden by means of the <code>AssociationOverride</code> and/or + * <code>AssociationOverrides</code> annotations. + * </ul> + * + * <p> If the <code>CollectionTable</code> annotation is missing, the + * default values of the <code>CollectionTable</code> annotation + * elements apply. + * + * <pre> + * Example: + * + * &#064;Embeddable public class Address { + * protected String street; + * protected String city; + * protected String state; + * ... + * } + * + * &#064;Entity public class Person { + * &#064;Id protected String ssn; + * protected String name; + * protected Address home; + * ... + * &#064;ElementCollection // use default table (PERSON_NICKNAMES) + * &#064;Column(name="name", length=50) + * protected Set&#060;String&#062; nickNames = new HashSet(); + * ... + * } + * + * &#064;Entity public class WealthyPerson extends Person { + * &#064;ElementCollection + * &#064;CollectionTable(name="HOMES") // use default join column name + * &#064;AttributeOverrides({ + * &#064;AttributeOverride(name="street", + * column=&#064;Column(name="HOME_STREET")), + * &#064;AttributeOverride(name="city", + * column=&#064;Column(name="HOME_CITY")), + * &#064;AttributeOverride(name="state", + * column=&#064;Column(name="HOME_STATE")) + * }) + * protected Set&#060;Address&#062; vacationHomes = new HashSet(); + * ... + * } + * </pre> + * + * @see ElementCollection + * @see AttributeOverride + * @see AssociationOverride + * @see Column + * + * @since Java Persistence 2.0 */ -@Target({ METHOD, FIELD }) + +@Target( { METHOD, FIELD }) @Retention(RUNTIME) public @interface CollectionTable { - String name() default ""; - String catalog() default ""; + /** + * (Optional) The name of the collection table. If not specified, + * it defaults to the concatenation of the name of the containing + * entity and the name of the collection attribute, separated by + * an underscore. + */ + String name() default ""; - String schema() default ""; + /** + * (Optional) The catalog of the table. If not specified, the + * default catalog is used. + */ + String catalog() default ""; - JoinColumn[] joinColumns() default { }; + /** + * (Optional) The schema of the table. If not specified, the + * default schema for the user is used. + */ + String schema() default ""; - UniqueConstraint[] uniqueConstraints() default { }; + /** + * (Optional) The foreign key columns of the collection table + * which reference the primary table of the entity. The default + * only applies if a single join column is used. The default is + * the same as for <code>JoinColumn</code> (i.e., the + * concatenation of the following: the name of the entity; "_"; + * the name of the referenced primary key column.) However, if + * there is more than one join column, a <code>JoinColumn</code> + * annotation must be specified for each join column using the + * <code>JoinColumns</code> annotation. In this case, both the + * <code>name</code> and the <code>referencedColumnName</code> + * elements must be specified in each such + * <code>JoinColumn</code> annotation. + */ + JoinColumn[] joinColumns() default {}; + + /** + * (Optional) Unique constraints that are to be placed on the + * table. These are only used if table generation is in effect. + */ + UniqueConstraint[] uniqueConstraints() default {}; } Modified: jpa-api/trunk/src/main/java/javax/persistence/Column.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Column.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Column.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,65 +1,109 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * Is used to specify a mapped column for a persistent property or field. If no Column annotation is - * specified, the default values are applied. + * Is used to specify the mapped column for a persistent property or field. + * If no <code>Column</code> annotation is specified, the default values apply. * - * @author Emmanuel Bernard + * <blockquote><pre> + * Example 1: + * + * &#064;Column(name="DESC", nullable=false, length=512) + * public String getDescription() { return description; } + * + * Example 2: + * + * &#064;Column(name="DESC", + * columnDefinition="CLOB NOT NULL", + * table="EMP_DETAIL") + * &#064;Lob + * public String getDescription() { return description; } + * + * Example 3: + * + * &#064;Column(name="ORDER_COST", updatable=false, precision=12, scale=2) + * public BigDecimal getCost() { return cost; } + * + * </pre></blockquote> + * + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) public @interface Column { - /** - * The name of the column. Defaults to the property or field name - */ - String name() default ""; - /** - * Whether the property is a unique key. This is a shortcut for the UniqueConstraint - * annotation at the table level and is useful for when the unique key constraint is - * only a single field. This constraint applies in addition to any constraint entailed - * by primary key mapping and to constraints specified at the table level. - */ - boolean unique() default false; - /** - * Whether the database column is nullable - */ - boolean nullable() default true; - /** - * Whether the column is included in SQL INSERT statements generated by the persistence provider. - */ - boolean insertable() default true; - /** - * Whether the column is included in SQL UPDATE statements generated by the persistence provider. - */ - boolean updatable() default true; - /** - * The SQL fragment that is used when generating the DDL for the column. - * Defaults to the generated SQL to create a column of the inferred type. - */ - String columnDefinition() default ""; - /** - * The name of the table that contains the column. If absent the column is assumed to - * be in the primary table. - */ - String table() default ""; - /** - * The column length. (Applies only if a string-valued column is used.) - */ - int length() default 255; - /** - * The precision for a decimal (exact numeric) column. (Applies only if a decimal column is used.) - * Value must be set by developer if used when generating the DDL for the column. - */ - int precision() default 0; - /** - * The scale for a decimal (exact numeric) column. (Applies only if a decimal column is used.) - */ - int scale() default 0; + + /** + * (Optional) The name of the column. Defaults to + * the property or field name. + */ + String name() default ""; + + /** + * (Optional) Whether the column is a unique key. This is a + * shortcut for the <code>UniqueConstraint</code> annotation at the table + * level and is useful for when the unique key constraint + * corresponds to only a single column. This constraint applies + * in addition to any constraint entailed by primary key mapping and + * to constraints specified at the table level. + */ + boolean unique() default false; + + /** + * (Optional) Whether the database column is nullable. + */ + boolean nullable() default true; + + /** + * (Optional) Whether the column is included in SQL INSERT + * statements generated by the persistence provider. + */ + boolean insertable() default true; + + /** + * (Optional) Whether the column is included in SQL UPDATE + * statements generated by the persistence provider. + */ + boolean updatable() default true; + + /** + * (Optional) The SQL fragment that is used when + * generating the DDL for the column. + * <p> Defaults to the generated SQL to create a + * column of the inferred type. + */ + String columnDefinition() default ""; + + /** + * (Optional) The name of the table that contains the column. + * If absent the column is assumed to be in the primary table. + */ + String table() default ""; + + /** + * (Optional) The column length. (Applies only if a + * string-valued column is used.) + */ + int length() default 255; + + /** + * (Optional) The precision for a decimal (exact numeric) + * column. (Applies only if a decimal column is used.) + * Value must be set by developer if used when generating + * the DDL for the column. + */ + int precision() default 0; + + /** + * (Optional) The scale for a decimal (exact numeric) column. + * (Applies only if a decimal column is used.) + */ + int scale() default 0; } Modified: jpa-api/trunk/src/main/java/javax/persistence/ColumnResult.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ColumnResult.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/ColumnResult.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,22 +1,49 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import java.lang.annotation.Target; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; - -/** - * References name of a column in the SELECT clause of a SQL query - i.e., - * column alias, if applicable. Scalar result types can be included in the query - * result by specifying this annotation in the metadata. - * - * @author Emmanuel Bernard - */ -@Target({}) @Retention(RetentionPolicy.RUNTIME) -public @interface ColumnResult { - /** - * The name of a column in the SELECT clause of a SQL query - */ - String name(); +package javax.persistence; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +/** + * References name of a column in the SELECT clause of a SQL query - + * i.e., column alias, if applicable. Scalar result types can be + * included in the query result by specifying this annotation in + * the metadata. + * + * <pre> + * + * Example: + * Query q = em.createNativeQuery( + * "SELECT o.id AS order_id, " + + * "o.quantity AS order_quantity, " + + * "o.item AS order_item, " + + * "i.name AS item_name, " + + * "FROM Order o, Item i " + + * "WHERE (order_quantity > 25) AND (order_item = i.id)", + * "OrderResults"); + * + * &#064;SqlResultSetMapping(name="OrderResults", + * entities={ + * &#064;EntityResult(entityClass=com.acme.Order.class, fields={ + * &#064;FieldResult(name="id", column="order_id"), + * &#064;FieldResult(name="quantity", column="order_quantity"), + * &#064;FieldResult(name="item", column="order_item")})}, + * columns={ + * &#064;ColumnResult(name="item_name")} + * ) + * </pre> + * + * @see SqlResultSetMapping + * + * @since Java Persistence 1.0 + */ +@Target({}) +@Retention(RUNTIME) + +public @interface ColumnResult { + + /** (Required) The name of a column in the SELECT clause of a SQL query */ + String name(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorColumn.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorColumn.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,47 +1,71 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; - -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; import static javax.persistence.DiscriminatorType.STRING; /** - * Is used to define the discriminator column for the SINGLE_TABLE and JOINED inheritance - * mapping strategies. + * Specifies the discriminator column for the + * <code>SINGLE_TABLE</code> and + * <code>JOINED</code> {@link Inheritance} mapping strategies. * - * The strategy and the discriminator column are only specified in the root of an entity - * class hierarchy or subhierarchy in which a different inheritance strategy is applied + * <p> The strategy and the discriminator column are only + * specified in the root of an entity class hierarchy or + * subhierarchy in which a different inheritance strategy is applied * - * If the DiscriminatorColumn annotation is missing, and a discriminator column is required, - * the name of the discriminator column defaults to "DTYPE" and the discriminator type to - * DiscriminatorType.STRING. + * <p> If the <code>DiscriminatorColumn</code> annotation is missing, + * and a discriminator column is required, the name of the + * discriminator column defaults to <code>"DTYPE"</code> and the discriminator + * type to {@link DiscriminatorType#STRING DiscriminatorType.STRING}. * - * @author Emmanuel Bernard + * <pre> + * Example: + * + * &#064;Entity + * &#064;Table(name="CUST") + * &#064;Inheritance(strategy=SINGLE_TABLE) + * &#064;DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20) + * public class Customer { ... } + * + * &#064;Entity + * public class ValuedCustomer extends Customer { ... } + * </pre> + * + * @see DiscriminatorValue + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) + public @interface DiscriminatorColumn { - /** - * The name of column to be used for the discriminator. - */ - String name() default "DTYPE"; - /** - * The type of object/column to use as a class discriminator. - * Defaults to DiscriminatorType.STRING - */ - DiscriminatorType discriminatorType() default STRING; - /** - * The SQL fragment that is used when generating the DDL for the discriminator column. - * Defaults to the provider-generated SQL to create a column of the specified - * discriminator type. - */ - String columnDefinition() default ""; - /** - * The column length for String-based discriminator types. Ignored for other - * discriminator types. - */ - int length() default 31; + + /** + * (Optional) The name of column to be used for the discriminator. + */ + String name() default "DTYPE"; + + /** + * (Optional) The type of object/column to use as a class discriminator. + * Defaults to {@link DiscriminatorType#STRING DiscriminatorType.STRING}. + */ + DiscriminatorType discriminatorType() default STRING; + + /** + * (Optional) The SQL fragment that is used when generating the DDL + * for the discriminator column. + * <p> Defaults to the provider-generated SQL to create a column + * of the specified discriminator type. + */ + String columnDefinition() default ""; + + /** + * (Optional) The column length for String-based discriminator types. + * Ignored for other discriminator types. + */ + int length() default 31; } Modified: jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,23 +1,26 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Defines supported types of the discriminator column + * Defines supported types of the discriminator column. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ public enum DiscriminatorType { - /** - * String as the discriminator type - */ - STRING, - /** - * Single character as the discriminator type - */ - CHAR, - /** - * Integer as the discriminator type - */ - INTEGER + + /** + * String as the discriminator type. + */ + STRING, + + /** + * Single character as the discriminator type. + */ + CHAR, + + /** + * Integer as the discriminator type. + */ + INTEGER } Modified: jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorValue.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorValue.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorValue.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,34 +1,68 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; import java.lang.annotation.Target; import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.TYPE; /** - * Is used to specify the value of the discriminator column for entities of the given type. - * The DiscriminatorValue annotation can only be specified on a concrete entity class. - * If the DiscriminatorValue annotation is not specified and a discriminator column is used, - * a provider-specific function will be used to generate a value representing the entity type. - * If the DiscriminatorType is STRING, the discriminator value default is the entity name. + * Specifies the value of the discriminator column for + * entities of the given type. * - * The inheritance strategy and the discriminator column are only specified in the root - * of an entity class hierarchy or subhierarchy in which a different inheritance strategy - * is applied. The discriminator value, if not defaulted, should be specified for each entity - * class in the hierarchy. + * <p> The <code>DiscriminatorValue</code> + * annotation can only be specified on a concrete entity + * class. * - * @author Emmanuel Bernard + * <p> If the <code>DiscriminatorValue</code> annotation is not + * specified and a discriminator column is used, a provider-specific + * function will be used to generate a value representing the + * entity type. If the {@link DiscriminatorType} is <code> + * STRING</code>, the discriminator value + * default is the entity name. + * + * <p> The inheritance strategy and the discriminator column + * are only specified in the root of an entity class hierarchy + * or subhierarchy in which a different inheritance strategy is + * applied. The discriminator value, if not defaulted, should be + * specified for each entity class in the hierarchy. + * + * <pre> + * + * Example: + * + * &#064;Entity + * &#064;Table(name="CUST") + * &#064;Inheritance(strategy=SINGLE_TABLE) + * &#064;DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20) + * &#064;DiscriminatorValue("CUSTOMER") + * public class Customer { ... } + * + * &#064;Entity + * &#064;DiscriminatorValue("VCUSTOMER") + * public class ValuedCustomer extends Customer { ... } + * </pre> + * + * @see DiscriminatorColumn + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) + public @interface DiscriminatorValue { - /** - * The value that indicates that the row is an entity of the annotated entity type. - * - * If the DiscriminatorValue annotation is not specified and a discriminator column is used, - * a provider-specific function will be used to generate a value representing the entity type. - * If the DiscriminatorType is STRING, the discriminator value default is the entity name. - */ - String value(); + + /** + * (Optional) The value that indicates that the + * row is an entity of the annotated entity type. + * + * <p> If the <code>DiscriminatorValue</code> annotation is not + * specified and a discriminator column is used, a + * provider-specific function will be used to generate a value + * representing the entity type. If the <code>DiscriminatorType</code> is + * <code>STRING</code>, the discriminator value default is the + * entity name. + */ + String value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/ElementCollection.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ElementCollection.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/ElementCollection.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,20 +2,54 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.FIELD; -import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; import static javax.persistence.FetchType.LAZY; /** - * @author Hardy Ferentschik + * Defines a collection of instances of a basic type or embeddable + * class. + * Must be specified if the collection is to be mapped by + * means of a collection table. + * + * <pre> + * Example: + * + * &#064;Entity public class Person { + * &#064;Id protected String ssn; + * protected String name; + * ... + * &#064;ElementCollection + * protected Set&#060;String&#062; nickNames = new HashSet(); + * ... + * } + * </pre> + * + * @since Java Persistence 2.0 */ -@Target({ METHOD, FIELD }) +@Target( { METHOD, FIELD }) @Retention(RUNTIME) public @interface ElementCollection { - Class targetClass() default void.class; - FetchType fetch() default LAZY; + /** + * (Optional) The basic or embeddable class that is the element + * type of the collection. This element is optional only if the + * collection field or property is defined using Java generics, + * and must be specified otherwise. It defaults to the + * paramterized type of the collection when defined using + * generics. + */ + Class targetClass() default void.class; + + /** + * (Optional) Whether the collection should be lazily loaded or must be + * eagerly fetched. The EAGER strategy is a requirement on + * the persistence provider runtime that the collection elements + * must be eagerly fetched. The LAZY strategy is a hint to the + * persistence provider runtime. + */ + FetchType fetch() default LAZY; } Modified: jpa-api/trunk/src/main/java/javax/persistence/Embeddable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Embeddable.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Embeddable.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,23 +1,67 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.Documented; import static java.lang.annotation.ElementType.TYPE; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; - /** - * Defines a class whose instances are stored as an intrinsic part of an owning entity and share - * the identity of the entity. Each of the persistent properties or fields of the embedded object - * is mapped to the database table for the entity. Only Basic, Column, Lob, Temporal, and - * Enumerated mapping annotations may portably be used to map the persistent fields or properties - * of classes annotated as Embeddable. + * Defines a class whose instances are stored as an intrinsic + * part of an owning entity and share the identity of the entity. + * Each of the persistent properties or fields of the embedded + * object is mapped to the database table for the entity. * - * @author Emmanuel Bernard + * <p> Note that the {@link Transient} annotation may be used to + * designate the non-persistent state of an embeddable class. + * + * <pre> + * + * Example 1: + * + * &#064;Embeddable public class EmploymentPeriod { + * &#064;Temporal(DATE) java.util.Date startDate; + * &#064;Temporal(DATE) java.util.Date endDate; + * ... + * } + * + * Example 2: + * + * &#064;Embeddable public class PhoneNumber { + * protected String areaCode; + * protected String localNumber; + * &#064;ManyToOne PhoneServiceProvider provider; + * ... + * } + * + * &#064;Entity public class PhoneServiceProvider { + * &#064;Id protected String name; + * ... + * } + * + * Example 3: + * + * &#064;Embeddable public class Address { + * protected String street; + * protected String city; + * protected String state; + * &#064;Embedded protected Zipcode zipcode; + * } + * + * &#064;Embeddable public class Zipcode { + * protected String zip; + * protected String plusFour; + * } + + + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({ TYPE }) +@Documented +@Target({TYPE}) @Retention(RUNTIME) public @interface Embeddable { } Modified: jpa-api/trunk/src/main/java/javax/persistence/Embedded.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Embedded.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Embedded.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,18 +1,43 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * Defines a persistent field or property of an entity whose value is an instance of - * an embeddable class. The embeddable class must be annotated as Embeddable. + * Specifies a persistent field or property of an entity whose + * value is an instance of an embeddable class. The embeddable + * class must be annotated as {@link Embeddable}. * - * @author Emmanuel Bernard + * <p> The <code>AttributeOverride</code>, <code>AttributeOverrides</code>, + * <code>AssociationOverride</code>, and <code>AssociationOverrides</code> + * annotations may be used to override mappings declared or defaulted + * by the embeddable class. + * + * <pre> + * Example: + * + * &#064;Embedded + * &#064;AttributeOverrides({ + * &#064;AttributeOverride(name="startDate", column=&#064;Column("EMP_START")), + * &#064;AttributeOverride(name="endDate", column=&#064;Column("EMP_END")) + * }) + * public EmploymentPeriod getEmploymentPeriod() { ... } + * </pre> + * + * @see Embeddable + * @see AttributeOverride + * @see AttributeOverrides + * @see AssociationOverride + * @see AssociationOverrides + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) -public @interface Embedded {} +@Target({METHOD, FIELD}) +@Retention(RUNTIME) +public @interface Embedded { +} Modified: jpa-api/trunk/src/main/java/javax/persistence/EmbeddedId.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EmbeddedId.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EmbeddedId.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,19 +1,69 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Is applied to a persistent field or property of an entity class or mapped superclass to denote - * a composite primary key that is an embeddable class. The embeddable class must be annotated - * as Embeddable. - * - * @author Emmanuel Bernard + * Applied to a persistent field or property of an entity + * class or mapped superclass to denote a composite primary + * key that is an embeddable class. The embeddable class + * must be annotated as {@link Embeddable}. + * + * <p> There must be only one <code>EmbeddedId</code> annotation and + * no <code>Id</code> annotation when the <code>EmbeddedId</code> annotation is used. + * + * <p> The {@link AttributeOverride} annotation may be used to override + * the column mappings declared within the embeddable class. + * + * <p> The {@link MapsId} annotation may be used in conjunction + * with the <code>EmbeddedId</code> annotation to specify a derived + * primary key. + * + * <p> If the entity has a derived primary key, the + * <code>AttributeOverride</code> annotation may only be used to + * override those attributes of the embedded id that do not correspond + * to the relationship to the parent entity. + * + * <p> Relationship mappings defined within an embedded id class are not supported. + * + * <pre> + * Example 1: + * + * &#064;EmbeddedId + * protected EmployeePK empPK; + * + * + * Example 2: + * + * &#064;Embeddable + * public class DependentId { + * String name; + * EmployeeId empPK; // corresponds to primary key type of Employee + * } + * + * &#064;Entity + * public class Dependent { + * // default column name for "name" attribute is overridden + * &#064;AttributeOverride(name="name", &#064;Column(name="dep_name")) + * &#064;EmbeddedId DependentId id; + * ... + * &#064;MapsId("empPK") + * &#064;ManyToOne Employee emp; + * } + * </pre> + * + * @see Embeddable + * @see MapsId + * + * @since Java Persistence 1.0 */ -(a)Target({ElementType.METHOD, ElementType.FIELD}) -(a)Retention(RetentionPolicy.RUNTIME) -public @interface EmbeddedId {} +@Target({METHOD, FIELD}) +@Retention(RUNTIME) + +public @interface EmbeddedId { +} \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/Entity.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Entity.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Entity.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,23 +1,29 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.Documented; import static java.lang.annotation.ElementType.TYPE; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * Specifies that the class is an entity. This annotation is applied to the entity class. + * Specifies that the class is an entity. This annotation is applied to the + * entity class. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ -@Target(TYPE) @Retention(RUNTIME) +@Documented +@Target(TYPE) +@Retention(RUNTIME) public @interface Entity { + /** - * The name of an entity. Defaults to the unqualified name of the entity class. - * This name is used to refer to the entity in queries. The name must not be a - * reserved literal in the Java Persistence query language. + * (Optional) The entity name. Defaults to the unqualified + * name of the entity class. This name is used to refer to the + * entity in queries. The name must not be a reserved literal + * in the Java Persistence query language. */ String name() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityExistsException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityExistsException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityExistsException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,46 +1,62 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; - /** - * Thrown by the persistence provider when EntityManager.persist(Object) is called and the - * entity already exists. The current transaction, if one is active, will be marked for rollback. + * Thrown by the persistence provider when {@link EntityManager#persist(Object) + * EntityManager.persist(Object)} is called and the entity already exists. The + * current transaction, if one is active, will be marked for rollback. + * <p> + * If the entity already exists, the <code>EntityExistsException</code> may be thrown when + * the persist operation is invoked, or the <code>EntityExistsException</code> or another + * <code>PersistenceException</code> may be thrown at flush or commit time. + * <p> The current transaction, if one is active, will be marked for rollback. * - * @author Emmanuel Bernard + * @see javax.persistence.EntityManager#persist(Object) + * + * @since Java Persistence 1.0 */ public class EntityExistsException extends PersistenceException { - /** - * Constructs a new EntityExistsException exception with null as its detail message. - */ - public EntityExistsException() { - super(); - } - /** - * Constructs a new EntityExistsException exception with the specified cause. - * - * @param cause the cause - */ - public EntityExistsException(Throwable cause) { - super( cause ); - } + /** + * Constructs a new <code>EntityExistsException</code> exception with + * <code>null</code> as its detail message. + */ + public EntityExistsException() { + super(); + } - /** - * Constructs a new EntityExistsException exception with the specified detail message. - * - * @param message the detail message. - */ - public EntityExistsException(String message) { - super( message ); - } + /** + * Constructs a new <code>EntityExistsException</code> exception with the + * specified detail message. + * + * @param message + * the detail message. + */ + public EntityExistsException(String message) { + super(message); + } - /** - * Constructs a new EntityExistsException exception with the specified detail message and cause. - * - * @param message the detail message. - * @param cause the cause. - */ - public EntityExistsException(String message, Throwable cause) { - super( message, cause ); - } + /** + * Constructs a new <code>EntityExistsException</code> exception with the + * specified detail message and cause. + * + * @param message + * the detail message. + * @param cause + * the cause. + */ + public EntityExistsException(String message, Throwable cause) { + super(message, cause); + } + + /** + * Constructs a new <code>EntityExistsException</code> exception with the + * specified cause. + * + * @param cause + * the cause. + */ + public EntityExistsException(Throwable cause) { + super(cause); + } } Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityListeners.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityListeners.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityListeners.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,24 +1,23 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; - /** - * Specifies the callback listener classes to be used for an entity or mapped superclass. - * This annotation may be applied to an entity class or mapped superclass. + * Specifies the callback listener classes to be used for an + * entity or mapped superclass. This annotation may be applied + * to an entity class or mapped superclass. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.TYPE}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) public @interface EntityListeners { - /** - * The callback listener classes - */ - Class[] value(); + + /** The callback listener classes */ + Class[] value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,741 +3,708 @@ package javax.persistence; import java.util.Map; -import java.util.Set; -import javax.persistence.criteria.CriteriaQuery; -import javax.persistence.criteria.QueryBuilder; import javax.persistence.metamodel.Metamodel; +import javax.persistence.criteria.CriteriaBuilder; +import javax.persistence.criteria.CriteriaQuery; /** * Interface used to interact with the persistence context. + * + * <p> An <code>EntityManager</code> instance is associated with + * a persistence context. A persistence context is a set of entity + * instances in which for any persistent entity identity there is + * a unique entity instance. Within the persistence context, the + * entity instances and their lifecycle are managed. + * The <code>EntityManager</code> API is used + * to create and remove persistent entity instances, to find entities + * by their primary key, and to query over entities. + * + * <p> The set of entities that can be managed by a given + * <code>EntityManager</code> instance is defined by a persistence + * unit. A persistence unit defines the set of all classes that are + * related or grouped by the application, and which must be + * colocated in their mapping to a single database. + * + * @see Query + * @see TypedQuery + * @see CriteriaQuery + * @see PersistenceContext + * + * @since Java Persistence 1.0 */ public interface EntityManager { - /** - * Make an instance managed and persistent. - * - * @param entity - * - * @throws EntityExistsException if the entity already exists. - * (If the entity already exists, the EntityExistsException may - * be thrown when the persist operation is invoked, or the - * EntityExistsException or another PersistenceException may be - * thrown at flush or commit time.) - * @throws IllegalArgumentException if the instance is not an - * entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public void persist(Object entity); - /** - * Merge the state of the given entity into the - * current persistence context. - * - * @param entity - * - * @return the managed instance that the state was merged to - * - * @throws IllegalArgumentException if instance is not an - * entity or is a removed entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public <T> T merge(T entity); + /** + * Make an instance managed and persistent. + * @param entity entity instance + * @throws EntityExistsException if the entity already exists. + * (If the entity already exists, the <code>EntityExistsException</code> may + * be thrown when the persist operation is invoked, or the + * <code>EntityExistsException</code> or another <code>PersistenceException</code> may be + * thrown at flush or commit time.) + * @throws IllegalArgumentException if the instance is not an + * entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * <code>PersistenceContextType.TRANSACTION</code> and there is + * no transaction + */ + public void persist(Object entity); - /** - * Remove the entity instance. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public void remove(Object entity); + /** + * Merge the state of the given entity into the + * current persistence context. + * @param entity entity instance + * @return the managed instance that the state was merged to + * @throws IllegalArgumentException if instance is not an + * entity or is a removed entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * <code>PersistenceContextType.TRANSACTION</code> and there is + * no transaction + */ + public <T> T merge(T entity); - /** - * Find by primary key. - * Search for an entity of the specified class and primary key. - * If the entity instance is contained in the persistence context - * it is returned from there. - * - * @param entityClass - * @param primaryKey - * - * @return the found entity instance or null - * if the entity does not exist - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * is not a valid type for that entity�s primary key or - * is null - */ - public <T> T find(Class<T> entityClass, Object primaryKey); + /** + * Remove the entity instance. + * @param entity entity instance + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * <code>PersistenceContextType.TRANSACTION</code> and there is + * no transaction + */ + public void remove(Object entity); - /** - * Find by primary key, using the specified properties. - * Search for an entity of the specified class and primary key. - * If the entity instance is contained in the persistence context - * it is returned from there. - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * - * @param entityClass - * @param primaryKey - * @param properties standard and vendor-specific properties - * - * @return the found entity instance or null - * if the entity does not exist - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * is not a valid type for that entity�s primary key or - * is null - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - Map<String, Object> properties); + /** + * Find by primary key. + * Search for an entity of the specified class and primary key. + * If the entity instance is contained in the persistence context, + * it is returned from there. + * @param entityClass entity class + * @param primaryKey primary key + * @return the found entity instance or null if the entity does + * not exist + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * is not a valid type for that entity’s primary key or + * is null + */ + public <T> T find(Class<T> entityClass, Object primaryKey); - /** - * Find by primary key and lock. - * Search for an entity of the specified class and primary key - * and lock it with respect to the specified lock type. - * If the entity instance is contained in the persistence context - * it is returned from there, and the effect of this method is - * the same as if the lock method had been called on the entity. - * If the entity is found within the persistence context and the - * lock mode type is pessimistic and the entity has a version - * attribute, the persistence provider must perform optimistic - * version checks when obtaining the database lock. If these - * checks fail, the OptimisticLockException will be thrown. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * - * @param entityClass - * @param primaryKey - * @param lockMode - * - * @return the found entity instance or null if the entity does - * not exist - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity's primary key or - * is null - * @throws TransactionRequiredException if there is no - * transaction and a lock mode other than NONE is set - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - LockModeType lockMode); + /** + * Find by primary key, using the specified properties. + * Search for an entity of the specified class and primary key. + * If the entity instance is contained in the persistence + * context, it is returned from there. + * If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * @param entityClass entity class + * @param primaryKey primary key + * @param properties standard and vendor-specific properties + * and hints + * @return the found entity instance or null if the entity does + * not exist + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * is not a valid type for that entity’s primary key or + * is null + * @since Java Persistence 2.0 + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + Map<String, Object> properties); - /** - * Find by primary key and lock, using the specified properties. - * Search for an entity of the specified class and primary key - * and lock it with respect to the specified lock type. - * If the entity instance is contained in the persistence context - * it is returned from there. If the entity is found - * within the persistence context and the lock mode type - * is pessimistic and the entity has a version attribute, the - * persistence provider must perform optimistic version checks - * when obtaining the database lock. If these checks fail, - * the OptimisticLockException will be thrown. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * - * @param entityClass - * @param primaryKey - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @return the found entity instance or null if the entity does - * not exist - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity's primary key or - * is null - * @throws TransactionRequiredException if there is no - * transaction and a lock mode other than NONE is set - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - LockModeType lockMode, - Map<String, Object> properties); + /** + * Find by primary key and lock. + * Search for an entity of the specified class and primary key + * and lock it with respect to the specified lock type. + * If the entity instance is contained in the persistence context, + * it is returned from there, and the effect of this method is + * the same as if the lock method had been called on the entity. + * <p> If the entity is found within the persistence context and the + * lock mode type is pessimistic and the entity has a version + * attribute, the persistence provider must perform optimistic + * version checks when obtaining the database lock. If these + * checks fail, the <code>OptimisticLockException</code> will be thrown. + * <p>If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * <ul> + * <li> the <code>PessimisticLockException</code> will be thrown if the database + * locking failure causes transaction-level rollback + * <li> the <code>LockTimeoutException</code> will be thrown if the database + * locking failure causes only statement-level rollback + * </ul> + * @param entityClass entity class + * @param primaryKey primary key + * @param lockMode lock mode + * @return the found entity instance or null if the entity does + * not exist + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * not a valid type for that entity's primary key or + * is null + * @throws TransactionRequiredException if there is no + * transaction and a lock mode other than NONE is + * specified + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + * @since Java Persistence 2.0 + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + LockModeType lockMode); - /** - * Get an instance, whose state may be lazily fetched. - * If the requested instance does not exist in the database, - * the EntityNotFoundException is thrown when the instance - * state is first accessed. (The persistence provider runtime is - * permitted to throw the EntityNotFoundException when - * getReference is called.) - * The application should not expect that the instance state will - * be available upon detachment, unless it was accessed by the - * application while the entity manager was open. - * - * @param entityClass - * @param primaryKey - * - * @return the found entity instance - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity�s primary key or - * is null - * @throws EntityNotFoundException if the entity state - * cannot be accessed - */ - public <T> T getReference(Class<T> entityClass, - Object primaryKey); + /** + * Find by primary key and lock, using the specified properties. + * Search for an entity of the specified class and primary key + * and lock it with respect to the specified lock type. + * If the entity instance is contained in the persistence context, + * it is returned from there. + * <p> If the entity is found + * within the persistence context and the lock mode type + * is pessimistic and the entity has a version attribute, the + * persistence provider must perform optimistic version checks + * when obtaining the database lock. If these checks fail, + * the <code>OptimisticLockException</code> will be thrown. + * <p>If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * <ul> + * <li> the <code>PessimisticLockException</code> will be thrown if the database + * locking failure causes transaction-level rollback + * <li> the <code>LockTimeoutException</code> will be thrown if the database + * locking failure causes only statement-level rollback + * </ul> + * <p>If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * <p>Portable applications should not rely on the standard timeout + * hint. Depending on the database in use and the locking + * mechanisms used by the provider, the hint may or may not + * be observed. + * @param entityClass entity class + * @param primaryKey primary key + * @param lockMode lock mode + * @param properties standard and vendor-specific properties + * and hints + * @return the found entity instance or null if the entity does + * not exist + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * not a valid type for that entity's primary key or + * is null + * @throws TransactionRequiredException if there is no + * transaction and a lock mode other than <code>NONE</code> is + * specified + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + * @since Java Persistence 2.0 + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + LockModeType lockMode, + Map<String, Object> properties); - /** - * Synchronize the persistence context to the - * underlying database. - * - * @throws TransactionRequiredException if there is - * no transaction - * @throws PersistenceException if the flush fails - */ - public void flush(); + /** + * Get an instance, whose state may be lazily fetched. + * If the requested instance does not exist in the database, + * the <code>EntityNotFoundException</code> is thrown when the instance + * state is first accessed. (The persistence provider runtime is + * permitted to throw the <code>EntityNotFoundException</code> when + * <code>getReference</code> is called.) + * The application should not expect that the instance state will + * be available upon detachment, unless it was accessed by the + * application while the entity manager was open. + * @param entityClass entity class + * @param primaryKey primary key + * @return the found entity instance + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * not a valid type for that entity’s primary key or + * is null + * @throws EntityNotFoundException if the entity state + * cannot be accessed + */ + public <T> T getReference(Class<T> entityClass, + Object primaryKey); - /** - * Set the flush mode that applies to all objects contained - * in the persistence context. - * - * @param flushMode - */ - public void setFlushMode(FlushModeType flushMode); + /** + * Synchronize the persistence context to the + * underlying database. + * @throws TransactionRequiredException if there is + * no transaction + * @throws PersistenceException if the flush fails + */ + public void flush(); - /** - * Get the flush mode that applies to all objects contained - * in the persistence context. - * - * @return flushMode - */ - public FlushModeType getFlushMode(); + /** + * Set the flush mode that applies to all objects contained + * in the persistence context. + * @param flushMode flush mode + */ + public void setFlushMode(FlushModeType flushMode); - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type. - * If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also perform optimistic version checks when obtaining the - * database lock. If these checks fail, the - * OptimisticLockException will be thrown. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * - * @param entity - * @param lockMode - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void lock(Object entity, LockModeType lockMode); + /** + * Get the flush mode that applies to all objects contained + * in the persistence context. + * @return flushMode + */ + public FlushModeType getFlushMode(); - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type and with specified - * properties. - * If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also perform optimistic version checks when obtaining the - * database lock. If these checks fail, the - * OptimisticLockException will be thrown. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * - * @param entity - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void lock(Object entity, LockModeType lockMode, - Map<String, Object> properties); + /** + * Lock an entity instance that is contained in the persistence + * context with the specified lock mode type. + * <p>If a pessimistic lock mode type is specified and the entity + * contains a version attribute, the persistence provider must + * also perform optimistic version checks when obtaining the + * database lock. If these checks fail, the + * <code>OptimisticLockException</code> will be thrown. + * <p>If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * <ul> + * <li> the <code>PessimisticLockException</code> will be thrown if the database + * locking failure causes transaction-level rollback + * <li> the <code>LockTimeoutException</code> will be thrown if the database + * locking failure causes only statement-level rollback + * </ul> + * @param entity entity instance + * @param lockMode lock mode + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity does not exist + * in the database when pessimistic locking is + * performed + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void lock(Object entity, LockModeType lockMode); - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - * @throws EntityNotFoundException if the entity no longer - * exists in the database - */ - public void refresh(Object entity); + /** + * Lock an entity instance that is contained in the persistence + * context with the specified lock mode type and with specified + * properties. + * <p>If a pessimistic lock mode type is specified and the entity + * contains a version attribute, the persistence provider must + * also perform optimistic version checks when obtaining the + * database lock. If these checks fail, the + * <code>OptimisticLockException</code> will be thrown. + * <p>If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * <ul> + * <li> the <code>PessimisticLockException</code> will be thrown if the database + * locking failure causes transaction-level rollback + * <li> the <code>LockTimeoutException</code> will be thrown if the database + * locking failure causes only statement-level rollback + * </ul> + * <p>If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * <p>Portable applications should not rely on the standard timeout + * hint. Depending on the database in use and the locking + * mechanisms used by the provider, the hint may or may not + * be observed. + * @param entity entity instance + * @param lockMode lock mode + * @param properties standard and vendor-specific properties + * and hints + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity does not exist + * in the database when pessimistic locking is + * performed + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + * @since Java Persistence 2.0 + */ + public void lock(Object entity, LockModeType lockMode, + Map<String, Object> properties); - /** - * Refresh the state of the instance from the database, using - * the specified properties, and overwriting changes made to - * the entity, if any. - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * - * @param entity - * @param properties standard and vendor-specific properties - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - * @throws EntityNotFoundException if the entity no longer - * exists in the database - */ - public void refresh(Object entity, - Map<String, Object> properties); + /** + * Refresh the state of the instance from the database, + * overwriting changes made to the entity, if any. + * @param entity entity instance + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * <code>PersistenceContextType.TRANSACTION</code> and there is + * no transaction + * @throws EntityNotFoundException if the entity no longer + * exists in the database + */ + public void refresh(Object entity); - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any, and - * lock it with respect to given lock mode type. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the - * database locking failure causes only statement-level - * rollback. - * - * @param entity - * @param lockMode - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity no longer exists - * in the database - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void refresh(Object entity, LockModeType lockMode); + /** + * Refresh the state of the instance from the database, using + * the specified properties, and overwriting changes made to + * the entity, if any. + * <p> If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * @param entity entity instance + * @param properties standard and vendor-specific properties + * and hints + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * <code>PersistenceContextType.TRANSACTION</code> and there is + * no transaction + * @throws EntityNotFoundException if the entity no longer + * exists in the database + * @since Java Persistence 2.0 + */ + public void refresh(Object entity, + Map<String, Object> properties); - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any, and - * lock it with respect to given lock mode type and with - * specified properties. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * - * @param entity - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity no longer exists - * in the database - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void refresh(Object entity, LockModeType lockMode, - Map<String, Object> properties); + /** + * Refresh the state of the instance from the database, + * overwriting changes made to the entity, if any, and + * lock it with respect to given lock mode type. + * <p>If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * <ul> + * <li> the <code>PessimisticLockException</code> will be thrown if the database + * locking failure causes transaction-level rollback + * <li> the <code>LockTimeoutException</code> will be thrown if the + * database locking failure causes only statement-level + * rollback. + * </ul> + * @param entity entity instance + * @param lockMode lock mode + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if there is no + * transaction and if invoked on a container-managed + * <code>EntityManager</code> instance with + * <code>PersistenceContextType.TRANSACTION</code> or with a lock mode + * other than <code>NONE</code> + * @throws EntityNotFoundException if the entity no longer exists + * in the database + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + * @since Java Persistence 2.0 + */ + public void refresh(Object entity, LockModeType lockMode); - /** - * Clear the persistence context, causing all managed - * entities to become detached. Changes made to entities that - * have not been flushed to the database will not be - * persisted. - */ - public void clear(); + /** + * Refresh the state of the instance from the database, + * overwriting changes made to the entity, if any, and + * lock it with respect to given lock mode type and with + * specified properties. + * <p>If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * <ul> + * <li> the <code>PessimisticLockException</code> will be thrown if the database + * locking failure causes transaction-level rollback + * <li> the <code>LockTimeoutException</code> will be thrown if the database + * locking failure causes only statement-level rollback + * </ul> + * <p>If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * <p>Portable applications should not rely on the standard timeout + * hint. Depending on the database in use and the locking + * mechanisms used by the provider, the hint may or may not + * be observed. + * @param entity entity instance + * @param lockMode lock mode + * @param properties standard and vendor-specific properties + * and hints + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if there is no + * transaction and if invoked on a container-managed + * <code>EntityManager</code> instance with + * <code>PersistenceContextType.TRANSACTION</code> or with a lock mode + * other than <code>NONE</code> + * @throws EntityNotFoundException if the entity no longer exists + * in the database + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + * @since Java Persistence 2.0 + */ + public void refresh(Object entity, LockModeType lockMode, + Map<String, Object> properties); - /** - * Remove the given entity from the persistence context, causing - * a managed entity to become detached. Unflushed changes made - * to the entity if any (including removal of the entity), - * will not be synchronized to the database. Entities which - * previously referenced the detached entity will continue to - * reference it. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not an - * entity - */ - public void detach(Object entity); + /** + * Clear the persistence context, causing all managed + * entities to become detached. Changes made to entities that + * have not been flushed to the database will not be + * persisted. + */ + public void clear(); - /** - * Check if the instance is a managed entity instance belonging - * to the current persistence context. - * - * @param entity - * - * @return - * - * @throws IllegalArgumentException if not an entity - */ - public boolean contains(Object entity); + /** + * Remove the given entity from the persistence context, causing + * a managed entity to become detached. Unflushed changes made + * to the entity if any (including removal of the entity), + * will not be synchronized to the database. Entities which + * previously referenced the detached entity will continue to + * reference it. + * @param entity entity instance + * @throws IllegalArgumentException if the instance is not an + * entity + * @since Java Persistence 2.0 + */ + public void detach(Object entity); - /** - * Get the current lock mode for the entity instance. - * - * @param entity - * - * @return lock mode - * - * @throws TransactionRequiredException if there is no - * transaction - * @throws IllegalArgumentException if the instance is not a - * managed entity and a transaction is active - */ - public LockModeType getLockMode(Object entity); + /** + * Check if the instance is a managed entity instance belonging + * to the current persistence context. + * @param entity entity instance + * @return boolean indicating if entity is in persistence context + * @throws IllegalArgumentException if not an entity + */ + public boolean contains(Object entity); - /** - * Set an entity manager property. - * If a vendor-specific property is not recognized, it is - * silently ignored. - * - * @param propertyName - * @param value - * - * @throws IllegalArgumentException if the second argument is not - * valid for the implementation - */ - public void setProperty(String propertyName, Object value); + /** + * Get the current lock mode for the entity instance. + * @param entity entity instance + * @return lock mode + * @throws TransactionRequiredException if there is no + * transaction + * @throws IllegalArgumentException if the instance is not a + * managed entity and a transaction is active + * @since Java Persistence 2.0 + */ + public LockModeType getLockMode(Object entity); - /** - * Get the properties and associated values that are in effect - * for the entity manager. Changing the contents of the map does - * not change the configuration in effect. - */ - public Map<String, Object> getProperties(); + /** + * Set an entity manager property or hint. + * If a vendor-specific property or hint is not recognized, it is + * silently ignored. + * @param propertyName name of property or hint + * @param value value for property or hint + * @throws IllegalArgumentException if the second argument is + * not valid for the implementation + * @since Java Persistence 2.0 + */ + public void setProperty(String propertyName, Object value); - /** - * Get the names of the properties that are supported for use - * with the entity manager. - * These correspond to properties and hints that may be passed - * to the methods of the EntityManager interface that take a - * properties argument or used with the PersistenceContext - * annotation. These properties include all standard entity - * manager hints and properties as well as vendor-specific ones - * supported by the provider. These properties may or may not - * currently be in effect. - * - * @return property names - */ - public Set<String> getSupportedProperties(); + /** + * Get the properties and hints and associated values that are in effect + * for the entity manager. Changing the contents of the map does + * not change the configuration in effect. + * @return map of properties and hints in effect for entity manager + * @since Java Persistence 2.0 + */ + public Map<String, Object> getProperties(); - /** - * Create an instance of Query for executing a - * Java Persistence query language statement. - * - * @param qlString a Java Persistence query string - * - * @return the new query instance - * - * @throws IllegalArgumentException if the query string is found - * to be invalid - */ - public Query createQuery(String qlString); + /** + * Create an instance of <code>Query</code> for executing a + * Java Persistence query language statement. + * @param qlString a Java Persistence query string + * @return the new query instance + * @throws IllegalArgumentException if the query string is + * found to be invalid + */ + public Query createQuery(String qlString); - /** - * Create an instance of TypedQuery for executing a - * criteria query. - * @param criteriaQuery a criteria query object - * @return the new query instance - * @throws IllegalArgumentException if the query definition is - * found to be invalid - */ - public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery); + /** + * Create an instance of <code>TypedQuery</code> for executing a + * criteria query. + * @param criteriaQuery a criteria query object + * @return the new query instance + * @throws IllegalArgumentException if the criteria query is + * found to be invalid + * @since Java Persistence 2.0 + */ + public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery); - /** - * Create an instance of TypedQuery for executing a - * Java Persistence query language statement. - * The select list of the query must contain only a single - * item, which must be assignable to the type specified by - * the resultClass argument. - * @param qlString a Java Persistence query string - * @param resultClass the type of the query result - * @return the new query instance - * @throws IllegalArgumentException if the query string is found - * to be invalid or if the query result is found to - * not be assignable to the specified type. - */ - public <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass); + /** + * Create an instance of <code>TypedQuery</code> for executing a + * Java Persistence query language statement. + * The select list of the query must contain only a single + * item, which must be assignable to the type specified by + * the <code>resultClass</code> argument. + * @param qlString a Java Persistence query string + * @param resultClass the type of the query result + * @return the new query instance + * @throws IllegalArgumentException if the query string is found + * to be invalid or if the query result is found to + * not be assignable to the specified type + * @since Java Persistence 2.0 + */ + public <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass); - /** - * Create an instance of Query for executing a - * named query (in the Java Persistence query language - * or in native SQL). - * - * @param name the name of a query defined in metadata - * - * @return the new query instance - * - * @throws IllegalArgumentException if a query has not been - * defined with the given name or if the query string is - * found to be invalid - */ - public Query createNamedQuery(String name); + /** + * Create an instance of <code>Query</code> for executing a named query + * (in the Java Persistence query language or in native SQL). + * @param name the name of a query defined in metadata + * @return the new query instance + * @throws IllegalArgumentException if a query has not been + * defined with the given name or if the query string is + * found to be invalid + */ + public Query createNamedQuery(String name); - /** - * Create an instance of TypedQuery for executing a - * named query (in the Java Persistence query language - * or in native SQL). - * The select list of the query must contain only a single - * item, which must be assignable to the type specified by - * the resultClass argument. - * @param name the name of a query defined in metadata - * @param resultClass the type of the query result - * @return the new query instance - * @throws IllegalArgumentException if a query has not been - * defined with the given name or if the query string is - * found to be invalid or if the query result is found to - * not be assignable to the specified type. - */ - public <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass); + /** + * Create an instance of <code>TypedQuery</code> for executing a + * Java Persistence query language named query. + * The select list of the query must contain only a single + * item, which must be assignable to the type specified by + * the <code>resultClass</code> argument. + * @param name the name of a query defined in metadata + * @param resultClass the type of the query result + * @return the new query instance + * @throws IllegalArgumentException if a query has not been + * defined with the given name or if the query string is + * found to be invalid or if the query result is found to + * not be assignable to the specified type + * @since Java Persistence 2.0 + */ + public <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass); - /** - * Create an instance of Query for executing - * a native SQL statement, e.g., for update or delete. - * - * @param sqlString a native SQL query string - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString); + /** + * Create an instance of <code>Query</code> for executing + * a native SQL statement, e.g., for update or delete. + * @param sqlString a native SQL query string + * @return the new query instance + */ + public Query createNativeQuery(String sqlString); - /** - * Create an instance of Query for executing - * a native SQL query. - * - * @param sqlString a native SQL query string - * @param resultClass the class of the resulting instance(s) - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString, - Class resultClass); + /** + * Create an instance of <code>Query</code> for executing + * a native SQL query. + * @param sqlString a native SQL query string + * @param resultClass the class of the resulting instance(s) + * @return the new query instance + */ + public Query createNativeQuery(String sqlString, Class resultClass); - /** - * Create an instance of Query for executing - * a native SQL query. - * - * @param sqlString a native SQL query string - * @param resultSetMapping the name of the result set mapping - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString, - String resultSetMapping); + /** + * Create an instance of <code>Query</code> for executing + * a native SQL query. + * @param sqlString a native SQL query string + * @param resultSetMapping the name of the result set mapping + * @return the new query instance + */ + public Query createNativeQuery(String sqlString, String resultSetMapping); - /** - * Indicate to the EntityManager that a JTA transaction is - * active. This method should be called on a JTA application - * managed EntityManager that was created outside the scope - * of the active transaction to associate it with the current - * JTA transaction. - * - * @throws TransactionRequiredException if there is - * no transaction. - */ - public void joinTransaction(); + /** + * Indicate to the entity manager that a JTA transaction is + * active. This method should be called on a JTA application + * managed entity manager that was created outside the scope + * of the active transaction to associate it with the current + * JTA transaction. + * @throws TransactionRequiredException if there is + * no transaction + */ + public void joinTransaction(); - /** - * Return an object of the specified type to allow access to the - * provider-specific API. If the provider's EntityManager - * implementation does not support the specified class, the - * PersistenceException is thrown. - * - * @param cls the class of the object to be returned. This is - * normally either the underlying EntityManager implementation - * class or an interface that it implements. - * - * @return an instance of the specified class - * - * @throws PersistenceException if the provider does not - * support the call. - */ - public <T> T unwrap(Class<T> cls); + /** + * Return an object of the specified type to allow access to the + * provider-specific API. If the provider's <code>EntityManager</code> + * implementation does not support the specified class, the + * <code>PersistenceException</code> is thrown. + * @param cls the class of the object to be returned. This is + * normally either the underlying <code>EntityManager</code> implementation + * class or an interface that it implements. + * @return an instance of the specified class + * @throws PersistenceException if the provider does not + * support the call + * @since Java Persistence 2.0 + */ + public <T> T unwrap(Class<T> cls); - /** - * Return the underlying provider object for the EntityManager, - * if available. The result of this method is implementation - * specific. The unwrap method is to be preferred for new - * applications. - */ - public Object getDelegate(); + /** + * Return the underlying provider object for the <code>EntityManager</code>, + * if available. The result of this method is implementation + * specific. The <code>unwrap</code> method is to be preferred for new + * applications. + * @return underlying provider object for EntityManager + */ + public Object getDelegate(); - /** - * Return the underlying provider object for the EntityManager, - * if available. The result of this method is implementation - * specific. The unwrap method is to be preferred for new - * applications. - * / - * public Object getDelegate(); - * /** - * Close an application-managed EntityManager. - * After the close method has been invoked, all methods - * on the EntityManager instance and any Query objects obtained - * from it will throw the IllegalStateException except - * for getProperties, getSupportedProperties, getTransaction, - * and isOpen (which will return false). - * If this method is called when the EntityManager is - * associated with an active transaction, the persistence - * context remains managed until the transaction completes. - * - * @throws IllegalStateException if the EntityManager - * is container-managed. - */ - public void close(); + /** + * Close an application-managed entity manager. + * After the close method has been invoked, all methods + * on the <code>EntityManager</code> instance and any + * <code>Query</code> and <code>TypedQuery</code> + * objects obtained from it will throw the <code>IllegalStateException</code> + * except for <code>getProperties</code>, + * <code>getTransaction</code>, and <code>isOpen</code> (which will return false). + * If this method is called when the entity manager is + * associated with an active transaction, the persistence + * context remains managed until the transaction completes. + * @throws IllegalStateException if the entity manager + * is container-managed + */ + public void close(); - /** - * Determine whether the EntityManager is open. - * - * @return true until the EntityManager has been closed. - */ - public boolean isOpen(); + /** + * Determine whether the entity manager is open. + * @return true until the entity manager has been closed + */ + public boolean isOpen(); - /** - * Return the resource-level transaction object. - * The EntityTransaction instance may be used serially to - * begin and commit multiple transactions. - * - * @return EntityTransaction instance - * - * @throws IllegalStateException if invoked on a JTA - * EntityManager. - */ - public EntityTransaction getTransaction(); + /** + * Return the resource-level <code>EntityTransaction</code> object. + * The <code>EntityTransaction</code> instance may be used serially to + * begin and commit multiple transactions. + * @return EntityTransaction instance + * @throws IllegalStateException if invoked on a JTA + * entity manager + */ + public EntityTransaction getTransaction(); - /** - * Return the entity manager factory for the entity manager. - * - * @return EntityManagerFactory instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public EntityManagerFactory getEntityManagerFactory(); + /** + * Return the entity manager factory for the entity manager. + * @return EntityManagerFactory instance + * @throws IllegalStateException if the entity manager has + * been closed + * @since Java Persistence 2.0 + */ + public EntityManagerFactory getEntityManagerFactory(); - /** - * Return an instance of QueryBuilder for the creation of - * Criteria API Query objects. - * - * @return QueryBuilder instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public QueryBuilder getQueryBuilder(); + /** + * Return an instance of <code>CriteriaBuilder</code> for the creation of + * <code>CriteriaQuery</code> objects. + * @return CriteriaBuilder instance + * @throws IllegalStateException if the entity manager has + * been closed + * @since Java Persistence 2.0 + */ + public CriteriaBuilder getCriteriaBuilder(); - /** - * Return an instance of Metamodel interface for access to the - * metamodel of the persistence unit. - * - * @return Metamodel instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public Metamodel getMetamodel(); -} + /** + * Return an instance of <code>Metamodel</code> interface for access to the + * metamodel of the persistence unit. + * @return Metamodel instance + * @throws IllegalStateException if the entity manager has + * been closed + * @since Java Persistence 2.0 + */ + public Metamodel getMetamodel(); +} \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,117 +3,119 @@ package javax.persistence; import java.util.Map; -import java.util.Set; -import javax.persistence.criteria.QueryBuilder; import javax.persistence.metamodel.Metamodel; +import javax.persistence.criteria.CriteriaBuilder; /** - * Interface used to interact with the entity manager factory * for the persistence unit. + * Interface used to interact with the entity manager factory + * for the persistence unit. + * + * <p>When the application has finished using the entity manager + * factory, and/or at application shutdown, the application should + * close the entity manager factory. Once an + * <code>EntityManagerFactory</code> has been closed, all its entity managers + * are considered to be in the closed state. + * + * @since Java Persistence 1.0 */ public interface EntityManagerFactory { - /** - * Create a new EntityManager. - * This method returns a new EntityManager instance each time - * it is invoked. - * The isOpen method will return true on the returned instance. - * - * @throws IllegalStateException if the entity manager factory - * has been closed. - */ - public EntityManager createEntityManager(); - /** - * Create a new EntityManager with the specified Map of - * properties. - * This method returns a new EntityManager instance each time - * it is invoked. - * The isOpen method will return true on the returned instance. - * - * @throws IllegalStateException if the entity manager factory - * has been closed. - */ - public EntityManager createEntityManager(Map map); + /** + * Create a new application-managed <code>EntityManager</code>. + * This method returns a new <code>EntityManager</code> instance each time + * it is invoked. + * The <code>isOpen</code> method will return true on the returned instance. + * @return entity manager instance + * @throws IllegalStateException if the entity manager factory + * has been closed + */ + public EntityManager createEntityManager(); - /** - * Return an instance of QueryBuilder for the creation of - * Criteria API objects. - * - * @return QueryBuilder instance - * - * @throws IllegalStateException if the entity manager factory - * has been closed. - */ - public QueryBuilder getQueryBuilder(); + /** + * Create a new application-managed <code>EntityManager</code> with the + * specified Map of properties. + * This method returns a new <code>EntityManager</code> instance each time + * it is invoked. + * The <code>isOpen</code> method will return true on the returned instance. + * @param map properties for entity manager + * @return entity manager instance + * @throws IllegalStateException if the entity manager factory + * has been closed + */ + public EntityManager createEntityManager(Map map); - /** - * Return an instance of Metamodel interface for access to the - * metamodel of the persistence unit. - * - * @return Metamodel instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public Metamodel getMetamodel(); + /** + * Return an instance of <code>CriteriaBuilder</code> for the creation of + * <code>CriteriaQuery</code> objects. + * @return CriteriaBuilder instance + * @throws IllegalStateException if the entity manager factory + * has been closed + * + * @since Java Persistence 2.0 + */ + public CriteriaBuilder getCriteriaBuilder(); - /** - * Indicates whether the factory is open. Returns true - * until the factory has been closed. - */ - public boolean isOpen(); + /** + * Return an instance of <code>Metamodel</code> interface for access to the + * metamodel of the persistence unit. + * @return Metamodel instance + * @throws IllegalStateException if the entity manager factory + * has been closed + * + * @since Java Persistence 2.0 + */ + public Metamodel getMetamodel(); - /** - * Close the factory, releasing any resources that it holds. - * After a factory instance is closed, all methods invoked on - * it will throw an IllegalStateException, except for isOpen, - * which will return false. Once an EntityManagerFactory has - * been closed, all its entity managers are considered to be - * in the closed state. - * - * @throws IllegalStateException if the entity manager factory - * has been closed. - */ - public void close(); + /** + * Indicates whether the factory is open. Returns true + * until the factory has been closed. + * @return boolean indicating whether the factory is open + */ + public boolean isOpen(); - /** - * Get the properties and associated values that are in effect - * for the entity manager factory. Changing the contents of the - * map does not change the configuration in effect. - * - * @return properties - */ - public Map<String, Object> getProperties(); + /** + * Close the factory, releasing any resources that it holds. + * After a factory instance has been closed, all methods invoked + * on it will throw the <code>IllegalStateException</code>, except + * for <code>isOpen</code>, which will return false. Once an + * <code>EntityManagerFactory</code> has been closed, all its + * entity managers are considered to be in the closed state. + * @throws IllegalStateException if the entity manager factory + * has been closed + */ + public void close(); - /** - * Get the names of the properties that are supported for use - * with the entity manager factory. These correspond to - * properties that may be passed to the methods of the - * EntityManagerFactory interface that take a properties - * argument. These include all standard properties as well as - * vendor-specific properties supported by the provider. These - * properties may or may not currently be in effect. - * - * @return properties and hints - */ - public Set<String> getSupportedProperties(); + /** + * Get the properties and associated values that are in effect + * for the entity manager factory. Changing the contents of the + * map does not change the configuration in effect. + * @return properties + * @throws IllegalStateException if the entity manager factory + * has been closed + * + * @since Java Persistence 2.0 + */ + public Map<String, Object> getProperties(); - /** - * Access the cache that is associated with the entity manager - * factory (the "second level cache"). - * - * @return instance of the Cache interface - * - * @throws IllegalStateException if the entity manager factory - * has been closed. - */ - public Cache getCache(); + /** + * Access the cache that is associated with the entity manager + * factory (the "second level cache"). + * @return instance of the <code>Cache</code> interface + * @throws IllegalStateException if the entity manager factory + * has been closed + * + * @since Java Persistence 2.0 + */ + public Cache getCache(); - /** + /** * Return interface providing access to utility methods * for the persistence unit. - * @return PersistenceUnitUtil interface + * @return <code>PersistenceUnitUtil</code> interface * @throws IllegalStateException if the entity manager factory - * has been closed. + * has been closed + * + * @since Java Persistence 2.0 */ public PersistenceUnitUtil getPersistenceUnitUtil(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityNotFoundException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityNotFoundException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityNotFoundException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,30 +1,46 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** * Thrown by the persistence provider when an entity reference obtained by - * EntityManager.getReference(Class,Object) is accessed but the entity does not exist. - * Also thrown when EntityManager.refresh(Object) is called and the object no longer exists - * in the database. The current transaction, if one is active, will be marked for rollback. + * {@link EntityManager#getReference EntityManager.getReference} + * is accessed but the entity does not exist. Thrown when + * {@link EntityManager#refresh EntityManager.refresh} is called and the + * object no longer exists in the database. + * Thrown when {@link EntityManager#lock EntityManager.lock} is used with + * pessimistic locking is used and the entity no longer exists in the database. + * <p> The current transaction, if one is active, will be marked for rollback. * - * @author Gavin King + * @see EntityManager#getReference(Class,Object) + * @see EntityManager#refresh(Object) + * @see EntityManager#refresh(Object, LockModeType) + * @see EntityManager#refresh(Object, java.util.Map) + * @see EntityManager#refresh(Object, LockModeType, java.util.Map) + * @see EntityManager#lock(Object, LockModeType) + * @see EntityManager#lock(Object, LockModeType, java.util.Map) + * + * @since Java Persistence 1.0 */ public class EntityNotFoundException extends PersistenceException { + /** - * Constructs a new EntityNotFoundException exception with null as its detail message. + * Constructs a new <code>EntityNotFoundException</code> exception with + * <code>null</code> as its detail message. */ public EntityNotFoundException() { super(); } /** - * Constructs a new EntityNotFoundException exception with the specified detail message. + * Constructs a new <code>EntityNotFoundException</code> exception with the + * specified detail message. * - * @param message the detail message + * @param message + * the detail message. */ public EntityNotFoundException(String message) { - super( message ); + super(message); } } Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityResult.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityResult.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityResult.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,33 +1,55 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * References an entity in the SELECT clause of a SQL query. If this annotation is used, - * the SQL statement should select all of the columns that are mapped to the entity object. - * This should include foreign key columns to related entities. The results obtained when - * insufficient data is available are undefined. + * Used to map the SELECT clause of a SQL query to an entity result. + * If this annotation is used, the SQL statement should select + * all of the columns that are mapped to the entity object. + * This should include foreign key columns to related entities. + * The results obtained when insufficient data is available + * are undefined. * - * @author Emmanuel Bernard + * <pre> + * Example: + * + * Query q = em.createNativeQuery( + * "SELECT o.id, o.quantity, o.item, i.id, i.name, i.description "+ + * "FROM Order o, Item i " + + * "WHERE (o.quantity > 25) AND (o.item = i.id)", + * "OrderItemResults"); + * &#064;SqlResultSetMapping(name="OrderItemResults", + * entities={ + * &#064;EntityResult(entityClass=com.acme.Order.class), + * &#064;EntityResult(entityClass=com.acme.Item.class) + * }) + * </pre> + * + * @see SqlResultSetMapping + * + * @since Java Persistence 1.0 */ -@Target({}) @Retention(RetentionPolicy.RUNTIME) +@Target({}) +@Retention(RUNTIME) public @interface EntityResult { - /** - * The class of the result - */ - Class entityClass(); - /** - * Maps the columns specified in the SELECT list of the query to the properties or - * fields of the entity class. - */ - FieldResult[] fields() default {}; - /** - * Specifies the column name (or alias) of the column in the SELECT list that is used to - * determine the type of the entity instance. - */ - String discriminatorColumn() default ""; + + /** The class of the result. */ + Class entityClass(); + + /** + * Maps the columns specified in the SELECT list of the + * query to the properties or fields of the entity class. + */ + FieldResult[] fields() default {}; + + /** + * Specifies the column name (or alias) of the column in + * the SELECT list that is used to determine the type of + * the entity instance. + */ + String discriminatorColumn() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityTransaction.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityTransaction.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityTransaction.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,62 +1,62 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -/** - * The EntityTransaction interface is used to control resource transactions - * on resource-local entity managers. The EntityManager.getTransaction() - * method returns the EntityTransaction interface. - * - * @author Emmanuel Bernard - */ -public interface EntityTransaction { - /** - * Start a resource transaction. - * - * @throws IllegalStateException if isActive() is true. - */ - public void begin(); - - /** - * Commit the current transaction, writing any unflushed - * changes to the database. - * - * @throws IllegalStateException if isActive() is false. - * @throws RollbackException if the commit fails. - */ - public void commit(); - - /** - * Roll back the current transaction. - * - * @throws IllegalStateException if isActive() is false. - * @throws PersistenceException if an unexpected error - * condition is encountered. - */ - public void rollback(); - - /** - * Mark the current transaction so that the only possible - * outcome of the transaction is for the transaction to be - * rolled back. - * - * @throws IllegalStateException if isActive() is false. - */ - public void setRollbackOnly(); - - /** - * Determine whether the current transaction has been marked - * for rollback. - * - * @throws IllegalStateException if isActive() is false. - */ - public boolean getRollbackOnly(); - - /** - * Indicate whether a transaction is in progress. - * - * @throws PersistenceException if an unexpected error - * condition is encountered. - */ - public boolean isActive(); +package javax.persistence; + +/** + * Interface used to control transactions on resource-local entity + * managers. The {@link EntityManager#getTransaction + * EntityManager.getTransaction()} method returns the + * <code>EntityTransaction</code> interface. + * + * @since Java Persistence 1.0 + */ +public interface EntityTransaction { + + /** + * Start a resource transaction. + * @throws IllegalStateException if <code>isActive()</code> is true + */ + public void begin(); + + /** + * Commit the current resource transaction, writing any + * unflushed changes to the database. + * @throws IllegalStateException if <code>isActive()</code> is false + * @throws RollbackException if the commit fails + */ + public void commit(); + + /** + * Roll back the current resource transaction. + * @throws IllegalStateException if <code>isActive()</code> is false + * @throws PersistenceException if an unexpected error + * condition is encountered + */ + public void rollback(); + + /** + * Mark the current resource transaction so that the only + * possible outcome of the transaction is for the transaction + * to be rolled back. + * @throws IllegalStateException if <code>isActive()</code> is false + */ + public void setRollbackOnly(); + + /** + * Determine whether the current resource transaction has been + * marked for rollback. + * @return boolean indicating whether the transaction has been + * marked for rollback + * @throws IllegalStateException if <code>isActive()</code> is false + */ + public boolean getRollbackOnly(); + + /** + * Indicate whether a resource transaction is in progress. + * @return boolean indicating whether transaction is + * in progress + * @throws PersistenceException if an unexpected error + * condition is encountered + */ + public boolean isActive(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/EnumType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EnumType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/EnumType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,18 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Defines mapping for the enumerated types. The constants of this enumerated type specify how persistent - * property or field should be persisted as a enumerated type. + * Defines mapping for enumerated types. The constants of this + * enumerated type specify how a persistent property or + * field of an enumerated type should be persisted. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ public enum EnumType { - /** - * Persist enumerated type property or field as an integer - */ - ORDINAL, - /** - * Persist enumerated type property or field as a string - */ - STRING + /** Persist enumerated type property or field as an integer. */ + ORDINAL, + + /** Persist enumerated type property or field as a string. */ + STRING } Modified: jpa-api/trunk/src/main/java/javax/persistence/Enumerated.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Enumerated.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Enumerated.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,25 +1,48 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import static javax.persistence.EnumType.ORDINAL; -import static java.lang.annotation.RetentionPolicy.*; -import static java.lang.annotation.ElementType.*; -import static javax.persistence.EnumType.*; - /** - * Specifies that a persistent property or field should be persisted as a enumerated type. - * It may be used in conjunction with the Basic annotation. + * Specifies that a persistent property or field should be persisted + * as a enumerated type. The <code>Enumerated</code> annotation may + * be used in conjunction with the <code>Basic</code> annotation, or in + * conjunction with the <code>ElementCollection</code> annotation when the + * element collection value is of basic type. If the enumerated type + * is not specified or the <code>Enumerated</code> annotation is not + * used, the <code>EnumType</code> value is assumed to be <code>ORDINAL<code>. * - * @author Emmanuel Bernard + * <pre> + * Example: + * + * public enum EmployeeStatus {FULL_TIME, PART_TIME, CONTRACT} + * + * public enum SalaryRate {JUNIOR, SENIOR, MANAGER, EXECUTIVE} + * + * &#064;Entity public class Employee { + * public EmployeeStatus getStatus() {...} + * ... + * &#064;Enumerated(STRING) + * public SalaryRate getPayScale() {...} + * ... + * } + * </pre> + * + * @see Basic + * @see ElementCollection + * + * @since Java Persistence 1.0 */ @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface Enumerated { - /** - * The type used in mapping an enum type - */ - EnumType value() default ORDINAL; + + /** (Optional) The type used in mapping an enum type. */ + EnumType value() default ORDINAL; } Modified: jpa-api/trunk/src/main/java/javax/persistence/ExcludeDefaultListeners.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ExcludeDefaultListeners.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/ExcludeDefaultListeners.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,18 +1,20 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.TYPE; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * Specifies that the invocation of default listeners is to be excluded for the entity class - * (or mapped superclass) and its subclasses. + * Specifies that the invocation of default listeners is + * to be excluded for the entity class (or mapped superclass) + * and its subclasses. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ -@Target(TYPE) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) public @interface ExcludeDefaultListeners { } Modified: jpa-api/trunk/src/main/java/javax/persistence/ExcludeSuperclassListeners.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ExcludeSuperclassListeners.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/ExcludeSuperclassListeners.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,18 +1,20 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; - import java.lang.annotation.Target; import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.TYPE; /** - * Specifies that the invocation of superclass listeners is to be excluded for the - * entity class (or mapped superclass) and its subclasses. + * Specifies that the invocation of superclass listeners is + * to be excluded for the entity class (or mapped superclass) + * and its subclasses. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ -@Target(TYPE) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) + public @interface ExcludeSuperclassListeners { } Modified: jpa-api/trunk/src/main/java/javax/persistence/FetchType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/FetchType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/FetchType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,24 +1,36 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** * Defines strategies for fetching data from the database. - * The EAGER strategy is a requirement on the persistence provider runtime that data must - * be eagerly fetched. The LAZY strategy is a hint to the persistence provider runtime that - * data should be fetched lazily when it is first accessed. The implementation is permitted to - * eagerly fetch data for which the LAZY strategy hint has been specified. In particular, lazy - * fetching might only be available for Basic mappings for which property-based access is used. + * The <code>EAGER</code> strategy is a requirement on the persistence + * provider runtime that data must be eagerly fetched. The + * <code>LAZY</code> strategy is a hint to the persistence provider + * runtime that data should be fetched lazily when it is + * first accessed. The implementation is permitted to eagerly + * fetch data for which the <code>LAZY</code> strategy hint has been + * specified. * - * @author Emmanuel Bernard + * <pre> + * Example: + * &#064;Basic(fetch=LAZY) + * protected String getName() { return name; } + * </pre> + * + * @see Basic + * @see ElementCollection + * @see ManyToMany + * @see OneToMany + * @see ManyToOne + * @see OneToOne + * @since Java Persistence 1.0 */ public enum FetchType { - /** - * Defines that data must be lazily fetched - */ - LAZY, - /** - * Defines that data must be eagerly fetched - */ - EAGER -}; + + /** Defines that data can be lazily fetched. */ + LAZY, + + /** Defines that data must be eagerly fetched. */ + EAGER +} Modified: jpa-api/trunk/src/main/java/javax/persistence/FieldResult.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/FieldResult.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/FieldResult.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,25 +1,48 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; -import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Is used to map the columns specified in the SELECT list of the query to the properties - * or fields of the entity class. + * Is used to map the columns specified in the SELECT list + * of the query to the properties or fields of the entity class. * - * @author Emmanuel Bernard + * <pre> + * + * Example: + * Query q = em.createNativeQuery( + * "SELECT o.id AS order_id, " + + * "o.quantity AS order_quantity, " + + * "o.item AS order_item, " + + * "FROM Order o, Item i " + + * "WHERE (order_quantity > 25) AND (order_item = i.id)", + * "OrderResults"); + * + * &#064;SqlResultSetMapping(name="OrderResults", + * entities={ + * &#064;EntityResult(entityClass=com.acme.Order.class, fields={ + * &#064;FieldResult(name="id", column="order_id"), + * &#064;FieldResult(name="quantity", column="order_quantity"), + * &#064;FieldResult(name="item", column="order_item")}) + * }) + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({}) @Retention(RetentionPolicy.RUNTIME) +@Target({}) +@Retention(RUNTIME) + public @interface FieldResult { - /** - * Name of the persistent field or property of the class. - */ - String name(); - /** - * Name of the column in the SELECT clause - i.e., column aliases, if applicable. - */ - String column(); + + /** Name of the persistent field or property of the class. */ + String name(); + + /** + * Name of the column in the SELECT clause - i.e., column + * aliases, if applicable. + */ + String column(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/FlushModeType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/FlushModeType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/FlushModeType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,30 +1,38 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** * Flush mode setting. * - * When queries are executed within a transaction, if FlushModeType.AUTO is set on the Query object, - * or if the flush mode setting for the persistence context is AUTO (the default) and a flush mode - * setting has not been specified for the Query object, the persistence provider is responsible for - * ensuring that all updates to the state of all entities in the persistence context which could - * potentially affect the result of the query are visible to the processing of the query. - * The persistence provider implementation may achieve this by flushing those entities to the database - * or by some other means. If FlushModeType.COMMIT is set, the effect of updates made to entities in the - * persistence context upon queries is unspecified. + * <p> When queries are executed within a transaction, if + * <code>FlushModeType.AUTO</code> is set on the {@link + * javax.persistence.Query Query} or {@link javax.persistence.TypedQuery + * TypedQuery} object, or if the flush mode setting for the + * persistence context is <code>AUTO</code> (the default) and a flush + * mode setting has not been specified for the <code>Query</code> or + * <code>TypedQuery</code> object, the persistence provider is + * responsible for ensuring that all updates to the state of all + * entities in the persistence context which could potentially affect + * the result of the query are visible to the processing of the + * query. The persistence provider implementation may achieve this by + * flushing those entities to the database or by some other means. + * <p> If <code>FlushModeType.COMMIT</code> is set, the effect of + * updates made to entities in the persistence context upon queries is + * unspecified. * - * If there is no transaction active, the persistence provider must not flush to the database. + * <p> If there is no transaction active, the persistence provider + * must not flush to the database. * - * @author Gavin King + * @since Java Persistence 1.0 */ public enum FlushModeType { - /** - * Flushing must occur only at transaction commit - */ - COMMIT, - /** - * (Default) Flushing to occur at query execution - */ - AUTO + + /** Flushing to occur at transaction commit. The provider may flush + * at other times, but is not required to. + */ + COMMIT, + + /** (Default) Flushing to occur at query execution. */ + AUTO } Modified: jpa-api/trunk/src/main/java/javax/persistence/GeneratedValue.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/GeneratedValue.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/GeneratedValue.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,33 +1,66 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; +import static javax.persistence.GenerationType.AUTO; /** - * Provides for the specification of generation strategies for the values of primary keys. - * The GeneratedValue annotation may be applied to a primary key property or field of an entity - * or mapped superclass in conjunction with the Id annotation. + * Provides for the specification of generation strategies for the + * values of primary keys. * - * @author Emmanuel Bernard + * <p> The <code>GeneratedValue</code> annotation + * may be applied to a primary key property or field of an entity or + * mapped superclass in conjunction with the {@link Id} annotation. + * The use of the <code>GeneratedValue</code> annotation is only + * required to be supported for simple primary keys. Use of the + * <code>GeneratedValue</code> annotation is not supported for derived + * primary keys. + * + * <pre> + * + * Example 1: + * + * &#064;Id + * &#064;GeneratedValue(strategy=SEQUENCE, generator="CUST_SEQ") + * &#064;Column(name="CUST_ID") + * public Long getId() { return id; } + * + * Example 2: + * + * &#064;Id + * &#064;GeneratedValue(strategy=TABLE, generator="CUST_GEN") + * &#064;Column(name="CUST_ID") + * Long id; + * </pre> + * + * @see Id + * @see TableGenerator + * @see SequenceGenerator + * + * @since Java Persistence 1.0 */ @Target({METHOD, FIELD}) @Retention(RUNTIME) + public @interface GeneratedValue { - /** - * The primary key generation strategy that the persistence provider must use - * to generate the annotated entity primary key. - */ - GenerationType strategy() default GenerationType.AUTO; - /** - * The name of the primary key generator to use as specified in the SequenceGenerator or - * TableGenerator annotation. - * - * Defaults to the id generator supplied by persistence provider. - */ - String generator() default ""; + + /** + * (Optional) The primary key generation strategy + * that the persistence provider must use to + * generate the annotated entity primary key. + */ + GenerationType strategy() default AUTO; + + /** + * (Optional) The name of the primary key generator + * to use as specified in the {@link SequenceGenerator} + * or {@link TableGenerator} annotation. + * <p> Defaults to the id generator supplied by persistence provider. + */ + String generator() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/GenerationType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/GenerationType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/GenerationType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,34 +1,43 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Defines the types of primary key generation. + * Defines the types of primary key generation strategies. * - * @author Emmanuel Bernard + * @see GeneratedValue + * + * @since Java Persistence 1.0 */ public enum GenerationType { - /** - * Indicates that the persistence provider must assign primary keys for the entity using an underlying - * database table to ensure uniqueness. - */ - TABLE, - /** - * Indicates that the persistence provider must assign primary keys for the entity using database - * sequence column. - */ - SEQUENCE, - /** - * Indicates that the persistence provider must assign primary keys for the entity using - * database identity column. - */ - IDENTITY, - /** - * Indicates that the persistence provider should pick an appropriate strategy for the - * particular database. The AUTO generation strategy may expect a database resource - * to exist, or it may attempt to create one. A vendor may provide documentation on how - * to create such resources in the event that it does not support schema generation or cannot - * create the schema resource at runtime. - */ - AUTO -}; + + /** + * Indicates that the persistence provider must assign + * primary keys for the entity using an underlying + * database table to ensure uniqueness. + */ + TABLE, + + /** + * Indicates that the persistence provider must assign + * primary keys for the entity using a database sequence. + */ + SEQUENCE, + + /** + * Indicates that the persistence provider must assign + * primary keys for the entity using a database identity column. + */ + IDENTITY, + + /** + * Indicates that the persistence provider should pick an + * appropriate strategy for the particular database. The + * <code>AUTO</code> generation strategy may expect a database + * resource to exist, or it may attempt to create one. A vendor + * may provide documentation on how to create such resources + * in the event that it does not support schema generation + * or cannot create the schema resource at runtime. + */ + AUTO +} Modified: jpa-api/trunk/src/main/java/javax/persistence/Id.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Id.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Id.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,18 +1,43 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; - /** - * Specifies the primary key property or field of an entity. - * - * @author Emmanuel Bernard + * Specifies the primary key of an entity. + * The field or property to which the <code>Id</code> annotation is applied + * should be one of the following types: any Java primitive type; + * any primitive wrapper type; + * <code>String</code>; + * <code>java.util.Date</code>; + * <code>java.sql.Date</code>; + * <code>java.math.BigDecimal</code>; + * <code>java.math.BigInteger</code>. + * + * <p>The mapped column for the primary key of the entity is assumed + * to be the primary key of the primary table. If no <code>Column</code> annotation + * is specified, the primary key column name is assumed to be the name + * of the primary key property or field. + * + * <pre> + * Example: + * + * &#064;Id + * public Long getId() { return id; } + * </pre> + * + * @see Column + * @see GeneratedValue + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) -public @interface Id {} +@Target({METHOD, FIELD}) +@Retention(RUNTIME) + +public @interface Id { +} Modified: jpa-api/trunk/src/main/java/javax/persistence/IdClass.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/IdClass.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/IdClass.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,26 +1,40 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; - import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Specifies a composite primary key class that is mapped to multiple fields or properties - * of the entity. + * Specifies a composite primary key class that is mapped to + * multiple fields or properties of the entity. * - * The names of the fields or properties in the primary key class and the primary key fields - * or properties of the entity must correspond and their types must be the same. + * <p> The names of the fields or properties in the primary key + * class and the primary key fields or properties of the entity + * must correspond and their types must be the same. * - * @author Emmanuel Bernard + * <pre> + * + * Example: + * + * &#064;IdClass(com.acme.EmployeePK.class) + * &#064;Entity + * public class Employee { + * &#064;Id String empName; + * &#064;Id Date birthDay; + * ... + * } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) + public @interface IdClass { - /** - * Primary key class - */ - Class value(); + + /** Primary key class */ + Class value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/Inheritance.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Inheritance.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Inheritance.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,23 +1,39 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.TYPE; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; import static javax.persistence.InheritanceType.SINGLE_TABLE; /** - * Defines the inheritance strategy to be used for an entity class hierarchy. It is specified - * on the entity class that is the root of the entity class hierarchy. + * Defines the inheritance strategy to be used for an entity class + * hierarchy. It is specified on the entity class that is the root of + * the entity class hierarchy. If the <code>Inheritance</code> annotation is not + * specified or if no inheritance type is specified for an entity + * class hierarchy, the <code>SINGLE_TABLE<code> mapping strategy is used. * - * @author Emmanuel Bernard + * <pre> + * + * Example: + * + * &#064;Entity + * &#064;Inheritance(strategy=JOINED) + * public class Customer { ... } + * + * &#064;Entity + * public class ValuedCustomer extends Customer { ... } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) + public @interface Inheritance { - /** - * The strategy to be used - */ - InheritanceType strategy() default SINGLE_TABLE; + + /** The strategy to be used for the entity inheritance hierarchy. */ + InheritanceType strategy() default SINGLE_TABLE; } Modified: jpa-api/trunk/src/main/java/javax/persistence/InheritanceType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/InheritanceType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/InheritanceType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,25 +1,25 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** * Defines inheritance strategy options. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ -public enum InheritanceType -{ - /** - * A single table per class hierarchy - */ - SINGLE_TABLE, - /** - * A table per concrete entity class - */ - TABLE_PER_CLASS, - /** - * A strategy in which fields that are specific to a subclass are mapped to a separate - * table than the fields that are common to the parent class, and a join is performed - * to instantiate the subclass. - */ - JOINED }; +public enum InheritanceType { + + /** A single table per class hierarchy. */ + SINGLE_TABLE, + + /** A table per concrete entity class. */ + TABLE_PER_CLASS, + + /** + * A strategy in which fields that are specific to a + * subclass are mapped to a separate table than the fields + * that are common to the parent class, and a join is + * performed to instantiate the subclass. + */ + JOINED +} Modified: jpa-api/trunk/src/main/java/javax/persistence/JoinColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/JoinColumn.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/JoinColumn.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,67 +1,157 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * Is used to specify a mapped column for joining an entity association. + * Specifies a column for joining an entity association or element + * collection. If the <code>JoinColumn</code> annotation itself is + * defaulted, a single join column is assumed and the default values + * apply. * - * @author Emmanuel Bernard + * <pre> + * Example: + * + * &#064;ManyToOne + * &#064;JoinColumn(name="ADDR_ID") + * public Address getAddress() { return address; } + * + * + * Example: unidirectional one-to-many association using a foreign key mapping + * + * // In Customer class + * &#064;OneToMany + * &#064;JoinColumn(name="CUST_ID") // join column is in table for Order + * public Set&#060;Order&#062; getOrders() {return orders;} + * </pre> + * + * @see ManyToOne + * @see OneToMany + * @see OneToOne + * @see JoinTable + * @see CollectionTable + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) public @interface JoinColumn { - /** - * The name of the foreign key column. - * The table in which it is found depends upon the context. If the join is for a OneToOne - * or Many- ToOne mapping, the foreign key column is in the table of the source entity. - * If the join is for a ManyToMany, the foreign key is in a join table. Default (only applies - * if a single join column is used): The concatenation of the following: the name of the referencing - * relationship property or field of the referencing entity; "_"; the name of the referenced primary - * key column. If there is no such referencing relationship property or field in the entity, the join - * column name is formed as the concatenation of the following: the name of the entity; "_"; the name - * of the referenced primary key column. - */ - String name() default ""; - /** - * The name of the column referenced by this foreign key column. When used with relationship mappings, - * the referenced column is in the table of the target entity. When used inside a JoinTable annotation, - * the referenced key column is in the entity table of the owning entity, or inverse entity if the join - * is part of the inverse join definition. Default (only applies if single join column is being used): - * The same name as the primary key column of the referenced table. - */ - String referencedColumnName() default ""; - /** - * Whether the property is a unique key. This is a shortcut for the UniqueConstraint annotation at the - * table level and is useful for when the unique key constraint is only a single field. It is not - * necessary to explicitly specify this for a join column that corresponds to a primary key that is part - * of a foreign key. - */ - boolean unique() default false; - /** - * Whether the foreign key column is nullable - */ - boolean nullable() default true; - /** - * Whether the column is included in SQL INSERT statements generated by the persistence provider - */ - boolean insertable() default true; - /** - * Whether the column is included in SQL UPDATE statements generated by the persistence provider - */ - boolean updatable() default true; - /** - * The SQL fragment that is used when generating the DDL for the column. - * Defaults to the generated SQL for the column. - */ - String columnDefinition() default ""; - /** - * The name of the table that contains the column. If a table is not specified, the column is - * assumed to be in the primary table of the applicable entity - */ - String table() default ""; + + /** + * (Optional) The name of the foreign key column. + * The table in which it is found depends upon the + * context. + * <ul> + * <li>If the join is for a OneToOne or ManyToOne + * mapping using a foreign key mapping strategy, + * the foreign key column is in the table of the + * source entity or embeddable. + * <li> If the join is for a unidirectional OneToMany mapping + * using a foreign key mapping strategy, the foreign key is in the + * table of the target entity. + * <li> If the join is for a ManyToMany mapping or for a OneToOne + * or bidirectional ManyToOne/OneToMany mapping using a join + * table, the foreign key is in a join table. + * <li> If the join is for an element collection, the foreign + * key is in a collection table. + *</ul> + * + * <p> Default (only applies if a single join column is used): + * The concatenation of the following: the name of the + * referencing relationship property or field of the referencing + * entity or embeddable class; "_"; the name of the referenced + * primary key column. + * If there is no such referencing relationship property or + * field in the entity, or if the join is for an element collection, + * the join column name is formed as the + * concatenation of the following: the name of the entity; "_"; + * the name of the referenced primary key column. + */ + String name() default ""; + + /** + * (Optional) The name of the column referenced by this foreign + * key column. + * <ul> + * <li> When used with entity relationship mappings other + * than the cases described here, the referenced column is in the + * table of the target entity. + * <li> When used with a unidirectional OneToMany foreign key + * mapping, the referenced column is in the table of the source + * entity. + * <li> When used inside a <code>JoinTable</code> annotation, + * the referenced key column is in the entity table of the owning + * entity, or inverse entity if the join is part of the inverse + * join definition. + * <li> When used in a <code>CollectionTable</code> mapping, the + * referenced column is in the table of the entity containing the + * collection. + * </ul> + * + * <p> Default (only applies if single join column is being + * used): The same name as the primary key column of the + * referenced table. + */ + String referencedColumnName() default ""; + + /** + * (Optional) Whether the property is a unique key. This is a + * shortcut for the <code>UniqueConstraint</code> annotation at + * the table level and is useful for when the unique key + * constraint is only a single field. It is not necessary to + * explicitly specify this for a join column that corresponds to a + * primary key that is part of a foreign key. + */ + boolean unique() default false; + + /** (Optional) Whether the foreign key column is nullable. */ + boolean nullable() default true; + + /** + * (Optional) Whether the column is included in + * SQL INSERT statements generated by the persistence + * provider. + */ + boolean insertable() default true; + + /** + * (Optional) Whether the column is included in + * SQL UPDATE statements generated by the persistence + * provider. + */ + boolean updatable() default true; + + /** + * (Optional) The SQL fragment that is used when + * generating the DDL for the column. + * <p> Defaults to the generated SQL for the column. + */ + String columnDefinition() default ""; + + /** + * (Optional) The name of the table that contains + * the column. If a table is not specified, the column + * is assumed to be in the primary table of the + * applicable entity. + * + * <p> Default: + * <ul> + * <li> If the join is for a OneToOne or ManyToOne mapping + * using a foreign key mapping strategy, the name of the table of + * the source entity or embeddable. + * <li> If the join is for a unidirectional OneToMany mapping + * using a foreign key mapping strategy, the name of the table of + * the target entity. + * <li> If the join is for a ManyToMany mapping or + * for a OneToOne or bidirectional ManyToOne/OneToMany mapping + * using a join table, the name of the join table. + * <li> If the join is for an element collection, the name of the collection table. + * </ul> + */ + String table() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/JoinColumns.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/JoinColumns.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/JoinColumns.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,23 +1,42 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * Defines mapping for the composite foreign keys. - * This annotation groups JoinColumn annotations for the same relationship. + * Defines mapping for composite foreign keys. This annotation + * groups <code>JoinColumn</code> annotations for the same relationship. * - * When the JoinColumns annotation is used, both the name and the referencedColumnName - * elements must be specified in each such JoinColumn annotation. - - * @author Emmanuel Bernard + * <p> When the <code>JoinColumns</code> annotation is used, + * both the <code>name</code> and the <code>referencedColumnName</code> elements + * must be specified in each such <code>JoinColumn</code> annotation. + * + * <pre> + * + * Example: + * &#064;ManyToOne + * &#064;JoinColumns({ + * &#064;JoinColumn(name="ADDR_ID", referencedColumnName="ID"), + * &#064;JoinColumn(name="ADDR_ZIP", referencedColumnName="ZIP") + * }) + * public Address getAddress() { return address; } + * </pre> + * + * @see JoinColumn + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) public @interface JoinColumns { + + /** + * The join columns that map the relationship. + */ JoinColumn[] value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/JoinTable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/JoinTable.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/JoinTable.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,63 +1,103 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * This annotation is used in the mapping of associations. It is specified on the owning - * side of a many-to-many association, or in a unidirectional one-to-many association. + * Used in the mapping of associations. It is specified on the + * owning side of an association. * - * If the JoinTable annotation is missing, the default values of the annotation elements apply. - * The name of the join table is assumed to be the table names of the associated primary tables - * concatenated together (owning side first) using an underscore. + * <p> A join table is typically used in the mapping of many-to-many + * and unidirectional one-to-many associations. It may also be used to + * map bidirectional many-to-one/one-to-many associations, + * unidirectional many-to-one relationships, and one-to-one + * associations (both bidirectional and unidirectional). * - * @author Emmanuel Bernard + *<p>When a join table is used in mapping a relationship with an + *embeddable class on the owning side of the relationship, the + *containing entity rather than the embeddable class is considered the + *owner of the relationship. + * + * <p> If the <code>JoinTable</code> annotation is missing, the + * default values of the annotation elements apply. + * The name of the join table is assumed to be the table names of the + * associated primary tables concatenated together (owning side + * first) using an underscore. + * + * <pre> + * + * Example: + * + * &#064;JoinTable( + * name="CUST_PHONE", + * joinColumns= + * &#064;JoinColumn(name="CUST_ID", referencedColumnName="ID"), + * inverseJoinColumns= + * &#064;JoinColumn(name="PHONE_ID", referencedColumnName="ID") + * ) + * </pre> + * + * @see JoinColumn + * @see JoinColumns + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) + public @interface JoinTable { - /** - * The name of the join table. - * - * Defaults to the concatenated names of the two associated primary entity tables, - * separated by an underscore - */ - String name() default ""; - /** - * The catalog of the table. - * - * Defaults to the default catalog. - */ - String catalog() default ""; - /** - * The schema of the table. - * - * Defaults to the default schema for user. - */ - String schema() default ""; - /** - * The foreign key columns of the join table which reference the primary table of the - * entity owning the association (i.e. the owning side of the association). - * - * Uses the same defaults as for JoinColumn. - */ - JoinColumn[] joinColumns() default {}; - /** - * The foreign key columns of the join table which reference the primary table of the entity - * that does not own the association (i.e. the inverse side of the association). - * - * Uses the same defaults as for JoinColumn - */ - JoinColumn[] inverseJoinColumns() default {}; - /** - * Unique constraints that are to be placed on the table. These are only used if table - * generation is in effect. - * - * Defaults to no additional constraints - */ - UniqueConstraint[] uniqueConstraints() default {}; + + /** + * (Optional) The name of the join table. + * + * <p> Defaults to the concatenated names of + * the two associated primary entity tables, + * separated by an underscore. + */ + String name() default ""; + + /** (Optional) The catalog of the table. + * <p> Defaults to the default catalog. + */ + String catalog() default ""; + + /** (Optional) The schema of the table. + * <p> Defaults to the default schema for user. + */ + String schema() default ""; + + /** + * (Optional) The foreign key columns + * of the join table which reference the + * primary table of the entity owning the + * association. (I.e. the owning side of + * the association). + * + * <p> Uses the same defaults as for {@link JoinColumn}. + */ + JoinColumn[] joinColumns() default {}; + + /** + * (Optional) The foreign key columns + * of the join table which reference the + * primary table of the entity that does + * not own the association. (I.e. the + * inverse side of the association). + * + * <p> Uses the same defaults as for {@link JoinColumn}. + */ + JoinColumn[] inverseJoinColumns() default {}; + + /** + * (Optional) Unique constraints that are + * to be placed on the table. These are + * only used if table generation is in effect. + * <p> Defaults to no additional constraints. + */ + UniqueConstraint[] uniqueConstraints() default {}; } Modified: jpa-api/trunk/src/main/java/javax/persistence/Lob.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Lob.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Lob.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,25 +1,49 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import static java.lang.annotation.ElementType.METHOD; - -import static java.lang.annotation.ElementType.FIELD; - -import static java.lang.annotation.RetentionPolicy.RUNTIME; - -import java.lang.annotation.Target; -import java.lang.annotation.Retention; - -/** - * Specifies that a persistent property or field should be persisted as a large object to a - * database-supported large object type. The Lob annotation may be used in conjunction with - * the Basic annotation. A Lob may be either a binary or character type. - * - * The Lob type is inferred from the type of the persistent field or property, and except - * for string and character-based types defaults to Blob. - * - * @author Emmanuel Bernard - */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) -public @interface Lob {} +package javax.persistence; + +import java.lang.annotation.Target; +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; + +/** + * Specifies that a persistent property or field should be persisted + * as a large object to a database-supported large object type. + * + * <p> Portable applications should use the <code>Lob</code> annotation + * when mapping to a database Lob type. The <code>Lob</code> + * annotation may be used in conjunction with the {@link Basic} + * annotation or the {@link ElementCollection} annotation when the + * element collection value is of basic type. A <code>Lob</code> may + * be either a binary or character type. + * + * <p> The <code>Lob</code> type is inferred from the type of the + * persistent field or property, and except for string and + * character-based types defaults to Blob. + * <pre> + * + * Example 1: + * + * &#064;Lob &#064;Basic(fetch=LAZY) + * &#064;Column(name="REPORT") + * protected String report; + * + * Example 2: + * + * &#064;Lob &#064;Basic(fetch=LAZY) + * &#064;Column(name="EMP_PIC", columnDefinition="BLOB NOT NULL") + * protected byte[] pic; + * + * </pre> + * + * @see Basic + * @see ElementCollection + * + * @since Java Persistence 1.0 + */ +@Target({METHOD, FIELD}) +@Retention(RUNTIME) +public @interface Lob { +} Modified: jpa-api/trunk/src/main/java/javax/persistence/LockModeType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/LockModeType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/LockModeType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,54 +1,175 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Lock modes that can be specified by means of the EntityManager.lock() method. - * <p/> - * The semantics of requesting locks of type LockModeType.READ and LockModeType.WRITE are t - * he following. - * <p/> - * If transaction T1 calls lock(entity, LockModeType.READ) on a versioned object, the entity - * manager must ensure that neither of the following phenomena can occur: - * <p/> - * * P1 (Dirty read): Transaction T1 modifies a row. Another transaction T2 then reads - * that row and obtains the modified value, before T1 has committed or rolled back. - * Transaction T2 eventually commits successfully; it does not matter whether T1 commits or rolls - * back and whether it does so before or after T2 commits. - * <p/> - * * P2 (Non-repeatable read): Transaction T1 reads a row. Another transaction T2 then modifies - * or deletes that row, before T1 has committed. Both transactions eventually commit successfully. - * <p/> - * Lock modes must always prevent the phenomena P1 and P2. - * In addition, calling lock(entity, LockModeType.WRITE) on a versioned object, - * will also force an update (increment) to the entity's version column. - * <p/> - * The persistence implementation is not required to support calling EntityManager.lock() - * on a non-versioned object. When it cannot support a such lock call, it must - * throw the PersistenceException. + * Lock modes can be specified by means of passing a <code>LockModeType</code> + * argument to one of the {@link javax.persistence.EntityManager} methods that take locks + * (<code>lock</code>, <code>find</code>, or <code>refresh</code>) or + * to the {@link Query#setLockMode Query.setLockMode()} or + * {@link TypedQuery#setLockMode TypedQuery.setLockMode()} method. * - * @author Emmanuel Bernard + * <p> Lock modes can be used to specify either optimistic or pessimistic locks. + * + * <p> Optimistic locks are specified using {@link + * LockModeType#OPTIMISTIC LockModeType.OPTIMISTIC} and {@link + * LockModeType#OPTIMISTIC_FORCE_INCREMENT + * LockModeType.OPTIMISTIC_FORCE_INCREMENT}. The lock mode type + * values {@link LockModeType#READ LockModeType.READ} and + * {@link LockModeType#WRITE LockModeType.WRITE} are + * synonyms of <code>OPTIMISTIC</code> and + * <code>OPTIMISTIC_FORCE_INCREMENT</code> respectively. The latter + * are to be preferred for new applications. + * + * <p> The semantics of requesting locks of type + * <code>LockModeType.OPTIMISTIC</code> and + * <code>LockModeType.OPTIMISTIC_FORCE_INCREMENT<code> are the + * following. + * + * <p> If transaction T1 calls for a lock of type + * <code>LockModeType.OPTIMISTIC</code> on a versioned object, + * the entity manager must ensure that neither of the following + * phenomena can occur: + * <ul> + * <li> P1 (Dirty read): Transaction T1 modifies a row. + * Another transaction T2 then reads that row and obtains + * the modified value, before T1 has committed or rolled back. + * Transaction T2 eventually commits successfully; it does not + * matter whether T1 commits or rolls back and whether it does + * so before or after T2 commits. + * <li> + * </li> P2 (Non-repeatable read): Transaction T1 reads a row. + * Another transaction T2 then modifies or deletes that row, + * before T1 has committed. Both transactions eventually commit + * successfully. + * </li> + * </ul> + * + * <p> Lock modes must always prevent the phenomena P1 and P2. + * + * <p> In addition, calling a lock of type + * <code>LockModeType.OPTIMISTIC_FORCE_INCREMENT</code> on a versioned object, + * will also force an update (increment) to the entity's version + * column. + * + * <p> The persistence implementation is not required to support + * the use of optimistic lock modes on non-versioned objects. When it + * cannot support a such lock call, it must throw the {@link + * PersistenceException}. + * + * <p>The lock modes {@link LockModeType#PESSIMISTIC_READ + * LockModeType.PESSIMISTIC_READ}, {@link + * LockModeType#PESSIMISTIC_WRITE LockModeType.PESSIMISTIC_WRITE}, and + * {@link LockModeType#PESSIMISTIC_FORCE_INCREMENT + * LockModeType.PESSIMISTIC_FORCE_INCREMENT} are used to immediately + * obtain long-term database locks. + * + * <p> The semantics of requesting locks of type + * <code>LockModeType.PESSIMISTIC_READ</code>, <code>LockModeType.PESSIMISTIC_WRITE</code>, and + * <code>LockModeType.PESSIMISTIC_FORCE_INCREMENT</code> are the following. + * + * <p> If transaction T1 calls for a lock of type + * <code>LockModeType.PESSIMISTIC_READ</code> or + * <code>LockModeType.PESSIMISTIC_WRITE</code> on an object, the entity + * manager must ensure that neither of the following phenomena can + * occur: + * <ul> + * <li> P1 (Dirty read): Transaction T1 modifies a + * row. Another transaction T2 then reads that row and obtains the + * modified value, before T1 has committed or rolled back. + * + * <li> P2 (Non-repeatable read): Transaction T1 reads a row. Another + * transaction T2 then modifies or deletes that row, before T1 has + * committed or rolled back. + * </ul> + * + * <p> A lock with <code>LockModeType.PESSIMISTIC_WRITE</code> can be obtained on + * an entity instance to force serialization among transactions + * attempting to update the entity data. A lock with + * <code>LockModeType.PESSIMISTIC_READ</code> can be used to query data using + * repeatable-read semantics without the need to reread the data at + * the end of the transaction to obtain a lock, and without blocking + * other transactions reading the data. A lock with + * <code>LockModeType.PESSIMISTIC_WRITE</code> can be used when querying data and + * there is a high likelihood of deadlock or update failure among + * concurrent updating transactions. + * + * <p> The persistence implementation must support use of locks of type + * <code>LockModeType.PESSIMISTIC_READ</code> + * <code>LockModeType.PESSIMISTIC_WRITE</code> on a non-versioned entity as well as + * on a versioned entity. + * + * <p> When the lock cannot be obtained, and the database locking + * failure results in transaction-level rollback, the provider must + * throw the {@link PessimisticLockException} and ensure that the JTA + * transaction or <code>EntityTransaction</code> has been marked for rollback. + * + * <p> When the lock cannot be obtained, and the database locking + * failure results in only statement-level rollback, the provider must + * throw the {@link LockTimeoutException} (and must not mark the transaction + * for rollback). + * + * @since Java Persistence 1.0 + * */ -public enum LockModeType { - /** - * Read lock - */ - READ, +public enum LockModeType +{ + /** + * Synonymous with <code>OPTIMISTIC</code>. + * <code>OPTIMISTIC</code> is to be preferred for new + * applications. + * + */ + READ, - /** - * Write lock - */ - WRITE, + /** + * Synonymous with <code>OPTIMISTIC_FORCE_INCREMENT</code>. + * <code>OPTIMISTIC_FORCE_IMCREMENT</code> is to be preferred for new + * applications. + * + */ + WRITE, - OPTIMISTIC, + /** + * Optimistic lock. + * + * @since Java Persistence 2.0 + */ + OPTIMISTIC, - OPTIMISTIC_FORCE_INCREMENT, + /** + * Optimistic lock, with version update. + * + * @since Java Persistence 2.0 + */ + OPTIMISTIC_FORCE_INCREMENT, - PESSIMISTIC_READ, + /** + * + * Pessimistic read lock. + * + * @since Java Persistence 2.0 + */ + PESSIMISTIC_READ, - PESSIMISTIC_WRITE, + /** + * Pessimistic write lock. + * + * @since Java Persistence 2.0 + */ + PESSIMISTIC_WRITE, - PESSIMISTIC_FORCE_INCREMENT, + /** + * Pessimistic write lock, with version update. + * + * @since Java Persistence 2.0 + */ + PESSIMISTIC_FORCE_INCREMENT, - NONE + /** + * No lock. + * + * @since Java Persistence 2.0 + */ + NONE } Modified: jpa-api/trunk/src/main/java/javax/persistence/LockTimeoutException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/LockTimeoutException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/LockTimeoutException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,7 +3,80 @@ package javax.persistence; /** - * @author Hardy Ferentschik + * Thrown by the persistence provider when an pessimistic locking + * conflict occurs that does not result in transaction rollback. This + * exception may be thrown as part of an API call, at, flush or at + * commit time. The current transaction, if one is active, will be not + * be marked for rollback. + * + * @since Java Persistence 2.0 */ -public class LockTimeoutException extends RuntimeException { +public class LockTimeoutException extends PersistenceException { + /** The object that caused the exception */ + Object entity; + + /** + * Constructs a new <code>LockTimeoutException</code> exception + * with <code>null</code> as its detail message. + */ + public LockTimeoutException() { + super(); + } + + /** + * Constructs a new <code>LockTimeoutException</code> exception + * with the specified detail message. + * @param message the detail message. + */ + public LockTimeoutException(String message) { + super(message); + } + + /** + * Constructs a new <code>LockTimeoutException</code> exception + * with the specified detail message and cause. + * @param message the detail message. + * @param cause the cause. + */ + public LockTimeoutException(String message, Throwable cause) { + super(message, cause); + } + + /** + * Constructs a new <code>LockTimeoutException</code> exception + * with the specified cause. + * @param cause the cause. + */ + public LockTimeoutException(Throwable cause) { + super(cause); + } + + /** + * Constructs a new <code>LockTimeoutException</code> exception + * with the specified object. + * @param entity the entity. + */ + public LockTimeoutException(Object entity) { + this.entity = entity; + } + + /** + * Constructs a new <code>LockTimeoutException</code> exception + * with the specified detail message, cause, and entity. + * @param message the detail message. + * @param cause the cause. + * @param entity the entity. + */ + public LockTimeoutException(String message, Throwable cause, Object entity) { + super(message, cause); + this.entity = entity; + } + + /** + * Returns the object that caused this exception. + * @return the entity + */ + public Object getObject() { + return this.entity; + } } Modified: jpa-api/trunk/src/main/java/javax/persistence/ManyToMany.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ManyToMany.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/ManyToMany.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,51 +1,129 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import java.lang.annotation.Retention; -import java.lang.annotation.Target; - -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; -import static javax.persistence.FetchType.*; - -/** - * Defines a many-valued association with many-to-many multiplicity. If the Collection is - * defined using generics to specify the element type, the associated target entity class - * does not need to be specified; otherwise it must be specified. - * - * Every many-to-many association has two sides, the owning side and the non-owning, or inverse, - * side. The join table is specified on the owning side. If the association is bidirectional, - * either side may be designated as the owning side. - * - * The same annotation elements for the OneToMany annotation apply to the ManyToMany annotation. - * - * @author Emmanuel Bernard - */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) -public @interface ManyToMany { - /** - * The entity class that is the target of the association. Optional only if the - * collection property is defined using Java generics. Must be specified otherwise. - * - * Defaults to the parameterized type of the collection when defined using generics. - */ - Class targetEntity() default void.class; - /** - * The operations that must be cascaded to the target of the association. - * - * Defaults to no operations being cascaded. - */ - CascadeType[] cascade() default {}; - /** - * Whether the association should be lazily loaded or must be eagerly fetched. - * The EAGER strategy is a requirement on the persistenceprovider runtime that - * the associatedentities must be eagerly fetched. The LAZY strategy is a hint - * to the persistence provider runtime. - */ - FetchType fetch() default LAZY; - /** - * The field that owns the relationship. Required unless the relationship is unidirectional. - */ - String mappedBy() default ""; +package javax.persistence; + +import java.lang.annotation.Target; +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; +import static javax.persistence.FetchType.LAZY; + +/** + * Defines a many-valued association with many-to-many multiplicity. + * + * <p> Every many-to-many association has two sides, the owning side + * and the non-owning, or inverse, side. The join table is specified + * on the owning side. If the association is bidirectional, either + * side may be designated as the owning side. If the relationship is + * bidirectional, the non-owning side must use the <code>mappedBy</code> element of + * the <code>ManyToMany</code> annotation to specify the relationship field or + * property of the owning side. + * + * <p> The join table for the relationship, if not defaulted, is + * specified on the owning side. + * + * <p> The <code>ManyToMany</code> annotation may be used within an + * embeddable class contained within an entity class to specify a + * relationship to a collection of entities. If the relationship is + * bidirectional and the entity containing the embeddable class is the + * owner of the relationship, the non-owning side must use the + * <code>mappedBy</code> element of the <code>ManyToMany</code> + * annotation to specify the relationship field or property of the + * embeddable class. The dot (".") notation syntax must be used in the + * <code>mappedBy</code> element to indicate the relationship + * attribute within the embedded attribute. The value of each + * identifier used with the dot notation is the name of the respective + * embedded field or property. + * + * <pre> + * + * Example 1: + * + * // In Customer class: + * + * &#064;ManyToMany + * &#064;JoinTable(name="CUST_PHONES") + * public Set&#060;PhoneNumber&#062; getPhones() { return phones; } + * + * // In PhoneNumber class: + * + * &#064;ManyToMany(mappedBy="phones") + * public Set&#060;Customer&#062; getCustomers() { return customers; } + * + * Example 2: + * + * // In Customer class: + * + * &#064;ManyToMany(targetEntity=com.acme.PhoneNumber.class) + * public Set getPhones() { return phones; } + * + * // In PhoneNumber class: + * + * &#064;ManyToMany(targetEntity=com.acme.Customer.class, mappedBy="phones") + * public Set getCustomers() { return customers; } + * + * Example 3: + * + * // In Customer class: + * + * &#064;ManyToMany + * &#064;JoinTable(name="CUST_PHONE", + * joinColumns= + * &#064;JoinColumn(name="CUST_ID", referencedColumnName="ID"), + * inverseJoinColumns= + * &#064;JoinColumn(name="PHONE_ID", referencedColumnName="ID") + * ) + * public Set&#060;PhoneNumber&#062; getPhones() { return phones; } + * + * // In PhoneNumberClass: + * + * &#064;ManyToMany(mappedBy="phones") + * public Set&#060;Customer&#062; getCustomers() { return customers; } + * </pre> + * + * @see JoinTable + * + * @since Java Persistence 1.0 + */ +@Target({METHOD, FIELD}) +@Retention(RUNTIME) +public @interface ManyToMany { + + /** + * (Optional) The entity class that is the target of the + * association. Optional only if the collection-valued + * relationship property is defined using Java generics. Must be + * specified otherwise. + * + * <p> Defaults to the parameterized type of + * the collection when defined using generics. + */ + Class targetEntity() default void.class; + + /** + * (Optional) The operations that must be cascaded to the target + * of the association. + * + * <p> When the target collection is a {@link java.util.Map + * java.util.Map}, the <code>cascade</code> element applies to the + * map value. + * + * <p> Defaults to no operations being cascaded. + */ + CascadeType[] cascade() default {}; + + /** (Optional) Whether the association should be lazily loaded or + * must be eagerly fetched. The EAGER strategy is a requirement on + * the persistence provider runtime that the associated entities + * must be eagerly fetched. The LAZY strategy is a hint to the + * persistence provider runtime. + */ + FetchType fetch() default LAZY; + + /** + * The field that owns the relationship. Required unless + * the relationship is unidirectional. + */ + String mappedBy() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/ManyToOne.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ManyToOne.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/ManyToOne.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,44 +1,104 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import static javax.persistence.FetchType.EAGER; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; -import static javax.persistence.FetchType.*; - /** - * This annotation defines a single-valued association to another entity class that has - * many-to-one multiplicity. It is not normally necessary to specify the target entity - * explicitly since it can usually be inferred from the type of the object being referenced. + * Defines a single-valued association to another entity class that + * has many-to-one multiplicity. It is not normally necessary to + * specify the target entity explicitly since it can usually be + * inferred from the type of the object being referenced. If the + * relationship is bidirectional, the non-owning + * <code>OneToMany</code> entity side must used the + * <code>mappedBy</code> element to specify the relationship field or + * property of the entity that is the owner of the relationship. * - * @author Emmanuel Bernard + * <p> The <code>ManyToOne</code> annotation may be used within an + * embeddable class to specify a relationship from the embeddable + * class to an entity class. If the relationship is bidirectional, the + * non-owning <code>OneToMany</code> entity side must use the <code>mappedBy</code> + * element of the <code>OneToMany</code> annotation to specify the + * relationship field or property of the embeddable field or property + * on the owning side of the relationship. The dot (".") notation + * syntax must be used in the <code>mappedBy</code> element to indicate the + * relationship attribute within the embedded attribute. The value of + * each identifier used with the dot notation is the name of the + * respective embedded field or property. + * <pre> + * + * Example 1: + * + * &#064;ManyToOne(optional=false) + * &#064;JoinColumn(name="CUST_ID", nullable=false, updatable=false) + * public Customer getCustomer() { return customer; } + * + * + * Example 2: + * + * &#064;Entity + * public class Employee { + * &#064;Id int id; + * &#064;Embedded JobInfo jobInfo; + * ... + * } + * + * &#064;Embeddable + * public class JobInfo { + * String jobDescription; + * &#064;ManyToOne ProgramManager pm; // Bidirectional + * } + * + * &#064;Entity + * public class ProgramManager { + * &#064;Id int id; + * &#064;OneToMany(mappedBy="jobInfo.pm") + * Collection&#060;Employee&#062; manages; + * } + * + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) + public @interface ManyToOne { - /** - * The entity class that is the target of the association. - * - * Defaults to the type of the field or property that stores the association - */ - Class targetEntity() default void.class; - /** - * The operations that must be cascaded to the target of the association. - * - * By default no operations are cascaded. - */ - CascadeType[] cascade() default {}; - /** - * Whether the association should be lazily loaded or must be eagerly fetched. - * The EAGER strategy is a requirement on the persistence provider runtime that - * the associated entity must be eagerly fetched. The LAZY strategy is a hint to - * the persistence provider runtime. - */ - FetchType fetch() default EAGER; - /** - * Whether the association is optional. If set to false then a non-null relationship must always exist. - */ - boolean optional() default true; + + /** + * (Optional) The entity class that is the target of + * the association. + * + * <p> Defaults to the type of the field or property + * that stores the association. + */ + Class targetEntity() default void.class; + + /** + * (Optional) The operations that must be cascaded to + * the target of the association. + * + * <p> By default no operations are cascaded. + */ + CascadeType[] cascade() default {}; + + /** + * (Optional) Whether the association should be lazily + * loaded or must be eagerly fetched. The EAGER + * strategy is a requirement on the persistence provider runtime that + * the associated entity must be eagerly fetched. The LAZY + * strategy is a hint to the persistence provider runtime. + */ + FetchType fetch() default EAGER; + + /** + * (Optional) Whether the association is optional. If set + * to false then a non-null relationship must always exist. + */ + boolean optional() default true; } Modified: jpa-api/trunk/src/main/java/javax/persistence/MapKey.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapKey.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/MapKey.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,27 +1,86 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +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.FIELD; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; -import java.lang.annotation.Retention; /** - * Is used to specify the map key for associations of type Map. - * If a persistent field or property other than the primary key is used as a map key then it - * is expected to have a uniqueness constraint associated with it. + * Specifies the map key for associations of type + * {@link java.util.Map java.util.Map} when the map key is itself the primary + * key or a persistent field or property of the entity that is + * the value of the map. * - * @author Emmanuel Bernard + * <p> If a persistent field or property other than the primary + * key is used as a map key then it is expected to have a + * uniqueness constraint associated with it. + * + * <p> The {@link MapKeyClass} annotation is not used when + * <code>MapKey</code> is specified and vice versa. + * + * <pre> + * + * Example 1: + * + * &#064;Entity + * public class Department { + * ... + * &#064;OneToMany(mappedBy="department") + * &#064;MapKey // map key is primary key + * public Map&#060;Integer, Employee&#062; getEmployees() {... } + * ... + * } + * + * &#064;Entity + * public class Employee { + * ... + * &#064;Id Integer getEmpId() { ... } + * &#064;ManyToOne + * &#064;JoinColumn(name="dept_id") + * public Department getDepartment() { ... } + * ... + * } + * + * Example 2: + * + * &#064;Entity + * public class Department { + * ... + * &#064;OneToMany(mappedBy="department") + * &#064;MapKey(name="name") + * public Map&#060;String, Employee&#062; getEmployees() {... } + * ... + * } + * + * &#064;Entity + * public class Employee { + * &#064;Id public Integer getEmpId() { ... } + * ... + * &#064;ManyToOne + * &#064;JoinColumn(name="dept_id") + * public Department getDepartment() { ... } + * ... + * } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) public @interface MapKey { - /** - * The name of the persistent field or property of the associated entity that is used as the map key. - * If the name element is not specified, the primary key of the associated entity is used as the map key. - * If the primary key is a composite primary key and is mapped as IdClass, an instance of the primary key - * class is used as the key. - */ - String name() default ""; + + /** + * (Optional) The name of the persistent field or property of the + * associated entity that is used as the map key. + * <p> Default: If the + * <code>name</code> element is not specified, the primary key of the + * associated entity is used as the map key. If the + * primary key is a composite primary key and is mapped + * as <code>IdClass</code>, an instance of the primary key + * class is used as the key. + */ + String name() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/MapKeyClass.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapKeyClass.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/MapKeyClass.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,17 +2,85 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * @author Hardy Ferentschik + * Specifies the type of the map key for associations of type + * <code>java.util.Map</code>. The map key can be a basic type, an + * embeddable class, or an entity. If the map is specified using Java + * generics, the <code>MapKeyClass</code> annotation and associated + * type need not be specified; otherwise they must be specified. + * + * <p> The <code>MapKeyClass</code> annotation is used in conjunction + * with <code>ElementCollection</code> or one of the collection-valued + * relationship annotations (<code>OneToMany</code> or <code>ManyToMany</code>). + * The <code>MapKey</code> annotation is not used when + * <code>MapKeyClass</code> is specified and vice versa. + * + * <pre> + * + * Example 1: + * + * &#064;Entity + * public class Item { + * &#064;Id int id; + * ... + * &#064;ElementCollection(targetClass=String.class) + * &#064;MapKeyClass(String.class) + * Map images; // map from image name to image filename + * ... + * } + * + * Example 2: + * + * // MapKeyClass and target type of relationship can be defaulted + * + * &#064;Entity + * public class Item { + * &#064;Id int id; + * ... + * &#064;ElementCollection + * Map&#060;String, String&#062; images; + * ... + * } + * + * Example 3: + * + * &#064;Entity + * public class Company { + * &#064;Id int id; + * ... + * &#064;OneToMany(targetEntity=com.example.VicePresident.class) + * &#064;MapKeyClass(com.example.Division.class) + * Map organization; + * } + * + * Example 4: + * + * // MapKeyClass and target type of relationship are defaulted + * + * &#064;Entity + * public class Company { + * &#064;Id int id; + * ... + * &#064;OneToMany + * Map&#060;Division, VicePresident&#062; organization; + * } + * + * </pre> + * @see ElementCollection + * @see OneToMany + * @see ManyToMany + * @since Java Persistence 2.0 */ -@Target({ METHOD, FIELD }) + +@Target( { METHOD, FIELD }) @Retention(RUNTIME) public @interface MapKeyClass { + /**(Required) The type of the map key.*/ Class value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/MapKeyColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapKeyColumn.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/MapKeyColumn.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,35 +2,118 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * @author Hardy Ferentschik + * Specifies the mapping for the key column of a map whose + * map key is a basic type. If the <code>name</code> element is not specified, it + * defaults to the concatenation of the following: the name of the + * referencing relationship field or property; "_"; "KEY". + * + * <pre> + * Example: + * + * &#064;Entity + * public class Item { + * &#064;Id int id; + * ... + * &#064;ElementCollection + * &#064;MapKeyColumn(name="IMAGE_NAME") + * &#064;Column(name="IMAGE_FILENAME") + * &#064;CollectionTable(name="IMAGE_MAPPING") + * Map&#060;String, String&#062; images; // map from image name to filename + * ... + * } + * </pre> + * @since Java Persistence 2.0 */ -@Target({ METHOD, FIELD }) +@Target( { METHOD, FIELD }) @Retention(RUNTIME) public @interface MapKeyColumn { + + /** + * (Optional) The name of the map key column. The table in which it is found + * depends upon the context. If the map key is for an element collection, + * the map key column is in the collection table for the map value. If the + * map key is for a ManyToMany entity relationship or for a OneToMany entity + * relationship using a join table, the map key column is in a join table. + * If the map key is for a OneToMany entity relationship using a foreign key + * mapping strategy, the map key column is in the table of the entity that + * is the value of the map. + * <p> Defaults to the concatenation of the following: the name of + * the referencing relationship field or property; "_"; "<code>KEY</code>". + */ String name() default ""; + /** + * (Optional) Whether the column is a unique key. This is a + * shortcut for the <code>UniqueConstraint</code> annotation + * at the table level and is useful for when the unique key + * constraint corresponds to only a single column. This + * constraint applies in addition to any constraint entailed + * by primary key mapping and to constraints specified at the + * table level. + */ boolean unique() default false; + /** (Optional) Whether the database column is nullable. */ boolean nullable() default false; + /** + * (Optional) Whether the column is included in SQL INSERT statements + * generated by the persistence provider. + */ boolean insertable() default true; + /** + * (Optional) Whether the column is included in SQL UPDATE statements + * generated by the persistence provider. + */ boolean updatable() default true; + /** + * (Optional) The SQL fragment that is used when generating the DDL for the + * column. + * <p> Defaults to the generated SQL to create a + * column of the inferred type. + * + */ String columnDefinition() default ""; + /** (Optional) The name of the table that contains the column. + * + * <p> Defaults: If the map key is for an element collection, + * the name of the collection table for the map value. If the + * map key is for a OneToMany or ManyToMany entity + * relationship using a join table, the name of the join table + * for the map. If the map key is for a OneToMany entity + * relationship using a foreign key mapping strategy, the name + * of the primary table of the entity that is the value of the + * map. + */ String table() default ""; + /** + * (Optional) The column length. (Applies only if a string-valued column is + * used.) + */ int length() default 255; + /** + * (Optional) The precision for a decimal (exact numeric) column. (Applies + * only if a decimal column is used.) + * + *<p> Default: 0. (The value must be set by the developer.) + */ int precision() default 0; // decimal precision + /** + * (Optional) The scale for a decimal (exact numeric) column. (Applies only + * if a decimal column is used.) + */ int scale() default 0; // decimal scale } Added: jpa-api/trunk/src/main/java/javax/persistence/MapKeyEnumerated.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapKeyEnumerated.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/MapKeyEnumerated.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -0,0 +1,52 @@ +// $Id: $ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Target; +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; +import static javax.persistence.EnumType.ORDINAL; + +/** + * Specifies the enum type for a map key whose basic type is an enumerated type. + * + * The <code>MapKeyEnumerated</code> annotation can be applied to an + * element collection or relationship of type <code>java.util.Map</code>, in + * conjunction with the <code>ElementCollection</code>, <code>OneToMany</code>, or + * <code>ManyToMany</code> annotation. + * If the enumerated type is not specified or the <code>MapKeyEnumerated</code> + * annotation is not used, the enumerated type is assumed to be + * <code>ORDINAL</code>. + * + * <pre> + * Example: + * + * public enum ProjectStatus {COMPLETE, DELAYED, CANCELLED, IN_PROGRESS} + * + * public enum SalaryRate {JUNIOR, SENIOR, MANAGER, EXECUTIVE} + * + * &#064;Entity public class Employee { + * &#064;ManyToMany + * public Projects&#060;ProjectStatus, Project&#062; getProjects() {...} + * + * &#064;OneToMany + * &#064;MapKeyEnumerated(STRING) + * public Map&#060;SalaryRate, Employee&#062; getEmployees() {...} + * ... + * } + * </pre> + * + * @see ElementCollection + * @see OneToMany + * @see ManyToMany + * + * @since Java Persistence 2.0 + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface MapKeyEnumerated { + + /** (Optional) The type used in mapping a map key enum type. */ + EnumType value() default ORDINAL; +} Modified: jpa-api/trunk/src/main/java/javax/persistence/MapKeyJoinColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapKeyJoinColumn.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/MapKeyJoinColumn.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,31 +2,167 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * @author Hardy Ferentschik + * Specifies a mapping to an entity that is a map key. The map key + * join column is in the collection table, join table, or table of the + * target entity that is used to represent the map. If no + * <code>MapKeyJoinColumn</code> annotation is specified, a single + * join column is assumed and the default values apply. + * + * <pre> + * + * Example 1: + * + * &#064;Entity + * public class Company { + * &#064;Id int id; + * ... + * &#064;OneToMany // unidirectional + * &#064;JoinTable(name="COMPANY_ORGANIZATION", + * joinColumns=&#064;JoinColumn(name="COMPANY"), + * inverseJoinColumns=&#064;JoinColumn(name="VICEPRESIDENT")) + * &#064;MapKeyJoinColumn(name="DIVISION") + * Map&#060;Division, VicePresident&#062; organization; + * } + * + * Example 2: + * + * &#064;Entity + * public class VideoStore { + * &#064;Id int id; + * String name; + * Address location; + * ... + * &#064;ElementCollection + * &#064;CollectionTable(name="INVENTORY", + * joinColumns=&#064;JoinColumn(name="STORE")) + * &#064;Column(name="COPIES_IN_STOCK") + * &#064;MapKeyJoinColumn(name="MOVIE", referencedColumnName="ID") + * Map&#060;Movie, Integer&#062; videoInventory; + * ... + * } + * + * &#064;Entity + * public class Movie { + * &#064;Id long id; + * String title; + * ... + * } + * + * Example 3: + * + * &#064;Entity + * public class Student { + * &#064;Id int studentId; + * ... + * &#064;ManyToMany // students and courses are also many-many + * &#064;JoinTable(name="ENROLLMENTS", + * joinColumns=&#064;JoinColumn(name="STUDENT"), + * inverseJoinColumns=&#064;JoinColumn(name="SEMESTER")) + * &#064;MapKeyJoinColumn(name="COURSE") + * Map&#060;Course, Semester&#062; enrollment; + * ... + * } + * </pre> + * + * @since Java Persistence 2.0 */ -@Target({ METHOD, FIELD }) +@Target( { METHOD, FIELD }) @Retention(RUNTIME) public @interface MapKeyJoinColumn { + /** + * (Optional) The name of the foreign key column for the map + * key. The table in which it is found depends upon the + * context. + * <ul> + * <li> If the join is for a map key for an + * element collection, the foreign key column is in the + * collection table for the map value. + * <li> If the join is for a map key for a ManyToMany entity + * relationship or for a OneToMany entity relationship + * using a join table, the foreign key column is in a join table. + * <li> If the join is for a OneToMany entity relationship using + * a foreign key mapping strategy, the foreign key column for the + * map key is in the table of the entity that is the value of the map. + * </ul> + * + * <p> Default (only applies if a single join column is used.) + * The concatenation of the following: the name of the + * referencing relationship property or field of the + * referencing entity or embeddable class; "_"; "KEY". + */ String name() default ""; + /** + * (Optional) The name of the column referenced by this foreign key column. + * The referenced column is in the table of the target entity. + * + * <p> Default (only applies if single join column is being + * used.) The same name as the primary key column of the + * referenced table + */ String referencedColumnName() default ""; + /** + * (Optional) Whether the property is a unique key. This is a + * shortcut for the <code>UniqueConstraint</code> annotation + * at the table level and is useful for when the unique key + * constraint is only a single field. + */ boolean unique() default false; + /** + * (Optional) Whether the foreign key column is nullable. + */ boolean nullable() default false; + /** + * (Optional) Whether the column is included in SQL INSERT statements + * generated by the persistence provider. + */ boolean insertable() default true; + /** + * (Optional) Whether the column is included in SQL UPDATE statements + * generated by the persistence provider. + */ boolean updatable() default true; + /** + * (Optional) The SQL fragment that is used when generating the DDL for the + * column. + * Defaults to SQL generated by the provider for the column. + */ String columnDefinition() default ""; + /** + * (Optional) The name of the table that contains the foreign key column. + * <ul> + * <li> If the join is for a map key for an element collection, the foreign key + * column is in the collection table for the map value. + * <li> If the join is for a map key for a ManyToMany entity relationship + * or for a OneToMany entity relationship using a join table, + * the foreign key column is in a join table. + * <li> If the join is for a OneToMany entity relationship using a foreign + * key mapping strategy, the foreign key column for the map key is in the + * table of the entity that is the value of the map. + * </ul> + * <p> Default: + * <ul> + * <li> If the map is for an element collection, the + * name of the collection table for the map value. + * <li> If the map is for a OneToMany or ManyToMany entity relationship + * using a join table, the name of the join table for the map. + * <li> If the map is for a OneToMany entity relationship using a + * foreign key mapping strategy, the name of the primary table + * of the entity that is the value of the map. + * </ul> + */ String table() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/MapKeyJoinColumns.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapKeyJoinColumns.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/MapKeyJoinColumns.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,17 +2,31 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * @author Hardy Ferentschik + * Supports composite map keys that reference entities. + * <p> The <code>MapKeyJoinColumns</code> annotation groups + * <code>MapKeyJoinColumn</code> annotations. When the + * <code>MapKeyJoinColumns</code> annotation is used, both the + * <code>name</code> and the <code>referencedColumnName</code> + * elements must be specified in each of the grouped + * <code>MapKeyJoinColumn</code> annotations. + * + * @see MapKeyJoinColumn + * + * @since Java Persistence 2.0 */ -@Target({ METHOD, FIELD }) +@Target( { METHOD, FIELD }) @Retention(RUNTIME) public @interface MapKeyJoinColumns { + /** + * (Required) The map key join columns that are used to map to the entity + * that is the map key. + */ MapKeyJoinColumn[] value(); } Added: jpa-api/trunk/src/main/java/javax/persistence/MapKeyTemporal.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapKeyTemporal.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/MapKeyTemporal.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -0,0 +1,40 @@ +// $Id: $ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Target; +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; + +/** + * This annotation must be specified for persistent map keys of type + * {@link java.util.Date} and {@link java.util.Calendar}. It may only be + * specified for map keys of these types. + * + * <p> The <code>MapKeyTemporal</code> annotation can be applied to an + * element collection or relationship of type <code>java.util.Map</code> + * in conjunction with the <code>ElementCollection</code>, + * <code>OneToMany</code>, or <code>ManyToMany</code> annotation. + * + * <pre> + * Example: + * + * &#064;OneToMany + * &#064;MapKeyTemporal(DATE) + * protected java.util.Map&#060;java.util.Date, Employee&#062; employees; + * </pre> + * + * @since Java Persistence 2.0 + */ +@Target({METHOD, FIELD}) +@Retention(RUNTIME) +public @interface MapKeyTemporal { + + /** (Required) The type used in mapping + * <code>java.util.Date</code> or + * <code>java.util.Calendar</code>. + */ + TemporalType value(); +} Deleted: jpa-api/trunk/src/main/java/javax/persistence/MappedById.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MappedById.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/MappedById.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,18 +0,0 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import static java.lang.annotation.ElementType.FIELD; -import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; -import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; - -/** - * @author Hardy Ferentschik - */ -@Target({ METHOD, FIELD }) -@Retention(RUNTIME) -public @interface MappedById { - String value() default ""; -} Modified: jpa-api/trunk/src/main/java/javax/persistence/MappedSuperclass.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MappedSuperclass.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/MappedSuperclass.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,25 +1,87 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import java.lang.annotation.Documented; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * Designates a class whose mapping information is applied to the entities that inherit - * from it. A mapped superclass has no separate table defined for it. + * Designates a class whose mapping information is applied + * to the entities that inherit from it. A mapped superclass + * has no separate table defined for it. * - * A class designated with the MappedSuperclass annotation can be mapped in the same way as - * an entity except that the mappings will apply only to its subclasses since no table exists - * for the mapped superclass itself. When applied to the subclasses the inherited mappings will - * apply in the context of the subclass tables. Mapping information may be overridden in such - * subclasses by using the AttributeOverride and AssociationOverride annotations or corresponding * - * XML elements. - * - * @author Emmanuel Bernard + * <p> A class designated with the <code>MappedSuperclass</code> + * annotation can be mapped in the same way as an entity except that the + * mappings will apply only to its subclasses since no table + * exists for the mapped superclass itself. When applied to the + * subclasses the inherited mappings will apply in the context + * of the subclass tables. Mapping information may be overridden + * in such subclasses by using the <code>AttributeOverride</code> and + * <code>AssociationOverride</code> annotations or corresponding XML elements. + * + * <pre> + * Example: Concrete class as a mapped superclass + * + * &#064;MappedSuperclass + * public class Employee { + * + * &#064;Id protected Integer empId; + * &#064;Version protected Integer version; + * &#064;ManyToOne &#064;JoinColumn(name="ADDR") + * protected Address address; + * + * public Integer getEmpId() { ... } + * public void setEmpId(Integer id) { ... } + * public Address getAddress() { ... } + * public void setAddress(Address addr) { ... } + * } + * + * // Default table is FTEMPLOYEE table + * &#064;Entity + * public class FTEmployee extends Employee { + * + * // Inherited empId field mapped to FTEMPLOYEE.EMPID + * // Inherited version field mapped to FTEMPLOYEE.VERSION + * // Inherited address field mapped to FTEMPLOYEE.ADDR fk + * + * // Defaults to FTEMPLOYEE.SALARY + * protected Integer salary; + * + * public FTEmployee() {} + * + * public Integer getSalary() { ... } + * + * public void setSalary(Integer salary) { ... } + * } + * + * &#064;Entity &#064;Table(name="PT_EMP") + * &#064;AssociationOverride( + * name="address", + * joincolumns=&#064;JoinColumn(name="ADDR_ID")) + * public class PartTimeEmployee extends Employee { + * + * // Inherited empId field mapped to PT_EMP.EMPID + * // Inherited version field mapped to PT_EMP.VERSION + * // address field mapping overridden to PT_EMP.ADDR_ID fk + * &#064;Column(name="WAGE") + * protected Float hourlyWage; + * + * public PartTimeEmployee() {} + * + * public Float getHourlyWage() { ... } + * public void setHourlyWage(Float wage) { ... } + * } + * </pre> + * + * @see AttributeOverride + * @see AssociationOverride + * @since Java Persistence 1.0 */ -@Target(TYPE) @Retention(RUNTIME) -public @interface MappedSuperclass {} +@Documented +@Target({TYPE}) +@Retention(RUNTIME) +public @interface MappedSuperclass { +} Added: jpa-api/trunk/src/main/java/javax/persistence/MapsId.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapsId.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/MapsId.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -0,0 +1,64 @@ +// $Id: $ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Target; +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; + +/** + * Designates a <code>ManyToOne</code> or + * <code>OneToOne</code> relationship attribute that provides the + * mapping for an {@link EmbeddedId} primary key, an attribute within + * an <code>EmbeddedId</code> primary key, or a simple primary key of + * the parent entity. The <code>value</code> element specifies the + * attribute within a composite key to which the relationship + * attribute corresponds. If the entity's primary key is of the same + * Java type as the primary key of the entity referenced by the + * relationship, the value attribute is not specified. + * + * <pre> + * Example: + * + * // parent entity has simple primary key + * + * &#064;Entity + * public class Employee { + * &#064;Id long empId; + * String name; + * ... + * } + * + * // dependent entity uses EmbeddedId for composite key + * + * &#064;Embeddable + * public class DependentId { + * String name; + * long empid; // corresponds to primary key type of Employee + * } + * + * &#064;Entity + * public class Dependent { + * &#064;EmbeddedId DependentId id; + * ... + * &#064;MapsId("empid") // maps the empid attribute of embedded id + * &#064;ManyToOne Employee emp; + * } + * </pre> + * + * @since Java Persistence 2.0 + */ +@Target( { METHOD, FIELD }) +@Retention(RUNTIME) +public @interface MapsId { + + /** + * (Optional) The name of the attribute within the composite key + * to which the relationship attribute corresponds. If not + * supplied, the relationship maps the entity’s primary + * key. + */ + String value() default ""; +} Modified: jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQueries.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQueries.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQueries.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,21 +1,25 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.TYPE; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * Is used to specify an array of native SQL named queries. Query names are scoped to the persistence unit + * Used to specify multiple native SQL named queries. Query names + * are scoped to the persistence unit. The <code>NamedNativeQueries</code> + * annotation can be applied to an entity or mapped superclass. * - * @author Emmanuel Bernard + * @see NamedNativeQuery + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) public @interface NamedNativeQueries { - /** - * Array of native SQL named queries - */ - NamedNativeQuery [] value (); + + /** (Required) Array of <code>NamedNativeQuery</code> annotations. */ + NamedNativeQuery[] value (); } Modified: jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQuery.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQuery.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,39 +1,39 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import static java.lang.annotation.ElementType.*; +import java.lang.annotation.Target; import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * Is used to specify a native SQL named query. Query names are scoped to the persistence unit. + * Specifies a named native SQL query. + * Query names are scoped to the persistence unit. + * The <code>NamedNativeQuery</code> annotation can be applied to an + * entity or mapped superclass. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ @Target({TYPE}) @Retention(RUNTIME) public @interface NamedNativeQuery { - /** - * Is used to refer to the query when using the EntityManager methods that create query objects - */ - String name(); - /** - * The SQL query string - */ - String query(); - /** - * Vendor-specific query hints - */ - QueryHint[] hints() default {}; - /** - * The class of the result - */ - Class resultClass() default void.class; - /** - * The name of a SqlResultSetMapping, as defined in metadata - */ - String resultSetMapping() default ""; // name of SQLResultSetMapping + /** + * The name used to refer to the query with the {@link EntityManager} + * methods that create query objects. + */ + String name(); + + /** The SQL query string. */ + String query(); + + /** Query properties and hints. (May include vendor-specific query hints.) */ + QueryHint[] hints() default {}; + + /** The class of the result. */ + Class resultClass() default void.class; + + /** The name of a {@link SqlResultSetMapping}, as defined in metadata. */ + String resultSetMapping() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/NamedQueries.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NamedQueries.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/NamedQueries.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,21 +1,25 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.TYPE; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * Specifies an array of named Java Persistence query language queries. Query names are scoped to the persistence unit. + * Specifies multiple named Java Persistence query language queries. + * Query names are scoped to the persistence unit. + * The <code>NamedQueries</code> annotation can be applied to an entity or mapped superclass. * - * @author Emmanuel Bernard + * @see NamedQuery + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) public @interface NamedQueries { - /** - * An array of named Java Persistence query language queries. - */ - NamedQuery [] value (); + + /** (Required) An array of <code>NamedQuery</code> annotations. */ + NamedQuery [] value (); } Modified: jpa-api/trunk/src/main/java/javax/persistence/NamedQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NamedQuery.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/NamedQuery.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,31 +1,66 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; -import static java.lang.annotation.RetentionPolicy.*; -import static java.lang.annotation.ElementType.*; +import static javax.persistence.LockModeType.NONE; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Is used to specify a named query in the Java Persistence query language, which is a static - * query expressed in metadata. Query names are scoped to the persistence unit. + * Specifies a static, named query in the Java Persistence query language. + * Query names are scoped to the persistence unit. + * The <code>NamedQuery</code> annotation can be applied to an entity or mapped superclass. * - * @author Emmanuel Bernard + * <p> The following is an example of the definition of a named query + * in the Java Persistence query language: + * + * <pre> + * &#064;NamedQuery( + * name="findAllCustomersWithName", + * query="SELECT c FROM Customer c WHERE c.name LIKE :custName" + * ) + * </pre> + * + * <p> The following is an example of the use of a named query: + * + * <pre> + * &#064;PersistenceContext + * public EntityManager em; + * ... + * customers = em.createNamedQuery("findAllCustomersWithName") + * .setParameter("custName", "Smith") + * .getResultList(); + * </pre> + * + * @since Java Persistence 1.0 */ -//TODO remove the mackage target -@Target({TYPE}) @Retention(RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) public @interface NamedQuery { - /** - * Refers to the query when using the EntityManager methods that create query objects. - */ - String name(); - /** - * The query string in the Java Persistence query language - */ - String query(); - /** - * Vendor-specific query hints - */ - QueryHint[] hints() default {}; + + /** + * (Required) The name used to refer to the query with the {@link EntityManager} + * methods that create query objects. + */ + String name(); + + /** (Required) + * The query string in the Java Persistence query language. + */ + String query(); + + /** + * (Optional) The lock mode type to use in query execution. If a <code>lockMode</code> + * other than <code>LockModeType.NONE</code> is specified, the query must be executed in + * a transaction. + * @since Java Persistence 2.0 + */ + LockModeType lockMode() default NONE; + + /** (Optional) Query properties and hints. May include + * vendor-specific query hints. + */ + QueryHint[] hints() default {}; } Modified: jpa-api/trunk/src/main/java/javax/persistence/NoResultException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NoResultException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/NoResultException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,28 +1,38 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Thrown by the persistence provider when getSingleResult() is executed on a query and there is no result to return. - * This exception will not cause the current transaction, if one is active, to be marked for roll back. - * - * @author Emmanuel Bernard + * Thrown by the persistence provider when {@link + * Query#getSingleResult Query.getSingleResult()} or {@link + * TypedQuery#getSingleResult TypedQuery.getSingleResult()}is executed on a query + * and there is no result to return. This exception will not cause + * the current transaction, if one is active, to be marked for + * rollback. + * + * @see Query#getSingleResult() + * @see TypedQuery#getSingleResult() + * + * @since Java Persistence 1.0 */ public class NoResultException extends PersistenceException { /** - * Constructs a new NoResultException exception with null as its detail message + * Constructs a new <code>NoResultException</code> exception with + * <code>null</code> as its detail message. */ public NoResultException() { super(); } /** - * Constructs a new NoResultException exception with the specified detail message. - * + * Constructs a new <code>NoResultException</code> exception with the + * specified detail message. + * * @param message + * the detail message. */ public NoResultException(String message) { - super( message ); + super(message); } } Modified: jpa-api/trunk/src/main/java/javax/persistence/NonUniqueResultException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NonUniqueResultException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/NonUniqueResultException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,30 +1,36 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Thrown by the persistence provider when getSingleResult() is executed on a query and there is more than - * one result from the query. This exception will not cause the current transaction, if one is active, to be - * marked for roll back. + * Thrown by the persistence provider when {@link + * Query#getSingleResult Query.getSingleResult()} or {@link + * TypedQuery#getSingleResult TypedQuery.getSingleResult()} is executed on a + * query and there is more than one result from the query. This + * exception will not cause the current transaction, if one is active, + * to be marked for rollback. * - * @author Gavin King + * @see Query#getSingleResult() + * @see TypedQuery#getSingleResult() + * + * @since Java Persistence 1.0 */ public class NonUniqueResultException extends PersistenceException { - /** - * Constructs a new NonUniqueResultException exception with null as its detail message - */ + /** + * Constructs a new <code>NonUniqueResultException</code> exception + * with <code>null</code> as its detail message. + */ public NonUniqueResultException() { super(); } - /** - * Constructs a new NonUniqueResultException exception with the specified detail message - * - * @param message - */ + /** + * Constructs a new <code>NonUniqueResultException</code> exception + * with the specified detail message. + * @param message the detail message. + */ public NonUniqueResultException(String message) { - super( message ); + super(message); } - } Modified: jpa-api/trunk/src/main/java/javax/persistence/OneToMany.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OneToMany.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/OneToMany.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,47 +1,122 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import static javax.persistence.FetchType.LAZY; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; -import static javax.persistence.FetchType.*; - /** * Defines a many-valued association with one-to-many multiplicity. + * + * <p> If the collection is defined using generics to specify the + * element type, the associated target entity type need not be + * specified; otherwise the target entity class must be specified. + * If the relationship is bidirectional, the + * <code> mappedBy</code> element must be used to specify the relationship field or + * property of the entity that is the owner of the relationship. * - * If the collection is defined using generics to specify the element type, - * the associated target entity type need not be specified; otherwise the target - * entity class must be specified. + * <p> The <code>OneToMany</code> annotation may be used within an embeddable class + * contained within an entity class to specify a relationship to a + * collection of entities. If the relationship is bidirectional, the + * <code> mappedBy</code> element must be used to specify the relationship field or + * property of the entity that is the owner of the relationship. * - * @author Emmanuel Bernard + * When the collection is a <code>java.util.Map</code>, the <code>cascade</code> + * element and the <code>orphanRemoval</code> element apply to the map value. + * + * <pre> + * + * Example 1: One-to-Many association using generics + * + * // In Customer class: + * + * &#064;OneToMany(cascade=ALL, mappedBy="customer") + * public Set&#060;Order&#062; getOrders() { return orders; } + * + * In Order class: + * + * &#064;ManyToOne + * &#064;JoinColumn(name="CUST_ID", nullable=false) + * public Customer getCustomer() { return customer; } + * + * + * Example 2: One-to-Many association without using generics + * + * // In Customer class: + * + * &#064;OneToMany(targetEntity=com.acme.Order.class, cascade=ALL, + * mappedBy="customer") + * public Set getOrders() { return orders; } + * + * // In Order class: + * + * &#064;ManyToOne + * &#064;JoinColumn(name="CUST_ID", nullable=false) + * public Customer getCustomer() { return customer; } + * + * + * Example 3: Unidirectional One-to-Many association using a foreign key mapping + * + * // In Customer class: + * + * &#064;OneToMany(orphanRemoval=true) + * &#064;JoinColumn(name="CUST_ID") // join column is in table for Order + * public Set&#060;Order&#062; getOrders() {return orders;} + * + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) + public @interface OneToMany { - /** - * The entity class that is the target of the association. Optional only if the collection - * property is defined using Java generics. Must be specified otherwise. - * - * Defaults to the parameterized type of the collection when defined using generics. - */ - Class targetEntity() default void.class; - /** - * The operations that must be cascaded to the target of the association. - * - * Defaults to no operations being cascaded. - */ - CascadeType[] cascade() default {}; - /** - * Whether the association should be lazily loaded or must be eagerly fetched. - * The EAGER strategy is a requirement on the persistenceprovider runtime that the - * associatedentities must be eagerly fetched. The LAZY strategy is a hint to the - * persistence provider runtime. - */ - FetchType fetch() default LAZY; - /** - * The field that owns the relationship. Required unless the relationship is unidirectional. - */ - String mappedBy() default ""; + + /** + * (Optional) The entity class that is the target + * of the association. Optional only if the collection + * property is defined using Java generics. + * Must be specified otherwise. + * + * <p> Defaults to the parameterized type of + * the collection when defined using generics. + */ + Class targetEntity() default void.class; + + /** + * (Optional) The operations that must be cascaded to + * the target of the association. + * <p> Defaults to no operations being cascaded. + * + * <p> When the target collection is a {@link java.util.Map + * java.util.Map}, the <code>cascade</code> element applies to the + * map value. + */ + CascadeType[] cascade() default {}; + + /** (Optional) Whether the association should be lazily loaded or + * must be eagerly fetched. The EAGER strategy is a requirement on + * the persistence provider runtime that the associated entities + * must be eagerly fetched. The LAZY strategy is a hint to the + * persistence provider runtime. + */ + FetchType fetch() default LAZY; + + /** + * The field that owns the relationship. Required unless + * the relationship is unidirectional. + */ + String mappedBy() default ""; + + /** + * (Optional) Whether to apply the remove operation to entities that have + * been removed from the relationship and to cascade the remove operation to + * those entities. + * @since Java Persistence 2.0 + */ + boolean orphanRemoval() default false; } Modified: jpa-api/trunk/src/main/java/javax/persistence/OneToOne.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OneToOne.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/OneToOne.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,51 +1,150 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import static javax.persistence.FetchType.EAGER; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; -import static javax.persistence.FetchType.*; - /** - * This annotation defines a single-valued association to another entity that has - * one-to-one multiplicity. It is not normally necessary to specify the associated - * target entity explicitly since it can usually be inferred from the type of the object - * being referenced. + * Defines a single-valued association to another entity that has + * one-to-one multiplicity. It is not normally necessary to specify + * the associated target entity explicitly since it can usually be + * inferred from the type of the object being referenced. If the relationship is + * bidirectional, the non-owning side must use the <code>mappedBy</code> element of + * the <code>OneToOne</code> annotation to specify the relationship field or + * property of the owning side. * - * @author Emmanuel Bernard + * <p> The <code>OneToOne</code> annotation may be used within an + * embeddable class to specify a relationship from the embeddable + * class to an entity class. If the relationship is bidirectional and + * the entity containing the embeddable class is on the owning side of + * the relationship, the non-owning side must use the + * <code>mappedBy</code> element of the <code>OneToOne</code> + * annotation to specify the relationship field or property of the + * embeddable class. The dot (".") notation syntax must be used in the + * <code>mappedBy</code> element to indicate the relationship attribute within the + * embedded attribute. The value of each identifier used with the dot + * notation is the name of the respective embedded field or property. + * + * <pre> + * Example 1: One-to-one association that maps a foreign key column + * + * // On Customer class: + * + * &#064;OneToOne(optional=false) + * &#064;JoinColumn( + * name="CUSTREC_ID", unique=true, nullable=false, updatable=false) + * public CustomerRecord getCustomerRecord() { return customerRecord; } + * + * // On CustomerRecord class: + * + * &#064;OneToOne(optional=false, mappedBy="customerRecord") + * public Customer getCustomer() { return customer; } + * + * + * Example 2: One-to-one association that assumes both the source and target share the same primary key values. + * + * // On Employee class: + * + * &#064;Entity + * public class Employee { + * &#064;Id Integer id; + * + * &#064;OneToOne &#064;MapsId + * EmployeeInfo info; + * ... + * } + * + * // On EmployeeInfo class: + * + * &#064;Entity + * public class EmployeeInfo { + * &#064;Id Integer id; + * ... + * } + * + * + * Example 3: One-to-one association from an embeddable class to another entity. + * + * &#064;Entity + * public class Employee { + * &#064;Id int id; + * &#064;Embedded LocationDetails location; + * ... + * } + * + * &#064;Embeddable + * public class LocationDetails { + * int officeNumber; + * &#064;OneToOne ParkingSpot parkingSpot; + * ... + * } + * + * &#064;Entity + * public class ParkingSpot { + * &#064;Id int id; + * String garage; + * &#064;OneToOne(mappedBy="location.parkingSpot") Employee assignedTo; + * ... + * } + * + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) + public @interface OneToOne { - /** - * The entity class that is the target of the association. - * - * Defaults to the type of the field or property that stores the association. - */ - Class targetEntity() default void.class; - /** - * The operations that must be cascaded to the target of the association. - * - * By default no operations are cascaded. - */ - CascadeType[] cascade() default {}; - /** - * Whether the association should be lazily loaded or must be eagerly fetched. - * The EAGER strategy is a requirement on the persistence provider runtime that - * the associated entity must be eagerly fetched. The LAZY strategy is a hint to - * the persistence provider runtime. - */ - FetchType fetch() default EAGER; - /** - * Whether the association is optional. If set to false then a non-null relationship must - * always exist. - */ - boolean optional() default true; - /** - * The field that owns the relationship. This element is only specified on the - * inverse (non-owning) side of the association. - */ - String mappedBy() default ""; + + /** + * (Optional) The entity class that is the target of + * the association. + * + * <p> Defaults to the type of the field or property + * that stores the association. + */ + Class targetEntity() default void.class; + + /** + * (Optional) The operations that must be cascaded to + * the target of the association. + * + * <p> By default no operations are cascaded. + */ + CascadeType[] cascade() default {}; + + /** + * (Optional) Whether the association should be lazily + * loaded or must be eagerly fetched. The EAGER + * strategy is a requirement on the persistence provider runtime that + * the associated entity must be eagerly fetched. The LAZY + * strategy is a hint to the persistence provider runtime. + */ + FetchType fetch() default EAGER; + + /** + * (Optional) Whether the association is optional. If set + * to false then a non-null relationship must always exist. + */ + boolean optional() default true; + + /** (Optional) The field that owns the relationship. This + * element is only specified on the inverse (non-owning) + * side of the association. + */ + String mappedBy() default ""; + + + /** + * (Optional) Whether to apply the remove operation to entities that have + * been removed from the relationship and to cascade the remove operation to + * those entities. + * @since Java Persistence 2.0 + */ + boolean orphanRemoval() default false; } Modified: jpa-api/trunk/src/main/java/javax/persistence/OptimisticLockException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OptimisticLockException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/OptimisticLockException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,43 +1,105 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; + /** - * Thrown by the persistence provider when an optimistic locking conflict occurs. - * This exception may be thrown as part of an API call, a flush or at commit time. - * The current transaction, if one is active, will be marked for rollback. + * Thrown by the persistence provider when an optimistic locking conflict + * occurs. This exception may be thrown as part of an API call, a flush or at + * commit time. The current transaction, if one is active, will be marked for + * rollback. * - * @author Emmanuel Bernard + * @see EntityManager#find(Class, Object, LockModeType) + * @see EntityManager#find(Class, Object, LockModeType, java.util.Map) + * @see EntityManager#lock(Object, LockModeType) + * @see EntityManager#lock(Object, LockModeType, java.util.Map) + * + * @since Java Persistence 1.0 */ public class OptimisticLockException extends PersistenceException { - private Object entity; + /** + * The object that caused the exception + */ + Object entity; + + /** + * Constructs a new <code>OptimisticLockException</code> exception with + * <code>null</code> as its detail message. + */ public OptimisticLockException() { super(); } - public OptimisticLockException(Object entity) { - this.entity = entity; + /** + * Constructs a new <code>OptimisticLockException</code> exception with the + * specified detail message. + * + * @param message + * the detail message. + */ + public OptimisticLockException(String message) { + super(message); } - public OptimisticLockException(Throwable cause) { - super( cause ); + /** + * Constructs a new <code>OptimisticLockException</code> exception with the + * specified detail message and cause. + * + * @param message + * the detail message. + * @param cause + * the cause. + */ + public OptimisticLockException(String message, Throwable cause) { + super(message, cause); } - public OptimisticLockException(String message) { - super( message ); + /** + * Constructs a new <code>OptimisticLockException</code> exception with the + * specified cause. + * + * @param cause + * the cause. + */ + public OptimisticLockException(Throwable cause) { + super(cause); } - public OptimisticLockException(String message, Throwable cause) { - super( message, cause ); + /** + * Constructs a new <code>OptimisticLockException</code> exception with the + * specified entity. + * + * @param entity + * the entity. + */ + public OptimisticLockException(Object entity) { + this.entity = entity; } + /** + * Constructs a new <code>OptimisticLockException</code> exception with the + * specified detail message, cause, and entity. + * + * @param message + * the detail message. + * @param cause + * the cause. + * @param entity + * the entity. + */ public OptimisticLockException(String message, Throwable cause, Object entity) { - super( message, cause ); + super(message, cause); this.entity = entity; } + /** + * Returns the entity that caused this exception. + * + * @return the entity. + */ public Object getEntity() { - return entity; + return this.entity; } + } Modified: jpa-api/trunk/src/main/java/javax/persistence/OrderBy.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OrderBy.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/OrderBy.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,39 +1,124 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * This annotation specifies the ordering of the elements of a collection valued association at the - * point when the association is retrieved. + * Specifies the ordering of the elements of a collection valued + * association or element collection at the point when the association + * or collection is retrieved. * - * The syntax of the value ordering element is an orderby_list, as follows: - * <code>orderby_list::= orderby_item [,orderby_item]* - * orderby_item::= property_or_field_name [ASC | DESC]</code> + * <p> The syntax of the <code>value</code> ordering element is an + * <code>orderby_list</code>, as follows: * - * If ASC or DESC is not specified, ASC (ascending order) is assumed. + * <pre> + * orderby_list::= orderby_item [,orderby_item]* + * orderby_item::= [property_or_field_name] [ASC | DESC] + * </pre> * - * If the ordering element is not specified, ordering by the primary key of the associated - * entity is assumed. + * <p> If <code>ASC</code> or <code>DESC</code> is not specified, + * <code>ASC</code> (ascending order) is assumed. * - * The property or field name must correspond to that of a persistent property or field of the - * associated class. The properties or fields used in the ordering must correspond to columns - * for which comparison operators are supported. + * <p> If the ordering element is not specified for an entity association, + * ordering by the primary key of the associated entity is assumed. * - * @author Emmanuel Bernard + * <p> The property or field name must correspond to that of a + * persistent property or field of the associated class or embedded class + * within it. The properties or fields used in the ordering must correspond to + * columns for which comparison operators are supported. + * + * <p> The dot (".") notation is used to refer to an attribute within an + * embedded attribute. The value of each identifier used with the dot + * notation is the name of the respective embedded field or property. + * + * <p> The <code>OrderBy</code> annotation may be applied to an element + * collection. When <code>OrderBy</code> is applied to an element collection of + * basic type, the ordering will be by value of the basic objects and + * the property or field name is not used. When specifying an ordering + * over an element collection of embeddable type, the dot notation + * must be used to specify the attribute or attributes that determine + * the ordering. + * + * <p> The <code>OrderBy</code> annotation is not used when an order + * column is specified. + * + * + * <pre> + * Example 1: + * + * &#064;Entity + * public class Course { + * ... + * &#064;ManyToMany + * &#064;OrderBy("lastname ASC") + * public List&#060;Student&#062; getStudents() {...}; + * ... + * } + * + * Example 2: + * + * &#064;Entity + * public class Student { + * ... + * &#064;ManyToMany(mappedBy="students") + * &#064;OrderBy // ordering by primary key is assumed + * public List&#060;Course&#062; getCourses() {...}; + * ... + * } + * + * Example 3: + * + * &#064;Entity + * public class Person { + * ... + * &#064;ElementCollection + * &#064;OrderBy("zipcode.zip, zipcode.plusFour") + * public Set&#060;Address&#062; getResidences() {...}; + * ... + * } + * + * &#064;Embeddable + * public class Address { + * protected String street; + * protected String city; + * protected String state; + * &#064;Embedded protected Zipcode zipcode; + * } + * + * &#064;Embeddable + * public class Zipcode { + * protected String zip; + * protected String plusFour; + * } + * </pre> + * + * @see OrderColumn + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) + public @interface OrderBy { - /** - * An orderby_list, specified as follows: - * orderby_list::= orderby_item [,orderby_item]* orderby_item::= property_or_field_name [ASC | DESC] - * - * If ASC or DESC is not specified, ASC (ascending order) is assumed. - * - */ - String value() default ""; + + /** + * An <code>orderby_list</code>. Specified as follows: + * + * <pre> + * orderby_list::= orderby_item [,orderby_item]* + * orderby_item::= [property_or_field_name] [ASC | DESC] + * </pre> + * + * <p> If <code>ASC</code> or <code>DESC</code> is not specified, + * <code>ASC</code> (ascending order) is assumed. + * + * <p> If the ordering element is not specified, ordering by + * the primary key of the associated entity is assumed. + */ + String value() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/OrderColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OrderColumn.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/OrderColumn.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,30 +1,88 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import static java.lang.annotation.ElementType.FIELD; -import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; -import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; - -/** - * @author Hardy Ferentschik - */ -@Target({ METHOD, FIELD }) -@Retention(RUNTIME) -public @interface OrderColumn { - String name() default ""; - - boolean nullable() default true; - - boolean insertable() default true; - - boolean updatable() default true; - - String columnDefinition() default ""; - - int base() default 0; - - String table() default ""; +package javax.persistence; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +/** + * Specifies a column that is used to maintain the persistent order of + * a list. The persistence provider is responsible for maintaining the + * order upon retrieval and in the database. The persistence provider + * is responsible for updating the ordering upon flushing to the + * database to reflect any insertion, deletion, or reordering + * affecting the list. + * + * <p> The <code>OrderColumn</code> annotation is specified on a + * OneToMany or ManyToMany relationship or on an element + * collection. The <code>OrderColumn</code> annotation is specified on + * the side of the relationship that references the collection that is + * to be ordered. The order column is not visible as part of the state + * of the entity or embeddable class. + * + * <p> The {@link OrderBy} annotation should be used for ordering that + * is visible as persistent state and maintained by the + * application. The <code>OrderBy</code> annotation is not used when + * <code>OrderColumn</code> is specified. + * + * <p> The order column must be of integral type. The persistence + * provider maintains a contiguous (non-sparse) ordering of the values + * of the order column when updating the association or element collection. + * The order column value for the first element is 0. + * + * <pre> + * + * Example: + * + * &#064;Entity + * public class CreditCard { + * + * &#064;Id long ccNumber; + * + * &#064;OneToMany // unidirectional + * &#064;OrderColumn + * List&#060;CardTransaction&#062; transactionHistory; + * ... + * } + * + * </pre> + * + * @see OrderBy + * + * @since Java Persistence 2.0 + */ +@Target( { METHOD, FIELD }) +@Retention(RUNTIME) +public @interface OrderColumn { + + /** (Optional) The name of the ordering column. + * Defaults to the concatenation of the name of the + * referencing property or field; "_"; "ORDER". + */ + String name() default ""; + + /** (Optional) Whether the database column is nullable. */ + boolean nullable() default true; + + /** + * (Optional) Whether the column is included in SQL INSERT statements + * generated by the persistence provider. + */ + boolean insertable() default true; + + /** + * (Optional) Whether the column is included in SQL UPDATE statements + * generated by the persistence provider. + */ + boolean updatable() default true; + + /** + * (Optional) The SQL fragment that is used when generating the DDL for the + * column. Defaults to generated SQL to create a column of the inferred type. + */ + String columnDefinition() default ""; } + Modified: jpa-api/trunk/src/main/java/javax/persistence/Parameter.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Parameter.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Parameter.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,10 +1,14 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; - /** - * Type for query parameters. + * Type for query parameter objects. * @param <T> the type of the parameter + * + * @see Query + * @see TypedQuery + * + * @since Java Persistence 2.0 */ public interface Parameter<T> { @@ -22,18 +26,18 @@ */ Integer getPosition(); - /** + /** * Return the Java type of the parameter. Values bound to the * parameter must be assignable to this type. * This method is required to be supported for criteria queries - * only. Applications that use this method for Java Persistence - * query language queries and native queries will not be portable. + * only. Applications that use this method for Java + * Persistence query language queries and native queries will + * not be portable. * @return the Java type of the parameter * @throws IllegalStateException if invoked on a parameter - * obtained from a Java persistence query language query or - * native query when the implementation does not support this - * use. + * obtained from a Java persistence query language + * query or native query when the implementation does + * not support this use */ - Class<T> getJavaType(); + Class<T> getParameterType(); } - Modified: jpa-api/trunk/src/main/java/javax/persistence/Persistence.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Persistence.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Persistence.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -73,12 +73,12 @@ public boolean isLoaded(Object entity, String attributeName) { List<PersistenceProvider> providers = Persistence.getProviders(); for ( PersistenceProvider provider : providers ) { - final LoadState state = provider.isLoadedWithoutReference( entity, attributeName ); + final LoadState state = provider.getProviderUtil().isLoadedWithoutReference( entity, attributeName ); if ( state == LoadState.UNKNOWN ) continue; return state == LoadState.LOADED; } for ( PersistenceProvider provider : providers ) { - final LoadState state = provider.isLoadedWithReference( entity, attributeName ); + final LoadState state = provider.getProviderUtil().isLoadedWithReference( entity, attributeName ); if ( state == LoadState.UNKNOWN ) continue; return state == LoadState.LOADED; } @@ -88,7 +88,7 @@ public boolean isLoaded(Object object) { List<PersistenceProvider> providers = Persistence.getProviders(); for ( PersistenceProvider provider : providers ) { - final LoadState state = provider.isLoaded( object ); + final LoadState state = provider.getProviderUtil().isLoaded( object ); if ( state == LoadState.UNKNOWN ) continue; return state == LoadState.LOADED; } Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceContext.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceContext.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceContext.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,39 +1,51 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.TYPE; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Target; /** - * Expresses a dependency on an EntityManager persistence context. + * Expresses a dependency on a container-managed {@link EntityManager} and its + * associated persistence context. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) -(a)Retention(RetentionPolicy.RUNTIME) + +@Target({TYPE, METHOD, FIELD}) +@Retention(RUNTIME) public @interface PersistenceContext { - /** - * The name by which the entity manager is to be accessed in the environment referencing context, - * and is not needed when dependency injection is used. - */ - String name() default ""; - /** - * The name of the persistence unit. If the unitName element is specified, the persistence unit - * for the entity manager that is accessible in JNDI must have the same name. - */ - String unitName() default ""; - /** - * Used to specify properties for the container or persistence provider. Vendor specific - * properties may be included in this set of properties. Properties that are not - * recognized by a vendor are ignored. - */ - PersistenceProperty[] properties() default {}; - /** - * Specifies whether this is a transaction-scoped persistence context or - * an extended persistence context. - */ - PersistenceContextType type() default PersistenceContextType.TRANSACTION; + + /** + * (Optional) The name by which the entity manager is to be accessed in the + * environment referencing context; not needed when dependency + * injection is used. + */ + String name() default ""; + + /** + * (Optional) The name of the persistence unit as defined in the + * <code>persistence.xml</code> file. If the <code>unitName</code> element is + * specified, the persistence unit for the entity manager that is + * accessible in JNDI must have the same name. + */ + String unitName() default ""; + + /** + * (Optional) Specifies whether a transaction-scoped persistence context + * or an extended persistence context is to be used. + */ + PersistenceContextType type() default PersistenceContextType.TRANSACTION; + + /** + * (Optional) Properties for the container or persistence + * provider. Vendor specific properties may be included in this + * set of properties. Properties that are not recognized by + * a vendor are ignored. + */ + PersistenceProperty[] properties() default {}; } Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceContextType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceContextType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceContextType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,17 +1,21 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Specifies whether a transaction-scoped or extended persistence context is to be used in - * PersistenceContext. If the type element is not specified, a transaction-scoped persistence - * context is used. + * Specifies whether a transaction-scoped or extended + * persistence context is to be used in {@link PersistenceContext}. + * If not specified, a transaction-scoped persistence context is used. + * + * @since Java Persistence 1.0 */ public enum PersistenceContextType { + /** * Transaction-scoped persistence context */ TRANSACTION, + /** * Extended persistence context */ Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceContexts.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceContexts.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceContexts.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,23 +1,26 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import static java.lang.annotation.ElementType.TYPE; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Target; /** - * Declares one or more PersistenceContext annotations. It is used to express a dependency on - * container-managed entity manager persistence contexts. + * Declares one or more {@link PersistenceContext} annotations. + * It is used to express a dependency on container-managed + * entity manager persistence contexts. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + *@see PersistenceContext + * + * @since Java Persistence 1.0 */ -(a)Target({ElementType.TYPE}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({TYPE}) +@Retention(RUNTIME) public @interface PersistenceContexts { - /** - * One or more persistence context - */ - PersistenceContext[] value(); + + /** (Required) One or more <code>PersistenceContext</code> annotations. */ + PersistenceContext[] value(); + } Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,46 +1,53 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Thrown by the persistence provider when a problem occurs. All instances of PersistenceException - * except for instances of NoResultException and NonUniqueResultException will cause the current - * transaction, if one is active, to be marked for rollback. + * Thrown by the persistence provider when a problem occurs. + * All instances of <code>PersistenceException</code> except for instances of + * {@link NoResultException}, {@link NonUniqueResultException}, + * {@link LockTimeoutException}, and {@link QueryTimeoutException} will cause + * the current transaction, if one is active, to be marked for rollback. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ public class PersistenceException extends RuntimeException { /** - * Constructs a new PersistenceException exception with null as its detail message. + * Constructs a new <code>PersistenceException</code> exception + * with <code>null</code> as its detail message. */ public PersistenceException() { + super(); } /** - * Constructs a new PersistenceException exception with the specified detail message. + * Constructs a new <code>PersistenceException</code> exception + * with the specified detail message. * - * @param message the detail message + * @param message the detail message. */ public PersistenceException(String message) { super( message ); } /** - * Constructs a new PersistenceException exception with the specified detail message and cause + * Constructs a new <code>PersistenceException</code> exception + * with the specified detail message and cause. * - * @param message the detail message - * @param cause the cause + * @param message the detail message. + * @param cause the cause. */ public PersistenceException(String message, Throwable cause) { super( message, cause ); } /** - * Constructs a new PersistenceException exception with the specified cause + * Constructs a new <code>PersistenceException</code> exception + * with the specified cause. * - * @param cause the cause + * @param cause the cause. */ public PersistenceException(Throwable cause) { - super( cause ); + super(cause); } } Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceProperty.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceProperty.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceProperty.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,28 +1,32 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import java.lang.annotation.Retention; -import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; - -/** - * Describes a single container or persistence provider property. - * Vendor specific properties may be included in the set of properties, and are passed to the persistence - * provider by the container when the entity manager is created. - * Properties that are not recognized by a vendor will be ignored. - * - * @author Emmanuel Bernard - */ -@Target({}) -@Retention(RUNTIME) -public @interface PersistenceProperty { - /** - * The name of the property - */ - String name(); - /** - * The value of the property - */ - String value(); +package javax.persistence; + +import java.lang.annotation.Retention; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import java.lang.annotation.Target; + +/** + * Describes a single container or persistence provider property. Used in {@link + * PersistenceContext}. + * <p/> + * Vendor specific properties may be included in the set of + * properties, and are passed to the persistence provider by the + * container when the entity manager is created. Properties that + * are not recognized by a vendor will be ignored. + * + * @since Java Persistence 1.0 + */ +@Target({ }) +@Retention(RUNTIME) +public @interface PersistenceProperty { + /** + * The name of the property + */ + String name(); + + /** + * The value of the property + */ + String value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnit.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnit.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnit.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,29 +1,35 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.TYPE; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Target; /** - * Expresses a dependency on an EntityManagerFactory. + * Expresses a dependency on an {@link EntityManagerFactory} and its + * associated persistence unit. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({ TYPE, METHOD, FIELD }) +@Retention(RUNTIME) public @interface PersistenceUnit { /** - * The name by which the entity manager factory is to be accessed in the environment - * referencing context, and is not needed when dependency injection is used. + * (Optional) The name by which the entity manager factory is to be accessed + * in the environment referencing context; not needed when + * dependency injection is used. */ String name() default ""; + /** - * The name of the persistence unit as defined in the persistence.xml file. If specified, the - * persistence unit for the entity manager factory that is accessible in JNDI must have the - * same name. + * (Optional) The name of the persistence unit as defined in the + * <code>persistence.xml</code> file. If specified, the + * persistence unit for the entity manager factory that is + * accessible in JNDI must have the same name. */ String unitName() default ""; } Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnitUtil.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnitUtil.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnitUtil.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -5,48 +5,56 @@ /** * Utility interface between the application and the persistence * provider managing the persistence unit. - * - * The methods of this interface should only be invoked on entity + * <p/> + * <p>The methods of this interface should only be invoked on entity * instances obtained from or managed by entity managers for this * persistence unit or on new entity instances. + * + * @since Java Persistence 2.0 */ public interface PersistenceUnitUtil extends PersistenceUtil { + /** + * Determine the load state of a given persistent attribute + * of an entity belonging to the persistence unit. + * + * @param entity entity instance containing the attribute + * @param attributeName name of attribute whose load state is + * to be determined + * + * @return false if entity's state has not been loaded or if + * the attribute state has not been loaded, else true + */ + public boolean isLoaded(Object entity, String attributeName); - /** - * Determine the load state of a given persistent attribute - * of an entity belonging to the persistence unit. - * @param entity containing the attribute - * @param attributeName name of attribute whose load state is - * to be determined - * @return false if entity's state has not been loaded or - * if the attribute state has not been loaded, otherwise true - */ - public boolean isLoaded(Object entity, String attributeName); + /** + * Determine the load state of an entity belonging to the + * persistence unit. This method can be used to determine the + * load state of an entity passed as a reference. An entity is + * considered loaded if all attributes for which + * <code>FetchType.EAGER</code> has been specified have been + * loaded. + * <p> The <code>isLoaded(Object, String)</code> method + * should be used to determine the load state of an attribute. + * Not doing so might lead to unintended loading of state. + * + * @param entity entity instance whose load state is to be determined + * + * @return false if the entity has not been loaded, else true + */ + public boolean isLoaded(Object entity); - /** - * Determine the load state of an entity belonging to the - * persistence unit. - * This method can be used to determine the load state - * of an entity passed as a reference. An entity is - * considered loaded if all attributes for which FetchType - * EAGER has been specified have been loaded. - * The isLoaded(Object, String) method should be used to - * determine the load state of an attribute. - * Not doing so might lead to unintended loading of state. - * @param entity whose load state is to be determined - * @return false if the entity has not been loaded, else true. - */ - public boolean isLoaded(Object entity); - - /** - * Returns the id of the entity. - * A generated id is not guaranteed to be available until after - * the database insert has occurred. - * Returns null if the entity does not yet have an id - * @param entity - * @return id of the entity - * @throws IllegalStateException if the entity is found not to be - * an entity. - */ - public Object getIdentifier(Object entity); -} + /** + * Return the id of the entity. + * A generated id is not guaranteed to be available until after + * the database insert has occurred. + * Returns null if the entity does not yet have an id. + * + * @param entity entity instance + * + * @return id of the entity + * + * @throws IllegalArgumentException if the object is found not + * to be an entity + */ + public Object getIdentifier(Object entity); +} Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnits.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnits.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnits.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,22 +1,23 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import static java.lang.annotation.ElementType.TYPE; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Target; /** - * Declares one or more PersistenceUnit annotations + * Declares one or more {@link PersistenceUnit} annotations. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.TYPE}) -(a)Retention(RetentionPolicy.RUNTIME) + +@Target({ TYPE }) +@Retention(RUNTIME) public @interface PersistenceUnits { /** - * One or more PersistenceUnit annotations + * (Required) One or more {@link PersistenceUnit} annotations. */ PersistenceUnit[] value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/PersistenceUtil.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceUtil.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceUtil.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,38 +3,42 @@ package javax.persistence; /** - * @author Hardy Ferentschik - */ - -/** * Utility interface between the application and the persistence * provider(s). + * <p/> + * The <code>PersistenceUtil</code> interface instance obtained from the + * {@link Persistence} class is used to determine the load state of an + * entity or entity attribute regardless of which persistence + * provider in the environment created the entity. + * + * @since Java Persistence 2.0 */ public interface PersistenceUtil { /** - * Determine the load state of a given persistent attribute - * regardless of the persistence provider that created the - * containing entity. - * @param attributeName name of attribute whose load state is * to be determined + * Determine the load state of a given persistent attribute. * + * @param entity entity containing the attribute + * @param attributeName name of attribute whose load state is + * to be determined + * * @return false if entity's state has not been loaded or - * if the attribute state has not been loaded, otherwise true + * if the attribute state has not been loaded, else true */ public boolean isLoaded(Object entity, String attributeName); /** - * Determine the load state of an entity regardless - * of the persistence provider that created it. + * Determine the load state of an entity. * This method can be used to determine the load state - * of an entity passed as a reference. An entity is - * considered loaded if all attributes for which FetchType - * EAGER has been specified have been loaded. - * The isLoaded(Object, String) method should be used to + * of an entity passed as a reference. An entity is + * considered loaded if all attributes for which + * <code>FetchType.EAGER</code> has been specified have been loaded. + * <p> The <code>isLoaded(Object, String)</code> method should be used to * determine the load state of an attribute. * Not doing so might lead to unintended loading of state. * - * @return false if the entity has not be loaded, otherwise - * true. + * @param entity whose load state is to be determined + * + * @return false if the entity has not been loaded, else true */ - public boolean isLoaded(Object object); + public boolean isLoaded(Object entity); } Modified: jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,7 +3,87 @@ package javax.persistence; /** - * @author Hardy Ferentschik + * Thrown by the persistence provider when an pessimistic locking conflict + * occurs. This exception may be thrown as part of an API call, a flush or at + * commit time. The current transaction, if one is active, will be marked for + * rollback. + * + * @since Java Persistence 2.0 */ -public class PessimisticLockException extends RuntimeException { -} +public class PessimisticLockException extends PersistenceException { + /** + * The object that caused the exception + */ + Object entity; + + /** + * Constructs a new <code>PessimisticLockException</code> exception + * with <code>null</code> as its detail message. + */ + public PessimisticLockException() { + super(); + } + + /** + * Constructs a new <code>PessimisticLockException</code> exception + * with the specified detail message. + * + * @param message the detail message. + */ + public PessimisticLockException(String message) { + super( message ); + } + + /** + * Constructs a new <code>PessimisticLockException</code> exception + * with the specified detail message and cause. + * + * @param message the detail message. + * @param cause the cause. + */ + public PessimisticLockException(String message, Throwable cause) { + super( message, cause ); + } + + /** + * Constructs a new <code>PessimisticLockException</code> exception + * with the specified cause. + * + * @param cause the cause. + */ + public PessimisticLockException(Throwable cause) { + super( cause ); + } + + /** + * Constructs a new <code>PessimisticLockException</code> exception + * with the specified entity. + * + * @param entity the entity. + */ + public PessimisticLockException(Object entity) { + this.entity = entity; + } + + /** + * Constructs a new <code>PessimisticLockException</code> exception + * with the specified detail message, cause, and entity. + * + * @param message the detail message. + * @param cause the cause. + * @param entity the entity. + */ + public PessimisticLockException(String message, Throwable cause, Object entity) { + super( message, cause ); + this.entity = entity; + } + + /** + * Returns the entity that caused this exception. + * + * @return the entity. + */ + public Object getEntity() { + return this.entity; + } +} \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockScope.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockScope.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockScope.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,8 +1,50 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +/** + * Defines the values of the <code>javax.persistence.lock.scope</code> + * property for pessimistic locking. This property may be passed as + * an argument to the methods of the {@link EntityManager}, + * {@link Query}, and {@link TypedQuery} interfaces that + * allow lock modes to be specified or used with the + * {@link NamedQuery} annotation. + * + * @since Java Persistence 2.0 + */ public enum PessimisticLockScope { - NORMAL, - EXTENDED + /** + * This value defines the default behavior for pessimistic locking. + * <p/> + * The persistence provider must lock the database row(s) that + * correspond to the non-collection-valued persistent state of + * that instance. If a joined inheritance strategy is used, or if + * the entity is otherwise mapped to a secondary table, this + * entails locking the row(s) for the entity instance in the + * additional table(s). Entity relationships for which the locked + * entity contains the foreign key will also be locked, but not + * the state of the referenced entities (unless those entities are + * explicitly locked). Element collections and relationships for + * which the entity does not contain the foreign key (such as + * relationships that are mapped to join tables or unidirectional + * one-to-many relationships for which the target entity contains + * the foreign key) will not be locked by default. + */ + NORMAL, + + /** + * In addition to the behavior for + * <code>PessimisticLockScope.NORMAL</code>, element collections + * and relationships owned by the entity that are contained in + * join tables will be locked if the + * <code>javax.persistence.lock.scope</code> property is specified + * with a value of <code>PessimisticLockScope.EXTENDED</code>. + * The state of entities referenced by such relationships will not + * be locked (unless those entities are explicitly locked). + * Locking such a relationship or element collection generally locks only + * the rows in the join table or collection table for that + * relationship or collection. This means that phantoms will be + * possible. + */ + EXTENDED } Modified: jpa-api/trunk/src/main/java/javax/persistence/PostLoad.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PostLoad.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PostLoad.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,21 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; - /** - * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied to - * methods of an entity class, a mapped superclass, or a callback listener class. + * Is used to specify callback methods for the corresponding + * lifecycle event. This annotation may be applied to methods + * of an entity class, a mapped superclass, or a callback + * listener class. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.METHOD}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({METHOD}) +@Retention(RUNTIME) public @interface PostLoad { } Modified: jpa-api/trunk/src/main/java/javax/persistence/PostPersist.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PostPersist.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PostPersist.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,21 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; - /** - * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be - * applied to methods of an entity class, a mapped superclass, or a callback listener class. + * Is used to specify callback methods for the corresponding + * lifecycle event. This annotation may be applied to methods + * of an entity class, a mapped superclass, or a callback + * listener class. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.METHOD}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({METHOD}) +@Retention(RUNTIME) public @interface PostPersist { } Modified: jpa-api/trunk/src/main/java/javax/persistence/PostRemove.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PostRemove.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PostRemove.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,21 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; - /** - * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied - * to methods of an entity class, a mapped superclass, or a callback listener class. + * Is used to specify callback methods for the corresponding + * lifecycle event. This annotation may be applied to methods + * of an entity class, a mapped superclass, or a callback + * listener class. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.METHOD}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({METHOD}) +@Retention(RUNTIME) public @interface PostRemove { } Modified: jpa-api/trunk/src/main/java/javax/persistence/PostUpdate.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PostUpdate.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PostUpdate.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,21 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; - /** - * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied to - * methods of an entity class, a mapped superclass, or a callback listener class. + * Is used to specify callback methods for the corresponding + * lifecycle event. This annotation may be applied to methods + * of an entity class, a mapped superclass, or a callback + * listener class. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.METHOD}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({METHOD}) +@Retention(RUNTIME) public @interface PostUpdate { } Modified: jpa-api/trunk/src/main/java/javax/persistence/PrePersist.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PrePersist.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PrePersist.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,21 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; - /** - * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied - * to methods of an entity class, a mapped superclass, or a callback listener class. + * Is used to specify callback methods for the corresponding + * lifecycle event. This annotation may be applied to methods + * of an entity class, a mapped superclass, or a callback + * listener class. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.METHOD}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({METHOD}) +@Retention(RUNTIME) public @interface PrePersist { } Modified: jpa-api/trunk/src/main/java/javax/persistence/PreRemove.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PreRemove.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PreRemove.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,21 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; - /** - * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied - * to methods of an entity class, a mapped superclass, or a callback listener class. + * Is used to specify callback methods for the corresponding + * lifecycle event. This annotation may be applied to methods + * of an entity class, a mapped superclass, or a callback + * listener class. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.METHOD}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({METHOD}) +@Retention(RUNTIME) public @interface PreRemove { } Modified: jpa-api/trunk/src/main/java/javax/persistence/PreUpdate.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PreUpdate.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PreUpdate.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,21 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import java.lang.annotation.ElementType; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; - /** - * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be - * applied to methods of an entity class, a mapped superclass, or a callback listener class. + * Is used to specify callback methods for the corresponding + * lifecycle event. This annotation may be applied to methods + * of an entity class, a mapped superclass, or a callback + * listener class. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ -(a)Target({ElementType.METHOD}) -(a)Retention(RetentionPolicy.RUNTIME) +@Target({METHOD}) +@Retention(RUNTIME) public @interface PreUpdate { } Modified: jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumn.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumn.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,52 +1,88 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * This annotation specifies a primary key column that is used as a foreign key to join to another - * table. + * Specifies a primary key column that is used as a foreign key to + * join to another table. + * <p/> + * It is used to join the primary table of an entity subclass + * in the {@link InheritanceType#JOINED JOINED} mapping strategy + * to the primary table of its superclass; it is used within a + * {@link SecondaryTable} annotation to join a secondary table + * to a primary table; and it may be used in a {@link OneToOne} + * mapping in which the primary key of the referencing entity + * is used as a foreign key to the referenced entity. + * <p/> + * If no <code>PrimaryKeyJoinColumn</code> annotation is + * specified for a subclass in the <code>JOINED</code> + * mapping strategy, the foreign key columns are assumed + * to have the same names as the primary key columns of the + * primary table of the superclass. * - * It is used to join the primary table of an entity subclass in the JOINED mapping strategy to - * the primary table of its superclass; it is used within a SecondaryTable annotation to join a - * secondary table to a primary table; and it may be used in a OneToOne mapping in which the - * primary key of the referencing entity is used as a foreign key to the referenced entity. + * <pre> * - * If no PrimaryKeyJoinColumn annotation is specified for a subclass in the JOINED mapping - * strategy, the foreign key columns are assumed to have the same names as the primary key - * columns of the primary table of the superclass + * Example: Customer and ValuedCustomer subclass * - * @author Emmanuel Bernard + * &#064;Entity + * &#064;Table(name="CUST") + * &#064;Inheritance(strategy=JOINED) + * &#064;DiscriminatorValue("CUST") + * public class Customer { ... } + * + * &#064;Entity + * &#064;Table(name="VCUST") + * &#064;DiscriminatorValue("VCUST") + * &#064;PrimaryKeyJoinColumn(name="CUST_ID") + * public class ValuedCustomer extends Customer { ... } + * </pre> + * + * @see SecondaryTable + * @see Inheritance + * @see OneToOne + * @since Java Persistence 1.0 */ -@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +@Target({ TYPE, METHOD, FIELD }) +@Retention(RUNTIME) public @interface PrimaryKeyJoinColumn { + /** - * The name of the primary key column of the current table. - * - * Defaults to the same name as the primary key column of the primary table of the - * superclass (JOINED mapping strategy); the same name as the primary key column of - * the primary table (SecondaryTable mapping); or the same name as the primary key - * column for the table for the referencing entity (OneToOne mapping) + * (Optional) The name of the primary key column of the current table. + * <p/> + * Defaults to the same name as the primary key column of the primary + * table of the superclass (<code>JOINED</code> mapping strategy); the same + * name as the primary key column of the primary table + * (<code>SecondaryTable</code> mapping); or the same name as the + * primary key column for the table for the referencing entity + * (<code>OneToOne</code> mapping). */ String name() default ""; + /** - * The name of the primary key column of the table being joined to. - * - * Defaults to the same name as the primary key column of the primary table of the - * superclass (JOINED mapping strategy); the same name as the primary key column of the - * primary table (SecondaryTable mapping); or the same name as the primary key column for - * the table for the referencing entity (OneToOne mapping) + * (Optional) The name of the primary key column of the table + * being joined to. + * <p/> + * Defaults to the same name as the primary key column of the primary table + * of the superclass (<code>JOINED</code> mapping strategy); the same name + * as the primary key column of the primary table + * (<code>SecondaryTable</code> mapping); or the same name as the + * primary key column for the table for the referencing entity + * (<code>OneToOne</code> mapping). */ String referencedColumnName() default ""; + /** - * The SQL fragment that is used when generating the DDL for the column. This should not be - * specified for a OneToOne primary key association. - * + * (Optional) The SQL fragment that is used when generating the + * DDL for the column. This should not be specified for a + * <code>OneToOne</code> primary key association. + * <p/> * Defaults to the generated SQL to create a column of the inferred type. */ String columnDefinition() default ""; Modified: jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumns.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumns.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumns.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,22 +1,40 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * This annotation groups PrimaryKeyJoinColumn annotations. It is used to map composite foreign keys. + * Groups {@link PrimaryKeyJoinColumn} annotations. + * It is used to map composite foreign keys. * - * @author Emmanuel Bernard + * <pre> + * Example: ValuedCustomer subclass + * + * &#064;Entity + * &#064;Table(name="VCUST") + * &#064;DiscriminatorValue("VCUST") + * &#064;PrimaryKeyJoinColumns({ + * &#064;PrimaryKeyJoinColumn(name="CUST_ID", + * referencedColumnName="ID"), + * &#064;PrimaryKeyJoinColumn(name="CUST_TYPE", + * referencedColumnName="TYPE") + * }) + * public class ValuedCustomer extends Customer { ... } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +@Target({ TYPE, METHOD, FIELD }) +@Retention(RUNTIME) public @interface PrimaryKeyJoinColumns { /** - * One or more PrimaryKeyJoinColumn annotations + * One or more <code>PrimaryKeyJoinColumn</code> annotations. */ PrimaryKeyJoinColumn[] value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/Query.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Query.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Query.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -5,403 +5,515 @@ import java.util.Calendar; import java.util.Date; import java.util.List; +import java.util.Set; import java.util.Map; -import java.util.Set; /** * Interface used to control query execution. + * + * @see TypedQuery + * @see Parameter + * @since Java Persistence 1.0 */ public interface Query { + /** * Execute a SELECT query and return the query results - * as a List. + * as an untyped List. * * @return a list of the results * - * @throws IllegalStateException if called for a Java - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set + * @throws IllegalStateException if called for a Java + * Persistence query language UPDATE or DELETE statement + * @throws QueryTimeoutException if the query execution exceeds + * the query timeout value set and only the statement is + * rolled back * @throws TransactionRequiredException if a lock mode has - * been set and there is no transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back + * been set and there is no transaction + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking + * fails and only the statement is rolled back + * @throws PersistenceException if the query execution exceeds + * the query timeout value set and the transaction + * is rolled back */ - public List getResultList(); + List getResultList(); /** - * Execute a SELECT query that returns a single result. + * Execute a SELECT query that returns a single untyped result. * * @return the result * - * @throws NoResultException if there is no result - * @throws NonUniqueResultException if more than one result - * @throws IllegalStateException if called for a Java - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds *the query timeout value set + * @throws NoResultException if there is no result + * @throws NonUniqueResultException if more than one result + * @throws IllegalStateException if called for a Java + * Persistence query language UPDATE or DELETE statement + * @throws QueryTimeoutException if the query execution exceeds + * the query timeout value set and only the statement is + * rolled back * @throws TransactionRequiredException if a lock mode has - * been set and there is no transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back + * been set and there is no transaction + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking + * fails and only the statement is rolled back + * @throws PersistenceException if the query execution exceeds + * the query timeout value set and the transaction + * is rolled back */ - public Object getSingleResult(); + Object getSingleResult(); /** * Execute an update or delete statement. * * @return the number of entities updated or deleted * - * @throws IllegalStateException if called for a Java - * Persistence query language SELECT statement or for - * a criteria query + * @throws IllegalStateException if called for a Java + * Persistence query language SELECT statement or for + * a criteria query * @throws TransactionRequiredException if there is - * no transaction - * @throws QueryTimeoutException if the statement execution - * exceeds the query timeout value set + * no transaction + * @throws QueryTimeoutException if the statement execution + * exceeds the query timeout value set and only + * the statement is rolled back + * @throws PersistenceException if the query execution exceeds + * the query timeout value set and the transaction + * is rolled back */ - public int executeUpdate(); + int executeUpdate(); /** * Set the maximum number of results to retrieve. * - * @param maxResult + * @param maxResult maximum number of results to retrieve * * @return the same query instance * - * @throws IllegalArgumentException if argument is negative + * @throws IllegalArgumentException if the argument is negative */ - public Query setMaxResults(int maxResult); + Query setMaxResults(int maxResult); /** * The maximum number of results the query object was set to - * retrieve. Returns Integer.MAX_VALUE if setMaxResults was not + * retrieve. Returns <code>Integer.MAX_VALUE</code> if <code>setMaxResults</code> was not * applied to the query object. * * @return maximum number of results + * + * @since Java Persistence 2.0 */ - public int getMaxResults(); + int getMaxResults(); /** * Set the position of the first result to retrieve. * - * @param startPosition position of the first result, numbered from 0 + * @param startPosition position of the first result, + * numbered from 0 * * @return the same query instance * - * @throws IllegalArgumentException if argument is negative + * @throws IllegalArgumentException if the argument is negative */ - public Query setFirstResult(int startPosition); + Query setFirstResult(int startPosition); /** * The position of the first result the query object was set to - * retrieve. Returns 0 if setFirstResult was not applied to the + * retrieve. Returns 0 if <code>setFirstResult</code> was not applied to the * query object. * - * @return position of first result + * @return position of the first result + * + * @since Java Persistence 2.0 */ - public int getFirstResult(); + int getFirstResult(); /** - * Set a query hint. - * If a vendor-specific hint is not recognized, it is silently - * ignored. - * Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * * @param hintName + * Set a query property or hint. The hints elements may be used + * to specify query properties and hints. Properties defined by + * this specification must be observed by the provider. + * Vendor-specific hints that are not recognized by a provider + * must be silently ignored. Portable applications should not + * rely on the standard timeout hint. Depending on the database + * in use and the locking mechanisms used by the provider, + * this hint may or may not be observed. * - * @param value + * @param hintName name of the property or hint + * @param value value for the property or hint * * @return the same query instance * * @throws IllegalArgumentException if the second argument is not - * valid for the implementation + * valid for the implementation */ - public Query setHint(String hintName, Object value); + Query setHint(String hintName, Object value); /** - * Get the hints and associated values that are in effect for - * the query instance. + * Get the properties and hints and associated values that are + * in effect for the query instance. * - * @return query hints + * @return query properties and hints + * + * @since Java Persistence 2.0 */ - public Map<String, Object> getHints(); + Map<String, Object> getHints(); /** - * Get the names of the hints that are supported for query - * objects. These hints correspond to hints that may be passed - * to the methods of the Query interface that take hints as - * arguments or used with the NamedQuery and NamedNativeQuery - * annotations. These include all standard query hints as well as - * vendor-specific hints supported by the provider. These hints - * may or may not currently be in effect. + * Bind the value of a <code>Parameter</code> object. * - * @return hints + * @param param parameter object + * @param value parameter value + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter + * does not correspond to a parameter of the + * query + * @since Java Persistence 2.0 */ - public Set<String> getSupportedHints(); + <T> Query setParameter(Parameter<T> param, T value); /** + * Bind an instance of <code>java.util.Calendar</code> to a <code>Parameter</code> object. + * + * @param param parameter object + * @param value parameter value + * @param temporalType temporal type + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter does not + * correspond to a parameter of the query + * @since Java Persistence 2.0 + */ + Query setParameter(Parameter<Calendar> param, Calendar value, + TemporalType temporalType); + + /** + * Bind an instance of <code>java.util.Date</code> to a <code>Parameter</code> object. + * + * @param param parameter object + * @param value parameter value + * @param temporalType temporal type + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter does not + * correspond to a parameter of the query + * @since Java Persistence 2.0 + */ + Query setParameter(Parameter<Date> param, Date value, + TemporalType temporalType); + + /** * Bind an argument to a named parameter. * - * @param name the parameter name - * @param value + * @param name parameter name + * @param value parameter value * * @return the same query instance * - * @throws IllegalArgumentException if parameter name does not - * correspond to a parameter of the query or if - * the argument is of incorrect type + * @throws IllegalArgumentException if the parameter name does + * not correspond to a parameter of the query or if + * the argument is of incorrect type */ - public Query setParameter(String name, Object value); + Query setParameter(String name, Object value); /** - * Bind an instance of java.util.Date to a named parameter. + * Bind an instance of <code>java.util.Calendar</code> to a named parameter. * - * @param name - * @param value - * @param temporalType + * @param name parameter name + * @param value parameter value + * @param temporalType temporal type * * @return the same query instance * - * @throws IllegalArgumentException if parameter name does not - * correspond to a parameter of the query + * @throws IllegalArgumentException if the parameter name does + * not correspond to a parameter of the query or if + * the value argument is of incorrect type */ - public Query setParameter(String name, Date value, - TemporalType temporalType); + Query setParameter(String name, Calendar value, + TemporalType temporalType); /** - * Bind an instance of java.util.Calendar to a named parameter. + * Bind an instance of <code>java.util.Date</code> to a named parameter. * - * @param name - * @param value - * @param temporalType + * @param name parameter name + * @param value parameter value + * @param temporalType temporal type * * @return the same query instance * - * @throws IllegalArgumentException if parameter name does not - * correspond to a parameter of the query + * @throws IllegalArgumentException if the parameter name does + * not correspond to a parameter of the query or if + * the value argument is of incorrect type */ - public Query setParameter(String name, Calendar value, - TemporalType temporalType); + Query setParameter(String name, Date value, + TemporalType temporalType); /** * Bind an argument to a positional parameter. * - * @param position - * @param value + * @param position position + * @param value parameter value * * @return the same query instance * * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of - * the query or if the argument is of incorrect - * type + * correspond to a positional parameter of the + * query or if the argument is of incorrect type */ - public Query setParameter(int position, Object value); + Query setParameter(int position, Object value); /** - * Bind an instance of java.util.Date to a positional parameter. + * Bind an instance of <code>java.util.Calendar</code> to a positional + * parameter. * - * @param position - * @param value - * @param temporalType + * @param position position + * @param value parameter value + * @param temporalType temporal type * * @return the same query instance * * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the - * query + * correspond to a positional parameter of the query or + * if the value argument is of incorrect type */ - public Query setParameter(int position, Date value, - TemporalType temporalType); + Query setParameter(int position, Calendar value, + TemporalType temporalType); /** - * Bind an instance of java.util.Calendar to a positional - * parameter. + * Bind an instance of <code>java.util.Date</code> to a positional parameter. * - * @param position - * @param value - * @param temporalType + * @param position position + * @param value parameter value + * @param temporalType temporal type * * @return the same query instance * * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the *query + * correspond to a positional parameter of the query or + * if the value argument is of incorrect type */ - public Query setParameter(int position, Calendar value, - TemporalType temporalType); + Query setParameter(int position, Date value, + TemporalType temporalType); /** - * Get the parameter objects corresponding to the declared - * parameters of the query. - * Returns empty set if the query has no parameters. - * This method is not required to be supported for native - * queries. - * @return set of the parameter objects - * @throws IllegalStateException if invoked on a native - * query when the implementation does not support - * this use - */ - Set<Parameter<?>> getParameters(); + * Get the parameter objects corresponding to the declared + * parameters of the query. + * Returns empty set if the query has no parameters. + * This method is not required to be supported for native + * queries. + * + * @return set of the parameter objects + * + * @throws IllegalStateException if invoked on a native + * query when the implementation does not support + * this use + * @since Java Persistence 2.0 + */ + Set<Parameter<?>> getParameters(); - /** - * Get the parameter object corresponding to the declared - * parameter of the given name. - * This method is not required to be supported for native - * queries. - * @param name - * @return parameter object - * @throws IllegalArgumentException if the parameter of the - * specified name does not exist - * @throws IllegalStateException if invoked on a native - * query when the implementation does not support - * this use - */ - Parameter<?> getParameter(String name); + /** + * Get the parameter object corresponding to the declared + * parameter of the given name. + * This method is not required to be supported for native + * queries. + * + * @param name parameter name + * + * @return parameter object + * + * @throws IllegalArgumentException if the parameter of the + * specified name does not exist + * @throws IllegalStateException if invoked on a native + * query when the implementation does not support + * this use + * @since Java Persistence 2.0 + */ + Parameter<?> getParameter(String name); - /** - * Get the parameter object corresponding to the declared - * positional parameter with the given position. - * This method is not required to be supported for native - * queries. - * @param position - * @return parameter object - * @throws IllegalArgumentException if the parameter with the - * specified position does not exist - * @throws IllegalStateException if invoked on a native - * query when the implementation does not support - * this use - */ - Parameter<?> getParameter(int position); + /** + * Get the parameter object corresponding to the declared + * parameter of the given name and type. + * This method is required to be supported for criteria queries + * only. + * + * @param name parameter name + * @param type type + * + * @return parameter object + * + * @throws IllegalArgumentException if the parameter of the + * specified name does not exist or is not assignable + * to the type + * @throws IllegalStateException if invoked on a native + * query or Java Persistence query language query when + * the implementation does not support this use + * @since Java Persistence 2.0 + */ + <T> Parameter<T> getParameter(String name, Class<T> type); - /** - * Get the parameter of the given name and type. - * This method is required to be supported for criteria queries - * only. - * @param name - * @param type - * @return parameter object - * @throws IllegalArgumentException if the parameter of the - * specified name does not exist or is not assignable - * to the type - * @throws IllegalStateException if invoked on a native - * query or Java Persistence query language query when - * the implementation does not support this use - */ - <T> Parameter<T> getParameter(String name, Class<T> type); + /** + * Get the parameter object corresponding to the declared + * positional parameter with the given position. + * This method is not required to be supported for native + * queries. + * + * @param position position + * + * @return parameter object + * + * @throws IllegalArgumentException if the parameter with the + * specified position does not exist + * @throws IllegalStateException if invoked on a native + * query when the implementation does not support + * this use + * @since Java Persistence 2.0 + */ + Parameter<?> getParameter(int position); - /** - * Get the positional parameter with the given position and type. - * This method is required to be supported for criteria queries - * only. - * @param position - * @param type - * @return parameter object - * @throws IllegalArgumentException if the parameter with the - * specified position does not exist or is not assignable - * to the type - * @throws IllegalStateException if invoked on a native - * query or Java Persistence query language query when - * the implementation does not support this use - */ - <T> Parameter<T> getParameter(int position, Class<T> type); + /** + * Get the parameter object corresponding to the declared + * positional parameter with the given position and type. + * This method is not required to be supported by the provider. + * + * @param position position + * @param type type + * + * @return parameter object + * + * @throws IllegalArgumentException if the parameter with the + * specified position does not exist or is not assignable + * to the type + * @throws IllegalStateException if invoked on a native + * query or Java Persistence query language query when + * the implementation does not support this use + * @since Java Persistence 2.0 + */ + <T> Parameter<T> getParameter(int position, Class<T> type); - /** - * Return a boolean indicating whether a value has been bound - * to the parameter. - * @param param parameter object - * @return boolean indicating whether parameter has been bound - */ - boolean isBound(Parameter<?> param); + /** + * Return a boolean indicating whether a value has been bound + * to the parameter. + * + * @param param parameter object + * + * @return boolean indicating whether parameter has been bound + * + * @since Java Persistence 2.0 + */ + boolean isBound(Parameter<?> param); - /** - * Return the value bound to the parameter. - * @param param parameter object - * @return parameter value - * @throws IllegalStateException if the parameter has not been - * been bound - */ - <T> T getParameterValue(Parameter<T> param); + /** + * Return the value bound to the parameter. + * + * @param param parameter object + * + * @return parameter value + * + * @throws IllegalArgumentException if the parameter is not + * a parameter of the query + * @throws IllegalStateException if the parameter has not been + * been bound + * @since Java Persistence 2.0 + */ + <T> T getParameterValue(Parameter<T> param); - /** - * Return the value bound to the named parameter. - * @param name - * @return parameter value - * @throws IllegalStateException if the parameter has not been - * been bound - * @throws IllegalArgumentException if the parameter of the - * specified name does not exist - */ - Object getParameterValue(String name); + /** + * Return the value bound to the named parameter. + * + * @param name parameter name + * + * @return parameter value + * + * @throws IllegalStateException if the parameter has not been + * been bound + * @throws IllegalArgumentException if the parameter of the + * specified name does not exist + * @since Java Persistence 2.0 + */ + Object getParameterValue(String name); - /** - * Return the value bound to the positional parameter. - * @param position - * @return parameter value - * @throws IllegalStateException if the parameter has not been - * been bound - * @throws IllegalArgumentException if the parameter with the - * specified position does not exist - */ - Object getParameterValue(int position); + /** + * Return the value bound to the positional parameter. + * + * @param position position + * + * @return parameter value + * + * @throws IllegalStateException if the parameter has not been + * been bound + * @throws IllegalArgumentException if the parameter with the + * specified position does not exist + * @since Java Persistence 2.0 + */ + Object getParameterValue(int position); /** * Set the flush mode type to be used for the query execution. * The flush mode type applies to the query regardless of the * flush mode type in use for the entity manager. * - * @param flushMode + * @param flushMode flush mode + * + * @return the same query instance */ - public Query setFlushMode(FlushModeType flushMode); + Query setFlushMode(FlushModeType flushMode); /** - * The flush mode in effect for the query execution. If a flush - * mode has not been set for the query object, returns the flush - * mode in effect for the entity manager. + * Get the flush mode in effect for the query execution. + * If a flush mode has not been set for the query object, + * returns the flush mode in effect for the entity manager. * * @return flush mode + * + * @since Java Persistence 2.0 */ - public FlushModeType getFlushMode(); + FlushModeType getFlushMode(); /** * Set the lock mode type to be used for the query execution. * - * @param lockMode + * @param lockMode lock mode * - * @throws IllegalStateException if the query is found not to be *a Java Persistence query language SELECT query - * or a Criteria API query + * @return the same query instance + * + * @throws IllegalStateException if the query is found not to be + * a Java Persistence query language SELECT query + * or a Criteria API query + * @since Java Persistence 2.0 */ - public Query setLockMode(LockModeType lockMode); + Query setLockMode(LockModeType lockMode); /** * Get the current lock mode for the query. * * @return lock mode * - * @throws IllegalStateException if the query is found not to be *a Java Persistence query language SELECT query - * or a Criteria API query + * @throws IllegalStateException if the query is found not to be + * a Java Persistence query language SELECT query or + * a Criteria API query + * @since Java Persistence 2.0 */ - public LockModeType getLockMode(); + LockModeType getLockMode(); /** - * Return an object of the specified type to allow access to the - * provider-specific API. If the provider's Query implementation - * does not support the specified class, the PersistenceException - * is thrown. + * Return an object of the specified type to allow access to + * the provider-specific API. If the provider's query + * implementation does not support the specified class, the + * <code>PersistenceException</code> is thrown. * - * @param cls the class of the object to be returned. This is - * normally either the underlying Query implementation class - * or an interface that it implements. + * @param cls the class of the object to be returned. This is + * normally either the underlying query + * implementation class or an interface that it + * implements. * * @return an instance of the specified class * * @throws PersistenceException if the provider does not support - * the call. + * the call + * @since Java Persistence 2.0 */ - public <T> T unwrap(Class<T> cls); + <T> T unwrap(Class<T> cls); } Modified: jpa-api/trunk/src/main/java/javax/persistence/QueryHint.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/QueryHint.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/QueryHint.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,26 +1,29 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * An implementation-specific Query hint + * Used to supply a query property or hint to the {@link NamedQuery} or {@link + * NamedNativeQuery} annotation. * - * @author Emmanuel Bernard + * <p> Vendor-specific hints that are not recognized by a provider are ignored. + * + * @since Java Persistence 1.0 */ -@Target({}) +@Target({ }) @Retention(RUNTIME) public @interface QueryHint { /** - * Name of the hint + * Name of the hint. */ String name(); /** - * Value of the hint + * Value of the hint. */ String value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/QueryTimeoutException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/QueryTimeoutException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/QueryTimeoutException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,7 +3,88 @@ package javax.persistence; /** - * @author Hardy Ferentschik + * Thrown by the persistence provider when a query times out + * and only the statement is rolled back. + * The current transaction, if one is active, will be not + * be marked for rollback. + * + * @since Java Persistence 2.0 */ -public class QueryTimeoutException extends RuntimeException { +public class QueryTimeoutException extends PersistenceException { + /** + * The query object that caused the exception + */ + Query query; + + /** + * Constructs a new <code>QueryTimeoutException</code> exception + * with <code>null</code> as its detail message. + */ + public QueryTimeoutException() { + super(); + } + + /** + * Constructs a new <code>QueryTimeoutException</code> exception + * with the specified detail message. + * + * @param message the detail message. + */ + public QueryTimeoutException(String message) { + super( message ); + } + + /** + * Constructs a new <code>QueryTimeoutException</code> exception + * with the specified detail message and cause. + * + * @param message the detail message. + * @param cause the cause. + */ + public QueryTimeoutException(String message, Throwable cause) { + super( message, cause ); + } + + /** + * Constructs a new <code>QueryTimeoutException</code> exception + * with the specified cause. + * + * @param cause the cause. + */ + public QueryTimeoutException(Throwable cause) { + super( cause ); + } + + + /** + * Constructs a new <code>QueryTimeoutException</code> exception + * with the specified query. + * + * @param query the query. + */ + public QueryTimeoutException(Query query) { + this.query = query; + } + + /** + * Constructs a new <code>QueryTimeoutException</code> exception + * with the specified detail message, cause, and query. + * + * @param message the detail message. + * @param cause the cause. + * @param query the query. + */ + public QueryTimeoutException(String message, Throwable cause, Query query) { + super( message, cause ); + this.query = query; + } + + /** + * Returns the query that caused this exception. + * + * @return the query. + */ + public Query getQuery() { + return this.query; + } } Modified: jpa-api/trunk/src/main/java/javax/persistence/RollbackException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/RollbackException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/RollbackException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,45 +1,51 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Thrown by the persistence provider when the EntityTransaction.commit() fails + * Thrown by the persistence provider when + * {@link EntityTransaction#commit() EntityTransaction.commit()} fails. * - * @author Emmanuel Bernard + * @see javax.persistence.EntityTransaction#commit() + * @since Java Persistence 1.0 */ public class RollbackException extends PersistenceException { /** - * Constructs a new RollbackException exception with null as its detail message + * Constructs a new <code>RollbackException</code> exception + * with <code>null</code> as its detail message. */ public RollbackException() { super(); } /** - * Constructs a new RollbackException exception with the specified cause + * Constructs a new <code>RollbackException</code> exception + * with the specified detail message. * - * @param cause The detail cause + * @param message the detail message. */ - public RollbackException(Throwable cause) { - super( cause ); + public RollbackException(String message) { + super( message ); } /** - * Constructs a new RollbackException exception with the specified detail message + * Constructs a new <code>RollbackException</code> exception + * with the specified detail message and cause. * - * @param message The detail message + * @param message the detail message. + * @param cause the cause. */ - public RollbackException(String message) { - super( message ); + public RollbackException(String message, Throwable cause) { + super( message, cause ); } /** - * Constructs a new RollbackException exception with the specified detail message and cause + * Constructs a new <code>RollbackException</code> exception + * with the specified cause. * - * @param message The detail message - * @param cause The detail cause + * @param cause the cause. */ - public RollbackException(String message, Throwable cause) { - super( message, cause ); + public RollbackException(Throwable cause) { + super(cause); } } Modified: jpa-api/trunk/src/main/java/javax/persistence/SecondaryTable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SecondaryTable.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/SecondaryTable.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,53 +1,83 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * This annotation is used to specify a secondary table for the annotated entity class. Specifying - * one or more secondary tables indicates that the data for the entity class is stored across multiple - * tables. + * Specifies a secondary table for the annotated entity + * class. Specifying one or more secondary tables indicates that the + * data for the entity class is stored across multiple tables. * - * If no SecondaryTable annotation is specified, it is assumed that all persistent fields or properties - * of the entity are mapped to the primary table. If no primary key join columns are specified, the - * join columns are assumed to reference the primary key columns of the primary table, and have the - * same names and types as the referenced primary key columns of the primary table. + * <p> If no <code>SecondaryTable</code> annotation is specified, + * it is assumed that all persistent fields or properties of the + * entity are mapped to the primary table. If no primary key join + * columns are specified, the join columns are assumed to reference + * the primary key columns of the primary table, and have the same + * names and types as the referenced primary key columns of the + * primary table. * - * @author Emmanuel Bernard + * <pre> + * Example 1: Single secondary table with a single primary key column. + * + * &#064;Entity + * &#064;Table(name="CUSTOMER") + * &#064;SecondaryTable(name="CUST_DETAIL", + * pkJoinColumns=&#064;PrimaryKeyJoinColumn(name="CUST_ID")) + * public class Customer { ... } + * + * + * Example 2: Single secondary table with multiple primary key columns. + * + * &#064;Entity + * &#064;Table(name="CUSTOMER") + * &#064;SecondaryTable(name="CUST_DETAIL", + * pkJoinColumns={ + * &#064;PrimaryKeyJoinColumn(name="CUST_ID"), + * &#064;PrimaryKeyJoinColumn(name="CUST_TYPE")}) + * public class Customer { ... } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target(TYPE) +@Retention(RUNTIME) public @interface SecondaryTable { /** - * The name of the table + * (Required) The name of the table. */ String name(); + /** - * The catalog of the table + * (Optional) The catalog of the table. + * <p> Defaults to the default catalog. */ String catalog() default ""; + /** - * The schema of the table + * (Optional) The schema of the table. + * <p> Defaults to the default schema for user. */ String schema() default ""; + /** - * The columns that are used to join with the primary table. - * - * Defaults to the column(s) of the same name(s) as the primary key column(s) - * in the primary table + * (Optional) The columns that are used to join with + * the primary table. + * <p> Defaults to the column(s) of the same name(s) + * as the primary key column(s) in the primary table. */ - PrimaryKeyJoinColumn[] pkJoinColumns() default {}; + PrimaryKeyJoinColumn[] pkJoinColumns() default { }; + /** - * Unique constraints that are to be placed on the table. These are typically only used if - * table generation is in effect. These constraints apply in addition to any constraints - * specified by the Column and JoinColumn annotations and constraints entailed by primary - * key mappings. - * - * Defaults to no additional constraints. + * (Optional) Unique constraints that are to be placed on the + * table. These are typically only used if table generation + * is in effect. These constraints apply in addition to any + * constraints specified by the <code>Column</code> and <code>JoinColumn</code> + * annotations and constraints entailed by primary key mappings. + * <p> Defaults to no additional constraints. */ - UniqueConstraint[] uniqueConstraints() default {}; + UniqueConstraint[] uniqueConstraints() default { }; } Modified: jpa-api/trunk/src/main/java/javax/persistence/SecondaryTables.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SecondaryTables.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/SecondaryTables.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,21 +1,48 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; /** - * This annotation is used to specify multiple secondary tables for an entity. + * Specifies multiple secondary tables for an entity. * - * @author Emmanuel Bernard + * <pre> + * Example 1: Multiple secondary tables assuming primary key columns are named the same in all tables. + * + * &#064;Entity + * &#064;Table(name="EMPLOYEE") + * &#064;SecondaryTables({ + * &#064;SecondaryTable(name="EMP_DETAIL"), + * &#064;SecondaryTable(name="EMP_HIST") + * }) + * public class Employee { ... } + * + * + * Example 2: Multiple secondary tables with differently named primary key columns. + * + * &#064;Entity + * &#064;Table(name="EMPLOYEE") + * &#064;SecondaryTables({ + * &#064;SecondaryTable(name="EMP_DETAIL", + * pkJoinColumns=&#064;PrimaryKeyJoinColumn(name="EMPL_ID")), + * &#064;SecondaryTable(name="EMP_HIST", + * pkJoinColumns=&#064;PrimaryKeyJoinColumn(name="EMPLOYEE_ID")) + * }) + * public class Employee { ... } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target(TYPE) +@Retention(RUNTIME) + public @interface SecondaryTables { /** - * The secondary tables for an entity. + * (Required) The secondary tables for an entity. */ SecondaryTable[] value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/SequenceGenerator.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SequenceGenerator.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/SequenceGenerator.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,38 +1,70 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * This annotation defines a primary key generator that may be referenced by name when a generator - * element is specified for the GeneratedValue annotation. A sequence generator may be specified on - * the entity class or on the primary key field or property. The scope of the generator name is global - * to the persistence unit (across all generator types). + * Defines a primary key generator that may be referenced by name when + * a generator element is specified for the {@link GeneratedValue} + * annotation. A sequence generator may be specified on the entity + * class or on the primary key field or property. The scope of the + * generator name is global to the persistence unit (across all + * generator types). * - * @author Emmanuel Bernard + * <pre> + * Example: + * + * &#064;SequenceGenerator(name="EMP_SEQ", allocationSize=25) + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +@Target({ TYPE, METHOD, FIELD }) +@Retention(RUNTIME) public @interface SequenceGenerator { /** - * A unique generator name that can be referenced by one or more classes to be the generator for primary key values + * (Required) A unique generator name that can be referenced + * by one or more classes to be the generator for primary key + * values. */ String name(); + /** - * The name of the database sequence object from which to obtain primary key values - * Defaults to a provider-chosen value + * (Optional) The name of the database sequence object from + * which to obtain primary key values. + * <p> Defaults to a provider-chosen value. */ String sequenceName() default ""; + /** - * The value from which the sequence object is to start generating + * (Optional) The catalog of the sequence generator. + * + * @since Java Persistence 2.0 */ + String catalog() default ""; + + /** + * (Optional) The schema of the sequence generator. + * + * @since Java Persistence 2.0 + */ + String schema() default ""; + + /** + * (Optional) The value from which the sequence object + * is to start generating. + */ int initialValue() default 1; + /** - * The amount to increment by when allocating sequence numbers from the sequence + * (Optional) The amount to increment by when allocating + * sequence numbers from the sequence. */ int allocationSize() default 50; } Copied: jpa-api/trunk/src/main/java/javax/persistence/SharedCacheMode.java (from rev 17521, jpa-api/trunk/src/main/java/javax/persistence/Caching.java) =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SharedCacheMode.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/SharedCacheMode.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -0,0 +1,42 @@ +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +/** + * Specifies how the provider must use a second-level cache for the + * persistence unit. Corresponds to the value of the <code>persistence.xml</code> + * <code>shared-cache-mode</code> element, and returned as the result of + * {@link javax.persistence.spi.PersistenceUnitInfo#getSharedCacheMode()}. + * + * @since Java Persistence 2.0 + */ +public enum SharedCacheMode { + /** + * All entities and entity-related state and data are cached. + */ + ALL, + + /** + * Caching is disabled for the persistence unit. + */ + NONE, + + /** + * Caching is enabled for all entities for <code>Cacheable(true)</code> + * is specified. All other entities are not cached. + */ + ENABLE_SELECTIVE, + + /** + * Caching is enabled for all entities except those for which + * <code>Cacheable(false) is specified. Entities for which + * <code>Cacheable(false) is specified are not cached. + */ + DISABLE_SELECTIVE, + + /** + * + * Caching behavior is undefined: provider-specific defaults may apply. + */ + UNSPECIFIED +} Property changes on: jpa-api/trunk/src/main/java/javax/persistence/SharedCacheMode.java ___________________________________________________________________ Name: svn:keywords + Id Modified: jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMapping.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMapping.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMapping.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,29 +1,56 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.ElementType; -import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * This annotation is used to specify the mapping of the result of a native SQL query + * Specifies the mapping of the result of a native SQL query. * - * @author Emmanuel Bernard + * <pre> + * Example: + * + * Query q = em.createNativeQuery( + * "SELECT o.id AS order_id, " + + * "o.quantity AS order_quantity, " + + * "o.item AS order_item, " + + * "i.name AS item_name, " + + * "FROM Order o, Item i " + + * "WHERE (order_quantity > 25) AND (order_item = i.id)", + * "OrderResults"); + * + * &#064;SqlResultSetMapping(name="OrderResults", + * entities={ + * &#064;EntityResult(entityClass=com.acme.Order.class, fields={ + * &#064;FieldResult(name="id", column="order_id"), + * &#064;FieldResult(name="quantity", column="order_quantity"), + * &#064;FieldResult(name="item", column="order_item")})}, + * columns={ + * &#064;ColumnResult(name="item_name")} + * ) + * </pre> + * + * @since Java Persistence 1.0 */ -(a)Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) +@Target({ TYPE }) +@Retention(RUNTIME) public @interface SqlResultSetMapping { /** - * The name given to the result set mapping, and used to refer to it in the methods of the Query API + * The name given to the result set mapping, and used to refer + * to it in the methods of the {@link Query} API. */ String name(); + /** - * Specifies the result set mapping to entities + * Specifies the result set mapping to entities. */ - EntityResult[] entities() default {}; + EntityResult[] entities() default { }; + /** - * Specifies the result set mapping to scalar values + * Specifies the result set mapping to scalar values. */ - ColumnResult[] columns() default {}; + ColumnResult[] columns() default { }; } Modified: jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMappings.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMappings.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMappings.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,18 +1,22 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; import java.lang.annotation.Target; -import java.lang.annotation.ElementType; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * This annotation is used to define one or more SqlResultSetMapping + * Is used to define one or more {@link SqlResultSetMapping} annotations. * - * @author Emmanuel Bernard + * @since Java Persistence 1.0 */ -(a)Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) +@Target({ TYPE }) +@Retention(RUNTIME) public @interface SqlResultSetMappings { + /** + * One or more <code>SqlResultSetMapping</code> annotations. + */ SqlResultSetMapping[] value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/Table.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Table.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Table.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,48 +1,62 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.TYPE; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * This annotation specifies the primary table for the annotated entity. Additional - * tables may be specified using SecondaryTable or SecondaryTables annotation. + * Specifies the primary table for the annotated entity. Additional + * tables may be specified using {@link SecondaryTable} or {@link + * SecondaryTables} annotation. + * <p/> + * If no <code>Table</code> annotation is specified for an entity + * class, the default values apply. * - * If no Table annotation is specified for an entity class, the default values apply. + * <pre> + * Example: * - * @author Emmanuel Bernard + * &#064;Entity + * &#064;Table(name="CUST", schema="RECORDS") + * public class Customer { ... } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({TYPE}) @Retention(RUNTIME) +@Target(TYPE) +@Retention(RUNTIME) public @interface Table { /** - * The name of the table. - * + * (Optional) The name of the table. + * <p/> * Defaults to the entity name. */ String name() default ""; + /** - * The catalog of the table. - * + * (Optional) The catalog of the table. + * <p/> * Defaults to the default catalog. */ String catalog() default ""; + /** - * The schema of the table. - * + * (Optional) The schema of the table. + * <p/> * Defaults to the default schema for user. */ String schema() default ""; + /** - * Unique constraints that are to be placed on the table. These are only used if table - * generation is in effect. These constraints apply in addition to any constraints - * specified by the Column and JoinColumn annotations and constraints entailed by - * primary key mappings. - * + * (Optional) Unique constraints that are to be placed on + * the table. These are only used if table generation is in + * effect. These constraints apply in addition to any constraints + * specified by the <code>Column</code> and <code>JoinColumn</code> + * annotations and constraints entailed by primary key mappings. + * <p/> * Defaults to no additional constraints. */ - UniqueConstraint[] uniqueConstraints() default {}; + UniqueConstraint[] uniqueConstraints() default { }; } Modified: jpa-api/trunk/src/main/java/javax/persistence/TableGenerator.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TableGenerator.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/TableGenerator.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,67 +1,132 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; -import static java.lang.annotation.ElementType.*; +import java.lang.annotation.Target; 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; -import java.lang.annotation.Target; /** - * This annotation defines a primary key generator that may be referenced by name when a generator - * element is specified for the GeneratedValue annotation. A table generator may be specified on the - * entity class or on the primary key field or property. The scope of the generator name is global to - * the persistence unit (across all generator types). + * Defines a primary key generator that may be + * referenced by name when a generator element is specified for + * the {@link GeneratedValue} annotation. A table generator + * may be specified on the entity class or on the primary key + * field or property. The scope of the generator name is global + * to the persistence unit (across all generator types). * - * @author Emmanuel Bernard + * <pre> + * Example 1: + * + * &#064;Entity public class Employee { + * ... + * &#064;TableGenerator( + * name="empGen", + * table="ID_GEN", + * pkColumnName="GEN_KEY", + * valueColumnName="GEN_VALUE", + * pkColumnValue="EMP_ID", + * allocationSize=1) + * &#064;Id + * &#064;GeneratedValue(strategy=TABLE, generator="empGen") + * int id; + * ... + * } + * + * Example 2: + * + * &#064;Entity public class Address { + * ... + * &#064;TableGenerator( + * name="addressGen", + * table="ID_GEN", + * pkColumnName="GEN_KEY", + * valueColumnName="GEN_VALUE", + * pkColumnValue="ADDR_ID") + * &#064;Id + * &#064;GeneratedValue(strategy=TABLE, generator="addressGen") + * int id; + * ... + * } + * </pre> + * + * @see GeneratedValue + * @since Java Persistence 1.0 */ -@Target({TYPE, METHOD, FIELD}) +@Target({ TYPE, METHOD, FIELD }) @Retention(RUNTIME) public @interface TableGenerator { /** - * A unique generator name that can be referenced by one or more classes to be the generator for id values + * (Required) A unique generator name that can be referenced + * by one or more classes to be the generator for id values. */ String name(); + /** - * Name of table that stores the generated id values. Defaults to a name chosen by persistence provider. + * (Optional) Name of table that stores the generated id values. + * <p/> + * Defaults to a name chosen by persistence provider. */ String table() default ""; + /** - * The catalog of the table - * Defaults to the default catalog + * (Optional) The catalog of the table. + * <p/> + * Defaults to the default catalog. */ String catalog() default ""; + /** - * The schema of the table - * Defaults to the default schema for user + * (Optional) The schema of the table. + * <p/> + * Defaults to the default schema for user. */ String schema() default ""; + /** - * Name of the primary key column in the table - * Defaults to a provider-chosen name + * (Optional) Name of the primary key column in the table. + * <p/> + * Defaults to a provider-chosen name. */ String pkColumnName() default ""; + /** - * Name of the column that stores the last value generated - * Defaults to a provider-chosen name + * (Optional) Name of the column that stores the last value generated. + * <p/> + * Defaults to a provider-chosen name. */ String valueColumnName() default ""; + /** - * The primary key value in the generator table that distinguishes this set of generated values from others that may be stored in the table - * Defaults to a provider-chosen value to store in the primary key column of the generator table + * (Optional) The primary key value in the generator table + * that distinguishes this set of generated values from others + * that may be stored in the table. + * <p/> + * Defaults to a provider-chosen value to store in the + * primary key column of the generator table */ String pkColumnValue() default ""; + /** - * The initial value to be used when allocating id numbers from the generator + * (Optional) The initial value to be used to initialize the column + * that stores the last value generated. */ int initialValue() default 0; + /** - * The amount to increment by when allocating id numbers from the generator + * (Optional) The amount to increment by when allocating id + * numbers from the generator. */ int allocationSize() default 50; + /** - * Unique constraints that are to be placed on the table. These are only used if table generation is in effect. These constraints apply in addition to primary key constraints - * Defaults to no additional constraints + * (Optional) Unique constraints that are to be placed on the + * table. These are only used if table generation is in effect. + * These constraints apply in addition to primary key constraints. + * <p/> + * Defaults to no additional constraints. */ - UniqueConstraint[] uniqueConstraints() default {}; + UniqueConstraint[] uniqueConstraints() default { }; } Modified: jpa-api/trunk/src/main/java/javax/persistence/Temporal.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Temporal.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Temporal.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,26 +1,38 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.METHOD; -import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * This annotation must be specified for persistent fields or properties of type Date and Calendar. - * It may only be specified for fields or properties of these types. + * This annotation must be specified for persistent fields + * or properties of type <code>java.util.Date</code> and + * <code>java.util.Calendar</code>. It may only be specified for fields + * or properties of these types. + * <p/> + * The <code>Temporal</code> annotation may be used in + * conjunction with the {@link Basic} annotation, the {@link Id} + * annotation, or the {@link ElementCollection} annotation (when + * the element collection value is of such a temporal type. * - * The Temporal annotation may be used in conjunction with the Basic annotation. + * <pre> + * Example: * - * @author Emmanuel Bernard + * &#064;Temporal(DATE) + * protected java.util.Date endDate; + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) +@Target({ METHOD, FIELD }) @Retention(RUNTIME) public @interface Temporal { /** - * The type used in mapping java.util.Date or java.util.Calendar + * The type used in mapping <code>java.util.Date</code> or <code>java.util.Calendar</code>. */ TemporalType value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/TemporalType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TemporalType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/TemporalType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,21 +1,26 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -/** - * Type used to indicate a specific mapping of Date or Calendar. - */ -public enum TemporalType { - /** - * Map as java.sql.Date - */ - DATE, - /** - * Map as java.sql.Time - */ - TIME, - /** - * Map as java.sql.Timestamp - */ - TIMESTAMP +package javax.persistence; + +/** + * Type used to indicate a specific mapping of <code>java.util.Date</code> + * or <code>java.util.Calendar</code>. + * + * @since Java Persistence 1.0 + */ +public enum TemporalType { + /** + * Map as <code>java.sql.Date</code> + */ + DATE, + + /** + * Map as <code>java.sql.Time</code> + */ + TIME, + + /** + * Map as <code>java.sql.Timestamp</code> + */ + TIMESTAMP } Modified: jpa-api/trunk/src/main/java/javax/persistence/TransactionRequiredException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TransactionRequiredException.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/TransactionRequiredException.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,27 +1,29 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * Thrown by the persistence provider when a transaction is required but is not active. - * @author Gavin King + * Thrown by the persistence provider when a transaction is required but is not + * active. + * + * @since Java Persistence 1.0 */ public class TransactionRequiredException extends PersistenceException { - /** - * Constructs a new TransactionRequiredException exception with null as its detail message + * Constructs a new <code>TransactionRequiredException</code> exception with + * <code>null</code> as its detail message. */ public TransactionRequiredException() { super(); } /** - * Constructs a new TransactionRequiredException exception with the specified detail message - * - * @param message + * Constructs a new <code>TransactionRequiredException</code> exception with + * the specified detail message. + * + * @param message the detail message. */ public TransactionRequiredException(String message) { super( message ); } - } Modified: jpa-api/trunk/src/main/java/javax/persistence/Transient.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Transient.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Transient.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,18 +1,32 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * This annotation specifies that the property or field is not persistent. It is used to annotate - * a property or field of an entity class, mapped superclass, or embeddable class. - * - * @author Emmanuel Bernard + * Specifies that the property or field is not persistent. It is used + * to annotate a property or field of an entity class, mapped + * superclass, or embeddable class. + * + * <pre> + * Example: + * + * &#064;Entity + * public class Employee { + * &#064;Id int id; + * &#064;Transient User currentUser; + * ... + * } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) -public @interface Transient {} +@Target({ METHOD, FIELD }) +@Retention(RUNTIME) +public @interface Transient { +} Modified: jpa-api/trunk/src/main/java/javax/persistence/Tuple.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Tuple.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Tuple.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,4 +1,4 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; @@ -6,75 +6,93 @@ /** * Interface for extracting the elements of a query result tuple. + * + * @see TupleElement + * @since Java Persistence 2.0 */ public interface Tuple { + /** + * Get the value of the specified tuple element. + * + * @param tupleElement tuple element + * + * @return value of tuple element + * + * @throws IllegalArgumentException if tuple element + * does not correspond to an element in the + * query result tuple + */ + <X> X get(TupleElement<X> tupleElement); - /** - * Get the value of the specified tuple element. - * @param tupleElement tuple element - * @return value of tuple element - * @throws IllegalArgumentException if tuple element - * does not correspond to an element in the - * query result tuple - */ - <X> X get(TupleElement<X> tupleElement); + /** + * Get the value of the tuple element to which the + * specified alias has been assigned. + * + * @param alias alias assigned to tuple element + * @param type of the tuple element + * + * @return value of the tuple element + * + * @throws IllegalArgumentException if alias + * does not correspond to an element in the + * query result tuple or element cannot be + * assigned to the specified type + */ + <X> X get(String alias, Class<X> type); - /** - * Get the value of the tuple element to which the - * specified alias has been assigned. - * @param alias alias assigned to tuple element - * @param type of the tuple element - * @return value of the tuple element - * @throws IllegalArgumentException if alias - * does not correspond to an element in the - * query result tuple or element cannot be - * assigned to the specified type - */ - <X> X get(String alias, Class<X> type); + /** + * Get the value of the tuple element to which the + * specified alias has been assigned. + * + * @param alias alias assigned to tuple element + * + * @return value of the tuple element + * + * @throws IllegalArgumentException if alias + * does not correspond to an element in the + * query result tuple + */ + Object get(String alias); - /** - * Get the value of the tuple element to which the - * specified alias has been assigned. - * @param alias alias assigned to tuple element - * @return value of the tuple element - * @throws IllegalArgumentException if alias - * does not correspond to an element in the - * query result tuple - */ - Object get(String alias); + /** + * Get the value of the element at the specified + * position in the result tuple. The first position is 0. + * + * @param i position in result tuple + * @param type type of the tuple element + * + * @return value of the tuple element + * + * @throws IllegalArgumentException if i exceeds + * length of result tuple or element cannot be + * assigned to the specified type + */ + <X> X get(int i, Class<X> type); - /** - * Get the value of the element at the specified - * position in the result tuple. The first position is 0. - * @param i position in result tuple - * @param type type of the tuple element - * @return value of the tuple element - * @throws IllegalArgumentException if i exceeds - * length of result tuple or element cannot be - * assigned to the specified type - */ - <X> X get(int i, Class<X> type); + /** + * Get the value of the element at the specified + * position in the result tuple. The first position is 0. + * + * @param i position in result tuple + * + * @return value of the tuple element + * + * @throws IllegalArgumentException if i exceeds + * length of result tuple + */ + Object get(int i); - /** - * Get the value of the element at the specified - * position in the result tuple. The first position is 0. - * @param i position in result tuple - * @return value of the tuple element - * @throws IllegalArgumentException if i exceeds - * length of result tuple - */ - Object get(int i); + /** + * Return the values of the result tuple elements as an array. + * + * @return tuple element values + */ + Object[] toArray(); - /** - * Return the values of the result tuple elements as an array. - * @return tuple element values - */ - Object[] toArray(); - - /** - * Return the tuple elements - * @return tuple elements - */ - List<TupleElement<?>> getElements(); + /** + * Return the tuple elements. + * + * @return tuple elements + */ + List<TupleElement<?>> getElements(); } - Modified: jpa-api/trunk/src/main/java/javax/persistence/TupleElement.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TupleElement.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/TupleElement.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,24 +1,28 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; /** - * The TupleElement interface defines an element that is returned in + * The <code>TupleElement</code> interface defines an element that is returned in * a query result tuple. + * * @param <X> the type of the element + * @see Tuple + * @since Java Persistence 2.0 */ public interface TupleElement<X> { + /** + * Return the Java type of the tuple element. + * + * @return the Java type of the tuple element + */ + Class<? extends X> getJavaType(); - /** - * Return the Java type of the tuple element. - * @return the Java type of the tuple element - */ - Class<X> getJavaType(); - - /** - * Return the alias assigned to the tuple element or null, - * if no alias has been assigned. - * @return alias - */ - String getAlias(); + /** + * Return the alias assigned to the tuple element or null, + * if no alias has been assigned. + * + * @return alias + */ + String getAlias(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/TypedQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TypedQuery.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/TypedQuery.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -8,196 +8,262 @@ /** * Interface used to control the execution of typed queries. + * * @param <X> query result type + * @see Query + * @see Parameter + * @since Java Persistence 2.0 */ public interface TypedQuery<X> extends Query { - - /** - * Execute a SELECT query and return the query results - * as a typed List. - * @return a list of the results - * @throws IllegalStateException if called for a Java - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set - * @throws TransactionRequiredException if a lock mode has - * been set and there is no transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - */ - List<X> getResultList(); + /** + * Execute a SELECT query and return the query results + * as a typed List. + * + * @return a list of the results + * + * @throws IllegalStateException if called for a Java + * Persistence query language UPDATE or DELETE statement + * @throws QueryTimeoutException if the query execution exceeds + * the query timeout value set and only the statement is + * rolled back + * @throws TransactionRequiredException if a lock mode has + * been set and there is no transaction + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking + * fails and only the statement is rolled back + * @throws PersistenceException if the query execution exceeds + * the query timeout value set and the transaction + * is rolled back + */ + List<X> getResultList(); - /** - * Execute a SELECT query that returns a single result. - * @return the result - * @throws NoResultException if there is no result - * @throws NonUniqueResultException if more than one result - * @throws IllegalStateException if called for a Java - * Persistence query language UPDATE or DELETE statement - * @throws QueryTimeoutException if the query execution exceeds - * the query timeout value set - * @throws TransactionRequiredException if a lock mode has - * been set and there is no transaction - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking - * fails and only the statement is rolled back - */ - X getSingleResult(); + /** + * Execute a SELECT query that returns a single result. + * + * @return the result + * + * @throws NoResultException if there is no result + * @throws NonUniqueResultException if more than one result + * @throws IllegalStateException if called for a Java + * Persistence query language UPDATE or DELETE statement + * @throws QueryTimeoutException if the query execution exceeds + * the query timeout value set and only the statement is + * rolled back + * @throws TransactionRequiredException if a lock mode has + * been set and there is no transaction + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking + * fails and only the statement is rolled back + * @throws PersistenceException if the query execution exceeds + * the query timeout value set and the transaction + * is rolled back + */ + X getSingleResult(); - /** - * Set the maximum number of results to retrieve. - * @param maxResult - * @return the same query instance - * @throws IllegalArgumentException if argument is negative - */ - TypedQuery<X> setMaxResults(int maxResult); + /** + * Set the maximum number of results to retrieve. + * + * @param maxResult maximum number of results to retrieve + * + * @return the same query instance + * + * @throws IllegalArgumentException if the argument is negative + */ + TypedQuery<X> setMaxResults(int maxResult); - /** - * Set the position of the first result to retrieve. - * @param startPosition position of the first result, - * numbered from 0 - * @return the same query instance - * @throws IllegalArgumentException if argument is negative - */ - TypedQuery<X> setFirstResult(int startPosition); + /** + * Set the position of the first result to retrieve. + * + * @param startPosition position of the first result, + * numbered from 0 + * + * @return the same query instance + * + * @throws IllegalArgumentException if the argument is negative + */ + TypedQuery<X> setFirstResult(int startPosition); - /** - * Set a query hint. - * If a vendor-specific hint is not recognized, it is silently - * ignored. - * Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * @param hintName - * @param value - * @return the same query instance - * @throws IllegalArgumentException if the second argument is not - * valid for the implementation - */ - TypedQuery<X> setHint(String hintName, Object value); + /** + * Set a query property or hint. The hints elements may be used + * to specify query properties and hints. Properties defined by + * this specification must be observed by the provider. + * Vendor-specific hints that are not recognized by a provider + * must be silently ignored. Portable applications should not + * rely on the standard timeout hint. Depending on the database + * in use and the locking mechanisms used by the provider, + * this hint may or may not be observed. + * + * @param hintName name of property or hint + * @param value value for the property or hint + * + * @return the same query instance + * + * @throws IllegalArgumentException if the second argument is not + * valid for the implementation + */ + TypedQuery<X> setHint(String hintName, Object value); - /** - * Bind the value of a Parameter object. - * @param param parameter object - * @param value parameter value - * @return the same query instance - * @throws IllegalArgumentException if parameter - * does not correspond to a parameter of the - * query - */ - <T> TypedQuery<X> setParameter(Parameter<T> param, T value); + /** + * Bind the value of a <code>Parameter</code> object. + * + * @param param parameter object + * @param value parameter value + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter + * does not correspond to a parameter of the + * query + */ + <T> TypedQuery<X> setParameter(Parameter<T> param, T value); - /** - * Bind an instance of java.util.Date to a Parameter object. - * @param parameter object - * @param value - * @param temporalType - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a parameter of the query - */ - TypedQuery<X> setParameter(Parameter<Date> param, Date value, TemporalType temporalType); + /** + * Bind an instance of <code>java.util.Calendar</code> to a <code>Parameter</code> object. + * + * @param param parameter object + * @param value parameter value + * @param temporalType temporal type + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter does not + * correspond to a parameter of the query + */ + TypedQuery<X> setParameter(Parameter<Calendar> param, + Calendar value, + TemporalType temporalType); + /** + * Bind an instance of <code>java.util.Date</code> to a <code>Parameter</code> object. + * + * @param param parameter object + * @param value parameter value + * @param temporalType temporal type + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter does not + * correspond to a parameter of the query + */ + TypedQuery<X> setParameter(Parameter<Date> param, Date value, + TemporalType temporalType); - /** - * Bind an instance of java.util.Calendar to a Parameter object. - * @param parameter - * @param value - * @param temporalType - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a parameter of the query - */ - TypedQuery<X> setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType); + /** + * Bind an argument to a named parameter. + * + * @param name parameter name + * @param value parameter value + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter name does + * not correspond to a parameter of the query or if + * the argument is of incorrect type + */ + TypedQuery<X> setParameter(String name, Object value); - /** - * Bind an argument to a named parameter. - * @param name the parameter name - * @param value - * @return the same query instance - * @throws IllegalArgumentException if parameter name does not - * correspond to a parameter of the query or if - * the argument is of incorrect type - */ - TypedQuery<X> setParameter(String name, Object value); + /** + * Bind an instance of <code>java.util.Calendar</code> to a named parameter. + * + * @param name parameter name + * @param value parameter value + * @param temporalType temporal type + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter name does + * not correspond to a parameter of the query or if + * the value argument is of incorrect type + */ + TypedQuery<X> setParameter(String name, Calendar value, + TemporalType temporalType); - /** - * Bind an instance of java.util.Date to a named parameter. - * @param name - * @param value - * @param temporalType - * @return the same query instance - * @throws IllegalArgumentException if parameter name does not - * correspond to a parameter of the query - */ - TypedQuery<X> setParameter(String name, Date value, TemporalType temporalType); + /** + * Bind an instance of <code>java.util.Date</code> to a named parameter. + * + * @param name parameter name + * @param value parameter value + * @param temporalType temporal type + * + * @return the same query instance + * + * @throws IllegalArgumentException if the parameter name does + * not correspond to a parameter of the query or if + * the value argument is of incorrect type + */ + TypedQuery<X> setParameter(String name, Date value, + TemporalType temporalType); - /** - * Bind an instance of java.util.Calendar to a named parameter. - * @param name - * @param value - * @param temporalType - * @return the same query instance - * @throws IllegalArgumentException if parameter name does not - * correspond to a parameter of the query - */ - TypedQuery<X> setParameter(String name, Calendar value, TemporalType temporalType); + /** + * Bind an argument to a positional parameter. + * + * @param position position + * @param value parameter value + * + * @return the same query instance + * + * @throws IllegalArgumentException if position does not + * correspond to a positional parameter of the + * query or if the argument is of incorrect type + */ + TypedQuery<X> setParameter(int position, Object value); - /** - * Bind an argument to a positional parameter. - * @param position - * @param value - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the - * query or if the argument is of incorrect type - */ - TypedQuery<X> setParameter(int position, Object value); + /** + * Bind an instance of <code>java.util.Calendar</code> to a positional + * parameter. + * + * @param position position + * @param value parameter value + * @param temporalType temporal type + * + * @return the same query instance + * + * @throws IllegalArgumentException if position does not + * correspond to a positional parameter of the query + * or if the value argument is of incorrect type + */ + TypedQuery<X> setParameter(int position, Calendar value, + TemporalType temporalType); - /** - * Bind an instance of java.util.Date to a positional parameter. - * @param position - * @param value - * @param temporalType - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query - */ - TypedQuery<X> setParameter(int position, Date value, TemporalType temporalType); + /** + * Bind an instance of <code>java.util.Date</code> to a positional parameter. + * + * @param position position + * @param value parameter value + * @param temporalType temporal type + * + * @return the same query instance + * + * @throws IllegalArgumentException if position does not + * correspond to a positional parameter of the query + * or if the value argument is of incorrect type + */ + TypedQuery<X> setParameter(int position, Date value, + TemporalType temporalType); - /** - * Bind an instance of java.util.Calendar to a positional - * parameter. - * @param position - * @param value - * @param temporalType - * @return the same query instance - * @throws IllegalArgumentException if position does not - * correspond to a positional parameter of the query - */ - TypedQuery<X> setParameter(int position, Calendar value, TemporalType temporalType); + /** + * Set the flush mode type to be used for the query execution. + * The flush mode type applies to the query regardless of the + * flush mode type in use for the entity manager. + * + * @param flushMode flush mode + * + * @return the same query instance + */ + TypedQuery<X> setFlushMode(FlushModeType flushMode); - /** - * Set the flush mode type to be used for the query execution. - * The flush mode type applies to the query regardless of the - * flush mode type in use for the entity manager. - * @return the same query instance - * @param flushMode - */ - TypedQuery<X> setFlushMode(FlushModeType flushMode); - - /** - * Set the lock mode type to be used for the query execution. - * @param lockMode - * @return the same query instance - * @throws IllegalStateException if the query is found not to - * be a Java Persistence query language SELECT query - * or a Criteria API query - */ - TypedQuery<X> setLockMode(LockModeType lockMode); - + /** + * Set the lock mode type to be used for the query execution. + * + * @param lockMode lock mode + * + * @return the same query instance + * + * @throws IllegalStateException if the query is found not to + * be a Java Persistence query language SELECT query + * or a Criteria API query + */ + TypedQuery<X> setLockMode(LockModeType lockMode); } Modified: jpa-api/trunk/src/main/java/javax/persistence/UniqueConstraint.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/UniqueConstraint.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/UniqueConstraint.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,21 +1,41 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.RUNTIME; -import java.lang.annotation.Target; /** - * This annotation is used to specify that a unique constraint is to be included in the generated DDL - * for a primary or secondary table + * Specifies that a unique constraint is to be included in + * the generated DDL for a primary or secondary table. * - * @author Emmanuel Bernard + * <pre> + * Example: + * &#064;Entity + * &#064;Table( + * name="EMPLOYEE", + * uniqueConstraints= + * &#064;UniqueConstraint(columnNames={"EMP_ID", "EMP_NAME"}) + * ) + * public class Employee { ... } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({}) @Retention(RUNTIME) +@Target({ }) +@Retention(RUNTIME) public @interface UniqueConstraint { /** - * An array of the column names that make up the constraint + * (Optional) Constraint name. A provider-chosen name will be chosen + * if a name is not specified. + * + * @since Java Persistence 2.0 */ + String name() default ""; + + /** + * (Required) An array of the column names that make up the constraint. + */ String[] columnNames(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/ValidationMode.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ValidationMode.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/ValidationMode.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,10 +3,30 @@ package javax.persistence; /** - * @author Hardy Ferentschik + * The validation mode to be used by the provider for the persistence + * unit. + * + * @since Java Persistence 2.0 */ public enum ValidationMode { - AUTO, - CALLBACK, - NONE + /** + * If a Bean Validation provider is present in the environment, + * the persistence provider must perform the automatic validation + * of entities. If no Bean Validation provider is present in the + * environment, no lifecycle event validation takes place. + * This is the default behavior. + */ + AUTO, + + /** + * The persistence provider must perform the lifecycle event + * validation. It is an error if there is no Bean Validation + * provider present in the environment. + */ + CALLBACK, + + /** + * The persistence provider must not perform lifecycle event validation. + */ + NONE } Modified: jpa-api/trunk/src/main/java/javax/persistence/Version.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Version.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/Version.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,28 +1,44 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; +import java.lang.annotation.Target; import java.lang.annotation.Retention; -import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - /** - * This annotation specifies the version field or property of an entity class that serves as its - * optimistic lock value. The version is used to ensure integrity when performing the merge - * operation and for optimistic concurrency control. + * Specifies the version field or property of an entity class that + * serves as its optimistic lock value. The version is used to ensure + * integrity when performing the merge operation and for optimistic + * concurrency control. * - * Only a single Version property or field should be used per class; applications that use more - * than one Version property or field will not be portable. + * <p> Only a single <code>Version</code> property or field + * should be used per class; applications that use more than one + * <code>Version</code> property or field will not be portable. * - * The Version property should be mapped to the primary table for the entity class; applications - * that map the Version property to a table other than the primary table will not be portable. + * <p> The <code>Version</code> property should be mapped to + * the primary table for the entity class; applications that + * map the <code>Version</code> property to a table other than + * the primary table will not be portable. * - * The following types are supported for version properties: int, Integer, short, Short, long, - * Long, Timestamp. - * - * @author Emmanuel Bernard + * <p> The following types are supported for version properties: + * <code>int</code>, <code>Integer</code>, <code>short</code>, + * <code>Short</code>, <code>long</code>, <code>Long</code>, + * <code>java.sql.Timestamp</code>. + * + * <pre> + * Example: + * + * &#064;Version + * &#064;Column(name="OPTLOCK") + * protected int getVersionNum() { return versionNum; } + * </pre> + * + * @since Java Persistence 1.0 */ -@Target({METHOD, FIELD}) @Retention(RUNTIME) -public @interface Version {} +@Target({ METHOD, FIELD }) +@Retention(RUNTIME) +public @interface Version { +} Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/AbstractQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/AbstractQuery.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/AbstractQuery.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -8,165 +8,205 @@ import javax.persistence.metamodel.EntityType; /** - * The AbstractQuery interface defines functionality that is common + * The <code>AbstractQuery</code> interface defines functionality that is common * to both top-level queries and subqueries. * It is not intended to be used directly in query construction. * - * All queries must have: - * a set of root entities (which may in turn own joins) - * All queries may have: - * a conjunction of restrictions + * <p> All queries must have: + * a set of root entities (which may in turn own joins). + * <p> All queries may have: + * a conjunction of restrictions. + * + * @param <T> the type of the result + * @since Java Persistence 2.0 */ public interface AbstractQuery<T> { + /** + * Create and add a query root corresponding to the given entity, + * forming a cartesian product with any existing roots. + * + * @param entityClass the entity class + * + * @return query root corresponding to the given entity + */ + <X> Root<X> from(Class<X> entityClass); - /** - * Add a query root corresponding to the given entity, - * forming a cartesian product with any existing roots. - * @param entityClass the entity class - * @return query root corresponding to the given entity - */ - <X> Root<X> from(Class<X> entityClass); + /** + * Create and add a query root corresponding to the given entity, + * forming a cartesian product with any existing roots. + * + * @param entity metamodel entity representing the entity + * of type X + * + * @return query root corresponding to the given entity + */ + <X> Root<X> from(EntityType<X> entity); - /** - * Add a query root corresponding to the given entity, - * forming a cartesian product with any existing roots. - * @param entity metamodel entity representing the entity - * of type X - * @return query root corresponding to the given entity - */ - <X> Root<X> from(EntityType<X> entity); + /** + * Modify the query to restrict the query results according + * to the specified boolean expression. + * Replaces the previously added restriction(s), if any. + * + * @param restriction a simple or compound boolean expression + * + * @return the modified query + */ + AbstractQuery<T> where(Expression<Boolean> restriction); - /** - * Modify the query to restrict the query results according - * to the specified boolean expression. - * Replaces the previously added restriction(s), if any. - * @param restriction a simple or compound boolean expression - * @return the modified query - */ - AbstractQuery<T> where(Expression<Boolean> restriction); + /** + * Modify the query to restrict the query results according + * to the conjunction of the specified restriction predicates. + * Replaces the previously added restriction(s), if any. + * If no restrictions are specified, any previously added + * restrictions are simply removed. + * + * @param restrictions zero or more restriction predicates + * + * @return the modified query + */ + AbstractQuery<T> where(Predicate... restrictions); - /** - * Modify the query to restrict the query results according - * to the conjunction of the specified restriction predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * @param restrictions zero or more restriction predicates - * @return the modified query - */ - AbstractQuery<T> where(Predicate... restrictions); + /** + * Specify the expressions that are used to form groups over + * the query results. + * Replaces the previous specified grouping expressions, if any. + * If no grouping expressions are specified, any previously + * added grouping expressions are simply removed. + * + * @param grouping zero or more grouping expressions + * + * @return the modified query + */ + AbstractQuery<T> groupBy(Expression<?>... grouping); - /** - * Specify the expressions that are used to form groups over - * the query results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * @param grouping zero or more grouping expressions - * @return the modified query - */ - AbstractQuery<T> groupBy(Expression<?>... grouping); - /** * Specify the expressions that are used to form groups over * the query results. * Replaces the previous specified grouping expressions, if any. * If no grouping expressions are specified, any previously * added grouping expressions are simply removed. + * * @param grouping list of zero or more grouping expressions + * * @return the modified query */ AbstractQuery<T> groupBy(List<Expression<?>> grouping); - /** - * Specify a restriction over the groups of the query. - * Replaces the previous having restriction(s), if any. - * @param restriction a simple or compound boolean expression - * @return the modified query - */ - AbstractQuery<T> having(Expression<Boolean> restriction); + /** + * Specify a restriction over the groups of the query. + * Replaces the previous having restriction(s), if any. + * + * @param restriction a simple or compound boolean expression + * + * @return the modified query + */ + AbstractQuery<T> having(Expression<Boolean> restriction); - /** - * Specify restrictions over the groups of the query - * according the conjunction of the specified restriction - * predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * @param restrictions zero or more restriction predicates - * @return the modified query - */ - AbstractQuery<T> having(Predicate... restrictions); + /** + * Specify restrictions over the groups of the query + * according the conjunction of the specified restriction + * predicates. + * Replaces the previously having added restriction(s), if any. + * If no restrictions are specified, any previously added + * restrictions are simply removed. + * + * @param restrictions zero or more restriction predicates + * + * @return the modified query + */ + AbstractQuery<T> having(Predicate... restrictions); - /** - * Specify whether duplicate query results will be eliminated. - * A true value will cause duplicates to be eliminated. - * A false value will cause duplicates to be retained. - * If distinct has not been specified, duplicate results must - * be retained. - * @param distinct boolean value specifying whether duplicate - * results must be eliminated from the query result or - * whether they must be retained - * @return the modified query. - */ - AbstractQuery<T> distinct(boolean distinct); + /** + * Specify whether duplicate query results will be eliminated. + * A true value will cause duplicates to be eliminated. + * A false value will cause duplicates to be retained. + * If distinct has not been specified, duplicate results must + * be retained. + * + * @param distinct boolean value specifying whether duplicate + * results must be eliminated from the query result or + * whether they must be retained + * + * @return the modified query + */ + AbstractQuery<T> distinct(boolean distinct); - /** - * Create a subquery of the query. - * @param type the subquery result type - * @return subquery - */ - <U> Subquery<U> subquery(Class<U> type); + /** + * Create a subquery of the query. + * + * @param type the subquery result type + * + * @return subquery + */ + <U> Subquery<U> subquery(Class<U> type); - /** - * Return the query roots. - * @return the set of query roots - */ - Set<Root<?>> getRoots(); + /** + * Return the query roots. These are the roots that have + * been defined for the <code>CriteriaQuery</code> or <code>Subquery</code> itself, + * including any subquery roots defined as a result of + * correlation. Returns empty set if no roots have been defined. + * Modifications to the set do not affect the query. + * + * @return the set of query roots + */ + Set<Root<?>> getRoots(); - /** - * Return the selection of the query - * @return selection item - */ - Selection<T> getSelection(); + /** + * Return the selection of the query, or null if no selection + * has been set. + * + * @return selection item + */ + Selection<T> getSelection(); - /** - * Return the predicate that corresponds to the where clause - * restriction(s). - * @return where clause predicate - */ - Predicate getRestriction(); + /** + * Return the predicate that corresponds to the where clause + * restriction(s), or null if no restrictions have been + * specified. + * + * @return where clause predicate + */ + Predicate getRestriction(); - /** - * Return a list of the grouping expressions - * @return the list of grouping expressions - */ - List<Expression<?>> getGroupList(); + /** + * Return a list of the grouping expressions. Returns empty + * list if no grouping expressions have been specified. + * Modifications to the list do not affect the query. + * + * @return the list of grouping expressions + */ + List<Expression<?>> getGroupList(); - /** - * Return the predicate that corresponds to the restriction(s) - * over the grouping items. - * @return having clause predicate - */ - Predicate getGroupRestriction(); + /** + * Return the predicate that corresponds to the restriction(s) + * over the grouping items, or null if no restrictions have + * been specified. + * + * @return having clause predicate + */ + Predicate getGroupRestriction(); - /** - * Return whether duplicate query results must be eliminated or - * retained. - * @return boolean indicating whether duplicate query results must - * be eliminated - */ - boolean isDistinct(); + /** + * Return whether duplicate query results must be eliminated or + * retained. + * + * @return boolean indicating whether duplicate query results + * must be eliminated + */ + boolean isDistinct(); /** - * Return the result type of the query or subquery. - * If a result type was specified as an argument to the - * createQuery or subquery method, that type will be returned. - * If the query was created using the createTupleQuery - * method, the result type is Tuple. - * Otherwise, the result type is Object. + * Return the result type of the query or subquery. If a result + * type was specified as an argument to the + * <code>createQuery</code> or <code>subquery</code> method, that + * type will be returned. If the query was created using the + * <code>createTupleQuery</code> method, the result type is + * <code>Tuple</code>. Otherwise, the result type is + * <code>Object</code>. + * * @return result type */ Class<T> getResultType(); } + Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/CollectionJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/CollectionJoin.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/CollectionJoin.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,20 +6,22 @@ import javax.persistence.metamodel.CollectionAttribute; /** - * The CollectionJoin interface is the type of the result of + * The <code>CollectionJoin</code> interface is the type of the result of * joining to a collection over an association or element - * collection that has been specified as a java.util.Collection. + * collection that has been specified as a <code>java.util.Collection</code>. * - * @param <Z> The source type of the join - * @param <E> The element type of the target Collection + * @param <Z> the source type of the join + * @param <E> the element type of the target <code>Collection</code> + * @since Java Persistence 2.0 */ -public interface CollectionJoin<Z, E> extends PluralJoin<Z, Collection<E>, E> { +public interface CollectionJoin<Z, E> + extends PluralJoin<Z, Collection<E>, E> { /** * Return the metamodel representation for the collection * attribute. * - * @return metamodel type representing the Collection that is + * @return metamodel type representing the <code>Collection</code> that is * the target of the join */ CollectionAttribute<? super Z, E> getModel(); Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/CompoundSelection.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/CompoundSelection.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/CompoundSelection.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,11 +1,14 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.criteria; /** - * The CompoundSelection interface defines compound selection item + * The <code>CompoundSelection</code> interface defines a compound selection item * (tuple, array, or result of constructor). + * * @param <X> the type of the selection item + * + * @since Java Persistence 2.0 */ public interface CompoundSelection<X> extends Selection<X> { } \ No newline at end of file Copied: jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaBuilder.java (from rev 17525, jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java) =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaBuilder.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaBuilder.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -0,0 +1,1725 @@ +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence.criteria; + +import java.math.BigDecimal; +import java.math.BigInteger; +import java.util.Collection; +import java.util.Map; +import java.util.Set; +import javax.persistence.Tuple; + +/** + * Used to construct criteria queries, compound selections, + * expressions, predicates, orderings. + * + * <p> Note that <code>Predicate</code> is used instead of <code>Expression&#060;Boolean&#062;</code> + * in this API in order to work around the fact that Java + * generics are not compatible with varags. + * + * @since Java Persistence 2.0 + */ +public interface CriteriaBuilder { + + /** + * Create a <code>CriteriaQuery</code> object. + * + * @return criteria query object + */ + CriteriaQuery<Object> createQuery(); + + /** + * Create a <code>CriteriaQuery</code> object with the specified result + * type. + * + * @param resultClass type of the query result + * + * @return criteria query object + */ + <T> CriteriaQuery<T> createQuery(Class<T> resultClass); + + /** + * Create a <code>CriteriaQuery</code> object that returns a tuple of + * objects as its result. + * + * @return criteria query object + */ + CriteriaQuery<Tuple> createTupleQuery(); + + + // selection construction methods: + + /** + * Create a selection item corresponding to a constructor. + * This method is used to specify a constructor that will be + * applied to the results of the query execution. If the + * constructor is for an entity class, the resulting entities + * will be in the new state after the query is executed. + * + * @param resultClass class whose instance is to be constructed + * @param selections arguments to the constructor + * + * @return compound selection item + * + * @throws IllegalArgumentException if an argument is a + * tuple- or array-valued selection item + */ + <Y> CompoundSelection<Y> construct(Class<Y> resultClass, Selection<?>... selections); + + /** + * Create a tuple-valued selection item. + * + * @param selections selection items + * + * @return tuple-valued compound selection + * + * @throws IllegalArgumentException if an argument is a + * tuple- or array-valued selection item + */ + CompoundSelection<Tuple> tuple(Selection<?>... selections); + + /** + * Create an array-valued selection item. + * + * @param selections selection items + * + * @return array-valued compound selection + * + * @throws IllegalArgumentException if an argument is a + * tuple- or array-valued selection item + */ + CompoundSelection<Object[]> array(Selection<?>... selections); + + + //ordering: + + /** + * Create an ordering by the ascending value of the expression. + * + * @param x expression used to define the ordering + * + * @return ascending ordering corresponding to the expression + */ + Order asc(Expression<?> x); + + /** + * Create an ordering by the descending value of the expression. + * + * @param x expression used to define the ordering + * + * @return descending ordering corresponding to the expression + */ + Order desc(Expression<?> x); + + + //aggregate functions: + + /** + * Create an aggregate expression applying the avg operation. + * + * @param x expression representing input value to avg operation + * + * @return avg expression + */ + <N extends Number> Expression<Double> avg(Expression<N> x); + + /** + * Create an aggregate expression applying the sum operation. + * + * @param x expression representing input value to sum operation + * + * @return sum expression + */ + <N extends Number> Expression<N> sum(Expression<N> x); + + /** + * Create an aggregate expression applying the sum operation to an + * Integer-valued expression, returning a Long result. + * + * @param x expression representing input value to sum operation + * + * @return sum expression + */ + Expression<Long> sumAsLong(Expression<Integer> x); + + /** + * Create an aggregate expression applying the sum operation to a + * Float-valued expression, returning a Double result. + * + * @param x expression representing input value to sum operation + * + * @return sum expression + */ + Expression<Double> sumAsDouble(Expression<Float> x); + + /** + * Create an aggregate expression applying the numerical max + * operation. + * + * @param x expression representing input value to max operation + * + * @return max expression + */ + <N extends Number> Expression<N> max(Expression<N> x); + + /** + * Create an aggregate expression applying the numerical min + * operation. + * + * @param x expression representing input value to min operation + * + * @return min expression + */ + <N extends Number> Expression<N> min(Expression<N> x); + + /** + * Create an aggregate expression for finding the greatest of + * the values (strings, dates, etc). + * + * @param x expression representing input value to greatest + * operation + * + * @return greatest expression + */ + <X extends Comparable<? super X>> Expression<X> greatest(Expression<X> x); + + /** + * Create an aggregate expression for finding the least of + * the values (strings, dates, etc). + * + * @param x expression representing input value to least + * operation + * + * @return least expression + */ + <X extends Comparable<? super X>> Expression<X> least(Expression<X> x); + + /** + * Create an aggregate expression applying the count operation. + * + * @param x expression representing input value to count + * operation + * + * @return count expression + */ + Expression<Long> count(Expression<?> x); + + /** + * Create an aggregate expression applying the count distinct + * operation. + * + * @param x expression representing input value to + * count distinct operation + * + * @return count distinct expression + */ + Expression<Long> countDistinct(Expression<?> x); + + + //subqueries: + + /** + * Create a predicate testing the existence of a subquery result. + * + * @param subquery subquery whose result is to be tested + * + * @return exists predicate + */ + Predicate exists(Subquery<?> subquery); + + /** + * Create an all expression over the subquery results. + * + * @param subquery subquery + * + * @return all expression + */ + <Y> Expression<Y> all(Subquery<Y> subquery); + + /** + * Create a some expression over the subquery results. + * This expression is equivalent to an <code>any</code> expression. + * + * @param subquery subquery + * + * @return some expression + */ + <Y> Expression<Y> some(Subquery<Y> subquery); + + /** + * Create an any expression over the subquery results. + * This expression is equivalent to a <code>some</code> expression. + * + * @param subquery subquery + * + * @return any expression + */ + <Y> Expression<Y> any(Subquery<Y> subquery); + + + //boolean functions: + + /** + * Create a conjunction of the given boolean expressions. + * + * @param x boolean expression + * @param y boolean expression + * + * @return and predicate + */ + Predicate and(Expression<Boolean> x, Expression<Boolean> y); + + /** + * Create a conjunction of the given restriction predicates. + * A conjunction of zero predicates is true. + * + * @param restrictions zero or more restriction predicates + * + * @return and predicate + */ + Predicate and(Predicate... restrictions); + + /** + * Create a disjunction of the given boolean expressions. + * + * @param x boolean expression + * @param y boolean expression + * + * @return or predicate + */ + Predicate or(Expression<Boolean> x, Expression<Boolean> y); + + /** + * Create a disjunction of the given restriction predicates. + * A disjunction of zero predicates is false. + * + * @param restrictions zero or more restriction predicates + * + * @return or predicate + */ + Predicate or(Predicate... restrictions); + + /** + * Create a negation of the given restriction. + * + * @param restriction restriction expression + * + * @return not predicate + */ + Predicate not(Expression<Boolean> restriction); + + /** + * Create a conjunction (with zero conjuncts). + * A conjunction with zero conjuncts is true. + * + * @return and predicate + */ + Predicate conjunction(); + + /** + * Create a disjunction (with zero disjuncts). + * A disjunction with zero disjuncts is false. + * + * @return or predicate + */ + Predicate disjunction(); + + + //turn Expression<Boolean> into a Predicate + //useful for use with varargs methods + + /** + * Create a predicate testing for a true value. + * + * @param x expression to be tested + * + * @return predicate + */ + Predicate isTrue(Expression<Boolean> x); + + /** + * Create a predicate testing for a false value. + * + * @param x expression to be tested + * + * @return predicate + */ + Predicate isFalse(Expression<Boolean> x); + + + //null tests: + + /** + * Create a predicate to test whether the expression is null. + * + * @param x expression + * + * @return is-null predicate + */ + Predicate isNull(Expression<?> x); + + /** + * Create a predicate to test whether the expression is not null. + * + * @param x expression + * + * @return is-not-null predicate + */ + Predicate isNotNull(Expression<?> x); + + //equality: + + /** + * Create a predicate for testing the arguments for equality. + * + * @param x expression + * @param y expression + * + * @return equality predicate + */ + Predicate equal(Expression<?> x, Expression<?> y); + + /** + * Create a predicate for testing the arguments for equality. + * + * @param x expression + * @param y object + * + * @return equality predicate + */ + Predicate equal(Expression<?> x, Object y); + + /** + * Create a predicate for testing the arguments for inequality. + * + * @param x expression + * @param y expression + * + * @return inequality predicate + */ + Predicate notEqual(Expression<?> x, Expression<?> y); + + /** + * Create a predicate for testing the arguments for inequality. + * + * @param x expression + * @param y object + * + * @return inequality predicate + */ + Predicate notEqual(Expression<?> x, Object y); + + + //comparisons for generic (non-numeric) operands: + + /** + * Create a predicate for testing whether the first argument is + * greater than the second. + * + * @param x expression + * @param y expression + * + * @return greater-than predicate + */ + <Y extends Comparable<? super Y>> Predicate greaterThan(Expression<? extends Y> x, Expression<? extends Y> y); + + /** + * Create a predicate for testing whether the first argument is + * greater than the second. + * + * @param x expression + * @param y value + * + * @return greater-than predicate + */ + <Y extends Comparable<? super Y>> Predicate greaterThan(Expression<? extends Y> x, Y y); + + /** + * Create a predicate for testing whether the first argument is + * greater than or equal to the second. + * + * @param x expression + * @param y expression + * + * @return greater-than-or-equal predicate + */ + <Y extends Comparable<? super Y>> Predicate greaterThanOrEqualTo(Expression<? extends Y> x, Expression<? extends Y> y); + + /** + * Create a predicate for testing whether the first argument is + * greater than or equal to the second. + * + * @param x expression + * @param y value + * + * @return greater-than-or-equal predicate + */ + <Y extends Comparable<? super Y>> Predicate greaterThanOrEqualTo(Expression<? extends Y> x, Y y); + + /** + * Create a predicate for testing whether the first argument is + * less than the second. + * + * @param x expression + * @param y expression + * + * @return less-than predicate + */ + <Y extends Comparable<? super Y>> Predicate lessThan(Expression<? extends Y> x, Expression<? extends Y> y); + + /** + * Create a predicate for testing whether the first argument is + * less than the second. + * + * @param x expression + * @param y value + * + * @return less-than predicate + */ + <Y extends Comparable<? super Y>> Predicate lessThan(Expression<? extends Y> x, Y y); + + /** + * Create a predicate for testing whether the first argument is + * less than or equal to the second. + * + * @param x expression + * @param y expression + * + * @return less-than-or-equal predicate + */ + <Y extends Comparable<? super Y>> Predicate lessThanOrEqualTo(Expression<? extends Y> x, Expression<? extends Y> y); + + /** + * Create a predicate for testing whether the first argument is + * less than or equal to the second. + * + * @param x expression + * @param y value + * + * @return less-than-or-equal predicate + */ + <Y extends Comparable<? super Y>> Predicate lessThanOrEqualTo(Expression<? extends Y> x, Y y); + + /** + * Create a predicate for testing whether the first argument is + * between the second and third arguments in value. + * + * @param v expression + * @param x expression + * @param y expression + * + * @return between predicate + */ + <Y extends Comparable<? super Y>> Predicate between(Expression<? extends Y> v, Expression<? extends Y> x, Expression<? extends Y> y); + + /** + * Create a predicate for testing whether the first argument is + * between the second and third arguments in value. + * + * @param v expression + * @param x value + * @param y value + * + * @return between predicate + */ + <Y extends Comparable<? super Y>> Predicate between(Expression<? extends Y> v, Y x, Y y); + + + //comparisons for numeric operands: + + /** + * Create a predicate for testing whether the first argument is + * greater than the second. + * + * @param x expression + * @param y expression + * + * @return greater-than predicate + */ + Predicate gt(Expression<? extends Number> x, Expression<? extends Number> y); + + /** + * Create a predicate for testing whether the first argument is + * greater than the second. + * + * @param x expression + * @param y value + * + * @return greater-than predicate + */ + Predicate gt(Expression<? extends Number> x, Number y); + + /** + * Create a predicate for testing whether the first argument is + * greater than or equal to the second. + * + * @param x expression + * @param y expression + * + * @return greater-than-or-equal predicate + */ + Predicate ge(Expression<? extends Number> x, Expression<? extends Number> y); + + /** + * Create a predicate for testing whether the first argument is + * greater than or equal to the second. + * + * @param x expression + * @param y value + * + * @return greater-than-or-equal predicate + */ + Predicate ge(Expression<? extends Number> x, Number y); + + /** + * Create a predicate for testing whether the first argument is + * less than the second. + * + * @param x expression + * @param y expression + * + * @return less-than predicate + */ + Predicate lt(Expression<? extends Number> x, Expression<? extends Number> y); + + /** + * Create a predicate for testing whether the first argument is + * less than the second. + * + * @param x expression + * @param y value + * + * @return less-than predicate + */ + Predicate lt(Expression<? extends Number> x, Number y); + + /** + * Create a predicate for testing whether the first argument is + * less than or equal to the second. + * + * @param x expression + * @param y expression + * + * @return less-than-or-equal predicate + */ + Predicate le(Expression<? extends Number> x, Expression<? extends Number> y); + + /** + * Create a predicate for testing whether the first argument is + * less than or equal to the second. + * + * @param x expression + * @param y value + * + * @return less-than-or-equal predicate + */ + Predicate le(Expression<? extends Number> x, Number y); + + + //numerical operations: + + /** + * Create an expression that returns the arithmetic negation + * of its argument. + * + * @param x expression + * + * @return arithmetic negation + */ + <N extends Number> Expression<N> neg(Expression<N> x); + + /** + * Create an expression that returns the absolute value + * of its argument. + * + * @param x expression + * + * @return absolute value + */ + <N extends Number> Expression<N> abs(Expression<N> x); + + /** + * Create an expression that returns the sum + * of its arguments. + * + * @param x expression + * @param y expression + * + * @return sum + */ + <N extends Number> Expression<N> sum(Expression<? extends N> x, Expression<? extends N> y); + + /** + * Create an expression that returns the sum + * of its arguments. + * + * @param x expression + * @param y value + * + * @return sum + */ + <N extends Number> Expression<N> sum(Expression<? extends N> x, N y); + + /** + * Create an expression that returns the sum + * of its arguments. + * + * @param x value + * @param y expression + * + * @return sum + */ + <N extends Number> Expression<N> sum(N x, Expression<? extends N> y); + + /** + * Create an expression that returns the product + * of its arguments. + * + * @param x expression + * @param y expression + * + * @return product + */ + <N extends Number> Expression<N> prod(Expression<? extends N> x, Expression<? extends N> y); + + /** + * Create an expression that returns the product + * of its arguments. + * + * @param x expression + * @param y value + * + * @return product + */ + <N extends Number> Expression<N> prod(Expression<? extends N> x, N y); + + /** + * Create an expression that returns the product + * of its arguments. + * + * @param x value + * @param y expression + * + * @return product + */ + <N extends Number> Expression<N> prod(N x, Expression<? extends N> y); + + /** + * Create an expression that returns the difference + * between its arguments. + * + * @param x expression + * @param y expression + * + * @return difference + */ + <N extends Number> Expression<N> diff(Expression<? extends N> x, Expression<? extends N> y); + + /** + * Create an expression that returns the difference + * between its arguments. + * + * @param x expression + * @param y value + * + * @return difference + */ + <N extends Number> Expression<N> diff(Expression<? extends N> x, N y); + + /** + * Create an expression that returns the difference + * between its arguments. + * + * @param x value + * @param y expression + * + * @return difference + */ + <N extends Number> Expression<N> diff(N x, Expression<? extends N> y); + + /** + * Create an expression that returns the quotient + * of its arguments. + * + * @param x expression + * @param y expression + * + * @return quotient + */ + Expression<Number> quot(Expression<? extends Number> x, Expression<? extends Number> y); + + /** + * Create an expression that returns the quotient + * of its arguments. + * + * @param x expression + * @param y value + * + * @return quotient + */ + Expression<Number> quot(Expression<? extends Number> x, Number y); + + /** + * Create an expression that returns the quotient + * of its arguments. + * + * @param x value + * @param y expression + * + * @return quotient + */ + Expression<Number> quot(Number x, Expression<? extends Number> y); + + /** + * Create an expression that returns the modulus + * of its arguments. + * + * @param x expression + * @param y expression + * + * @return modulus + */ + Expression<Integer> mod(Expression<Integer> x, Expression<Integer> y); + + /** + * Create an expression that returns the modulus + * of its arguments. + * + * @param x expression + * @param y value + * + * @return modulus + */ + Expression<Integer> mod(Expression<Integer> x, Integer y); + + /** + * Create an expression that returns the modulus + * of its arguments. + * + * @param x value + * @param y expression + * + * @return modulus + */ + Expression<Integer> mod(Integer x, Expression<Integer> y); + + /** + * Create an expression that returns the square root + * of its argument. + * + * @param x expression + * + * @return square root + */ + Expression<Double> sqrt(Expression<? extends Number> x); + + + //typecasts: + + /** + * Typecast. Returns same expression object. + * + * @param number numeric expression + * + * @return Expression&#060;Long&#062; + */ + Expression<Long> toLong(Expression<? extends Number> number); + + /** + * Typecast. Returns same expression object. + * + * @param number numeric expression + * + * @return Expression&#060;Integer&#062; + */ + Expression<Integer> toInteger(Expression<? extends Number> number); + + /** + * Typecast. Returns same expression object. + * + * @param number numeric expression + * + * @return Expression&#060;Float&#062; + */ + Expression<Float> toFloat(Expression<? extends Number> number); + + /** + * Typecast. Returns same expression object. + * + * @param number numeric expression + * + * @return Expression&#060;Double&#062; + */ + Expression<Double> toDouble(Expression<? extends Number> number); + + /** + * Typecast. Returns same expression object. + * + * @param number numeric expression + * + * @return Expression&#060;BigDecimal&#062; + */ + Expression<BigDecimal> toBigDecimal(Expression<? extends Number> number); + + /** + * Typecast. Returns same expression object. + * + * @param number numeric expression + * + * @return Expression&#060;BigInteger&#062; + */ + Expression<BigInteger> toBigInteger(Expression<? extends Number> number); + + /** + * Typecast. Returns same expression object. + * + * @param character expression + * + * @return Expression&#060;String&#062; + */ + Expression<String> toString(Expression<Character> character); + + + //literals: + + /** + * Create an expression for a literal. + * + * @param value value represented by the expression + * + * @return expression literal + * + * @throws IllegalArgumentException if value is null + */ + <T> Expression<T> literal(T value); + + /** + * Create an expression for a null literal with the given type. + * + * @param resultClass type of the null literal + * + * @return null expression literal + */ + <T> Expression<T> nullLiteral(Class<T> resultClass); + + //parameters: + + /** + * Create a parameter expression. + * + * @param paramClass parameter class + * + * @return parameter expression + */ + <T> ParameterExpression<T> parameter(Class<T> paramClass); + + /** + * Create a parameter expression with the given name. + * + * @param paramClass parameter class + * @param name name that can be used to refer to + * the parameter + * + * @return parameter expression + */ + <T> ParameterExpression<T> parameter(Class<T> paramClass, String name); + + + //collection operations: + + /** + * Create a predicate that tests whether a collection is empty. + * + * @param collection expression + * + * @return is-empty predicate + */ + <C extends Collection<?>> Predicate isEmpty(Expression<C> collection); + + /** + * Create a predicate that tests whether a collection is + * not empty. + * + * @param collection expression + * + * @return is-not-empty predicate + */ + <C extends Collection<?>> Predicate isNotEmpty(Expression<C> collection); + + /** + * Create an expression that tests the size of a collection. + * + * @param collection expression + * + * @return size expression + */ + <C extends java.util.Collection<?>> Expression<Integer> size(Expression<C> collection); + + /** + * Create an expression that tests the size of a collection. + * + * @param collection collection + * + * @return size expression + */ + <C extends Collection<?>> Expression<Integer> size(C collection); + + /** + * Create a predicate that tests whether an element is + * a member of a collection. + * If the collection is empty, the predicate will be false. + * + * @param elem element expression + * @param collection expression + * + * @return is-member predicate + */ + <E, C extends Collection<E>> Predicate isMember(Expression<E> elem, Expression<C> collection); + + /** + * Create a predicate that tests whether an element is + * a member of a collection. + * If the collection is empty, the predicate will be false. + * + * @param elem element + * @param collection expression + * + * @return is-member predicate + */ + <E, C extends Collection<E>> Predicate isMember(E elem, Expression<C> collection); + + /** + * Create a predicate that tests whether an element is + * not a member of a collection. + * If the collection is empty, the predicate will be true. + * + * @param elem element expression + * @param collection expression + * + * @return is-not-member predicate + */ + <E, C extends Collection<E>> Predicate isNotMember(Expression<E> elem, Expression<C> collection); + + /** + * Create a predicate that tests whether an element is + * not a member of a collection. + * If the collection is empty, the predicate will be true. + * + * @param elem element + * @param collection expression + * + * @return is-not-member predicate + */ + <E, C extends Collection<E>> Predicate isNotMember(E elem, Expression<C> collection); + + + //get the values and keys collections of the Map, which may then + //be passed to size(), isMember(), isEmpty(), etc + + /** + * Create an expression that returns the values of a map. + * + * @param map map + * + * @return collection expression + */ + <V, M extends Map<?, V>> Expression<Collection<V>> values(M map); + + /** + * Create an expression that returns the keys of a map. + * + * @param map map + * + * @return set expression + */ + <K, M extends Map<K, ?>> Expression<Set<K>> keys(M map); + + + //string functions: + + /** + * Create a predicate for testing whether the expression + * satisfies the given pattern. + * + * @param x string expression + * @param pattern string expression + * + * @return like predicate + */ + Predicate like(Expression<String> x, Expression<String> pattern); + + /** + * Create a predicate for testing whether the expression + * satisfies the given pattern. + * + * @param x string expression + * @param pattern string + * + * @return like predicate + */ + Predicate like(Expression<String> x, String pattern); + + /** + * Create a predicate for testing whether the expression + * satisfies the given pattern. + * + * @param x string expression + * @param pattern string expression + * @param escapeChar escape character expression + * + * @return like predicate + */ + Predicate like(Expression<String> x, Expression<String> pattern, Expression<Character> escapeChar); + + /** + * Create a predicate for testing whether the expression + * satisfies the given pattern. + * + * @param x string expression + * @param pattern string expression + * @param escapeChar escape character + * + * @return like predicate + */ + Predicate like(Expression<String> x, Expression<String> pattern, char escapeChar); + + /** + * Create a predicate for testing whether the expression + * satisfies the given pattern. + * + * @param x string expression + * @param pattern string + * @param escapeChar escape character expression + * + * @return like predicate + */ + Predicate like(Expression<String> x, String pattern, Expression<Character> escapeChar); + + /** + * Create a predicate for testing whether the expression + * satisfies the given pattern. + * + * @param x string expression + * @param pattern string + * @param escapeChar escape character + * + * @return like predicate + */ + Predicate like(Expression<String> x, String pattern, char escapeChar); + + /** + * Create a predicate for testing whether the expression + * does not satisfy the given pattern. + * + * @param x string expression + * @param pattern string expression + * + * @return not-like predicate + */ + Predicate notLike(Expression<String> x, Expression<String> pattern); + + /** + * Create a predicate for testing whether the expression + * does not satisfy the given pattern. + * + * @param x string expression + * @param pattern string + * + * @return not-like predicate + */ + Predicate notLike(Expression<String> x, String pattern); + + /** + * Create a predicate for testing whether the expression + * does not satisfy the given pattern. + * + * @param x string expression + * @param pattern string expression + * @param escapeChar escape character expression + * + * @return not-like predicate + */ + Predicate notLike(Expression<String> x, Expression<String> pattern, Expression<Character> escapeChar); + + /** + * Create a predicate for testing whether the expression + * does not satisfy the given pattern. + * + * @param x string expression + * @param pattern string expression + * @param escapeChar escape character + * + * @return not-like predicate + */ + Predicate notLike(Expression<String> x, Expression<String> pattern, char escapeChar); + + /** + * Create a predicate for testing whether the expression + * does not satisfy the given pattern. + * + * @param x string expression + * @param pattern string + * @param escapeChar escape character expression + * + * @return not-like predicate + */ + Predicate notLike(Expression<String> x, String pattern, Expression<Character> escapeChar); + + /** + * Create a predicate for testing whether the expression + * does not satisfy the given pattern. + * + * @param x string expression + * @param pattern string + * @param escapeChar escape character + * + * @return not-like predicate + */ + Predicate notLike(Expression<String> x, String pattern, char escapeChar); + + /** + * Create an expression for string concatenation. + * + * @param x string expression + * @param y string expression + * + * @return expression corresponding to concatenation + */ + Expression<String> concat(Expression<String> x, Expression<String> y); + + /** + * Create an expression for string concatenation. + * + * @param x string expression + * @param y string + * + * @return expression corresponding to concatenation + */ + Expression<String> concat(Expression<String> x, String y); + + /** + * Create an expression for string concatenation. + * + * @param x string + * @param y string expression + * + * @return expression corresponding to concatenation + */ + Expression<String> concat(String x, Expression<String> y); + + /** + * Create an expression for substring extraction. + * Extracts a substring starting at the specified position + * through to end of the string. + * First position is 1. + * + * @param x string expression + * @param from start position expression + * + * @return expression corresponding to substring extraction + */ + Expression<String> substring(Expression<String> x, Expression<Integer> from); + + /** + * Create an expression for substring extraction. + * Extracts a substring starting at the specified position + * through to end of the string. + * First position is 1. + * + * @param x string expression + * @param from start position + * + * @return expression corresponding to substring extraction + */ + Expression<String> substring(Expression<String> x, int from); + + /** + * Create an expression for substring extraction. + * Extracts a substring of given length starting at the + * specified position. + * First position is 1. + * + * @param x string expression + * @param from start position expression + * @param len length expression + * + * @return expression corresponding to substring extraction + */ + Expression<String> substring(Expression<String> x, Expression<Integer> from, Expression<Integer> len); + + /** + * Create an expression for substring extraction. + * Extracts a substring of given length starting at the + * specified position. + * First position is 1. + * + * @param x string expression + * @param from start position + * @param len length + * + * @return expression corresponding to substring extraction + */ + Expression<String> substring(Expression<String> x, int from, int len); + + /** + * Used to specify how strings are trimmed. + */ + public static enum Trimspec { + + /** + * Trim from leading end. + */ + LEADING, + + /** + * Trim from trailing end. + */ + TRAILING, + + /** + * Trim from both ends. + */ + BOTH + } + + /** + * Create expression to trim blanks from both ends of + * a string. + * + * @param x expression for string to trim + * + * @return trim expression + */ + Expression<String> trim(Expression<String> x); + + /** + * Create expression to trim blanks from a string. + * + * @param ts trim specification + * @param x expression for string to trim + * + * @return trim expression + */ + Expression<String> trim(Trimspec ts, Expression<String> x); + + /** + * Create expression to trim character from both ends of + * a string. + * + * @param t expression for character to be trimmed + * @param x expression for string to trim + * + * @return trim expression + */ + Expression<String> trim(Expression<Character> t, Expression<String> x); + + /** + * Create expression to trim character from a string. + * + * @param ts trim specification + * @param t expression for character to be trimmed + * @param x expression for string to trim + * + * @return trim expression + */ + Expression<String> trim(Trimspec ts, Expression<Character> t, Expression<String> x); + + /** + * Create expression to trim character from both ends of + * a string. + * + * @param t character to be trimmed + * @param x expression for string to trim + * + * @return trim expression + */ + Expression<String> trim(char t, Expression<String> x); + + /** + * Create expression to trim character from a string. + * + * @param ts trim specification + * @param t character to be trimmed + * @param x expression for string to trim + * + * @return trim expression + */ + Expression<String> trim(Trimspec ts, char t, Expression<String> x); + + /** + * Create expression for converting a string to lowercase. + * + * @param x string expression + * + * @return expression to convert to lowercase + */ + Expression<String> lower(Expression<String> x); + + /** + * Create expression for converting a string to uppercase. + * + * @param x string expression + * + * @return expression to convert to uppercase + */ + Expression<String> upper(Expression<String> x); + + /** + * Create expression to return length of a string. + * + * @param x string expression + * + * @return length expression + */ + Expression<Integer> length(Expression<String> x); + + + /** + * Create expression to locate the position of one string + * within another, returning position of first character + * if found. + * The first position in a string is denoted by 1. If the + * string to be located is not found, 0 is returned. + * + * @param x expression for string to be searched + * @param pattern expression for string to be located + * + * @return expression corresponding to position + */ + Expression<Integer> locate(Expression<String> x, Expression<String> pattern); + + /** + * Create expression to locate the position of one string + * within another, returning position of first character + * if found. + * The first position in a string is denoted by 1. If the + * string to be located is not found, 0 is returned. + * + * @param x expression for string to be searched + * @param pattern string to be located + * + * @return expression corresponding to position + */ + Expression<Integer> locate(Expression<String> x, String pattern); + + /** + * Create expression to locate the position of one string + * within another, returning position of first character + * if found. + * The first position in a string is denoted by 1. If the + * string to be located is not found, 0 is returned. + * + * @param x expression for string to be searched + * @param pattern expression for string to be located + * @param from expression for position at which to start search + * + * @return expression corresponding to position + */ + Expression<Integer> locate(Expression<String> x, Expression<String> pattern, Expression<Integer> from); + + /** + * Create expression to locate the position of one string + * within another, returning position of first character + * if found. + * The first position in a string is denoted by 1. If the + * string to be located is not found, 0 is returned. + * + * @param x expression for string to be searched + * @param pattern string to be located + * @param from position at which to start search + * + * @return expression corresponding to position + */ + Expression<Integer> locate(Expression<String> x, String pattern, int from); + + + // Date/time/timestamp functions: + + /** + * Create expression to return current date. + * + * @return expression for current date + */ + Expression<java.sql.Date> currentDate(); + + /** + * Create expression to return current timestamp. + * + * @return expression for current timestamp + */ + Expression<java.sql.Timestamp> currentTimestamp(); + + /** + * Create expression to return current time. + * + * @return expression for current time + */ + Expression<java.sql.Time> currentTime(); + + + //in builders: + + /** + * Interface used to build in predicates. + */ + public static interface In<T> extends Predicate { + + /** + * Return the expression to be tested against the + * list of values. + * + * @return expression + */ + Expression<T> getExpression(); + + /** + * Add to list of values to be tested against. + * + * @param value value + * + * @return in predicate + */ + In<T> value(T value); + + /** + * Add to list of values to be tested against. + * + * @param value expression + * + * @return in predicate + */ + In<T> value(Expression<? extends T> value); + } + + /** + * Create predicate to test whether given expression + * is contained in a list of values. + * + * @param expression to be tested against list of values + * + * @return in predicate + */ + <T> In<T> in(Expression<? extends T> expression); + + + // coalesce, nullif: + + /** + * Create an expression that returns null if all its arguments + * evaluate to null, and the value of the first non-null argument + * otherwise. + * + * @param x expression + * @param y expression + * + * @return coalesce expression + */ + <Y> Expression<Y> coalesce(Expression<? extends Y> x, Expression<? extends Y> y); + + /** + * Create an expression that returns null if all its arguments + * evaluate to null, and the value of the first non-null argument + * otherwise. + * + * @param x expression + * @param y value + * + * @return coalesce expression + */ + <Y> Expression<Y> coalesce(Expression<? extends Y> x, Y y); + + /** + * Create an expression that tests whether its argument are + * equal, returning null if they are and the value of the + * first expression if they are not. + * + * @param x expression + * @param y expression + * + * @return nullif expression + */ + <Y> Expression<Y> nullif(Expression<Y> x, Expression<?> y); + + /** + * Create an expression that tests whether its argument are + * equal, returning null if they are and the value of the + * first expression if they are not. + * + * @param x expression + * @param y value + * + * @return nullif expression + */ + <Y> Expression<Y> nullif(Expression<Y> x, Y y); + + + // coalesce builder: + + /** + * Interface used to build coalesce expressions. + * + * A coalesce expression is equivalent to a case expression + * that returns null if all its arguments evaluate to null, + * and the value of its first non-null argument otherwise. + */ + public static interface Coalesce<T> extends Expression<T> { + + /** + * Add an argument to the coalesce expression. + * + * @param value value + * + * @return coalesce expression + */ + Coalesce<T> value(T value); + + /** + * Add an argument to the coalesce expression. + * + * @param value expression + * + * @return coalesce expression + */ + Coalesce<T> value(Expression<? extends T> value); + } + + /** + * Create a coalesce expression. + * + * @return coalesce expression + */ + <T> Coalesce<T> coalesce(); + + + //case builders: + + /** + * Interface used to build simple case expressions. + * Case conditions are evaluated in the order in which + * they are specified. + */ + public static interface SimpleCase<C, R> extends Expression<R> { + + /** + * Return the expression to be tested against the + * conditions. + * + * @return expression + */ + Expression<C> getExpression(); + + /** + * Add a when/then clause to the case expression. + * + * @param condition "when" condition + * @param result "then" result value + * + * @return simple case expression + */ + SimpleCase<C, R> when(C condition, R result); + + /** + * Add a when/then clause to the case expression. + * + * @param condition "when" condition + * @param result "then" result expression + * + * @return simple case expression + */ + SimpleCase<C, R> when(C condition, Expression<? extends R> result); + + /** + * Add an "else" clause to the case expression. + * + * @param result "else" result + * + * @return expression + */ + Expression<R> otherwise(R result); + + /** + * Add an "else" clause to the case expression. + * + * @param result "else" result expression + * + * @return expression + */ + Expression<R> otherwise(Expression<? extends R> result); + } + + /** + * Create a simple case expression. + * + * @param expression to be tested against the case conditions + * + * @return simple case expression + */ + <C, R> SimpleCase<C, R> selectCase(Expression<? extends C> expression); + + + /** + * Interface used to build general case expressions. + * Case conditions are evaluated in the order in which + * they are specified. + */ + public static interface Case<R> extends Expression<R> { + + /** + * Add a when/then clause to the case expression. + * + * @param condition "when" condition + * @param result "then" result value + * + * @return general case expression + */ + Case<R> when(Expression<Boolean> condition, R result); + + /** + * Add a when/then clause to the case expression. + * + * @param condition "when" condition + * @param result "then" result expression + * + * @return general case expression + */ + Case<R> when(Expression<Boolean> condition, Expression<? extends R> result); + + /** + * Add an "else" clause to the case expression. + * + * @param result "else" result + * + * @return expression + */ + Expression<R> otherwise(R result); + + /** + * Add an "else" clause to the case expression. + * + * @param result "else" result expression + * + * @return expression + */ + Expression<R> otherwise(Expression<? extends R> result); + } + + /** + * Create a general case expression. + * + * @return general case expression + */ + <R> Case<R> selectCase(); + + /** + * Create an expression for the execution of a database + * function. + * + * @param name function name + * @param type expected result type + * @param args function arguments + * + * @return expression + */ + <T> Expression<T> function(String name, Class<T> type, Expression<?>... args); + +} Property changes on: jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaBuilder.java ___________________________________________________________________ Name: svn:keywords + Id Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaQuery.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaQuery.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,8 +6,11 @@ import java.util.Set; /** - * The CriteriaQuery interface defines functionality that is specific + * The <code>CriteriaQuery</code> interface defines functionality that is specific * to top-level queries. + * + * @param <T> the type of the defined result + * @since Java Persistence 2.0 */ public interface CriteriaQuery<T> extends AbstractQuery<T> { @@ -15,23 +18,30 @@ * Specify the item that is to be returned in the query result. * Replaces the previously specified selection(s), if any. * - * Note: Applications using the string-based API may need to + * <p> Note: Applications using the string-based API may need to * specify the type of the select item when it results from * a get or join operation and the query result type is - * specified. For example: + * specified. * - * CriteriaQuery<String> q = qb.createQuery(String.class); - * Root<Order> order = q.from(Order.class); - * q.select(order.get("shippingAddress").<String>get("state")); + * <pre> + * For example: * - * CriteriaQuery<Product> q2 = qb.createQuery(Product.class); - * q2.select(q2.from(Order.class) - * .join("items") - * .<Item,Product>join("product")); + * CriteriaQuery&#060;String&#062; q = cb.createQuery(String.class); + * Root&#060;Order&#062; order = q.from(Order.class); + * q.select(order.get("shippingAddress").&#060;String&#062;get("state")); * + * CriteriaQuery&#060;Product&#062; q2 = cb.createQuery(Product.class); + * q2.select(q2.from(Order.class) + * .join("items") + * .&#060;Item,Product&#062;join("product")); + * + * </pre> + * * @param selection selection specifying the item that * is to be returned in the query result + * * @return the modified query + * * @throws IllegalArgumentException if the selection is * a compound selection and more than one selection * item has the same assigned alias @@ -46,145 +56,164 @@ * The type of the result of the query execution depends on * the specification of the type of the criteria query object * created as well as the arguments to the multiselect method. - * An argument to the multiselect method must not be a tuple- + * <p> An argument to the multiselect method must not be a tuple- * or array-valued compound selection item. * - * The semantics of this method are as follows: + * <p>The semantics of this method are as follows: + * <ul> + * <li> + * If the type of the criteria query is + * <code>CriteriaQuery&#060;Tuple&#062;</code> (i.e., a criteria + * query object created by either the + * <code>createTupleQuery</code> method or by passing a + * <code>Tuple</code> class argument to the + * <code>createQuery</code> method), a <code>Tuple</code> object + * corresponding to the arguments of the <code>multiselect</code> + * method, in the specified order, will be instantiated and + * returned for each row that results from the query execution. * - * If the type of the criteria query is CriteriaQuery<Tuple> - * (i.e., a criteria query object created by either the - * createTupleQuery method or by passing a Tuple class argument - * to the createQuery method), a Tuple object corresponding to - * the arguments of the multiselect method will be instantiated - * and returned for each row that results from the query - * execution. - * - * If the type of the criteria query is CriteriaQuery<X> for + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;X&#062;</code> for * some user-defined class X (i.e., a criteria query object - * created by passing a X class argument to the createQuery - * method), the arguments to the multiselect method will be + * created by passing a X class argument to the <code>createQuery</code> + * method), the arguments to the <code>multiselect</code> method will be * passed to the X constructor and an instance of type X will be * returned for each row. * - * If the type of the criteria query is CriteriaQuery<X[]> for + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;X[]&#062;</code> for * some class X, an instance of type X[] will be returned for - * each row. The elements of the array will correspond to the - * arguments of the multiselect method. + * each row. The elements of the array will correspond to the + * arguments of the <code>multiselect</code> method, in the + * specified order. * - * If the type of the criteria query is CriteriaQuery<Object> + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;Object&#062;</code> * or if the criteria query was created without specifying a - * type, and only a single argument is passed to the multiselect - * method, an instance of type Object will be returned for + * type, and only a single argument is passed to the <code>multiselect</code> + * method, an instance of type <code>Object</code> will be returned for * each row. * - * If the type of the criteria query is CriteriaQuery<Object> + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;Object&#062;</code> * or if the criteria query was created without specifying a - * type, and more than one argument is passed to the multiselect - * method, an instance of type Object[] will be instantiated - * and returned for each row. The elements of the array will - * correspond to the arguments to the multiselect method. + * type, and more than one argument is passed to the <code>multiselect</code> + * method, an instance of type <code>Object[]</code> will be instantiated + * and returned for each row. The elements of the array will + * correspond to the arguments to the <code> multiselect</code> method, + * in the specified order. + * </ul> * * @param selections selection items corresponding to the * results to be returned by the query + * * @return the modified query + * * @throws IllegalArgumentException if a selection item is * not valid or if more than one selection item has * the same assigned alias */ CriteriaQuery<T> multiselect(Selection<?>... selections); + /** * Specify the selection items that are to be returned in the * query result. * Replaces the previously specified selection(s), if any. * - * The type of the result of the query execution depends on + * <p> The type of the result of the query execution depends on * the specification of the type of the criteria query object - * created as well as the argument to the multiselect method. - * An element of the list passed to the multiselect method + * created as well as the argument to the <code>multiselect</code> method. + * An element of the list passed to the <code>multiselect</code> method * must not be a tuple- or array-valued compound selection item. * - * The semantics of this method are as follows: - * - * If the type of the criteria query is CriteriaQuery<Tuple> + * <p> The semantics of this method are as follows: + * <ul> + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;Tuple&#062;</code> * (i.e., a criteria query object created by either the - * createTupleQuery method or by passing a Tuple class argument - * to the createQuery method), a Tuple object corresponding to - * the elements of the list passed to the multiselect method - * will be instantiated and returned for each row that results - * from the query execution. + * <code>createTupleQuery</code> method or by passing a <code>Tuple</code> class argument + * to the <code>createQuery</code> method), a <code>Tuple</code> object corresponding to + * the elements of the list passed to the <code>multiselect</code> method, + * in the specified order, will be instantiated and returned for each + * row that results from the query execution. * - * If the type of the criteria query is CriteriaQuery<X> for + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;X&#062;</code> for * some user-defined class X (i.e., a criteria query object - * created by passing a X class argument to the createQuery - * method), the elements of the list passed to the multiselect + * created by passing a X class argument to the <code>createQuery</code> + * method), the elements of the list passed to the <code>multiselect</code> * method will be passed to the X constructor and an instance * of type X will be returned for each row. * - * If the type of the criteria query is CriteriaQuery<X[]> for + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;X[]&#062;</code> for * some class X, an instance of type X[] will be returned for - * each row. The elements of the array will correspond to the - * elements of the list passed to the multiselect method. + * each row. The elements of the array will correspond to the + * elements of the list passed to the <code>multiselect</code> method, + * in the specified order. * - * If the type of the criteria query is CriteriaQuery<Object> + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;Object&#062;</code> * or if the criteria query was created without specifying a - * type, and the list passed to the multiselect method contains - * only a single element, an instance of type Object will be + * type, and the list passed to the <code>multiselect</code> method contains + * only a single element, an instance of type <code>Object</code> will be * returned for each row. * - * If the type of the criteria query is CriteriaQuery<Object> + * <li> If the type of the criteria query is <code>CriteriaQuery&#060;Object&#062;</code> * or if the criteria query was created without specifying a - * type, and the list passed to the multiselect method contains - * more than one element, an instance of type Object[] will be - * instantiated and returned for each row. The elements of the + * type, and the list passed to the <code>multiselect</code> method contains + * more than one element, an instance of type <code>Object[]</code> will be + * instantiated and returned for each row. The elements of the * array will correspond to the elements of the list passed to - * the multiselect method. + * the <code>multiselect</code> method, in the specified order. + * </ul> * * @param selectionList list of selection items corresponding * to the results to be returned by the query + * * @return the modified query + * * @throws IllegalArgumentException if a selection item is * not valid or if more than one selection item has * the same assigned alias */ CriteriaQuery<T> multiselect(List<Selection<?>> selectionList); - /** - * Modify the query to restrict the query result according - * to the specified boolean expression. - * Replaces the previously added restriction(s), if any. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restriction a simple or compound boolean expression - * @return the modified query - */ - CriteriaQuery<T> where(Expression<Boolean> restriction); + /** + * Modify the query to restrict the query result according + * to the specified boolean expression. + * Replaces the previously added restriction(s), if any. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param restriction a simple or compound boolean expression + * + * @return the modified query + */ + CriteriaQuery<T> where(Expression<Boolean> restriction); - /** - * Modify the query to restrict the query result according - * to the conjunction of the specified restriction predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restrictions zero or more restriction predicates - * @return the modified query - */ - CriteriaQuery<T> where(Predicate... restrictions); + /** + * Modify the query to restrict the query result according + * to the conjunction of the specified restriction predicates. + * Replaces the previously added restriction(s), if any. + * If no restrictions are specified, any previously added + * restrictions are simply removed. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param restrictions zero or more restriction predicates + * + * @return the modified query + */ + CriteriaQuery<T> where(Predicate... restrictions); - /** - * Specify the expressions that are used to form groups over - * the query results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param grouping zero or more grouping expressions - * @return the modified query - */ - CriteriaQuery<T> groupBy(Expression<?>... grouping); + /** + * Specify the expressions that are used to form groups over + * the query results. + * Replaces the previous specified grouping expressions, if any. + * If no grouping expressions are specified, any previously + * added grouping expressions are simply removed. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param grouping zero or more grouping expressions + * + * @return the modified query + */ + CriteriaQuery<T> groupBy(Expression<?>... grouping); /** * Specify the expressions that are used to form groups over @@ -193,50 +222,58 @@ * If no grouping expressions are specified, any previously * added grouping expressions are simply removed. * This method only overrides the return type of the - * corresponding AbstractQuery method. + * corresponding <code>AbstractQuery</code> method. + * * @param grouping list of zero or more grouping expressions + * * @return the modified query */ CriteriaQuery<T> groupBy(List<Expression<?>> grouping); - /** - * Specify a restriction over the groups of the query. - * Replaces the previous having restriction(s), if any. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restriction a simple or compound boolean expression - * @return the modified query - */ - CriteriaQuery<T> having(Expression<Boolean> restriction); + /** + * Specify a restriction over the groups of the query. + * Replaces the previous having restriction(s), if any. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param restriction a simple or compound boolean expression + * + * @return the modified query + */ + CriteriaQuery<T> having(Expression<Boolean> restriction); - /** - * Specify restrictions over the groups of the query - * according the conjunction of the specified restriction - * predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restrictions zero or more restriction predicates - * @return the modified query - */ - CriteriaQuery<T> having(Predicate... restrictions); + /** + * Specify restrictions over the groups of the query + * according the conjunction of the specified restriction + * predicates. + * Replaces the previously added having restriction(s), if any. + * If no restrictions are specified, any previously added + * restrictions are simply removed. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param restrictions zero or more restriction predicates + * + * @return the modified query + */ + CriteriaQuery<T> having(Predicate... restrictions); - /** - * Specify the ordering expressions that are used to - * order the query results. - * Replaces the previous ordering expressions, if any. - * If no ordering expressions are specified, the previous - * ordering, if any, is simply removed, and results will - * be returned in no particular order. - * The left-to-right sequence of the ordering expressions - * determines the precedence, whereby the leftmost has highest - * precedence. - * @param o zero or more ordering expressions - * @return the modified query. - */ - CriteriaQuery<T> orderBy(Order... o); + /** + * Specify the ordering expressions that are used to + * order the query results. + * Replaces the previous ordering expressions, if any. + * If no ordering expressions are specified, the previous + * ordering, if any, is simply removed, and results will + * be returned in no particular order. + * The left-to-right sequence of the ordering expressions + * determines the precedence, whereby the leftmost has highest + * precedence. + * + * @param o zero or more ordering expressions + * + * @return the modified query + */ + CriteriaQuery<T> orderBy(Order... o); /** * Specify the ordering expressions that are used to @@ -248,40 +285,46 @@ * The order of the ordering expressions in the list * determines the precedence, whereby the first element in the * list has highest precedence. + * * @param o list of zero or more ordering expressions - * @return the modified query. + * + * @return the modified query */ CriteriaQuery<T> orderBy(List<Order> o); - /** - * Specify whether duplicate query results will be eliminated. - * A true value will cause duplicates to be eliminated. - * A false value will cause duplicates to be retained. - * If distinct has not been specified, duplicate results must - * be retained. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param distinct boolean value specifying whether duplicate - * results must be eliminated from the query result or - * whether they must be retained - * @return the modified query. - */ - CriteriaQuery<T> distinct(boolean distinct); + /** + * Specify whether duplicate query results will be eliminated. + * A true value will cause duplicates to be eliminated. + * A false value will cause duplicates to be retained. + * If distinct has not been specified, duplicate results must + * be retained. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param distinct boolean value specifying whether duplicate + * results must be eliminated from the query result or + * whether they must be retained + * + * @return the modified query. + */ + CriteriaQuery<T> distinct(boolean distinct); - /** + /** * Return the ordering expressions in order of precedence. * Returns empty list if no ordering expressions have been * specified. * Modifications to the list do not affect the query. + * * @return the list of ordering expressions - */ - List<Order> getOrderList(); + */ + List<Order> getOrderList(); /** - * Return the parameters of the query. Returns empty set if + * Return the parameters of the query. Returns empty set if * there are no parameters. * Modifications to the set do not affect the query. + * * @return the query parameters */ - Set<ParameterExpression<?>> getParameters(); + Set<ParameterExpression<?>> getParameters(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Expression.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Expression.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Expression.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,63 +6,77 @@ /** * Type for query expressions. + * * @param <T> the type of the expression + * @since Java Persistence 2.0 */ public interface Expression<T> extends Selection<T> { - - /** - * Create a predicate to test whether the expression is null. + /** + * Create a predicate to test whether the expression is null. + * * @return predicate testing whether the expression is null - */ - Predicate isNull(); + */ + Predicate isNull(); - /** - * Create a predicate to test whether the expression is + /** + * Create a predicate to test whether the expression is * not null. - * @return predicate testing whether the expression is not null. - */ - Predicate isNotNull(); + * + * @return predicate testing whether the expression is not null + */ + Predicate isNotNull(); - /** - * Create a predicate to test whether the expression is a member + /** + * Create a predicate to test whether the expression is a member * of the argument list. - * @param values The argument list - * @return predicate testing for membership in the list - */ - Predicate in(Object... values); + * + * @param values values to be tested against + * + * @return predicate testing for membership + */ + Predicate in(Object... values); - /** - * Create a predicate to test whether the expression is a member + /** + * Create a predicate to test whether the expression is a member * of the argument list. - * @param values The argument list - * @return predicate testing for membership in the list - */ - Predicate in(Expression<?>... values); + * + * @param values expressions to be tested against + * + * @return predicate testing for membership + */ + Predicate in(Expression<?>... values); - /** - * Create a predicate to test whether the expression is a member + /** + * Create a predicate to test whether the expression is a member * of the collection. - * @param values collection + * + * @param values collection of values to be tested against + * * @return predicate testing for membership - */ - Predicate in(Collection<?> values); + */ + Predicate in(Collection<?> values); - /** - * Create a predicate to test whether the expression is a member + /** + * Create a predicate to test whether the expression is a member * of the collection. - * @param values expression corresponding to collection + * + * @param values expression corresponding to collection to be + * tested against + * * @return predicate testing for membership - */ - Predicate in(Expression<Collection<?>> values); + */ + Predicate in(Expression<Collection<?>> values); - /** - * Perform a typecast upon the expression, returning new + /** + * Perform a typecast upon the expression, returning a new * expression object. * This method does not cause type conversion: * the runtime type is not changed. * Warning: may result in a runtime failure. - * @param type The cast type + * + * @param type intended type of the expression + * * @return new expression of the given type - */ - <X> Expression<X> as(Class<X> type); + */ + <X> Expression<X> as(Class<X> type); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Fetch.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Fetch.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Fetch.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,26 +6,32 @@ /** * Represents a join-fetched association or attribute. - * @param <Z> - * @param <X> + * + * @param <Z> the source type of the fetch + * @param <X> the target type of the fetch + * @since Java Persistence 2.0 */ public interface Fetch<Z, X> extends FetchParent<Z, X> { - /** - * Return the metamodel attribute corresponding to the fetch join. - * @return metamodel attribute for the join - */ - Attribute<? super Z, ?> getAttribute(); + /** + * Return the metamodel attribute corresponding to the + * fetch join. + * + * @return metamodel attribute for the join + */ + Attribute<? super Z, ?> getAttribute(); - /** - * Return the parent of the fetched item. - * @return fetch parent - */ - FetchParent<?, Z> getParent(); + /** + * Return the parent of the fetched item. + * + * @return fetch parent + */ + FetchParent<?, Z> getParent(); - /** - * Return the join type used in the fetch join. - * @return join type - */ - JoinType getJoinType(); + /** + * Return the join type used in the fetch join. + * + * @return join type + */ + JoinType getJoinType(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/FetchParent.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/FetchParent.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/FetchParent.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -9,78 +9,94 @@ * Represents an element of the from clause which may * function as the parent of Fetches. * - * @param <Z> The type of the fetch source - * @param <X> The type of the fetched attribute/association + * @param <Z> the source type + * @param <X> the target type + * @since Java Persistence 2.0 */ public interface FetchParent<Z, X> { - - /** - * Return the fetch joins that have been made from this type. + /** + * Return the fetch joins that have been made from this type. * Returns empty set if no fetch joins have been made from * this type. * Modifications to the set do not affect the query. + * * @return fetch joins made from this type - */ - java.util.Set<Fetch<X, ?>> getFetches(); + */ + java.util.Set<Fetch<X, ?>> getFetches(); - /** - * Create a fetch join to the specified single-valued attribute + /** + * Create a fetch join to the specified single-valued attribute * using an inner join. + * * @param attribute target of the join + * * @return the resulting fetch join - */ - <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute); + */ + <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute); - /** - * Create a fetch join to the specified single-valued attribute + /** + * Create a fetch join to the specified single-valued attribute * using the given join type. - * @param attribute target of the join - * @param jt join type - * @return the resulting fetch join - */ - <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute, JoinType jt); + * + * @param attribute target of the join + * @param jt join type + * + * @return the resulting fetch join + */ + <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute, JoinType jt); - /** - * Create a fetch join to the specified collection-valued attribute - * using an inner join. + /** + * Create a fetch join to the specified collection-valued + * attribute using an inner join. + * * @param attribute target of the join + * * @return the resulting join - */ - <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute); + */ + <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute); - /** - * Create a fetch join to the specified collection-valued attribute - * using the given join type. - * @param attribute target of the join - * @param jt join type - * @return the resulting join - */ - <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute, JoinType jt); + /** + * Create a fetch join to the specified collection-valued + * attribute using the given join type. + * + * @param attribute target of the join + * @param jt join type + * + * @return the resulting join + */ + <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute, JoinType jt); - //String-based: + //String-based: - /** - * Create a fetch join to the specified attribute using an + /** + * Create a fetch join to the specified attribute using an * inner join. + * * @param attributeName name of the attribute for the * target of the join + * * @return the resulting fetch join + * * @throws IllegalArgumentException if attribute of the given * name does not exist - */ - <X, Y> Fetch<X, Y> fetch(String attributeName); + */ + @SuppressWarnings("hiding") + <X, Y> Fetch<X, Y> fetch(String attributeName); - /** - * Create a fetch join to the specified attribute using the given - * join type. + /** + * Create a fetch join to the specified attribute using + * the given join type. * * @param attributeName name of the attribute for the * target of the join - * @param jt join type + * @param jt join type + * * @return the resulting fetch join - * @throws IllegalArgumentException if attribute of the given + * + * @throws IllegalArgumentException if attribute of the given * name does not exist - */ - <X, Y> Fetch<X, Y> fetch(String attributeName, JoinType jt); + */ + @SuppressWarnings("hiding") + <X, Y> Fetch<X, Y> fetch(String attributeName, JoinType jt); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/From.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/From.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/From.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -7,268 +7,298 @@ import javax.persistence.metamodel.ListAttribute; import javax.persistence.metamodel.MapAttribute; import javax.persistence.metamodel.SetAttribute; +import java.util.Set; /** * Represents a bound type, usually an entity that appears in * the from clause, but may also be an embeddable belonging to * an entity in the from clause. - * Serves as a factory for Joins of associations, embeddables and + * <p> Serves as a factory for Joins of associations, embeddables, and * collections belonging to the type, and for Paths of attributes * belonging to the type. - * @param <Z> - * @param <X> + * + * @param <Z> the source type + * @param <X> the target type + * @since Java Persistence 2.0 */ +@SuppressWarnings("hiding") public interface From<Z, X> extends Path<X>, FetchParent<Z, X> { - /** - * Return the joins that have been made from this bound type. - * Does not include joins from map keys, if any. + /** + * Return the joins that have been made from this bound type. * Returns empty set if no joins have been made from this * bound type. * Modifications to the set do not affect the query. + * * @return joins made from this type - */ - java.util.Set<Join<X, ?>> getJoins(); + */ + Set<Join<X, ?>> getJoins(); - /** - * Create an inner join to the specified single-valued + /** + * Whether the <code>From</code> object has been obtained as a result of + * correlation (use of a <code>Subquery</code> <code>correlate</code> + * method). + * + * @return boolean indicating whether the object has been + * obtained through correlation + */ + boolean isCorrelated(); + + /** + * Returns the parent <code>From</code> object from which the correlated + * <code>From</code> object has been obtained through correlation (use + * of a <code>Subquery</code> <code>correlate</code> method). + * + * @return the parent of the correlated From object + * + * @throws IllegalStateException if the From object has + * not been obtained through correlation + */ + From<Z, X> getCorrelationParent(); + + /** + * Create an inner join to the specified single-valued * attribute. + * * @param attribute target of the join + * * @return the resulting join - */ - <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute); + */ + <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute); - /** - * Create a join to the specified single-valued attribute + /** + * Create a join to the specified single-valued attribute * using the given join type. + * * @param attribute target of the join * @param jt join type + * * @return the resulting join - */ - <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute, JoinType jt); + */ + <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute, JoinType jt); - /** - * Create an inner join to the specified Collection-valued + /** + * Create an inner join to the specified Collection-valued * attribute. + * * @param collection target of the join + * * @return the resulting join - */ - <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection); + */ + <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection); - /** - * Create an inner join to the specified Set-valued attribute. + /** + * Create an inner join to the specified Set-valued attribute. + * * @param set target of the join + * * @return the resulting join - */ - <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set); + */ + <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set); - /** - * Create an inner join to the specified List-valued attribute. + /** + * Create an inner join to the specified List-valued attribute. + * * @param list target of the join + * * @return the resulting join - */ - <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list); + */ + <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list); - /** - * Create an inner join to the specified Map-valued attribute. - * @param map target of the join - * @return the resulting join - */ - <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map); + /** + * Create an inner join to the specified Map-valued attribute. + * + * @param map target of the join + * + * @return the resulting join + */ + <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map); - /** - * Create a join to the specified Collection-valued attribute + /** + * Create a join to the specified Collection-valued attribute * using the given join type. + * * @param collection target of the join * @param jt join type + * * @return the resulting join - */ - <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection, JoinType jt); + */ + <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection, JoinType jt); - /** - * Create a join to the specified Set-valued attribute using + /** + * Create a join to the specified Set-valued attribute using * the given join type. + * * @param set target of the join * @param jt join type + * * @return the resulting join - */ - <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set, JoinType jt); + */ + <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set, JoinType jt); - /** - * Create a join to the specified List-valued attribute using + /** + * Create a join to the specified List-valued attribute using * the given join type. + * * @param list target of the join * @param jt join type + * * @return the resulting join - */ - <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list, JoinType jt); + */ + <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list, JoinType jt); - /** - * Create a join to the specified Map-valued attribute using + /** + * Create a join to the specified Map-valued attribute using * the given join type. + * * @param map target of the join * @param jt join type + * * @return the resulting join - */ - <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map, JoinType jt); + */ + <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map, JoinType jt); - //String-based: + //String-based: - /** - * Join to the specified attribute using an inner join. + /** + * Create an inner join to the specified attribute. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <Y> The type of the joined attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, Y> Join<X, Y> join(String attributeName); + * @param attributeName name of the attribute for the + * target of the join + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, Y> Join<X, Y> join(String attributeName); - /** - * Join to the specified Collection-valued attribute using an - * inner join. + /** + * Create an inner join to the specified Collection-valued + * attribute. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <Y> The type of the joined attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, Y> CollectionJoin<X, Y> joinCollection(String attributeName); + * @param attributeName name of the attribute for the + * target of the join + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, Y> CollectionJoin<X, Y> joinCollection(String attributeName); - /** - * Join to the specified Set-valued attribute using an inner - * join. + /** + * Create an inner join to the specified Set-valued attribute. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <Y> The type of the joined attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, Y> SetJoin<X, Y> joinSet(String attributeName); + * @param attributeName name of the attribute for the + * target of the join + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, Y> SetJoin<X, Y> joinSet(String attributeName); - /** - * Join to the specified List-valued attribute using an inner - * join. + /** + * Create an inner join to the specified List-valued attribute. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <Y> The type of the joined attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, Y> ListJoin<X, Y> joinList(String attributeName); + * @param attributeName name of the attribute for the + * target of the join + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, Y> ListJoin<X, Y> joinList(String attributeName); - /** - * Join to the specified Map-valued attribute using an inner - * join. + /** + * Create an inner join to the specified Map-valued attribute. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <K> The type of the key of the joined map. - * @param <V> The type of the value of the joined map. - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, K, V> MapJoin<X, K, V> joinMap(String attributeName); + * @param attributeName name of the attribute for the + * target of the join + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, K, V> MapJoin<X, K, V> joinMap(String attributeName); - - /** - * Join to the specified attribute using the given - * join type. + /** + * Create a join to the specified attribute using the given + * join type. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <Y> The type of the joined attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, Y> Join<X, Y> join(String attributeName, JoinType jt); + * @param attributeName name of the attribute for the + * target of the join + * @param jt join type + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, Y> Join<X, Y> join(String attributeName, JoinType jt); - /** - * Join to the specified Collection-valued attribute using - * the given join type. + /** + * Create a join to the specified Collection-valued attribute + * using the given join type. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <Y> The type of the joined attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, Y> CollectionJoin<X, Y> joinCollection(String attributeName, JoinType jt); + * @param attributeName name of the attribute for the + * target of the join + * @param jt join type + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, Y> CollectionJoin<X, Y> joinCollection(String attributeName, JoinType jt); - /** - * Join to the specified Set-valued attribute using - * the given join type. + /** + * Create a join to the specified Set-valued attribute using + * the given join type. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <Y> The type of the joined attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, Y> SetJoin<X, Y> joinSet(String attributeName, JoinType jt); + * @param attributeName name of the attribute for the + * target of the join + * @param jt join type + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, Y> SetJoin<X, Y> joinSet(String attributeName, JoinType jt); - /** - * Join to the specified List-valued attribute using - * the given join type. + /** + * Create a join to the specified List-valued attribute using + * the given join type. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <Y> The type of the joined attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, Y> ListJoin<X, Y> joinList(String attributeName, JoinType jt); + * @param attributeName name of the attribute for the + * target of the join + * @param jt join type + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, Y> ListJoin<X, Y> joinList(String attributeName, JoinType jt); - /** - * Join to the specified Map-valued attribute using - * the given join type. + /** + * Create a join to the specified Map-valued attribute using + * the given join type. * - * @param <X> The type of the source of the join; note that this method-local <X> hides the <X> defined as a type - * param to {@link From}; the expectation is that the two types match. - * @param <K> The type of the key of the joined map. - * @param <V> The type of the value of the joined map. - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting join - * @throws IllegalArgumentException if attribute of the given - * name does not exist - */ - <X, K, V> MapJoin<X, K, V> joinMap(String attributeName, JoinType jt); + * @param attributeName name of the attribute for the + * target of the join + * @param jt join type + * + * @return the resulting join + * + * @throws IllegalArgumentException if attribute of the given + * name does not exist + */ + <X, K, V> MapJoin<X, K, V> joinMap(String attributeName, JoinType jt); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Join.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Join.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Join.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -5,27 +5,31 @@ import javax.persistence.metamodel.Attribute; /** - * A join to an entity or embeddable type. - * @param <Z> The source type of the join - * @param <X> The target type of the join + * A join to an entity, embeddable, or basic type. + * + * @param <Z> the source type of the join + * @param <X> the target type of the join + * @since Java Persistence 2.0 */ public interface Join<Z, X> extends From<Z, X> { + /** + * Return the metamodel attribute corresponding to the join. + * + * @return metamodel attribute corresponding to the join + */ + Attribute<? super Z, ?> getAttribute(); - /** - * Return the metamodel attribute corresponding to the join. - * @return metamodel attribute corresponding to the join - */ - Attribute<? super Z, ?> getAttribute(); + /** + * Return the parent of the join. + * + * @return join parent + */ + From<?, Z> getParent(); - /** - * Return the parent of the join. - * @return join parent - */ - From<?, Z> getParent(); - - /** - * Return the join type. - * @return join type - */ - JoinType getJoinType(); + /** + * Return the join type. + * + * @return join type + */ + JoinType getJoinType(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/JoinType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/JoinType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/JoinType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,9 +3,27 @@ package javax.persistence.criteria; /** - * Defines the three types of joins + * Defines the three types of joins. + * + * Right outer joins and right outer fetch joins are not required + * to be supported in Java Persistence 2.0. Applications that use + * <code>RIGHT</code> join types will not be portable. + * + * @since Java Persistence 2.0 */ public enum JoinType { - INNER, LEFT, RIGHT + /** + * Inner join. + */ + INNER, + + /** + * Left outer join. + */ + LEFT, + + /** + * Right outer join. + */ + RIGHT } - Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/ListJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/ListJoin.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/ListJoin.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,30 +6,34 @@ import javax.persistence.metamodel.ListAttribute; /** - * The ListJoin interface is the type of the result of + * The <code>ListJoin</code> interface is the type of the result of * joining to a collection over an association or element - * collection that has been specified as a java.util.List. + * collection that has been specified as a <code>java.util.List</code>. * - * @param <Z> The source type of the join - * @param <E> The element type of the target List + * @param <Z> the source type of the join + * @param <E> the element type of the target List + * @since Java Persistence 2.0 */ -public interface ListJoin<Z, E> extends PluralJoin<Z, List<E>, E> { +public interface ListJoin<Z, E> + extends PluralJoin<Z, List<E>, E> { - /** - * Return the metamodel representation for the list attribute. - * @return metamodel type representing the List that is - * the target of the join - */ - ListAttribute<? super Z, E> getModel(); + /** + * Return the metamodel representation for the list attribute. + * + * @return metamodel type representing the <code>List</code> that is + * the target of the join + */ + ListAttribute<? super Z, E> getModel(); - /** + /** * Create an expression that corresponds to the index of * the object in the referenced association or element * collection. * This method must only be invoked upon an object that * represents an association or element collection for * which an order column has been defined. + * * @return expression denoting the index - */ - Expression<Integer> index(); + */ + Expression<Integer> index(); } \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/MapJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/MapJoin.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/MapJoin.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,54 +6,43 @@ import javax.persistence.metamodel.MapAttribute; /** - * The MapJoin interface is the type of the result of + * The <code>MapJoin</code> interface is the type of the result of * joining to a collection over an association or element - * collection that has been specified as a java.util.Map. + * collection that has been specified as a <code>java.util.Map</code>. * - * @param <Z> The source type of the join - * @param <K> The type of the target Map key - * @param <V> The type of the target Map value + * @param <Z> the source type of the join + * @param <K> the type of the target Map key + * @param <V> the type of the target Map value + * @since Java Persistence 2.0 */ public interface MapJoin<Z, K, V> extends PluralJoin<Z, Map<K, V>, V> { + /** + * Return the metamodel representation for the map attribute. + * + * @return metamodel type representing the <code>Map</code> that is + * the target of the join + */ + MapAttribute<? super Z, K, V> getModel(); - /** - * Return the metamodel representation for the map attribute. - * @return metamodel type representing the Map that is - * the target of the join - */ - MapAttribute<? super Z, K, V> getModel(); - - /** - * Create an inner join over the map key. - * @return result of joining over the map key - */ - Join<Map<K, V>, K> joinKey(); - - /** - * Create a join over the map key using the given - * join type. - * @param jt join type - * @return result of joining over the map key - */ - Join<Map<K, V>, K> joinKey(JoinType jt); - - /** - * Create a path expression that corresponds to the map key. + /** + * Create a path expression that corresponds to the map key. + * * @return path corresponding to map key - */ - Path<K> key(); + */ + Path<K> key(); - /** - * Create a path expression that corresponds to the map value. + /** + * Create a path expression that corresponds to the map value. * This method is for stylistic use only: it just returns this. + * * @return path corresponding to the map value - */ - Path<V> value(); + */ + Path<V> value(); - /** - * Create an expression that corresponds to the map entry. + /** + * Create an expression that corresponds to the map entry. + * * @return expression corresponding to the map entry - */ - Expression<Map.Entry<K, V>> entry(); + */ + Expression<Map.Entry<K, V>> entry(); } - Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Order.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Order.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Order.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -4,24 +4,28 @@ /** * An object that defines an ordering over the query results. + * + * @since Java Persistence 2.0 */ public interface Order { + /** + * Switch the ordering. + * + * @return a new <code>Order</code> instance with the reversed ordering + */ + Order reverse(); - /** - * Switch the ordering. - * @return a new Order instance with the reversed ordering - */ - Order reverse(); + /** + * Whether ascending ordering is in effect. + * + * @return boolean indicating whether ordering is ascending + */ + boolean isAscending(); - /** - * Whether ascending ordering is in effect. - * @return boolean indicating whether ordering is ascending - */ - boolean isAscending(); - - /** - * Return the expression that is used for ordering. - * @return expression used for ordering - */ - Expression<?> getExpression(); -} \ No newline at end of file + /** + * Return the expression that is used for ordering. + * + * @return expression used for ordering + */ + Expression<?> getExpression(); +} Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/ParameterExpression.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/ParameterExpression.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/ParameterExpression.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -4,11 +4,12 @@ import javax.persistence.Parameter; - /** * Type of criteria query parameter expressions. + * * @param <T> the type of the parameter expression + * + * @since Java Persistence 2.0 */ public interface ParameterExpression<T> extends Parameter<T>, Expression<T> { } - Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Path.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Path.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Path.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,89 +2,103 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.criteria; +import javax.persistence.metamodel.PluralAttribute; +import javax.persistence.metamodel.SingularAttribute; import javax.persistence.metamodel.Bindable; import javax.persistence.metamodel.MapAttribute; -import javax.persistence.metamodel.PluralAttribute; -import javax.persistence.metamodel.SingularAttribute; /** * Represents a simple or compound attribute path from a * bound type or collection, and is a "primitive" expression. - * @param <X> Type referenced by the path + * + * @param <X> the type referenced by the path + * @since Java Persistence 2.0 */ public interface Path<X> extends Expression<X> { + /** + * Return the bindable object that corresponds to the + * path expression. + * + * @return bindable object corresponding to the path + */ + Bindable<X> getModel(); - /** - * Return the bindable object that corresponds to the - * path expression. - * @return bindable object corresponding to the path - */ - Bindable<X> getModel(); + /** + * Return the parent "node" in the path or null if no parent. + * + * @return parent + */ + Path<?> getParentPath(); - /** - * Return the parent "node" in the path or null if no parent. - * @return parent - */ - Path<?> getParentPath(); + /** + * Create a path corresponding to the referenced + * single-valued attribute. + * + * @param attribute single-valued attribute + * + * @return path corresponding to the referenced attribute + */ + <Y> Path<Y> get(SingularAttribute<? super X, Y> attribute); - /** - * Return the path corresponding to the referenced - * single-valued attribute. - * @param attribute single-valued attribute - * @return path corresponding to the referenced attribute - */ - <Y> Path<Y> get(SingularAttribute<? super X, Y> attribute); + /** + * Create a path corresponding to the referenced + * collection-valued attribute. + * + * @param collection collection-valued attribute + * + * @return expression corresponding to the referenced attribute + */ + <E, C extends java.util.Collection<E>> Expression<C> get(PluralAttribute<X, C, E> collection); - /** - * Return the path corresponding to the referenced - * collection-valued attribute. - * @param collection collection-valued attribute - * @return expression corresponding to the referenced attribute - */ - <E, C extends java.util.Collection<E>> Expression<C> get(PluralAttribute<X, C, E> collection); + /** + * Create a path corresponding to the referenced + * map-valued attribute. + * + * @param map map-valued attribute + * + * @return expression corresponding to the referenced attribute + */ + <K, V, M extends java.util.Map<K, V>> Expression<M> get(MapAttribute<X, K, V> map); - /** - * Return the path corresponding to the referenced - * map-valued attribute. - * @param map map-valued attribute - * @return expression corresponding to the referenced attribute - */ - <K, V, M extends java.util.Map<K, V>> Expression<M> get(MapAttribute<X, K, V> map); + /** + * Create an expression corresponding to the type of the path. + * + * @return expression corresponding to the type of the path + */ + Expression<Class<? extends X>> type(); - /** - * Return an expression corresponding to the type of the path. - * @return expression corresponding to the type of the path - */ - Expression<Class<? extends X>> type(); + //String-based: - //String-based: - /** * Create a path corresponding to the referenced attribute. * - * Note: Applications using the string-based API may need to - * specify the type resulting from the get operation in order - * to avoid the use of Path variables. + * <p> Note: Applications using the string-based API may need to + * specify the type resulting from the <code>get</code> operation in order + * to avoid the use of <code>Path</code> variables. * - * For example: + * <pre> + * For example: * - * CriteriaQuery<Person> q = qb.createQuery(Person.class); - * Root<Person> p = q.from(Person.class); - * q.select(p) - * .where(qb.isMember(qb.literal("joe"), - * p.<Set<String>>get("nicknames"))); + * CriteriaQuery&#060;Person&#062; q = cb.createQuery(Person.class); + * Root&#060;Person&#062; p = q.from(Person.class); + * q.select(p) + * .where(cb.isMember("joe", + * p.&#060;Set&#060;String&#062;&#062;get("nicknames"))); * - * rather than: + * rather than: * - * CriteriaQuery<Person> q = qb.createQuery(Person.class); - * Root<Person> p = q.from(Person.class); - * Path<Set<String>> nicknames = p.get("nicknames"); - * q.select(p) - * .where(qb.isMember(qb.literal("joe"), nicknames)); + * CriteriaQuery&#060;Person&#062; q = cb.createQuery(Person.class); + * Root&#060;Person&#062; p = q.from(Person.class); + * Path&#060;Set&#060;String&#062;&#062; nicknames = p.get("nicknames"); + * q.select(p) + * .where(cb.isMember("joe", nicknames)); + * </pre> * * @param attributeName name of the attribute + * * @return path corresponding to the referenced attribute + * * @throws IllegalStateException if invoked on a path that * corresponds to a basic type * @throws IllegalArgumentException if attribute of the given Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/PluralJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/PluralJoin.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/PluralJoin.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,25 +1,27 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.criteria; import javax.persistence.metamodel.PluralAttribute; /** - * The PluralJoin interface defines functionality + * The <code>PluralJoin</code> interface defines functionality * that is common to joins to all collection types. It is * not intended to be used directly in query construction. * - * @param <Z> The source type - * @param <C> The collection type - * @param <E> The element type of the collection + * @param <Z> the source type + * @param <C> the collection type + * @param <E> the element type of the collection + * @since Java Persistence 2.0 */ public interface PluralJoin<Z, C, E> extends Join<Z, E> { - /** - * Return the metamodel representation for the collection-valued - * attribute corresponding to the join. - * @return metamodel collection-valued attribute corresponding - * to the target of the join - */ - PluralAttribute<? super Z, C, E> getModel(); + /** + * Return the metamodel representation for the collection-valued + * attribute corresponding to the join. + * + * @return metamodel collection-valued attribute corresponding + * to the target of the join + */ + PluralAttribute<? super Z, C, E> getModel(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Predicate.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Predicate.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Predicate.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -9,38 +9,49 @@ * disjunction of restrictions. * A simple predicate is considered to be a conjunction with a * single conjunct. + * + * @since Java Persistence 2.0 */ public interface Predicate extends Expression<Boolean> { public static enum BooleanOperator { - AND, OR + AND, + OR } - /** - * Return the boolean operator for the predicate. - * If the predicate is simple, this is AND. - * @return boolean operator for the predicate - */ - BooleanOperator getOperator(); + /** + * Return the boolean operator for the predicate. + * If the predicate is simple, this is <code>AND</code>. + * + * @return boolean operator for the predicate + */ + BooleanOperator getOperator(); - /** - * Has negation been applied to the predicate. - * @return boolean indicating if the predicate has been negated - */ - boolean isNegated(); + /** + * Whether the predicate has been created from another + * predicate by applying the <code>Predicate.not()</code> method + * or the <code>CriteriaBuilder.not()</code> method. + * + * @return boolean indicating if the predicate is + * a negated predicate + */ + boolean isNegated(); - /** - * Return the top-level conjuncts or disjuncts of the predicate. + /** + * Return the top-level conjuncts or disjuncts of the predicate. * Returns empty list if there are no top-level conjuncts or * disjuncts of the predicate. * Modifications to the list do not affect the query. + * * @return list of boolean expressions forming the predicate - */ - List<Expression<Boolean>> getExpressions(); + */ + List<Expression<Boolean>> getExpressions(); - /** - * Create a negation of the predicate. - * @return negated predicate - */ - Predicate negate(); -} \ No newline at end of file + /** + * Create a negation of the predicate. + * + * @return negated predicate + */ + Predicate not(); + +} Deleted: jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,1661 +0,0 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence.criteria; - -import java.math.BigDecimal; -import java.math.BigInteger; -import java.util.Collection; -import java.util.Map; -import java.util.Set; -import javax.persistence.Tuple; - -/** - * Factory object for queries, select lists, restrictions, - * expressions, orderings - * Note that Predicate is used instead of Expression<Boolean> - * in this API in order to work around the fact that Java - * generics are not compatible with varags. - */ -public interface QueryBuilder { - - /** - * Create a Criteria query object. - * - * @return query object - */ - CriteriaQuery<Object> createQuery(); - - /** - * Create a Criteria query object with the specified result - * type. - * - * @param resultClass type of the query result - * - * @return query object - */ - <T> CriteriaQuery<T> createQuery(Class<T> resultClass); - - /** - * Create a Criteria query object that returns a tuple of - * objects as its result. - * - * @return query object - */ - CriteriaQuery<Tuple> createTupleQuery(); - - - /** - * Define a selection item corresponding to a constructor. - * - * @param result class whose instance is to be constructed - * @param selections arguments to the constructor - * - * @return compound selection item - * - * @throws IllegalArgumentException if an argument is a tuple- or - * array-valued selection item - */ - <Y> CompoundSelection<Y> construct(Class<Y> result, Selection<?>... selections); - - /** - * Define a tuple-valued selection item - * - * @param selections selection items - * - * @return tuple-valued compound selection - * - * @throws IllegalArgumentException if an argument is a tuple- or - * array-valued selection item - */ - CompoundSelection<Tuple> tuple(Selection<?>... selections); - - /** - * Define a array-valued selection item - * - * @param selections selection items - * - * @return array-valued compound selection - * - * @throws IllegalArgumentException if an argument is a tuple- or - * array-valued selection item - */ - CompoundSelection<Object[]> array(Selection<?>... selections); - - - //ordering: - - /** - * Create an ordering by the ascending value of the expression. - * - * @param x expression used to define the ordering - * - * @return ascending ordering corresponding to the expression - */ - Order asc(Expression<?> x); - - /** - * Create an ordering by the descending value of the expression. - * - * @param x expression used to define the ordering - * - * @return descending ordering corresponding to the expression - */ - Order desc(Expression<?> x); - - - //aggregate functions: - - /** - * Create an expression applying the avg operation. - * - * @param x expression representing input value to avg operation - * - * @return avg expression - */ - <N extends Number> Expression<Double> avg(Expression<N> x); - - /** - * Create an expression applying the sum operation. - * - * @param x expression representing input value to sum operation - * - * @return sum expression - */ - <N extends Number> Expression<N> sum(Expression<N> x); - - /** - * Create an expression applying the numerical max operation. - * - * @param x expression representing input value to max operation - * - * @return max expression - */ - <N extends Number> Expression<N> max(Expression<N> x); - - /** - * Create an expression applying the numerical min operation. - * - * @param x expression representing input value to min operation - * - * @return min expression - */ - <N extends Number> Expression<N> min(Expression<N> x); - - /** - * Create an aggregate expression for finding the greatest of - * the values (strings, dates, etc). - * - * @param x expression representing input value to greatest - * operation - * - * @return greatest expression - */ - <X extends Comparable<X>> Expression<X> greatest(Expression<X> x); - - /** - * Create an aggregate expression for finding the least of - * the values (strings, dates, etc). - * - * @param x expression representing input value to least - * operation - * - * @return least expression - */ - <X extends Comparable<X>> Expression<X> least(Expression<X> x); - - /** - * Create an expression applying the count operation. - * - * @param x expression representing input value to count - * operation - * - * @return count expression - */ - Expression<Long> count(Expression<?> x); - - /** - * Create an expression applying the count distinct operation. - * - * @param x expression representing input value to - * count distinct operation - * - * @return count distinct expression - */ - Expression<Long> countDistinct(Expression<?> x); - - - //subqueries: - - /** - * Create a predicate testing the existence of a subquery result. - * - * @param subquery subquery whose result is to be tested - * - * @return exists predicate - */ - Predicate exists(Subquery<?> subquery); - - /** - * Create a predicate corresponding to an all expression over the - * subquery results. - * - * @param subquery - * - * @return all expression - */ - <Y> Expression<Y> all(Subquery<Y> subquery); - - /** - * Create a predicate corresponding to a some expression over the - * subquery results. This is equivalent to an any expression. - * - * @param subquery - * - * @return all expression - */ - <Y> Expression<Y> some(Subquery<Y> subquery); - - /** - * Create a predicate corresponding to an any expression over the - * subquery results. This is equivalent to a some expression. - * - * @param subquery - * - * @return any expression - */ - <Y> Expression<Y> any(Subquery<Y> subquery); - - - //boolean functions: - - /** - * Create a conjunction of the given boolean expressions. - * - * @param x boolean expression - * @param y boolean expression - * - * @return and predicate - */ - Predicate and(Expression<Boolean> x, Expression<Boolean> y); - - /** - * Create a conjunction of the given restriction predicates. - * A conjunction of zero predicates is true. - * - * @param restrictions zero or more restriction predicates - * - * @return and predicate - */ - Predicate and(Predicate... restrictions); - - /** - * Create a disjunction of the given boolean expressions. - * - * @param x boolean expression - * @param y boolean expression - * - * @return or predicate - */ - Predicate or(Expression<Boolean> x, Expression<Boolean> y); - - /** - * Create a conjunction of the given restriction predicates. - * A disjunction of zero predicates is false. - * - * @param restrictions zero or more restriction predicates - * - * @return or predicate - */ - Predicate or(Predicate... restrictions); - - /** - * Create a negation of the given restriction. - * - * @param restriction restriction expression - * - * @return not predicate - */ - Predicate not(Expression<Boolean> restriction); - - /** - * Create a conjunction (with zero conjuncts). - * A conjunction with zero conjuncts is true. - * - * @return and predicate - */ - Predicate conjunction(); - - /** - * Create a disjunction (with zero disjuncts). - * A disjunction with zero disjuncts is false. - * - * @return or predicate - */ - Predicate disjunction(); - - - //turn Expression<Boolean> into a Predicate - //useful for use with varargs methods - - /** - * Create a predicate testing for a true value. - * - * @param x expression to be tested if true - * - * @return predicate - */ - Predicate isTrue(Expression<Boolean> x); - - /** - * Create a predicate testing for a false value. - * - * @param x expression to be tested if false - * - * @return predicate - */ - Predicate isFalse(Expression<Boolean> x); - - - //null tests: - - /** - * Create a predicate to test whether the expression is null. - * - * @param x expression - * - * @return predicate - */ - Predicate isNull(Expression<?> x); - - /** - * Create a predicate to test whether the expression is not null. - * - * @param x expression - * - * @return predicate - */ - Predicate isNotNull(Expression<?> x); - - //equality: - - /** - * Create a predicate for testing the arguments for equality. - * - * @param x expression - * @param y expression - * - * @return equality predicate - */ - Predicate equal(Expression<?> x, Expression<?> y); - - /** - * Create a predicate for testing the arguments for inequality. - * - * @param x expression - * @param y expression - * - * @return inequality predicate - */ - Predicate notEqual(Expression<?> x, Expression<?> y); - - /** - * Create a predicate for testing the arguments for equality. - * - * @param x expression - * @param y object - * - * @return equality predicate - */ - Predicate equal(Expression<?> x, Object y); - - /** - * Create a predicate for testing the arguments for inequality. - * - * @param x expression - * @param y object - * - * @return inequality predicate - */ - Predicate notEqual(Expression<?> x, Object y); - - - //comparisons for generic (non-numeric) operands: - - /** - * Create a predicate for testing whether the first argument is - * greater than the second. - * - * @param x expression - * @param y expression - * - * @return greater-than predicate - */ - <Y extends Comparable<Y>> Predicate greaterThan(Expression<? extends Y> x, Expression<? extends Y> y); - - /** - * Create a predicate for testing whether the first argument is - * less than the second. - * - * @param x expression - * @param y expression - * - * @return less-than predicate - */ - <Y extends Comparable<Y>> Predicate lessThan(Expression<? extends Y> x, Expression<? extends Y> y); - - /** - * Create a predicate for testing whether the first argument is - * greater than or equal to the second. - * - * @param x expression - * @param y expression - * - * @return greater-than-or-equal predicate - */ - <Y extends Comparable<Y>> Predicate greaterThanOrEqualTo(Expression<? extends Y> x, Expression<? extends Y> y); - - /** - * Create a predicate for testing whether the first argument is - * less than or equal to the second. - * - * @param x expression - * @param y expression - * - * @return less-than-or-equal predicate - */ - <Y extends Comparable<Y>> Predicate lessThanOrEqualTo(Expression<? extends Y> x, Expression<? extends Y> y); - - /** - * Create a predicate for testing whether the first argument is - * between the second and third arguments in value. - * - * @param v expression - * @param x expression - * @param y expression - * - * @return between predicate - */ - <Y extends Comparable<Y>> Predicate between(Expression<? extends Y> v, Expression<? extends Y> x, Expression<? extends Y> y); - - /** - * Create a predicate for testing whether the first argument is - * greater than the second. - * - * @param x expression - * @param y value - * - * @return greater-than predicate - */ - <Y extends Comparable<Y>> Predicate greaterThan(Expression<? extends Y> x, Y y); - - /** - * Create a predicate for testing whether the first argument is - * less than the second. - * - * @param x expression - * @param y value - * - * @return less-than predicate - */ - <Y extends Comparable<Y>> Predicate lessThan(Expression<? extends Y> x, Y y); - - /** - * Create a predicate for testing whether the first argument is - * greater than or equal to the second. - * - * @param x expression - * @param y value - * - * @return greater-than-or-equal predicate - */ - <Y extends Comparable<Y>> Predicate greaterThanOrEqualTo(Expression<? extends Y> x, Y y); - - /** - * Create a predicate for testing whether the first argument is - * less than or equal to the second. - * - * @param x expression - * @param y value - * - * @return less-than-or-equal predicate - */ - <Y extends Comparable<Y>> Predicate lessThanOrEqualTo(Expression<? extends Y> x, Y y); - - /** - * Create a predicate for testing whether the first argument is - * between the second and third arguments in value. - * - * @param v expression - * @param x value - * @param y value - * - * @return between predicate - */ - <Y extends Comparable<Y>> Predicate between(Expression<? extends Y> v, Y x, Y y); - - - //comparisons for numeric operands: - - /** - * Create a predicate for testing whether the first argument is - * greater than the second. - * - * @param x expression - * @param y expression - * - * @return greater-than predicate - */ - Predicate gt(Expression<? extends Number> x, Expression<? extends Number> y); - - /** - * Create a predicate for testing whether the first argument is - * less than the second. - * - * @param x expression - * @param y expression - * - * @return less-than predicate - */ - Predicate lt(Expression<? extends Number> x, Expression<? extends Number> y); - - /** - * Create a predicate for testing whether the first argument is - * greater than or equal to the second. - * - * @param x expression - * @param y expression - * - * @return greater-than-or-equal predicate - */ - Predicate ge(Expression<? extends Number> x, Expression<? extends Number> y); - - /** - * Create a predicate for testing whether the first argument is - * less than or equal to the second. - * - * @param x expression - * @param y expression - * - * @return less-than-or-equal predicate - */ - Predicate le(Expression<? extends Number> x, Expression<? extends Number> y); - - /** - * Create a predicate for testing whether the first argument is - * greater than the second. - * - * @param x expression - * @param y value - * - * @return greater-than predicate - */ - Predicate gt(Expression<? extends Number> x, Number y); - - /** - * Create a predicate for testing whether the first argument is - * less than the second. - * - * @param x expression - * @param y value - * - * @return less-than predicate - */ - Predicate lt(Expression<? extends Number> x, Number y); - - /** - * Create a predicate for testing whether the first argument is - * greater than or equal to the second. - * - * @param x expression - * @param y value - * - * @return greater-than-or-equal predicate - */ - Predicate ge(Expression<? extends Number> x, Number y); - - /** - * Create a predicate for testing whether the first argument is - * less than or equal to the second. - * - * @param x expression - * @param y value - * - * @return less-than-or-equal predicate - */ - Predicate le(Expression<? extends Number> x, Number y); - - - //numerical operations: - - /** - * Create an expression that returns the arithmetic negation - * of its argument. - * - * @param x expression - * - * @return arithmetic negation - */ - <N extends Number> Expression<N> neg(Expression<N> x); - - /** - * Create an expression that returns the absolute value - * of its argument. - * - * @param x expression - * - * @return absolute value - */ - <N extends Number> Expression<N> abs(Expression<N> x); - - /** - * Create an expression that returns the sum - * of its arguments. - * - * @param x expression - * @param y expression - * - * @return sum - */ - <N extends Number> Expression<N> sum(Expression<? extends N> x, Expression<? extends N> y); - - /** - * Create an expression that returns the product - * of its arguments. - * - * @param x expression - * @param y expression - * - * @return product - */ - <N extends Number> Expression<N> prod(Expression<? extends N> x, Expression<? extends N> y); - - /** - * Create an expression that returns the difference - * between its arguments. - * - * @param x expression - * @param y expression - * - * @return difference - */ - <N extends Number> Expression<N> diff(Expression<? extends N> x, Expression<? extends N> y); - - /** - * Create an expression that returns the sum - * of its arguments. - * - * @param x expression - * @param y value - * - * @return sum - */ - <N extends Number> Expression<N> sum(Expression<? extends N> x, N y); - - /** - * Create an expression that returns the product - * of its arguments. - * - * @param x expression - * @param y value - * - * @return product - */ - <N extends Number> Expression<N> prod(Expression<? extends N> x, N y); - - /** - * Create an expression that returns the difference - * between its arguments. - * - * @param x expression - * @param y value - * - * @return difference - */ - <N extends Number> Expression<N> diff(Expression<? extends N> x, N y); - - /** - * Create an expression that returns the sum - * of its arguments. - * - * @param x value - * @param y expression - * - * @return sum - */ - <N extends Number> Expression<N> sum(N x, Expression<? extends N> y); - - /** - * Create an expression that returns the product - * of its arguments. - * - * @param x value - * @param y expression - * - * @return product - */ - <N extends Number> Expression<N> prod(N x, Expression<? extends N> y); - - /** - * Create an expression that returns the difference - * between its arguments. - * - * @param x value - * @param y expression - * - * @return difference - */ - <N extends Number> Expression<N> diff(N x, Expression<? extends N> y); - - /** - * Create an expression that returns the quotient - * of its arguments. - * - * @param x expression - * @param y expression - * - * @return quotient - */ - Expression<Number> quot(Expression<? extends Number> x, Expression<? extends Number> y); - - /** - * Create an expression that returns the quotient - * of its arguments. - * - * @param x expression - * @param y value - * - * @return quotient - */ - Expression<Number> quot(Expression<? extends Number> x, Number y); - - /** - * Create an expression that returns the quotient - * of its arguments. - * - * @param x value - * @param y expression - * - * @return quotient - */ - Expression<Number> quot(Number x, Expression<? extends Number> y); - - /** - * Create an expression that returns the modulus - * of its arguments. - * - * @param x expression - * @param y expression - * - * @return modulus - */ - Expression<Integer> mod(Expression<Integer> x, Expression<Integer> y); - - /** - * Create an expression that returns the modulus - * of its arguments. - * - * @param x expression - * @param y value - * - * @return modulus - */ - Expression<Integer> mod(Expression<Integer> x, Integer y); - - /** - * Create an expression that returns the modulus - * of its arguments. - * - * @param x value - * @param y expression - * - * @return modulus - */ - Expression<Integer> mod(Integer x, Expression<Integer> y); - - /** - * Create an expression that returns the square root - * of its argument. - * - * @param x expression - * - * @return square root - */ - Expression<Double> sqrt(Expression<? extends Number> x); - - - //typecasts: - - /** - * Typecast. - * - * @param number numeric expression - * - * @return Expression<Long> - */ - Expression<Long> toLong(Expression<? extends Number> number); - - /** - * Typecast. - * - * @param number numeric expression - * - * @return Expression<Integer> - */ - Expression<Integer> toInteger(Expression<? extends Number> number); - - /** - * Typecast. - * - * @param number numeric expression - * - * @return Expression<Float> - */ - Expression<Float> toFloat(Expression<? extends Number> number); - - /** - * Typecast. - * - * @param number numeric expression - * - * @return Expression<Double> - */ - Expression<Double> toDouble(Expression<? extends Number> number); - - /** - * Typecast. - * - * @param number numeric expression - * - * @return Expression<BigDecimal> - */ - Expression<BigDecimal> toBigDecimal(Expression<? extends Number> number); - - /** - * Typecast. - * - * @param number numeric expression - * - * @return Expression<BigInteger> - */ - Expression<BigInteger> toBigInteger(Expression<? extends Number> number); - - /** - * Typecast. - * - * @param character expression - * - * @return Expression<String> - */ - Expression<String> toString(Expression<Character> character); - - - //literals: - - /** - * Create an expression literal. - * - * @param value - * - * @return expression literal - */ - <T> Expression<T> literal(T value); - - - //parameters: - - /** - * Create a parameter expression. - * - * @param paramClass parameter class - * - * @return parameter expression - */ - <T> ParameterExpression<T> parameter(Class<T> paramClass); - - /** - * Create a parameter expression with the given name. - * - * @param paramClass parameter class - * @param name - * - * @return parameter expression - */ - <T> ParameterExpression<T> parameter(Class<T> paramClass, String name); - - //collection operations: - - /** - * Create a predicate that tests whether a collection is empty. - * - * @param collection expression - * - * @return predicate - */ - <C extends Collection<?>> Predicate isEmpty(Expression<C> collection); - - /** - * Create a predicate that tests whether a collection is - * not empty. - * - * @param collection expression - * - * @return predicate - */ - <C extends Collection<?>> Predicate isNotEmpty(Expression<C> collection); - - /** - * Create an expression that tests the size of a collection. - * - * @param collection - * - * @return size expression - */ - <C extends Collection<?>> Expression<Integer> size(C collection); - - /** - * Create an expression that tests the size of a collection. - * - * @param collection expression - * - * @return size expression - */ - <C extends java.util.Collection<?>> Expression<Integer> size(Expression<C> collection); - - /** - * Create a predicate that tests whether an element is - * a member of a collection. - * - * @param elem element - * @param collection expression - * - * @return predicate - */ - <E, C extends Collection<E>> Predicate isMember(E elem, Expression<C> collection); - - /** - * Create a predicate that tests whether an element is - * not a member of a collection. - * - * @param elem element - * @param collection expression - * - * @return predicate - */ - <E, C extends Collection<E>> Predicate isNotMember(E elem, Expression<C> collection); - - /** - * Create a predicate that tests whether an element is - * a member of a collection. - * - * @param elem element expression - * @param collection expression - * - * @return predicate - */ - <E, C extends Collection<E>> Predicate isMember(Expression<E> elem, Expression<C> collection); - - /** - * Create a predicate that tests whether an element is - * not a member of a collection. - * - * @param elem element expression - * @param collection expression - * - * @return predicate - */ - <E, C extends Collection<E>> Predicate isNotMember(Expression<E> elem, Expression<C> collection); - - - //get the values and keys collections of the Map, which may then - //be passed to size(), isMember(), isEmpty(), etc - - /** - * Create an expression that returns the values of a map. - * - * @param map - * - * @return collection expression - */ - <V, M extends Map<?, V>> Expression<Collection<V>> values(M map); - - /** - * Create an expression that returns the keys of a map. - * - * @param map - * - * @return set expression - */ - <K, M extends Map<K, ?>> Expression<Set<K>> keys(M map); - - - //string functions: - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * - * @param x string expression - * @param pattern string expression - * - * @return like predicate - */ - Predicate like(Expression<String> x, Expression<String> pattern); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * - * @param x string expression - * @param pattern string expression - * @param escapeChar escape character expression - * - * @return like predicate - */ - Predicate like(Expression<String> x, Expression<String> pattern, Expression<Character> escapeChar); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * - * @param x string expression - * @param pattern string expression - * @param escapeChar escape character - * - * @return like predicate - */ - Predicate like(Expression<String> x, Expression<String> pattern, char escapeChar); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * - * @param x string expression - * @param pattern string - * - * @return like predicate - */ - Predicate like(Expression<String> x, String pattern); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * - * @param x string expression - * @param pattern string - * @param escapeChar escape character expression - * - * @return like predicate - */ - Predicate like(Expression<String> x, String pattern, Expression<Character> escapeChar); - - /** - * Create a predicate for testing whether the expression - * satisfies the given pattern. - * - * @param x string expression - * @param pattern string - * @param escapeChar escape character - * - * @return like predicate - */ - Predicate like(Expression<String> x, String pattern, char escapeChar); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * - * @param x string expression - * @param pattern string expression - * - * @return like predicate - */ - Predicate notLike(Expression<String> x, Expression<String> pattern); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * - * @param x string expression - * @param pattern string expression - * @param escapeChar escape character expression - * - * @return like predicate - */ - Predicate notLike(Expression<String> x, Expression<String> pattern, Expression<Character> escapeChar); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * - * @param x string expression - * @param pattern string expression - * @param escapeChar escape character - * - * @return like predicate - */ - Predicate notLike(Expression<String> x, Expression<String> pattern, char escapeChar); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * - * @param x string expression - * @param pattern string - * - * @return like predicate - */ - Predicate notLike(Expression<String> x, String pattern); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * - * @param x string expression - * @param pattern string - * @param escapeChar escape character expression - * - * @return like predicate - */ - Predicate notLike(Expression<String> x, String pattern, Expression<Character> escapeChar); - - /** - * Create a predicate for testing whether the expression - * does not satisfy the given pattern. - * - * @param x string expression - * @param pattern string - * @param escapeChar escape character - * - * @return like predicate - */ - Predicate notLike(Expression<String> x, String pattern, char escapeChar); - - /** - * String concatenation operation. - * - * @param x string expression - * @param y string expression - * - * @return expression corresponding to concatenation - */ - Expression<String> concat(Expression<String> x, Expression<String> y); - - /** - * String concatenation operation. - * - * @param x string expression - * @param y string - * - * @return expression corresponding to concatenation - */ - Expression<String> concat(Expression<String> x, String y); - - /** - * String concatenation operation. - * - * @param x string - * @param y string expression - * - * @return expression corresponding to concatenation - */ - Expression<String> concat(String x, Expression<String> y); - - /** - * Substring extraction operation. - * Extracts a substring starting at specified position through - * to end of the string. - * First position is 1. - * - * @param x string expression - * @param from start position expression - * - * @return expression corresponding to substring extraction - */ - Expression<String> substring(Expression<String> x, Expression<Integer> from); - - /** - * Substring extraction operation. - * Extracts a substring starting at specified position through - * to end of the string. - * First position is 1. - * - * @param x string expression - * @param from start position - * - * @return expression corresponding to substring extraction - */ - Expression<String> substring(Expression<String> x, int from); - - /** - * Substring extraction operation. - * Extracts a substring of given length starting at - * specified position. - * First position is 1. - * - * @param x string expression - * @param from start position expression - * @param len length expression - * - * @return expression corresponding to substring extraction - */ - Expression<String> substring(Expression<String> x, Expression<Integer> from, Expression<Integer> len); - - /** - * Substring extraction operation. - * Extracts a substring of given length starting at - * specified position. - * First position is 1. - * - * @param x string expression - * @param from start position - * @param len length - * - * @return expression corresponding to substring extraction - */ - Expression<String> substring(Expression<String> x, int from, int len); - - public static enum Trimspec { - LEADING, TRAILING, BOTH - } - - /** - * Create expression to trim blanks from both ends of - * a string. - * - * @param x expression for string to trim - * - * @return trim expression - */ - Expression<String> trim(Expression<String> x); - - /** - * Create expression to trim blanks from a string. - * - * @param ts trim specification - * @param x expression for string to trim - * - * @return trim expression - */ - Expression<String> trim(Trimspec ts, Expression<String> x); - - /** - * Create expression to trim character from both ends of - * a string. - * - * @param t expression for character to be trimmed - * @param x expression for string to trim - * - * @return trim expression - */ - Expression<String> trim(Expression<Character> t, Expression<String> x); - - /** - * Create expression to trim character from a string. - * - * @param ts trim specification - * @param t expression for character to be trimmed - * @param x expression for string to trim - * - * @return trim expression - */ - Expression<String> trim(Trimspec ts, Expression<Character> t, Expression<String> x); - - /** - * Create expression to trim character from both ends of - * a string. - * - * @param t character to be trimmed - * @param x expression for string to trim - * - * @return trim expression - */ - Expression<String> trim(char t, Expression<String> x); - - /** - * Create expression to trim character from a string. - * - * @param ts trim specification - * @param t character to be trimmed - * @param x expression for string to trim - * - * @return trim expression - */ - Expression<String> trim(Trimspec ts, char t, Expression<String> x); - - /** - * Create expression for converting a string to lowercase. - * - * @param x string expression - * - * @return expression to convert to lowercase - */ - Expression<String> lower(Expression<String> x); - - /** - * Create expression for converting a string to uppercase. - * - * @param x string expression - * - * @return expression to convert to uppercase - */ - Expression<String> upper(Expression<String> x); - - /** - * Create expression to return length of a string. - * - * @param x string expression - * - * @return length expression - */ - Expression<Integer> length(Expression<String> x); - - - /** - * Create expression to locate the position of one string - * within another, returning position of first character - * if found. - * The first position in a string is denoted by 1. If the - * string to be located is not found, 0 is returned. - * - * @param x expression for string to be searched - * @param pattern expression for string to be located - * - * @return expression corresponding to position - */ - Expression<Integer> locate(Expression<String> x, Expression<String> pattern); - - /** - * Create expression to locate the position of one string - * within another, returning position of first character - * if found. - * The first position in a string is denoted by 1. If the - * string to be located is not found, 0 is returned. - * - * @param x expression for string to be searched - * @param pattern expression for string to be located - * @param from expression for position at which to start search - * - * @return expression corresponding to position - */ - Expression<Integer> locate(Expression<String> x, Expression<String> pattern, Expression<Integer> from); - - /** - * Create expression to locate the position of one string - * within another, returning position of first character - * if found. - * The first position in a string is denoted by 1. If the - * string to be located is not found, 0 is returned. - * - * @param x expression for string to be searched - * @param pattern string to be located - * - * @return expression corresponding to position - */ - Expression<Integer> locate(Expression<String> x, String pattern); - - /** - * Create expression to locate the position of one string - * within another, returning position of first character - * if found. - * The first position in a string is denoted by 1. If the - * string to be located is not found, 0 is returned. - * - * @param x expression for string to be searched - * @param pattern string to be located - * @param from position at which to start search - * - * @return expression corresponding to position - */ - Expression<Integer> locate(Expression<String> x, String pattern, int from); - - - // Date/time/timestamp functions: - - /** - * Create expression to return current date. - * - * @return expression for current date - */ - Expression<java.sql.Date> currentDate(); - - /** - * Create expression to return current timestamp. - * - * @return expression for current timestamp - */ - Expression<java.sql.Timestamp> currentTimestamp(); - - /** - * Create expression to return current time. - * - * @return expression for current time - */ - Expression<java.sql.Time> currentTime(); - - - //in builders: - - /** - * Interface used to build in-expressions. - */ - public static interface In<T> extends Predicate { - - /** - * Returns the expression to be tested against the - * list of values. - * - * @return expression - */ - Expression<T> getExpression(); - - /** - * Add to list of values to be tested against. - * - * @param value - * - * @return in predicate - */ - In<T> value(T value); - - /** - * Add to list of values to be tested against. - * - * @param value expression - * - * @return in predicate - */ - In<T> value(Expression<? extends T> value); - } - - /** - * Create predicate to test whether given expression - * is contained in a list of values. - * - * @param expression to be tested against list of values - * - * @return in predicate - */ - <T> In<T> in(Expression<? extends T> expression); - - - //coalesce, nullif: - - /** - * Create an expression that returns null if all its arguments - * evaluate to null, and the value of the first non-null argument - * otherwise. - * - * @param x expression - * @param y expression - * - * @return expression corresponding to the given coalesce - * expression - */ - <Y> Expression<Y> coalesce(Expression<? extends Y> x, Expression<? extends Y> y); - - /** - * Create an expression that returns null if all its arguments - * evaluate to null, and the value of the first non-null argument - * otherwise. - * - * @param x expression - * @param y value - * - * @return coalesce expression - */ - <Y> Expression<Y> coalesce(Expression<? extends Y> x, Y y); - - /** - * Create an expression that tests whether its argument are - * equal, returning null if they are and the value of the - * first expression if they are not. - * - * @param x expression - * @param y expression - * - * @return expression corresponding to the given nullif - * expression - */ - <Y> Expression<Y> nullif(Expression<Y> x, Expression<?> y); - - - /** - * Create an expression that tests whether its argument are - * equal, returning null if they are and the value of the - * first expression if they are not. - * - * @param x expression - * @param y value - * - * @return expression corresponding to the given nullif - * expression - */ - <Y> Expression<Y> nullif(Expression<Y> x, Y y); - - - // coalesce builder: - - /** - * Interface used to build coalesce expressions. - * A coalesce expression is equivalent to a case expression - * that returns null if all its arguments evaluate to null, - * and the value of its first non-null argument otherwise. - */ - public static interface Coalesce<T> extends Expression<T> { - - /** - * Add an argument to the coalesce expression. - * - * @param value - * - * @return coalesce expression - */ - Coalesce<T> value(T value); - - /** - * Add an argument to the coalesce expression. - * - * @param value expression - * - * @return coalesce expression - */ - Coalesce<T> value(Expression<? extends T> value); - } - - /** - * Create a coalesce expression. - * - * @return coalesce expression - */ - <T> Coalesce<T> coalesce(); - - - //case builders: - - /** - * Interface used to build simple case expressions. - */ - public static interface SimpleCase<C, R> extends Expression<R> { - - /** - * Returns the expression to be tested against the - * conditions. - * - * @return expression - */ - Expression<C> getExpression(); - - /** - * Add a when/then clause to the case expression. - * - * @param condition "when" condition - * @param result "then" result value - * - * @return simple case expression - */ - SimpleCase<C, R> when(C condition, R result); - - /** - * Add a when/then clause to the case expression. - * - * @param condition "when" condition - * @param result "then" result expression - * - * @return simple case expression - */ - SimpleCase<C, R> when(C condition, Expression<? extends R> result); - - /** - * Add an "else" clause to the case expression. - * - * @param result "else" result - * - * @return expression - */ - Expression<R> otherwise(R result); - - /** - * Add an "else" clause to the case expression. - * - * @param result "else" result expression - * - * @return expression - */ - Expression<R> otherwise(Expression<? extends R> result); - } - - /** - * Create simple case expression. - * - * @param expression to be tested against the case conditions - * - * @return simple case expression - */ - <C, R> SimpleCase<C, R> selectCase(Expression<? extends C> expression); - - - /** - * Interface used to build general case expressions. - */ - public static interface Case<R> extends Expression<R> { - - /** - * Add a when/then clause to the case expression. - * - * @param condition "when" condition - * @param result "then" result value - * - * @return general case expression - */ - Case<R> when(Expression<Boolean> condition, R result); - - /** - * Add a when/then clause to the case expression. - * - * @param condition "when" condition - * @param result "then" result expression - * - * @return general case expression - */ - Case<R> when(Expression<Boolean> condition, Expression<? extends R> result); - - /** - * Add an "else" clause to the case expression. - * - * @param result "else" result - * - * @return expression - */ - Expression<R> otherwise(R result); - - /** - * Add an "else" clause to the case expression. - * - * @param result "else" result expression - * - * @return expression - */ - Expression<R> otherwise(Expression<? extends R> result); - } - - /** - * Create a general case expression. - * - * @return general case expression - */ - <R> Case<R> selectCase(); - - /** - * Create an expression for execution of a database - * function. - * - * @param name function name - * @param type expected result type - * @param args function arguments - * - * @return expression - */ - <T> Expression<T> function(String name, Class<T> type, - Expression<?>... args); - -} \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Root.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Root.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Root.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -9,13 +9,14 @@ * Query roots always reference entities. * * @param <X> the entity type referenced by the root + * @since Java Persistence 2.0 */ public interface Root<X> extends From<X, X> { - /** - * Return the metamodel entity corresponding to the root. - * @return metamodel entity corresponding to the root - */ - EntityType<X> getModel(); + /** + * Return the metamodel entity corresponding to the root. + * + * @return metamodel entity corresponding to the root + */ + EntityType<X> getModel(); } - Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Selection.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Selection.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Selection.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,32 +6,41 @@ import java.util.List; /** - * The Selection interface defines an item that to be - * returned in the query result. + * The <code>Selection</code> interface defines an item that is to be + * returned in a query result. + * * @param <X> the type of the selection item + * @since Java Persistence 2.0 */ public interface Selection<X> extends TupleElement<X> { + /** + * Assigns an alias to the selection item. + * Once assigned, an alias cannot be changed or reassigned. + * Returns the same selection item. + * + * @param name alias + * + * @return selection item + */ + Selection<X> alias(String name); - /** - * Return a selection item with the assigned alias. - * @param name alias - * @return selection item - */ - Selection<X> alias(String name); + /** + * Whether the selection item is a compound selection. + * + * @return boolean indicating whether the selection is a compound + * selection + */ + boolean isCompoundSelection(); - /** - * Whether the selection item is a compound selection - * @return boolean - */ - boolean isCompoundSelection(); - - /** - * Return selection items composing a compound selection - * @return list of selection items - * @throws IllegalStateException if selection is not a compound - * selection - */ - List<Selection<?>> getCompoundSelectionItems(); - + /** + * Return the selection items composing a compound selection. + * Modifications to the list do not affect the query. + * + * @return list of selection items + * + * @throws IllegalStateException if selection is not a + * compound selection + */ + List<Selection<?>> getCompoundSelectionItems(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/SetJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/SetJoin.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/SetJoin.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,19 +6,20 @@ import javax.persistence.metamodel.SetAttribute; /** - * The SetJoin interface is the type of the result of + * The <code>SetJoin</code> interface is the type of the result of * joining to a collection over an association or element - * collection that has been specified as a java.util.Set. + * collection that has been specified as a <code>java.util.Set</code>. * - * @param <Z> The source type of the join - * @param <E> The element type of the target Set + * @param <Z> the source type of the join + * @param <E> the element type of the target <code>Set</code> + * @since Java Persistence 2.0 */ public interface SetJoin<Z, E> extends PluralJoin<Z, Set<E>, E> { - - /** - * Return the metamodel representation for the set attribute. - * @return metamodel type representing the Set that is - * the target of the join - */ - SetAttribute<? super Z, E> getModel(); + /** + * Return the metamodel representation for the set attribute. + * + * @return metamodel type representing the <code>Set</code> that is + * the target of the join + */ + SetAttribute<? super Z, E> getModel(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Subquery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Subquery.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Subquery.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,62 +3,73 @@ package javax.persistence.criteria; import java.util.List; +import java.util.Set; /** - * The Subquery interface defines functionality that is + * The <code>Subquery</code> interface defines functionality that is * specific to subqueries. * * A subquery has an expression as its selection item. - * @param <T> the type of the returned selection item. + * + * @param <T> the type of the selection item. + * @since Java Persistence 2.0 */ public interface Subquery<T> extends AbstractQuery<T>, Expression<T> { + /** + * Specify the item that is to be returned as the subquery + * result. + * Replaces the previously specified selection, if any. + * + * @param expression expression specifying the item that + * is to be returned as the subquery result + * + * @return the modified subquery + */ + Subquery<T> select(Expression<T> expression); - /** - * Specify the item that is to be returned in the query result. - * Replaces the previously specified selection, if any. - * @param expression expression specifying the item that - * is returned in the query result - * @return the modified subquery - */ - Subquery<T> select(Expression<T> expression); + /** + * Modify the subquery to restrict the result according + * to the specified boolean expression. + * Replaces the previously added restriction(s), if any. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param restriction a simple or compound boolean expression + * + * @return the modified subquery + */ + Subquery<T> where(Expression<Boolean> restriction); - /** - * Modify the subquery to restrict the result according - * to the specified boolean expression. - * Replaces the previously added restriction(s), if any. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restriction a simple or compound boolean expression - * @return the modified subquery - */ - Subquery<T> where(Expression<Boolean> restriction); + /** + * Modify the subquery to restrict the result according + * to the conjunction of the specified restriction predicates. + * Replaces the previously added restriction(s), if any. + * If no restrictions are specified, any previously added + * restrictions are simply removed. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param restrictions zero or more restriction predicates + * + * @return the modified subquery + */ + Subquery<T> where(Predicate... restrictions); - /** - * Modify the subquery to restrict the result according - * to the conjunction of the specified restriction predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restrictions zero or more restriction predicates - * @return the modified subquery - */ - Subquery<T> where(Predicate... restrictions); + /** + * Specify the expressions that are used to form groups over + * the subquery results. + * Replaces the previous specified grouping expressions, if any. + * If no grouping expressions are specified, any previously + * added grouping expressions are simply removed. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param grouping zero or more grouping expressions + * + * @return the modified subquery + */ + Subquery<T> groupBy(Expression<?>... grouping); - /** - * Specify the expressions that are used to form groups over - * the subquery results. - * Replaces the previous specified grouping expressions, if any. - * If no grouping expressions are specified, any previously - * added grouping expressions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param grouping zero or more grouping expressions - * @return the modified subquery - */ - Subquery<T> groupBy(Expression<?>... grouping); - /** * Specify the expressions that are used to form groups over * the subquery results. @@ -66,119 +77,140 @@ * If no grouping expressions are specified, any previously * added grouping expressions are simply removed. * This method only overrides the return type of the - * corresponding AbstractQuery method. + * corresponding <code>AbstractQuery</code> method. + * * @param grouping list of zero or more grouping expressions + * * @return the modified subquery */ Subquery<T> groupBy(List<Expression<?>> grouping); - /** - * Specify a restriction over the groups of the subquery. - * Replaces the previous having restriction(s), if any. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restriction a simple or compound boolean expression - * @return the modified subquery - */ - Subquery<T> having(Expression<Boolean> restriction); + /** + * Specify a restriction over the groups of the subquery. + * Replaces the previous having restriction(s), if any. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param restriction a simple or compound boolean expression + * + * @return the modified subquery + */ + Subquery<T> having(Expression<Boolean> restriction); - /** - * Specify restrictions over the groups of the subquery - * according the conjunction of the specified restriction - * predicates. - * Replaces the previously added restriction(s), if any. - * If no restrictions are specified, any previously added - * restrictions are simply removed. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param restrictions zero or more restriction predicates - * @return the modified subquery - */ - Subquery<T> having(Predicate... restrictions); + /** + * Specify restrictions over the groups of the subquery + * according the conjunction of the specified restriction + * predicates. + * Replaces the previously added having restriction(s), if any. + * If no restrictions are specified, any previously added + * restrictions are simply removed. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param restrictions zero or more restriction predicates + * + * @return the modified subquery + */ + Subquery<T> having(Predicate... restrictions); - /** - * Specify whether duplicate query results will be eliminated. - * A true value will cause duplicates to be eliminated. - * A false value will cause duplicates to be retained. - * If distinct has not been specified, duplicate results must - * be retained. - * This method only overrides the return type of the - * corresponding AbstractQuery method. - * @param distinct boolean value specifying whether duplicate - * results must be eliminated from the subquery result or - * whether they must be retained - * @return the modified subquery. - */ - Subquery<T> distinct(boolean distinct); + /** + * Specify whether duplicate query results will be eliminated. + * A true value will cause duplicates to be eliminated. + * A false value will cause duplicates to be retained. + * If distinct has not been specified, duplicate results must + * be retained. + * This method only overrides the return type of the + * corresponding <code>AbstractQuery</code> method. + * + * @param distinct boolean value specifying whether duplicate + * results must be eliminated from the subquery result or + * whether they must be retained + * + * @return the modified subquery. + */ + Subquery<T> distinct(boolean distinct); - /** - * Create a subquery root correlated to a root of the + /** + * Create a subquery root correlated to a root of the * enclosing query. + * * @param parentRoot a root of the containing query + * * @return subquery root - */ - <Y> Root<Y> correlate(Root<Y> parentRoot); + */ + <Y> Root<Y> correlate(Root<Y> parentRoot); - /** + /** * Create a subquery join object correlated to a join object * of the enclosing query. + * * @param parentJoin join object of the containing query + * * @return subquery join */ - <X, Y> Join<X, Y> correlate(Join<X, Y> parentJoin); + <X, Y> Join<X, Y> correlate(Join<X, Y> parentJoin); - /** + /** * Create a subquery collection join object correlated to a * collection join object of the enclosing query. + * * @param parentCollection join object of the containing query + * * @return subquery join - */ - <X, Y> CollectionJoin<X, Y> correlate(CollectionJoin<X, Y> parentCollection); + */ + <X, Y> CollectionJoin<X, Y> correlate(CollectionJoin<X, Y> parentCollection); - /** + /** * Create a subquery set join object correlated to a set join * object of the enclosing query. + * * @param parentSet join object of the containing query + * * @return subquery join - */ - <X, Y> SetJoin<X, Y> correlate(SetJoin<X, Y> parentSet); + */ + <X, Y> SetJoin<X, Y> correlate(SetJoin<X, Y> parentSet); - /** + /** * Create a subquery list join object correlated to a list join * object of the enclosing query. + * * @param parentList join object of the containing query + * * @return subquery join - */ - <X, Y> ListJoin<X, Y> correlate(ListJoin<X, Y> parentList); + */ + <X, Y> ListJoin<X, Y> correlate(ListJoin<X, Y> parentList); - /** + /** * Create a subquery map join object correlated to a map join * object of the enclosing query. + * * @param parentMap join object of the containing query + * * @return subquery join - */ - <X, K, V> MapJoin<X, K, V> correlate(MapJoin<X, K, V> parentMap); + */ + <X, K, V> MapJoin<X, K, V> correlate(MapJoin<X, K, V> parentMap); - /** - * Return the query of which this is a subquery. - * @return the enclosing query or subquery - */ - AbstractQuery<?> getParent(); + /** + * Return the query of which this is a subquery. + * + * @return the enclosing query or subquery + */ + AbstractQuery<?> getParent(); - /** - * Return the selection expression. - * @return the item to be returned in the subquery result - */ - Expression<T> getSelection(); + /** + * Return the selection expression. + * + * @return the item to be returned in the subquery result + */ + Expression<T> getSelection(); - /** - * Return the joins that have been made from the subquery. - * Does not include joins from map keys, if any. - * Returns empty set if there are no joins made from the - * subquery. + /** + * Return the correlated joins of the subquery. + * Returns empty set if the subquery has no correlated + * joins. * Modifications to the set do not affect the query. - * @return joins made from this type - */ - java.util.Set<Join<?, ?>> getCorrelatedJoins(); - + * + * @return the correlated joins of the subquery + */ + Set<Join<?, ?>> getCorrelatedJoins(); } \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/Attribute.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/Attribute.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/Attribute.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,16 +3,48 @@ package javax.persistence.metamodel; /** - * An attribute of a Java type + * Represents an attribute of a Java type. * * @param <X> The represented type that contains the attribute * @param <Y> The type of the represented attribute + * @since Java Persistence 2.0 */ public interface Attribute<X, Y> { + public static enum PersistentAttributeType { + /** + * Many-to-one association + */ + MANY_TO_ONE, - public static enum PersistentAttributeType { - MANY_TO_ONE, ONE_TO_ONE, BASIC, EMBEDDED, - MANY_TO_MANY, ONE_TO_MANY, ELEMENT_COLLECTION + /** + * One-to-one association + */ + ONE_TO_ONE, + + /** + * Basic attribute + */ + BASIC, + + /** + * Embeddable class attribute + */ + EMBEDDED, + + /** + * Many-to-many association + */ + MANY_TO_MANY, + + /** + * One-to-many association + */ + ONE_TO_MANY, + + /** + * Element collection + */ + ELEMENT_COLLECTION } /** @@ -45,25 +77,26 @@ Class<Y> getJavaType(); /** - * Return the java.lang.reflect.Member for the represented + * Return the <code>java.lang.reflect.Member</code> for the represented * attribute. * - * @return corresponding java.lang.reflect.Member + * @return corresponding <code>java.lang.reflect.Member</code> */ java.lang.reflect.Member getJavaMember(); /** * Is the attribute an association. * - * @return whether boolean indicating whether attribute + * @return boolean indicating whether the attribute * corresponds to an association */ boolean isAssociation(); /** - * Is the attribute collection-valued. + * Is the attribute collection-valued (represents a Collection, + * Set, List, or Map). * - * @return boolean indicating whether attribute is + * @return boolean indicating whether the attribute is * collection-valued */ boolean isCollection(); Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/BasicType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/BasicType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/BasicType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,12 +1,14 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type BasicType represent basic types (including + * Instances of the type <code>BasicType</code> represent basic types (including * temporal and enumerated types). * * @param <X> The type of the represented basic type + * + * @since Java Persistence 2.0 */ public interface BasicType<X> extends Type<X> { } Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/Bindable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/Bindable.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/Bindable.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,15 +3,28 @@ package javax.persistence.metamodel; /** - * Instances of the type Bindable represent object or attribute types - * that can be bound into a Path. + * Instances of the type <code>Bindable</code> represent object or attribute types + * that can be bound into a {@link javax.persistence.criteria.Path Path}. * * @param <T> The type of the represented object or attribute + * @since Java Persistence 2.0 */ public interface Bindable<T> { + public static enum BindableType { + /** + * Single-valued attribute type + */ + SINGULAR_ATTRIBUTE, - public static enum BindableType { - SINGULAR_ATTRIBUTE, PLURAL_ATTRIBUTE, ENTITY_TYPE + /** + * Multi-valued attribute type + */ + PLURAL_ATTRIBUTE, + + /** + * Entity type + */ + ENTITY_TYPE } /** @@ -23,9 +36,10 @@ /** * Return the Java type of the represented object. - * If the bindable type of the object is PLURAL_ATTRIBUTE, + * If the bindable type of the object is <code>PLURAL_ATTRIBUTE</code>, * the Java element type is returned. If the bindable type is - * SINGULAR_ATTRIBUTE or ENTITY_TYPE, the Java type of the + * <code>SINGULAR_ATTRIBUTE</code> or <code>ENTITY_TYPE</code>, + * the Java type of the * represented entity or attribute is returned. * * @return Java type Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/CollectionAttribute.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/CollectionAttribute.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/CollectionAttribute.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,15 +1,14 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type CollectionAttribute represent persistent - * Collection-valued attributes. + * Instances of the type <code>CollectionAttribute</code> represent persistent + * <code>java.util.Collection</code>-valued attributes. * * @param <X> The type the represented Collection belongs to * @param <E> The element type of the represented Collection + * @since Java Persistence 2.0 */ -public interface CollectionAttribute<X, E> - extends PluralAttribute<X, java.util.Collection<E>, E> { +public interface CollectionAttribute<X, E> extends PluralAttribute<X, java.util.Collection<E>, E> { } - Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/EmbeddableType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/EmbeddableType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/EmbeddableType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,11 +1,12 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type EmbeddableType represent embeddable types. + * Instances of the type <code>EmbeddableType</code> represent embeddable types. * * @param <X> The represented type. + * @since Java Persistence 2.0 */ public interface EmbeddableType<X> extends ManagedType<X> { } Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/EntityType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/EntityType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/EntityType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,17 +1,16 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type EntityType represent entity types. + * Instances of the type <code>EntityType</code> represent entity types. * * @param <X> The represented entity type. + * @since Java Persistence 2.0 */ -public interface EntityType<X> - extends IdentifiableType<X>, Bindable<X> { - +public interface EntityType<X> extends IdentifiableType<X>, Bindable<X> { /** - * Return the entity name + * Return the entity name. * * @return entity name */ Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/IdentifiableType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/IdentifiableType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/IdentifiableType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,14 +2,16 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; +import java.util.Set; + /** - * Instances of the type IdentifiableType represent entity or + * Instances of the type <code>IdentifiableType</code> represent entity or * mapped superclass types. * * @param <X> The represented entity or mapped superclass type. + * @since Java Persistence 2.0 */ public interface IdentifiableType<X> extends ManagedType<X> { - /** * Return the attribute that corresponds to the id attribute of * the entity or mapped superclass. @@ -28,7 +30,8 @@ * Return the attribute that corresponds to the id attribute * declared by the entity or mapped superclass. * - * @param type the type of the represented declared id attribute + * @param type the type of the represented declared + * id attribute * * @return declared id attribute * @@ -70,25 +73,26 @@ * specific mapped superclass or entity extended by the entity * or mapped superclass. * - * @return supertype of identifiable type or null if no such supertype + * @return supertype of identifiable type or null if no + * such supertype */ IdentifiableType<? super X> getSupertype(); /** - * Whether or not the identifiable type has an id attribute. + * Whether the identifiable type has a single id attribute. * Returns true for a simple id or embedded id; returns false * for an idclass. * - * @return boolean indicating whether or not the identifiable - * type has a single id attribute + * @return boolean indicating whether the identifiable + * type has a single id attribute */ boolean hasSingleIdAttribute(); /** - * Whether or not the identifiable type has a version attribute. + * Whether the identifiable type has a version attribute. * - * @return boolean indicating whether or not the identifiable - * type has a version attribute + * @return boolean indicating whether the identifiable + * type has a version attribute */ boolean hasVersionAttribute(); @@ -101,7 +105,7 @@ * @throws IllegalArgumentException if the identifiable type * does not have an id class */ - java.util.Set<SingularAttribute<? super X, ?>> getIdClassAttributes(); + Set<SingularAttribute<? super X, ?>> getIdClassAttributes(); /** * Return the type that represents the type of the id. @@ -110,4 +114,3 @@ */ Type<?> getIdType(); } - Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/ListAttribute.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/ListAttribute.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/ListAttribute.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,14 +1,15 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type ListAttribute represent persistent - * List-valued attributes. + * Instances of the type <code>ListAttribute</code> represent persistent + * <code>javax.util.List</code>-valued attributes. * * @param <X> The type the represented List belongs to * @param <E> The element type of the represented List + * @since Java Persistence 2.0 */ public interface ListAttribute<X, E> extends PluralAttribute<X, java.util.List<E>, E> { -} \ No newline at end of file +} Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/ManagedType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/ManagedType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/ManagedType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,33 +2,35 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; +import java.util.Set; + /** - * Instances of the type ManagedType represent entity, mapped + * Instances of the type <code>ManagedType</code> represent entity, mapped * superclass, and embeddable types. * * @param <X> The represented type. + * @since Java Persistence 2.0 */ public interface ManagedType<X> extends Type<X> { - /** * Return the attributes of the managed type. * - * @return The type's attributes + * @return attributes of the managed type */ - java.util.Set<Attribute<? super X, ?>> getAttributes(); + Set<Attribute<? super X, ?>> getAttributes(); /** * Return the attributes declared by the managed type. - * Returns empty set if the managed type has no declared attributes. + * Returns empty set if the managed type has no declared + * attributes. * - * @return The type's declared attributes, or empty set representing none. + * @return declared attributes of the managed type */ - java.util.Set<Attribute<X, ?>> getDeclaredAttributes(); + Set<Attribute<X, ?>> getDeclaredAttributes(); /** * Return the single-valued attribute of the managed - * type that corresponds to the specified name and Java type - * in the represented type. + * type that corresponds to the specified name and Java type. * * @param name the name of the represented attribute * @param type the type of the represented attribute @@ -36,14 +38,14 @@ * @return single-valued attribute with given name and type * * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type + * name and type is not present in the managed type */ <Y> SingularAttribute<? super X, Y> getSingularAttribute(String name, Class<Y> type); /** - * Return the declared single-valued attribute of the - * managed type that corresponds to the specified name and Java - * type in the represented type. + * Return the single-valued attribute declared by the + * managed type that corresponds to the specified name and + * Java type. * * @param name the name of the represented attribute * @param type the type of the represented attribute @@ -52,25 +54,28 @@ * name and type * * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type + * name and type is not declared in the managed type */ <Y> SingularAttribute<X, Y> getDeclaredSingularAttribute(String name, Class<Y> type); /** * Return the single-valued attributes of the managed type. - * Returns empty set if the managed type has no single-valued attributes. + * Returns empty set if the managed type has no single-valued + * attributes. * * @return single-valued attributes */ - java.util.Set<SingularAttribute<? super X, ?>> getSingularAttributes(); + Set<SingularAttribute<? super X, ?>> getSingularAttributes(); /** - * Return the single-valued attributes declared by the managed type. - * Returns empty set if the managed type has no declared single-valued attributes. + * Return the single-valued attributes declared by the managed + * type. + * Returns empty set if the managed type has no declared + * single-valued attributes. * * @return declared single-valued attributes */ - java.util.Set<SingularAttribute<X, ?>> getDeclaredSingularAttributes(); + Set<SingularAttribute<X, ?>> getDeclaredSingularAttributes(); /** * Return the Collection-valued attribute of the managed type @@ -84,7 +89,7 @@ * type * * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type + * name and type is not present in the managed type */ <E> CollectionAttribute<? super X, E> getCollection(String name, Class<E> elementType); @@ -97,11 +102,11 @@ * @param elementType the element type of the represented * attribute * - * @return declared CollectionAttribute of the given name and + * @return declared <code>CollectionAttribute</code> of the given name and * element type * * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type + * name and type is not declared in the managed type */ <E> CollectionAttribute<X, E> getDeclaredCollection(String name, Class<E> elementType); @@ -116,7 +121,7 @@ * @return SetAttribute of the given name and element type * * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type + * name and type is not present in the managed type */ <E> SetAttribute<? super X, E> getSet(String name, Class<E> elementType); @@ -132,7 +137,7 @@ * element type * * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type + * name and type is not declared in the managed type */ <E> SetAttribute<X, E> getDeclaredSet(String name, Class<E> elementType); @@ -147,7 +152,7 @@ * @return ListAttribute of the given name and element type * * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type + * name and type is not present in the managed type */ <E> ListAttribute<? super X, E> getList(String name, Class<E> elementType); @@ -164,7 +169,7 @@ * element type * * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type + * name and type is not declared in the managed type */ <E> ListAttribute<X, E> getDeclaredList(String name, Class<E> elementType); @@ -181,11 +186,9 @@ * types * * @throws IllegalArgumentException if attribute of the given - * name and type is not present in the managed type + * name and type is not present in the managed type */ - <K, V> MapAttribute<? super X, K, V> getMap(String name, - Class<K> keyType, - Class<V> valueType); + <K, V> MapAttribute<? super X, K, V> getMap(String name, Class<K> keyType, Class<V> valueType); /** * Return the Map-valued attribute declared by the managed @@ -200,11 +203,9 @@ * and value types * * @throws IllegalArgumentException if attribute of the given - * name and type is not declared in the managed type + * name and type is not declared in the managed type */ - <K, V> MapAttribute<X, K, V> getDeclaredMap(String name, - Class<K> keyType, - Class<V> valueType); + <K, V> MapAttribute<X, K, V> getDeclaredMap(String name, Class<K> keyType, Class<V> valueType); /** * Return all multi-valued attributes (Collection-, Set-, @@ -214,7 +215,7 @@ * * @return Collection-, Set-, List-, and Map-valued attributes */ - java.util.Set<PluralAttribute<? super X, ?, ?>> getPluralAttributes(); + Set<PluralAttribute<? super X, ?, ?>> getPluralAttributes(); /** * Return all multi-valued attributes (Collection-, Set-, @@ -224,10 +225,11 @@ * multi-valued attributes. * * @return declared Collection-, Set-, List-, and Map-valued - * attributes + * attributes */ - java.util.Set<PluralAttribute<X, ?, ?>> getDeclaredPluralAttributes(); + Set<PluralAttribute<X, ?, ?>> getDeclaredPluralAttributes(); + //String-based: /** @@ -239,12 +241,12 @@ * @return attribute with given name * * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type + * name is not present in the managed type */ Attribute<? super X, ?> getAttribute(String name); /** - * Return the declared attribute of the managed + * Return the attribute declared by the managed * type that corresponds to the specified name. * * @param name the name of the represented attribute @@ -252,27 +254,26 @@ * @return attribute with given name * * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type + * name is not declared in the managed type */ Attribute<X, ?> getDeclaredAttribute(String name); /** * Return the single-valued attribute of the managed type that - * corresponds to the specified name in the represented type. + * corresponds to the specified name. * * @param name the name of the represented attribute * * @return single-valued attribute with the given name * * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type + * name is not present in the managed type */ SingularAttribute<? super X, ?> getSingularAttribute(String name); /** - * Return the declared single-valued attribute of the managed - * type that corresponds to the specified name in the - * represented type. + * Return the single-valued attribute declared by the managed + * type that corresponds to the specified name. * * @param name the name of the represented attribute * @@ -280,7 +281,7 @@ * name * * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type + * name is not declared in the managed type */ SingularAttribute<X, ?> getDeclaredSingularAttribute(String name); @@ -293,7 +294,7 @@ * @return CollectionAttribute of the given name * * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type + * name is not present in the managed type */ CollectionAttribute<? super X, ?> getCollection(String name); @@ -306,7 +307,7 @@ * @return declared CollectionAttribute of the given name * * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type + * name is not declared in the managed type */ CollectionAttribute<X, ?> getDeclaredCollection(String name); @@ -319,7 +320,7 @@ * @return SetAttribute of the given name * * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type + * name is not present in the managed type */ SetAttribute<? super X, ?> getSet(String name); @@ -332,7 +333,7 @@ * @return declared SetAttribute of the given name * * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type + * name is not declared in the managed type */ SetAttribute<X, ?> getDeclaredSet(String name); @@ -345,7 +346,7 @@ * @return ListAttribute of the given name * * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type + * name is not present in the managed type */ ListAttribute<? super X, ?> getList(String name); @@ -358,7 +359,7 @@ * @return declared ListAttribute of the given name * * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type + * name is not declared in the managed type */ ListAttribute<X, ?> getDeclaredList(String name); @@ -371,7 +372,7 @@ * @return MapAttribute of the given name * * @throws IllegalArgumentException if attribute of the given - * name is not present in the managed type + * name is not present in the managed type */ MapAttribute<? super X, ?, ?> getMap(String name); @@ -384,8 +385,7 @@ * @return declared MapAttribute of the given name * * @throws IllegalArgumentException if attribute of the given - * name is not declared in the managed type + * name is not declared in the managed type */ MapAttribute<X, ?, ?> getDeclaredMap(String name); } - Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/MapAttribute.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/MapAttribute.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/MapAttribute.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,18 +1,17 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type MapAttribute represent persistent Map-valued - * attributes. + * Instances of the type <code>MapAttribute</code> represent + * persistent <code>java.util.Map</code>-valued attributes. * * @param <X> The type the represented Map belongs to * @param <K> The type of the key of the represented Map * @param <V> The type of the value of the represented Map + * @since Java Persistence 2.0 */ -public interface MapAttribute<X, K, V> - extends PluralAttribute<X, java.util.Map<K, V>, V> { - +public interface MapAttribute<X, K, V> extends PluralAttribute<X, java.util.Map<K, V>, V> { /** * Return the Java type of the map key. * Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/MappedSuperclassType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/MappedSuperclassType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/MappedSuperclassType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,13 +1,13 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type MappedSuperclassType represent mapped + * Instances of the type <code>MappedSuperclassType</code> represent mapped * superclass types. * * @param <X> The represented entity type + * @since Java Persistence 2.0 */ public interface MappedSuperclassType<X> extends IdentifiableType<X> { } - Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/Metamodel.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/Metamodel.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/Metamodel.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -2,12 +2,15 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; +import java.util.Set; + /** * Provides access to the metamodel of persistent * entities in the persistence unit. + * + * @since Java Persistence 2.0 */ public interface Metamodel { - /** * Return the metamodel entity type representing the entity. * @@ -29,7 +32,7 @@ * * @throws IllegalArgumentException if not a managed class */ - <X> ManagedType<X> type(Class<X> cls); + <X> ManagedType<X> managedType(Class<X> cls); /** * Return the metamodel embeddable type representing the @@ -48,20 +51,20 @@ * * @return the metamodel managed types */ - java.util.Set<ManagedType<?>> getManagedTypes(); + Set<ManagedType<?>> getManagedTypes(); /** * Return the metamodel entity types. * * @return the metamodel entity types */ - java.util.Set<EntityType<?>> getEntities(); + Set<EntityType<?>> getEntities(); /** - * Return the metamodel embeddable types. + * Return the metamodel embeddable types. Returns empty set + * if there are no embeddable types. * * @return the metamodel embeddable types */ - java.util.Set<EmbeddableType<?>> getEmbeddables(); + Set<EmbeddableType<?>> getEmbeddables(); } - Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/PluralAttribute.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/PluralAttribute.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/PluralAttribute.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,37 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type PluralAttribute represent + * Instances of the type <code>PluralAttribute</code> represent * persistent collection-valued attributes. * * @param <X> The type the represented collection belongs to * @param <C> The type of the represented collection * @param <E> The element type of the represented collection + * @since Java Persistence 2.0 */ -public interface PluralAttribute<X, C, E> - extends Attribute<X, C>, Bindable<E> { +public interface PluralAttribute<X, C, E> extends Attribute<X, C>, Bindable<E> { + public static enum CollectionType { + /** + * Collection-valued attribute + */ + COLLECTION, - public static enum CollectionType { - COLLECTION, SET, LIST, MAP + /** + * Set-valued attribute + */ + SET, + + /** + * List-valued attribute + */ + LIST, + + /** + * Map-valued attribute + */ + MAP } /** Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/SetAttribute.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/SetAttribute.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/SetAttribute.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,15 +1,15 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type SetAttribute represent persistent Set-valued - * attributes. + * Instances of the type <code>SetAttribute</code> represent + * persistent <code>java.util.Set</code>-valued attributes. * * @param <X> The type the represented Set belongs to * @param <E> The element type of the represented Set + * + * @since Java Persistence 2.0 */ -public interface SetAttribute<X, E> - extends PluralAttribute<X, java.util.Set<E>, E> { +public interface SetAttribute<X, E> extends PluralAttribute<X, java.util.Set<E>, E> { } - Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/SingularAttribute.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/SingularAttribute.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/SingularAttribute.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,28 +1,29 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; /** - * Instances of the type SingularAttribute represents persistent + * Instances of the type <code>SingularAttribute</code> represents persistent * single-valued properties or fields. * * @param <X> The type containing the represented attribute * @param <T> The type of the represented attribute + * @since Java Persistence 2.0 */ -public interface SingularAttribute<X, T> - extends Attribute<X, T>, Bindable<T> { - +public interface SingularAttribute<X, T> extends Attribute<X, T>, Bindable<T> { /** - * Is the attribute an id attribute. + * Is the attribute an id attribute. This method will return + * true if the attribute is an attribute that corresponds to + * a simple id, an embedded id, or an attribute of an id class. * - * @return boolean indicating whether or not attribute is an id + * @return boolean indicating whether the attribute is an id */ boolean isId(); /** * Is the attribute a version attribute. * - * @return boolean indicating whether or not attribute is + * @return boolean indicating whether the attribute is * a version attribute */ boolean isVersion(); @@ -30,7 +31,7 @@ /** * Can the attribute be null. * - * @return boolean indicating whether or not the attribute can + * @return boolean indicating whether the attribute can * be null */ boolean isOptional(); Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/StaticMetamodel.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/StaticMetamodel.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/StaticMetamodel.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,25 @@ -// $Id:$ +// $Id: $ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.metamodel; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Retention; -import java.lang.annotation.ElementType; import java.lang.annotation.Target; /** - * The StaticMetamodel annotation specifies that the class + * The <code>StaticMetamodel</code> annotation specifies that the class * is a metamodel class that represents the entity, mapped * superclass, or embeddable class designated by the value * element. + * + * @since Java Persistence 2.0 */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) public @interface StaticMetamodel { + /** + * Class being modeled by the annotated class. + */ Class<?> value(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/metamodel/Type.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/metamodel/Type.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/metamodel/Type.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,15 +3,33 @@ package javax.persistence.metamodel; /** - * Instances of the type Type represent persistent object + * Instances of the type <code>Type</code> represent persistent object * or attribute types. * * @param <X> The type of the represented object or attribute + * @since Java Persistence 2.0 */ public interface Type<X> { + public static enum PersistenceType { + /** + * Entity + */ + ENTITY, - public static enum PersistenceType { - ENTITY, EMBEDDABLE, MAPPED_SUPERCLASS, BASIC + /** + * Embeddable class + */ + EMBEDDABLE, + + /** + * Mapped superclass + */ + MAPPED_SUPERCLASS, + + /** + * Basic type + */ + BASIC } /** Modified: jpa-api/trunk/src/main/java/javax/persistence/spi/ClassTransformer.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/ClassTransformer.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/ClassTransformer.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,46 +1,50 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.spi; +import java.security.ProtectionDomain; import java.lang.instrument.IllegalClassFormatException; -import java.security.ProtectionDomain; /** * A persistence provider supplies an instance of this - * interface to the PersistenceUnitInfo.addTransformer + * interface to the {@link PersistenceUnitInfo#addTransformer + * PersistenceUnitInfo.addTransformer} * method. The supplied transformer instance will get * called to transform entity class files when they are * loaded or redefined. The transformation occurs before * the class is defined by the JVM. + * + * @since Java Persistence 1.0 */ public interface ClassTransformer { + /** * Invoked when a class is being loaded or redefined. * The implementation of this method may transform the * supplied class file and return a new replacement class * file. * - * @param loader The defining loader of the class to be + * @param loader the defining loader of the class to be * transformed, may be null if the bootstrap loader - * @param className The name of the class in the internal form + * @param className the name of the class in the internal form * of fully qualified class and interface names - * @param classBeingRedefined If this is a redefine, the + * @param classBeingRedefined if this is a redefine, the * class being redefined, otherwise null - * @param protectionDomain The protection domain of the + * @param protectionDomain the protection domain of the * class being defined or redefined - * @param classfileBuffer The input byte buffer in class + * @param classfileBuffer the input byte buffer in class * file format - must not be modified * - * @return A well-formed class file buffer (the result of + * @return a well-formed class file buffer (the result of * the transform), or null if no transform is performed * - * @throws IllegalClassFormatException If the input does - * not represent a well-formed class file + * @throws IllegalClassFormatException if the input does + * not represent a well-formed class file */ - byte[] transform(ClassLoader loader, - String className, - Class<?> classBeingRedefined, - ProtectionDomain protectionDomain, - byte[] classfileBuffer) - throws IllegalClassFormatException; + byte[] transform( + ClassLoader loader, + String className, + Class<?> classBeingRedefined, + ProtectionDomain protectionDomain, + byte[] classfileBuffer) throws IllegalClassFormatException; } Modified: jpa-api/trunk/src/main/java/javax/persistence/spi/LoadState.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/LoadState.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/LoadState.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -3,20 +3,21 @@ package javax.persistence.spi; /** - * @author Hardy Ferentschik + * Load states returned by the {@link ProviderUtil} SPI methods. + * + * @since Java Persistence 2.0 */ public enum LoadState { /** - * the state of the element is known to have been loaded + * The state of the element is known to have been loaded. */ LOADED, /** - * the state of the element is known not to have been loaded + * The state of the element is known not to have been loaded. */ NOT_LOADED, /** - * the load state of the element cannot be determined + * The load state of the element cannot be determined. */ UNKNOWN } - Modified: jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProvider.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProvider.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProvider.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,122 +1,61 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence.spi; - -import java.util.Map; -import javax.persistence.EntityManagerFactory; - -/** - * Interface implemented by the persistence provider. - * <p/> - * It is invoked by the container in Java EE environments and - * by the Persistence class in Java SE environments to - * create an EntityManagerFactory. - * <p/> - * It is also invoked by the PersistenceUtil implementation to - * determine the load status of an entity or entity attribute. - */ -public interface PersistenceProvider { - /** - * Called by Persistence class when an EntityManagerFactory - * is to be created. - * - * @param emName The name of the persistence unit - * @param map A Map of properties for use by the - * persistence provider. These properties may be used to - * override the values of the corresponding elements in - * the persistence.xml file or specify values for - * properties not specified in the persistence.xml - * (and may be null if no properties are specified). - * - * @return EntityManagerFactory for the persistence unit, - * or null if the provider is not the right provider - */ - public EntityManagerFactory createEntityManagerFactory(String emName, Map map); - - /** - * Called by the container when an EntityManagerFactory - * is to be created. - * - * @param info Metadata for use by the persistence provider - * @param map A Map of integration-level properties for use - * by the persistence provider (may be null if no properties - * are specified). - * If a Bean Validation provider is present in the classpath, - * the container must pass the ValidatorFactory instance in - * the map with the key "javax.persistence.validation.factory". - * - * @return EntityManagerFactory for the persistence unit - * specified by the metadata - */ - public EntityManagerFactory createContainerEntityManagerFactory(PersistenceUnitInfo info, Map map); - - /** - * If the provider determines that the entity has been provided - * by itself and that the state of the specified attribute has - * been loaded, this method returns LoadState.LOADED. - * If the provider determines that the entity has been provided - * by itself and that either entity attributes with FetchType - * EAGER have not been loaded or that the state of the specified - * attribute has not been loaded, this methods returns - * LoadState.NOT_LOADED. - * If a provider cannot determine the load state, this method - * returns LoadState.UNKNOWN. - * The provider's implementation of this method must not obtain - * a reference to an attribute value, as this could trigger the - * loading of entity state if the entity has been provided by a - * different provider. - * - * @param entity - * @param attributeName name of attribute whose load status is - * to be determined - * - * @return load status of the attribute - */ - public LoadState isLoadedWithoutReference(Object entity, String attributeName); - - /** - * If the provider determines that the entity has been provided - * by itself and that the state of the specified attribute has - * been loaded, this method returns LoadState.LOADED. - * If a provider determines that the entity has been provided - * by itself and that either the entity attributes with FetchType - * EAGER have not been loaded or that the state of the specified - * attribute has not been loaded, this method returns - * return LoadState.NOT_LOADED. - * If the provider cannot determine the load state, this method - * returns LoadState.UNKNOWN. - * The provider's implementation of this method is permitted to - * obtain a reference to the attribute value. (This access is - * safe because providers which might trigger the loading of the - * attribute state will have already been determined by - * isLoadedWithoutReference. ) - * - * @param entity - * @param attributeName name of attribute whose load status is - * to be determined - * - * @return load status of the attribute - */ - public LoadState isLoadedWithReference(Object entity, String attributeName); - - /** - * If the provider determines that the entity has been provided - * by itself and that the state of all attributes for which - * FetchType EAGER has been specified have been loaded, this - * method returns LoadState.LOADED. - * If the provider determines that the entity has been provided - * by itself and that not all attributes with FetchType EAGER - * have been loaded, this method returns LoadState.NOT_LOADED. - * If the provider cannot determine if the entity has been - * provided by itself, this method returns LoadState.UNKNOWN. - * The provider's implementation of this method must not obtain - * a reference to any attribute value, as this could trigger the - * loading of entity state if the entity has been provided by a - * different provider. - * - * @param entity whose loaded status is to be determined - * - * @return load status of the entity - */ - public LoadState isLoaded(Object entity); +package javax.persistence.spi; + +import javax.persistence.EntityManagerFactory; +import java.util.Map; + +/** + * Interface implemented by the persistence provider. + * + * <p> It is invoked by the container in Java EE environments and + * by the {@link javax.persistence.Persistence} class in Java SE environments to + * create an {@link javax.persistence.EntityManagerFactory}. + * + * @since Java Persistence 1.0 + */ +public interface PersistenceProvider { + /** + * Called by <code>Persistence</code> class when an + * <code>EntityManagerFactory</code> is to be created. + * + * @param emName the name of the persistence unit + * @param map a Map of properties for use by the + * persistence provider. These properties may be used to + * override the values of the corresponding elements in + * the <code>persistence.xml</code> file or specify values for + * properties not specified in the <code>persistence.xml</code> + * (and may be null if no properties are specified). + * + * @return EntityManagerFactory for the persistence unit, + * or null if the provider is not the right provider + */ + public EntityManagerFactory createEntityManagerFactory(String emName, Map map); + + /** + * Called by the container when an <code>EntityManagerFactory</code> + * is to be created. + * + * @param info metadata for use by the persistence provider + * @param map a Map of integration-level properties for use + * by the persistence provider (may be null if no properties + * are specified). + * If a Bean Validation provider is present in the classpath, + * the container must pass the <code>ValidatorFactory</code> instance in + * the map with the key <code>"javax.persistence.validation.factory"</code>. + * + * @return EntityManagerFactory for the persistence unit + * specified by the metadata + */ + public EntityManagerFactory createContainerEntityManagerFactory(PersistenceUnitInfo info, Map map); + + /** + * Return the utility interface implemented by the persistence + * provider. + * + * @return ProviderUtil interface + * + * @since Java Persistence 2.0 + */ + public ProviderUtil getProviderUtil(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProviderResolver.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProviderResolver.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProviderResolver.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -6,24 +6,29 @@ /** * Determine the list of persistence providers available in the - * runtime environment - * <p/> - * Persistence providers are identified by the presence of - * META-INF/services/javax.persistence.spi.PersistenceProvider - * files following the Service Provider pattern. - * <p/> - * Each META-INF/services/javax.persistence.spi.PersistenceProvider * file contains the name of the provider implementation class of the - * javax.persistence.spi.PersistenceProvider interface. - * <p/> - * Implementations must be thread-safe. + * runtime environment. + * + * <p> Implementations must be thread-safe. + * + * <p> Note that the <code>getPersistenceProviders</code> method can potentially + * be called many times: it is recommended that the implementation + * of this method make use of caching. + * + * @see PersistenceProvider + * @since Java Persistence 2.0 */ public interface PersistenceProviderResolver { /** - * Returns a list of PersistenceProvider implementations + * Returns a list of the <code>PersistenceProvider</code> implementations * available in the runtime environment. * - * @return list of persistence providers available + * @return list of the persistence providers available * in the environment */ List<PersistenceProvider> getPersistenceProviders(); + + /** + * Clear cache of providers. + */ + void clearCachedProviders(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProviderResolverHolder.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProviderResolverHolder.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProviderResolverHolder.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -14,9 +14,6 @@ import java.util.List; import java.util.Set; import java.util.WeakHashMap; -import java.util.Map; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.ConcurrentLinkedQueue; import java.util.regex.Matcher; import java.util.regex.Pattern; import javax.persistence.PersistenceException; @@ -29,23 +26,26 @@ * Implementations must be thread-safe. */ public class PersistenceProviderResolverHolder { + private static final PersistenceProviderResolver DEFAULT_RESOLVER = new PersistenceProviderResolverPerClassLoader(); - private static volatile PersistenceProviderResolver resolver; + private static volatile PersistenceProviderResolver RESOLVER; - private static final PersistenceProviderResolver defaultResolver = new PersistenceProviderResolverPerClassLoader(); - /** * Returns the current persistence provider resolver + * + * @return persistence provider resolver in use */ public static PersistenceProviderResolver getPersistenceProviderResolver() { - return resolver == null ? defaultResolver : resolver; + return RESOLVER == null ? DEFAULT_RESOLVER : RESOLVER; } /** - * Defines the persistence provider resolver used + * Defines the persistence provider resolver used. + * + * @param resolver PersistenceProviderResolver to be used. */ public static void setPersistenceProviderResolver(PersistenceProviderResolver resolver) { - PersistenceProviderResolverHolder.resolver = resolver; + RESOLVER = resolver; } /** @@ -61,17 +61,16 @@ private final WeakHashMap<ClassLoader, PersistenceProviderResolver> resolvers = new WeakHashMap<ClassLoader, PersistenceProviderResolver>(); private volatile short barrier = 1; - + /** + * {@inheritDoc} + */ public List<PersistenceProvider> getPersistenceProviders() { - ClassLoader cl = Thread.currentThread().getContextClassLoader(); - if ( cl == null ) { - cl = PersistenceProviderResolverPerClassLoader.class.getClassLoader(); - } - if (barrier == 1) {} //read barrier syncs state with other threads + ClassLoader cl = getContextualClassLoader(); + if ( barrier == 1 ) {} //read barrier syncs state with other threads PersistenceProviderResolver currentResolver = resolvers.get( cl ); - if (currentResolver == null) { - currentResolver = new CachingPersistenceProviderResolver(cl); + if ( currentResolver == null ) { + currentResolver = new CachingPersistenceProviderResolver( cl ); resolvers.put( cl, currentResolver ); barrier = 1; } @@ -79,6 +78,27 @@ } /** + * {@inheritDoc} + */ + public void clearCachedProviders() { + // todo : should we clear all providers from all resolvers here? + ClassLoader cl = getContextualClassLoader(); + if ( barrier == 1 ) {} //read barrier syncs state with other threads + PersistenceProviderResolver currentResolver = resolvers.get( cl ); + if ( currentResolver != null ) { + currentResolver.clearCachedProviders(); + } + } + + private static ClassLoader getContextualClassLoader() { + ClassLoader cl = Thread.currentThread().getContextClassLoader(); + if ( cl == null ) { + cl = PersistenceProviderResolverPerClassLoader.class.getClassLoader(); + } + return cl; + } + + /** * Resolve the list of Persistence providers for a given classloader and cache the results. * * Avoids to keep any reference from this class to the classloader being @@ -88,64 +108,86 @@ */ private static class CachingPersistenceProviderResolver implements PersistenceProviderResolver { //this assumes that the class loader keeps the list of classes loaded - private final List<WeakReference<Class<? extends PersistenceProvider>>> resolverClasses; + private final List<WeakReference<Class<? extends PersistenceProvider>>> resolverClasses + = new ArrayList<WeakReference<Class<? extends PersistenceProvider>>>(); public CachingPersistenceProviderResolver(ClassLoader cl) { - resolverClasses = new ArrayList<WeakReference<Class<? extends PersistenceProvider>>>(); - try { - Enumeration<URL> resources = cl.getResources( "META-INF/services/" + PersistenceProvider.class.getName() ); - Set<String> names = new HashSet<String>(); - while ( resources.hasMoreElements() ) { - URL url = resources.nextElement(); - InputStream is = url.openStream(); - try { - names.addAll( providerNamesFromReader( new BufferedReader( new InputStreamReader( is ) ) ) ); + loadResolverClasses( cl ); + } + + private void loadResolverClasses(ClassLoader cl) { + synchronized ( resolverClasses ) { + try { + Enumeration<URL> resources = cl.getResources( "META-INF/services/" + PersistenceProvider.class.getName() ); + Set<String> names = new HashSet<String>(); + while ( resources.hasMoreElements() ) { + URL url = resources.nextElement(); + InputStream is = url.openStream(); + try { + names.addAll( providerNamesFromReader( new BufferedReader( new InputStreamReader( is ) ) ) ); + } + finally { + is.close(); + } } - finally { - is.close(); + for ( String s : names ) { + @SuppressWarnings( "unchecked" ) + Class<? extends PersistenceProvider> providerClass = (Class<? extends PersistenceProvider>) cl.loadClass( s ); + WeakReference<Class<? extends PersistenceProvider>> reference + = new WeakReference<Class<? extends PersistenceProvider>>(providerClass); + //keep Hibernate atop + if ( s.endsWith( "HibernatePersistence" ) && resolverClasses.size() > 0 ) { + WeakReference<Class<? extends PersistenceProvider>> movedReference = resolverClasses.get( 0 ); + resolverClasses.add( 0, reference ); + resolverClasses.add( movedReference ); + } + else { + resolverClasses.add( reference ); + } } } - for ( String s : names ) { - @SuppressWarnings( "unchecked" ) - Class<? extends PersistenceProvider> providerClass = (Class<? extends PersistenceProvider>) cl.loadClass( s ); - WeakReference<Class<? extends PersistenceProvider>> reference - = new WeakReference<Class<? extends PersistenceProvider>>(providerClass); - //keep Hibernate atop - if ( s.endsWith( "HibernatePersistence" ) && resolverClasses.size() > 0 ) { - WeakReference<Class<? extends PersistenceProvider>> movedReference = resolverClasses.get( 0 ); - resolverClasses.add( 0, reference ); - resolverClasses.add( movedReference ); - } - else { - resolverClasses.add( reference ); - } + catch ( IOException e ) { + throw new PersistenceException( e ); } + catch ( ClassNotFoundException e ) { + throw new PersistenceException( e ); + } } - catch ( IOException e ) { - throw new PersistenceException( e ); - } - catch ( ClassNotFoundException e ) { - throw new PersistenceException( e ); - } } - //TODO find a way to cache property instances - //problem #1: avoid hard ref with classloader (List<WR<PP>>? - //problem #2: avoid half GC lists + /** + * {@inheritDoc} + */ public List<PersistenceProvider> getPersistenceProviders() { - List<PersistenceProvider> providers = new ArrayList<PersistenceProvider>( resolverClasses.size() ); - try { - for ( WeakReference<Class<? extends PersistenceProvider>> providerClass : resolverClasses ) { - providers.add( providerClass.get().newInstance() ); + //TODO find a way to cache property instances + //problem #1: avoid hard ref with classloader (List<WR<PP>>? + //problem #2: avoid half GC lists + // todo (steve) : why arent we just caching the PersistenceProvider *instances* as the CachingPersistenceProviderResolver state??? + synchronized ( resolverClasses ) { + List<PersistenceProvider> providers = new ArrayList<PersistenceProvider>( resolverClasses.size() ); + try { + for ( WeakReference<Class<? extends PersistenceProvider>> providerClass : resolverClasses ) { + providers.add( providerClass.get().newInstance() ); + } } + catch ( InstantiationException e ) { + throw new PersistenceException( e ); + } + catch ( IllegalAccessException e ) { + throw new PersistenceException( e ); + } + return providers; } - catch ( InstantiationException e ) { - throw new PersistenceException( e ); + } + + /** + * {@inheritDoc} + */ + public synchronized void clearCachedProviders() { + synchronized ( resolverClasses ) { + resolverClasses.clear(); + loadResolverClasses( PersistenceProviderResolverPerClassLoader.getContextualClassLoader() ); } - catch ( IllegalAccessException e ) { - throw new PersistenceException( e ); - } - return providers; } Modified: jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitInfo.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitInfo.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitInfo.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,178 +1,223 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence.spi; - -import java.net.URL; -import java.util.List; -import java.util.Properties; -import javax.persistence.Caching; -import javax.persistence.ValidationMode; -import javax.sql.DataSource; - -/** - * Interface implemented by the container and used by the * persistence provider when creating an EntityManagerFactory. - */ -public interface PersistenceUnitInfo { - /** - * @return The name of the persistence unit. - * Corresponds to the name attribute in the persistence.xml file. - */ - public String getPersistenceUnitName(); - - /** - * @return The fully qualified name of the persistence provider - * implementation class. - * Corresponds to the provider element in the persistence.xml - * file. - */ - public String getPersistenceProviderClassName(); - - /** - * @return The transaction type of the entity managers created - * by the EntityManagerFactory. - * The transaction type corresponds to the transaction-type - * attribute in the persistence.xml file. - */ - public PersistenceUnitTransactionType getTransactionType(); - - /** - * @return The JTA-enabled data source to be used by the - * persistence provider. - * The data source corresponds to the jta-data-source - * element in the persistence.xml file or is provided at - * deployment or by the container. - */ - public DataSource getJtaDataSource(); - - /** - * @return The non-JTA-enabled data source to be used by the - * persistence provider for accessing data outside a JTA - * transaction. - * The data source corresponds to the non-jta-data-source - * element in the persistence.xml file or provided at - * deployment or by the container. - */ - public DataSource getNonJtaDataSource(); - - /** - * @return The list of mapping file names that the persistence - * provider must load to determine the mappings for the entity - * classes. The mapping files must be in the standard XML - * mapping format, be uniquely named and be resource-loadable - * from the application classpath. - * Each mapping file name corresponds to a mapping-file - * element in the persistence.xml file. - */ - public List<String> getMappingFileNames(); - - /** - * Returns a list of URLs for the jar files or exploded jar - * file directories that the persistence provider must examine - * for managed classes of the persistence unit. Each URL - * corresponds to a jar-file element in the - * persistence.xml file. A URL will either be a file: - * URL referring to a jar file or referring to a directory - * that contains an exploded jar file, or some other URL from - * which an InputStream in jar format can be obtained. - * - * @return a list of URL objects referring to jar files or - * directories. - */ - public List<URL> getJarFileUrls(); - - /** - * Returns the URL for the jar file or directory that is the - * root of the persistence unit. (If the persistence unit is - * rooted in the WEB-INF/classes directory, this will be the - * URL of that directory.) - * The URL will either be a file: URL referring to a jar file - * or referring to a directory that contains an exploded jar - * file, or some other URL from which an InputStream in jar - * format can be obtained. - * - * @return a URL referring to a jar file or directory. - */ - public URL getPersistenceUnitRootUrl(); - - /** - * @return The list of the names of the classes that the - * persistence provider must add it to its set of managed - * classes. Each name corresponds to a class element - * in the persistence.xml file. - */ - public List<String> getManagedClassNames(); - - /** - * @return Whether classes in the root of the persistence - * unit that have not been explicitly listed are to be - * included in the set of managed classes. - * This value corresponds to the exclude-unlisted-classes - * element in the persistence.xml file. - */ - public boolean excludeUnlistedClasses(); - - /** - * @return The specification of how the provider must use - * a second-level cache for the persistence unit - * The result of this method corresponds to the caching - * element in the persistence.xml file. - */ - public Caching getCaching(); - - /** - * @return The validation mode to be used by the - * persistence provider for the persistence unit. - * The validation mode corresponds to the validation-mode - * element in the persistence.xml file. - */ - public ValidationMode getValidationMode(); - - /** - * @return Properties object. Each property corresponds - * to a property element in the persistence.xml file - */ - public Properties getProperties(); - - /** - * @return persistence.xml schema version - */ - public String PersistenceXMLSchemaVersion(); - - /** - * @return ClassLoader that the provider may use to load any - * classes, resources, or open URLs. - */ - public ClassLoader getClassLoader(); - - /** - * Add a transformer supplied by the provider that will be - * called for every new class definition or class redefinition - * that gets loaded by the loader returned by the - * PersistenceUnitInfo.getClassLoader method. The transformer - * has no effect on the result returned by the - * PersistenceUnitInfo.getNewTempClassLoader method. - * Classes are only transformed once within the same classloading - * scope, regardless of how many persistence units they may be - * a part of. - * - * @param transformer A provider-supplied transformer that the - * Container invokes at class-(re)definition time - */ - public void addTransformer(ClassTransformer transformer); - - /** - * Return a new instance of a ClassLoader that the provider - * may use to temporarily load any classes, resources, or - * open URLs. The scope and classpath of this loader is - * exactly the same as that of the loader returned by - * PersistenceUnitInfo.getClassLoader. None of the classes loaded - * by this class loader will be visible to application - * components. The provider may only use this ClassLoader - * within the scope of the createContainerEntityManagerFactory - * call. - * - * @return Temporary ClassLoader with same visibility as current - * loader - */ - public ClassLoader getNewTempClassLoader(); +package javax.persistence.spi; + +import javax.sql.DataSource; +import java.util.List; +import java.util.Properties; +import java.net.URL; +import javax.persistence.SharedCacheMode; +import javax.persistence.ValidationMode; + +/** + * Interface implemented by the container and used by the + * persistence provider when creating an {@link javax.persistence.EntityManagerFactory}. + * + * @since Java Persistence 1.0 + */ +public interface PersistenceUnitInfo { + + /** + * Returns the name of the persistence unit. Corresponds to the + * <code>name</code> attribute in the <code>persistence.xml<code> file. + * + * @return the name of the persistence unit + */ + public String getPersistenceUnitName(); + + /** + * Returns the fully qualified name of the persistence provider + * implementation class. Corresponds to the <code>provider</code> element in + * the <code>persistence.xml</code> file. + * + * @return the fully qualified name of the persistence provider + * implementation class + */ + public String getPersistenceProviderClassName(); + + /** + * Returns the transaction type of the entity managers created by + * the <code>EntityManagerFactory</code>. The transaction type corresponds to + * the <code>transaction-type</code> attribute in the <code>persistence.xml</code> file. + * + * @return transaction type of the entity managers created + * by the EntityManagerFactory + */ + public PersistenceUnitTransactionType getTransactionType(); + + /** + * Returns the JTA-enabled data source to be used by the + * persistence provider. The data source corresponds to the + * <code>jta-data-source</code> element in the <code>persistence.xml</code> file or is + * provided at deployment or by the container. + * + * @return the JTA-enabled data source to be used by the + * persistence provider + */ + public DataSource getJtaDataSource(); + + /** + * Returns the non-JTA-enabled data source to be used by the + * persistence provider for accessing data outside a JTA + * transaction. The data source corresponds to the named + * <code>non-jta-data-source</code> element in the <code>persistence.xml</code> file or + * provided at deployment or by the container. + * + * @return the non-JTA-enabled data source to be used by the + * persistence provider for accessing data outside a JTA + * transaction + */ + public DataSource getNonJtaDataSource(); + + /** + * Returns the list of the names of the mapping files that the + * persistence provider must load to determine the mappings for + * the entity classes. The mapping files must be in the standard + * XML mapping format, be uniquely named and be resource-loadable + * from the application classpath. Each mapping file name + * corresponds to a <code>mapping-file</code> element in the + * <code>persistence.xml</code> file. + * + * @return the list of mapping file names that the persistence + * provider must load to determine the mappings for the entity + * classes + */ + public List<String> getMappingFileNames(); + + /** + * Returns a list of URLs for the jar files or exploded jar + * file directories that the persistence provider must examine + * for managed classes of the persistence unit. Each URL + * corresponds to a <code>jar-file</code> element in the + * <code>persistence.xml</code> file. A URL will either be a + * file: URL referring to a jar file or referring to a directory + * that contains an exploded jar file, or some other URL from + * which an InputStream in jar format can be obtained. + * + * @return a list of URL objects referring to jar files or + * directories + */ + public List<URL> getJarFileUrls(); + + /** + * Returns the URL for the jar file or directory that is the + * root of the persistence unit. (If the persistence unit is + * rooted in the WEB-INF/classes directory, this will be the + * URL of that directory.) + * The URL will either be a file: URL referring to a jar file + * or referring to a directory that contains an exploded jar + * file, or some other URL from which an InputStream in jar + * format can be obtained. + * + * @return a URL referring to a jar file or directory + */ + public URL getPersistenceUnitRootUrl(); + + /** + * Returns the list of the names of the classes that the + * persistence provider must add to its set of managed + * classes. Each name corresponds to a named <code>class</code> element in the + * <code>persistence.xml</code> file. + * + * @return the list of the names of the classes that the + * persistence provider must add to its set of managed + * classes + */ + public List<String> getManagedClassNames(); + + /** + * Returns whether classes in the root of the persistence unit + * that have not been explicitly listed are to be included in the + * set of managed classes. This value corresponds to the + * <code>exclude-unlisted-classes</code> element in the <code>persistence.xml</code> file. + * + * @return whether classes in the root of the persistence + * unit that have not been explicitly listed are to be + * included in the set of managed classes + */ + public boolean excludeUnlistedClasses(); + + /** + * Returns the specification of how the provider must use + * a second-level cache for the persistence unit. + * The result of this method corresponds to the <code>shared-cache-mode</code> + * element in the <code>persistence.xml</code> file. + * + * @return the second-level cache mode that must be used by the + * provider for the persistence unit + * + * @since Java Persistence 2.0 + */ + public SharedCacheMode getSharedCacheMode(); + + /** + * Returns the validation mode to be used by the persistence + * provider for the persistence unit. The validation mode + * corresponds to the <code>validation-mode</code> element in the + * <code>persistence.xml</code> file. + * + * @return the validation mode to be used by the + * persistence provider for the persistence unit + * + * @since Java Persistence 2.0 + */ + public ValidationMode getValidationMode(); + + /** + * Returns a properties object. Each property corresponds to a + * <code>property</code> element in the <code>persistence.xml</code> file. + * + * @return Properties object + */ + public Properties getProperties(); + + /** + * Returns the schema version of the <code>persistence.xml</code> file. + * + * @return persistence.xml schema version + * + * @since Java Persistence 2.0 + */ + public String getPersistenceXMLSchemaVersion(); + + /** + * Returns ClassLoader that the provider may use to load any + * classes, resources, or open URLs. + * + * @return ClassLoader that the provider may use to load any + * classes, resources, or open URLs + */ + public ClassLoader getClassLoader(); + + /** + * Add a transformer supplied by the provider that will be + * called for every new class definition or class redefinition + * that gets loaded by the loader returned by the + * {@link PersistenceUnitInfo#getClassLoader} method. The transformer + * has no effect on the result returned by the + * {@link PersistenceUnitInfo#getNewTempClassLoader} method. + * Classes are only transformed once within the same classloading + * scope, regardless of how many persistence units they may be + * a part of. + * + * @param transformer provider-supplied transformer that the + * container invokes at class-(re)definition time + */ + public void addTransformer(ClassTransformer transformer); + + /** + * Return a new instance of a ClassLoader that the provider may + * use to temporarily load any classes, resources, or open + * URLs. The scope and classpath of this loader is exactly the + * same as that of the loader returned by {@link + * PersistenceUnitInfo#getClassLoader}. None of the classes loaded + * by this class loader will be visible to application + * components. The provider may only use this ClassLoader within + * the scope of the {@link + * PersistenceProvider#createContainerEntityManagerFactory} call. + * + * @return temporary ClassLoader with same visibility as current + * loader + */ + public ClassLoader getNewTempClassLoader(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitTransactionType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitTransactionType.java 2009-10-14 23:20:44 UTC (rev 17751) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitTransactionType.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -1,20 +1,22 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.spi; /** - * This enum class defines whether the entity managers created by the EntityManagerFactory will be - * JTA or resource-local entity managers. + * Specifies whether entity managers created by the {@link + * javax.persistence.EntityManagerFactory} will be JTA or + * resource-local entity managers. * - * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @since Java Persistence 1.0 */ public enum PersistenceUnitTransactionType { /** - * JTA entity manager + * JTA entity managers will be created. */ JTA, + /** - * Resource-local entity manager + * Resource-local entity managers will be created. */ RESOURCE_LOCAL } Added: jpa-api/trunk/src/main/java/javax/persistence/spi/ProviderUtil.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/ProviderUtil.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/ProviderUtil.java 2009-10-15 01:19:21 UTC (rev 17752) @@ -0,0 +1,83 @@ +// $Id: $ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence.spi; + +/** + * Utility interface implemented by the persistence provider. This + * interface is invoked by the {@link + * javax.persistence.PersistenceUtil} implementation to determine + * the load status of an entity or entity attribute. + * + * @since Java Persistence 2.0 + */ +public interface ProviderUtil { + /** + * If the provider determines that the entity has been provided + * by itself and that the state of the specified attribute has + * been loaded, this method returns <code>LoadState.LOADED</code>. + * <p> If the provider determines that the entity has been provided + * by itself and that either entity attributes with <code>FetchType.EAGER</code> + * have not been loaded or that the state of the specified + * attribute has not been loaded, this methods returns + * <code>LoadState.NOT_LOADED</code>. + * <p> If a provider cannot determine the load state, this method + * returns <code>LoadState.UNKNOWN</code>. + * <p> The provider's implementation of this method must not obtain + * a reference to an attribute value, as this could trigger the + * loading of entity state if the entity has been provided by a + * different provider. + * + * @param entity entity instance + * @param attributeName name of attribute whose load status is + * to be determined + * + * @return load status of the attribute + */ + public LoadState isLoadedWithoutReference(Object entity, String attributeName); + + /** + * If the provider determines that the entity has been provided + * by itself and that the state of the specified attribute has + * been loaded, this method returns <code>LoadState.LOADED</code>. + * <p> If a provider determines that the entity has been provided + * by itself and that either the entity attributes with <code>FetchType.EAGER</code> + * have not been loaded or that the state of the specified + * attribute has not been loaded, this method returns + * return <code>LoadState.NOT_LOADED</code>. + * <p> If the provider cannot determine the load state, this method + * returns <code>LoadState.UNKNOWN</code>. + * <p> The provider's implementation of this method is permitted to + * obtain a reference to the attribute value. (This access is + * safe because providers which might trigger the loading of the + * attribute state will have already been determined by + * <code>isLoadedWithoutReference</code>. ) + * + * @param entity entity instance + * @param attributeName name of attribute whose load status is + * to be determined + * + * @return load status of the attribute + */ + public LoadState isLoadedWithReference(Object entity, String attributeName); + + /** + * If the provider determines that the entity has been provided + * by itself and that the state of all attributes for which + * <code>FetchType.EAGER</code> has been specified have been loaded, this + * method returns <code>LoadState.LOADED</code>. + * <p> If the provider determines that the entity has been provided + * by itself and that not all attributes with <code>FetchType.EAGER</code> + * have been loaded, this method returns <code>LoadState.NOT_LOADED</code>. + * <p> If the provider cannot determine if the entity has been + * provided by itself, this method returns <code>LoadState.UNKNOWN</code>. + * <p> The provider's implementation of this method must not obtain + * a reference to any attribute value, as this could trigger the + * loading of entity state if the entity has been provided by a + * different provider. + * + * @param entity whose loaded status is to be determined + * + * @return load status of the entity + */ + public LoadState isLoaded(Object entity); +}