Author: hardy.ferentschik Date: 2009-03-08 15:48:33 -0400 (Sun, 08 Mar 2009) New Revision: 16112 Added: jpa-api/trunk/src/main/java/javax/ jpa-api/trunk/src/main/java/javax/jpa/ jpa-api/trunk/src/main/java/javax/jpa/criteria/ jpa-api/trunk/src/main/java/javax/jpa/criteria/AbstractCollectionJoin.java jpa-api/trunk/src/main/java/javax/jpa/criteria/AbstractQuery.java jpa-api/trunk/src/main/java/javax/jpa/criteria/CollectionJoin.java jpa-api/trunk/src/main/java/javax/jpa/criteria/CriteriaQuery.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Expression.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Fetch.java jpa-api/trunk/src/main/java/javax/jpa/criteria/FetchParent.java jpa-api/trunk/src/main/java/javax/jpa/criteria/From.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Join.java jpa-api/trunk/src/main/java/javax/jpa/criteria/JoinType.java jpa-api/trunk/src/main/java/javax/jpa/criteria/ListJoin.java jpa-api/trunk/src/main/java/javax/jpa/criteria/MapJoin.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Order.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Parameter.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Path.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Predicate.java jpa-api/trunk/src/main/java/javax/jpa/criteria/QueryBuilder.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Result.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Root.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Selection.java jpa-api/trunk/src/main/java/javax/jpa/criteria/SetJoin.java jpa-api/trunk/src/main/java/javax/jpa/criteria/Subquery.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/ jpa-api/trunk/src/main/java/javax/jpa/metamodel/AbstractCollection.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Attribute.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Basic.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Bindable.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Collection.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Embeddable.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Entity.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/IdentifiableType.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/List.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/ManagedType.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Map.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/MappedSuperclass.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Member.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Metamodel.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Set.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/Type.java jpa-api/trunk/src/main/java/javax/jpa/metamodel/TypesafeMetamodel.java jpa-api/trunk/src/main/java/javax/persistence/ 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/CascadeType.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/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/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/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/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/PersistenceUnits.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/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/UniqueConstraint.java jpa-api/trunk/src/main/java/javax/persistence/Version.java jpa-api/trunk/src/main/java/javax/persistence/package-info.java jpa-api/trunk/src/main/java/javax/persistence/spi/ jpa-api/trunk/src/main/java/javax/persistence/spi/ClassTransformer.java jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProvider.java jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitInfo.java jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitTransactionType.java jpa-api/trunk/src/main/java/javax/persistence/spi/package-info.java Log: added jpa 2 api Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/AbstractCollectionJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/AbstractCollectionJoin.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/AbstractCollectionJoin.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,37 @@ +package javax.persistence.criteria; + +import javax.persistence.metamodel.AbstractCollection; + +/** + * The interface AbstractCollectionJoin 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 + */ +public interface AbstractCollectionJoin<Z, C, E> + extends Join<Z, E> { + + /** + * Return the metamodel representation for the collection. + * @return metamodel type representing the collection that is + * the target of the join + */ + AbstractCollection<? super Z, C, E> getModel(); + + //TODO: do we need these???? + /* + Predicate isEmpty(); + Predicate isNotEmpty(); + + Expression<Integer> size(); + + Predicate isMember(E elem); + Predicate isNotMember(E elem); + + Predicate isMember(Expression<E> elem); + Predicate isNotMember(Expression<E> elem); + */ +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/AbstractQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/AbstractQuery.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/AbstractQuery.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,164 @@ +package javax.persistence.criteria; + +import java.util.List; +import java.util.Set; + +import javax.persistence.metamodel.Entity; + +/** + * The interface AbstractQuery 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 + * an ordered list of orders + */ +public interface AbstractQuery { + + /** + * 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(Entity<X> entity); + + /** + * 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); + + /** + * Return the query roots. + * @return the set of query roots + */ + Set<Root<?>> getRoots(); + + /** + * 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 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 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 group(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 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 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 expression + * @return the modified query. + */ + AbstractQuery order(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. + * @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 distinct(boolean distinct); + + /** + * Return the ordering expressions in order of precedence. + * @return the list of ordering expressions + */ + List<Order> getOrderList(); + + /** + * Return a list of the grouping expressions + * @result the list of grouping expressions + */ + List<Expression<?>> getGroupList(); + + /** + * Return the predicate that corresponds to the whereclause + * restriction(s). + * @return where clause predicate + */ + Predicate getRestriction(); + + /** + * Return the predicate that corresponds to the restriction(s) + * over the grouping items. + * @return having clause predicate + */ + Predicate getGroupRestriction(); + + /** + * Return whether duplicate query results must be eliminated or + * retained. + * @result boolean indicating whether duplicate query results must + * be eliminated + */ + boolean isDistinct(); + + /** + * Specify that the query is to be used as a subquery having + * the specified return type. + * @return subquery corresponding to the query + */ + <U> Subquery<U> subquery(Class<U> type); + +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/CollectionJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/CollectionJoin.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/CollectionJoin.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,22 @@ +package javax.persistence.criteria; + +import java.util.Collection; + +/** + * The interface CollectionJoin 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. + * + * @param <Z> The source type of the join + * @param <E> The element type of the target oCollection + */ +public interface CollectionJoin<Z, E> + extends AbstractCollectionJoin<Z, Collection<E>, E> { + + /** + * Return the metamodel representation for the collection. + * @return metamodel type representing the Collection that is + * the target of the join + */ + javax.persistence.metamodel.Collection<? super Z, E> getModel(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/CriteriaQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/CriteriaQuery.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/CriteriaQuery.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,140 @@ +package javax.persistence.criteria; + +import java.util.List; + + +/** + * The interface CriteriaQuery defines functionality that is specific + * to top-level queries. + * + * A top-level query has an ordered list of selections. + */ + +public interface CriteriaQuery extends AbstractQuery { + + /** + * Specify the items that are to be returned in the query result. + * Replaces the previously specified selections, if any. + * @param selections expressions specifying the items that + * are returned in the query result + * @return the modified query + */ + CriteriaQuery select(Selection<?>... selections); + + + //override the return type only: + + /** + * 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 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 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 group(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 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 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. + * This method only overrides the return type of the + * corresponding AbstractQuery method. + * @param o zero or more ordering expressions + * @return the modified query. + */ + CriteriaQuery order(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 distinct(boolean distinct); + + /** + * Return the selection list of the query + * @return the list of items to be returned in the query result + */ + List<Selection<?>> getSelectionList(); + + /** + * Bind a parameter + * @param parameter to be bound + * @param value + * @return the modified query. + */ + <T> CriteriaQuery setParameter(Parameter<T> param, T value); + + // Not sure what the intention here is: + + List<Result> getResultList(); + + Result getSingleResult(); + +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Expression.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Expression.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Expression.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,43 @@ +package javax.persistence.criteria; + +/** + * Type for query expressions. + * @param <T> the type of the expression + */ + +public interface Expression<T> extends Selection<T> { + + /** + * Return the Java type of the expression. + * @return the Java type of the expression + */ + Class<T> getJavaType(); + + /** + * Apply a predicate to test whether the expression is null. + * @return predicate testing whether the expression is null + */ + Predicate isNull(); + + /** + * Apply a predicate to test whether the expression is not null. + * @return predicate testing whether the expression is not null. + */ + Predicate isNotNull(); + + /** + * Apply a predicate to test whether the expression is a member + * of the argument list. + * @param values + * @return predicate testing for membership in the list + */ + Predicate in(Object... values); + + /** + * Perform a typecast upon the expression. + * Warning: may result in a runtime failure. + * @param type + * @return expression + */ + <X> Expression<X> as(Class<X> type); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Fetch.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Fetch.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Fetch.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,29 @@ +package javax.persistence.criteria; + +import javax.persistence.metamodel.Member; + +/** + * Represents a join-fetched association or attribute + * @param <Z> + * @param <X> + */ +public interface Fetch<Z, X> extends FetchParent<Z, X> { + + /** + * Return the metamodel member corresponding to the fetch join. + * @return metamodel member type for the join + */ + Member<? extends Z, X> getMember(); + + /** + * 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(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/FetchParent.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/FetchParent.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/FetchParent.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,72 @@ +package javax.persistence.criteria; + +import javax.persistence.metamodel.AbstractCollection; +import javax.persistence.metamodel.Attribute; + +/** + * Represents an element of the from clause which may + * function as the parent of Fetches. + * + * @param <Z> + * @param <X> + */ +public interface FetchParent<Z, X> { + + /** + * Return the fetch joins that have been made from this type. + * @return fetch joins made from this type + */ + java.util.Set<Fetch<X, ?>> getFetches(); + + /** + * Fetch join to the specified attribute. + * @param assoc target of the join + * @return the resulting fetch join + */ + <Y> Fetch<X, Y> fetch(Attribute<? super X, Y> assoc); + + /** + * Fetch join to the specified attribute using the given + * join type. + * @param assoc target of the join + * @param jt join type + * @return the resulting fetch join + */ + <Y> Fetch<X, Y> fetch(Attribute<? super X, Y> assoc, JoinType jt); + + /** + * Join to the specified collection. + * @param assoc target of the join + * @return the resulting join + */ + <Y> Fetch<X, Y> fetch(AbstractCollection<? super X, ?, Y> assoc); + + /** + * Join to the specified collection using the given join type. + * @param assoc target of the join + * @param jt join type + * @return the resulting join + */ + <Y> Fetch<X, Y> fetch(AbstractCollection<? super X, ?, Y> assoc, JoinType jt); + + + //Untypesafe: + + /** + * Fetch join to the specified attribute or association. + * @param name name of the attribute or association for the + * target of the join + * @return the resulting fetch join + */ + <Y> Fetch<X, Y> fetch(String assocName); + + /** + * Fetch join to the specified attribute or association using + * the given join type. + * @param name name of the attribute or association for the + * target of the join + * @param jt join type + * @return the resulting fetch join + */ + <Y> Fetch<X, Y> fetch(String assocName, JoinType jt); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/From.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/From.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/From.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,200 @@ +package javax.persistence.criteria; + +import javax.persistence.metamodel.Attribute; +import javax.persistence.metamodel.Collection; +import javax.persistence.metamodel.List; +import javax.persistence.metamodel.Map; +import javax.persistence.metamodel.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 + * collections belonging to the type, and for Paths of attributes + * belonging to the type. + * @param <Z> + * @param <X> + */ +public interface From<Z, X> extends Path<X>, FetchParent<Z, X> { + + /** + * Return the joins that have been made from this type. + * @return joins made from this type + */ + java.util.Set<Join<X, ?>> getJoins(); + + /** + * Join to the specified attribute. + * @param attribute target of the join + * @return the resulting join + */ + <Y> Join<X, Y> join(Attribute<? super X, Y> attribute); + + /** + * Join to the specified 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(Attribute<? super X, Y> attribute, JoinType jt); + + + /** + * Join to the specified Collection-valued attribute. + * @param collection target of the join + * @return the resulting join + */ + <Y> CollectionJoin<X, Y> join(Collection<? super X, Y> collection); + + /** + * Join to the specified Set-valued attribute. + * @param set target of the join + * @return the resulting join + */ + <Y> SetJoin<X, Y> join(Set<? super X, Y> set); + + /** + * Join to the specified List-valued attribute. + * @param list target of the join + * @return the resulting join + */ + <Y> ListJoin<X, Y> join(List<? super X, Y> list); + + /** + * Join to the specified Map-valued attribute. + * @param map target of the join + * @return the resulting join + */ + <K, V> MapJoin<X, K, V> join(Map<? super X, K, V> map); + + + /** + * 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(Collection<? super X, Y> collection, JoinType jt); + + /** + * 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(Set<? super X, Y> set, JoinType jt); + + /** + * 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(List<? super X, Y> list, JoinType jt); + + /** + * 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(Map<? super X, K, V> map, JoinType jt); + + + //Untypesafe: + + /** + * Join to the specified attribute. + * @param name name of the attribute for the + * target of the join + * @return the resulting join + */ + <W, Y> Join<W, Y> join(String attributeName); + + /** + * Join to the specified Collection-valued attribute. + * @param name name of the attribute for the + * target of the join + * @return the resulting join + */ + <W, Y> CollectionJoin<W, Y> joinCollection(String attributeName); + + /** + * Join to the specified Set-valued attribute. + * @param name name of the attribute for the + * target of the join + * @return the resulting join + */ + <W, Y> SetJoin<W, Y> joinSet(String attributeName); + + /** + * Join to the specified List-valued attribute. + * @param name name of the attribute for the + * target of the join + * @return the resulting join + */ + <W, Y> ListJoin<W, Y> joinList(String attributeName); + + /** + * Join to the specified Map-valued attribute. + * @param name name of the attribute for the + * target of the join + * @return the resulting join + */ + <W, K, V> MapJoin<W, K, V> joinMap(String attributeName); + + /** + * Join to the specified attribute, using the given + * join type. + * @param name name of the attribute for the + * target of the join + * @param jt join type + * @return the resulting join + */ + <W, Y> Join<W, Y> join(String attributeName, JoinType jt); + + /** + * Join to the specified Collection-valued attribute, using + * the given join type. + * @param name name of the attribute for the + * target of the join + * @param jt join type + * @return the resulting join + */ + <W, Y> CollectionJoin<W, Y> joinCollection(String attributeName, JoinType jt); + + /** + * Join to the specified Set-valued attribute, using + * the given join type. + * @param name name of the attribute for the + * target of the join + * @param jt join type + * @return the resulting join + */ + <W, Y> SetJoin<W, Y> joinSet(String attributeName, JoinType jt); + + /** + * Join to the specified List-valued attribute, using + * the given join type. + * @param name name of the attribute for the + * target of the join + * @param jt join type + * @return the resulting join + */ + <W, Y> ListJoin<W, Y> joinList(String attributeName, JoinType jt); + + /** + * Join to the specified Mapn-valued attribute, using + * the given join type. + * @param name name of the attribute for the + * target of the join + * @param jt join type + * @return the resulting join + */ + <W, K, V> MapJoin<W, K, V> joinMap(String attributeName, JoinType jt); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Join.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Join.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Join.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,29 @@ +package javax.persistence.criteria; + +import javax.persistence.metamodel.Member; + +/** + * A join to an entity or embeddable type. + * @param <Z> The source type of the join + * @param <X> The target type of the join + */ +public interface Join<Z, X> extends From<Z, X> { + + /** + * Return the metamodel member corresponding to the join. + * @return metamodel member type for the join + */ + Member<? extends Z, X> getMember(); + + /** + * Return the parent of the join. + * @return join parent + */ + From<?, Z> getParent(); + + /** + * Return the join type. + * @return join type + */ + JoinType getJoinType(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/JoinType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/JoinType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/JoinType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,8 @@ +package javax.persistence.criteria; + +/** + * Defines the three types of joins + */ +public enum JoinType { + INNER, LEFT, RIGHT +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/ListJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/ListJoin.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/ListJoin.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,34 @@ +package javax.persistence.criteria; + +import java.util.List; + +/** + * The interface ListJoin 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. + * + * @param <Z> The source type of the join + * @param <E> The element type of the target List + */ + +public interface ListJoin<Z, E> + extends AbstractCollectionJoin<Z, List<E>, E> { + + /** + * Return the metamodel representation for the list. + * @return metamodel type representing the List that is + * the target of the join + */ + javax.persistence.metamodel.List<? super Z, E> getModel(); + + /** + * Return 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(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/MapJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/MapJoin.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/MapJoin.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,57 @@ +package javax.persistence.criteria; + +import java.util.Map; + +/** + * The interface MapJoin 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. + * + * @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 + */ + +public interface MapJoin<Z, K, V> + extends AbstractCollectionJoin<Z, Map<K, V>, V> { + + /** + * Return the metamodel representation for the map. + * @return metamodel type representing the Map that is + * the target of the join + */ + javax.persistence.metamodel.Map<? super Z, K, V> getModel(); + + /** + * Specify a join over the map key. + * @return result of joining over the map key + */ + Join<Map<K, V>, K> joinKey(); + + /** + * Specify 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); + + /** + * Return a path expression that corresponds to the map key. + * @return Path corresponding to map key + */ + Path<K> key(); + + /** + * Return 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(); //Unnecessary - just returns this + + /** + * Return an expression that corresponds to the map entry. + * @return Expression corresponding to the map entry + */ + Expression<Map.Entry<K, V>> entry(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Order.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Order.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Order.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +package javax.persistence.criteria; + +/** + * An object that defines an ordering over the query results. + */ +public interface Order { + + /** + * Switch the ordering. + */ + void reverse(); + + /** + * 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 + */ + <T extends Comparable<T>> Expression<T> getExpression(); +} + Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Parameter.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Parameter.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Parameter.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,8 @@ +package javax.persistence.criteria; + +/** + * Type for query parameters. + * @param <T> the type of the parameter + */ + +public interface Parameter<T> extends Expression<T> {} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Path.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Path.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Path.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,63 @@ +package javax.persistence.criteria; + +import javax.persistence.metamodel.AbstractCollection; +import javax.persistence.metamodel.Attribute; +import javax.persistence.metamodel.Bindable; +import javax.persistence.metamodel.Map; + +/** + * 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 + */ +public interface Path<X> extends Expression<X> { + + Bindable<X> getModel(); //TODO: what does this return for a collection key, value? null? + + /** + * Return the parent "node" in the path. + * @return parent + */ + Path<?> getParentPath(); + + /** + * Return the path corresponding to the referenced + * non-collection valued attribute. + * @param model attribute + * @return path corresponding to the referenced attribute + */ + <Y> Path<Y> get(Attribute<? super X, Y> model); + + /** + * Return the path corresponding to the referenced + * collection-valued attribute. + * @param model collection-valued attribute + * @return path corresponding to the referenced attribute + */ + <E, C extends java.util.Collection<E>> Expression<C> get(AbstractCollection<X, C, E> collection); + + /** + * Return the path corresponding to the referenced + * map-valued attribute. + * @param model map-valued attribute + * @return path corresponding to the referenced attribute + */ + <K, V, M extends java.util.Map<K, V>> Expression<M> get(Map<X, K, V> collection); + + /** + * Return an expression corresponding to the type of the path. + * @return expression corresponding to the type of the path + */ + Expression<Class<? extends X>> type(); + + + //Untypesafe: + + /** + * Return the path corresponding to the referenced + * attribute. + * @param attName name of the attribute + * @return path corresponding to the referenced attribute + */ + <Y> Path<Y> get(String attName); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Predicate.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Predicate.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Predicate.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,49 @@ +package javax.persistence.criteria; + +import java.util.List; + +/** + * The type of a simple or compound predicate: a conjunction or + * disjunction of restrictions. + * A simple predicate is considered to be a conjunction with a + * single conjunct. + */ +public interface Predicate extends Expression<Boolean> { + + public static enum BooleanOperator { + 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(); + + /** + * Has negation been applied to the predicate? + * @return boolean indicating if the predicate has been negated + */ + boolean isNegated(); + + /** + * Return the top-level conjuncts or disjuncts of the predicate. + * @return list boolean expressions forming the predicate + */ + List<Expression<Boolean>> getExpressions(); + + /** + * Add another operand to the predicate. + * Whether the operand is added as a conjunct or disjunct is + * determined by the predicate operator. + * @return the resulting compound predicate + */ + Predicate add(Expression<Boolean> s); + + /** + * Apply negation to the predicate. + * @return the negated predicate + */ + Predicate negate(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/QueryBuilder.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/QueryBuilder.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/QueryBuilder.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,1297 @@ +package javax.persistence.criteria; + +import java.math.BigDecimal; +import java.math.BigInteger; +import java.util.Collection; +import java.util.Map; +import java.util.Set; + +/** + * Factory object for queries, select lists, restrictions, + * expressions, orderings + * The factory methods are all typesafe. + * 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 create(); + + + //select new Foo(...) equivalent: + + /** + * Define a select list item corresponding to a constructor. + * @param result class whose instance is to be constructed + * @param selections arguments to the constructor + * @return selection item + */ + <Y> Selection<Y> select(Class<Y> result, 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<N> 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 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 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 expression applying the count operation. + * @param x expression representing input value to count + * operation + * @return count expression + */ + Expression<Integer> 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<Integer> 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); + + // Not sure what this does. Why is this needed? + <Y> Expression<Y> none(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 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. + * @param restriction zero or more restriction predicates + * @return and predicate + */ + Predicate and(Predicate... restrictions); + + /** + * Create a conjunction of the given restriction predicates. + * @param restriction zero or more restriction predicates + * @return and 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). + * @return and predicate + */ + Predicate conjunction(); + + /** + * Create a disjunction (with zero disjuncts). + * @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); + + + //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); + + //Predicate in(Expression<?> expression, Object... values); + + //<Y> Predicate equal(Expression<Y> x, Expression<Y> y); + //<Y> Predicate notEqual(Expression<Y> x, Expression<Y> y); + //<Y> Predicate equal(Expression<Y> x, Y y); + //<Y> Predicate notEqual(Expression<Y> x, Y y); + //Predicate eq(Expression<? extends Number> x, Expression<? extends Number> y); + //Predicate ne(Expression<? extends Number> x, Expression<? extends Number> y); + //Predicate eq(Expression<? extends Number> x, Number y); + //Predicate ne(Expression<? extends Number> x, Number 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 negated expression + */ + <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); + + + //TODO: support builder pattern for sums, products + + /** + * 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 modulus + */ + Expression<Double> sqrt(Expression<? extends Number> x); + + + //typecasts: + + /** + * Typecast + * @param numeric expression + * @return Expression<Long> + */ + Expression<Long> toLong(Expression<? extends Number> number); + + /** + * Typecast + * @param numeric expression + * @return Expression<Integer> + */ + Expression<Integer> toInteger(Expression<? extends Number> number); + + /** + * Typecast + * @param numeric expression + * @return Expression<Float> + */ + Expression<Float> toFloat(Expression<? extends Number> number); + + /** + * Typecast * @param numeric expression + * @return Expression<Double> + */ + Expression<Double> toDouble(Expression<? extends Number> number); + + /** + * Typecast + * @param numeric expression + * @return Expression<BigDecimal> + */ + Expression<BigDecimal> toBigDecimal(Expression<? extends Number> number); + + /** + * Typecast + * @param 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. + * @param parameter class + * @return parameter + */ + <T> Parameter<T> parameter(Class<T> paramClass); + + + //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 + * @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 elementexpression + * @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 elementexpression + * @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>> keySet(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 lowercasing a string. + * @param x string expression + * @return expression to convert to lowercase + */ + Expression<String> lower(Expression<String> x); + + /** + * Create expression for uppercasing a string. + * @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 string to be search + * @param pattern 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 string to be search + * @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, 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 string to be search + * @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 string to be search + * @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 + * @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, Object y); + + + // coalesce builder: + + /** + * Interface used to build coalesce expressions + */ + 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. + * 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. + * @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 "then" condition + * @param result "when" result + * @result simple case expression + */ + SimpleCase<C, R> when(C condition, R result); + + /** + * Add a when/then clause to the case expression. + * @param condition "then" condition + * @param result "when" result expression + * @result 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 + * @result expression + */ + Expression<R> elseCase(R result); + + /** + * Add an else clause to the case expression. + * @param result "else" result expression + * @result expression + */ + Expression<R> elseCase(Expression<? extends R> result); + } + + /** + * Create simple case expression. + * @param expression to be tested against the cases + * @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 "then" condition + * @param result "when" result + * @result general case expression + */ + Case<R> when(Expression<Boolean> condition, R result); + + /** + * Add a when/then clause to the case expression. + * @param condition "then" condition + * @param result "when" result expression + * @result 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 + * @result expression + */ + Expression<R> elseCase(R result); + + /** + * Add an else clause to the case expression. + * @param result "else" result expression + * @result expression + */ + Expression<R> elseCase(Expression<? extends R> result); + } + + /** + * Create a general case expression. + * @return general case expression + */ + <R> Case<R> selectCase(); +} + + + + Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Result.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Result.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Result.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,12 @@ +package javax.persistence.criteria; + +public interface Result { + + <X> X get(Selection<X> selection); + + <X> X get(int i, Class<X> type); + + Object get(int i); + + Object[] toArray(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Root.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Root.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Root.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,18 @@ +package javax.persistence.criteria; + +import javax.persistence.metamodel.Entity; + +/** + * A root type in the from clause. + * Query roots always reference entities. + * + * @param <X> the entity type referenced by the root + */ +public interface Root<X> extends From<X, X> { + + /** + * Return the metamodel entity corresponding to the root. + * @return metamodel entity corresponding to the root + */ + Entity<X> getModel(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Selection.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Selection.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Selection.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,16 @@ +package javax.persistence.criteria; + +/** + * The Selection interface defines an item that is returned by + * a query. + * @param <X> + */ + +public interface Selection<X> { + + /** + * Return the Java type of the selection. + * @return the Java type of the selection item + */ + Class<?> getJavaType(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/SetJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/SetJoin.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/SetJoin.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,23 @@ +package javax.persistence.criteria; + +import java.util.Set; + +/** + * The interface SetJoin 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. + * + * @param <Z> The source type of the join + * @param <E> The element type of the target Set + */ + +public interface SetJoin<Z, E> + extends AbstractCollectionJoin<Z, Set<E>, E> { + + /** + * Return the metamodel representation for the set. + * @return metamodel type representing the Set that is + * the target of the join + */ + javax.persistence.metamodel.Set<? super Z, E> getModel(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/criteria/Subquery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/criteria/Subquery.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/criteria/Subquery.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,186 @@ + +package javax.persistence.criteria; + +import javax.persistence.metamodel.Collection; +import javax.persistence.metamodel.List; +import javax.persistence.metamodel.Map; +import javax.persistence.metamodel.Set; + +/** + * The interface Subquery 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. + */ + +public interface Subquery<T> extends AbstractQuery, Expression<T> { + + /** + * Return the query of which this is a subquery + * @return the enclosing query or subquery + */ + AbstractQuery getParent(); + + /** + * Specify the item that is to be returned in the query result. + * Replaces the previously specified selection, if any. + * @param expression expressions specifying the item that + * is returned in the query result + * @return the modified subquery + */ + Subquery<T> select(Expression<T> expression); + + //override the return type only: + + /** + * 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 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 AbstractQuery method. + * @param grouping zero or more grouping expressions + * @return the modified subquery + */ + Subquery<T> group(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 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 having(Predicate... restrictions); + + /** + * Specify the ordering expressions that are used to + * order the subquery 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. + * This method only overrides the return type of the + * corresponding AbstractQuery method. + * @param o zero or more ordering expressions + * @return the modified subquery. + */ + Subquery<T> order(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 subquery result or + * whether they must be retained + * @return the modified subquery. + */ + Subquery<T> distinct(boolean distinct); + + /** + * Return the selection expression + * @return the item to be returned in the subquery result + */ + Expression<T> getSelection(); + + /** + * Correlates a root of the enclosing query to a root of + * the subquery and returns the subquery root. + * @param parentRoot a root of the containing query + * @return subquery root + */ + <Y> Root<Y> correlate(Root<Y> parentRoot); + + /** + * Correlates a join of the enclosing query to a join of + * the subquery and returns the subquery join. + * @param parentJoin join target of the containing query + * @return subquery join + */ + <X, Y> Join<X, Y> correlate(Join<X, Y> parentJoin); + + /** + * Correlates a join to a Collection-valued association or + * element collection in the enclosing query to a join of + * the subquery and returns the subquery join. + * @param parentCollection join target of the containing query + * @return subquery join + */ + <X, Y> CollectionJoin<X, Y> correlate(CollectionJoin<X, Y> parentCollection); + + /** + * Correlates a join to a Set-valued association or + * element collection in the enclosing query to a join of + * the subquery and returns the subquery join. + * @param parentSet join target of the containing query + * @return subquery join + */ + <X, Y> SetJoin<X, Y> correlate(SetJoin<X, Y> parentSet); + + /** + * Correlates a join to a List-valued association or + * element collection in the enclosing query to a join of + * the subquery and returns the subquery join. + * @param parentList join target of the containing query + * @return subquery join + */ + <X, Y> ListJoin<X, Y> correlate(ListJoin<X, Y> parentList); + + /** + * Correlates a join to a Map-valued association or + * element collection in the enclosing query to a join of + * the subquery and returns the subquery join. + * @param parentMap join target of the containing query + * @return subquery join + */ + <X, K, V> MapJoin<X, K, V> correlate(MapJoin<X, K, V> parentMap); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/AbstractCollection.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/AbstractCollection.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/AbstractCollection.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,40 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type AbstractionCollection 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 + */ +public interface AbstractCollection<X, C, E> + extends Member<X, C>, Bindable<E> { + + public static enum CollectionType { + COLLECTION, SET, LIST, MAP + } + + public static enum Multiplicity { + MANY_TO_MANY, ONE_TO_MANY, ELEMENT_COLLECTION + } + + /** + * Return the collection type + * @return collection type + */ + CollectionType getCollectionType(); + + /** + * Return the multiplicity + * @return multiplicity + */ + Multiplicity getMultiplicity(); + + /** + * Return the type representing the element type of the + * collection. + * @return element type + */ + Type<E> getElementType(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Attribute.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Attribute.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Attribute.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,47 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Attribute represents persistent + * non-collection-valued properties or fields. + * + * @param <X> The represented type containing the attribute + * @param <T> The type of the represented attribute + */ +public interface Attribute<X, T> + extends Member<X, T>, Bindable<T> { + + public static enum Multiplicity { + MANY_TO_ONE, ONE_TO_ONE, EMBEDDED, BASIC + } + + /** + * Return the multiplicity of the attribute. + * @return multiplicity + */ + Multiplicity getMultiplicity(); + + /** + * Is the attribute an id attribute. + * @return boolean indicating whether or not an id + */ + boolean isId(); + + /** + * Is the attribute a version attribute. + * @return boolean indicating whether or not a version attribute + */ + boolean isVersion(); + + /** + * Can the attribute be null. + * @return boolean indicating whether or not the attribute can + * be null + */ + boolean isOptional(); + + /** + * Return the type that represents the type of the attribute. + * @return type of attribute + */ + Type<T> getAttributeType(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Basic.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Basic.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Basic.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,9 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Basic represent basic types (including + * temporal and enumerated types). + * + * @param <X> The type of the represented basic type + */ +public interface Basic<X> extends Type<X> {} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Bindable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Bindable.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Bindable.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,26 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Bindable represent object or attribute types + * that can be bound into the from clause. + * + * @param <T> The type of the represented object or attribute + */ +public interface Bindable<T> { + + public static enum BindableType { + ATTRIBUTE, COLLECTION, MANAGED_TYPE + } + + /** + * Return the bindable type of the represented object + * @return bindable type + */ + BindableType getBindableType(); + + /** + * Return the Java type of the represented object + * @return Java type + */ + Class<T> getJavaType(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Collection.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Collection.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Collection.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,11 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Collection represent persistent + * Collection-valued attributes. + * + * @param <X> The type the represented Collection belongs to + * @param <E> The element type of the represented Collection + */ +public interface Collection<X, E> + extends AbstractCollection<X, java.util.Collection<E>, E> {} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Embeddable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Embeddable.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Embeddable.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,8 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Embeddable represent embeddable types. + * + * @param <X> The represented type. + */ +public interface Embeddable<X> extends ManagedType<X> {} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Entity.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Entity.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Entity.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,21 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Entity represent entity types. + * + * @param <X> The represented entity type. + */ +public interface Entity<X> extends IdentifiableType<X> { + + /** + * Return the entity name + * @return entity name + */ + String getName(); + + /** + * Return the Java type of the entity's id. + * @return Java type of id + */ + Class<?> getIdJavaType(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/IdentifiableType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/IdentifiableType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/IdentifiableType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,63 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type IdentifiableType represent entity or + * mapped superclass types. + * + * @param <X> The represented entity or mapped superclass type. + */ +public interface IdentifiableType<X> extends ManagedType<X> { + + /** + * Return the attribute that corresponds to the id attribute of + * the entity or mapped superclass. + * @param type the type of the represented id attribute + * @return id attribute + * @throws IllegalArgumentException if id attribute of the given + * name and type is not present in the identifiable type + */ + <Y> Attribute<? super X, Y> getId(Class<Y> type); + + /** + * Return the attribute that corresponds to the version + * attribute + * of the entity or mapped superclass. + * @param type the type of the represented version attribute + * @return version attribute + * @throws IllegalArgumentException if version attribute of the + * given name and type is not present in the + * identifiable type + */ + <Y> Attribute<? super X, Y> getVersion(Class<Y> type); + + /** + * 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 + * @return declared id attribute + * @throws IllegalArgumentException if id attribute of the given + * name and type is not present in the identifiable type + */ + <Y> Attribute<X, Y> getDeclaredId(Class<Y> type); + + /** + * Return the attribute that corresponds to the version + * attribute declared by the entity or mapped superclass. + * @param type the type of the represented declared version + * attribute + * @return declared version attribute + * @throws IllegalArgumentException if version attribute of the + * given name and type is not present in the + * identifiable type + */ + <Y> Attribute<X, Y> getDeclaredVersion(Class<Y> type); + + /** + * Return the identifiable type that corresponds to the most + * specific mapped superclass or entity extended by the entity + * or mapped superclass. + * @return supertype of identifiable type + */ + IdentifiableType<? super X> getSupertype(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/List.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/List.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/List.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,11 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type List represent persistent List-valued + * attributes. + * + * @param <X> The type the represented List belongs to + * @param <E> The element type of the represented List + */ +public interface List<X, E> + extends AbstractCollection<X, java.util.List<E>, E> {} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/ManagedType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/ManagedType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/ManagedType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,184 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type ManagedType represent entity, mapped + * superclass, and embeddable types. + * + * @param <X> The represented type. + */ +public interface ManagedType<X> extends Type<X>, Bindable<X> { + /** + * Return the non-collection-valued attribute of the managed + * type that corresponds to the specified name in the + * represented type. + * @param name the name of the represented attribute + * @return non-collection attribute with the given name + */ + Attribute<? super X, ?> getAttribute(String name); + + /** + * Return the non-collection-valued attribute of the managed + * type that corresponds to the specified name and Java type + * in therepresented type. + * @param name the name of the represented attribute + * @param type the type of the represented attribute + * @return non-collection attribute with given name and type + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <Y> Attribute<? super X, Y> getAttribute(String name, + Class<Y> type); + + /** + * Return the declared non-collection-valued attribute of the + * managed type that corresponds to the specified name and Java + * in the represented type. + * @param name the name of the represented attribute + * @param type the type of the represented attribute + * @return declared non-collection attribute of the given + * name and type + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <Y> Attribute<X, Y> getDeclaredAttribute(String name, + Class<Y> type); + + /** + * Return the non-collection-valued attributes of the + * managed type. + * @return non-collection attributes + */ + java.util.Set<Attribute<? super X, ?>> getAttributes(); + + /** + * Return the non-collection-valued attributes declared by + * the managed type. + * @return declared non-collection attributes + */ + java.util.Set<Attribute<X, ?>> getDeclaredAttributes(); + + /** + * Return the Collection-valued attribute of the managed type + * that corresponds to the specified name and Java element type. + * @param name the name of the represented attribute + * @param elementType the element type of the represented + * attribute + * @return Collection attribute of the given name and element + * type + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <E> Collection<? super X, E> getCollection(String name, + Class<E> elementType); + + /** + * Return the Set-valued attribute of the managed type that + * corresponds to the specified name and Java element type. + * @param name the name of the represented attribute + * @param elementType the element type of the represented + * attribute + * @return Set attribute of the given name and element type + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <E> Set<? super X, E> getSet(String name, Class<E> elementType); + + /** + * Return the List-valued attribute of the managed type that + * corresponds to the specified name and Java element type. + * @param name the name of the represented attribute + * @param elementType the element type of the represented + * attribute + * @return List attribute of the given name and element type + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <E> List<? super X, E> getList(String name, Class<E> elementType); + + /** + * Return the Map-valued attribute of the managed type that + * corresponds to the specified name and Java key and value + * types. + * @param name the name of the represented attribute + * @param keyType the key type of the represented attribute + * @param valueType the value type of the represented attribute + * @return Map attribute of the given name and key and value + * types + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <K, V> Map<? super X, K, V> getMap(String name, + Class<K> keyType, + Class<V> valueType); + + /** + * Return the Collection-valued attribute declared by the + * managed type that corresponds to the specified name and Java + * element type. + * @param name the name of the represented attribute + * @param elementType the element type of the represented + * attribute + * @return declared Collection attribute of the given name and + * element type + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <E> Collection<X, E> getDeclaredCollection(String name, + Class<E> elementType); + + /** + * Return the Set-valued attribute declared by the managed type + * that corresponds to the specified name and Java element type. + * @param name the name of the represented attribute + * @param elementType the element type of the represented + * attribute + * @return declared Set attribute of the given name and + * element type + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <E> Set<X, E> getDeclaredSet(String name, Class<E> elementType); + + /** + * Return the List-valued attribute declared by the managed + * type that corresponds to the specified name and Java + * element type. + * @param name the name of the represented attribute + * @param elementType the element type of the represented + * attribute + * @return declared List attribute of the given name and + * element type + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <E> List<X, E> getDeclaredList(String name, Class<E> elementType); + + /** + * Return the Map-valued attribute declared by the managed + * type that corresponds to the specified name and Java key + * and value types. + * @param name the name of the represented attribute + * @param keyType the key type of the represented attribute + * @param valueType the value type of the represented attribute + * @return declared Map attribute of the given name and key + * and value types + * @throws IllegalArgumentException if attribute of the given + * name and type is not present in the managed type + */ + <K, V> Map<X, K, V> getDeclaredMap(String name, + Class<K> keyType, + Class<V> valueType); + + /** + * Return all collection-valued attributes of the managed type. + * @return collection valued attributes + */ + java.util.Set<AbstractCollection<? super X, ?, ?>> getCollections(); + + /** + * Return all collection-valued attributes declared by the + * managedtype. + * @return declared collection valued attributes + */ + java.util.Set<AbstractCollection<X, ?, ?>> getDeclaredCollections(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Map.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Map.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Map.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,24 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Map represent persistent Map-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 + */ +public interface Map<X, K, V> + extends AbstractCollection<X, java.util.Map<K, V>, V> { + /** + * Return the Java type of the map key. + * @return Java key type + */ + Class<K> getKeyJavaType(); + + /** + * Return the type representing the key type of the map. + * @return type representing key type + */ + Type<K> getKeyType(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/MappedSuperclass.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/MappedSuperclass.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/MappedSuperclass.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,9 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type MappedSuperclass represent mapped + * superclass types. + * + * @param <X> The represented entity type + */ +public interface MappedSuperclass<X> extends IdentifiableType<X> {} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Member.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Member.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Member.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,46 @@ +package javax.persistence.metamodel; + +/** + * A member of a Java type + * + * @param <X> The represented type that contains the member + * @param <Y> The type of the represented member + */ +public interface Member<X, Y> { + //String getName(); //TODO: do we need this? + // the java.lang.reflect.Member has it + + /** + * Return the managed type representing the type in which + * the member was declared. + * @return declaring type + */ + ManagedType<X> getDeclaringType(); + + /** + * Return the Java type of the represented member. + * @return Java type + */ + Class<Y> getMemberJavaType(); + + /** + * Return the java.lang.reflect.Member for the represented + * member. + * @return corresponding java.lang.reflect.Member + */ + java.lang.reflect.Member getJavaMember(); + + /** + * Is the member an association + * @return whether an association + */ + boolean isAssociation(); + + /** + * Is the member collection-valued + * @return whether a collection + */ + boolean isCollection(); + + //TODO: fetch type +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Metamodel.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Metamodel.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Metamodel.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,55 @@ +package javax.persistence.metamodel; + +/** + * Provides access to the metamodel of persistent + * entities in the persistence unit. + * + * @param <X> The type of the represented entity, mapped + * mapped superclass, or embeddable. + */ +public interface Metamodel { + + /** + * Return the metamodel entity representing the entity type. + * @param clazz the type of the represented entity + * @return the metamodel entity + * @throws IllegalArgumentException if not an entity + */ + <X> Entity<X> entity(Class<X> clazz); + + /** + * Return the metamodel managed type representing the + * entity, mapped superclass, or embeddable type. + * @param clazz the type of the represented managed class + * @return the metamodel managed type + * @throws IllegalArgumentException if not a managed class + */ + <X> ManagedType<X> type(Class<X> clazz); + + /** + * Return the metamodel embeddable type representing the + * embeddable type. + * @param clazz the type of the represented embeddable class + * @return the metamodel embeddable type + * @throws IllegalArgumentException if not an embeddable class + */ + <X> Embeddable<X> embeddable(Class<X> clazz); + + /** + * Return the metamodel managed types. + * @return the metamodel managed types + */ + java.util.Set<ManagedType<?>> getManagedTypes(); + + /** + * Return the metamodel entity types. + * @return the metamodel entity types + */ + java.util.Set<Entity<?>> getEntities(); + + /** + * Return the metamodel embeddable types. + * @return the metamodel embeddable types + */ + java.util.Set<Embeddable<?>> getEmbeddables(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Set.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Set.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Set.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,12 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Set represent persistent Set-valued + * attributes. + * + * @param <X> The type the represented Set belongs to + * @param <E> The element type of the represented Set + */ +public interface Set<X, E> + extends AbstractCollection<X, java.util.Set<E>, E> {} + Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/Type.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/Type.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/Type.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,26 @@ +package javax.persistence.metamodel; + +/** + * Instances of the type Type represent persistent object + * or attribute types. + * + * @param <X> The type of the represented object or attribute + */ +public interface Type<X> { + + public static enum PersistenceType { + ENTITY, EMBEDDABLE, MAPPED_SUPERCLASS, BASIC + } + + /** + * Return the persistence type + * @return persistence type + */ + PersistenceType getPersistenceType(); + + /** + * Return the represented Java type + * @return Java type + */ + Class<X> getJavaType(); +} Added: jpa-api/trunk/src/main/java/javax/jpa/metamodel/TypesafeMetamodel.java =================================================================== --- jpa-api/trunk/src/main/java/javax/jpa/metamodel/TypesafeMetamodel.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/jpa/metamodel/TypesafeMetamodel.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,18 @@ +package javax.persistence.metamodel; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * The TypesafeMetamodel annotation specifies that the class + * is a metamodel class that represents the entity, mapped + * superclass, or embeddable class designated by the value + * element. + */ +(a)Target(ElementType.TYPE) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface TypesafeMetamodel { + Class<?> value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/AssociationOverride.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AssociationOverride.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/AssociationOverride.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,34 @@ +//$Id:$ +//EJB3 Specification Copyright 2004-2006 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; + +/** + * 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. + * + * @author Emmanuel Bernard + */ +@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +public @interface AssociationOverride { + /** + * 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(); + + /** + * The join column that is being mapped to the persistent attribute. + */ + JoinColumn[] joinColumns(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/AssociationOverrides.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AssociationOverrides.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/AssociationOverrides.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,24 @@ +//$Id:$ +//EJB3 Specification Copyright 2004-2006 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; + +/** + * This annotation is used to override mappings of multiple many-to-one + * or one-to-one relationship properties or fields. + * + * @author Emmanuel Bernard + */ +@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +public @interface AssociationOverrides { + /** + * Mapping overrides of relationship properties or fields + */ + AssociationOverride[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/AttributeOverride.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AttributeOverride.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/AttributeOverride.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,34 @@ +//$Id: AttributeOverride.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Retention; +import java.lang.annotation.Target; + +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. + * + * 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. + * + * @author Emmanuel Bernard + */ +@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +public @interface AttributeOverride { + /** + * The name of the property whose mapping is being overridden if property-based access is being + * used, or the name of the field if field-based access is used. + */ + String name(); + /** + * The column that is being mapped to the persistent attribute + */ + Column column(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/AttributeOverrides.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/AttributeOverrides.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/AttributeOverrides.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,23 @@ +//$Id: AttributeOverrides.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Retention; +import java.lang.annotation.Target; + +import static java.lang.annotation.RetentionPolicy.*; +import static java.lang.annotation.ElementType.*; + + +/** + * Is used to override mappings of multiple properties or fields + * + * @author Emmanuel Bernard + */ +@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +public @interface AttributeOverrides { + /** + * One or more mapping override + */ + AttributeOverride[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/Basic.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Basic.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Basic.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,39 @@ +//$Id: Basic.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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; +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 use of the Basic annotation is optional for persistent fields and properties of these types. + + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface Basic { + /** + * Defines whether the value of the field or property should be lazily loaded or must be + * eagerly fetched. The EAGER strategy is a requirement on the persistence provider runtime + * that the value must be eagerly fetched. The LAZY strategy is a hint to the persistence + * provider runtime. If not specified, defaults to EAGER. + */ + FetchType fetch() default EAGER; + /** + * Defines whether the value of the field or property may be null. This is a hint and is + * disregarded for primitive types; it may be used in schema generation. If not specified, + * defaults to true. + */ + boolean optional() default true; +} Added: jpa-api/trunk/src/main/java/javax/persistence/CascadeType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/CascadeType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/CascadeType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,32 @@ +//$Id: CascadeType.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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}. + * + * @author Emmanuel Bernard + */ +public enum CascadeType { + /** + * Cascade all operations + */ + ALL, + /** + * Cascade persist operations + */ + PERSIST, + /** + * Cascade merge operations + */ + MERGE, + /** + * Cascade remove operations + */ + REMOVE, + /** + * Cascade refresh operations + */ + REFRESH +} Added: jpa-api/trunk/src/main/java/javax/persistence/Column.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Column.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Column.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,65 @@ +//$Id: Column.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * Is used to specify a mapped column for a persistent property or field. If no Column annotation is + * specified, the default values are applied. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface Column { + /** + * The name of the column. Defaults to the property or field name + */ + String name() default ""; + /** + * Whether the property is a unique key. This is a shortcut for the UniqueConstraint + * annotation at the table level and is useful for when the unique key constraint is + * only a single field. This constraint applies in addition to any constraint entailed + * by primary key mapping and to constraints specified at the table level. + */ + boolean unique() default false; + /** + * Whether the database column is nullable + */ + boolean nullable() default true; + /** + * Whether the column is included in SQL INSERT statements generated by the persistence provider. + */ + boolean insertable() default true; + /** + * Whether the column is included in SQL UPDATE statements generated by the persistence provider. + */ + boolean updatable() default true; + /** + * The SQL fragment that is used when generating the DDL for the column. + * Defaults to the generated SQL to create a column of the inferred type. + */ + String columnDefinition() default ""; + /** + * The name of the table that contains the column. If absent the column is assumed to + * be in the primary table. + */ + String table() default ""; + /** + * The column length. (Applies only if a string-valued column is used.) + */ + int length() default 255; + /** + * The precision for a decimal (exact numeric) column. (Applies only if a decimal column is used.) + * Value must be set by developer if used when generating the DDL for the column. + */ + int precision() default 0; + /** + * The scale for a decimal (exact numeric) column. (Applies only if a decimal column is used.) + */ + int scale() default 0; +} Added: jpa-api/trunk/src/main/java/javax/persistence/ColumnResult.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ColumnResult.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/ColumnResult.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,22 @@ +//$Id: ColumnResult.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +/** + * References name of a column in the SELECT clause of a SQL query - i.e., + * column alias, if applicable. Scalar result types can be included in the query + * result by specifying this annotation in the metadata. + * + * @author Emmanuel Bernard + */ +@Target({}) @Retention(RetentionPolicy.RUNTIME) +public @interface ColumnResult { + /** + * The name of a column in the SELECT clause of a SQL query + */ + String name(); +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorColumn.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorColumn.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,47 @@ +//$Id: DiscriminatorColumn.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.DiscriminatorType.STRING; + +/** + * Is used to define the discriminator column for the SINGLE_TABLE and JOINED 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 + * + * 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. + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface DiscriminatorColumn { + /** + * The name of column to be used for the discriminator. + */ + String name() default "DTYPE"; + /** + * The type of object/column to use as a class discriminator. + * Defaults to DiscriminatorType.STRING + */ + DiscriminatorType discriminatorType() default STRING; + /** + * The SQL fragment that is used when generating the DDL for the discriminator column. + * Defaults to the provider-generated SQL to create a column of the specified + * discriminator type. + */ + String columnDefinition() default ""; + /** + * The column length for String-based discriminator types. Ignored for other + * discriminator types. + */ + int length() default 31; +} Added: jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,23 @@ +//$Id: DiscriminatorType.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +/** + * Defines supported types of the discriminator column + * + * @author Emmanuel Bernard + */ +public enum DiscriminatorType { + /** + * String as the discriminator type + */ + STRING, + /** + * Single character as the discriminator type + */ + CHAR, + /** + * Integer as the discriminator type + */ + INTEGER +}; Added: jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorValue.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorValue.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/DiscriminatorValue.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,33 @@ +//$Id: DiscriminatorValue.java 11171 2007-02-08 03:40:51Z epbernard $ +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; + +/** + * 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. + * + * 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. + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface DiscriminatorValue { + /** + * The value that indicates that the row is an entity of the annotated entity type. + * + * If the DiscriminatorValue annotation is not specified and a discriminator column is used, + * a provider-specific function will be used to generate a value representing the entity type. + * If the DiscriminatorType is STRING, the discriminator value default is the entity name. + */ + String value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/Embeddable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Embeddable.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Embeddable.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,22 @@ +//$Id: Embeddable.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB Specification Copyright 2004 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.*; + + +/** + * 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. + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface Embeddable {} Added: jpa-api/trunk/src/main/java/javax/persistence/Embedded.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Embedded.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Embedded.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,18 @@ +//$Id: Embedded.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB Specification Copyright 2004 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.*; + +/** + * 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. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface Embedded {} Added: jpa-api/trunk/src/main/java/javax/persistence/EmbeddedId.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EmbeddedId.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EmbeddedId.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,19 @@ +//$Id: EmbeddedId.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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; + +/** + * 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 + */ +(a)Target({ElementType.METHOD, ElementType.FIELD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface EmbeddedId {} Added: jpa-api/trunk/src/main/java/javax/persistence/Entity.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Entity.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Entity.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,23 @@ +//$Id: Entity.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +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. + * + * @author Emmanuel Bernard + */ +@Target(TYPE) @Retention(RUNTIME) +public @interface Entity { + /** + * The name of an entity. Defaults to the unqualified name of the entity class. + * This name is used to refer to the entity in queries. The name must not be a + * reserved literal in the Java Persistence query language. + */ + String name() default ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/EntityExistsException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityExistsException.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityExistsException.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,45 @@ +//$Id: $ +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. + * + * @author Emmanuel Bernard + */ +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 EntityExistsException 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 ); + } +} Added: jpa-api/trunk/src/main/java/javax/persistence/EntityListeners.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityListeners.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityListeners.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,28 @@ +/* + * JBoss, the OpenSource J2EE webOS + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Specifies the callback listener classes to be used for an entity or mapped superclass. + * This annotation may be applied to an entity class or mapped superclass. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.TYPE}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface EntityListeners { + /** + * The callback listener classes + */ + Class[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,298 @@ +// $Id: EntityManager.java 11171 2007-02-08 03:40:51Z epbernard $ +package javax.persistence; + +/** + * Interface used to interact with the persistence context. + * + * An EntityManager 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. This interface + * defines the methods that are used to interact with the persistence context. The EntityManager API is + * used to create and remove persistent entity instances, to find entities by their primary key, and to + * query over entities. + * + * The set of entities that can be managed by a given EntityManager 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. + * + * @author Emmanuel Bernard + */ +public interface EntityManager { + /** + * Make an entity instance managed and persistent. + * + * @param entity + * @throws EntityExistsException 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 commit + * time.) + * @throws IllegalStateException if this EntityManager has been closed. + * @throws IllegalArgumentException if 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 instance that the state was merged to + * @throws IllegalStateException if this EntityManager has been closed + * @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); + + /** + * Remove the entity instance. + * + * @param entity + * @throws IllegalStateException if this EntityManager has been closed + * @throws IllegalArgumentException if not an entity + * or if 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); + + /** + * Find by primary key. + * + * @param entityClass + * @param primaryKey + * @return the found entity instance or null + * if the entity does not exist + * @throws IllegalStateException if this EntityManager has been closed + * @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 + */ + public <T> T find(Class<T> entityClass, Object primaryKey); + + /** + * 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 IllegalStateException if this EntityManager has been closed + * @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 + * @throws EntityNotFoundException if the entity state + * cannot be accessed + */ + public <T> T getReference(Class<T> entityClass, Object primaryKey); + + /** + * Synchronize the persistence context to the + * underlying database. + * + * @throws IllegalStateException if this EntityManager has been closed + * @throws TransactionRequiredException if there is + * no transaction + * @throws PersistenceException if the flush fails + */ + public void flush(); + + /** + * Set the flush mode that applies to all objects contained + * in the persistence context. + * + * @param flushMode + * @throws IllegalStateException if this EntityManager has been closed + */ + public void setFlushMode(FlushModeType flushMode); + + /** + * Get the flush mode that applies to all objects contained + * in the persistence context. + * + * @return flushMode + * @throws IllegalStateException if this EntityManager has been closed + */ + public FlushModeType getFlushMode(); + + /** + * Set the lock mode for an entity object contained + * in the persistence context. + * + * @param entity + * @param lockMode + * @throws IllegalStateException if this EntityManager has been closed + * @throws PersistenceException if an unsupported lock call + * is made + * @throws IllegalArgumentException if the instance is not + * an entity or is a detached entity + * @throws TransactionRequiredException if there is no + * transaction + */ + 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 IllegalStateException if this EntityManager has been closed + * @throws IllegalArgumentException if not an entity + * or 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); + + /** + * 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. + * + * @throws IllegalStateException if this EntityManager has been closed + */ + public void clear(); + + /** + * Check if the instance belongs to the current persistence + * context. + * + * @param entity + * @return <code>true</code> if the instance belongs to the current persistence context. + * @throws IllegalStateException if this EntityManager has been closed + * @throws IllegalArgumentException if not an entity + */ + public boolean contains(Object entity); + + /** + * Create an instance of Query for executing an + * EJB QL statement. + * + * @param ejbqlString an EJB QL query string + * @return the new query instance + * @throws IllegalStateException if this EntityManager has been closed + * @throws IllegalArgumentException if query string is not valid + */ + public Query createQuery(String ejbqlString); + + /** + * Create an instance of Query for executing a + * named query (in EJB QL or native SQL). + * + * @param name the name of a query defined in metadata + * @return the new query instance + * @throws IllegalStateException if this EntityManager has been closed + * @throws IllegalArgumentException if a query has not been + * defined with the given name + */ + public Query createNamedQuery(String name); + + /** + * 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 + * @throws IllegalStateException if this EntityManager has been closed + */ + 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 + * @throws IllegalStateException if this EntityManager has been closed + */ + 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 + * @throws IllegalStateException if this EntityManager has been closed + */ + 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 IllegalStateException if this EntityManager has been closed + * @throws TransactionRequiredException if there is + * no transaction. + */ + public void joinTransaction(); + + /** + * Return the underlying provider object for the EntityManager, if available. + * The result of this method is implementation specific + * + * @throws IllegalStateException if this EntityManager has been closed + */ + 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 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 or has been already closed + */ + public void close(); + + /** + * Determine whether the EntityManager is open. + * + * @return true until the EntityManager 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(); +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,49 @@ +//$Id: EntityManagerFactory.java 11171 2007-02-08 03:40:51Z epbernard $ +package javax.persistence; + +import java.util.Map; + +/** + * The EntityManagerFactory interface is used by the application to obtain an + * application-managed entity manager. 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 EntityManagerFactory has been + * closed, all its entity managers are considered to be in the closed state. + * + * @author Emmanuel Bernard + */ +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. + */ + 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. + */ + EntityManager createEntityManager(Map map); + + /** + * 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. + */ + void close(); + + /** + * Indicates whether or not this factory is open. Returns + * true until a call to close has been made. + */ + public boolean isOpen(); +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/EntityNotFoundException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityNotFoundException.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityNotFoundException.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,29 @@ +//$Id: EntityNotFoundException.java 11171 2007-02-08 03:40:51Z epbernard $ +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. + * + * @author Gavin King + */ +public class EntityNotFoundException extends PersistenceException { + /** + * Constructs a new EntityNotFoundException exception with null as its detail message. + */ + public EntityNotFoundException() { + super(); + } + + /** + * Constructs a new EntityNotFoundException exception with the specified detail message. + * + * @param message the detail message + */ + public EntityNotFoundException(String message) { + super( message ); + } + +} Added: jpa-api/trunk/src/main/java/javax/persistence/EntityResult.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityResult.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityResult.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,33 @@ +//$Id: EntityResult.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +/** + * 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. + * + * @author Emmanuel Bernard + */ +@Target({}) @Retention(RetentionPolicy.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 ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/EntityTransaction.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityTransaction.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityTransaction.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,60 @@ +//$Id: EntityTransaction.java 11171 2007-02-08 03:40:51Z epbernard $ +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(); +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/EnumType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EnumType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/EnumType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,19 @@ +//$Id: EnumType.java 11171 2007-02-08 03:40:51Z epbernard $ +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. + * + * @author Emmanuel Bernard + */ +public enum EnumType { + /** + * Persist enumerated type property or field as an integer + */ + ORDINAL, + /** + * Persist enumerated type property or field as a string + */ + STRING +} Added: jpa-api/trunk/src/main/java/javax/persistence/Enumerated.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Enumerated.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Enumerated.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,24 @@ +//$Id: Enumerated.java 11171 2007-02-08 03:40:51Z epbernard $ +package javax.persistence; + +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.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. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) +@Retention(RUNTIME) +public @interface Enumerated { + /** + * The type used in mapping an enum type + */ + EnumType value() default ORDINAL; +} Added: jpa-api/trunk/src/main/java/javax/persistence/ExcludeDefaultListeners.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ExcludeDefaultListeners.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/ExcludeDefaultListeners.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,17 @@ +//$Id: ExcludeDefaultListeners.java 11171 2007-02-08 03:40:51Z epbernard $ +package javax.persistence; + +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. + * + * @author Emmanuel Bernard + */ +@Target(TYPE) @Retention(RUNTIME) +public @interface ExcludeDefaultListeners { +} Added: jpa-api/trunk/src/main/java/javax/persistence/ExcludeSuperclassListeners.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ExcludeSuperclassListeners.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/ExcludeSuperclassListeners.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,17 @@ +//$Id: ExcludeSuperclassListeners.java 11171 2007-02-08 03:40:51Z epbernard $ +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; + +/** + * Specifies that the invocation of superclass listeners is to be excluded for the + * entity class (or mapped superclass) and its subclasses. + * + * @author Emmanuel Bernard + */ +@Target(TYPE) @Retention(RUNTIME) +public @interface ExcludeSuperclassListeners { +} Added: jpa-api/trunk/src/main/java/javax/persistence/FetchType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/FetchType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/FetchType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,24 @@ +//$Id: FetchType.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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. + * + * @author Emmanuel Bernard + */ +public enum FetchType { + /** + * Defines that data must be lazily fetched + */ + LAZY, + /** + * Defines that data must be eagerly fetched + */ + EAGER +}; Added: jpa-api/trunk/src/main/java/javax/persistence/FieldResult.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/FieldResult.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/FieldResult.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +//$Id: FieldResult.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Retention; +import java.lang.annotation.Target; +import java.lang.annotation.RetentionPolicy; + +/** + * 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 + */ +@Target({}) @Retention(RetentionPolicy.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(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/FlushModeType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/FlushModeType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/FlushModeType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,29 @@ +//$Id: FlushModeType.java 11171 2007-02-08 03:40:51Z epbernard $ +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. + * + * If there is no transaction active, the persistence provider must not flush to the database. + * + * @author Gavin King + */ +public enum FlushModeType { + /** + * Flushing must occur only at transaction commit + */ + COMMIT, + /** + * (Default) Flushing to occur at query execution + */ + AUTO +} Added: jpa-api/trunk/src/main/java/javax/persistence/GeneratedValue.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/GeneratedValue.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/GeneratedValue.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,32 @@ +//$Id: GeneratedValue.java 11171 2007-02-08 03:40:51Z epbernard $ +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; + +/** + * 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. + * + * @author Emmanuel Bernard + */ +@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 ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/GenerationType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/GenerationType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/GenerationType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,34 @@ +//$Id: GenerationType.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +/** + * Defines the types of primary key generation. + * + * @author Emmanuel Bernard + */ +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 +}; Added: jpa-api/trunk/src/main/java/javax/persistence/Id.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Id.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Id.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,18 @@ +//$Id: Id.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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; + + +/** + * Specifies the primary key property or field of an entity. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface Id {} Added: jpa-api/trunk/src/main/java/javax/persistence/IdClass.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/IdClass.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/IdClass.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,26 @@ +//$Id: IdClass.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +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. + * + * 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 + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface IdClass { + /** + * Primary key class + */ + Class value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/Inheritance.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Inheritance.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Inheritance.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,23 @@ +//$Id: Inheritance.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +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. + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface Inheritance { + /** + * The strategy to be used + */ + InheritanceType strategy() default SINGLE_TABLE; +} Added: jpa-api/trunk/src/main/java/javax/persistence/InheritanceType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/InheritanceType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/InheritanceType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +//$Id: InheritanceType.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +/** + * Defines inheritance strategy options. + * + * @author Emmanuel Bernard + */ +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 }; Added: jpa-api/trunk/src/main/java/javax/persistence/JoinColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/JoinColumn.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/JoinColumn.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,67 @@ +//$Id: JoinColumn.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * Is used to specify a mapped column for joining an entity association. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface JoinColumn { + /** + * The name of the foreign key column. + * The table in which it is found depends upon the context. If the join is for a OneToOne + * or Many- ToOne mapping, the foreign key column is in the table of the source entity. + * If the join is for a ManyToMany, the foreign key is in a join table. Default (only applies + * if a single join column is used): The concatenation of the following: the name of the referencing + * relationship property or field of the referencing entity; "_"; the name of the referenced primary + * key column. If there is no such referencing relationship property or field in the entity, the join + * column name is formed as the concatenation of the following: the name of the entity; "_"; the name + * of the referenced primary key column. + */ + String name() default ""; + /** + * The name of the column referenced by this foreign key column. When used with relationship mappings, + * the referenced column is in the table of the target entity. When used inside a JoinTable annotation, + * the referenced key column is in the entity table of the owning entity, or inverse entity if the join + * is part of the inverse join definition. Default (only applies if single join column is being used): + * The same name as the primary key column of the referenced table. + */ + String referencedColumnName() default ""; + /** + * Whether the property is a unique key. This is a shortcut for the UniqueConstraint annotation at the + * table level and is useful for when the unique key constraint is only a single field. It is not + * necessary to explicitly specify this for a join column that corresponds to a primary key that is part + * of a foreign key. + */ + boolean unique() default false; + /** + * Whether the foreign key column is nullable + */ + boolean nullable() default true; + /** + * Whether the column is included in SQL INSERT statements generated by the persistence provider + */ + boolean insertable() default true; + /** + * Whether the column is included in SQL UPDATE statements generated by the persistence provider + */ + boolean updatable() default true; + /** + * The SQL fragment that is used when generating the DDL for the column. + * Defaults to the generated SQL for the column. + */ + String columnDefinition() default ""; + /** + * The name of the table that contains the column. If a table is not specified, the column is + * assumed to be in the primary table of the applicable entity + */ + String table() default ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/JoinColumns.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/JoinColumns.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/JoinColumns.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,23 @@ +//$Id: JoinColumns.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * Defines mapping for the composite foreign keys. + * This annotation groups JoinColumn 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 + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface JoinColumns { + JoinColumn[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/JoinTable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/JoinTable.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/JoinTable.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,63 @@ +//$Id: JoinTable.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * 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. + * + * 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. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface JoinTable { + /** + * The name of the join table. + * + * Defaults to the concatenated names of the two associated primary entity tables, + * separated by an underscore + */ + String name() default ""; + /** + * The catalog of the table. + * + * Defaults to the default catalog. + */ + String catalog() default ""; + /** + * The schema of the table. + * + * Defaults to the default schema for user. + */ + String schema() default ""; + /** + * The foreign key columns of the join table which reference the primary table of the + * entity owning the association (i.e. the owning side of the association). + * + * Uses the same defaults as for JoinColumn. + */ + JoinColumn[] joinColumns() default {}; + /** + * The foreign key columns of the join table which reference the primary table of the entity + * that does not own the association (i.e. the inverse side of the association). + * + * Uses the same defaults as for JoinColumn + */ + JoinColumn[] inverseJoinColumns() default {}; + /** + * Unique constraints that are to be placed on the table. These are only used if table + * generation is in effect. + * + * Defaults to no additional constraints + */ + UniqueConstraint[] uniqueConstraints() default {}; +} Added: jpa-api/trunk/src/main/java/javax/persistence/Lob.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Lob.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Lob.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +//$Id: Lob.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import static java.lang.annotation.ElementType.METHOD; + +import static java.lang.annotation.ElementType.FIELD; + +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; + +/** + * Specifies that a persistent property or field should be persisted as a large object to a + * database-supported large object type. The Lob annotation may be used in conjunction with + * the Basic annotation. A Lob may be either a binary or character type. + * + * The Lob type is inferred from the type of the persistent field or property, and except + * for string and character-based types defaults to Blob. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface Lob {} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/LockModeType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/LockModeType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/LockModeType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,40 @@ +//$Id: LockModeType.java 11171 2007-02-08 03:40:51Z epbernard $ +package javax.persistence; + +/** + * Lock modes that can be specified by means of the EntityManager.lock() method. + * + * The semantics of requesting locks of type LockModeType.READ and LockModeType.WRITE are t + * he following. + * + * 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: + * + * * 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. + * + * * 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. + * + * 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. + * + * 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. + * + * @author Emmanuel Bernard + */ +public enum LockModeType { + /** + * Read lock + */ + READ, + /** + * Write lock + */ + WRITE +} Added: jpa-api/trunk/src/main/java/javax/persistence/ManyToMany.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ManyToMany.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/ManyToMany.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,51 @@ +//$Id: ManyToMany.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Retention; +import java.lang.annotation.Target; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; +import static javax.persistence.FetchType.*; + +/** + * Defines a many-valued association with many-to-many multiplicity. If the Collection is + * defined using generics to specify the element type, the associated target entity class + * does not need to be specified; otherwise it must be specified. + * + * Every many-to-many association has two sides, the owning side and the non-owning, or inverse, + * side. The join table is specified on the owning side. If the association is bidirectional, + * either side may be designated as the owning side. + * + * The same annotation elements for the OneToMany annotation apply to the ManyToMany annotation. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface ManyToMany { + /** + * The entity class that is the target of the association. Optional only if the + * collection property is defined using Java generics. Must be specified otherwise. + * + * Defaults to the parameterized type of the collection when defined using generics. + */ + Class targetEntity() default void.class; + /** + * The operations that must be cascaded to the target of the association. + * + * Defaults to no operations being cascaded. + */ + CascadeType[] cascade() default {}; + /** + * Whether the association should be lazily loaded or must be eagerly fetched. + * The EAGER strategy is a requirement on the persistenceprovider runtime that + * the associatedentities must be eagerly fetched. The LAZY strategy is a hint + * to the persistence provider runtime. + */ + FetchType fetch() default LAZY; + /** + * The field that owns the relationship. Required unless the relationship is unidirectional. + */ + String mappedBy() default ""; +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/ManyToOne.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/ManyToOne.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/ManyToOne.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,44 @@ +//$Id: ManyToOne.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * 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. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface ManyToOne { + /** + * The entity class that is the target of the association. + * + * Defaults to the type of the field or property that stores the association + */ + Class targetEntity() default void.class; + /** + * The operations that must be cascaded to the target of the association. + * + * By default no operations are cascaded. + */ + CascadeType[] cascade() default {}; + /** + * Whether the association should be lazily loaded or must be eagerly fetched. + * The EAGER strategy is a requirement on the persistence provider runtime that + * the associated entity must be eagerly fetched. The LAZY strategy is a hint to + * the persistence provider runtime. + */ + FetchType fetch() default EAGER; + /** + * Whether the association is optional. If set to false then a non-null relationship must always exist. + */ + boolean optional() default true; +} Added: jpa-api/trunk/src/main/java/javax/persistence/MapKey.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MapKey.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/MapKey.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +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; + +/** + * 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. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface MapKey { + /** + * The name of the persistent field or property of the associated entity that is used as the map key. + * If the name element is not specified, the primary key of the associated entity is used as the map key. + * If the primary key is a composite primary key and is mapped as IdClass, an instance of the primary key + * class is used as the key. + */ + String name() default ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/MappedSuperclass.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/MappedSuperclass.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/MappedSuperclass.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +//$Id: MappedSuperclass.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * 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 + */ +@Target(TYPE) @Retention(RUNTIME) +public @interface MappedSuperclass {} Added: jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQueries.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQueries.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQueries.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,21 @@ +//$Id: NamedNativeQueries.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +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 + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface NamedNativeQueries { + /** + * Array of native SQL named queries + */ + NamedNativeQuery [] value (); +} Added: jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQuery.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/NamedNativeQuery.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,39 @@ +//$Id: NamedNativeQuery.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import static java.lang.annotation.ElementType.*; +import java.lang.annotation.Retention; +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. + * + * @author Emmanuel Bernard + */ +@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 +} Added: jpa-api/trunk/src/main/java/javax/persistence/NamedQueries.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NamedQueries.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/NamedQueries.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,21 @@ +//$Id: NamedQueries.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +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. + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface NamedQueries { + /** + * An array of named Java Persistence query language queries. + */ + NamedQuery [] value (); +} Added: jpa-api/trunk/src/main/java/javax/persistence/NamedQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NamedQuery.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/NamedQuery.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,31 @@ +//$Id: NamedQuery.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import java.lang.annotation.Retention; +import java.lang.annotation.Target; +import static java.lang.annotation.RetentionPolicy.*; +import static java.lang.annotation.ElementType.*; + +/** + * 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. + * + * @author Emmanuel Bernard + */ +//TODO remove the mackage target +@Target({TYPE}) @Retention(RUNTIME) +public @interface NamedQuery { + /** + * Refers to the query when using the EntityManager methods that create query objects. + */ + String name(); + /** + * The query string in the Java Persistence query language + */ + String query(); + /** + * Vendor-specific query hints + */ + QueryHint[] hints() default {}; +} Added: jpa-api/trunk/src/main/java/javax/persistence/NoResultException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NoResultException.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/NoResultException.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,27 @@ +//$Id: NoResultException.java 11171 2007-02-08 03:40:51Z epbernard $ +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 + */ +public class NoResultException extends PersistenceException { + + /** + * Constructs a new NoResultException exception with null as its detail message + */ + public NoResultException() { + super(); + } + + /** + * Constructs a new NoResultException exception with the specified detail message. + * + * @param message + */ + public NoResultException(String message) { + super( message ); + } +} Added: jpa-api/trunk/src/main/java/javax/persistence/NonUniqueResultException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/NonUniqueResultException.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/NonUniqueResultException.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,29 @@ +//$Id: NonUniqueResultException.java 11171 2007-02-08 03:40:51Z epbernard $ +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. + * + * @author Gavin King + */ +public class NonUniqueResultException extends PersistenceException { + + /** + * Constructs a new NonUniqueResultException exception with null as its detail message + */ + public NonUniqueResultException() { + super(); + } + + /** + * Constructs a new NonUniqueResultException exception with the specified detail message + * + * @param message + */ + public NonUniqueResultException(String message) { + super( message ); + } + +} Added: jpa-api/trunk/src/main/java/javax/persistence/OneToMany.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OneToMany.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/OneToMany.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,47 @@ +//$Id: OneToMany.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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 one-to-many multiplicity. + * + * 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. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface OneToMany { + /** + * The entity class that is the target of the association. Optional only if the collection + * property is defined using Java generics. Must be specified otherwise. + * + * Defaults to the parameterized type of the collection when defined using generics. + */ + Class targetEntity() default void.class; + /** + * The operations that must be cascaded to the target of the association. + * + * Defaults to no operations being cascaded. + */ + CascadeType[] cascade() default {}; + /** + * Whether the association should be lazily loaded or must be eagerly fetched. + * The EAGER strategy is a requirement on the persistenceprovider runtime that the + * associatedentities must be eagerly fetched. The LAZY strategy is a hint to the + * persistence provider runtime. + */ + FetchType fetch() default LAZY; + /** + * The field that owns the relationship. Required unless the relationship is unidirectional. + */ + String mappedBy() default ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/OneToOne.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OneToOne.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/OneToOne.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,51 @@ +//$Id: OneToOne.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * 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. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface OneToOne { + /** + * The entity class that is the target of the association. + * + * Defaults to the type of the field or property that stores the association. + */ + Class targetEntity() default void.class; + /** + * The operations that must be cascaded to the target of the association. + * + * By default no operations are cascaded. + */ + CascadeType[] cascade() default {}; + /** + * Whether the association should be lazily loaded or must be eagerly fetched. + * The EAGER strategy is a requirement on the persistence provider runtime that + * the associated entity must be eagerly fetched. The LAZY strategy is a hint to + * the persistence provider runtime. + */ + FetchType fetch() default EAGER; + /** + * Whether the association is optional. If set to false then a non-null relationship must + * always exist. + */ + boolean optional() default true; + /** + * The field that owns the relationship. This element is only specified on the + * inverse (non-owning) side of the association. + */ + String mappedBy() default ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/OptimisticLockException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OptimisticLockException.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/OptimisticLockException.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,42 @@ +//$Id: $ +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. + * + * @author Emmanuel Bernard + */ +public class OptimisticLockException extends PersistenceException { + private Object entity; + + public OptimisticLockException() { + super(); + } + + public OptimisticLockException(Object entity) { + this.entity = entity; + } + + public OptimisticLockException(Throwable cause) { + super( cause ); + } + + public OptimisticLockException(String message) { + super( message ); + } + + public OptimisticLockException(String message, Throwable cause) { + super( message, cause ); + } + + public OptimisticLockException(String message, Throwable cause, Object entity) { + super( message, cause ); + this.entity = entity; + } + + public Object getEntity() { + return entity; + } +} Added: jpa-api/trunk/src/main/java/javax/persistence/OrderBy.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/OrderBy.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/OrderBy.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,39 @@ +//$Id: OrderBy.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * This annotation specifies the ordering of the elements of a collection valued association at the + * point when the association 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> + * + * If ASC or DESC is not specified, ASC (ascending order) is assumed. + * + * If the ordering element is not specified, ordering by the primary key of the associated + * entity 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. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface OrderBy { + /** + * An orderby_list, specified as follows: + * orderby_list::= orderby_item [,orderby_item]* orderby_item::= property_or_field_name [ASC | DESC] + * + * If ASC or DESC is not specified, ASC (ascending order) is assumed. + * + */ + String value() default ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/Persistence.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Persistence.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Persistence.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,110 @@ +// $Id: Persistence.java 11171 2007-02-08 03:40:51Z epbernard $ +package javax.persistence; + +import java.io.BufferedReader; +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.net.URL; +import java.util.Enumeration; +import java.util.HashSet; +import java.util.Map; +import java.util.Set; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import javax.persistence.spi.PersistenceProvider; + +/** + * Bootstrap class that provides access to an EntityManagerFactory. + */ +public class Persistence { + + public static String PERSISTENCE_PROVIDER = PersistenceProvider.class.getName(); + + protected static final Set<PersistenceProvider> providers = new HashSet<PersistenceProvider>(); + + /** + * Create and return an EntityManagerFactory for the named persistence unit. + * + * @param persistenceUnitName The name of the persistence unit + * @return The factory that creates EntityManagers configured according to the specified persistence unit + */ + public static EntityManagerFactory createEntityManagerFactory(String persistenceUnitName) { + return createEntityManagerFactory( persistenceUnitName, null ); + } + + /** + * Create and return an EntityManagerFactory for the named persistence unit using the given properties. + * + * @param persistenceUnitName The name of the persistence unit + * @param properties Additional properties to use when creating the factory. The values of these properties override + * any values that may have been configured elsewhere + * @return The factory that creates EntityManagers configured according to the specified persistence unit + */ + public static EntityManagerFactory createEntityManagerFactory(String persistenceUnitName, Map properties) { + EntityManagerFactory emf = null; + + if ( providers.size() == 0 ) { + findAllProviders(); + } + for ( PersistenceProvider provider : providers ) { + emf = provider.createEntityManagerFactory( persistenceUnitName, properties ); + if ( emf != null ) break; + } + if ( emf == null ) { + throw new PersistenceException( "No Persistence provider for EntityManager named " + persistenceUnitName ); + } + return emf; + } + + // Helper methods + + private static void findAllProviders() { + try { + ClassLoader loader = Thread.currentThread().getContextClassLoader(); + Enumeration<URL> resources = loader.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(); + } + } + for ( String s : names ) { + Class providerClass = loader.loadClass( s ); + providers.add( (PersistenceProvider) providerClass.newInstance() ); + } + } + catch (IOException e) { + throw new PersistenceException( e ); + } + catch (InstantiationException e) { + throw new PersistenceException( e ); + } + catch (IllegalAccessException e) { + throw new PersistenceException( e ); + } + catch (ClassNotFoundException e) { + throw new PersistenceException( e ); + } + } + + private static final Pattern nonCommentPattern = Pattern.compile( "^([^#]+)" ); + + private static Set<String> providerNamesFromReader(BufferedReader reader) throws IOException { + Set<String> names = new HashSet<String>(); + String line; + while ( ( line = reader.readLine() ) != null ) { + line = line.trim(); + Matcher m = nonCommentPattern.matcher( line ); + if ( m.find() ) { + names.add( m.group().trim() ); + } + } + return names; + } +} Added: jpa-api/trunk/src/main/java/javax/persistence/PersistenceContext.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceContext.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceContext.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,43 @@ +/* $Id: PersistenceContext.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Expresses a dependency on an EntityManager persistence context. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) +(a)Retention(RetentionPolicy.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; +} Added: jpa-api/trunk/src/main/java/javax/persistence/PersistenceContextType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceContextType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceContextType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,18 @@ +//$Id: PersistenceContextType.java 11171 2007-02-08 03:40:51Z epbernard $ +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. + */ +public enum PersistenceContextType { + /** + * Transaction-scoped persistence context + */ + TRANSACTION, + /** + * Extended persistence context + */ + EXTENDED +} Added: jpa-api/trunk/src/main/java/javax/persistence/PersistenceContexts.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceContexts.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceContexts.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,27 @@ +/* $Id: PersistenceContexts.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +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. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.TYPE}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PersistenceContexts { + /** + * One or more persistence context + */ + PersistenceContext[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/PersistenceException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceException.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceException.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,50 @@ +/* $Id: PersistenceException.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss, Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ +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. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +public class PersistenceException extends RuntimeException { + /** + * Constructs a new PersistenceException exception with null as its detail message. + */ + public PersistenceException() { + } + + /** + * Constructs a new PersistenceException exception with the specified 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 + * + * @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 + * + * @param cause the cause + */ + public PersistenceException(Throwable cause) { + super( cause ); + } +} Added: jpa-api/trunk/src/main/java/javax/persistence/PersistenceProperty.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceProperty.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceProperty.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,27 @@ +//$Id: $ +package javax.persistence; + +import java.lang.annotation.Retention; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import java.lang.annotation.Target; + +/** + * Describes a single container or persistence provider property. + * Vendor specific properties may be included in the set of properties, and are passed to the persistence + * provider by the container when the entity manager is created. + * Properties that are not recognized by a vendor will be ignored. + * + * @author Emmanuel Bernard + */ +@Target({}) +@Retention(RUNTIME) +public @interface PersistenceProperty { + /** + * The name of the property + */ + String name(); + /** + * The value of the property + */ + String value(); +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnit.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnit.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnit.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,33 @@ +/* $Id: PersistenceUnit.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Expresses a dependency on an EntityManagerFactory. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) +(a)Retention(RetentionPolicy.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. + */ + 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. + */ + String unitName() default ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnits.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnits.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnits.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,26 @@ +/* $Id: PersistenceUnits.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Declares one or more PersistenceUnit annotations + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.TYPE}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PersistenceUnits { + /** + * One or more PersistenceUnit annotations + */ + PersistenceUnit[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/PostLoad.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PostLoad.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PostLoad.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,24 @@ +/* $Id: PostLoad.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied to + * methods of an entity class, a mapped superclass, or a callback listener class. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.METHOD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PostLoad { +} Added: jpa-api/trunk/src/main/java/javax/persistence/PostPersist.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PostPersist.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PostPersist.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +/* $Id: PostPersist.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ + +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be + * applied to methods of an entity class, a mapped superclass, or a callback listener class. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.METHOD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PostPersist { +} Added: jpa-api/trunk/src/main/java/javax/persistence/PostRemove.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PostRemove.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PostRemove.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +/* $Id: PostRemove.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ + +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied + * to methods of an entity class, a mapped superclass, or a callback listener class. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.METHOD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PostRemove { +} Added: jpa-api/trunk/src/main/java/javax/persistence/PostUpdate.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PostUpdate.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PostUpdate.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +/* $Id: PostUpdate.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ + +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied to + * methods of an entity class, a mapped superclass, or a callback listener class. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.METHOD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PostUpdate { +} Added: jpa-api/trunk/src/main/java/javax/persistence/PrePersist.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PrePersist.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PrePersist.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +/* $Id: PrePersist.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ + +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied + * to methods of an entity class, a mapped superclass, or a callback listener class. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.METHOD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PrePersist { +} Added: jpa-api/trunk/src/main/java/javax/persistence/PreRemove.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PreRemove.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PreRemove.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +/* $Id: PreRemove.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ + +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be applied + * to methods of an entity class, a mapped superclass, or a callback listener class. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.METHOD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PreRemove { +} Added: jpa-api/trunk/src/main/java/javax/persistence/PreUpdate.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PreUpdate.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PreUpdate.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +/* $Id: PreUpdate.java 11171 2007-02-08 03:40:51Z epbernard $ + * JBoss Inc + * + * Distributable under LGPL license. + * See terms of license at gnu.org. + */ + +package javax.persistence; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Is used to specify callback methods for the corresponding lifecycle event. This annotation may be + * applied to methods of an entity class, a mapped superclass, or a callback listener class. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +(a)Target({ElementType.METHOD}) +(a)Retention(RetentionPolicy.RUNTIME) +public @interface PreUpdate { +} Added: jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumn.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumn.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumn.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,53 @@ +//$Id: PrimaryKeyJoinColumn.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * This annotation specifies a primary key column that is used as a foreign key to join to another + * table. + * + * 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. + * + * 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 + * + * @author Emmanuel Bernard + */ +@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +public @interface PrimaryKeyJoinColumn { + /** + * The name of the primary key column of the current table. + * + * Defaults to the same name as the primary key column of the primary table of the + * superclass (JOINED mapping strategy); the same name as the primary key column of + * the primary table (SecondaryTable mapping); or the same name as the primary key + * column for the table for the referencing entity (OneToOne mapping) + */ + 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) + */ + 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. + * + * Defaults to the generated SQL to create a column of the inferred type. + */ + String columnDefinition() default ""; +} Added: jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumns.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumns.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PrimaryKeyJoinColumns.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,22 @@ +//$Id: PrimaryKeyJoinColumns.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * This annotation groups PrimaryKeyJoinColumn annotations. It is used to map composite foreign keys. + * + * @author Emmanuel Bernard + */ +@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +public @interface PrimaryKeyJoinColumns { + /** + * One or more PrimaryKeyJoinColumn annotations + */ + PrimaryKeyJoinColumn[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/Query.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Query.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Query.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,148 @@ +// $Id: Query.java 11225 2007-02-20 20:55:29Z epbernard $ +package javax.persistence; + +import java.util.Calendar; +import java.util.Date; +import java.util.List; + + +/** + * Interface used to control query execution. + */ +public interface Query +{ + /** + * Execute the query and return the query results as a List. + * + * @return a list of the results + * @throws IllegalStateException f called for a Java Persistence query language UPDATE or DELETE statement + */ + public List 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 + */ + public 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 + * @throws TransactionRequiredException if there is no transaction + */ + public int executeUpdate(); + + /** + * Set the maximum number of results to retrieve. + * + * @param maxResult + * @return the same query instance + * @throws IllegalArgumentException if argument is negative + */ + public Query 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 + */ + public Query setFirstResult(int startPosition); + + /** + * Set an implementation-specific hint. If the hint name is not recognized, it is silently + * ignored. + * + * @param hintName + * @param value + * @return the same query instance + * @throws IllegalArgumentException if the second argument is not valid for the implementation + */ + public Query setHint(String hintName, 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 parameter in query + * string or argument is of incorrect type + */ + public Query setParameter(String name, Object value); + + /** + * 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 parameter in query + * string + */ + public Query 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 parameter in query + * string + */ + public Query setParameter(String name, Calendar value, TemporalType temporalType); + + /** + * Bind an argument to a positional parameter. + * + * @param position + * @param value + * @return the same query instance + * @throws IllegalArgumentException if position does not correspond to positional parameter of + * query or argument is of incorrect type + */ + public Query setParameter(int position, Object value); + + /** + * 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 positional parameter of + * query + */ + public Query 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 } correspond to positional parameter of query + */ + public Query 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 + */ + public Query setFlushMode(FlushModeType flushMode); + +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/QueryHint.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/QueryHint.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/QueryHint.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,25 @@ +//$Id: QueryHint.java 11171 2007-02-08 03:40:51Z epbernard $ +package javax.persistence; + +import java.lang.annotation.Retention; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import java.lang.annotation.Target; + +/** + * An implementation-specific Query hint + * + * @author Emmanuel Bernard + */ +@Target({}) +@Retention(RUNTIME) +public @interface QueryHint { + /** + * Name of the hint + */ + String name(); + + /** + * Value of the hint + */ + String value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/RollbackException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/RollbackException.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/RollbackException.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,44 @@ +//$Id: $ +package javax.persistence; + +/** + * Thrown by the persistence provider when the EntityTransaction.commit() fails + * + * @author Emmanuel Bernard + */ +public class RollbackException extends PersistenceException { + /** + * Constructs a new RollbackException exception with null as its detail message + */ + public RollbackException() { + super(); + } + + /** + * Constructs a new RollbackException exception with the specified cause + * + * @param cause The detail cause + */ + public RollbackException(Throwable cause) { + super( cause ); + } + + /** + * Constructs a new RollbackException exception with the specified detail message + * + * @param message The detail message + */ + public RollbackException(String message) { + super( message ); + } + + /** + * Constructs a new RollbackException exception with the specified detail message and cause + * + * @param message The detail message + * @param cause The detail cause + */ + public RollbackException(String message, Throwable cause) { + super( message, cause ); + } +} Added: jpa-api/trunk/src/main/java/javax/persistence/SecondaryTable.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SecondaryTable.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/SecondaryTable.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,53 @@ +//$Id: SecondaryTable.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * 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. + * + * 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. + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface SecondaryTable { + /** + * The name of the table + */ + String name(); + /** + * The catalog of the table + */ + String catalog() default ""; + /** + * The schema of the table + */ + 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 + */ + 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. + */ + UniqueConstraint[] uniqueConstraints() default {}; +} Added: jpa-api/trunk/src/main/java/javax/persistence/SecondaryTables.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SecondaryTables.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/SecondaryTables.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,21 @@ +//$Id: SecondaryTables.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; +/** + * This annotation is used to specify multiple secondary tables for an entity. + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface SecondaryTables { + /** + * The secondary tables for an entity. + */ + SecondaryTable[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/SequenceGenerator.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SequenceGenerator.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/SequenceGenerator.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,38 @@ +//$Id: SequenceGenerator.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * 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). + * + * @author Emmanuel Bernard + */ +@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) +public @interface SequenceGenerator { + /** + * A unique generator name that can be referenced by one or more classes to be the generator for primary key values + */ + String name(); + /** + * The name of the database sequence object from which to obtain primary key values + * Defaults to a provider-chosen value + */ + String sequenceName() default ""; + /** + * 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 + */ + int allocationSize() default 50; +} Added: jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMapping.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMapping.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMapping.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,29 @@ +//$Id: SqlResultSetMapping.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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; + +/** + * This annotation is used to specify the mapping of the result of a native SQL query + * + * @author Emmanuel Bernard + */ +(a)Target({ElementType.TYPE}) @Retention(RetentionPolicy.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 + */ + String name(); + /** + * Specifies the result set mapping to entities + */ + EntityResult[] entities() default {}; + /** + * Specifies the result set mapping to scalar values + */ + ColumnResult[] columns() default {}; +} Added: jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMappings.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMappings.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/SqlResultSetMappings.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,19 @@ +//$Id: SqlResultSetMapping.java 9044 2006-01-12 20:58:41 -0500 (jeu., 12 janv. 2006) epbernard $ +//EJB3 Specification Copyright 2004 - 2006 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; + +/** + * This annotation is used to define one or more SqlResultSetMapping + * + * @author Emmanuel Bernard + */ +(a)Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) +public @interface SqlResultSetMappings { + SqlResultSetMapping[] value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/Table.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Table.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Table.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,48 @@ +//$Id: Table.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * This annotation specifies the primary table for the annotated entity. Additional + * tables may be specified using SecondaryTable or SecondaryTables annotation. + * + * If no Table annotation is specified for an entity class, the default values apply. + * + * @author Emmanuel Bernard + */ +@Target({TYPE}) @Retention(RUNTIME) +public @interface Table { + /** + * The name of the table. + * + * Defaults to the entity name. + */ + 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 ""; + /** + * 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. + * + * Defaults to no additional constraints. + */ + UniqueConstraint[] uniqueConstraints() default {}; +} Added: jpa-api/trunk/src/main/java/javax/persistence/TableGenerator.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TableGenerator.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/TableGenerator.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,67 @@ +//$Id: TableGenerator.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +import static java.lang.annotation.ElementType.*; +import java.lang.annotation.Retention; +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). + * + * @author Emmanuel Bernard + */ +@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 + */ + String name(); + /** + * Name of table that stores the generated id values. Defaults to a name chosen by persistence provider. + */ + String table() 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 ""; + /** + * Name of the primary key column in the table + * 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 + */ + 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 + */ + String pkColumnValue() default ""; + /** + * The initial value to be used when allocating id numbers from the generator + */ + int initialValue() default 0; + /** + * 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 + */ + UniqueConstraint[] uniqueConstraints() default {}; +} Added: jpa-api/trunk/src/main/java/javax/persistence/Temporal.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Temporal.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Temporal.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,26 @@ +//$Id: Temporal.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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; + +/** + * 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. + * + * The Temporal annotation may be used in conjunction with the Basic annotation. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) +@Retention(RUNTIME) +public @interface Temporal { + /** + * The type used in mapping java.util.Date or java.util.Calendar + */ + TemporalType value(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/TemporalType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TemporalType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/TemporalType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,21 @@ +//$Id: TemporalType.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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 +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/TransactionRequiredException.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TransactionRequiredException.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/TransactionRequiredException.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,26 @@ +//$Id: TransactionRequiredException.java 11171 2007-02-08 03:40:51Z epbernard $ +package javax.persistence; + +/** + * Thrown by the persistence provider when a transaction is required but is not active. + * @author Gavin King + */ +public class TransactionRequiredException extends PersistenceException { + + /** + * Constructs a new TransactionRequiredException exception with null as its detail message + */ + public TransactionRequiredException() { + super(); + } + + /** + * Constructs a new TransactionRequiredException exception with the specified detail message + * + * @param message + */ + public TransactionRequiredException(String message) { + super( message ); + } + +} Added: jpa-api/trunk/src/main/java/javax/persistence/Transient.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Transient.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Transient.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,18 @@ +//$Id: Transient.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * 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 + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface Transient {} Added: jpa-api/trunk/src/main/java/javax/persistence/UniqueConstraint.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/UniqueConstraint.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/UniqueConstraint.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,21 @@ +//$Id: UniqueConstraint.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence; + +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 + * + * @author Emmanuel Bernard + */ +@Target({}) @Retention(RUNTIME) +public @interface UniqueConstraint { + /** + * An array of the column names that make up the constraint + */ + String[] columnNames(); +} Added: jpa-api/trunk/src/main/java/javax/persistence/Version.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Version.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/Version.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,28 @@ +//$Id: Version.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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.*; + +/** + * 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. + * + * 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. + * + * 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. + * + * The following types are supported for version properties: int, Integer, short, Short, long, + * Long, Timestamp. + * + * @author Emmanuel Bernard + */ +@Target({METHOD, FIELD}) @Retention(RUNTIME) +public @interface Version {} Added: jpa-api/trunk/src/main/java/javax/persistence/package-info.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/package-info.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/package-info.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,9 @@ +//$Id:$ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. + +/** + * The javax.persistence package contains the classes and interfaces that define the contracts + * between a persistence provider and the managed classes and the clients of the Java Persistence API. + */ +package javax.persistence; + Added: jpa-api/trunk/src/main/java/javax/persistence/spi/ClassTransformer.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/ClassTransformer.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/ClassTransformer.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,39 @@ +//$Id: ClassTransformer.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence.spi; + +import java.security.ProtectionDomain; +import java.lang.instrument.IllegalClassFormatException; + +/** + * A persistence provider provides an instance of this interface + * to the PersistenceUnitInfo.addTransformer method. + * The supplied transformer instance will get called to transform + * entity class files when they are loaded and redefined. The transformation + * occurs before the class is defined by the JVM + * + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + * @version $Revision: 11171 $ + */ +public interface ClassTransformer +{ + /** + * Invoked when a class is being loaded or redefined to add hooks for persistence bytecode manipulation + * + * @param loader the defining class loaderof the class being transformed. It may be null if using bootstrap loader + * @param classname The name of the class being transformed + * @param classBeingRedefined If an already loaded class is being redefined, then pass this as a parameter + * @param protectionDomain ProtectionDomain of the class being (re)-defined + * @param classfileBuffer The input byte buffer in class file format + * @return A well-formed class file that can be loaded + * + * @throws IllegalClassFormatException + */ + byte[] transform(ClassLoader loader, + String classname, + Class<?> classBeingRedefined, + ProtectionDomain protectionDomain, + byte[] classfileBuffer) + throws IllegalClassFormatException; +} Added: jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProvider.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProvider.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceProvider.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,43 @@ +//$Id: PersistenceProvider.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. +package javax.persistence.spi; + +import java.util.Map; +import javax.persistence.EntityManagerFactory; + +/** + * Interface implemented by the persistence provider. + * This interface is used to create an EntityManagerFactory. + * It is invoked by the container in Java EE environments and + * by the Persistence class in Java SE environments. + */ +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). + * @return EntityManagerFactory for the persistence unit + * specified by the metadata + */ + public EntityManagerFactory createContainerEntityManagerFactory(PersistenceUnitInfo info, Map map); +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitInfo.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitInfo.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitInfo.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,142 @@ +//$Id: PersistenceUnitInfo.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc.package javax.persistence.spi; +package javax.persistence.spi; + +import java.net.URL; +import java.util.List; +import java.util.Properties; +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> element 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 named <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(); + + /** + * @return The list of JAR file URLs that the persistence + * provider must examine for managed classes of the persistence + * unit. Each jar file URL corresponds to a named <jar-file> + * element in the persistence.xml file. + */ + public List<URL> getJarFileUrls(); + + /** + * @return 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.) + */ + 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 named <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 Properties object. Each property corresponds + * to a <property> element in the persistence.xml file + */ + public Properties getProperties(); + + /** + * @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 + * PersistenceInfo.getClassLoader method. The transformer + * has no effect on the result returned by the + * PersistenceInfo.getTempClassLoader 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 + * PersistenceInfo.getClassLoader. None of the classes loaded + * by this class loader will be visible to application + * components. The container does not use or maintain references + * to this class loader after returning it to the provider. + * + * @return Temporary ClassLoader with same visibility as current + * loader + */ + public ClassLoader getNewTempClassLoader(); +} \ No newline at end of file Added: jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitTransactionType.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitTransactionType.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/PersistenceUnitTransactionType.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,20 @@ +//$Id: PersistenceUnitTransactionType.java 11171 2007-02-08 03:40:51Z epbernard $ +//EJB3 Specification Copyright 2004-2006 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. + * + * @author <a href="mailto:bill@jboss.org">Bill Burke</a> + */ +public enum PersistenceUnitTransactionType { + /** + * JTA entity manager + */ + JTA, + /** + * Resource-local entity manager + */ + RESOURCE_LOCAL +} Added: jpa-api/trunk/src/main/java/javax/persistence/spi/package-info.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/spi/package-info.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/spi/package-info.java 2009-03-08 19:48:33 UTC (rev 16112) @@ -0,0 +1,10 @@ +//$Id:$ +//EJB3 Specification Copyright 2004-2006 Sun Microsystems, Inc. + +/** + * The javax.persistence.spi package defines the classes and interfaces that are implemented by the + * persistence provider and the Java EE container for use by the container, provider, and/or Persistence + * bootstrap class in deployment and bootstrapping. + */ +package javax.persistence.spi; +