[hibernate-commits] Hibernate SVN: r17752 - in jpa-api/trunk: src/main/java/javax/persistence and 3 other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed Oct 14 21:19:24 EDT 2009
Author: steve.ebersole at 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
*/
- at Target({ TYPE, METHOD, FIELD })
+ at 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
+ *
+ * @MappedSuperclass
+ * public class Employee {
+ * ...
+ * @ManyToOne
+ * protected Address address;
+ * ...
+ * }
+ *
+ * @Entity
+ * @AssociationOverride(name="address",
+ * joinColumns=@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
+ *
+ * @Entity
+ * public class Employee {
+ * @Id int id;
+ * @AssociationOverride(
+ * name="phoneNumbers",
+ * joinTable=@JoinTable(
+ * name="EMPPHONES",
+ * joinColumns=@JoinColumn(name="EMP"),
+ * inverseJoinColumns=@JoinColumn(name="PHONE")
+ * )
+ * )
+ * @Embedded ContactInfo contactInfo;
+ * ...
+ * }
+ *
+ * @Embeddable
+ * public class ContactInfo {
+ * @ManyToOne Address address; // Unidirectional
+ * @ManyToMany(targetEntity=PhoneNumber.class) List phoneNumbers;
+ * }
+ *
+ * @Entity
+ * public class PhoneNumber {
+ * @Id int number;
+ * @ManyToMany(mappedBy="contactInfo.phoneNumbers")
+ * Collection<Employee> employees;
+ * }
+ * </pre>
+ *
+ * @see Embedded
+ * @see Embeddable
+ * @see MappedSuperclass
+ * @see AttributeOverride
+ *
+ * @since Java Persistence 1.0
*/
- at Target({ TYPE, METHOD, FIELD })
+ at 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:
+ *
+ * @MappedSuperclass
+ * public class Employee {
+ *
+ * @Id protected Integer id;
+ * @Version protected Integer version;
+ * @ManyToOne protected Address address;
+ * @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) { ... }
+ * ...
+ * }
+ *
+ * @Entity
+ * @AssociationOverrides({
+ * @AssociationOverride(
+ * name="address",
+ * joinColumns=@JoinColumn("ADDR_ID")),
+ * @AttributeOverride(
+ * name="locker",
+ * joinColumns=@JoinColumn("LCKR_ID"))
+ * })
+ * public PartTimeEmployee { ... }
+ * </pre>
+ *
+ *@see AssociationOverride
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({TYPE, METHOD, FIELD})
+ at 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:
+ *
+ * @MappedSuperclass
+ * public class Employee {
+ * @Id protected Integer id;
+ * @Version protected Integer version;
+ * protected String address;
+ * public Integer getId() { ... }
+ * public void setId(Integer id) { ... }
+ * public String getAddress() { ... }
+ * public void setAddress(String address) { ... }
+ * }
+ *
+ * @Entity
+ * @AttributeOverride(name="address", column=@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:
+ *
+ * @Embeddable public class Address {
+ * protected String street;
+ * protected String city;
+ * protected String state;
+ * @Embedded protected Zipcode zipcode;
+ * }
+ *
+ * @Embeddable public class Zipcode {
+ * protected String zip;
+ * protected String plusFour;
+ * }
+ *
+ * @Entity public class Customer {
+ * @Id protected Integer id;
+ * protected String name;
+ * @AttributeOverrides({
+ * @AttributeOverride(name="state",
+ * column=@Column(name="ADDR_STATE")),
+ * @AttributeOverride(name="zipcode.zip",
+ * column=@Column(name="ADDR_ZIP"))
+ * })
+ * @Embedded protected Address address;
+ * ...
+ * }
+ *
+ *
+ * Example 3:
+ *
+ * @Entity public class PropertyRecord {
+ * @EmbeddedId PropertyOwner owner;
+ * @AttributeOverrides({
+ * @AttributeOverride(name="key.street",
+ * column=@Column(name="STREET_NAME")),
+ * @AttributeOverride(name="value.size",
+ * column=@Column(name="SQUARE_FEET")),
+ * @AttributeOverride(name="value.tax",
+ * column=@Column(name="ASSESSMENT"))
+ * })
+ * @ElementCollection
+ * Map<Address, PropertyInfo> parcels;
+ * }
+ *
+ * @Embeddable public class PropertyInfo {
+ * Integer parcelNumber;
+ * Integer size;
+ * BigDecimal tax;
+ * }
+ *
+ * </pre>
+ *
+ * @see Embedded
+ * @see Embeddable
+ * @see MappedSuperclass
+ * @see AssociationOverride
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({TYPE, METHOD, FIELD})
+ at 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:
+ *
+ * @Embedded
+ * @AttributeOverrides({
+ * @AttributeOverride(name="startDate",
+ * column=@Column("EMP_START")),
+ * @AttributeOverride(name="endDate",
+ * column=@Column("EMP_END"))
+ * })
+ * public EmploymentPeriod getEmploymentPeriod() { ... }
+ *
+ * </pre>
+ *
+ *
+ * @see AttributeOverride
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({TYPE, METHOD, FIELD})
+ at 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:
+ *
+ * @Basic
+ * protected String name;
+ *
+ * Example 2:
+ *
+ * @Basic(fetch=LAZY)
+ * protected String getName() { return name; }
+ *
+ * </pre>
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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
*/
- at Target({ TYPE })
+ at 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:
+ *
+ * @Embeddable public class Address {
+ * protected String street;
+ * protected String city;
+ * protected String state;
+ * ...
+ * }
+ *
+ * @Entity public class Person {
+ * @Id protected String ssn;
+ * protected String name;
+ * protected Address home;
+ * ...
+ * @ElementCollection // use default table (PERSON_NICKNAMES)
+ * @Column(name="name", length=50)
+ * protected Set<String> nickNames = new HashSet();
+ * ...
+ * }
+ *
+ * @Entity public class WealthyPerson extends Person {
+ * @ElementCollection
+ * @CollectionTable(name="HOMES") // use default join column name
+ * @AttributeOverrides({
+ * @AttributeOverride(name="street",
+ * column=@Column(name="HOME_STREET")),
+ * @AttributeOverride(name="city",
+ * column=@Column(name="HOME_CITY")),
+ * @AttributeOverride(name="state",
+ * column=@Column(name="HOME_STATE"))
+ * })
+ * protected Set<Address> vacationHomes = new HashSet();
+ * ...
+ * }
+ * </pre>
+ *
+ * @see ElementCollection
+ * @see AttributeOverride
+ * @see AssociationOverride
+ * @see Column
+ *
+ * @since Java Persistence 2.0
*/
- at Target({ METHOD, FIELD })
+
+ at 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:
+ *
+ * @Column(name="DESC", nullable=false, length=512)
+ * public String getDescription() { return description; }
+ *
+ * Example 2:
+ *
+ * @Column(name="DESC",
+ * columnDefinition="CLOB NOT NULL",
+ * table="EMP_DETAIL")
+ * @Lob
+ * public String getDescription() { return description; }
+ *
+ * Example 3:
+ *
+ * @Column(name="ORDER_COST", updatable=false, precision=12, scale=2)
+ * public BigDecimal getCost() { return cost; }
+ *
+ * </pre></blockquote>
+ *
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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
- */
- at 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");
+ *
+ * @SqlResultSetMapping(name="OrderResults",
+ * entities={
+ * @EntityResult(entityClass=com.acme.Order.class, fields={
+ * @FieldResult(name="id", column="order_id"),
+ * @FieldResult(name="quantity", column="order_quantity"),
+ * @FieldResult(name="item", column="order_item")})},
+ * columns={
+ * @ColumnResult(name="item_name")}
+ * )
+ * </pre>
+ *
+ * @see SqlResultSetMapping
+ *
+ * @since Java Persistence 1.0
+ */
+ at Target({})
+ at 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:
+ *
+ * @Entity
+ * @Table(name="CUST")
+ * @Inheritance(strategy=SINGLE_TABLE)
+ * @DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20)
+ * public class Customer { ... }
+ *
+ * @Entity
+ * public class ValuedCustomer extends Customer { ... }
+ * </pre>
+ *
+ * @see DiscriminatorValue
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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:
+ *
+ * @Entity
+ * @Table(name="CUST")
+ * @Inheritance(strategy=SINGLE_TABLE)
+ * @DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20)
+ * @DiscriminatorValue("CUSTOMER")
+ * public class Customer { ... }
+ *
+ * @Entity
+ * @DiscriminatorValue("VCUSTOMER")
+ * public class ValuedCustomer extends Customer { ... }
+ * </pre>
+ *
+ * @see DiscriminatorColumn
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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:
+ *
+ * @Entity public class Person {
+ * @Id protected String ssn;
+ * protected String name;
+ * ...
+ * @ElementCollection
+ * protected Set<String> nickNames = new HashSet();
+ * ...
+ * }
+ * </pre>
+ *
+ * @since Java Persistence 2.0
*/
- at Target({ METHOD, FIELD })
+ at 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:
+ *
+ * @Embeddable public class EmploymentPeriod {
+ * @Temporal(DATE) java.util.Date startDate;
+ * @Temporal(DATE) java.util.Date endDate;
+ * ...
+ * }
+ *
+ * Example 2:
+ *
+ * @Embeddable public class PhoneNumber {
+ * protected String areaCode;
+ * protected String localNumber;
+ * @ManyToOne PhoneServiceProvider provider;
+ * ...
+ * }
+ *
+ * @Entity public class PhoneServiceProvider {
+ * @Id protected String name;
+ * ...
+ * }
+ *
+ * Example 3:
+ *
+ * @Embeddable public class Address {
+ * protected String street;
+ * protected String city;
+ * protected String state;
+ * @Embedded protected Zipcode zipcode;
+ * }
+ *
+ * @Embeddable public class Zipcode {
+ * protected String zip;
+ * protected String plusFour;
+ * }
+
+
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({ TYPE })
+ at Documented
+ at 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:
+ *
+ * @Embedded
+ * @AttributeOverrides({
+ * @AttributeOverride(name="startDate", column=@Column("EMP_START")),
+ * @AttributeOverride(name="endDate", column=@Column("EMP_END"))
+ * })
+ * public EmploymentPeriod getEmploymentPeriod() { ... }
+ * </pre>
+ *
+ * @see Embeddable
+ * @see AttributeOverride
+ * @see AttributeOverrides
+ * @see AssociationOverride
+ * @see AssociationOverrides
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
-public @interface Embedded {}
+ at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @EmbeddedId
+ * protected EmployeePK empPK;
+ *
+ *
+ * Example 2:
+ *
+ * @Embeddable
+ * public class DependentId {
+ * String name;
+ * EmployeeId empPK; // corresponds to primary key type of Employee
+ * }
+ *
+ * @Entity
+ * public class Dependent {
+ * // default column name for "name" attribute is overridden
+ * @AttributeOverride(name="name", @Column(name="dep_name"))
+ * @EmbeddedId DependentId id;
+ * ...
+ * @MapsId("empPK")
+ * @ManyToOne Employee emp;
+ * }
+ * </pre>
+ *
+ * @see Embeddable
+ * @see MapsId
+ *
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.METHOD, ElementType.FIELD})
- at Retention(RetentionPolicy.RUNTIME)
-public @interface EmbeddedId {}
+ at Target({METHOD, FIELD})
+ at 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
*/
- at Target(TYPE) @Retention(RUNTIME)
+ at Documented
+ at Target(TYPE)
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.TYPE})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({TYPE})
+ at 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");
+ * @SqlResultSetMapping(name="OrderItemResults",
+ * entities={
+ * @EntityResult(entityClass=com.acme.Order.class),
+ * @EntityResult(entityClass=com.acme.Item.class)
+ * })
+ * </pre>
+ *
+ * @see SqlResultSetMapping
+ *
+ * @since Java Persistence 1.0
*/
- at Target({}) @Retention(RetentionPolicy.RUNTIME)
+ at Target({})
+ at 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}
+ *
+ * @Entity public class Employee {
+ * public EmployeeStatus getStatus() {...}
+ * ...
+ * @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
*/
- at Target(TYPE) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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
*/
- at Target(TYPE) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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:
+ * @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");
+ *
+ * @SqlResultSetMapping(name="OrderResults",
+ * entities={
+ * @EntityResult(entityClass=com.acme.Order.class, fields={
+ * @FieldResult(name="id", column="order_id"),
+ * @FieldResult(name="quantity", column="order_quantity"),
+ * @FieldResult(name="item", column="order_item")})
+ * })
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({}) @Retention(RetentionPolicy.RUNTIME)
+ at Target({})
+ at 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:
+ *
+ * @Id
+ * @GeneratedValue(strategy=SEQUENCE, generator="CUST_SEQ")
+ * @Column(name="CUST_ID")
+ * public Long getId() { return id; }
+ *
+ * Example 2:
+ *
+ * @Id
+ * @GeneratedValue(strategy=TABLE, generator="CUST_GEN")
+ * @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:
+ *
+ * @Id
+ * public Long getId() { return id; }
+ * </pre>
+ *
+ * @see Column
+ * @see GeneratedValue
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
-public @interface Id {}
+ at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @IdClass(com.acme.EmployeePK.class)
+ * @Entity
+ * public class Employee {
+ * @Id String empName;
+ * @Id Date birthDay;
+ * ...
+ * }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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:
+ *
+ * @Entity
+ * @Inheritance(strategy=JOINED)
+ * public class Customer { ... }
+ *
+ * @Entity
+ * public class ValuedCustomer extends Customer { ... }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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:
+ *
+ * @ManyToOne
+ * @JoinColumn(name="ADDR_ID")
+ * public Address getAddress() { return address; }
+ *
+ *
+ * Example: unidirectional one-to-many association using a foreign key mapping
+ *
+ * // In Customer class
+ * @OneToMany
+ * @JoinColumn(name="CUST_ID") // join column is in table for Order
+ * public Set<Order> getOrders() {return orders;}
+ * </pre>
+ *
+ * @see ManyToOne
+ * @see OneToMany
+ * @see OneToOne
+ * @see JoinTable
+ * @see CollectionTable
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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:
+ * @ManyToOne
+ * @JoinColumns({
+ * @JoinColumn(name="ADDR_ID", referencedColumnName="ID"),
+ * @JoinColumn(name="ADDR_ZIP", referencedColumnName="ZIP")
+ * })
+ * public Address getAddress() { return address; }
+ * </pre>
+ *
+ * @see JoinColumn
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @JoinTable(
+ * name="CUST_PHONE",
+ * joinColumns=
+ * @JoinColumn(name="CUST_ID", referencedColumnName="ID"),
+ * inverseJoinColumns=
+ * @JoinColumn(name="PHONE_ID", referencedColumnName="ID")
+ * )
+ * </pre>
+ *
+ * @see JoinColumn
+ * @see JoinColumns
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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
- */
- at 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:
+ *
+ * @Lob @Basic(fetch=LAZY)
+ * @Column(name="REPORT")
+ * protected String report;
+ *
+ * Example 2:
+ *
+ * @Lob @Basic(fetch=LAZY)
+ * @Column(name="EMP_PIC", columnDefinition="BLOB NOT NULL")
+ * protected byte[] pic;
+ *
+ * </pre>
+ *
+ * @see Basic
+ * @see ElementCollection
+ *
+ * @since Java Persistence 1.0
+ */
+ at Target({METHOD, FIELD})
+ at 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
- */
- at 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:
+ *
+ * @ManyToMany
+ * @JoinTable(name="CUST_PHONES")
+ * public Set<PhoneNumber> getPhones() { return phones; }
+ *
+ * // In PhoneNumber class:
+ *
+ * @ManyToMany(mappedBy="phones")
+ * public Set<Customer> getCustomers() { return customers; }
+ *
+ * Example 2:
+ *
+ * // In Customer class:
+ *
+ * @ManyToMany(targetEntity=com.acme.PhoneNumber.class)
+ * public Set getPhones() { return phones; }
+ *
+ * // In PhoneNumber class:
+ *
+ * @ManyToMany(targetEntity=com.acme.Customer.class, mappedBy="phones")
+ * public Set getCustomers() { return customers; }
+ *
+ * Example 3:
+ *
+ * // In Customer class:
+ *
+ * @ManyToMany
+ * @JoinTable(name="CUST_PHONE",
+ * joinColumns=
+ * @JoinColumn(name="CUST_ID", referencedColumnName="ID"),
+ * inverseJoinColumns=
+ * @JoinColumn(name="PHONE_ID", referencedColumnName="ID")
+ * )
+ * public Set<PhoneNumber> getPhones() { return phones; }
+ *
+ * // In PhoneNumberClass:
+ *
+ * @ManyToMany(mappedBy="phones")
+ * public Set<Customer> getCustomers() { return customers; }
+ * </pre>
+ *
+ * @see JoinTable
+ *
+ * @since Java Persistence 1.0
+ */
+ at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @ManyToOne(optional=false)
+ * @JoinColumn(name="CUST_ID", nullable=false, updatable=false)
+ * public Customer getCustomer() { return customer; }
+ *
+ *
+ * Example 2:
+ *
+ * @Entity
+ * public class Employee {
+ * @Id int id;
+ * @Embedded JobInfo jobInfo;
+ * ...
+ * }
+ *
+ * @Embeddable
+ * public class JobInfo {
+ * String jobDescription;
+ * @ManyToOne ProgramManager pm; // Bidirectional
+ * }
+ *
+ * @Entity
+ * public class ProgramManager {
+ * @Id int id;
+ * @OneToMany(mappedBy="jobInfo.pm")
+ * Collection<Employee> manages;
+ * }
+ *
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @Entity
+ * public class Department {
+ * ...
+ * @OneToMany(mappedBy="department")
+ * @MapKey // map key is primary key
+ * public Map<Integer, Employee> getEmployees() {... }
+ * ...
+ * }
+ *
+ * @Entity
+ * public class Employee {
+ * ...
+ * @Id Integer getEmpId() { ... }
+ * @ManyToOne
+ * @JoinColumn(name="dept_id")
+ * public Department getDepartment() { ... }
+ * ...
+ * }
+ *
+ * Example 2:
+ *
+ * @Entity
+ * public class Department {
+ * ...
+ * @OneToMany(mappedBy="department")
+ * @MapKey(name="name")
+ * public Map<String, Employee> getEmployees() {... }
+ * ...
+ * }
+ *
+ * @Entity
+ * public class Employee {
+ * @Id public Integer getEmpId() { ... }
+ * ...
+ * @ManyToOne
+ * @JoinColumn(name="dept_id")
+ * public Department getDepartment() { ... }
+ * ...
+ * }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @Entity
+ * public class Item {
+ * @Id int id;
+ * ...
+ * @ElementCollection(targetClass=String.class)
+ * @MapKeyClass(String.class)
+ * Map images; // map from image name to image filename
+ * ...
+ * }
+ *
+ * Example 2:
+ *
+ * // MapKeyClass and target type of relationship can be defaulted
+ *
+ * @Entity
+ * public class Item {
+ * @Id int id;
+ * ...
+ * @ElementCollection
+ * Map<String, String> images;
+ * ...
+ * }
+ *
+ * Example 3:
+ *
+ * @Entity
+ * public class Company {
+ * @Id int id;
+ * ...
+ * @OneToMany(targetEntity=com.example.VicePresident.class)
+ * @MapKeyClass(com.example.Division.class)
+ * Map organization;
+ * }
+ *
+ * Example 4:
+ *
+ * // MapKeyClass and target type of relationship are defaulted
+ *
+ * @Entity
+ * public class Company {
+ * @Id int id;
+ * ...
+ * @OneToMany
+ * Map<Division, VicePresident> organization;
+ * }
+ *
+ * </pre>
+ * @see ElementCollection
+ * @see OneToMany
+ * @see ManyToMany
+ * @since Java Persistence 2.0
*/
- at Target({ METHOD, FIELD })
+
+ at 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:
+ *
+ * @Entity
+ * public class Item {
+ * @Id int id;
+ * ...
+ * @ElementCollection
+ * @MapKeyColumn(name="IMAGE_NAME")
+ * @Column(name="IMAGE_FILENAME")
+ * @CollectionTable(name="IMAGE_MAPPING")
+ * Map<String, String> images; // map from image name to filename
+ * ...
+ * }
+ * </pre>
+ * @since Java Persistence 2.0
*/
- at Target({ METHOD, FIELD })
+ at 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}
+ *
+ * @Entity public class Employee {
+ * @ManyToMany
+ * public Projects<ProjectStatus, Project> getProjects() {...}
+ *
+ * @OneToMany
+ * @MapKeyEnumerated(STRING)
+ * public Map<SalaryRate, Employee> getEmployees() {...}
+ * ...
+ * }
+ * </pre>
+ *
+ * @see ElementCollection
+ * @see OneToMany
+ * @see ManyToMany
+ *
+ * @since Java Persistence 2.0
+ */
+ at 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:
+ *
+ * @Entity
+ * public class Company {
+ * @Id int id;
+ * ...
+ * @OneToMany // unidirectional
+ * @JoinTable(name="COMPANY_ORGANIZATION",
+ * joinColumns=@JoinColumn(name="COMPANY"),
+ * inverseJoinColumns=@JoinColumn(name="VICEPRESIDENT"))
+ * @MapKeyJoinColumn(name="DIVISION")
+ * Map<Division, VicePresident> organization;
+ * }
+ *
+ * Example 2:
+ *
+ * @Entity
+ * public class VideoStore {
+ * @Id int id;
+ * String name;
+ * Address location;
+ * ...
+ * @ElementCollection
+ * @CollectionTable(name="INVENTORY",
+ * joinColumns=@JoinColumn(name="STORE"))
+ * @Column(name="COPIES_IN_STOCK")
+ * @MapKeyJoinColumn(name="MOVIE", referencedColumnName="ID")
+ * Map<Movie, Integer> videoInventory;
+ * ...
+ * }
+ *
+ * @Entity
+ * public class Movie {
+ * @Id long id;
+ * String title;
+ * ...
+ * }
+ *
+ * Example 3:
+ *
+ * @Entity
+ * public class Student {
+ * @Id int studentId;
+ * ...
+ * @ManyToMany // students and courses are also many-many
+ * @JoinTable(name="ENROLLMENTS",
+ * joinColumns=@JoinColumn(name="STUDENT"),
+ * inverseJoinColumns=@JoinColumn(name="SEMESTER"))
+ * @MapKeyJoinColumn(name="COURSE")
+ * Map<Course, Semester> enrollment;
+ * ...
+ * }
+ * </pre>
+ *
+ * @since Java Persistence 2.0
*/
- at Target({ METHOD, FIELD })
+ at 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
*/
- at Target({ METHOD, FIELD })
+ at 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:
+ *
+ * @OneToMany
+ * @MapKeyTemporal(DATE)
+ * protected java.util.Map<java.util.Date, Employee> employees;
+ * </pre>
+ *
+ * @since Java Persistence 2.0
+ */
+ at Target({METHOD, FIELD})
+ at 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
- */
- at Target({ METHOD, FIELD })
- at 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
+ *
+ * @MappedSuperclass
+ * public class Employee {
+ *
+ * @Id protected Integer empId;
+ * @Version protected Integer version;
+ * @ManyToOne @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
+ * @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) { ... }
+ * }
+ *
+ * @Entity @Table(name="PT_EMP")
+ * @AssociationOverride(
+ * name="address",
+ * joincolumns=@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
+ * @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
*/
- at Target(TYPE) @Retention(RUNTIME)
-public @interface MappedSuperclass {}
+ at Documented
+ at Target({TYPE})
+ at 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
+ *
+ * @Entity
+ * public class Employee {
+ * @Id long empId;
+ * String name;
+ * ...
+ * }
+ *
+ * // dependent entity uses EmbeddedId for composite key
+ *
+ * @Embeddable
+ * public class DependentId {
+ * String name;
+ * long empid; // corresponds to primary key type of Employee
+ * }
+ *
+ * @Entity
+ * public class Dependent {
+ * @EmbeddedId DependentId id;
+ * ...
+ * @MapsId("empid") // maps the empid attribute of embedded id
+ * @ManyToOne Employee emp;
+ * }
+ * </pre>
+ *
+ * @since Java Persistence 2.0
+ */
+ at Target( { METHOD, FIELD })
+ at 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
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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>
+ * @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>
+ * @PersistenceContext
+ * public EntityManager em;
+ * ...
+ * customers = em.createNamedQuery("findAllCustomersWithName")
+ * .setParameter("custName", "Smith")
+ * .getResultList();
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
-//TODO remove the mackage target
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target({TYPE})
+ at 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:
+ *
+ * @OneToMany(cascade=ALL, mappedBy="customer")
+ * public Set<Order> getOrders() { return orders; }
+ *
+ * In Order class:
+ *
+ * @ManyToOne
+ * @JoinColumn(name="CUST_ID", nullable=false)
+ * public Customer getCustomer() { return customer; }
+ *
+ *
+ * Example 2: One-to-Many association without using generics
+ *
+ * // In Customer class:
+ *
+ * @OneToMany(targetEntity=com.acme.Order.class, cascade=ALL,
+ * mappedBy="customer")
+ * public Set getOrders() { return orders; }
+ *
+ * // In Order class:
+ *
+ * @ManyToOne
+ * @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:
+ *
+ * @OneToMany(orphanRemoval=true)
+ * @JoinColumn(name="CUST_ID") // join column is in table for Order
+ * public Set<Order> getOrders() {return orders;}
+ *
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @OneToOne(optional=false)
+ * @JoinColumn(
+ * name="CUSTREC_ID", unique=true, nullable=false, updatable=false)
+ * public CustomerRecord getCustomerRecord() { return customerRecord; }
+ *
+ * // On CustomerRecord class:
+ *
+ * @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:
+ *
+ * @Entity
+ * public class Employee {
+ * @Id Integer id;
+ *
+ * @OneToOne @MapsId
+ * EmployeeInfo info;
+ * ...
+ * }
+ *
+ * // On EmployeeInfo class:
+ *
+ * @Entity
+ * public class EmployeeInfo {
+ * @Id Integer id;
+ * ...
+ * }
+ *
+ *
+ * Example 3: One-to-one association from an embeddable class to another entity.
+ *
+ * @Entity
+ * public class Employee {
+ * @Id int id;
+ * @Embedded LocationDetails location;
+ * ...
+ * }
+ *
+ * @Embeddable
+ * public class LocationDetails {
+ * int officeNumber;
+ * @OneToOne ParkingSpot parkingSpot;
+ * ...
+ * }
+ *
+ * @Entity
+ * public class ParkingSpot {
+ * @Id int id;
+ * String garage;
+ * @OneToOne(mappedBy="location.parkingSpot") Employee assignedTo;
+ * ...
+ * }
+ *
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @Entity
+ * public class Course {
+ * ...
+ * @ManyToMany
+ * @OrderBy("lastname ASC")
+ * public List<Student> getStudents() {...};
+ * ...
+ * }
+ *
+ * Example 2:
+ *
+ * @Entity
+ * public class Student {
+ * ...
+ * @ManyToMany(mappedBy="students")
+ * @OrderBy // ordering by primary key is assumed
+ * public List<Course> getCourses() {...};
+ * ...
+ * }
+ *
+ * Example 3:
+ *
+ * @Entity
+ * public class Person {
+ * ...
+ * @ElementCollection
+ * @OrderBy("zipcode.zip, zipcode.plusFour")
+ * public Set<Address> getResidences() {...};
+ * ...
+ * }
+ *
+ * @Embeddable
+ * public class Address {
+ * protected String street;
+ * protected String city;
+ * protected String state;
+ * @Embedded protected Zipcode zipcode;
+ * }
+ *
+ * @Embeddable
+ * public class Zipcode {
+ * protected String zip;
+ * protected String plusFour;
+ * }
+ * </pre>
+ *
+ * @see OrderColumn
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({METHOD, FIELD})
+ at 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
- */
- at Target({ METHOD, FIELD })
- at 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:
+ *
+ * @Entity
+ * public class CreditCard {
+ *
+ * @Id long ccNumber;
+ *
+ * @OneToMany // unidirectional
+ * @OrderColumn
+ * List<CardTransaction> transactionHistory;
+ * ...
+ * }
+ *
+ * </pre>
+ *
+ * @see OrderBy
+ *
+ * @since Java Persistence 2.0
+ */
+ at Target( { METHOD, FIELD })
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
- at Retention(RetentionPolicy.RUNTIME)
+
+ at Target({TYPE, METHOD, FIELD})
+ at 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 at jboss.org">Bill Burke</a>
+ *@see PersistenceContext
+ *
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.TYPE})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({TYPE})
+ at 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 at 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
- */
- at Target({})
- at 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
+ */
+ at Target({ })
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({ TYPE, METHOD, FIELD })
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.TYPE})
- at Retention(RetentionPolicy.RUNTIME)
+
+ at Target({ TYPE })
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.METHOD})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({METHOD})
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.METHOD})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({METHOD})
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.METHOD})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({METHOD})
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.METHOD})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({METHOD})
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.METHOD})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({METHOD})
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.METHOD})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({METHOD})
+ at 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 at jboss.org">Bill Burke</a>
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.METHOD})
- at Retention(RetentionPolicy.RUNTIME)
+ at Target({METHOD})
+ at 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
+ * @Entity
+ * @Table(name="CUST")
+ * @Inheritance(strategy=JOINED)
+ * @DiscriminatorValue("CUST")
+ * public class Customer { ... }
+ *
+ * @Entity
+ * @Table(name="VCUST")
+ * @DiscriminatorValue("VCUST")
+ * @PrimaryKeyJoinColumn(name="CUST_ID")
+ * public class ValuedCustomer extends Customer { ... }
+ * </pre>
+ *
+ * @see SecondaryTable
+ * @see Inheritance
+ * @see OneToOne
+ * @since Java Persistence 1.0
*/
- at Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({ TYPE, METHOD, FIELD })
+ at 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
+ *
+ * @Entity
+ * @Table(name="VCUST")
+ * @DiscriminatorValue("VCUST")
+ * @PrimaryKeyJoinColumns({
+ * @PrimaryKeyJoinColumn(name="CUST_ID",
+ * referencedColumnName="ID"),
+ * @PrimaryKeyJoinColumn(name="CUST_TYPE",
+ * referencedColumnName="TYPE")
+ * })
+ * public class ValuedCustomer extends Customer { ... }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({ TYPE, METHOD, FIELD })
+ at 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
*/
- at Target({})
+ at 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.
+ *
+ * @Entity
+ * @Table(name="CUSTOMER")
+ * @SecondaryTable(name="CUST_DETAIL",
+ * pkJoinColumns=@PrimaryKeyJoinColumn(name="CUST_ID"))
+ * public class Customer { ... }
+ *
+ *
+ * Example 2: Single secondary table with multiple primary key columns.
+ *
+ * @Entity
+ * @Table(name="CUSTOMER")
+ * @SecondaryTable(name="CUST_DETAIL",
+ * pkJoinColumns={
+ * @PrimaryKeyJoinColumn(name="CUST_ID"),
+ * @PrimaryKeyJoinColumn(name="CUST_TYPE")})
+ * public class Customer { ... }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target(TYPE)
+ at 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.
+ *
+ * @Entity
+ * @Table(name="EMPLOYEE")
+ * @SecondaryTables({
+ * @SecondaryTable(name="EMP_DETAIL"),
+ * @SecondaryTable(name="EMP_HIST")
+ * })
+ * public class Employee { ... }
+ *
+ *
+ * Example 2: Multiple secondary tables with differently named primary key columns.
+ *
+ * @Entity
+ * @Table(name="EMPLOYEE")
+ * @SecondaryTables({
+ * @SecondaryTable(name="EMP_DETAIL",
+ * pkJoinColumns=@PrimaryKeyJoinColumn(name="EMPL_ID")),
+ * @SecondaryTable(name="EMP_HIST",
+ * pkJoinColumns=@PrimaryKeyJoinColumn(name="EMPLOYEE_ID"))
+ * })
+ * public class Employee { ... }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target(TYPE)
+ at 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:
+ *
+ * @SequenceGenerator(name="EMP_SEQ", allocationSize=25)
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+ at Target({ TYPE, METHOD, FIELD })
+ at 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");
+ *
+ * @SqlResultSetMapping(name="OrderResults",
+ * entities={
+ * @EntityResult(entityClass=com.acme.Order.class, fields={
+ * @FieldResult(name="id", column="order_id"),
+ * @FieldResult(name="quantity", column="order_quantity"),
+ * @FieldResult(name="item", column="order_item")})},
+ * columns={
+ * @ColumnResult(name="item_name")}
+ * )
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME)
+ at Target({ TYPE })
+ at 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
*/
- at Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME)
+ at Target({ TYPE })
+ at 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
+ * @Entity
+ * @Table(name="CUST", schema="RECORDS")
+ * public class Customer { ... }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({TYPE}) @Retention(RUNTIME)
+ at Target(TYPE)
+ at 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:
+ *
+ * @Entity public class Employee {
+ * ...
+ * @TableGenerator(
+ * name="empGen",
+ * table="ID_GEN",
+ * pkColumnName="GEN_KEY",
+ * valueColumnName="GEN_VALUE",
+ * pkColumnValue="EMP_ID",
+ * allocationSize=1)
+ * @Id
+ * @GeneratedValue(strategy=TABLE, generator="empGen")
+ * int id;
+ * ...
+ * }
+ *
+ * Example 2:
+ *
+ * @Entity public class Address {
+ * ...
+ * @TableGenerator(
+ * name="addressGen",
+ * table="ID_GEN",
+ * pkColumnName="GEN_KEY",
+ * valueColumnName="GEN_VALUE",
+ * pkColumnValue="ADDR_ID")
+ * @Id
+ * @GeneratedValue(strategy=TABLE, generator="addressGen")
+ * int id;
+ * ...
+ * }
+ * </pre>
+ *
+ * @see GeneratedValue
+ * @since Java Persistence 1.0
*/
- at Target({TYPE, METHOD, FIELD})
+ at 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
+ * @Temporal(DATE)
+ * protected java.util.Date endDate;
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD})
+ at 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:
+ *
+ * @Entity
+ * public class Employee {
+ * @Id int id;
+ * @Transient User currentUser;
+ * ...
+ * }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
-public @interface Transient {}
+ at Target({ METHOD, FIELD })
+ at 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:
+ * @Entity
+ * @Table(
+ * name="EMPLOYEE",
+ * uniqueConstraints=
+ * @UniqueConstraint(columnNames={"EMP_ID", "EMP_NAME"})
+ * )
+ * public class Employee { ... }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({}) @Retention(RUNTIME)
+ at Target({ })
+ at 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:
+ *
+ * @Version
+ * @Column(name="OPTLOCK")
+ * protected int getVersionNum() { return versionNum; }
+ * </pre>
+ *
+ * @since Java Persistence 1.0
*/
- at Target({METHOD, FIELD}) @Retention(RUNTIME)
-public @interface Version {}
+ at Target({ METHOD, FIELD })
+ at 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<Boolean></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<Long>
+ */
+ Expression<Long> toLong(Expression<? extends Number> number);
+
+ /**
+ * Typecast. Returns same expression object.
+ *
+ * @param number numeric expression
+ *
+ * @return Expression<Integer>
+ */
+ Expression<Integer> toInteger(Expression<? extends Number> number);
+
+ /**
+ * Typecast. Returns same expression object.
+ *
+ * @param number numeric expression
+ *
+ * @return Expression<Float>
+ */
+ Expression<Float> toFloat(Expression<? extends Number> number);
+
+ /**
+ * Typecast. Returns same expression object.
+ *
+ * @param number numeric expression
+ *
+ * @return Expression<Double>
+ */
+ Expression<Double> toDouble(Expression<? extends Number> number);
+
+ /**
+ * Typecast. Returns same expression object.
+ *
+ * @param number numeric expression
+ *
+ * @return Expression<BigDecimal>
+ */
+ Expression<BigDecimal> toBigDecimal(Expression<? extends Number> number);
+
+ /**
+ * Typecast. Returns same expression object.
+ *
+ * @param number numeric expression
+ *
+ * @return Expression<BigInteger>
+ */
+ Expression<BigInteger> toBigInteger(Expression<? extends Number> number);
+
+ /**
+ * Typecast. Returns same expression object.
+ *
+ * @param character expression
+ *
+ * @return Expression<String>
+ */
+ 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<String> q = cb.createQuery(String.class);
+ * Root<Order> order = q.from(Order.class);
+ * q.select(order.get("shippingAddress").<String>get("state"));
*
+ * CriteriaQuery<Product> q2 = cb.createQuery(Product.class);
+ * q2.select(q2.from(Order.class)
+ * .join("items")
+ * .<Item,Product>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<Tuple></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<X></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<X[]></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<Object></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<Object></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<Tuple></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<X></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<X[]></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<Object></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<Object></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
*/
+ at 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<Person> q = cb.createQuery(Person.class);
+ * Root<Person> p = q.from(Person.class);
+ * q.select(p)
+ * .where(cb.isMember("joe",
+ * p.<Set<String>>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<Person> q = cb.createQuery(Person.class);
+ * Root<Person> p = q.from(Person.class);
+ * Path<Set<String>> 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 at 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);
+}
More information about the hibernate-commits
mailing list