Jakarta Persistence

Italic serif font

Specification: Jakarta Persistence

Version: 3.2

Status: Final Release

Release: April 10, 2024
T getProperty()

void setProperty(T t)
@Entity
public class Customer implements Serializable {
    private Long id;
    private String name;
    private Address address;
    private Collection<Order> orders = new HashSet();
    private Set<PhoneNumber> phones = new HashSet();

    // No-arg constructor
    public Customer() {}

    @Id // property access is used
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Address getAddress() {
        return address;
    }

    public void setAddress(Address address) {
        this.address = address;
    }

    @OneToMany
    public Collection<Order> getOrders() {
        return orders;
    }

    public void setOrders(Collection<Order> orders) {
        this.orders = orders;
    }

    @ManyToMany
    public Set<PhoneNumber> getPhones() {
        return phones;
    }

    public void setPhones(Set<PhoneNumber> phones) {
        this.phones = phones;
    }

    // Business method to add a phone number to the customer
    public void addPhone(PhoneNumber phone) {
        this.getPhones().add(phone);

        // Update the phone entity instance to refer to this customer
        phone.addCustomer(this);
    }
}
public enum AccessType {
    FIELD,
    PROPERTY
}
@Entity @Access(PROPERTY)
public class Customer {
    private Long id;

    @Access(FIELD) // use field access for name
    private String name;

    @Id
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    @Transient // suppress duplicated name attribute
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    ...
}
@Entity
public class Employee {
    @Id long empId;
    String empName;

    // ...
}
public class DependentId {
    String name; // matches name of @Id attribute
    long emp; // matches name of @Id attribute and type of Employee PK
}

@Entity
@IdClass(DependentId.class)
public class Dependent {
    @Id String name;

    // id attribute mapped by join column default
    @Id @ManyToOne
    Employee emp;

    // ...
}
SELECT d
FROM Dependent d
WHERE d.name = 'Joe' AND d.emp.empName = 'Sam'
@Embeddable
public class DependentId {
    String name;
    long empPK; // corresponds to PK type of Employee
}

@Entity
public class Dependent {
    @EmbeddedId DependentId id;

    // id attribute mapped by join column default
    @MapsId("empPK") // maps empPK attribute of embedded id
    @ManyToOne
    Employee emp;

    // ...
}
SELECT d
FROM Dependent d
WHERE d.id.name = 'Joe' AND d.emp.empName = 'Sam'
public class EmployeeId {
    String firstName;
    String lastName;

    // ...
}

@Entity
@IdClass(EmployeeId.class)
public class Employee {
    @Id String firstName
    @Id String lastName

   // ...
}
public class DependentId {
    String name; // matches name of attribute
    EmployeeId emp; //matches name of attribute and type of Employee PK
}

@Entity
@IdClass(DependentId.class)
public class Dependent {
    @Id
    String name;

    @Id
    @JoinColumns({
        @JoinColumn(name="FK1", referencedColumnName="firstName"),
        @JoinColumn(name="FK2", referencedColumnName="lastName")
    })

    @ManyToOne
    Employee emp;
}
SELECT d
FROM Dependent d
WHERE d.name = 'Joe' AND d.emp.firstName = 'Sam'
@Embeddable
public class DependentId {
    String name;
    EmployeeId empPK;
}

@Entity
public class Dependent {
    @EmbeddedId
    DependentId id;

    @MapsId("empPK")
    @JoinColumns({
        @JoinColumn(name="FK1", referencedColumnName="firstName"),
        @JoinColumn(name="FK2", referencedColumnName="lastName")
    })

    @ManyToOne
    Employee emp;

    // ...
}
SELECT d
FROM Dependent d
WHERE d.id.name = 'Joe' AND d.emp.firstName = 'Sam'
SELECT d
FROM Dependent d
WHERE d.id.name = 'Joe' AND d.id.empPK.firstName = 'Sam'
@Embeddable
public class EmployeeId {
    String firstName;
    String lastName;

    // ...
}

@Entity
public class Employee {
    @EmbeddedId
    EmployeeId empId;

    // ...
}
public class DependentId {
    String name; // matches name of @Id attribute
    EmployeeId emp; // matches name of @Id attribute and type of embedded id of Employee
}

@Entity
@IdClass(DependentId.class)
public class Dependent {
    @Id
    @Column(name="dep_name") // default column name is overridden
    String name;

    @Id
    @JoinColumns({
        @JoinColumn(name="FK1", referencedColumnName="firstName"),
        @JoinColumn(name="FK2", referencedColumnName="lastName")
    })

    @ManyToOne Employee
    emp;
}
SELECT d
FROM Dependent d
WHERE d.name = 'Joe' and d.emp.empId.firstName = 'Sam'
@Embeddable
public class DependentId {
    String name;
    EmployeeId empPK; // corresponds to PK type of Employee
}

@Entity
public class Dependent {
    // default column name for "name" attribute is overridden
    @AttributeOverride(name="name", column=@Column(name="dep_name"))
    @EmbeddedId DependentId id;

    @MapsId("empPK")
    @JoinColumns({
        @JoinColumn(name="FK1", referencedColumnName="firstName"),
        @JoinColumn(name="FK2", referencedColumnName="lastName")
    })
    @ManyToOne
    Employee emp;

    // ...
}
SELECT d
FROM Dependent d
WHERE d.id.name = 'Joe' and d.emp.empId.firstName = 'Sam'
SELECT d
FROM Dependent d
WHERE d.id.name = 'Joe' AND d.id.empPK.firstName = 'Sam'
@Entity
public class Person {
    @Id
    String ssn;

    // ...
}
@Entity
public class MedicalHistory {
    // default join column name is overridden
    @Id
    @OneToOne
    @JoinColumn(name="FK")
    Person patient;

    // ...
}
SELECT m
FROM MedicalHistory m
WHERE m.patient.ssn = '123-45-6789'
@Entity
public class MedicalHistory {
    @Id
    String id; // overriding not allowed

    // ...

    // default join column name is overridden
    @MapsId
    @JoinColumn(name="FK")
    @OneToOne
    Person patient;

    // ...
}
SELECT m
FROM MedicalHistory m WHERE m.patient.ssn = '123-45-6789'
public class PersonId {
    String firstName;
    String lastName;
}

@Entity
@IdClass(PersonId.class)
public class Person {
    @Id
    String firstName;

    @Id
    String lastName;

    // ...
}
@Entity
@IdClass(PersonId.class)
public class MedicalHistory {
    @Id
    @JoinColumns({
        @JoinColumn(name="FK1", referencedColumnName="firstName"),
        @JoinColumn(name="FK2", referencedColumnName="lastName")
    })

    @OneToOne
    Person patient;

    // ...
}
SELECT m
FROM MedicalHistory m
WHERE m.patient.firstName = 'Charles'
@Entity
public class MedicalHistory {
    // all attributes map to relationship:
    AttributeOverride not allowed

    @EmbeddedId
    PersonId id;

    // ...

    @MapsId
    @JoinColumns({
        @JoinColumn(name="FK1", referencedColumnName="firstName"),
        @JoinColumn(name="FK2", referencedColumnName="lastName")
    })

    @OneToOne Person patient;

    // ...
}
SELECT m
FROM MedicalHistory m
WHERE m.patient.firstName = 'Charles'
SELECT m
FROM MedicalHistory m
WHERE m.id.firstName = 'Charles'
@Embeddable
public class PersonId {
    String firstName;
    String lastName;
}

@Entity
public class Person {
    @EmbeddedId PersonId id;

    // ...
}
@Entity
@IdClass(PersonId.class)
public class MedicalHistory {
    @Id
    @OneToOne
    @JoinColumns({
        @JoinColumn(name="FK1", referencedColumnName="firstName"),
        @JoinColumn(name="FK2", referencedColumnName="lastName")
    })

    Person patient;

    // ...
}
@Entity
public class MedicalHistory {
    // All attributes are mapped by the relationship
    // AttributeOverride is not allowed
    @EmbeddedId PersonId id;

    // ...

    @MapsId
    @JoinColumns({
        @JoinColumn(name="FK1", referencedColumnName="firstName"),
        @JoinColumn(name="FK2", referencedColumnName="lastName")
    })
    @OneToOne
    Person patient;

    // ...
}
@Entity
public class Employee {
    private Cubicle assignedCubicle;

    @OneToOne
    public Cubicle getAssignedCubicle() {
        return assignedCubicle;
    }

    public void setAssignedCubicle(Cubicle cubicle) {
        this.assignedCubicle = cubicle;
    }

    // ...
}

@Entity
public class Cubicle {
    private Employee residentEmployee;

    @OneToOne(mappedBy="assignedCubicle")
    public Employee getResidentEmployee() {
        return residentEmployee;
    }

    public void setResidentEmployee(Employee employee) {
        this.residentEmployee = employee;
    }

    // ...
}
@Entity
public class Employee {
    private Department department;

    @ManyToOne
    public Department getDepartment() {
        return department;
    }

    public void setDepartment(Department department) {
        this.department = department;
    }

    // ...
}

@Entity
public class Department {
    private Collection<Employee> employees = new HashSet();

    @OneToMany(mappedBy="department")
    public Collection<Employee> getEmployees() {
        return employees;
    }

    public void setEmployees(Collection<Employee> employees) {
        this.employees = employees;
    }

    // ...
}
@Entity
public class Employee {
    private TravelProfile profile;

    @OneToOne
    public TravelProfile getProfile() {
        return profile;
    }

    public void setProfile(TravelProfile profile) {
        this.profile = profile;
    }

    // ...
}

@Entity
public class TravelProfile {
    // ...
}
@Entity
public class Employee {
    private Address address;

    @ManyToOne
    public Address getAddress() {
        return address;
    }

    public void setAddress(Address address) {
        this.address = address;
    }

    // ...
}

@Entity
public class Address {
    // ...
}
@Entity
public class Project {
    private Collection<Employee> employees;

    @ManyToMany
    public Collection<Employee> getEmployees() {
        return employees;
    }

    public void setEmployees(Collection<Employee> employees) {
        this.employees = employees;
    }

    // ...
}

@Entity
public class Employee {
    private Collection<Project> projects;

    @ManyToMany(mappedBy="employees")
    public Collection<Project> getProjects() {
        return projects;
    }

    public void setProjects(Collection<Project> projects) {
        this.projects = projects;
    }

    // ...
}
@Entity
public class Employee {
    private Collection<AnnualReview> annualReviews;

    @OneToMany
    public Collection<AnnualReview> getAnnualReviews() {
        return annualReviews;
    }

    public void setAnnualReviews(Collection<AnnualReview> annualReviews) {
        this.annualReviews = annualReviews;
    }

    // ...
}

@Entity
public class AnnualReview {
    // ...
}
@Entity
public class Employee {
    private Collection<Patent> patents;

    @ManyToMany
    public Collection<Patent> getPatents() {
        return patents;
    }

    public void setPatents(Collection<Patent> patents) {
        this.patents = patents;
    }

    // ...
}

@Entity
public class Patent {
    //...
}
@Entity
@Table(name="EMP")
@Inheritance(strategy=JOINED)
public abstract class Employee {
    @Id
    protected Integer empId;

    @Version
    protected Integer version;

    @ManyToOne
    protected Address address;

    // ...
}

@Entity
@Table(name="FT_EMP")
@DiscriminatorValue("FT")
@PrimaryKeyJoinColumn(name="FT_EMPID")
public class FullTimeEmployee extends Employee {
    // Inherit empId, but mapped in this class to FT_EMP.FT_EMPID
    // Inherit version mapped to EMP.VERSION
    // Inherit address mapped to EMP.ADDRESS fk

    // Defaults to FT_EMP.SALARY
    protected Integer salary;

    // ...
}

@Entity
@Table(name="PT_EMP")
@DiscriminatorValue("PT")
// PK column is PT_EMP.EMPID due to `PrimaryKeyJoinColumn` default
public class PartTimeEmployee extends Employee {
    protected Float hourlyWage;

    // ...
}
@MappedSuperclass
public class Employee {
    @Id
    protected Integer empId;

    @Version
    protected Integer version;

    @ManyToOne
    @JoinColumn(name="ADDR")
    protected Address address;

    public Integer getEmpId() { ... }

    public void setEmpId(Integer id) { ... }

    public Address getAddress() { ... }

    public void setAddress(Address addr) { ... }
}

// Default table is FTEMPLOYEE table
@Entity
public class FTEmployee extends Employee {
    // Inherited empId field mapped to FTEMPLOYEE.EMPID
    // Inherited version field mapped to FTEMPLOYEE.VERSION
    // Inherited address field mapped to FTEMPLOYEE.ADDR fk

    // Defaults to FTEMPLOYEE.SALARY
    protected Integer salary;

    public FTEmployee() {}

    public Integer getSalary() { ... }

    public void setSalary(Integer salary) { ... }
}

@Entity
@Table(name="PT_EMP")
@AssociationOverride(name="address", joincolumns=@JoinColumn(name="ADDR_ID"))
public class PartTimeEmployee extends Employee {
    // Inherited empId field mapped to PT_EMP.EMPID
    // Inherited version field mapped to PT_EMP.VERSION
    // address field mapping overridden to PT_EMP.ADDR_ID fk
    @Column(name="WAGE")
    protected Float hourlyWage;

    public PartTimeEmployee() {}

    public Float getHourlyWage() { ... }

    public void setHourlyWage(Float wage) { ... }
}
public class Cart {
    protected Integer operationCount; // transient state

    public Cart() {
        operationCount = 0;
    }

    public Integer getOperationCount() {
        return operationCount;
    }

    public void incrementOperationCount() {
        operationCount++;
    }
}

@Entity
public class ShoppingCart extends Cart {
    Collection<Item> items = new Vector<Item>();

    public ShoppingCart() {
        super();
    }

    // ...

    @OneToMany
    public Collection<Item> getItems() {
        return items;
    }

    public void addItem(Item item) {
        items.add(item);
        incrementOperationCount();
    }
}
@Table(name="Customer")
@Table(name="customer")
@Table(name="cUsTomer")
@JoinColumn(name="CUSTOMER")
@ManyToOne Customer customer;

@JoinColumn(name="customer")
@ManyToOne Customer customer;

@ManyToOne Customer customer;
@Stateless
public class OrderEntryBean implements OrderEntry {
    @PersistenceContext
    EntityManager em;

    public void enterOrder(int custID, Order newOrder) {
        Customer cust = em.find(Customer.class, custID);
        cust.getOrders().add(newOrder);
        newOrder.setCustomer(cust);
        em.persist(newOrder);
    }
}
public <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass)
public <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass)
/**
 * Specifies whether a transaction-scoped or extended persistence
 * context is to be used in {@link PersistenceContext}. If not
 * specified, a transaction-scoped persistence context is used.
 *
 * @since 1.0
 */
public enum PersistenceContextType {

    /** Transaction-scoped persistence context */
    TRANSACTION,

    /** Extended persistence context */
    EXTENDED
}
/**
 *
 * Defines the values of the {@code jakarta.persistence.lock.scope}
 * property for pessimistic locking.  This property may be passed as an
 * argument to the methods of the {@link EntityManager}, {@link Query},
 * and {@link TypedQuery} interfaces that allow lock modes to be specified
 * or used with the {@link NamedQuery} annotation.
 *
 * @since 2.0
 */
public enum PessimisticLockScope implements FindOption, RefreshOption, LockOption {

    /**
     * This value defines the default behavior for pessimistic locking.
     *
     * <p>The persistence provider must lock the database row(s) that
     * correspond to the non-collection-valued persistent state of
     * that instance. If a joined inheritance strategy is used, or if
     * the entity is otherwise mapped to a secondary table, this
     * entails locking the row(s) for the entity instance in the
     * additional table(s). Entity relationships for which the locked
     * entity contains the foreign key will also be locked, but not
     * the state of the referenced entities (unless those entities are
     * explicitly locked). Element collections and relationships for
     * which the entity does not contain the foreign key (such as
     * relationships that are mapped to join tables or unidirectional
     * one-to-many relationships for which the target entity contains
     * the foreign key) will not be locked by default.
     */
    NORMAL,

    /**
     * In addition to the locking behavior specified for {@link #NORMAL},
     * element collections and relationships owned by the entity that
     * are contained in join tables are locked if the property
     * {@code jakarta.persistence.lock.scope} is specified with a value
     * of {@code PessimisticLockScope#EXTENDED}. The state of entities
     * referenced by such relationships is not locked (unless those
     * entities are explicitly locked). Locking such a relationship or
     * element collection generally locks only the rows in the join table
     * or collection table for that relationship or collection. This means
     * that phantoms are possible.
     */
    EXTENDED
}
jakarta.persistence.lock.scope
jakarta.persistence.lock.timeout // time in milliseconds
void <METHOD>()
void <METHOD>(S)
@Entity
@EntityListeners(com.acme.AlertMonitor.class)
public class Account {
    Long accountId;
    Integer balance;
    boolean preferred;

    @Id
    public Long getAccountId() { ... }

    // ...

    public Integer getBalance() { ... }

    // ...

    @Transient // because status depends upon non-persistent context
    public boolean isPreferred() { ... }

    // ...

    public void deposit(Integer amount) { ... }

    public Integer withdraw(Integer amount) throws NSFException { ... }

    @PrePersist
    protected void validateCreate() {
        if (getBalance() < MIN_REQUIRED_BALANCE)
            throw new AccountException("Insufficient balance to open an account");
    }

    @PostLoad
    protected void adjustPreferredStatus() {
        preferred = (getBalance() >= AccountManager.getPreferredStatusLevel());
    }
}

public class AlertMonitor {
    @PostPersist
    public void newAccountAlert(Account acct) {
        Alerts.sendMarketingInfo(acct.getAccountId(), acct.getBalance());
    }
}
@Entity
public class Animal {

    // ...

    @PostPersist
    protected void postPersistAnimal() {
        // ...
    }
}

@Entity
@EntityListeners(PetListener.class)
public class Pet extends Animal {
    // ...
}

@Entity
@EntityListeners({CatListener.class, CatListener2.class})
public class Cat extends Pet {
    // ...
}

public class PetListener {
    @PostPersist
    protected void postPersistPetListenerMethod(Object pet) {
        // ...
    }
}

public class CatListener {
    @PostPersist
    protected void postPersistCatListenerMethod(Object cat) {
        // ...
    }
}

public class CatListener2 {
    @PostPersist
    protected void postPersistCatListener2Method(Object cat) {
        // ...
    }
}
@EntityListeners(SiameseCatListener.class)
@Entity
public class SiameseCat extends Cat {
    // ...

    @PostPersist
    protected void postPersistSiameseCat() {
        // ...
    }
}

public class SiameseCatListener {
    @PostPersist
    protected void postPersistSiameseCatListenerMethod(Object cat) {
        // ...
    }
}
@EntityListeners(SiameseCatListener.class)
@Entity
public class SiameseCat extends Cat {
    // ...

    @PostPersist
    protected void postPersistAnimal() {
        // ...
    }
}
@NamedEntityGraph
@Entity
public class Phonenumber {
    @Id
    protected String number;

    protected PhoneTypeEnum type;

    // ...
}
@NamedEntityGraph(
    attributeNodes={@NamedAttributeNode("projects")}
)
@Entity
public class Employee {
    @Id
    @GeneratedValue
    protected long id;

    @Basic
    protected String name;

    @Basic
    protected String employeeNumber;

    @OneToMany()
    protected List<Dependents> dependents;

    @OneToMany()
    protected List<Project> projects;

    @OneToMany()
    protected List<PhoneNumber> phoneNumbers;

    // ...
}

@Entity
@Inheritance
public class Project {
    @Id
    @GeneratedValue
    protected long id;

    String name;

    @OneToOne(fetch=FetchType.EAGER)
    protected Requirements doc;

    // ...
}

@Entity
public class LargeProject extends Project {
    @OneToOne(fetch=FetchType.LAZY)
    protected Employee approver;

    // ...
}

@Entity
public class Requirements {
    @Id
    protected long id;

    @Lob
    protected String description;

    @OneToOne(fetch=FetchType.LAZY)
    protected Approval approval

    // ...
}
@NamedEntityGraph
@Entity
public class Phonenumber {
    @Id
    protected String number;

    protected PhoneTypeEnum type;

    // ...
}
@NamedEntityGraph(
    attributeNodes={@NamedAttributeNode("projects")}
)
@Entity
public class Employee {
    @Id
    @GeneratedValue
    protected long id;

    @Basic
    protected String name;

    @Basic
    protected String employeeNumber;

    @OneToMany()
    protected List<Dependents> dependents;

    @OneToMany()
    protected List<Project> projects;

    @OneToMany()
    protected List<PhoneNumber> phoneNumbers;

    // ...
}

@Entity
@Inheritance
public class Project {
    @Id
    @GeneratedValue
    protected long id;

    String name;

    @OneToOne(fetch=FetchType.EAGER)
    protected Requirements doc;

    // ...
}

@Entity
public class LargeProject extends Project {
    @OneToOne(fetch=FetchType.LAZY)
    protected Employee approver;

    // ...
}

@Entity
public class Requirements {
    @Id
    protected long id;

    @Lob
    protected String description;

    @OneToOne(fetch=FetchType.LAZY)
    protected Approval approval

    // ...
}
/**
 * Interface implemented by custom attribute <em>converters</em>. A
 * converter is a class whose methods convert between:
 * <ul>
 * <li>the <em>target type</em> of the converter, an arbitrary Java
 *     type which may be used as the type of a persistent field or
 *     property, and
 * <li>a {@linkplain Basic basic type} used as an intermediate step
 *     in mapping to the database representation.
 * </ul>
 *
 * <p>A converted field or property is considered {@link Basic}, since,
 * with the aid of the converter, its values can be represented as
 * instances of a basic type.
 *
 * <p>A converter class must be annotated {@link Converter} or declared
 * as a converter in the object/relational mapping descriptor. The value
 * of {@link Converter#autoApply autoApply} determines if the converter
 * is automatically applied to persistent fields and properties of the
 * target type. The {@link Convert} annotation may be used to apply a
 * converter which is declared {@code autoApply=false}, to explicitly
 * {@linkplain Convert#disableConversion disable conversion}, or to
 * resolve ambiguities when multiple converters would otherwise apply.
 *
 * <p>Note that the target type {@code X} and the converted basic type
 * {@code Y} may be the same Java type.
 *
 * @param <X> the target type, that is, the type of the entity attribute
 * @param <Y> a basic type representing the type of the database column
 *
 * @see Converter
 * @see Convert#converter
 */
public interface AttributeConverter<X,Y> {

    /**
     * Converts the value stored in the entity attribute into the 
     * data representation to be stored in the database.
     *
     * @param attribute  the entity attribute value to be converted
     * @return  the converted data to be stored in the database column
     */
    Y convertToDatabaseColumn(X attribute);

    /**
     * Converts the data stored in the database column into the value
     * to be stored in the entity attribute.
     *
     * <p>Note that it is the responsibility of the converter writer
     * to specify the correct {@code dbData} type for the corresponding
     * column for use by the JDBC driver: i.e., persistence providers
     * are not expected to do such type conversion.
     *
     * @param dbData  the data from the database column to be converted
     * @return  the converted value to be stored in the entity attribute
     */
    X convertToEntityAttribute(Y dbData);
}
/**
 * Specifies how the {@link EntityManager} interacts with the
 * second-level cache when data is read from the database via
 * the {@link EntityManager#find} methods and execution of
 * queries.
 * <ul>
 * <li>{@link #USE} indicates that data may be read from the
 *     second-level cache.
 * <li>{@link #BYPASS} indicates that data may not be read
 *     from the second-level cache.
 * </ul>
 *
 * <p>Enumerates legal values of the property
 * {@code jakarta.persistence.cache.retrieveMode}.
 *
 * @see EntityManager#setCacheRetrieveMode(CacheRetrieveMode)
 * @see Query#setCacheRetrieveMode(CacheRetrieveMode)
 *
 * @since 2.0
 */
public enum CacheRetrieveMode implements FindOption {

    /**
     * Read entity data from the cache: this is the default
     * behavior.
     */
    USE,

    /**
     * Bypass the cache: get data directly from the database.
     */
    BYPASS  
}
/**
 * Specifies how the {@link EntityManager} interacts with the
 * second-level cache when data is read from the database and
 * when data is written to the database.
 * <ul>
 * <li>{@link #USE} indicates that data may be written to the
 *     second-level cache.
 * <li>{@link #BYPASS} indicates that data may not be written
 *     to the second-level cache.
 * <li>{@link #REFRESH} indicates that data must be written
 *     to the second-level cache, even when the data is already
 *     cached.
 * </ul>
 *
 * <p>Enumerates legal values of the property
 * {@code jakarta.persistence.cache.storeMode}.
 *
 * @see EntityManager#setCacheStoreMode(CacheStoreMode)
 * @see Query#setCacheStoreMode(CacheStoreMode)
 *
 * @since 2.0
 */
public enum CacheStoreMode implements FindOption, RefreshOption {

    /**
     * Insert entity data into cache when read from database and
     * insert/update entity data when written to the database:
     * this is the default behavior. Does not force refresh of
     * already cached items when reading from database.
     */
    USE,

    /**
     * Don't insert into cache. 
     */
    BYPASS,

    /**
     * Insert/update entity data held in the cache when read from
     * the database and when written to the database. Force refresh
     * of cache for items read from database.
     */
    REFRESH
}
public List findWithName(String name) {
    return em.createQuery("SELECT c FROM Customer c WHERE c.name LIKE :custName")
        .setParameter("custName", name)
        .setMaxResults(10)
        .getResultList();
}
/**
 * Enumerates flush modes recognized by the {@link EntityManager}.
 *
 * <p>When queries are executed within a transaction, if {@link #AUTO}
 * is set on the {@link Query Query} or {@link TypedQuery} object, or
 * if the flush mode setting for the persistence context is {@code AUTO}
 * (the default) and a flush mode setting has not been specified for the
 * {@code Query} or {@code TypedQuery} 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
 * updates to those entities to the database or by some other means.
 *
 * <p>On the other hand, if {@link #COMMIT} is set, the effect of updates
 * made to entities in the persistence context on queries is unspecified.
 *
 * <p>If there is no transaction active or the persistence context is
 * not joined to the current transaction, the persistence provider must
 * not flush to the database.
 *
 * @see EntityManager#setFlushMode(FlushModeType)
 * @see Query#setFlushMode(FlushModeType)
 *
 * @since 1.0
 */
public enum FlushModeType {

    /**
     * Flushing to occur at transaction commit. The provider may flush
     * at other times, but is not required to.
     */
   COMMIT,

    /**
     * (Default) Flushing to occur at query execution.
     */
   AUTO
}
jakarta.persistence.query.timeout // time in milliseconds
query.setParameter("name", name)
query.setParameter("names", List.of(name1, name2, name3))
@NamedQuery(
    name="findAllCustomersWithName",
    query="SELECT c FROM Customer c WHERE c.name LIKE :custName"
)
@PersistenceContext
public EntityManager em;
    // ...

    customers = em.createNamedQuery("findAllCustomersWithName")
        .setParameter("custName", "Smith")
        .getResultList();
select avg(e.salary) from Employee e where e.salary > 80000
Query q = em.createNativeQuery(
    "SELECT o.id, o.quantity, o.item " +
        "FROM Order o, Item i " +
        "WHERE (o.item = i.id) AND (i.name = 'widget')",
    com.acme.Order.class);
@SqlResultSetMapping(
    name="WidgetOrderResults",
    entities=@EntityResult(entityClass=com.acme.Order.class))
Query q = em.createNativeQuery(
    "SELECT o.id, o.quantity, o.item " +
        "FROM Order o, Item i " +
        "WHERE (o.item = i.id) AND (i.name = 'widget')",
    "WidgetOrderResults");
Query q = em.createNativeQuery(
    "SELECT o.id, o.quantity, o.item, i.id, i.name, i.description " +
        "FROM Order o, Item i " +
        "WHERE (o.quantity > 25) AND (o.item = i.id)",
    "OrderItemResults");

@SqlResultSetMapping(name="OrderItemResults", entities={
    @EntityResult(entityClass=com.acme.Order.class),
    @EntityResult(entityClass=com.acme.Item.class)
})
Query q = em.createNativeQuery(
    "SELECT o.id AS order_id, " +
        "o.quantity AS order_quantity, " +
        "o.item AS order_item, " +
        "i.id, i.name, i.description " +
        "FROM Order o, Item i " +
        "WHERE (order_quantity > 25) AND (order_item = i.id)",
    "OrderItemResults");

@SqlResultSetMapping(name="OrderItemResults", entities={
    @EntityResult(entityClass=com.acme.Order.class, fields={
        @FieldResult(name="id", column="order_id"),
        @FieldResult(name="quantity", column="order_quantity"),
        @FieldResult(name="item", column="order_item")}),
    @EntityResult(entityClass=com.acme.Item.class)
})
Query q = em.createNativeQuery(
    "SELECT c.id AS customer_id, " +
        "c.street AS customer_street, " +
        "c.city AS customer_city, " +
        "c.state AS customer_state, " +
        "c.status AS customer_status " +
        "FROM Customer c " +
        "WHERE c.status = 'GOLD' ",
    "CustomerResults");

@SqlResultSetMapping(name=”CustomerResults”, entities={
    @EntityResult(entityClass=com.acme.Customer.class, fields={
        @FieldResult(name="id", column="customer_id"),
        @FieldResult(name="address.street", column="customer_street"),
        @FieldResult(name="address.city", column="customer_city"),
        @FieldResult(name="address.state", column="customer_state"),
        @FieldResult(name="status", column="customer_status")
    })
})
Query q = em.createNativeQuery(
    "SELECT o.id AS order_id, " +
        "o.quantity AS order_quantity, " +
        "o.item_id AS order_item_id, " +
        "o.item_name AS order_item_name, " +
        "i.id, i.name, i.description " +
        "FROM Order o, Item i " +
        "WHERE (order_quantity > 25) AND (order_item_id = i.id) " +
        "AND (order_item_name = i.name)",
    "OrderItemResults");

@SqlResultSetMapping(name="OrderItemResults", entities={
    @EntityResult(entityClass=com.acme.Order.class, fields={
        @FieldResult(name="id", column="order_id"),
        @FieldResult(name="quantity", column="order_quantity"),
        @FieldResult(name="item.id", column="order_item_id")}),
        @FieldResult(name="item.name", column="order_item_name")}),
    @EntityResult(entityClass=com.acme.Item.class)
})
Query q = em.createNativeQuery(
    "SELECT o.id AS order_id, " +
        "o.quantity AS order_quantity, " +
        "o.item_id AS order_item_id, " +
        "o.item_name AS order_item_name, " +
        "i.id, i.name, i.description " +
        "FROM Order o, Item i " +
        "WHERE (order_quantity > 25) AND (order_item_id = i.id) AND (order_item_name = i.name)",
    "OrderItemResults");

@SqlResultSetMapping(name="OrderItemResults", entities={
    @EntityResult(entityClass=com.acme.Order.class, fields={
        @FieldResult(name="id", column="order_id"),
        @FieldResult(name="quantity", column="order_quantity"),
        @FieldResult(name="item.itemPk.id", column="order_item_id")}),
        @FieldResult(name="item.itemPk.name", column="order_item_name")}),
    @EntityResult(entityClass=com.acme.Item.class)
})
Query q = em.createNativeQuery(
    "SELECT o.id AS order_id, " +
        "o.quantity AS order_quantity, " +
        "o.item AS order_item, " +
        "i.name AS item_name, " +
        "i.availabilityDate AS item_shipdate " +
        "FROM Order o, Item i " +
        "WHERE (order_quantity > 25) AND (order_item = i.id)",
    "OrderResults");

@SqlResultSetMapping(
    name="OrderResults",
    entities={
        @EntityResult(entityClass=com.acme.Order.class, fields={
            @FieldResult(name="id", column="order_id"),
            @FieldResult(name="quantity", column="order_quantity"),
            @FieldResult(name="item", column="order_item")}
        )},
    columns={
        @ColumnResult(name="item_name"),
        @ColumnResult(name="item_shipdate", type=java.util.Date.class)
    })
Query q = em.createNativeQuery(
    "SELECT c.id, c.name, COUNT(o) as orderCount, AVG(o.price) AS avgOrder " +
        "FROM Customer c, Orders o " +
        "WHERE o.cid = c.id " +
        "GROUP BY c.id, c.name",
    "CustomerDetailsResult");

@SqlResultSetMapping(name="CustomerDetailsResult", classes={
    @ConstructorResult(targetClass=com.acme.CustomerDetails.class, columns={
        @ColumnResult(name="id"),
        @ColumnResult(name="name"),
        @ColumnResult(name="orderCount"),
        @ColumnResult(name="avgOrder", type=Double.class)})
})
QL_statement ::= select_statement | update_statement | delete_statement
select_query ::= [select_clause]? from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause]
select_statement ::= union
union ::= intersection | union {UNION [ALL] | EXCEPT [ALL]} intersection
intersection ::= query_expression | intersection INTERSECT [ALL] query_expression
query_expression ::= select_query | (union)
update_statement ::= update_clause [where_clause]
delete_statement ::= delete_clause [where_clause]
SELECT DISTINCT o
FROM Order AS o JOIN o.lineItems AS l
WHERE l.shipped = FALSE
SELECT DISTINCT o
FROM Order o JOIN o.lineItems l JOIN l.product p
WHERE p.productType = 'office_supplies'
from_clause ::=
    FROM {this_implicit_variable | identification_variable_declarations}

this_implicit_variable ::= entity_name

identification_variable_declarations ::=
    identification_variable_declaration
    {, {identification_variable_declaration | collection_member_declaration}}*

identification_variable_declaration ::= range_variable_declaration {join | fetch_join}*

range_variable_declaration ::= entity_name [AS] identification_variable

join ::= range_join | path_join

range_join ::= join_spec range_variable_declaration [join_condition]

path_join ::=
    join_spec join_association_path_expression [AS] identification_variable [join_condition]

fetch_join ::= join_spec FETCH join_association_path_expression

join_spec ::= [INNER | LEFT [OUTER]] JOIN

join_association_path_expression ::=
    join_collection_valued_path_expression |
    join_single_valued_path_expression |
    TREAT(join_collection_valued_path_expression AS subtype) |
    TREAT(join_single_valued_path_expression AS subtype)

join_collection_valued_path_expression ::= [identification_variable.]{single_valued_embeddable_object_field.}*collection_valued_field

join_single_valued_path_expression ::= [identification_variable.]{single_valued_embeddable_object_field.}*single_valued_object_field

join_condition ::= ON conditional_expression

collection_member_declaration ::= IN (collection_valued_path_expression) [AS] identification_variable
SELECT DISTINCT o
FROM Order o JOIN o.lineItems l JOIN l.product p
WHERE p.productType = 'office_supplies'
range_variable_declaration ::= entity_name [AS] identification_variable
SELECT DISTINCT o1
FROM Order o1, Order o2
WHERE o1.quantity > o2.quantity AND
 o2.customer.lastname = 'Smith' AND
 o2.customer.firstname= 'John'
SELECT quantity
FROM Order
WHERE customer.lastname = 'Smith'
  AND customer.firstname= 'John'
SELECT this.quantity
FROM Order
WHERE this.customer.lastname = 'Smith'
  AND this.customer.firstname= 'John'
SELECT ord.quantity
FROM Order AS ord
WHERE ord.customer.lastname = 'Smith'
  AND ord.customer.firstname= 'John'
SELECT i.name, VALUE(p)
FROM Item i JOIN i.photos p
WHERE KEY(p) LIKE '%egret'
SELECT i.name, p
FROM Item i JOIN i.photos p
WHERE KEY(p) LIKE '%egret'
qualified_identification_variable ::=
    map_field_identification_variable |
    ENTRY(identification_variable)

map_field_identification_variable ::=
    KEY(identification_variable) |
    VALUE(identification_variable)
@Entity
public class Employee {
    @Id int id;
    @Embedded
    private ContactInfo contactInfo;
}

@Entity
public class Phone {
    @Id
    private int id;
    private String vendor;
}

@Embeddable
public class ContactInfo {
    @Embedded
    private Address address;
    @ManyToMany
    private List<Phone> phones;
}

@Embeddable
public class Address {
    private String street;
    private String city;
    private String state;
    private String zipcode;
}
SELECT p.vendor
FROM Employee e JOIN e.contactInfo.phones p
WHERE e.contactInfo.address.zipcode = '95054'
SELECT p.vendor
FROM Employee e JOIN e.contactInfo c JOIN c.phones p
WHERE e.contactInfo.address.zipcode = '95054'
general_identification_variable ::=
    identification_variable |
    map_field_identification_variable
general_subpath ::= simple_subpath | treated_subpath{.single_valued_object_field}*

simple_subpath ::=
    general_identification_variable |
    general_identification_variable{.single_valued_object_field}*

treated_subpath ::= TREAT(general_subpath AS subtype)

single_valued_path_expression ::=
    qualified_identification_variable |
    TREAT(qualified_identification_variable AS subtype) |
    state_field_path_expression |
    single_valued_object_path_expression

state_field_path_expression ::= [general_subpath.]state_field

state_valued_path_expression ::= state_field_path_expression | general_identification_variable

single_valued_object_path_expression ::= general_subpath.single_valued_object_field

collection_valued_path_expression ::= general_subpath.collection_valued_field
SELECT DISTINCT l.product
FROM Order AS o JOIN o.lineItems l
SELECT c FROM Customer c, Employee e WHERE c.hatsize = e.shoesize
join ::= range_join | path_join

range_join ::= join_spec range_variable_declaration [join_condition]

path_join ::=
    join_spec join_association_path_expression [AS] identification_variable [join_condition]

fetch_join ::= join_spec FETCH join_association_path_expression

join_spec ::= [INNER | LEFT [OUTER]] JOIN

join_association_path_expression ::=
    join_collection_valued_path_expression |
    join_single_valued_path_expression |
    TREAT(join_collection_valued_path_expression `AS` subtype) |
    TREAT(join_single_valued_path_expression AS subtype)

join_collection_valued_path_expression ::=
    [identification_variable.]{single_valued_embeddable_object_field.}*collection_valued_field

join_single_valued_path_expression ::=
    [identification_variable.]{single_valued_embeddable_object_field.}*single_valued_object_field

join_condition ::= ON conditional_expression
[INNER] JOIN range_variable_declaration [join_condition]
SELECT c
FROM Customer c
    JOIN Order o ON o.customer.id = c.id
WHERE c.status = 1
SELECT c
FROM Customer c
    INNER JOIN Order o ON o.customer.id = c.id
WHERE c.status = 1
SELECT c
FROM Customer c, Order o
WHERE o.customer.id = c.id AND c.status = 1
[INNER] JOIN join_association_path_expression [AS] identification_variable [join_condition]
SELECT c
FROM Customer c
   JOIN c.orders o
WHERE c.status = 1
SELECT c
FROM Customer c
    INNER JOIN c.orders o
WHERE c.status = 1
SELECT OBJECT(c)
FROM Customer c, IN(c.orders) o
WHERE c.status = 1
SELECT p.vendor
FROM Employee e JOIN e.contactInfo c JOIN c.phones p
WHERE c.address.zipcode = '95054'
LEFT [OUTER] JOIN range_variable_declaration [join_condition]
SELECT c
FROM Customer c
    LEFT JOIN Order o ON o.customer.id = c.id
WHERE c.status = 1
SELECT c
FROM Customer c
    LEFT OUTER JOIN Order o ON o.customer.id = c.id
WHERE c.status = 1
LEFT [OUTER] JOIN join_association_path_expression [AS] identification_variable [join_condition]
SELECT s.name, COUNT(p)
FROM Suppliers s LEFT JOIN s.products p
GROUP BY s.name
SELECT s.name, COUNT(p.id)
FROM Suppliers s LEFT JOIN Products p
    ON s.id = p.supplierId
GROUP By s.name
SELECT s.name, COUNT(p)
FROM Suppliers s LEFT JOIN s.products p
    ON p.status = 'inStock'
GROUP BY s.name
SELECT s.name, COUNT(p.id)
FROM Suppliers s LEFT JOIN Products p
    ON s.id = p.supplierId AND p.status = 'inStock'
GROUP BY s.name
SELECT s.name, COUNT(p)
FROM Suppliers s LEFT JOIN s.products p
WHERE p.status = 'inStock'
GROUP BY s.name
fetch_join ::= [LEFT [OUTER] | INNER] JOIN FETCH join_association_path_expression
SELECT d
FROM Department d LEFT JOIN FETCH d.employees
WHERE d.deptno = 1
collection_member_declaration ::=
    IN (collection_valued_path_expression) [AS] identification_variable
SELECT DISTINCT o
FROM Order o JOIN o.lineItems l
WHERE l.product.productType = 'office_supplies'
SELECT DISTINCT o
FROM Order o, IN(o.lineItems) l
WHERE l.product.productType = 'office_supplies'
SELECT o
FROM Order AS o JOIN o.lineItems l JOIN l.product p
SELECT b.name, b.ISBN
FROM Order o JOIN TREAT(o.product AS Book) b

SELECT e FROM Employee e JOIN TREAT(e.projects AS LargeProject) lp
WHERE lp.budget > 1000

SELECT e FROM Employee e JOIN e.projects p
WHERE TREAT(p AS LargeProject).budget > 1000
    OR TREAT(p AS SmallProject).name LIKE 'Persist%'
    OR p.description LIKE "cost overrun"

SELECT e FROM Employee e
WHERE TREAT(e AS Exempt).vacationDays > 10
    OR TREAT(e AS Contractor).hours > 100
where_clause ::= WHERE conditional_expression
having_clause ::= HAVING conditional_expression
conditional_expression ::= conditional_term | conditional_expression OR conditional_term
conditional_term ::= conditional_factor | conditional_term AND conditional_factor
conditional_factor ::= [NOT] conditional_primary
conditional_primary ::= simple_cond_expression | (conditional_expression)
simple_cond_expression ::=
    comparison_expression |
    between_expression |
    in_expression |
    like_expression |
    null_comparison_expression |
    empty_collection_comparison_expression |
    collection_member_expression |
    exists_expression
comparison_expression ::=
    string_expression comparison_operator {string_expression | all_or_any_expression} |
    boolean_expression {= | <>} {boolean_expression | all_or_any_expression} |
    enum_expression {= | <>} {enum_expression | all_or_any_expression} |
    datetime_expression comparison_operator
        {datetime_expression | all_or_any_expression} |
    entity_expression {= | <>} {entity_expression | all_or_any_expression} |
    arithmetic_expression comparison_operator
        {arithmetic_expression | all_or_any_expression} |
    entity_id_or_version_function {= | <>} input_parameter |
    entity_type_expression {= | <>} entity_type_expression}

comparison_operator ::= = | > | >= | < | <= | <>
item.cost * 1.08 <= 100.00
CONCAT(person.lastName, ', ', person.firstName)) = 'Jones, Sam'
TYPE(e) = ExemptEmployee
 between_expression ::=
    arithmetic_expression [NOT] BETWEEN arithmetic_expression AND arithmetic_expression |
    string_expression [NOT] BETWEEN string_expression AND string_expression |
    datetime_expression [NOT] BETWEEN datetime_expression AND datetime_expression
x BETWEEN y AND z
y <= x AND x <= z
SELECT t
FROM CreditCard c JOIN c.transactionHistory t
WHERE c.holder.name = 'John Doe' AND INDEX(t) BETWEEN 0 AND 9
in_expression ::=
    {state_valued_path_expression | type_discriminator} [NOT] IN
        {(in_item {, in_item}*) | (subquery) | collection_valued_input_parameter}
in_item ::= literal | single_valued_input_parameter
o.country IN ('UK', 'US', 'France')
(o.country = 'UK') OR (o.country = 'US') OR (o.country = 'France')
o.country NOT IN ('UK', 'US', 'France')
NOT ((o.country = 'UK') OR (o.country = 'US') OR (o.country = 'France'))
o.country NOT IN :countries
like_expression ::=
    string_expression [NOT] LIKE pattern_value [ESCAPE escape_character]
null_comparison_expression ::=
    {single_valued_path_expression | input_parameter} IS [NOT] NULL
empty_collection_comparison_expression ::=
    collection_valued_path_expression IS [NOT] EMPTY
SELECT o
FROM Order o
WHERE o.lineItems IS EMPTY
collection_member_expression ::=
    entity_or_value_expression [NOT] MEMBER [OF] collection_valued_path_expression
entity_or_value_expression ::=
    single_valued_object_path_expression |
    state_valued_path_expression |
    simple_entity_or_value_expression
simple_entity_or_value_expression ::=
    identification_variable |
    input_parameter |
    literal
SELECT p
FROM Person p
WHERE 'Joe' MEMBER OF p.nicknames
exists_expression ::= [NOT] EXISTS (subquery)
SELECT DISTINCT emp
FROM Employee emp
WHERE EXISTS (
    SELECT spouseEmp
    FROM Employee spouseEmp
        WHERE spouseEmp = emp.spouse)
all_or_any_expression ::= {ALL | ANY | SOME} (subquery)
SELECT emp
FROM Employee emp
WHERE emp.salary > ALL (
    SELECT m.salary
    FROM Manager m
    WHERE m.department = emp.department)
subquery ::= simple_select_clause subquery_from_clause [where_clause]
    [groupby_clause] [having_clause]
simple_select_clause ::= SELECT [DISTINCT] simple_select_expression
subquery_from_clause ::=
    FROM subselect_identification_variable_declaration
        {, subselect_identification_variable_declaration |
            collection_member_declaration}*
subselect_identification_variable_declaration ::=
    identification_variable_declaration |
    derived_path_expression [AS] identification_variable {join}* |
    derived_collection_member_declaration
simple_select_expression ::=
    single_valued_path_expression |
    scalar_expression |
    aggregate_expression |
    identification_variable
derived_path_expression ::=
    general_derived_path.single_valued_object_field |
    general_derived_path.collection_valued_field
general_derived_path ::=
    simple_derived_path |
    treated_derived_path{.single_valued_object_field}*
simple_derived_path ::= superquery_identification_variable{.single_valued_object_field}*
treated_derived_path ::= TREAT(general_derived_path AS subtype)
derived_collection_member_declaration ::=
    IN superquery_identification_variable.{single_valued_object_field.}*collection_valued_field
SELECT DISTINCT emp
FROM Employee emp
WHERE EXISTS (
    SELECT spouseEmp
    FROM Employee spouseEmp
    WHERE spouseEmp = emp.spouse)
SELECT c
FROM Customer c
WHERE (SELECT AVG(o.price) FROM c.orders o) > 100

SELECT goodCustomer
FROM Customer goodCustomer
WHERE goodCustomer.balanceOwed < (
    SELECT AVG(c.balanceOwed)/2.0 FROM Customer c)
SELECT o
FROM Order o
SELECT o
FROM Order o
WHERE o.shippingAddress.state = 'CA'
SELECT DISTINCT o.shippingAddress.state
FROM Order o
SELECT DISTINCT o
FROM Order o JOIN o.lineItems l
SELECT o
FROM Order o
WHERE o.lineItems IS NOT EMPTY
SELECT o
FROM Order o
WHERE o.lineItems IS EMPTY
SELECT DISTINCT o
FROM Order o JOIN o.lineItems l
WHERE l.shipped = FALSE
SELECT o
FROM Order o
WHERE
    NOT (o.shippingAddress.state = o.billingAddress.state AND
         o.shippingAddress.city = o.billingAddress.city AND
         o.shippingAddress.street = o.billingAddress.street)
SELECT o
FROM Order o
WHERE o.shippingAddress <> o.billingAddress
SELECT DISTINCT o
FROM Order o JOIN o.lineItems l
WHERE l.product.name = ?1
scalar_expression ::=
    arithmetic_expression |
    string_expression |
    enum_expression |
    datetime_expression |
    boolean_expression |
    case_expression |
    entity_type_expression |
    entity_id_or_version_function
SELECT o
FROM Customer c JOIN c.orders o
WHERE c.name = 'Smith'
    AND o.submissionDate < {d '2008-12-31'}
SELECT c
FROM Customer c
WHERE c.status = :stat
functions_returning_strings ::=
    CONCAT(string_expression, string_expression {, string_expression}*) |
    SUBSTRING(string_expression,
              arithmetic_expression [, arithmetic_expression]) |
    TRIM([[trim_specification] [trim_character] FROM] string_expression) |
    LOWER(string_expression) |
    UPPER(string_expression) |
    REPLACE(string_expression, string_expression, string_expression) |
    LEFT(string_expression, arithmetic_expression) |
    RIGHT(string_expression, arithmetic_expression)
trim_specification ::= LEADING | TRAILING | BOTH

functions_returning_numerics ::=
    LENGTH(string_expression) |
    LOCATE(string_expression, string_expression[, arithmetic_expression])
functions_returning_numerics ::=
    ABS(arithmetic_expression) |
    CEILING(arithmetic_expression) |
    EXP(arithmetic_expression) |
    FLOOR(arithmetic_expression) |
    LN(arithmetic_expression) |
    MOD(arithmetic_expression, arithmetic_expression) |
    POWER(arithmetic_expression, arithmetic_expression) |
    ROUND(arithmetic_expression, arithmetic_expression) |
    SIGN(arithmetic_expression) |
    SQRT(arithmetic_expression) |
    SIZE(collection_valued_path_expression) |
    INDEX(identification_variable) |
    extract_datetime_field
SELECT w.name
FROM Course c JOIN c.studentWaitlist w
WHERE c.name = 'Calculus'
AND INDEX(w) = 0
functions_returning_datetime :=
    CURRENT_DATE |
    CURRENT_TIME |
    CURRENT_TIMESTAMP |
    LOCAL DATE |
    LOCAL TIME |
    LOCAL DATETIME |
    extract_datetime_part
extract_datetime_field :=
    EXTRACT(datetime_field FROM datetime_expression)

datetime_field := identification_variable
extract_datetime_part :=
    EXTRACT(datetime_part FROM datetime_expression)

datetime_part := identification_variable
FROM Course c WHERE c.year = EXTRACT(YEAR FROM LOCAL DATE)
string_cast_function::=
    CAST(scalar_expression AS STRING)
arithmetic_cast_function::=
    CAST(string_expression AS {INTEGER | LONG | FLOAT | DOUBLE})
function_invocation ::= FUNCTION(function_name {, function_arg}*)

function_arg ::=
    literal |
    state_valued_path_expression |
    input_parameter |
    scalar_expression
SELECT c
FROM Customer c
WHERE FUNCTION('hasGoodCredit', c.balance, c.creditLimit)
case_expression ::=
    general_case_expression |
    simple_case_expression |
    coalesce_expression |
    nullif_expression

general_case_expression ::=
    CASE when_clause {when_clause}* ELSE scalar_expression END
when_clause ::= WHEN conditional_expression THEN scalar_expression

simple_case_expression ::=
    CASE case_operand simple_when_clause {simple_when_clause}*
    ELSE scalar_expression
    END
case_operand ::= state_valued_path_expression | type_discriminator
simple_when_clause ::= WHEN scalar_expression THEN scalar_expression

coalesce_expression ::= COALESCE(scalar_expression {, scalar_expression}+)

nullif_expression ::= NULLIF(scalar_expression, scalar_expression)
UPDATE Employee e
SET e.salary =
    CASE WHEN e.rating = 1 THEN e.salary * 1.1
         WHEN e.rating = 2 THEN e.salary * 1.05
         ELSE e.salary * 1.01
    END

UPDATE Employee e
SET e.salary =
    CASE e.rating WHEN 1 THEN e.salary * 1.1
                  WHEN 2 THEN e.salary * 1.05
                  ELSE e.salary * 1.01
    END

SELECT e.name,
    CASE TYPE(e) WHEN Exempt THEN 'Exempt'
                 WHEN Contractor THEN 'Contractor'
                 WHEN Intern THEN 'Intern'
                 ELSE 'NonExempt'
    END
FROM Employee e
WHERE e.dept.name = 'Engineering'

SELECT e.name,
       f.name,
       CONCAT(CASE WHEN f.annualMiles > 50000 THEN 'Platinum '
                   WHEN f.annualMiles > 25000 THEN 'Gold '
                   ELSE ''
              END,
       'Frequent Flyer')
FROM Employee e JOIN e.frequentFlierPlan f
entity_id_or_version_function ::= id_function | version_function
id_function ::=
    ID(general_identification_variable |
       single_valued_object_path_expression)
version_function ::=
    VERSION(general_identification_variable |
            single_valued_object_path_expression)
DELETE from Employee
WHERE id(this) = :id
  AND version(this) = :version
entity_type_expression ::=
    type_discriminator |
    entity_type_literal |
    input_parameter
type_discriminator ::=
    TYPE(general_identification_variable |
         single_valued_object_path_expression |
         input_parameter)
SELECT e
FROM Employee e
WHERE TYPE(e) IN (Exempt, Contractor)

SELECT e
FROM Employee e
WHERE TYPE(e) IN (:empType1, :empType2)

SELECT e
FROM Employee e
WHERE TYPE(e) IN :empTypes

SELECT TYPE(e)
FROM Employee e
WHERE TYPE(e) <> Exempt
groupby_clause ::= GROUP BY groupby_item {, groupby_item}*
groupby_item ::= single_valued_path_expression | identification_variable

having_clause ::= HAVING conditional_expression
SELECT c.status, AVG(c.filledOrderCount), COUNT(c)
FROM Customer c
GROUP BY c.status
HAVING c.status IN (1, 2)

SELECT c.country, COUNT(c)
FROM Customer c
GROUP BY c.country
HAVING COUNT(c) > 30

SELECT c, COUNT(o)
FROM Customer c JOIN c.orders o
GROUP BY c
HAVING COUNT(o) >= 5
select_clause ::= SELECT [DISTINCT] select_item {, select_item}*
select_item ::= select_expression [[AS] result_variable]
select_expression ::=
    single_valued_path_expression |
    scalar_expression |
    aggregate_expression |
    identification_variable |
    OBJECT(identification_variable) |
    constructor_expression
constructor_expression ::=
    NEW constructor_name (constructor_item {, constructor_item}*)
constructor_item ::=
    single_valued_path_expression |
    scalar_expression |
    aggregate_expression |
    identification_variable
aggregate_expression ::=
    {AVG | MAX | MIN | SUM} ([DISTINCT] state_valued_path_expression) |
     COUNT ([DISTINCT] identification_variable | state_valued_path_expression |
         single_valued_object_path_expression) |
     function_invocation
SELECT c.id, c.status
FROM Customer c JOIN c.orders o
WHERE o.count > 100
SELECT v.location.street, KEY(i).title, VALUE(i)
FROM VideoStore v JOIN v.videoInventory i
WHERE v.location.zipcode = '94301' AND VALUE(i) > 0
SELECT o.lineItems FROM Order AS o
SELECT c, COUNT(l) AS itemCount
FROM Customer c JOIN c.orders o JOIN o.lineItems l
WHERE c.address.state = 'CA'
GROUP BY c
ORDER BY itemCount
FROM Order
WHERE customer.lastname = 'Smith'
  AND customer.firstname= 'John'
SELECT this
FROM Order
WHERE this.customer.lastname = 'Smith'
  AND this.customer.firstname= 'John'
SELECT ord
FROM Order AS ord
WHERE ord.customer.lastname = 'Smith'
  AND ord.customer.firstname= 'John'
SELECT NEW com.acme.example.CustomerDetails(c.id, c.status, o.count)
FROM Customer c JOIN c.orders o
WHERE o.count > 100
@Entity
public class Employee {
    @Id
    int id;

    Address address;

    // ...
}

@Embeddable
public class Address {
    String street;

    // ...

    @OneToOne
    Phone phone; // fetch=EAGER
}

@Entity
public class Phone {
    @Id
    int id;

    // ...

    @OneToOne(mappedBy="address.phone")
    Employee emp; // fetch=EAGER
}
SELECT e.address AS addr
FROM Employee e
SELECT AVG(o.quantity) FROM Order o
SELECT SUM(l.price)
FROM Order o JOIN o.lineItems l JOIN o.customer c
WHERE c.lastname = 'Smith' AND c.firstname = 'John'
SELECT COUNT(o) FROM Order o
SELECT COUNT(l.price)
FROM Order o JOIN o.lineItems l JOIN o.customer c
WHERE c.lastname = 'Smith' AND c.firstname = 'John'
SELECT COUNT(l)
FROM Order o JOIN o.lineItems l JOIN o.customer c
WHERE c.lastname = 'Smith' AND c.firstname = 'John' AND l.price IS NOT NULL
orderby_clause ::= ORDER BY orderby_item {, orderby_item}*
orderby_item ::= orderby_expression [ASC | DESC] [NULLS {FIRST | LAST}]
orderby_expression ::=
    state_field_path_expression |
    general_identification_variable |
    result_variable |
    scalar_expression
SELECT o
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA'
ORDER BY o.quantity DESC, o.totalcost

SELECT o.quantity, a.zipcode
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA'
ORDER BY o.quantity, a.zipcode

SELECT o.quantity, o.cost*1.08 AS taxedCost, a.zipcode
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA' AND a.county = 'Santa Clara'
ORDER BY o.quantity, taxedCost, a.zipcode

SELECT AVG(o.quantity) as q, a.zipcode
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA'
GROUP BY a.zipcode
ORDER BY q DESC
SELECT c, o
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA'
ORDER BY UPPER(c.lastname), UPPER(c.firstname)
SELECT p.product_name
FROM Order o JOIN o.lineItems l JOIN l.product p JOIN o.customer c
WHERE c.lastname = 'Smith' AND c.firstname = 'John'
ORDER BY p.price

SELECT p.product_name
FROM Order o, IN(o.lineItems) l JOIN o.customer c
WHERE c.lastname = 'Smith' AND c.firstname = 'John'
ORDER BY o.quantity
update_statement ::= update_clause [where_clause]
update_clause ::= UPDATE entity_name [[AS] identification_variable]
                  SET update_item {, update_item}*
update_item ::= [identification_variable.]{single_valued_embeddable_object_field.}*
    {state_field | single_valued_object_field} = new_value
new_value ::=
    scalar_expression |
    simple_entity_expression |
    NULL

delete_statement ::= delete_clause [where_clause]
delete_clause ::= DELETE FROM entity_name [[AS] identification_variable]
DELETE
FROM Customer c
WHERE c.status = 'inactive'

DELETE
FROM Customer c
WHERE c.status = 'inactive'
    AND c.orders IS EMPTY

UPDATE Customer c
SET c.status = 'outstanding'
WHERE c.balance < 10000

UPDATE Employee e
SET e.address.building = 22
WHERE e.address.building = 14
    AND e.address.city = 'Santa Clara'
    AND e.project = 'Jakarta EE'
QL_statement ::= select_statement | update_statement | delete_statement
select_statement ::= union
union ::= intersection | union {UNION [ALL] | EXCEPT [ALL]} intersection
intersection ::= query_expression | intersection INTERSECT [ALL] query_expression
query_expression ::= select_query | (union)
select_query ::= [select_clause] from_clause [where_clause] [groupby_clause]
    [having_clause] [orderby_clause]
update_statement ::= update_clause [where_clause]
delete_statement ::= delete_clause [where_clause]
from_clause ::=
    FROM {this_implicit_variable | identification_variable_declarations}
this_implicit_variable ::= entity_name
identification_variable_declarations ::=
    identification_variable_declaration
    {, {identification_variable_declaration | collection_member_declaration}}*
identification_variable_declaration ::= range_variable_declaration {join | fetch_join}*
range_variable_declaration ::= entity_name [AS] identification_variable
join ::= range_join | path_join
range_join ::= join_spec range_variable_declaration [join_condition]
path_join ::=
    join_spec join_association_path_expression [AS] identification_variable [join_condition]
fetch_join ::= join_spec FETCH join_association_path_expression
join_spec ::= [INNER | LEFT [OUTER]] JOIN
join_condition ::= ON conditional_expression
join_association_path_expression ::=
    join_collection_valued_path_expression |
    join_single_valued_path_expression |
    TREAT(join_collection_valued_path_expression AS subtype) |
    TREAT(join_single_valued_path_expression AS subtype)
join_collection_valued_path_expression ::=
    [identification_variable.]{single_valued_embeddable_object_field.}* collection_valued_field
join_single_valued_path_expression ::=
    [identification_variable.]{single_valued_embeddable_object_field.}* single_valued_object_field
collection_member_declaration ::=
    IN (collection_valued_path_expression) [AS] identification_variable
qualified_identification_variable ::=
    map_field_identification_variable |
    ENTRY(identification_variable)
map_field_identification_variable ::=
    KEY(identification_variable) |
    VALUE(identification_variable)
single_valued_path_expression ::=
    qualified_identification_variable |
    TREAT(qualified_identification_variable AS subtype) |
    state_field_path_expression |
    single_valued_object_path_expression
general_identification_variable ::=
    identification_variable |
    map_field_identification_variable
general_subpath ::= simple_subpath | treated_subpath{.single_valued_object_field}*
simple_subpath ::=
    general_identification_variable |
    general_identification_variable{.single_valued_object_field}*
treated_subpath ::= TREAT(general_subpath AS subtype)
state_field_path_expression ::= [general_subpath.]state_field
state_valued_path_expression ::=
    state_field_path_expression | general_identification_variable
single_valued_object_path_expression ::=
    general_subpath.single_valued_object_field
collection_valued_path_expression ::= general_subpath.{collection_valued_field}
update_clause ::= UPDATE entity_name [[AS] identification_variable]
    SET update_item {, update_item}*
update_item ::= [identification_variable.]{single_valued_embeddable_object_field.}*
    {state_field | single_valued_object_field} = new_value
new_value ::=
    scalar_expression |
    simple_entity_expression |
    NULL
delete_clause ::= DELETE FROM entity_name [[AS] identification_variable]
select_clause ::= SELECT [DISTINCT] select_item {, select_item}*
select_item ::= select_expression [[AS] result_variable]
select_expression ::=
    single_valued_path_expression |
    scalar_expression |
    aggregate_expression |
    identification_variable |
    OBJECT(identification_variable) |
    constructor_expression
constructor_expression ::=
    NEW constructor_name (constructor_item {, constructor_item}*)
constructor_item ::=
    single_valued_path_expression |
    scalar_expression |
    aggregate_expression |
    identification_variable
aggregate_expression ::=
    {AVG | MAX | MIN | SUM} ([DISTINCT] state_valued_path_expression) |
    COUNT ([DISTINCT] identification_variable | state_valued_path_expression |
        single_valued_object_path_expression) |
    function_invocation
where_clause ::= WHERE conditional_expression
groupby_clause ::= GROUP BY groupby_item {, groupby_item}*
groupby_item ::= single_valued_path_expression | identification_variable
having_clause ::= HAVING conditional_expression
orderby_clause ::= ORDER BY orderby_item {, orderby_item}*
orderby_item ::= orderby_expression [ASC | DESC] [NULLS {FIRST | LAST}]
orderby_expression ::=
    state_field_path_expression |
    general_identification_variable |
    result_variable |
    scalar_expression
subquery ::= simple_select_clause subquery_from_clause [where_clause]
    [groupby_clause] [having_clause]
subquery_from_clause ::=
    FROM subselect_identification_variable_declaration
        {, subselect_identification_variable_declaration | collection_member_declaration}*
subselect_identification_variable_declaration ::=
    identification_variable_declaration |
    derived_path_expression [AS] identification_variable {join}* |
    derived_collection_member_declaration
derived_path_expression ::=
    general_derived_path.single_valued_object_field |
    general_derived_path.collection_valued_field
general_derived_path ::=
    simple_derived_path |
    treated_derived_path{.single_valued_object_field}*
simple_derived_path ::= superquery_identification_variable{.single_valued_object_field}*
treated_derived_path ::= TREAT(general_derived_path AS subtype)
derived_collection_member_declaration ::=
    IN superquery_identification_variable.{single_valued_object_field.}*collection_valued_field
simple_select_clause ::= SELECT [DISTINCT] simple_select_expression
simple_select_expression::=
    single_valued_path_expression |
    scalar_expression |
    aggregate_expression |
    identification_variable
scalar_expression ::=
    arithmetic_expression |
    string_expression |
    enum_expression |
    datetime_expression |
    boolean_expression |
    case_expression |
    entity_type_expression |
    entity_id_or_version_function
conditional_expression ::= conditional_term | conditional_expression OR conditional_term
conditional_term ::= conditional_factor | conditional_term AND conditional_factor
conditional_factor ::= [NOT] conditional_primary
conditional_primary ::= simple_cond_expression | (conditional_expression)
simple_cond_expression ::=
    comparison_expression |
    between_expression |
    in_expression |
    like_expression |
    null_comparison_expression |
    empty_collection_comparison_expression |
    collection_member_expression |
    exists_expression
between_expression ::=
    arithmetic_expression [NOT] BETWEEN
        arithmetic_expression AND arithmetic_expression |
    string_expression [NOT] BETWEEN string_expression AND string_expression |
    datetime_expression [NOT] BETWEEN datetime_expression AND datetime_expression
in_expression ::=
    {state_valued_path_expression | type_discriminator} [NOT] IN
        {(in_item{, in_item}*) | (subquery) | collection_valued_input_parameter}
in_item ::= literal | single_valued_input_parameter
like_expression ::=
    string_expression [NOT] LIKE pattern_value [ESCAPE escape_character]
null_comparison_expression ::=
    {single_valued_path_expression | input_parameter} IS [NOT] NULL
empty_collection_comparison_expression ::=
    collection_valued_path_expression IS [NOT] EMPTY
collection_member_expression ::= entity_or_value_expression
    [NOT] MEMBER [OF] collection_valued_path_expression
entity_or_value_expression ::=
    single_valued_object_path_expression |
    state_field_path_expression |
    simple_entity_or_value_expression
simple_entity_or_value_expression ::=
    identification_variable |
    input_parameter |
    literal
exists_expression ::= [NOT] EXISTS (subquery)
all_or_any_expression ::= {ALL | ANY | SOME} (subquery)
comparison_expression ::=
    string_expression comparison_operator {string_expression | all_or_any_expression} |
    boolean_expression {= | <>} {boolean_expression | all_or_any_expression} |
    enum_expression {= | <>} {enum_expression | all_or_any_expression} |
    datetime_expression comparison_operator
        {datetime_expression | all_or_any_expression} |
    entity_expression {= | <>} {entity_expression | all_or_any_expression} |
    arithmetic_expression comparison_operator {arithmetic_expression | all_or_any_expression} |
    entity_id_or_version_function {= | <>} input_parameter |
    entity_type_expression {= | <>} entity_type_expression}
comparison_operator ::= = | > | >= | < | <= | <>
arithmetic_expression ::=
    arithmetic_term | arithmetic_expression {+ | -} arithmetic_term
arithmetic_term ::= arithmetic_factor | arithmetic_term {* | /} arithmetic_factor
arithmetic_factor ::= [{+ | -}] arithmetic_primary
arithmetic_primary ::=
    state_valued_path_expression |
    numeric_literal |
    (arithmetic_expression) |
    input_parameter |
    functions_returning_numerics |
    aggregate_expression |
    case_expression |
    function_invocation |
    arithmetic_cast_function |
    (subquery)
string_expression ::=
    state_valued_path_expression |
    string_literal |
    input_parameter |
    functions_returning_strings |
    aggregate_expression |
    case_expression |
    function_invocation |
    string_cast_function |
    string_expression || string_expression |
    (subquery)
datetime_expression ::=
    state_valued_path_expression |
    input_parameter |
    functions_returning_datetime |
    aggregate_expression |
    case_expression |
    function_invocation |
    date_time_timestamp_literal |
    (subquery)
boolean_expression ::=
    state_valued_path_expression |
    boolean_literal |
    input_parameter |
    case_expression |
    function_invocation |
    (subquery)
enum_expression ::=
    state_valued_path_expression |
    enum_literal |
    input_parameter |
    case_expression |
    (subquery)
entity_expression ::= single_valued_object_path_expression | simple_entity_expression
simple_entity_expression ::= identification_variable | input_parameter
entity_type_expression ::=
    type_discriminator |
    entity_type_literal |
    input_parameter
type_discriminator ::=
    TYPE(general_identification_variable |
        single_valued_object_path_expression |
        input_parameter)
arithmetic_cast_function::=
    CAST(string_expression AS {INTEGER | LONG | FLOAT | DOUBLE})
functions_returning_numerics ::=
    LENGTH(string_expression) |
    LOCATE(string_expression, string_expression[, arithmetic_expression]) |
    ABS(arithmetic_expression) |
    CEILING(arithmetic_expression) |
    EXP(arithmetic_expression) |
    FLOOR(arithmetic_expression) |
    LN(arithmetic_expression) |
    SIGN(arithmetic_expression) |
    SQRT(arithmetic_expression) |
    MOD(arithmetic_expression, arithmetic_expression) |
    POWER(arithmetic_expression, arithmetic_expression) |
    ROUND(arithmetic_expression, arithmetic_expression) |
    SIZE(collection_valued_path_expression) |
    INDEX(identification_variable) |
    extract_datetime_field
functions_returning_datetime ::=
    CURRENT_DATE |
    CURRENT_TIME |
    CURRENT_TIMESTAMP |
    LOCAL DATE |
    LOCAL TIME |
    LOCAL DATETIME |
    extract_datetime_part
string_cast_function::=
    CAST(scalar_expression AS STRING)
functions_returning_strings ::=
    CONCAT(string_expression, string_expression{, string_expression}*) |
    SUBSTRING(string_expression, arithmetic_expression[, arithmetic_expression]) |
    TRIM([[trim_specification] [trim_character] FROM] string_expression) |
    LOWER(string_expression) |
    UPPER(string_expression)
trim_specification ::= LEADING | TRAILING | BOTH
function_invocation ::= FUNCTION(function_name{, function_arg}*)
extract_datetime_field :=
    EXTRACT(datetime_field FROM datetime_expression)
datetime_field := identification_variable
extract_datetime_part :=
    EXTRACT(datetime_part FROM datetime_expression)
datetime_part := identification_variable
function_arg ::=
    literal |
    state_valued_path_expression |
    input_parameter |
    scalar_expression
entity_id_or_version_function ::= id_function | version_function
id_function ::=
    ID(general_identification_variable |
       single_valued_object_path_expression)
version_function ::=
    VERSION(general_identification_variable |
            single_valued_object_path_expression)
case_expression ::=
    general_case_expression |
    simple_case_expression |
    coalesce_expression |
    nullif_expression
general_case_expression::= CASE when_clause {when_clause}* ELSE scalar_expression END
when_clause ::= WHEN conditional_expression THEN scalar_expression
simple_case_expression ::=
    CASE case_operand simple_when_clause {simple_when_clause}*
    ELSE scalar_expression
    END
case_operand ::= state_valued_path_expression | type_discriminator
simple_when_clause ::= WHEN scalar_expression THEN scalar_expression
coalesce_expression ::= COALESCE(scalar_expression{, scalar_expression}+)
nullif_expression::= NULLIF(scalar_expression, scalar_expression)
public static volatile jakarta.persistence.metamodel.T<X> class_;
public static final String Y = "y";
public static volatile SingularAttribute<X, Y> y;
public static volatile CollectionAttribute<X, Z> z;
public static volatile SetAttribute<X, Z> z;
public static volatile ListAttribute<X, Z> z;
public static volatile MapAttribute<X, K, Z> z;
public static final String T_N = "n";
public static volatile TypedQueryReference<R> _n_;
public static volatile EntityGraph<X> _n;
package com.example;

import java.util.Set;
import java.math.BigDecimal;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.OneToMany;

@Entity
public class Order {
    @Id
    Integer orderId;

    @ManyToOne
    Customer customer;

    @OneToMany
    Set<Item> lineItems;

    Address shippingAddress;

    BigDecimal totalCost;

    // ...
}
package com.example;

import java.math.BigDecimal;
import jakarta.persistence.metamodel.EntityType;
import jakarta.persistence.metamodel.SingularAttribute;
import jakarta.persistence.metamodel.SetAttribute;
import jakarta.persistence.metamodel.StaticMetamodel;

@StaticMetamodel(Order.class)
public class Order_ {
    public static volatile EntityType<Order> class_;

    public static volatile SingularAttribute<Order, Integer> orderId;
    public static volatile SingularAttribute<Order, Customer> customer;
    public static volatile SetAttribute<Order, Item> lineItems;
    public static volatile SingularAttribute<Order, Address> shippingAddress;
    public static volatile SingularAttribute<Order, BigDecimal> totalCost;

    public static final String LINE_ITEMS = "lineItems";
    public static final String ORDER_ID = "orderId";
    public static final String SHIPPING_ADDRESS = "shippingAddress";
    public static final String TOTAL_COST = "totalCost";
    public static final String CUSTOMER = "customer";
}
@PersistenceUnit
EntityManagerFactory emf;

CriteriaBuilder cb = emf.getCriteriaBuilder();
<T> CriteriaQuery<T> createQuery(Class<T> resultClass);

CriteriaQuery<Tuple> createTupleQuery();

CriteriaQuery<Object> createQuery();
CriteriaBuilder cb = ...
CriteriaQuery<Customer> q = cb.createQuery(Customer.class);
Root<Customer> customer = q.from(Customer.class);
q.select(customer);
CriteriaQuery<Order> q = cb.createQuery(Order.class);
Root<Order> order = q.from(Order.class);
Join<Order, Item> item = order.join(Order_.lineItems);
q.select(order);
CriteriaBuilder cb = ...
CriteriaQuery<String> q = cb.createQuery(String.class);
Root<Customer> customer = q.from(Customer.class);
Join<Customer, Order> order = customer.join(Customer_.orders);
Join<Order, Item> item = order.join(Order_.lineItems);
q.select(customer.get(Customer_.name))
    .where(cb.equal(item.get(Item_.product).get(Product_.productType), "printer"));
SELECT c.name
FROM Customer c JOIN c.orders o JOIN o.lineItems i
WHERE i.product.productType = 'printer'
CriteriaQuery<String> q = cb.createQuery(String.class);
Root<Customer> customer = q.from(Customer.class);
Join<Order, Item> item = customer.join(Customer_.orders).join(Order_.lineItems);
q.select(customer.get(Customer_.name))
    .where(cb.equal(item.get(Item_.product).get(Product_.productType), "printer"));
CriteriaQuery<Customer> q = cb.createQuery(Customer.class);
Root<Customer> customer = q.from(Customer.class);
Join<Customer,Order> order = customer.join(Customer_.orders, JoinType.LEFT);
q.where(cb.equal(customer.get(Customer_.status), 1))
    .select(customer);
SELECT c FROM Customer c LEFT JOIN c.orders o WHERE c.status = 1
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Supplier> s = q.from(Supplier.class);
Join<Supplier, Product> p = s.join(Supplier_.products, JoinType.LEFT);
p.on(cb.equal(p.get(Product_.status), "inStock"));
q.groupBy(s.get(Supplier_.name));
q.multiselect(s.get(Supplier_.name), cb.count(p));
SELECT s.name, COUNT(p)
FROM Suppliers s LEFT JOIN s.products p ON p.status = 'inStock'
GROUP BY s.name
CriteriaQuery<Department> q = cb.createQuery(Department.class);
Root<Department> d = q.from(Department.class);
d.fetch(Department.employees, JoinType.LEFT);
q.where(cb.equal(d.get(Department_.deptno), 1)).select(d);
SELECT d
FROM Department d LEFT JOIN FETCH d.employees
WHERE d.deptno = 1
CriteriaQuery<Vendor> q = cb.createQuery(Vendor.class);
Root<Employee> emp = q.from(Employee.class);
Join<ContactInfo, Phone> phone =
    emp.join(Employee_.contactInfo).join(ContactInfo_.phones);
q.where(cb.equal(emp.get(Employee_.contactInfo)
        .get(ContactInfo_.address)
        .get(Address_.zipcode), "95054"))
    .select(phone.get(Phone_.vendor));
SELECT p.vendor
FROM Employee e JOIN e.contactInfo.phones p
WHERE e.contactInfo.address.zipcode = '95054'
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Item> item = q.from(Item.class);
MapJoin<Item, String, Object> photo = item.join(Item_.photos);
q.multiselect(item.get(Item_.name), photo)
    .where(cb.like(photo.key(), "%egret%"));
SELECT i.name, p
FROM Item i JOIN i.photos p
WHERE KEY(p) LIKE '%egret%'
CriteriaQuery<TransactionHistory> q = cb.createQuery(TransactionHistory.class);
Root<CreditCard> cc = q.from(CreditCard.class);
ListJoin<CreditCard,TransactionHistory> t = cc.join(CreditCard_.transactionHistory);
q.select(t)
    .where(cb.equal(cc.get(CreditCard_.customer)
             .get(Customer_.accountNum), 321987),
           cb.between (t.index(), 0, 9));
SELECT t
FROM CreditCard c JOIN c.transactionHistory t
WHERE c.customer.accountNum = 321987 AND INDEX(t) BETWEEN 0 AND 9
CriteriaQuery<Order> q = cb.createQuery(Order.class);
Root<Order> order = q.from(Order.class);
q.where(cb.isEmpty(order.get(Order_.lineItems)))
    .select(order);
SELECT o
FROM Order o
WHERE o.lineItems IS EMPTY
CriteriaQuery<String> q = cb.createQuery(String.class);
Root<Order> order = q.from(Order.class);
Join<Order,Book> book = cb.treat(order.join(Order_.product), Book.class);
q.select(book.get(Book_.isbn));
SELECT b.ISBN
FROM Order o JOIN TREAT(o.product AS Book) b
CriteriaQuery<Customer> q = cb.createQuery(Customer.class);
Root<Customer> customer = q.from(Customer.class);
Join<Customer, Order> order = customer.join(Customer_.orders);
q.where(
    cb.equal(cb.treat(order.get(Order_.product), Book.class).get(Book_.name), "Iliad"));
q.select(customer);
SELECT c
FROM Customer c JOIN c.orders o
WHERE TREAT(o.product AS Book).name = 'Iliad'
CriteriaQuery<Employee> q = cb.createQuery(Employee.class);
Root<Employee> e = q.from(Employee.class);
q.where(
    cb.or(cb.gt(cb.treat(e, Exempt.class).get(Exempt_.vacationDays), 10),
    cb.gt(cb.treat(e, Contractor.class).get(Contractor_.hours), 100)));
SELECT e
FROM Employee e
WHERE TREAT(e AS Exempt).vacationDays > 10
    OR TREAT(e AS Contractor).hours > 100
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Customer> cust = q.from(Customer.class);
Join<Customer, Order> order = cust.join(Customer_.orders);
Join<Customer, Address> addr = cust.join(Customer_.address);
q.where(cb.equal(addr.get(Address_.state), "CA"),
        cb.equal(addr.get(Address_.county), "Santa Clara"));

q.multiselect(order.get(Order_.quantity),
        cb.prod(order.get(Order_.totalCost), 1.08),
        addr.get(Address_.zipcode));
SELECT o.quantity, o.totalCost*1.08, a.zipcode
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA' AND a.county = 'Santa Clara'
CriteriaQuery<Employee> q = cb.createQuery(Employee.class);
Root<Employee> emp = q.from(Employee.class);
q.select(emp)
    .where(cb.notEqual(emp.type(), Exempt.class));
SELECT e
FROM Employee e
WHERE TYPE(e) <> Exempt
CriteriaQuery<String> q = cb.createQuery(String.class);
Root<Course> c = q.from(Course.class);
ListJoin<Course, Student> w = c.join(Course_.studentWaitlist);
q.where(cb.equal(c.get(Course_.name), "Calculus"),
        cb.equal(w.index(), 0))
 .select(w.get(Student_.name));
SELECT w.name
FROM Course c JOIN c.studentWaitlist w
WHERE c.name = 'Calculus' AND INDEX(w) = 0
CriteriaQuery<BigDecimal> q = cb.createQuery(BigDecimal.class);
Root<Order> order = q.from(Order.class);
Join<Order, Item> item = order.join(Order_.lineItems);
Join<Order, Customer> cust = order.join(Order_.customer);

q.where(
    cb.equal(cust.get(Customer_.lastName), "Smith"),
    cb.equal(cust.get(Customer_.firstName), "John"));
q.select(cb.sum(item.get(Item_.price)));
SELECT SUM(i.price)
FROM Order o JOIN o.lineItems i JOIN o.customer c
WHERE c.lastName = 'Smith' AND c.firstName = 'John'
CriteriaQuery<Integer> q = cb.createQuery(Integer.class);
Root<Department> d = q.from(Department.class);
q
    .where(cb.equal(d.get(Department_.name), "Sales"))
    .select(cb.size(d.get(Department_.employees)));
SELECT SIZE(d.employees)
FROM Department d
WHERE d.name = 'Sales'
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Employee> e = q.from(Employee.class);
q.where(
    cb.equal(e.get(Employee_.department).get(Department_.name), "Engineering"));
q.multiselect(
    e.get(Employee_.name),
    cb.selectCase()
        .when(
            cb.equal(e.get(Employee_.rating), 1),
            cb.prod(e.get(Employee_.salary), 1.1))
        .when(
            cb.equal(e.get(Employee_.rating), 2),
            cb.prod(e.get(Employee_.salary), 1.2))
        .otherwise(cb.prod(e.get(Employee_.salary), 1.01)));
SELECT e.name,
    CASE
        WHEN e.rating = 1 THEN e.salary * 1.1
        WHEN e.rating = 2 THEN e.salary * 1.2
        ELSE e.salary * 1.01
    END
FROM EMPLOYEE e
WHERE e.department.name = 'Engineering'
CriteriaQuery<String> q = cb.createQuery(String.class);
Root<Employee> emp = q.from(Employee.class);
Join<Employee, FrequentFlierPlan> fp = emp.join(Employee_.frequentFlierPlan);

q.select(
    cb.<String>selectCase()
        .when(
            cb.gt(fp.get(FrequentFlierPlan_.annualMiles), 50000),
            cb.literal("Platinum"))
        .when(
            cb.gt(fp.get(FrequentFlierPlan_.annualMiles), 25000),
            cb.literal("Silver"))
        .otherwise(cb.nullLiteral(String.class)));
SELECT
    CASE
        WHEN fp.annualMiles > 50000 THEN 'Platinum'
        WHEN fp.annualMiles > 25000 THEN 'Gold'
        ELSE NULL
    END
CriteriaQuery<Customer> q = cb.createQuery(Customer.class);
Root<Customer> c = q.from(Customer.class);
ParameterExpression<Integer> param = cb.parameter(Integer.class);

q.select(c)
    .where(cb.equal(c.get(Customer_.status), param));
Root<Customer> c = q.from(Customer.class);
ParameterExpression<Integer> param = cb.parameter(Integer.class, "stat");
q.select(c).where(cb.equal(c.get(Customer_.status), param));
SELECT c FROM Customer c WHERE c.status = :stat
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<VideoStore> v = q.from(VideoStore.class);
MapJoin<VideoStore, Movie, Integer> inv = v.join(VideoStore_.videoInventory);

q.multiselect(
    v.get(VideoStore_.location).get(Address_.street),
    inv.key().get(Movie_.title),
    inv);
q.where(cb.equal(v.get(VideoStore_.location).get(Address_.zipcode), "94301"),
        cb.gt(inv, 0));
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<VideoStore> v = q.from(VideoStore.class);
MapJoin<VideoStore, Movie, Integer> inv = v.join(VideoStore_.videoInventory);

q.select(cb.tuple(
        v.get(VideoStore_.location).get(Address_.street),
        inv.key().get(Movie_.title),
        inv));
q.where(cb.equal(v.get(VideoStore_.location).get(Address_.zipcode), "94301"),
        cb.gt(inv, 0));
SELECT v.location.street, KEY(i).title, VALUE(i)
FROM VideoStore v JOIN v.videoInventory i
WHERE v.location.zipcode = '94301' AND VALUE(i) > 0
CriteriaQuery<Object> q = cb.createQuery();
Root<VideoStore> v = q.from(VideoStore.class);
MapJoin<VideoStore, Movie, Integer> inv = v.join(VideoStore_.videoInventory);

q.multiselect(
    v.get(VideoStore_.location).get(Address_.street),
    inv.key().get(Movie_.title),
    inv);

q.where(cb.equal(v.get(VideoStore_.location).get(Address_.zipcode), "94301"),
        cb.gt(inv, 0));
CriteriaQuery<Object> q = cb.createQuery();
Root<VideoStore> v = q.from(VideoStore.class);
MapJoin<VideoStore, Movie, Integer> inv = v.join(VideoStore_.videoInventory);

q.select(cb.array(
        v.get(VideoStore_.location).get(Address_.street),
        inv.key().get(Movie_.title),
        inv));
q.where(cb.equal(v.get(VideoStore_.location).get(Address_.zipcode), "94301"),
        cb.gt(inv, 0));
CriteriaQuery<CustomerDetails> q = cb.createQuery(CustomerDetails.class);
Root<Customer> c = q.from(Customer.class);
Join<Customer, Order> o = c.join(Customer_.orders);

q.where(cb.gt(o.get(Order_.quantity), 100));
q.select(cb.construct(
        CustomerDetails.class,
        c.get(Customer_.id),
        c.get(Customer_.status),
        o.get(Order_.quantity)));
SELECT NEW com.acme.example.CustomerDetails(c.id, c.status, o.quantity)
FROM Customer c JOIN c.orders o
WHERE o.quantity > 100
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Customer> c = q.from(Customer.class);
Join<Customer, Order> o = c.join(Customer_.orders);
Join<Customer, Address> a = c.join(Customer_.address);

q.where(cb.equal(c.get(Customer_.id), 97510));
q.multiselect(
        o.get(Order_.quantity).alias("quantity"),
        cb.prod(o.get(Order_.totalCost), 1.08).alias("taxedCost"),
        a.get(Address_.zipcode).alias("zipcode"));

TypedQuery<Tuple> typedQuery = em.createQuery(q);
Tuple result = typedQuery.getSingleResult();
Double cost = (Double)result.get("taxedCost");
// create criteria query instance, with root Customer
CriteriaQuery<Customer> q = cb.createQuery(Customer.class);
Root<Customer> goodCustomer = q.from(Customer.class);

// create subquery instance, with root Customer
// the Subquery object is typed according to its return type
Subquery<Double> sq = q.subquery(Double.class);
Root<Customer> customer = sq.from(Customer.class);

// the result of the first query depends on the subquery
q.where(cb.lt(
    goodCustomer.get(Customer_.balanceOwed),
    sq.select(cb.avg(customer.get(Customer_.balanceOwed)))));
q.select(goodCustomer);
SELECT goodCustomer
FROM Customer goodCustomer
WHERE goodCustomer.balanceOwed < (SELECT AVG(c.balanceOwed) FROM Customer c)
// create CriteriaQuery instance, with root Employee
CriteriaQuery<Employee> q = cb.createQuery(Employee.class);
Root<Employee> emp = q.from(Employee.class);

// create Subquery instance, with root Employee
Subquery<Employee> sq = q.subquery(Employee.class);
Root<Employee> spouseEmp = sq.from(Employee.class);

// the subquery references the root of the containing query
sq.where(cb.equal(spouseEmp, emp.get(Employee_.spouse)))
    .select(spouseEmp);

// an exists condition is applied to the subquery result:
q.where(cb.exists(sq));
q.select(emp).distinct(true);
SELECT DISTINCT emp
FROM Employee emp
WHERE EXISTS (
    SELECT spouseEmp
    FROM Employee spouseEmp
    WHERE spouseEmp = emp.spouse)
// create CriteriaQuery instance, with root Employee
CriteriaQuery<Employee> q = cb.createQuery(Employee.class);
Root<Employee> emp = q.from(Employee.class);

// create Subquery instance, with root Manager
Subquery<BigDecimal> sq = q.subquery(BigDecimal.class);
Root<Manager> manager = sq.from(Manager.class);

sq.select(manager.get(Manager_.salary));
sq.where(cb.equal(
    manager.get(Manager_.department),
    emp.get(Employee_.department)));

// an all expression is applied to the subquery result
q.select(emp)
    .where(cb.gt(emp.get(Employee_.salary), cb.all(sq)));
SELECT emp
FROM Employee emp
WHERE emp.salary > ALL (
    SELECT m.salary
    FROM Manager m
    WHERE m.department = emp.department)
CriteriaQuery<Customer> q = cb.createQuery(Customer.class);
Root<Customer> customer = q.from(Customer.class);
Subquery<Long> sq = q.subquery(Long.class);
Root<Customer> customerSub = sq.correlate(customer);
Join<Customer,Order> order = customerSub.join(Customer_.orders);

q.where(cb.gt(sq.select(cb.count(order)), 10))
    .select(customer);
SELECT c
FROM Customer c
WHERE (SELECT COUNT(o) FROM c.orders o) > 10
CriteriaQuery<Order> q = cb.createQuery(Order.class);
Root<Order> order = q.from(Order.class);
Subquery<Integer> sq = q.subquery(Integer.class);
Root<Order> orderSub = sq.correlate(order);
Join<Order,Customer> customer = orderSub.join(Order_.customer);
Join<Customer,Account> account = customer.join(Customer_.accounts);

sq.select(account.get(Account_.balance));
q.where(cb.lt(cb.literal(10000), cb.all(sq)));
CriteriaQuery<Order> q = cb.createQuery(Order.class);
Root<Order> order = q.from(Order.class);
Join<Order,Customer> customer = order.join(Order_.customer);
Subquery<Integer> sq = q.subquery(Integer.class);
Join<Order,Customer> customerSub = sq.correlate(customer);
Join<Customer,Account> account = customerSub.join(Customer_.accounts);

sq.select(account.get(Account_.balance));
q.where(cb.lt(cb.literal(10000), cb.all(sq)));
SELECT o
FROM Order o
WHERE 10000 < ALL (
    SELECT a.balance
    FROM o.customer c JOIN c.accounts a)
SELECT o
FROM Order o JOIN o.customer c
WHERE 10000 < ALL (
    SELECT a.balance
    FROM c.accounts a)
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Customer> customer = q.from(Customer.class);

q.groupBy(customer.get(Customer_.status));
q.having(cb.in(customer.get(Customer_.status)).value(1).value(2));
q.select(cb.tuple(
        customer.get(Customer_.status),
        cb.avg(customer.get(Customer_.filledOrderCount)),
        cb.count(customer)));
SELECT c.status, AVG(c.filledOrderCount), COUNT(c)
FROM Customer c
GROUP BY c.status
HAVING c.status IN (1, 2)
CriteriaQuery<Order> q = cb.createQuery(Order.class);
Root<Customer> c = q.from(Customer.class);
Join<Customer,Order> o = c.join(Customer_.orders);
Join<Customer,Address> a = c.join(Customer_.address);

q.where(cb.equal(a.get(Address_.state), "CA"));
q.select(o);
q.orderBy(cb.desc(o.get(Order_.quantity)),
    cb.asc(o.get(Order_.totalCost)));
SELECT o
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA'
ORDER BY o.quantity DESC, o.totalcost
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Customer> c = q.from(Customer.class);
Join<Customer, Order> o = c.join(Customer_.orders);
Join<Customer, Address> a = c.join(Customer_.address);

q.where(cb.equal(a.get(Address_.state), "CA"));
q.orderBy(cb.asc(o.get(Order_.quantity)),
    cb.asc(a.get(Address_.zipcode)));
q.multiselect(o.get(Order_.quantity),
    a.get(Address_.zipcode));
SELECT o.quantity, a.zipcode
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA'
ORDER BY o.quantity, a.zipcode
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Customer> c = q.from(Customer.class);
Join<Customer, Order> o = c.join(Customer_.orders);
Join<Customer, Address> a = c.join(Customer_.address);

q.where(cb.equal(a.get(Address_.state), "CA"));
q.orderBy(cb.asc(o.get(Order_.quantity)),
    cb.asc(a.get(Address_.zipcode)));
q.select(cb.tuple(o.get(Order_.quantity),
    a.get(Address_.zipcode)));
CriteriaQuery<Object[]> q = cb.createQuery(Object[].class);
Root<Customer> c = q.from(Customer.class);
Join<Customer, Order> o = c.join(Customer_.orders);
Join<Customer, Address> a = c.join(Customer_.address);

q.where(cb.equal(a.get(Address_.state), "CA"),
    cb.equal(a.get(Address_.county), "Santa Clara"));
q.select(cb.array(o.get(Order_.quantity),
    cb.prod(o.get(Order_.totalCost), 1.08),
    a.get(Address_.zipcode)));
q.orderBy(cb.asc(o.get(Order_.quantity)),
    cb.asc(cb.prod(o.get(Order_.totalCost), 1.08)),
    cb.asc(a.get(Address_.zipcode)));
SELECT o.quantity, o.totalCost * 1.08 AS taxedCost, a.zipcode
FROM Customer c JOIN c.orders o JOIN c.address a
WHERE a.state = 'CA' AND a.county = 'Santa Clara'
ORDER BY o.quantity, taxedCost, a.zipcode
CriteriaUpdate<Customer> q = cb.createCriteriaUpdate(Customer.class);
Root<Customer> c = q.from(Customer.class);

q.set(c.get(Customer_.status), "outstanding")
    .where(cb.lt(c.get(Customer_.balance), 10000));
UPDATE Customer c
SET c.status = 'outstanding'
WHERE c.balance < 10000
CriteriaUpdate<Employee> q = cb.createCriteriaUpdate(Employee.class);
Root<Employee> e = q.from(Employee.class);

q.set(e.get(Employee_.address).get(Address_.building), 22)
    .where(
        cb.equal(e.get(Employee_.address).get(Address_.building), 14),
        cb.equal(e.get(Employee_.address).get(Address_.city), "Santa Clara"),
        cb.equal(e.get(Employee_.project).get(Project_.name), "Jakarta EE"));
UPDATE Employee e
SET e.address.building = 22
WHERE e.address.building = 14
    AND e.address.city = 'Santa Clara'
    AND e.project.name = 'Jakarta EE'
CriteriaUpdate<Employee> q = cb.createCriteriaUpdate(Employee.class);
Root<Employee> e = q.from(Employee.class);

q.set(e.get(Employee_.salary), cb.prod(e.get(Employee_.salary), 1.1f))
    .set(e.get(Employee_.commission), cb.prod(e.get(Employee_.commission), 1.1f))
    .set(e.get(Employee_.bonus), cb.sum(e.get(Employee_.bonus), 5000))
    .where(cb.equal(e.get(Employee_.dept).get(Department_.name), "Sales"));
UPDATE Employee e
SET e.salary = e.salary * 1.1,
    e.commission = e.commission * 1.1,
    e.bonus = e.bonus + 5000
WHERE e.dept.name = 'Sales'
CriteriaDelete<Customer> q = cb.createCriteriaDelete(Customer.class);
Root<Customer> c = q.from(Customer.class);

q.where(
    cb.equal(c.get(Customer_.status), "inactive"),
    cb.isEmpty(c.get(Customer_.orders)));
DELETE
FROM Customer c
WHERE c.status = 'inactive'
    AND c.orders IS EMPTY
EntityManager em = ...;

Metamodel mm = em.getMetamodel();
EntityType<Employee> emp_ =mm.entity(Employee.class);
EmbeddableType<ContactInfo> cinfo_ = mm.embeddable(ContactInfo.class);
EntityType<Phone> phone_ = mm.entity(Phone.class);
EmbeddableType<Address> addr_ = mm.embeddable(Address.class);

CriteriaQuery<Vendor> q = cb.createQuery(Vendor.class);
Root<Employee> emp = q.from(Employee.class);
Join<Employee, ContactInfo> cinfo =
    emp.join(emp_.getSingularAttribute("contactInfo", ContactInfo.class));
Join<ContactInfo, Phone> p =
    cinfo.join(cinfo_.getSingularAttribute("phones", Phone.class));
q.where(
    cb.equal(emp.get(emp_.getSingularAttribute("contactInfo", ContactInfo.class))
        .get(cinfo_.getSingularAttribute("address", Address.class))
        .get(addr_.getSingularAttribute("zipcode", String.class)), "95054"))
    .select(p.get(phone_.getSingularAttribute("vendor",Vendor.class)));
EntityManager em = ...;
Metamodel mm = em.getMetamodel();

EntityType<Item> item_ = mm.entity(Item.class);
CriteriaQuery<Tuple> q = cb.createTupleQuery();
Root<Item> item = q.from(Item.class);
MapJoin<Item, String, Object> photo =
    item.join(item_.getMap("photos", String.class, Object.class));
q.multiselect(
    item.get(item_.getSingularAttribute("name", String.class)), photo)
        .where(cb.like(photo.key(), "%egret%"));
CriteriaBuilder cb = ...
CriteriaQuery<String> q = cb.createQuery(String.class);
Root<Customer> cust = q.from(Customer.class);
Join<Order, Item> item = cust.join("orders").join("lineItems");
q.select(cust.<String>get("name"))
    .where(cb.equal(item.get("product").get("productType"), "printer"));
SELECT c.name
FROM Customer c JOIN c.orders o JOIN o.lineItems i
WHERE i.product.productType = 'printer'
CriteriaBuilder cb = ...
CriteriaQuery q = cb.createQuery();
Root cust = q.from(Customer.class);
Join item = cust.join("orders").join("lineItems");
q.select(cust.get("name")).where(
    cb.equal(item.get("product").get("productType"),"printer"));
CriteriaQuery<Customer> q = cb.createQuery(Customer.class);
Root<Customer> cust = q.from(Customer.class);
Join<Customer,Order> order = cust.join("orders", JoinType.LEFT);
q.where(cb.equal(cust.get("status"), 1))
    .select(cust);
SELECT c FROM Customer c LEFT JOIN c.orders o
WHERE c.status = 1
CriteriaQuery<Vendor> q = cb.createQuery(Vendor.class);
Root<Employee> emp = q.from(Employee.class);
Join<ContactInfo, Phone> phone = emp.join("contactInfo").join("phones");
q.where(cb.equal(emp.get("contactInfo")
    .get("address")
    .get("zipcode"), "95054"));
q.select(phone.<Vendor>get("vendor"));
SELECT p.vendor
FROM Employee e JOIN e.contactInfo.phones p
WHERE e.contactInfo.address.zipcode = '95054'
CriteriaQuery<Object> q = cb.createQuery();
Root<Item> item = q.from(Item.class);
MapJoin<Item, String, Object> photo = item.joinMap("photos");
q.multiselect(item.get("name"), photo)
    .where(cb.like(photo.key(), "%egret%"));
SELECT i.name, p
FROM Item i JOIN i.photos p
WHERE KEY(p) LIKE '%egret%'
CriteriaQuery<Customer> q = cb.createQuery(Customer.class);
Root<Customer> c = q.from(Customer.class);

Predicate pred = cb.equal(c.get(Customer_.address).get(Address_.city),"Chicago");

q.select(c);
q.where(pred);
Predicate pred2 = cb.gt(c.get(Customer_.balanceOwed), 1000);
q.where(pred2);
@PersistenceContext
EntityManager em;

@PersistenceContext(type=PersistenceContextType.EXTENDED)
EntityManager orderEM;
@Stateless
@PersistenceContext(name="OrderEM")
public class MySessionBean implements MyInterface {
    @Resource
    SessionContext ctx;

    public void doSomething() {
        EntityManager em = (EntityManager)ctx.lookup("OrderEM");

        // ...
    }
}
@PersistenceUnit
EntityManagerFactory emf;
EntityManagerFactory emf =
    jakarta.persistence.Persistence.createEntityManagerFactory("Order");
EntityManager em = emf.createEntityManager();
DataSource datasource = (DataSource)
        new InitialContext()
                .lookup("java:global/jdbc/MyOrderDB");
EntityManagerFactory emf =
        new PersistenceConfiguration()
                .name("OrderManagement")
                .jtaDataSource(datasource)
                .mappingFile("ormap.xml")
                .managedClass(Order.class)
                .managedClass(Customer.class)
                .createEntityManagerFactory();
import jakarta.persistence.*;

public class PasswordChanger {
    public static void main (String[] args) {
        EntityManagerFactory emf =
            Persistence.createEntityManagerFactory("Order");
        EntityManager em = emf.createEntityManager();
        em.getTransaction().begin();

        User user = em.createQuery
            ("SELECT u FROM User u WHERE u.name=:name AND u.pass=:pass", User.class)
            .setParameter("name", args[0])
            .setParameter("pass", args[1])
            .getSingleResult();

        user.setPassword(args[2]);

        em.getTransaction().commit();
        em.close();
        emf.close();
    }
}
entityManagerFactory.runInTransaction(entityManager -> {
    User user = em.createQuery
        ("SELECT u FROM User u WHERE u.name=:name AND u.pass=:pass", User.class)
        .setParameter("name", args[0])
        .setParameter("pass", args[1])
        .getSingleResult();

    user.setPassword(args[2]);
})
@Stateless
public class ShoppingCartImpl implements ShoppingCart {
    @PersistenceContext
    EntityManager em;

    public Order getOrder(Long id) {
        Order order = em.find(Order.class, id);
        order.getLineItems();
        return order;
    }

    public Product getProduct(String name) {
        return (Product) em.createQuery("select p from Product p where p.name = : name")
               .setParameter("name", name)
               .getSingleResult();
    }

    public LineItem createLineItem(Order order, Product product, int quantity) {
        LineItem li = new LineItem(order, product, quantity);
        order.getLineItems().add(li);
        em.persist(li);
        return li;
    }
}
/*
 * An extended transaction context is used. The entities remain
 * managed in the persistence context across multiple transactions.
 */
@Stateful
@Transaction(REQUIRES_NEW)
public class ShoppingCartImpl implements ShoppingCart {
    @PersistenceContext(type = EXTENDED)
    EntityManager em;

    private Order order;
    private Product product;

    public void initOrder(Long id) {
        order = em.find(Order.class, id);
    }

    public void initProduct(String name) {
        product = (Product) em.createQuery("select p from Product p where p.name = : name")
                  .setParameter("name", name)
                  .getSingleResult();
    }

    public LineItem createLineItem(int quantity) {
        LineItem li = new LineItem(order, product, quantity);
        order.getLineItems().add(li);
        em.persist(li);
        return li;
    }
}
/*
 * Container-managed transaction demarcation is used.
 * The session bean creates and closes an entity manager
 * in each business method.
 */
@Stateless
public class ShoppingCartImpl implements ShoppingCart {
    @PersistenceUnit
    private EntityManagerFactory emf;

    public Order getOrder(Long id) {
        EntityManager em = emf.createEntityManager();
        Order order = em.find(Order.class, id);
        order.getLineItems();
        em.close();
        return order;
    }

    public Product getProduct() {
        EntityManager em = emf.createEntityManager();
        Product product = (Product)
                          em.createQuery("select p from Product p where p.name = :name")
                          .setParameter("name", name)
                          .getSingleResult();
        em.close();
        return product;
    }

    public LineItem createLineItem(Order order, Product product, int quantity) {
        EntityManager em = emf.createEntityManager();
        LineItem li = new LineItem(order, product, quantity);
        order.getLineItems().add(li);
        em.persist(li);
        em.close();
        return li; // remains managed until JTA transaction ends
    }
}
/*
 * Container-managed transaction demarcation is used.
 * The session bean creates entity manager in PostConstruct
 * method and clears persistence context at the end of each
 * business method.
 */
@Stateless
public class ShoppingCartImpl implements ShoppingCart {
    @PersistenceUnit
    private EntityManagerFactory emf;

    private EntityManager em;

    @PostConstruct
    public void init() {
        em = emf.createEntityManager();
    }

    public Order getOrder(Long id) {
        Order order = em.find(Order.class, id);
        order.getLineItems();
        em.clear(); // entities are detached
        return order;
    }

    public Product getProduct() {
        Product product = (Product)
                          em.createQuery("select p from Product p where p.name = :name")
                          .setParameter("name", name)
                          .getSingleResult();
        em.clear();
        return product;
    }

    public LineItem createLineItem(Order order, Product product, int quantity) {
        em.joinTransaction();
        LineItem li = new LineItem(order, product, quantity);
        order.getLineItems().add(li);
        em.persist(li);
        // persistence context is flushed to database;
        // all updates will be committed to database on tx commit
        em.flush();
        // entities in persistence context are detached
        em.clear();
        return li;
    }

    @PreDestroy
    public void destroy() {
        em.close();
    }
}
/*
 * Container-managed transaction demarcation is used.
 * Entities remain managed until the entity manager is closed.
 */
@Stateful
public class ShoppingCartImpl implements ShoppingCart {
    @PersistenceUnit
    private EntityManagerFactory emf;

    private EntityManager em;

    private Order order;

    private Product product;

    @PostConstruct
    public void init() {
        em = emf.createEntityManager();
    }

    public void initOrder(Long id) {
        order = em.find(Order.class, id);
    }

    public void initProduct(String name) {
        product = (Product) em.createQuery("select p from Product p where p.name = : name")
                  .setParameter("name", name)
                  .getSingleResult();
    }

    public LineItem createLineItem(int quantity) {
        em.joinTransaction();
        LineItem li = new LineItem(order, product, quantity);
        order.getLineItems().add(li);
        em.persist(li);
        return li;
    }

    @Remove
    public void destroy() {
        em.close();
    }
}
// Usage in an ordinary Java class
public class ShoppingImpl {
    private EntityManager em;
    private EntityManagerFactory emf;

    public ShoppingCart() {
        emf = Persistence.createEntityManagerFactory("orderMgt");
        em = emf.createEntityManager();
    }

    private Order order;
    private Product product;

    public void initOrder(Long id) {
        order = em.find(Order.class, id);
    }

    public void initProduct(String name) {
        product = (Product) em.createQuery("select p from Product p where p.name = : name")
                  .setParameter("name", name)
                  .getSingleResult();
    }

    public LineItem createLineItem(int quantity) {
        em.getTransaction().begin();
        LineItem li = new LineItem(order, product, quantity);
        order.getLineItems().add(li);
        em.persist(li);
        em.getTransaction().commit();
        return li;
    }

    public void destroy() {
        em.close();
        emf.close();
    }
}
<persistence>
    <persistence-unit name="OrderManagement">
        <description>
            This unit manages orders and customers.
            It does not rely on any vendor-specific features and can
            therefore be deployed to any persistence provider.
        </description>
        <jta-data-source>jdbc/MyOrderDB</jta-data-source>
        <mapping-file>ormap.xml</mapping-file>
        <jar-file>MyOrderApp.jar</jar-file>
        <class>com.widgets.Order</class>
        <class>com.widgets.Customer</class>
    </persistence-unit>
</persistence>
<persistence>
    <persistence-unit name="OrderManagement2">
        <description>
            This unit manages inventory for auto parts.
            It depends on features provided by the
            com.acme.persistence implementation.
        </description>
        <provider>com.acme.AcmePersistence</provider>
        <jta-data-source>jdbc/MyPartDB</jta-data-source>
        <mapping-file>ormap2.xml</mapping-file>
        <jar-file>MyPartsApp.jar</jar-file>
        <properties>
            <property name="com.acme.persistence.sql-logging" value="on"/>
        </properties>
    </persistence-unit>
</persistence>
app.ear
    lib/earEntities.jar
    earRootPUnit.jar (with META-INF/persistence.xml)
<jar-file>lib/earEntities.jar</jar-file>
app.ear
    lib/earEntities.jar
    lib/earLibPUnit.jar (with META-INF/persistence.xml)
<jar-file>earEntities.jar</jar-file>
app.ear
    lib/earEntities.jar
    ejbjar.jar (with META-INF/persistence.xml)
<jar-file>lib/earEntities.jar</jar-file>
app.ear
    war1.war
        WEB-INF/lib/warEntities.jar
        WEB-INF/lib/warPUnit.jar (with META-INF/persistence.xml)
<jar-file>warEntities.jar</jar-file>
app.ear
    war2.war
        WEB-INF/lib/warEntities.jar
        WEB-INF/classes/META-INF/persistence.xml
<jar-file>lib/warEntities.jar</jar-file>
app.ear
    lib/earEntities.jar
    war2.war
        WEB-INF/classes/META-INF/persistence.xml
<jar-file>../../lib/earEntities.jar</jar-file>
app.ear
    lib/earEntities.jar
    war1.war
        WEB-INF/lib/warPUnit.jar (with META-INF/persistence.xml)
<jar-file>../../../lib/earEntities.jar</jar-file>
<persistence-unit name="OrderManagement"/>
<persistence-unit name="OrderManagement2">
    <mapping-file>mappings.xml</mapping-file>
</persistence-unit>
<persistence-unit name="OrderManagement3">
    <jar-file>order.jar</jar-file>
    <jar-file>order-supplemental.jar</jar-file>
</persistence-unit>
<persistence-unit name="OrderManagement4" transaction-type=RESOURCE_LOCAL>
    <non-jta-data-source>java:app/jdbc/MyDB</non-jta-data-source>
    <mapping-file>order-mappings.xml</mapping-file>
    <class>com.acme.Order</class>
    <class>com.acme.Customer</class>
    <class>com.acme.Item</class>
    <exclude-unlisted-classes/>
</persistence-unit>
<persistence-unit name="OrderManagement5">
    <provider>com.acme.AcmePersistence</provider>
    <mapping-file>order1.xml</mapping-file>
    <mapping-file>order2.xml</mapping-file>
    <jar-file>order.jar</jar-file>
    <jar-file>order-supplemental.jar</jar-file>
</persistence-unit>
<?xml version="1.0" encoding="UTF-8"?>

<!-- persistence.xml schema -->
<xsd:schema targetNamespace="https://jakarta.ee/xml/ns/persistence"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:persistence="https://jakarta.ee/xml/ns/persistence"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"
  version="3.2">

   <xsd:annotation>
     <xsd:documentation><![CDATA[

     This is the XML Schema for the persistence configuration file.
     The file must be named "META-INF/persistence.xml" in the
     persistence archive.

     Persistence configuration files must indicate
     the persistence schema by using the persistence namespace:

     https://jakarta.ee/xml/ns/persistence

     and indicate the version of the schema by
     using the version element as shown below:

      <persistence xmlns="https://jakarta.ee/xml/ns/persistence"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence
          https://jakarta.ee/xml/ns/persistence/persistence_3_2.xsd"
        version="3.2">
          ...
      </persistence>

    ]]></xsd:documentation>
  </xsd:annotation>

  <xsd:simpleType name="versionType">
    <xsd:restriction base="xsd:token">
      <xsd:pattern value="[0-9]+(\.[0-9]+)*"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:element name="persistence">
    <xsd:complexType>
      <xsd:sequence>

        <!-- **************************************************** -->

        <xsd:element name="persistence-unit"
                     minOccurs="1" maxOccurs="unbounded">
          <xsd:complexType>
            <xsd:annotation>
              <xsd:documentation>

                Configuration of a persistence unit.

              </xsd:documentation>
            </xsd:annotation>
            <xsd:sequence>

            <!-- **************************************************** -->

              <xsd:element name="description" type="xsd:string"
                           minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    Description of this persistence unit.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="provider" type="xsd:string"
                           minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    Provider class that supplies EntityManagers for this
                    persistence unit.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="qualifier" type="xsd:string"
                           minOccurs="0" maxOccurs="unbounded">
                <xsd:annotation>
                  <xsd:documentation>

                    Qualifier annotation class used for dependency injection.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="scope" type="xsd:string"
                           minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    Scope annotation class used for dependency injection.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="jta-data-source" type="xsd:string"
                           minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    The container-specific name of the JTA datasource to use.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="non-jta-data-source" type="xsd:string"
                           minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    The container-specific name of a non-JTA datasource to use.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="mapping-file" type="xsd:string"
                           minOccurs="0" maxOccurs="unbounded">
                <xsd:annotation>
                  <xsd:documentation>

                    File containing mapping information. Loaded as a resource
                    by the persistence provider.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="jar-file" type="xsd:string"
                           minOccurs="0" maxOccurs="unbounded">
                <xsd:annotation>
                  <xsd:documentation>

                    Jar file that is to be scanned for managed classes.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="class" type="xsd:string"
                           minOccurs="0" maxOccurs="unbounded">
                <xsd:annotation>
                  <xsd:documentation>

                    Managed class to be included in the persistence unit and
                    to scan for annotations.  It should be annotated
                    with either @Entity, @Embeddable or @MappedSuperclass.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="exclude-unlisted-classes" type="xsd:boolean"
                           default="true" minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    When set to true then only listed classes and jars will
                    be scanned for persistent classes, otherwise the
                    enclosing jar or directory will also be scanned.
                    Not applicable to Java SE persistence units.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="shared-cache-mode"
                           type="persistence:persistence-unit-caching-type"
                           minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    Defines whether caching is enabled for the
                    persistence unit if caching is supported by the
                    persistence provider. When set to ALL, all entities
                    will be cached. When set to NONE, no entities will
                    be cached. When set to ENABLE_SELECTIVE, only entities
                    specified as cacheable will be cached. When set to
                    DISABLE_SELECTIVE, entities specified as not cacheable
                    will not be cached. When not specified or when set to
                    UNSPECIFIED, provider defaults may apply.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="validation-mode"
                           type="persistence:persistence-unit-validation-mode-type"
                           minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    The validation mode to be used for the persistence unit.

                  </xsd:documentation>
                </xsd:annotation>
              </xsd:element>

              <!-- **************************************************** -->

              <xsd:element name="properties" minOccurs="0">
                <xsd:annotation>
                  <xsd:documentation>

                    A list of standard and vendor-specific properties
                    and hints.

                  </xsd:documentation>
                </xsd:annotation>
                <xsd:complexType>
                  <xsd:sequence>
                    <xsd:element name="property"
                                 minOccurs="0" maxOccurs="unbounded">
                      <xsd:annotation>
                        <xsd:documentation>
                          A name-value pair.
                        </xsd:documentation>
                      </xsd:annotation>
                      <xsd:complexType>
                        <xsd:attribute name="name" type="xsd:string"
                                       use="required"/>
                        <xsd:attribute name="value" type="xsd:string"
                                       use="required"/>
                      </xsd:complexType>
                    </xsd:element>
                  </xsd:sequence>
                </xsd:complexType>
              </xsd:element>

              <xsd:any namespace="##other" processContents="lax"
                       minOccurs="0" maxOccurs="unbounded">
                <xsd:annotation>
                  <xsd:documentation>
                    An extension point for integration related configuration, e.g. cdi:
                    <!--
                    <persistence-unit name="my-unit" xmlns:cdi="https://jakarta.ee/xml/ns/persistence-cdi">
                      ...
                      <cdi:scope>com.example.jpa.ACustomScope</cdi:scope>
                      <cdi:qualifier>com.example.jpa.CustomQualifier</cdi:qualifier>
                    </persistence-unit>
                    -->
                  </xsd:documentation>
                </xsd:annotation>
              </xsd:any>
            </xsd:sequence>

            <!-- **************************************************** -->

            <xsd:attribute name="name" type="xsd:string" use="required">
              <xsd:annotation>
                <xsd:documentation>

                  Name used in code to reference this persistence unit.

                </xsd:documentation>
              </xsd:annotation>
            </xsd:attribute>

            <!-- **************************************************** -->

            <xsd:attribute name="transaction-type"
                           type="persistence:persistence-unit-transaction-type">
              <xsd:annotation>
                <xsd:documentation>

                  Type of transactions used by EntityManagers from this
                  persistence unit.

                </xsd:documentation>
              </xsd:annotation>
            </xsd:attribute>

          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
      <xsd:attribute name="version" type="persistence:versionType"
                     fixed="3.2" use="required"/>
    </xsd:complexType>
  </xsd:element>

  <!-- **************************************************** -->

  <xsd:simpleType name="persistence-unit-transaction-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum PersistenceUnitTransactionType {JTA, RESOURCE_LOCAL};

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="JTA"/>
      <xsd:enumeration value="RESOURCE_LOCAL"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:simpleType name="persistence-unit-caching-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum SharedCacheMode { ALL, NONE, ENABLE_SELECTIVE, DISABLE_SELECTIVE, UNSPECIFIED};

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="ALL"/>
      <xsd:enumeration value="NONE"/>
      <xsd:enumeration value="ENABLE_SELECTIVE"/>
      <xsd:enumeration value="DISABLE_SELECTIVE"/>
      <xsd:enumeration value="UNSPECIFIED"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:simpleType name="persistence-unit-validation-mode-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum ValidationMode { AUTO, CALLBACK, NONE};

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="AUTO"/>
      <xsd:enumeration value="CALLBACK"/>
      <xsd:enumeration value="NONE"/>
    </xsd:restriction>
  </xsd:simpleType>

</xsd:schema>
acme.jar
    META-INF/services/jakarta.persistence.spi.PersistenceProvider
    com.acme.PersistenceProvider
    ...
/**
 * Specifies whether entity managers created by the
 * {@link jakarta.persistence.EntityManagerFactory}
 * are JTA or resource-local entity managers.
 *
 * @since 1.0
 *
 * @deprecated replaced by
 * {@link jakarta.persistence.PersistenceUnitTransactionType}
 */
@Deprecated(since = "3.2", forRemoval = true)
public enum PersistenceUnitTransactionType {

    /** JTA entity managers are created. */
    JTA,

    /** Resource-local entity managers are created. */
    RESOURCE_LOCAL
}
import jakarta.persistence.spi.PersistenceUnitInfo;

/**
 * Specifies how the provider must use a second-level cache for the
 * persistence unit. Corresponds to the value of the {@code persistence.xml}
 * {@code shared-cache-mode} element, and returned as the result of
 * {@link PersistenceUnitInfo#getSharedCacheMode()}.
 * 
 * @since 2.0
 */
public enum SharedCacheMode {

    /**
     * All entities and entity-related state and data are cached.
     */
    ALL, 

    /**
     * Caching is disabled for the persistence unit.
     */
    NONE, 

    /**
     * Caching is enabled for all entities for which
     * {@link Cacheable Cacheable(true)} is specified. All other
     * entities are not cached.
     */
    ENABLE_SELECTIVE, 

    /**
     * Caching is enabled for all entities except those for which
     * {@link Cacheable Cacheable(false)} is specified. Entities
     * for which {@code Cacheable(false)} is specified are not cached.
     */
    DISABLE_SELECTIVE, 

    /**
     * Caching behavior is undefined: provider-specific defaults may apply.
     */
    UNSPECIFIED
}
/**
 * The validation mode to be used by the provider for the persistence
 * unit.
 * 
 * @since 2.0
 */
public enum ValidationMode {

    /**
     * If a Bean Validation provider is present in the environment,
     * the persistence provider must perform the automatic validation
     * of entities. If no Bean Validation provider is present in the
     * environment, no lifecycle event validation takes place.
     * This is the default behavior.
     */
    AUTO,

    /**
     * The persistence provider must perform the lifecycle event
     * validation. It is an error if there is no Bean Validation
     * provider present in the environment.
     */
    CALLBACK,

    /**
     * The persistence provider must not perform lifecycle event
     * validation.
     */
    NONE
}
@Documented
@Target(TYPE)
@Retention(RUNTIME)
public @interface Entity {
    String name() default "";
}
@Target({TYPE})
@Retention(RUNTIME)
public @interface EntityListeners {
    Class[] value();
}
@Target({TYPE})
@Retention(RUNTIME)
public @interface ExcludeSuperclassListeners {
}
@Target({TYPE})
@Retention(RUNTIME)
public @interface ExcludeDefaultListeners {
}
@Target({METHOD})
@Retention(RUNTIME)
public @interface PrePersist {}

@Target({METHOD})
@Retention(RUNTIME)
public @interface PostPersist {}

@Target({METHOD})
@Retention(RUNTIME)
public @interface PreRemove {}

@Target({METHOD})
@Retention(RUNTIME)
public @interface PostRemove {}

@Target({METHOD})
@Retention(RUNTIME)
public @interface PreUpdate {}

@Target({METHOD})
@Retention(RUNTIME)
public @interface PostUpdate {}

@Target({METHOD})
@Retention(RUNTIME)
public @interface PostLoad {}
@Target({TYPE})
@Retention(RUNTIME)
@Repeatable(NamedEntityGraphs.class)
public @interface NamedEntityGraph {
    String name() default "";
    NamedAttributeNode[] attributeNodes() default {};
    boolean includeAllAttributes() default false;
    NamedSubgraph[] subgraphs() default {};
    NamedSubgraph[] subclassSubgraphs() default {};
}

@Target({TYPE})
@Retention(RUNTIME)
public @interface NamedEntityGraphs {
    NamedEntityGraph[] value();
}
@Target({})
@Retention(RUNTIME)
public @interface NamedAttributeNode {
    String value();
    String subgraph() default "";
    String keySubgraph() default "";
}
@Target({})
@Retention(RUNTIME)
public @interface NamedSubgraph {
    String name();
    Class type() default void.class;
    NamedAttributeNode[] attributeNodes();
}
@Target({TYPE})
@Retention(RUNTIME)
@Repeatable(NamedQueries.class)
public @interface NamedQuery {
    String name();
    String query();
    Class<?> resultClass() default void.class;
    LockModeType lockMode() default NONE;
    QueryHint[] hints() default {};
}

@Target({})
@Retention(RUNTIME)
public @interface QueryHint {
    String name();
    String value();
}

@Target({TYPE})
@Retention(RUNTIME)
public @interface NamedQueries {
    NamedQuery[] value ();
}
@Target({TYPE})
@Retention(RUNTIME)
@Repeatable(NamedNativeQueries.class)
public @interface NamedNativeQuery {
    String name();
    String query();
    QueryHint[] hints() default {};
    Class resultClass() default void.class;
    String resultSetMapping() default "";
    EntityResult[] entities() default {};
    ConstructorResult[] classes() default {};
    ColumnResult[] columns() default {};
}

@Target({TYPE})
@Retention(RUNTIME)
public @interface NamedNativeQueries {
    NamedNativeQuery[] value ();
}
@Target(TYPE)
@Retention(RUNTIME)
@Repeatable(NamedStoredProcedureQueries.class)
public @interface NamedStoredProcedureQuery {
    String name();
    String procedureName();
    StoredProcedureParameter[] parameters() default {};
    Class[] resultClasses() default {};
    String[] resultSetMappings() default {};
    QueryHint[] hints() default {};
}

@Target(TYPE)
@Retention(RUNTIME)
public @interface NamedStoredProcedureQueries {
    NamedStoredProcedureQuery [] value;
}
@Target({})
@Retention(RUNTIME)
public @interface StoredProcedureParameter {
    String name() default "";
    ParameterMode mode() default ParameterMode.IN;
    Class type();
}

public enum ParameterMode {
    IN,
    INOUT,
    OUT,
    REF_CURSOR
}
@Target({TYPE})
@Retention(RUNTIME)
@Repeatable(SqlResultSetMappings.class)
public @interface SqlResultSetMapping {
    String name();
    EntityResult[] entities() default {};
    ConstructorResult[] classes() default {};
    ColumnResult[] columns() default {};
}

@Target({TYPE})
@Retention(RUNTIME)
public @interface SqlResultSetMappings {
    SqlResultSetMapping[] value();
}
@Target({})
@Retention(RUNTIME)
public @interface EntityResult {
    Class entityClass();
    LockModeType lockMode() default LockModeType.OPTIMISTIC;
    FieldResult[] fields() default {};
    String discriminatorColumn() default "";
}
@Target({})
@Retention(RUNTIME)
public @interface FieldResult {
    String name();
    String column();
}
@Target(value={})
@Retention(RUNTIME)
public @interface ConstructorResult {
    Class targetClass();
    ColumnResult[] columns();
}
@Target({})
@Retention(RUNTIME)
public @interface ColumnResult {
    String name();
    Class type() default void.class;
}
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
@Repeatable(PersistenceContexts.class)
public @interface PersistenceContext {
    String name() default "";
    String unitName() default "";
    PersistenceContextType type() default TRANSACTION;
    SynchronizationType synchronization() default SYNCHRONIZED;
    PersistenceProperty[] properties() default {};
}

public enum PersistenceContextType {
    TRANSACTION,
    EXTENDED
}

public enum SynchronizationType {
    SYNCHRONIZED,
    UNSYNCHRONIZED
}

@Target({})
@Retention(RUNTIME)
public @interface PersistenceProperty {
    String name();
    String value();
}
@Target({TYPE})
@Retention(RUNTIME)
public @interface PersistenceContexts {
    PersistenceContext[] value();
}
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
@Repeatable(PersistenceUnits.class)
public @interface PersistenceUnit {
    String name() default "";
    String unitName() default "";
}
@Target(TYPE)
@Retention(RUNTIME)
public @interface PersistenceUnits {
    PersistenceUnit[] value();
}
@Target({TYPE})
@Retention(RUNTIME)
public @interface Converter {
    boolean autoApply() default false;
}
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface Access {
    AccessType value();
}
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
@Repeatable(AssociationOverrides.class)
public @interface AssociationOverride {
    String name();

    JoinColumn[] joinColumns() default {};

    ForeignKey foreignKey() default

    @ForeignKey(PROVIDER_DEFAULT);
    JoinTable joinTable() default @JoinTable;
}
@MappedSuperclass
public class Employee {
    @Id
    protected Integer id;

    @Version
    protected Integer version;

    @ManyToOne
    protected Address address;

    public Integer getId() { ... }

    public void setId(Integer id) { ... }

    public Address getAddress() { ... }

    public void setAddress(Address address) { ... }
}

@Entity
@AssociationOverride(name="address", joinColumns=@JoinColumn(name="ADDR_ID"))
public class PartTimeEmployee extends Employee {
    // address field mapping overridden to ADDR_ID foreign key
    @Column(name="WAGE")
    protected Float hourlyWage;

    public Float getHourlyWage() { ... }

    public void setHourlyWage(Float wage) { ... }
}
@Entity
public class Employee {
    @Id
    int id;

    @AssociationOverride(
        name="phoneNumbers",
        joinTable=@JoinTable(
            name="EMPPHONES",
            joinColumns=@JoinColumn(name="EMP"),
            inverseJoinColumns=@JoinColumn(name="PHONE")
        )
    )
    @Embedded
    ContactInfo contactInfo;

    // ...
}

@Embeddable
public class ContactInfo {
    @ManyToOne Address address; // Unidirectional
    @ManyToMany(targetEntity=PhoneNumber.class)
    List phoneNumbers;
}

@Entity
public class PhoneNumber {
    @Id
    int number;

    @ManyToMany(mappedBy="contactInfo.phoneNumbers")
    Collection<Employee> employees;
}
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface AssociationOverrides {
    AssociationOverride[] value();
}
@MappedSuperclass
public class Employee {
    @Id
    protected Integer id;

    @Version
    protected Integer version;

    @ManyToOne
    protected Address address;

    @OneToOne
    protected Locker locker;

    public Integer getId() { ... }

    public void setId(Integer id) { ... }

    public Address getAddress() { ... }

    public void setAddress(Address address) { ... }

    public Locker getLocker() { ... }

    public void setLocker(Locker locker) { ... }
}

@Entity
@AssociationOverrides({
    @AssociationOverride(name="address", joinColumns=@JoinColumn("ADDR_ID")),
    @AssociationOverride(name="locker", joinColumns=@JoinColumn("LCKR_ID"))})
public PartTimeEmployee { ... }
@Entity
@AssociationOverride(name="address", joinColumns=@JoinColumn("ADDR_ID"))
@AssociationOverride(name="locker", joinColumns=@JoinColumn("LCKR_ID"))
public PartTimeEmployee { ... }
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
@Repeatable(AttributeOverrides.class)
public @interface AttributeOverride {
    String name();
    Column column();
}
@MappedSuperclass
public class Employee {
    @Id
    protected Integer id;

    @Version
    protected Integer version;

    protected String address;

    public Integer getId() { ... }

    public void setId(Integer id) { ... }

    public String getAddress() { ... }

    public void setAddress(String address) { ... }
}

@Entity
@AttributeOverride(name="address", column=@Column(name="ADDR"))
public class PartTimeEmployee extends Employee {
    // address field mapping overridden to ADDR
    protected Float wage();

    public Float getHourlyWage() { ... }

    public void setHourlyWage(Float wage) { ... }
}
@Embeddable public class Address {
    protected String street;

    protected String city;

    protected String state;

    @Embedded
    protected Zipcode zipcode;
}

@Embeddable
public class Zipcode {
    protected String zip;
    protected String plusFour;
}

@Entity
public class Customer {
    @Id
    protected Integer id;

    protected String name;

    @AttributeOverride(name="state", column=@Column(name="ADDR_STATE"))
    @AttributeOverride(name="zipcode.zip", column= @Column(name="ADDR_ZIP"))
    @Embedded
    protected Address address;

    // ...
}
@Entity
public class PropertyRecord {
    @EmbeddedId
    PropertyOwner owner;

    @AttributeOverrides(name="key.street", column=@Column(name="STREET_NAME"))
    @AttributeOverride(name="value.size", column=@Column(name="SQUARE_FEET"))
    @AttributeOverride(name="value.tax", column=@Column(name="ASSESSMENT"))
    @ElementCollection
    Map<Address, PropertyInfo> parcels;
}

@Embeddable
public class PropertyInfo {
    Integer parcelNumber;
    Integer size;
    BigDecimal tax;
}
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface AttributeOverrides {
    AttributeOverride[] value();
}
@Embedded
@AttributeOverrides({
    @AttributeOverride(name="startDate", column=@Column(name="EMP_START")),
    @AttributeOverride(name="endDate", column=@Column(name="EMP_END"))
})
public EmploymentPeriod getEmploymentPeriod() { ... }
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Basic {
    FetchType fetch() default EAGER;
    boolean optional() default true;
}
public enum FetchType { LAZY, EAGER };
@Basic
protected String name;
@Basic(fetch=LAZY)
protected String getName() { return name; }
@Target({TYPE})
@Retention(RUNTIME)
public @interface Cacheable {
    boolean value() default true;
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface CollectionTable {
    String name() default "";
    String catalog() default "";
    String schema() default "";
    JoinColumn[] joinColumns() default {};
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
    UniqueConstraint[] uniqueConstraints() default {};
    Index[] indexes() default {};
    String options() default "";
}
@Embeddable
public class Address {
    protected String street;
    protected String city;
    protected String state;

    // ...
}

@Entity public class Person {
    @Id
    protected String ssn;

    protected String name;

    protected Address home;

    // ...

    @ElementCollection // use default table (PERSON_NICKNAMES)
    @Column(name="name", length=50)
    protected Set<String> nickNames = new HashSet();

    // ...
}

@Entity
public class WealthyPerson extends Person {
    @ElementCollection
    @CollectionTable(name="HOMES") // use default join column name
    @AttributeOverrides({
        @AttributeOverride(name="street", column=@Column(name="HOME_STREET")),
        @AttributeOverride(name="city", column=@Column(name="HOME_CITY")),
        @AttributeOverride(name="state", column=@Column(name="HOME_STATE"))
    })
    protected Set<Address> vacationHomes = new HashSet();

    // ...
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Column {
    String name() default "";
    boolean unique() default false;
    boolean nullable() default true;
    boolean insertable() default true;
    boolean updatable() default true;
    String columnDefinition() default "";
    String options() default "";
    String table() default "";
    int length() default 255;
    int precision() default 0; // decimal precision
    int scale() default 0; // decimal scale
    int secondPrecision() default -1; //fractional second precision
    CheckConstraint[] check() default {}
    String comment() default "";
}
@Column(name="DESC", nullable=false, length=512)
public String getDescription() {
    return description;
}
@Column(name="DESC", columnDefinition="CLOB NOT NULL", table="EMP_DETAIL")
@Lob
public String getDescription() {
    return description;
}
@Column(name="ORDER_COST", updatable=false, precision=12, scale=2)
public BigDecimal getCost() {
    return cost;
}
@Target({METHOD, FIELD, TYPE})
@Retention(RUNTIME)
@Repeatable(Converts.class)
public @interface Convert {
    Class converter() default void.class;
    String attributeName() default "";
    boolean disableConversion() default false;
}
@Converter
public class BooleanToIntegerConverter implements AttributeConverter<Boolean, Integer> { ... }

@Entity
public class Employee {
    @Id
    long id;

    @Convert(converter=BooleanToIntegerConverter.class)
    boolean fullTime;

    // ...
}
@Converter(autoApply=true)
public class EmployeeDateConverter implements
    AttributeConverter<com.acme.EmployeeDate, java.sql.Date> { ... }

@Entity
public class Employee {
    @Id
    long id;

    // ...

    // EmployeeDateConverter is applied automatically
    EmployeeDate startDate;
}
@Convert(disableConversion=true)
EmployeeDate lastReview;
@ElementCollection
// applies to each element in the collection
@Convert(converter=NameConverter.class)
List<String> names;
@ElementCollection
@Convert(converter=EmployeeNameConverter.class)
Map<String, String> responsibilities;
@OneToMany
@Convert(converter=ResponsibilityCodeConverter.class, attributeName="key")
Map<String, Employee> responsibilities;
@Embedded
@Convert(converter=CountryConverter.class, attributeName="country")
Address address;
@Embedded
@Convert(converter=CityConverter.class, attributeName="region.city")
Address address;
@Entity
public class PropertyRecord {
    // ...

    @Convert(converter=CityConverter.class, attributeName="key.region.city")
    @ElementCollection
    Map<Address, PropertyInfo> parcels;
}
@OneToMany
@Convert(converter=ResponsibilityCodeConverter.class, attributeName="key.jobType")
Map<Responsibility, Employee> responsibilities;
@Entity
@Convert(converter=DateConverter.class, attributeName="startDate")
@Convert(converter=DateConverter.class, attributeName="endDate")
public class FullTimeEmployee extends GenericEmployee { ... }
@Target({METHOD, FIELD, TYPE})
@Retention(RUNTIME)
public @interface Converts {
    Convert[] value();
}
@Embedded
@Converts({
    @Convert(converter=CountryConverter.class, attributeName="country"),
    @Convert(converter=CityConverter.class, attributeName="region.city")
})
Address address;
public enum DiscriminatorType { STRING, CHAR, INTEGER };
@Target({TYPE})
@Retention(RUNTIME)
public @interface DiscriminatorColumn {
    String name() default "DTYPE";
    DiscriminatorType discriminatorType() default STRING;
    String columnDefinition() default "";
    String options() default "";
    int length() default 31;
}
@Entity
@Table(name="CUST")
@DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20)
public class Customer { ... }

@Entity
public class ValuedCustomer extends Customer { ... }
@Target({TYPE})
@Retention(RUNTIME)
public @interface DiscriminatorValue {
    String value();
}
@Entity
@Table(name="CUST")
@Inheritance(strategy=SINGLE_TABLE)
@DiscriminatorColumn(name="DISC", discriminatorType=STRING,length=20)
@DiscriminatorValue("CUSTOMER")
public class Customer { ... }

@Entity
@DiscriminatorValue("VCUSTOMER")
public class ValuedCustomer extends Customer { ... }
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface ElementCollection {
    Class targetClass() default void.class;
    FetchType fetch() default LAZY;
}
@Entity public class Person {
    @Id
    protected String ssn;

    protected String name;

    @ElementCollection
    protected Set<String> nickNames = new HashSet();

    // ...
}
@Documented
@Target({TYPE})
@Retention(RUNTIME)
public @interface Embeddable {

}
@Embeddable
public class EmploymentPeriod {
    @Temporal(DATE)
    java.util.Date startDate;

    @Temporal(DATE)
    java.util.Date endDate;

    // ...
}
@Embeddable
public class PhoneNumber {
    protected String areaCode;
    protected String localNumber;

    @ManyToOne
    PhoneServiceProvider provider;

    // ...
}

@Entity
public class PhoneServiceProvider {
    @Id
    protected String name;

    // ...
}
@Embeddable
public class Address {
    protected String street;
    protected String city;
    protected String state;

    @Embedded
    protected Zipcode zipcode;
}

@Embeddable
public class Zipcode {
    protected String zip;
    protected String plusFour;
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Embedded {}
@Embedded
@AttributeOverrides({
    @AttributeOverride(name="startDate", column=@Column(name="EMP_START")),
    @AttributeOverride(name="endDate", column=@Column(name="EMP_END"))
})
public EmploymentPeriod getEmploymentPeriod() { ... }
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface EmbeddedId {}
@Entity public class Employee {
    @EmbeddedId
    protected EmployeePK empPK;

    String name;

    @ManyToOne
    Set<Department> dept;

    // ...
}
@Embeddable
public class DependentId {
    String name;
    EmployeeId empPK; // corresponds to PK type of Employee
}

@Entity
public class Dependent {
    // default column name for "name" attribute is overridden
    @AttributeOverride(name="name", @Column(name="dep_name"))
    @EmbeddedId
    DependentId id;

    // ...

    @MapsId("empPK")
    @ManyToOne
    Employee emp;
}
public enum EnumType {
    ORDINAL,
    STRING
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Enumerated {
    EnumType value() default ORDINAL;
}
public enum EmployeeStatus {FULL_TIME, PART_TIME, CONTRACT}
public enum SalaryRate {JUNIOR, SENIOR, MANAGER, EXECUTIVE}

@Entity
public class Employee {
    // ...

    public EmployeeStatus getStatus() {...}

    @Enumerated(STRING)
    public SalaryRate getPayScale() {...}

    // ...
}
enum Status {
    OPEN(0), CLOSED(1), CANCELLED(-1);

    @EnumeratedValue
    final int intValue;

    Status(int intValue) {
        this.intValue = intValue;
    }
}
@Target({})
@Retention(RUNTIME)
public @interface ForeignKey {
    String name() default "";
    ConstraintMode value() default CONSTRAINT;
    String foreignKeyDefinition() default "";
    String options() default "";
}
public enum ConstraintMode {CONSTRAINT, NO_CONSTRAINT, PROVIDER_DEFAULT}
FOREIGN KEY (<COLUMN expression> {, <COLUMN expression>}... )
REFERENCES <TABLE identifier> [ (<COLUMN expression> {, <COLUMN expression>}... ) ]
[ ON UPDATE <referential action> ]
[ ON DELETE <referential action> ]
public enum GenerationType { TABLE, SEQUENCE, IDENTITY, UUID, AUTO };
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface GeneratedValue {
    GenerationType strategy() default AUTO;
    String generator() default "";
}
@Id
@GeneratedValue(strategy=SEQUENCE, generator="CUST_SEQ")
@Column(name="CUST_ID")
public Long getId() { return id; }
@Id
@GeneratedValue(strategy=TABLE, generator="CUST_GEN")
@Column(name="CUST_ID")
Long id;
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Id {}
@Id
public Long getId() { return id; }
@Target({TYPE})
@Retention(RUNTIME)
public @interface IdClass {
    Class value();
}
@IdClass(com.acme.EmployeePK.class)
@Entity
public class Employee {
    @Id
    String empName;

    @Id
    Date birthDay;

    // ...
}
@Target({})
@Retention(RUNTIME)
public @interface Index {
    String name() default "";
    String columnList();
    boolean unique() default false;
    String options() default "";
}
column_list::= index_column [,index_column]*
index_column::= column_name [ASC | DESC]
public enum InheritanceType { SINGLE_TABLE, JOINED, TABLE_PER_CLASS };
@Target({TYPE})
@Retention(RUNTIME)
public @interface Inheritance {
    InheritanceType strategy() default SINGLE_TABLE;
}
@Entity
@Inheritance(strategy=JOINED)
public class Customer { ... }

@Entity
public class ValuedCustomer extends Customer { ... }
@Target({METHOD, FIELD})
@Retention(RUNTIME)
@Repeatable(JoinColumns.class)
public @interface JoinColumn {
    String name() default "";
    String referencedColumnName() default "";
    boolean unique() default false;
    boolean nullable() default true;
    boolean insertable() default true;
    boolean updatable() default true;
    String columnDefinition() default "";
    String options() default "";
    String table() default "";
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
    CheckConstraint[] check() default {}
    String comment() default "";
}
@ManyToOne
@JoinColumn(name="ADDR_ID")
public Address getAddress() { return address; }
@OneToMany
@JoinColumn(name="CUST_ID") // join column is in table for Order
public Set<Order> getOrders() { return orders; }
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinColumns {
    JoinColumn[] value();
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
}
@ManyToOne
@JoinColumns({
    @JoinColumn(name="ADDR_ID", referencedColumnName="ID"),
    @JoinColumn(name="ADDR_ZIP", referencedColumnName="ZIP")
})
public Address getAddress() { return address; }
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinTable {
    String name() default "";
    String catalog() default "";
    String schema() default "";
    JoinColumn[] joinColumns() default {};
    JoinColumn[] inverseJoinColumns() default {};
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
    ForeignKey inverseForeignKey() default @ForeignKey(PROVIDER_DEFAULT);
    UniqueConstraint[] uniqueConstraints() default {};
    Index[] indexes() default {};
    CheckConstraint[] check() default {}
    String comment() default "";
    String options() default "";
}
@JoinTable(
    name="CUST_PHONE",
    joinColumns=@JoinColumn(name="CUST_ID", referencedColumnName="ID"),
    inverseJoinColumns=@JoinColumn(name="PHONE_ID", referencedColumnName="ID")
)
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Lob {

}
@Lob
@Basic(fetch=EAGER)
@Column(name="REPORT")
protected String report;
@Lob @Basic(fetch=LAZY)
@Column(name="EMP_PIC", columnDefinition="BLOB NOT NULL")
protected byte[] pic;
public enum CascadeType {ALL, PERSIST, MERGE, REMOVE, REFRESH, DETACH};
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface ManyToMany {
    Class targetEntity() default void.class;
    CascadeType[] cascade() default {};
    FetchType fetch() default LAZY;
    String mappedBy() default "";
}
@ManyToMany
@JoinTable(name="CUST_PHONES")
public Set<PhoneNumber> getPhones() { return phones; }
@ManyToMany(mappedBy="phones")
public Set<Customer> getCustomers() { return customers; }
@ManyToMany(targetEntity=com.acme.PhoneNumber.class)
public Set getPhones() { return phones; }
@ManyToMany(targetEntity=com.acme.Customer.class, mappedBy="phones")
public Set getCustomers() { return customers; }
@ManyToMany
@JoinTable(
    name="CUST_PHONE",
    joinColumns=@JoinColumn(name="CUST_ID", referencedColumnName="ID"),
    inverseJoinColumns=@JoinColumn(name="PHONE_ID",referencedColumnName="ID")
)
public Set<PhoneNumber> getPhones() { return phones; }
@ManyToMany(mappedBy="phones")
public Set<Customer> getCustomers() { return customers; }
@Entity
public class Employee {
    @Id
    int id;

    @Embedded
    ContactInfo contactInfo;

    // ...
}

@Embeddable
public class ContactInfo {
    @ManyToOne
    Address address; // Unidirectional

    @ManyToMany
    List<PhoneNumber> phoneNumbers; // Bidirectional
}

@Entity
public class PhoneNumber {
    @Id
    int phNumber;

    @ManyToMany(mappedBy="contactInfo.phoneNumbers")
    Collection<Employee> employees;
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface ManyToOne {
    Class targetEntity() default void.class;
    CascadeType[] cascade() default {};
    FetchType fetch() default EAGER;
    boolean optional() default true;
}
@ManyToOne(optional=false)
@JoinColumn(name="CUST_ID", nullable=false, updatable=false)
public Customer getCustomer() { return customer; }
@Entity
public class Employee {
    @Id
    int id;

    @Embedded
    JobInfo jobInfo;

    // ...
}

@Embeddable
public class JobInfo {
    String jobDescription;

    @ManyToOne
    ProgramManager pm; // Bidirectional
}

@Entity
public class ProgramManager {
    @Id
    int id;

    @OneToMany(mappedBy="jobInfo.pm")
    Collection<Employee> manages;
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface MapKey {
    String name() default "";
}
@Entity
public class Department {

    // ...

    @OneToMany(mappedBy="department")
    @MapKey // map key is primary key
    public Map<Integer, Employee> getEmployees() { ... }

    // ...
}

@Entity
public class Employee {

    // ...

    @Id public Integer getEmpId() { ... }
    @ManyToOne
    @JoinColumn(name="dept_id")
    public Department getDepartment() { ... }

    // ...
}
@Entity
public class Department {
    // ...

    @OneToMany(mappedBy="department")
    @MapKey(name="name")
    public Map<String, Employee> getEmployees() { ... }

    // ...
}

@Entity
public class Employee {
    @Id
    public Integer getEmpId() { ... }

    // ...

    public String getName() { ... }

    // ...

    @ManyToOne
    @JoinColumn(name="dept_id")
    public Department getDepartment() { ... }

    // ...
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface MapKeyClass {
    Class value();
}
@Entity
public class Item {
    @Id
    int id;

    // ...

    @ElementCollection(targetClass=String.class)
    @MapKeyClass(String.class)
    Map images; // map from image name to image filename

    // ...
}
// MapKeyClass and target type of relationship can be defaulted
@Entity
public class Item {
    @Id
    int id;

    // ...

    @ElementCollection
    Map<String, String> images;

    // ...
}
@Entity
public class Company {
    @Id
    int id;

    // ...

    @OneToMany(targetEntity=com.example.VicePresident.class)
    @MapKeyClass(com.example.Division.class)
    Map organization;
}
// MapKeyClass and target type of relationship are defaulted
@Entity
public class Company {
    @Id
    int id;

    // ...

    @OneToMany
    Map<Division, VicePresident> organization;
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface MapKeyColumn {
    String name() default "";
    boolean unique() default false;
    boolean nullable() default false;
    boolean insertable() default true;
    boolean updatable() default true;
    String columnDefinition() default "";
    String options() default "";
    String table() default "";
    int length() default 255;
    int precision() default 0; // decimal precision
    int scale() default 0; // decimal scale
}
@Entity
public class Item {
    @Id
    int id;

    // ...

    @ElementCollection
    @MapKeyColumn(name="IMAGE_NAME")
    @Column(name="IMAGE_FILENAME")
    @CollectionTable(name="IMAGE_MAPPING")
    Map<String, String> images; // map from image name to filename

    // ...
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface MapKeyEnumerated {
    EnumType value() default ORDINAL;
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
@Repeatable(MapKeyJoinColumns.class)
public @interface MapKeyJoinColumn {
    String name() default "";
    String referencedColumnName() default "";
    boolean unique() default false;
    boolean nullable() default false;
    boolean insertable() default true;
    boolean updatable() default true;
    String columnDefinition() default "";
    String options() default "";
    String table() default "";
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
}
@Entity
public class Company {
    @Id
    int id;

    // ...

    @OneToMany // unidirectional
    @JoinTable(
        name="COMPANY_ORGANIZATION",
        joinColumns=@JoinColumn(name="COMPANY"),
        inverseJoinColumns=@JoinColumn(name="VICEPRESIDENT")
    )
    @MapKeyJoinColumn(name="DIVISION")
    Map<Division, VicePresident> organization;
}
@Entity
public class VideoStore {
    @Id
    int id;

    String name;

    Address location;

    // ...

    @ElementCollection
    @CollectionTable(name="INVENTORY", joinColumns=@JoinColumn(name="STORE"))
    @Column(name="COPIES_IN_STOCK")
    @MapKeyJoinColumn(name="MOVIE", referencedColumnName="ID")
    Map<Movie, Integer> videoInventory;

    // ...
}

@Entity
public class Movie {
    @Id
    long id;

    String title;

    // ...
}
@Entity
public class Student {
    @Id
    int studentId;

    // ...

    @ManyToMany // students and courses are also many-many
    @JoinTable(
        name="ENROLLMENTS",
        joinColumns=@JoinColumn(name="STUDENT"),
        inverseJoinColumns=@JoinColumn(name="SEMESTER")
    )
    @MapKeyJoinColumn(name="COURSE")
    Map<Course, Semester> enrollment;

    // ...
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface MapKeyJoinColumns {
    MapKeyJoinColumn[] value();
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface MapKeyTemporal {
    TemporalType value();
}
@Documented
@Target(TYPE)
@Retention(RUNTIME)
public @interface MappedSuperclass {}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface MapsId {
    String value() default "";
}
// parent entity has simple primary key
@Entity
public class Employee {
    @Id
    long empId;

    String name;

    // ...
}

// dependent entity uses EmbeddedId for composite key
@Embeddable
public class DependentId {
    String name;
    long empid; // corresponds to PK type of Employee
}

@Entity
public class Dependent {
    @EmbeddedId
    DependentId id;

    // ...

    @MapsId("empid") // maps the empid attribute of embedded id
    @ManyToOne
    Employee emp;
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OneToMany {
    Class targetEntity() default void.class;
    CascadeType[] cascade() default {};
    FetchType fetch() default LAZY;
    String mappedBy() default "";
    boolean orphanRemoval() default false;
}
@OneToMany(cascade=ALL, mappedBy="customer", orphanRemoval=true)
public Set<Order> getOrders() { return orders; }
@ManyToOne
@JoinColumn(name="CUST_ID", nullable=false)
public Customer getCustomer() { return customer; }
@OneToMany(
    targetEntity=com.acme.Order.class,
    cascade=ALL,
    mappedBy="customer",
    orphanRemoval=true
)
public Set getOrders() { return orders; }
@ManyToOne
@JoinColumn(name="CUST_ID", nullable=false)
protected Customer customer;
@OneToMany(orphanRemoval=true)
@JoinColumn(name="CUST_ID") // join column is in table for Order
public Set<Order> getOrders() { return orders; }
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OneToOne {
    Class targetEntity() default void.class;
    CascadeType[] cascade() default {};
    FetchType fetch() default EAGER;
    boolean optional() default true;
    String mappedBy() default "";
    boolean orphanRemoval() default false;
}
@OneToOne(optional=false)
@JoinColumn(name="CUSTREC_ID", unique=true, nullable=false, updatable=false)
public CustomerRecord getCustomerRecord() { return customerRecord; }
@OneToOne(optional=false, mappedBy="customerRecord")
public Customer getCustomer() { return customer; }
@Entity
public class Employee {
    @Id
    Integer id;

    @OneToOne(orphanRemoval=true)
    @MapsId
    EmployeeInfo info;

    // ...
}
@Entity
public class EmployeeInfo {
    @Id
    Integer id;

    //...
}
@Entity
public class Employee {
    @Id
    int id;

    @Embedded
    LocationDetails location;

    // ...
}

@Embeddable
public class LocationDetails {
    int officeNumber;

    @OneToOne
    ParkingSpot parkingSpot;

    // ...
}

@Entity
public class ParkingSpot {
    @Id
    int id;

    String garage;

    @OneToOne(mappedBy="location.parkingSpot")
    Employee assignedTo;

    // ...
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OrderBy {
    String value() default "";
}
orderby_list ::= orderby_item [,orderby_item]*
orderby_item ::= [property_or_field_name] [ASC | DESC]
@Entity
public class Course {
    // ...

    @ManyToMany
    @OrderBy("lastname ASC")
    public List<Student> getStudents() { ... };

    // ...
}
@Entity
public class Student {
    // ...

    @ManyToMany(mappedBy="students")
    @OrderBy // PK is assumed
    public List<Course> getCourses() { ... };

    // ...
}
@Entity
public class Person {
    // ...

    @ElementCollection
    @OrderBy("zipcode.zip, zipcode.plusFour")
    public Set<Address> getResidences() { ... };

    // ...
}

@Embeddable
public class Address {
    protected String street;
    protected String city;
    protected String state;

    @Embedded
    protected Zipcode zipcode;
}

@Embeddable
public class Zipcode {
    protected String zip;
    protected String plusFour;
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OrderColumn {
    String name() default "";
    boolean nullable() default true;
    boolean insertable() default true;
    boolean updatable() default true;
    String columnDefinition() default "";
    String options() default "";
}
@Entity
public class CreditCard {
    @Id
    long ccNumber;

    @OneToMany // unidirectional
    @OrderColumn
    List<CardTransaction> transactionHistory;

    // ...
}
@Entity
public class Course {
    // ...

    @ManyToMany
    @JoinTable(name="COURSE_ENROLLMENT")
    public Set<Student> getStudents() { ... };

    // ...

    @ManyToMany // unidirectional
    @JoinTable(name="WAIT_LIST")
    @OrderColumn(name="WAITLIST_ORDER")
    public List<Student> getWaitList()  { ... }
}

@Entity
public class Student {
    // ...

    @ManyToMany(mappedBy="students")
    public Set<Course> getCourses() { ... };

    // ...
}
SELECT w
FROM course c JOIN c.waitlist w
WHERE c.name = "geometry" AND INDEX(w) = 0
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
@Repeatable(PrimaryKeyJoinColumns.class)
public @interface PrimaryKeyJoinColumn {
    String name() default "";
    String referencedColumnName() default "";
    String columnDefinition() default "";
    String options() default "";
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
}
@Entity
@Table(name="CUST")
@Inheritance(strategy=JOINED)
@DiscriminatorValue("CUST")
public class Customer { ... }

@Entity
@Table(name="VCUST")
@DiscriminatorValue("VCUST")
@PrimaryKeyJoinColumn(name="CUST_ID")
public class ValuedCustomer extends Customer { ... }
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface PrimaryKeyJoinColumns {
    PrimaryKeyJoinColumn[] value();
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
}
@Entity
@Table(name="VCUST")
@DiscriminatorValue("VCUST")
@PrimaryKeyJoinColumns({
    @PrimaryKeyJoinColumn(name="CUST_ID", referencedColumnName="ID"),
    @PrimaryKeyJoinColumn(name="CUST_TYPE", referencedColumnName="TYPE")
})
public class ValuedCustomer extends Customer { ... }
public class EmpPK {
    public Integer id;
    public String name;
}

@Entity
@IdClass(com.acme.EmpPK.class)
public class Employee {
    @Id
    Integer id;

    @Id
    String name;

    @OneToOne
    @PrimaryKeyJoinColumns({
        @PrimaryKeyJoinColumn(name="ID", referencedColumnName="EMP_ID"),
        @PrimaryKeyJoinColumn(name="NAME", referencedColumnName="EMP_NAME")
    })
    EmployeeInfo info;

    // ...
}

@Entity
@IdClass(com.acme.EmpPK.class)
public class EmployeeInfo {
    @Id
    @Column(name="EMP_ID")
    Integer id;

    @Id
    @Column(name="EMP_NAME")
    String name;

    // ...
}
@Target({TYPE})
@Retention(RUNTIME)
@Repeatable(SecondaryTables.class)
public @interface SecondaryTable {
    String name();
    String catalog() default "";
    String schema() default "";
    PrimaryKeyJoinColumn[] pkJoinColumns() default {};
    ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
    UniqueConstraint[] uniqueConstraints() default {};
    Index[] indexes() default {};
    CheckConstraint[] check() default {}
    String comment() default "";
    String options() default "";
}
@Entity
@Table(name="CUSTOMER")
@SecondaryTable(
    name="CUST_DETAIL",
    pkJoinColumns=@PrimaryKeyJoinColumn(name="CUST_ID")
)
public class Customer { ... }
@Entity
@Table(name="CUSTOMER")
@SecondaryTable(
    name="CUST_DETAIL",
    pkJoinColumns={
        @PrimaryKeyJoinColumn(name="CUST_ID"),
        @PrimaryKeyJoinColumn(name="CUST_TYPE")
    })
public class Customer { ... }
@Target({TYPE})
@Retention(RUNTIME)
public @interface SecondaryTables {
    SecondaryTable[] value();
}
@Entity
@Table(name="EMPLOYEE")
@SecondaryTables({
    @SecondaryTable(name="EMP_DETAIL"),
    @SecondaryTable(name="EMP_HIST")
})
public class Employee { ... }
@Entity
@Table(name="EMPLOYEE")
@SecondaryTables({
    @SecondaryTable(
        name="EMP_DETAIL",
        pkJoinColumns=@PrimaryKeyJoinColumn(name="EMPL_ID")),
    @SecondaryTable(
        name="EMP_HIST",
        pkJoinColumns=@PrimaryKeyJoinColumn(name="EMPLOYEE_ID"))
})
public class Employee { ... }
@Target({TYPE, METHOD, FIELD, PACKAGE})
@Retention(RUNTIME)
@Repeatable(SequenceGenerators.class)
public @interface SequenceGenerator {
    String name() default "";
    String sequenceName() default "";
    String catalog() default "";
    String schema() default "";
    int initialValue() default 1;
    int allocationSize() default 50;
    String options() default "";
}
@SequenceGenerator(name="EMP_SEQ", allocationSize=25)
@Target({TYPE, METHOD, FIELD, PACKAGE})
@Retention(RUNTIME)
public @interface SequenceGenerators {
    SequenceGenerator[] value();
}
@Target({TYPE})
@Retention(RUNTIME)
public @interface Table {
    String name() default "";
    String catalog() default "";
    String schema() default "";
    UniqueConstraint[] uniqueConstraints() default {};
    Index[] indexes() default {};
    CheckConstraint[] check() default {}
    String comment() default "";
    String options() default "";
}
@Entity
@Table(name="CUST", schema="RECORDS")
public class Customer { ... }
@Target({TYPE, METHOD, FIELD, PACKAGE})
@Retention(RUNTIME)
@Repeatable(TableGenerators.class)
public @interface TableGenerator {
    String name() default "";
    String table() default "";
    String catalog() default "";
    String schema() default "";
    String pkColumnName() default "";
    String valueColumnName() default "";
    String pkColumnValue() default "";
    int initialValue() default 0;
    int allocationSize() default 50;
    UniqueConstraint[] uniqueConstraints() default {};
    Index[] indexes() default {};
    String options() default "";
}
@Entity
public class Employee {
    // ...

    @TableGenerator(
        name="empGen",
        table="ID_GEN",
        pkColumnName="GEN_KEY",
        valueColumnName="GEN_VALUE",
        pkColumnValue="EMP_ID",
        allocationSize=1)
    @Id
    @GeneratedValue(strategy=TABLE, generator="empGen")
    int id;

    // ...
}
@Entity
public class Address {
    // ...

    @TableGenerator(
        name="addressGen",
        table="ID_GEN",
        pkColumnName="GEN_KEY",
        valueColumnName="GEN_VALUE",
        pkColumnValue="ADDR_ID")
    @Id
    @GeneratedValue(strategy=TABLE, generator="addressGen")
    int id;

    // ...
}
@Target({TYPE, METHOD, FIELD, PACKAGE})
@Retention(RUNTIME)
public @interface TableGenerators {
    TableGenerator[] value();
}
public enum TemporalType {
    DATE, //java.sql.Date
    TIME, //java.sql.Time
    TIMESTAMP //java.sql.Timestamp
}

@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Temporal {
    TemporalType value();
}
@Embeddable
public class EmploymentPeriod {
    @Temporal(DATE)
    java.util.Date startDate;

    @Temporal(DATE)
    java.util.Date endDate;

    // ...
}
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Transient {}
@Entity
public class Employee {
    @Id
    int id;

    @Transient
    User currentUser;

    // ...
}
@Target({})
@Retention(RUNTIME)
public @interface UniqueConstraint {
    String name() default "";
    String[] columnNames();
    String options() default "";
}
@Entity
@Table(
    name="EMPLOYEE",
    uniqueConstraints=@UniqueConstraint(columnNames={"EMP_ID", "EMP_NAME"})
)
public class Employee { ... }
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Version {}
@Version
@Column(name="OPTLOCK")
protected int getVersionNum() { return versionNum; }
@Entity
public class Customer {
    @Id
    @GeneratedValue(strategy = AUTO)
    Long id;

    @Version
    protected int version;

    @ManyToOne
    Address address;

    @Basic
    String description;

    @OneToMany(targetEntity = com.acme.Order.class,
               mappedBy = "customer")
    Collection orders = new Vector();

    @ManyToMany(mappedBy = "customers")
    Set<DeliveryService> serviceOptions = new HashSet();

    public Long getId() {
        return id;
    }

    public Address getAddress() {
        return address;
    }

    public void setAddress(Address addr) {
        this.address = addr;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String desc) {
        this.description = desc;
    }

    public Collection getOrders() {
        return orders;
    }

    public Set<DeliveryService> getServiceOptions() {
        return serviceOptions;
    }
}

@Entity
public class Address {
    private Long id;
    private int version;
    private String street;

    @Id
    @GeneratedValue(strategy = AUTO)
    public Long getId() {
        return id;
    }

    protected void setId(Long id) {
        this.id = id;
    }

    @Version
    public int getVersion() {
        return version;
    }

    protected void setVersion(int version) {
        this.version = version;
    }

    public String getStreet() {
        return street;
    }

    public void setStreet(String street) {
        this.street = street;
    }
}

@Entity
public class Order {
    private Long id;
    private int version;
    private String itemName;
    private int quantity;
    private Customer cust;

    @Id
    @GeneratedValue(strategy = AUTO)
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    @Version
    protected int getVersion() {
        return version;
    }

    protected void setVersion(int version) {
        this.version = version;
    }

    public String getItemName() {
        return itemName;
    }

    public void setItemName(String itemName) {
        this.itemName = itemName;
    }

    public int getQuantity() {
        return quantity;
    }

    public void setQuantity(int quantity) {
        this.quantity = quantity;
    }

    @ManyToOne
    public Customer getCustomer() {
        return cust;
    }

    public void setCustomer(Customer cust) {
        this.cust = cust;
    }
}

@Entity
@Table(name = "DLVY_SVC")
public class DeliveryService {
    private String serviceName;
    private int priceCategory;
    private Collection customers;

    @Id
    public String getServiceName() {
        return serviceName;
    }

    public void setServiceName(String serviceName) {
        this.serviceName = serviceName;
    }

    public int getPriceCategory() {
        return priceCategory;
    }

    public void setPriceCategory(int priceCategory) {
        this.priceCategory = priceCategory;
    }

    @ManyToMany(targetEntity = com.acme.Customer.class)
    @JoinTable(name = "CUST_DLVRY")
    public Collection getCustomers() {
        return customers;
    }

    public setCustomers(Collection customers) {
        this.customers = customers;
    }
}
/***** Employee class *****/
@Entity
@Table(name = "EMPL")
@SecondaryTable(name = "EMP_SALARY",
                pkJoinColumns = @PrimaryKeyJoinColumn(name = "EMP_ID", referencedColumnName = "ID"))
public class Employee implements Serializable {
    private Long id;
    private int version;
    private String name;
    private Address address;
    private Collection phoneNumbers;
    private Collection<Project> projects;
    private Long salary;
    private EmploymentPeriod period;

    @Id
    @GeneratedValue(strategy = TABLE)
    public Integer getId() {
        return id;
    }

    protected void setId(Integer id) {
        this.id = id;
    }

    @Version
    @Column(name = "EMP_VERSION", nullable = false)
    public int getVersion() {
        return version;
    }

    protected void setVersion(int version) {
        this.version = version;
    }

    @Column(name = "EMP_NAME", length = 80)
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @ManyToOne(cascade = PERSIST, optional = false)
    @JoinColumn(name = "ADDR_ID", referencedColumnName = "ID", nullable = false)
    public Address getAddress() {
        return address;
    }

    public void setAddress(Address address) {
        this.address = address;
    }

    @OneToMany(targetEntity = com.acme.PhoneNumber.class,
               cascade = ALL,
               mappedBy = "employee")
    public Collection getPhoneNumbers() {
        return phoneNumbers;
    }

    public void setPhoneNumbers(Collection phoneNumbers) {
        this.phoneNumbers = phoneNumbers;
    }

    @ManyToMany(cascade = PERSIST, mappedBy = "employees")
    @JoinTable(
        name = "EMP_PROJ",
        joinColumns = @JoinColumn(name = "EMP_ID", referencedColumnName = "ID"),
        inverseJoinColumns = @JoinColumn(name = "PROJ_ID", referencedColumnName = "ID"))
    public Collection<Project> getProjects() {
        return projects;
    }

    public void setProjects(Collection<Project> projects) {
        this.projects = projects;
    }

    @Column(name = "EMP_SAL", table = "EMP_SALARY")
    public Long getSalary() {
        return salary;
    }

    public void setSalary(Long salary) {
        this.salary = salary;
    }

    @Embedded
    @AttributeOverrides({
        @AttributeOverride(name = "startDate",
                           column = @Column(name = "EMP_START")),
        @AttributeOverride(name = "endDate",
                           column = @Column(name = "EMP_END"))
    })
    public EmploymentPeriod getEmploymentPeriod() {
        return period;
    }

    public void setEmploymentPeriod(EmploymentPeriod period) {
        this.period = period;
    }
}

/***** Address class *****/
@Entity
public class Address implements Serializable {
    private Integer id;
    private int version;
    private String street;
    private String city;

    @Id
    @GeneratedValue(strategy = IDENTITY)
    public Integer getId() {
        return id;
    }

    protected void setId(Integer id) {
        this.id = id;
    }

    @Version
    @Column(name = "VERS", nullable = false)
    public int getVersion() {
        return version;
    }

    protected void setVersion(int version) {
        this.version = version;
    }

    @Column(name = "RUE")
    public String getStreet() {
        return street;
    }

    public void setStreet(String street) {
        this.street = street;
    }

    @Column(name = "VILLE")
    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }
}

/***** PhoneNumber class *****/
@Entity
@Table(name = "PHONE")
public class PhoneNumber implements Serializable {
    private String number;
    private int phoneType;
    private Employee employee;

    @Id
    public String getNumber() {
        return number;
    }

    public void setNumber(String number) {
        this.number = number;
    }

    @Column(name = "PTYPE")
    public int getPhonetype() {
        return phonetype;
    }

    public void setPhoneType(int phoneType) {
        this.phoneType = phoneType;
    }

    @ManyToOne(optional = false)
    @JoinColumn(name = "EMP_ID", nullable = false)
    public Employee getEmployee() {
        return employee;
    }

    public void setEmployee(Employee employee) {
        this.employee = employee;
    }
}

/***** Project class *****/
@Entity
@Inheritance(strategy = JOINED)
@DiscriminatorValue("Proj")
@DiscriminatorColumn(name = "DISC")
public class Project implements Serializable {
    private Integer projId;
    private int version;
    private String name;
    private Set<Employee> employees;

    @Id
    @GeneratedValue(strategy = TABLE)
    public Integer getId() {
        return projId;
    }

    protected void setId(Integer id) {
        this.projId = id;
    }

    @Version
    public int getVersion() {
        return version;
    }

    protected void setVersion(int version) {
        this.version = version;
    }

    @Column(name = "PROJ_NAME")
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @ManyToMany(mappedBy = "projects")
    public Set<Employee> getEmployees() {
        return employees;
    }

    public void setEmployees(Set<Employee> employees) {
        this.employees = employees;
    }
}

/***** GovernmentProject subclass *****/
@Entity
@Table(name = "GOVT_PROJECT")
@DiscriminatorValue("GovtProj")
@PrimaryKeyJoinColumn(name = "GOV_PROJ_ID", referencedColumnName = "ID")
public class GovernmentProject extends Project {
    private String fileInfo;

    @Column(name = "INFO")
    public String getFileInfo() {
        return fileInfo;
    }

    public void setFileInfo(String fileInfo) {
        this.fileInfo = fileInfo;
    }
}

/***** CovertProject subclass *****/
@Entity
@Table(name = "C_PROJECT")
@DiscriminatorValue("CovProj")
@PrimaryKeyJoinColumn(name = "COV_PROJ_ID", referencedColumnName = "ID")
public class CovertProject extends Project {
    private String classified;

    public CovertProject() {
        super();
    }

    public CovertProject(String classified) {
        this();
        this.classified = classified;
    }

    @Column(updatable = false)
    public String getClassified() {
        return classified;
    }

    protected void setClassified(String classified) {
        this.classified = classified;
    }
}

/***** EmploymentPeriod class *****/
@Embeddable
public class EmploymentPeriod implements Serializable {
    private Date start;
    private Date end;

    @Column(nullable = false)
    public Date getStartDate() {
        return start;
    }

    public void setStartDate(Date start) {
        this.start = start;
    }

    public Date getEndDate() {
        return end;
    }

    public void setEndDate(Date end) {
        this.end = end;
    }
}
<?xml version="1.0" encoding="UTF-8"?>

<!-- Jakarta Persistence API object/relational mapping file schema -->
<xsd:schema targetNamespace="https://jakarta.ee/xml/ns/persistence/orm"
  xmlns:orm="https://jakarta.ee/xml/ns/persistence/orm"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"
  version="3.2">
  <xsd:annotation>
     <xsd:documentation><![CDATA[

       This is the XML Schema for the persistence object/relational mapping file.
       The file may be named "META-INF/orm.xml" in the persistence
       archive or it may be named some other name which would be
       used to locate the file as resource on the classpath.

       Object/relational mapping files must indicate the object/relational
       mapping file schema by using the persistence namespace:

       https://jakarta.ee/xml/ns/persistence/orm

       and indicate the version of the schema by
       using the version element as shown below:

      <entity-mappings xmlns="https://jakarta.ee/xml/ns/persistence/orm"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence/orm
          https://jakarta.ee/xml/ns/persistence/orm/orm_3_2.xsd"
        version="3.2">
          ...
      </entity-mappings>

     ]]></xsd:documentation>
  </xsd:annotation>

  <xsd:complexType name="emptyType"/>

  <xsd:simpleType name="versionType">
    <xsd:restriction base="xsd:token">
      <xsd:pattern value="[0-9]+(\.[0-9]+)*"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:element name="entity-mappings">
    <xsd:complexType>
      <xsd:annotation>
        <xsd:documentation>

        The entity-mappings element is the root element of a mapping
        file. It contains the following four types of elements:

        1. The persistence-unit-metadata element contains metadata
        for the entire persistence unit. It is undefined if this element
        occurs in multiple mapping files within the same persistence unit.

        2. The package, schema, catalog and access elements apply to all of
        the entity, mapped-superclass and embeddable elements defined in
        the same file in which they occur.

        3. The sequence-generator, table-generator, converter, named-query,
        named-native-query, named-stored-procedure-query, and
        sql-result-set-mapping elements are global to the persistence
        unit. It is undefined to have more than one sequence-generator
        or table-generator of the same name in the same or different
        mapping files in a persistence unit. It is undefined to have
        more than one named-query, named-native-query, sql-result-set-mapping,
        or named-stored-procedure-query of the same name in the same
        or different mapping files in a persistence unit.  It is also
        undefined to have more than one converter for the same target
        type in the same or different mapping files in a persistence unit.

        4. The entity, mapped-superclass and embeddable elements each define
        the mapping information for a managed persistent class. The mapping
        information contained in these elements may be complete or it may
        be partial.

        </xsd:documentation>
      </xsd:annotation>
      <xsd:sequence>
        <xsd:element name="description" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="persistence-unit-metadata"
                     type="orm:persistence-unit-metadata"
                     minOccurs="0"/>
        <xsd:element name="package" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="schema" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="catalog" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="access" type="orm:access-type"
                     minOccurs="0"/>
        <xsd:element name="sequence-generator" type="orm:sequence-generator"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="table-generator" type="orm:table-generator"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="named-query" type="orm:named-query"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="named-native-query" type="orm:named-native-query"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="named-stored-procedure-query"
                     type="orm:named-stored-procedure-query"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="sql-result-set-mapping"
                     type="orm:sql-result-set-mapping"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="mapped-superclass" type="orm:mapped-superclass"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="entity" type="orm:entity"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="embeddable" type="orm:embeddable"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="converter" type="orm:converter"
                     minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
      <xsd:attribute name="version" type="orm:versionType"
                     fixed="3.2" use="required"/>
    </xsd:complexType>
  </xsd:element>

  <!-- **************************************************** -->

  <xsd:complexType name="persistence-unit-metadata">
    <xsd:annotation>
      <xsd:documentation>

        Metadata that applies to the persistence unit and not just to
        the mapping file in which it is contained.

        If the xml-mapping-metadata-complete element is specified,
        the complete set of mapping metadata for the persistence unit
        is contained in the XML mapping files for the persistence unit.

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="xml-mapping-metadata-complete" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="persistence-unit-defaults"
                   type="orm:persistence-unit-defaults"
                   minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="persistence-unit-defaults">
    <xsd:annotation>
      <xsd:documentation>

        These defaults are applied to the persistence unit as a whole
        unless they are overridden by local annotation or XML
        element settings.

        schema - Used as the schema for all tables, secondary tables, join
            tables, collection tables, sequence generators, and table
            generators that apply to the persistence unit
        catalog - Used as the catalog for all tables, secondary tables, join
            tables, collection tables, sequence generators, and table
            generators that apply to the persistence unit
        delimited-identifiers - Used to treat database identifiers as
            delimited identifiers.
        access - Used as the access type for all managed classes in
            the persistence unit
        cascade-persist - Adds cascade-persist to the set of cascade options
            in all entity relationships of the persistence unit
        entity-listeners - List of default entity listeners to be invoked
            on each entity in the persistence unit.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
        <xsd:element name="description" type="xsd:string" minOccurs="0"/>
        <xsd:element name="schema" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="catalog" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="delimited-identifiers" type="orm:emptyType"
                     minOccurs="0"/>
        <xsd:element name="access" type="orm:access-type"
                     minOccurs="0"/>
        <xsd:element name="cascade-persist" type="orm:emptyType"
                     minOccurs="0"/>
        <xsd:element name="entity-listeners" type="orm:entity-listeners"
                     minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="entity">
    <xsd:annotation>
      <xsd:documentation>

        Defines the settings and mappings for an entity. Is allowed to be
        sparsely populated and used in conjunction with the annotations.
        Alternatively, the metadata-complete attribute can be used to
        indicate that no annotations on the entity class (and its fields
        or properties) are to be processed. If this is the case then
        the defaulting rules for the entity and its subelements will
        be recursively applied.

        @Target(TYPE) @Retention(RUNTIME)
        public @interface Entity {
          String name() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="table" type="orm:table"
                   minOccurs="0"/>
      <xsd:element name="secondary-table" type="orm:secondary-table"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:sequence>
        <xsd:element name="primary-key-join-column"
                     type="orm:primary-key-join-column"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="primary-key-foreign-key"
                     type="orm:foreign-key"
                     minOccurs="0"/>
      </xsd:sequence>
      <xsd:element name="id-class" type="orm:id-class" minOccurs="0"/>
      <xsd:element name="inheritance" type="orm:inheritance" minOccurs="0"/>
      <xsd:element name="discriminator-value" type="orm:discriminator-value"
                   minOccurs="0"/>
      <xsd:element name="discriminator-column"
                   type="orm:discriminator-column"
                   minOccurs="0"/>
      <xsd:element name="sequence-generator" type="orm:sequence-generator"
                   minOccurs="0"/>
      <xsd:element name="table-generator" type="orm:table-generator"
                   minOccurs="0"/>
      <xsd:element name="named-query" type="orm:named-query"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="named-native-query" type="orm:named-native-query"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="named-stored-procedure-query"
                   type="orm:named-stored-procedure-query"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="sql-result-set-mapping"
                   type="orm:sql-result-set-mapping"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="exclude-default-listeners" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="exclude-superclass-listeners" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="entity-listeners" type="orm:entity-listeners"
                   minOccurs="0"/>
      <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/>
      <xsd:element name="post-persist" type="orm:post-persist"
                   minOccurs="0"/>
      <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/>
      <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/>
      <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/>
      <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/>
      <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/>
      <xsd:element name="attribute-override" type="orm:attribute-override"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="association-override"
                   type="orm:association-override"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="convert" type="orm:convert"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="named-entity-graph" type="orm:named-entity-graph"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="attributes" type="orm:attributes" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="cacheable" type="xsd:boolean"/>
    <xsd:attribute name="metadata-complete" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="access-type">
    <xsd:annotation>
      <xsd:documentation>

        This element determines how the persistence provider accesses the
        state of an entity or embedded object.

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="PROPERTY"/>
      <xsd:enumeration value="FIELD"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:complexType name="association-override">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(AssociationOverrides.class)
        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface AssociationOverride {
          String name();
          JoinColumn[] joinColumns() default{};
          ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
          JoinTable joinTable() default @JoinTable;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:choice>
        <xsd:sequence>
          <xsd:element name="join-column" type="orm:join-column"
                       minOccurs="0" maxOccurs="unbounded"/>
          <xsd:element name="foreign-key" type="orm:foreign-key"
                       minOccurs="0"/>
        </xsd:sequence>
        <xsd:element name="join-table" type="orm:join-table"
                     minOccurs="0"/>
      </xsd:choice>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="attribute-override">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(AttributeOverrides.class)
        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface AttributeOverride {
          String name();
          Column column();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="column" type="orm:column"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="attributes">
    <xsd:annotation>
      <xsd:documentation>

        This element contains the entity field or property mappings.
        It may be sparsely populated to include only a subset of the
        fields or properties. If metadata-complete for the entity is true
        then the remainder of the attributes will be defaulted according
        to the default rules.

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:choice>
        <xsd:element name="id" type="orm:id"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="embedded-id" type="orm:embedded-id"
                     minOccurs="0"/>
      </xsd:choice>
      <xsd:element name="basic" type="orm:basic"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="version" type="orm:version"
                   minOccurs="0"/>
      <xsd:element name="many-to-one" type="orm:many-to-one"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="one-to-many" type="orm:one-to-many"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="one-to-one" type="orm:one-to-one"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="many-to-many" type="orm:many-to-many"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="element-collection" type="orm:element-collection"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="embedded" type="orm:embedded"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="transient" type="orm:transient"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="basic">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Basic {
          FetchType fetch() default FetchType.EAGER;
          boolean optional() default true;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column" type="orm:column" minOccurs="0"/>
      <xsd:choice>
        <xsd:element name="lob" type="orm:lob" minOccurs="0"/>
        <xsd:element name="temporal" type="orm:temporal" minOccurs="0"/>
        <xsd:element name="enumerated" type="orm:enumerated" minOccurs="0"/>
        <xsd:element name="convert" type="orm:convert" minOccurs="0"/>
      </xsd:choice>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="optional" type="xsd:boolean"/>
    <xsd:attribute name="access" type="orm:access-type"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="cascade-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum CascadeType { ALL, PERSIST, MERGE, REMOVE, REFRESH, DETACH }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="cascade-all" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-persist" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-merge" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-remove" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-refresh" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-detach" type="orm:emptyType"
                   minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="check-constraint">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface CheckConstraint {
          String name() default "";
          String constraint();
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="constraint" type="xsd:string" use="required"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="collection-table">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface CollectionTable {
          String name() default "";
          String catalog() default "";
          String schema() default "";
          JoinColumn[] joinColumns() default {};
          ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
          UniqueConstraint[] uniqueConstraints() default {};
          Index[] indexes() default {};
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:sequence>
        <xsd:element name="join-column" type="orm:join-column"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="foreign-key" type="orm:foreign-key"
                     minOccurs="0"/>
      </xsd:sequence>
      <xsd:element name="unique-constraint" type="orm:unique-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="index" type="orm:index"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="column">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Column {
          String name() default "";
          boolean unique() default false;
          boolean nullable() default true;
          boolean insertable() default true;
          boolean updatable() default true;
          String columnDefinition() default "";
          String options() default "";
          String table() default "";
          int length() default 255;
          int precision() default 0; // decimal precision
          int scale() default 0; // decimal scale
          int secondPrecision() default -1; //fractional second precision
          CheckConstraint[] check() default {};
          String comment() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="comment" type="xsd:string" minOccurs="0" />
      <xsd:element name="check-constraint" type="orm:check-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="unique" type="xsd:boolean"/>
    <xsd:attribute name="nullable" type="xsd:boolean"/>
    <xsd:attribute name="insertable" type="xsd:boolean"/>
    <xsd:attribute name="updatable" type="xsd:boolean"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
    <xsd:attribute name="table" type="xsd:string"/>
    <xsd:attribute name="length" type="xsd:int"/>
    <xsd:attribute name="precision" type="xsd:int"/>
    <xsd:attribute name="scale" type="xsd:int"/>
    <xsd:attribute name="second-precision" type="xsd:int"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="column-result">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({}) @Retention(RUNTIME)
        public @interface ColumnResult {
          String name();
          Class<?> type() default void.class;
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="class" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="constraint-mode">
    <xsd:annotation>
      <xsd:documentation>

       public enum ConstraintMode { CONSTRAINT, NO_CONSTRAINT, PROVIDER_DEFAULT }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="CONSTRAINT"/>
      <xsd:enumeration value="NO_CONSTRAINT"/>
      <xsd:enumeration value="PROVIDER_DEFAULT"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:complexType name="constructor-result">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({}) @Retention(RUNTIME)
        public @interface ConstructorResult {
          Class<?> targetClass();
          ColumnResult[] columns();
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column" type="orm:column-result"
                   maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="target-class" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="convert">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Repeatable(Converts.class)
        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Convert {
          Class<? extends AttributeConverter> converter() default AttributeConverter.class;
          String attributeName() default "";
          boolean disableConversion() default false;
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="converter" type="xsd:string"/>
    <xsd:attribute name="attribute-name" type="xsd:string"/>
    <xsd:attribute name="disable-conversion" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="converter">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface Converter {
          boolean autoApply() default false;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
    <xsd:attribute name="auto-apply" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="discriminator-column">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface DiscriminatorColumn {
          String name() default "DTYPE";
          DiscriminatorType discriminatorType() default STRING;
          String columnDefinition() default "";
          String options() default "";
          int length() default 31;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="discriminator-type" type="orm:discriminator-type"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
    <xsd:attribute name="length" type="xsd:int"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="discriminator-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum DiscriminatorType { STRING, CHAR, INTEGER }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="STRING"/>
      <xsd:enumeration value="CHAR"/>
      <xsd:enumeration value="INTEGER"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:simpleType name="discriminator-value">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface DiscriminatorValue {
          String value();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string"/>
  </xsd:simpleType>

<!-- **************************************************** -->

 <xsd:complexType name="element-collection">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface ElementCollection {
          Class<?> targetClass() default void.class;
          FetchType fetch() default FetchType.LAZY;
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice>
        <xsd:element name="order-by" type="orm:order-by"
                     minOccurs="0"/>
        <xsd:element name="order-column" type="orm:order-column"
                     minOccurs="0"/>
      </xsd:choice>
      <xsd:choice>
        <xsd:element name="map-key" type="orm:map-key"
                     minOccurs="0"/>
        <xsd:sequence>
          <xsd:element name="map-key-class" type="orm:map-key-class"
                       minOccurs="0"/>
          <xsd:choice>
            <xsd:element name="map-key-temporal"
                         type="orm:temporal"
                         minOccurs="0"/>
            <xsd:element name="map-key-enumerated"
                         type="orm:enumerated"
                         minOccurs="0"/>
            <xsd:sequence>
               <xsd:element name="map-key-attribute-override"
                            type="orm:attribute-override"
                            minOccurs="0" maxOccurs="unbounded"/>
               <xsd:element name="map-key-convert" type="orm:convert"
                            minOccurs="0" maxOccurs="unbounded"/>
            </xsd:sequence>
          </xsd:choice>
          <xsd:choice>
            <xsd:element name="map-key-column"
                         type="orm:map-key-column"
                         minOccurs="0"/>
            <xsd:sequence>
              <xsd:element name="map-key-join-column"
                           type="orm:map-key-join-column"
                           minOccurs="0" maxOccurs="unbounded"/>
              <xsd:element name="map-key-foreign-key"
                           type="orm:foreign-key"
                           minOccurs="0"/>
            </xsd:sequence>
          </xsd:choice>
        </xsd:sequence>
      </xsd:choice>
      <xsd:choice>
        <xsd:sequence>
          <xsd:element name="column" type="orm:column" minOccurs="0"/>
          <xsd:choice>
            <xsd:element name="temporal"
                         type="orm:temporal"
                         minOccurs="0"/>
            <xsd:element name="enumerated"
                         type="orm:enumerated"
                         minOccurs="0"/>
            <xsd:element name="lob"
                         type="orm:lob"
                         minOccurs="0"/>
          </xsd:choice>
        </xsd:sequence>
        <xsd:sequence>
          <xsd:element name="attribute-override"
                       type="orm:attribute-override"
                       minOccurs="0" maxOccurs="unbounded"/>
          <xsd:element name="association-override"
                       type="orm:association-override"
                       minOccurs="0" maxOccurs="unbounded"/>
          <xsd:element name="convert" type="orm:convert"
                       minOccurs="0" maxOccurs="unbounded"/>
        </xsd:sequence>
      </xsd:choice>
      <xsd:element name="collection-table" type="orm:collection-table"
                     minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-class" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="access" type="orm:access-type"/>
</xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="embeddable">
    <xsd:annotation>
      <xsd:documentation>

        Defines the settings and mappings for embeddable objects. Is
        allowed to be sparsely populated and used in conjunction with
        the annotations. Alternatively, the metadata-complete attribute
        can be used to indicate that no annotations are to be processed
        in the class. If this is the case then the defaulting rules will
        be recursively applied.

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface Embeddable {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="attributes" type="orm:embeddable-attributes"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="metadata-complete" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="embeddable-attributes">
    <xsd:sequence>
      <xsd:element name="basic" type="orm:basic"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="many-to-one" type="orm:many-to-one"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="one-to-many" type="orm:one-to-many"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="one-to-one" type="orm:one-to-one"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="many-to-many" type="orm:many-to-many"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="element-collection" type="orm:element-collection"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="embedded" type="orm:embedded"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="transient" type="orm:transient"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="embedded">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Embedded {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="attribute-override" type="orm:attribute-override"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="association-override"
                   type="orm:association-override"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="convert" type="orm:convert"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="embedded-id">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface EmbeddedId {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="attribute-override" type="orm:attribute-override"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="entity-listener">
    <xsd:annotation>
      <xsd:documentation>

        Defines an entity listener to be invoked at lifecycle events
        for the entities that list this listener.

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/>
      <xsd:element name="post-persist" type="orm:post-persist"
                   minOccurs="0"/>
      <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/>
      <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/>
      <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/>
      <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/>
      <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="entity-listeners">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface EntityListeners {
          Class<?>[] value();
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="entity-listener" type="orm:entity-listener"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="entity-result">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({}) @Retention(RUNTIME)
        public @interface EntityResult {
          Class<?> entityClass();
          LockModeType lockMode() default LockModeType.OPTIMISTIC;
          FieldResult[] fields() default {};
          String discriminatorColumn() default "";
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="lock-mode" type="orm:lock-mode-type" minOccurs="0"/>
      <xsd:element name="field-result" type="orm:field-result"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="entity-class" type="xsd:string" use="required"/>
    <xsd:attribute name="discriminator-column" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="enum-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum EnumType { ORDINAL, STRING }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="ORDINAL"/>
      <xsd:enumeration value="STRING"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:simpleType name="enumerated">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Enumerated {
          EnumType value() default ORDINAL;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="orm:enum-type"/>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:simpleType name="fetch-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum FetchType { LAZY, EAGER }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="LAZY"/>
      <xsd:enumeration value="EAGER"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:complexType name="field-result">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface FieldResult {
          String name();
          String column();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="column" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="foreign-key">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface ForeignKey {
          String name() default "";
          ConstraintMode value() default CONSTRAINT;
          String foreign-key-definition() default "";
          String options() default "";
        }

        Note that the elements that embed the use of the annotation
        default this use as @ForeignKey(PROVIDER_DEFAULT).

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="constraint-mode" type="orm:constraint-mode"/>
    <xsd:attribute name="foreign-key-definition" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="generated-value">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface GeneratedValue {
          GenerationType strategy() default AUTO;
          String generator() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="strategy" type="orm:generation-type"/>
    <xsd:attribute name="generator" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="generation-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum GenerationType { TABLE, SEQUENCE, IDENTITY, UUID, AUTO }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="TABLE"/>
      <xsd:enumeration value="SEQUENCE"/>
      <xsd:enumeration value="IDENTITY"/>
      <xsd:enumeration value="UUID"/>
      <xsd:enumeration value="AUTO"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:complexType name="id">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Id {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column" type="orm:column"
                   minOccurs="0"/>
      <xsd:element name="generated-value" type="orm:generated-value"
                   minOccurs="0"/>
      <xsd:element name="temporal" type="orm:temporal"
                   minOccurs="0"/>
      <xsd:element name="table-generator" type="orm:table-generator"
                   minOccurs="0"/>
      <xsd:element name="sequence-generator" type="orm:sequence-generator"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="id-class">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface IdClass {
          Class<?> value();
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="index">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface Index {
          String name() default "";
          String columnList();
          boolean unique() default false;
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="column-list" type="xsd:string" use="required"/>
    <xsd:attribute name="unique" type="xsd:boolean"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="inheritance">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface Inheritance {
          InheritanceType strategy() default InheritanceType.SINGLE_TABLE;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="strategy" type="orm:inheritance-type"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:simpleType name="inheritance-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum InheritanceType { SINGLE_TABLE, TABLE_PER_CLASS, JOINED }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="SINGLE_TABLE"/>
      <xsd:enumeration value="JOINED"/>
      <xsd:enumeration value="TABLE_PER_CLASS"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:complexType name="join-column">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(JoinColumns.class)
        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface JoinColumn {
          String name() default "";
          String referencedColumnName() default "";
          boolean unique() default false;
          boolean nullable() default true;
          boolean insertable() default true;
          boolean updatable() default true;
          String columnDefinition() default "";
          String options() default "";
          String table() default "";
          ForeignKey foreignKey() default @ForeignKey();
          CheckConstraint[] check() default {};
          String comment() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="comment" type="xsd:string" minOccurs="0" />
      <xsd:element name="foreign-key" type="orm:foreign-key"
                   minOccurs="0"/>
      <xsd:element name="check-constraint" type="orm:check-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="referenced-column-name" type="xsd:string"/>
    <xsd:attribute name="unique" type="xsd:boolean"/>
    <xsd:attribute name="nullable" type="xsd:boolean"/>
    <xsd:attribute name="insertable" type="xsd:boolean"/>
    <xsd:attribute name="updatable" type="xsd:boolean"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
    <xsd:attribute name="table" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="join-table">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface JoinTable {
          String name() default "";
          String catalog() default "";
          String schema() default "";
          JoinColumn[] joinColumns() default {};
          JoinColumn[] inverseJoinColumns() default {};
          ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
          ForeignKey inverseForeignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
          UniqueConstraint[] uniqueConstraints() default {};
          Index[] indexes() default {};
          CheckConstraint[] check() default {};
          String comment() default "";
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="comment" type="xsd:string" minOccurs="0" />
      <xsd:sequence>
        <xsd:element name="join-column" type="orm:join-column"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="foreign-key" type="orm:foreign-key"
                     minOccurs="0"/>
      </xsd:sequence>
      <xsd:sequence>
        <xsd:element name="inverse-join-column" type="orm:join-column"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="inverse-foreign-key" type="orm:foreign-key"
                     minOccurs="0"/>
      </xsd:sequence>
      <xsd:element name="unique-constraint" type="orm:unique-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="index" type="orm:index"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="check-constraint" type="orm:check-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="lob">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Lob {}

      </xsd:documentation>
    </xsd:annotation>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="lock-mode-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum LockModeType implements FindOption, RefreshOption { READ, WRITE, OPTIMISTIC, OPTIMISTIC_FORCE_INCREMENT, PESSIMISTIC_READ, PESSIMISTIC_WRITE, PESSIMISTIC_FORCE_INCREMENT, NONE}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="READ"/>
      <xsd:enumeration value="WRITE"/>
      <xsd:enumeration value="OPTIMISTIC"/>
      <xsd:enumeration value="OPTIMISTIC_FORCE_INCREMENT"/>
      <xsd:enumeration value="PESSIMISTIC_READ"/>
      <xsd:enumeration value="PESSIMISTIC_WRITE"/>
      <xsd:enumeration value="PESSIMISTIC_FORCE_INCREMENT"/>
      <xsd:enumeration value="NONE"/>

    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

<xsd:complexType name="many-to-many">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface ManyToMany {
          Class<?> targetEntity() default void.class;
          CascadeType[] cascade() default {};
          FetchType fetch() default FetchType.LAZY;
          String mappedBy() default "";
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice>
        <xsd:element name="order-by" type="orm:order-by"
                   minOccurs="0"/>
        <xsd:element name="order-column" type="orm:order-column"
                   minOccurs="0"/>
      </xsd:choice>
      <xsd:choice>
        <xsd:element name="map-key" type="orm:map-key"
                   minOccurs="0"/>
        <xsd:sequence>
          <xsd:element name="map-key-class" type="orm:map-key-class"
                   minOccurs="0"/>
          <xsd:choice>
            <xsd:element name="map-key-temporal"
                         type="orm:temporal"
                         minOccurs="0"/>
            <xsd:element name="map-key-enumerated"
                         type="orm:enumerated"
                         minOccurs="0"/>
            <xsd:sequence>
               <xsd:element name="map-key-attribute-override"
                            type="orm:attribute-override"
                            minOccurs="0" maxOccurs="unbounded"/>
               <xsd:element name="map-key-convert" type="orm:convert"
                            minOccurs="0" maxOccurs="unbounded"/>
            </xsd:sequence>
          </xsd:choice>
          <xsd:choice>
            <xsd:element name="map-key-column" type="orm:map-key-column"
                   minOccurs="0"/>
            <xsd:sequence>
              <xsd:element name="map-key-join-column"
                     type="orm:map-key-join-column"
                     minOccurs="0" maxOccurs="unbounded"/>
              <xsd:element name="map-key-foreign-key"
                           type="orm:foreign-key"
                           minOccurs="0"/>
            </xsd:sequence>
          </xsd:choice>
        </xsd:sequence>
      </xsd:choice>
      <xsd:element name="join-table" type="orm:join-table"
                   minOccurs="0"/>
      <xsd:element name="cascade" type="orm:cascade-type"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-entity" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="mapped-by" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="many-to-one">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface ManyToOne {
          Class<?> targetEntity() default void.class;
          CascadeType[] cascade() default {};
          FetchType fetch() default FetchType.EAGER;
          boolean optional() default true;
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice>
        <xsd:sequence>
          <xsd:element name="join-column" type="orm:join-column"
                       minOccurs="0" maxOccurs="unbounded"/>
          <xsd:element name="foreign-key" type="orm:foreign-key"
                       minOccurs="0"/>
        </xsd:sequence>
        <xsd:element name="join-table" type="orm:join-table"
                     minOccurs="0"/>
      </xsd:choice>
      <xsd:element name="cascade" type="orm:cascade-type"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-entity" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="optional" type="xsd:boolean"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="maps-id" type="xsd:string"/>
    <xsd:attribute name="id" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="map-key">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface MapKey {
          String name() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="map-key-class">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface MapKeyClass {
          Class<?> value();
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="map-key-column">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface MapKeyColumn {
          String name() default "";
          boolean unique() default false;
          boolean nullable() default false;
          boolean insertable() default true;
          boolean updatable() default true;
          String columnDefinition() default "";
          String options() default "";
          String table() default "";
          int length() default 255;
          int precision() default 0; // decimal precision
          int scale() default 0; // decimal scale
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="unique" type="xsd:boolean"/>
    <xsd:attribute name="nullable" type="xsd:boolean"/>
    <xsd:attribute name="insertable" type="xsd:boolean"/>
    <xsd:attribute name="updatable" type="xsd:boolean"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
    <xsd:attribute name="table" type="xsd:string"/>
    <xsd:attribute name="length" type="xsd:int"/>
    <xsd:attribute name="precision" type="xsd:int"/>
    <xsd:attribute name="scale" type="xsd:int"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="map-key-join-column">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(MapKeyJoinColumns.class)
        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface MapKeyJoinColumn {
          String name() default "";
          String referencedColumnName() default "";
          boolean unique() default false;
          boolean nullable() default false;
          boolean insertable() default true;
          boolean updatable() default true;
          String columnDefinition() default "";
          String options() default "";
          String table() default "";
          ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="foreign-key" type="orm:foreign-key"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="referenced-column-name" type="xsd:string"/>
    <xsd:attribute name="unique" type="xsd:boolean"/>
    <xsd:attribute name="nullable" type="xsd:boolean"/>
    <xsd:attribute name="insertable" type="xsd:boolean"/>
    <xsd:attribute name="updatable" type="xsd:boolean"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
    <xsd:attribute name="table" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="mapped-superclass">
    <xsd:annotation>
      <xsd:documentation>

        Defines the settings and mappings for a mapped superclass. Is
        allowed to be sparsely populated and used in conjunction with
        the annotations. Alternatively, the metadata-complete attribute
        can be used to indicate that no annotations are to be processed
        If this is the case then the defaulting rules will be recursively
        applied.

        @Target(TYPE) @Retention(RUNTIME)
        public @interface MappedSuperclass {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="id-class" type="orm:id-class" minOccurs="0"/>
      <xsd:element name="exclude-default-listeners" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="exclude-superclass-listeners" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="entity-listeners" type="orm:entity-listeners"
                   minOccurs="0"/>
      <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/>
      <xsd:element name="post-persist" type="orm:post-persist"
                   minOccurs="0"/>
      <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/>
      <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/>
      <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/>
      <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/>
      <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/>
      <xsd:element name="attributes" type="orm:attributes" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="metadata-complete" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="named-attribute-node">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface NamedAttributeNode {
          String value();
          String subgraph() default "";
          String keySubgraph() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="subgraph" type="xsd:string"/>
    <xsd:attribute name="key-subgraph" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="named-entity-graph">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(NamedEntityGraphs.class)
        @Target({TYPE}) @Retention(RUNTIME)
        public @interface NamedEntityGraph {
          String name() default "";
          NamedAttributeNode[] attributeNodes() default {};
          boolean includeAllAttributes() default false;
          NamedSubgraph[] subgraphs() default {};
          NamedSubGraph[] subclassSubgraphs() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="named-attribute-node"
                   type="orm:named-attribute-node"
                   minOccurs="0"
                   maxOccurs="unbounded"/>
      <xsd:element name="subgraph"
                   type="orm:named-subgraph"
                   minOccurs="0"
                   maxOccurs="unbounded"/>
      <xsd:element name="subclass-subgraph"
                   type="orm:named-subgraph"
                   minOccurs="0"
                   maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="include-all-attributes" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="named-native-query">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Repeatable(NamedNativeQueries.class)
        @Target({TYPE}) @Retention(RUNTIME)
        public @interface NamedNativeQuery {
          String name();
          String query();
          QueryHint[] hints() default {};
          Class<?> resultClass() default void.class;
          String resultSetMapping() default ""; //named SqlResultSetMapping
          EntityResult[] entities() default {};
          ConstructorResult[] classes() default {};
          ColumnResult[] columns() default {};
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="query" type="xsd:string"/>
      <xsd:element name="hint" type="orm:query-hint"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="entity-result" type="orm:entity-result"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="constructor-result" type="orm:constructor-result"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="column-result" type="orm:column-result"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="result-class" type="xsd:string"/>
    <xsd:attribute name="result-set-mapping" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="named-query">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(NamedQueries.class)
        @Target({TYPE}) @Retention(RUNTIME)
        public @interface NamedQuery {
          String name();
          String query();
          LockModeType lockMode() default LockModeType.NONE;
          QueryHint[] hints() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="query" type="xsd:string"/>
      <xsd:element name="lock-mode" type="orm:lock-mode-type" minOccurs="0"/>
      <xsd:element name="hint" type="orm:query-hint"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
</xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="named-stored-procedure-query">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(NamedStoredProcedureQueries.class)
        @Target({TYPE}) @Retention(RUNTIME)
        public @interface NamedStoredProcedureQuery {
          String name();
          String procedureName();
          StoredProcedureParameter[] parameters() default {};
          Class[] resultClasses() default {};
          String[] resultSetMappings() default{};
          QueryHint[] hints() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="parameter"
                   type="orm:stored-procedure-parameter"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="result-class" type="xsd:string"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="result-set-mapping" type="xsd:string"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="hint" type="orm:query-hint"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="procedure-name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="named-subgraph">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({}) @Retention(RUNTIME)
        public @interface NamedSubgraph {
          String name();
          Class<?> type() default void.class;
          NamedAttributeNode[] attributeNodes();
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="named-attribute-node"
                   type="orm:named-attribute-node"
                   minOccurs="0"
                   maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="class" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

<xsd:complexType name="one-to-many">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface OneToMany {
          Class<?> targetEntity() default void.class;
          CascadeType[] cascade() default {};
          FetchType fetch() default FetchType.LAZY;
          String mappedBy() default "";
          boolean orphanRemoval() default false;
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice>
        <xsd:element name="order-by" type="orm:order-by"
                   minOccurs="0"/>
        <xsd:element name="order-column" type="orm:order-column"
                   minOccurs="0"/>
      </xsd:choice>
      <xsd:choice>
        <xsd:element name="map-key" type="orm:map-key"
                   minOccurs="0"/>
        <xsd:sequence>
          <xsd:element name="map-key-class" type="orm:map-key-class"
                   minOccurs="0"/>
          <xsd:choice>
            <xsd:element name="map-key-temporal"
                         type="orm:temporal"
                         minOccurs="0"/>
            <xsd:element name="map-key-enumerated"
                         type="orm:enumerated"
                         minOccurs="0"/>
            <xsd:sequence>
               <xsd:element name="map-key-attribute-override"
                            type="orm:attribute-override"
                            minOccurs="0" maxOccurs="unbounded"/>
               <xsd:element name="map-key-convert" type="orm:convert"
                            minOccurs="0" maxOccurs="unbounded"/>
            </xsd:sequence>
          </xsd:choice>
          <xsd:choice>
            <xsd:element name="map-key-column" type="orm:map-key-column"
                   minOccurs="0"/>
            <xsd:sequence>
              <xsd:element name="map-key-join-column"
                           type="orm:map-key-join-column"
                           minOccurs="0" maxOccurs="unbounded"/>
              <xsd:element name="map-key-foreign-key"
                           type="orm:foreign-key"
                           minOccurs="0"/>
            </xsd:sequence>
          </xsd:choice>
        </xsd:sequence>
      </xsd:choice>
      <xsd:choice>
        <xsd:element name="join-table" type="orm:join-table"
                     minOccurs="0"/>
        <xsd:sequence>
          <xsd:element name="join-column" type="orm:join-column"
                       minOccurs="0" maxOccurs="unbounded"/>
          <xsd:element name="foreign-key" type="orm:foreign-key"
                       minOccurs="0"/>
        </xsd:sequence>
      </xsd:choice>
      <xsd:element name="cascade" type="orm:cascade-type"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-entity" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="mapped-by" type="xsd:string"/>
    <xsd:attribute name="orphan-removal" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="one-to-one">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface OneToOne {
          Class<?> targetEntity() default void.class;
          CascadeType[] cascade() default {};
          FetchType fetch() default FetchType.EAGER;
          boolean optional() default true;
          String mappedBy() default "";
          boolean orphanRemoval() default false;
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice>
        <xsd:sequence>
          <xsd:element name="primary-key-join-column"
                       type="orm:primary-key-join-column"
                       minOccurs="0" maxOccurs="unbounded"/>
          <xsd:element name="primary-key-foreign-key"
                       type="orm:foreign-key"
                       minOccurs="0"/>
        </xsd:sequence>
        <xsd:sequence>
          <xsd:element name="join-column" type="orm:join-column"
                       minOccurs="0" maxOccurs="unbounded"/>
          <xsd:element name="foreign-key" type="orm:foreign-key"
                       minOccurs="0"/>
        </xsd:sequence>
        <xsd:element name="join-table" type="orm:join-table"
                     minOccurs="0"/>
      </xsd:choice>
      <xsd:element name="cascade" type="orm:cascade-type"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-entity" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="optional" type="xsd:boolean"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="mapped-by" type="xsd:string"/>
    <xsd:attribute name="orphan-removal" type="xsd:boolean"/>
    <xsd:attribute name="maps-id" type="xsd:string"/>
    <xsd:attribute name="id" type="xsd:boolean"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="order-by">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface OrderBy {
          String value() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string"/>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:complexType name="order-column">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface OrderColumn {
          String name() default "";
          boolean nullable() default true;
          boolean insertable() default true;
          boolean updatable() default true;
          String columnDefinition() default "";
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="nullable" type="xsd:boolean"/>
    <xsd:attribute name="insertable" type="xsd:boolean"/>
    <xsd:attribute name="updatable" type="xsd:boolean"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="parameter-mode">
    <xsd:annotation>
      <xsd:documentation>

        public enum ParameterMode { IN, INOUT, OUT, REF_CURSOR }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="IN"/>
      <xsd:enumeration value="INOUT"/>
      <xsd:enumeration value="OUT"/>
      <xsd:enumeration value="REF_CURSOR"/>
    </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:complexType name="post-load">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PostLoad {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="post-persist">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PostPersist {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="post-remove">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PostRemove {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="post-update">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PostUpdate {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="pre-persist">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PrePersist {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="pre-remove">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PreRemove {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="pre-update">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PreUpdate {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="primary-key-join-column">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(PrimaryKeyJoinColumns.class)
        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface PrimaryKeyJoinColumn {
          String name() default "";
          String referencedColumnName() default "";
          String columnDefinition() default "";
          String options() default "";
          ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="foreign-key" type="orm:foreign-key"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="referenced-column-name" type="xsd:string"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="query-hint">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface QueryHint {
          String name();
          String value();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="value" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="secondary-table">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(SecondaryTables.class)
        @Target({TYPE}) @Retention(RUNTIME)
        public @interface SecondaryTable {
          String name();
          String catalog() default "";
          String schema() default "";
          PrimaryKeyJoinColumn[] pkJoinColumns() default {};
          ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
          UniqueConstraint[] uniqueConstraints() default {};
          Index[] indexes() default {};
          CheckConstraint[] check() default {};
          String comment() default "";
          String options() default "";
        }

       </xsd:documentation>
     </xsd:annotation>
     <xsd:sequence>
       <xsd:sequence>
         <xsd:element name="comment" type="xsd:string" minOccurs="0" />
         <xsd:element name="primary-key-join-column"
                      type="orm:primary-key-join-column"
                      minOccurs="0" maxOccurs="unbounded"/>
         <xsd:element name="primary-key-foreign-key"
                      type="orm:foreign-key"
                      minOccurs="0"/>
       </xsd:sequence>
       <xsd:element name="unique-constraint" type="orm:unique-constraint"
                    minOccurs="0" maxOccurs="unbounded"/>
       <xsd:element name="index" type="orm:index"
                    minOccurs="0" maxOccurs="unbounded"/>
       <xsd:element name="foreign-key" type="orm:foreign-key"
                    minOccurs="0"/>
       <xsd:element name="check-constraint" type="orm:check-constraint"
                    minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="sequence-generator">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(SequenceGenerators.class)
        @Target({TYPE, METHOD, FIELD, PACKAGE}) @Retention(RUNTIME)
        public @interface SequenceGenerator {
          String name() default "";
          String sequenceName() default "";
          String catalog() default "";
          String schema() default "";
          int initialValue() default 1;
          int allocationSize() default 50;
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="sequence-name" type="xsd:string"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
    <xsd:attribute name="initial-value" type="xsd:int"/>
    <xsd:attribute name="allocation-size" type="xsd:int"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="sql-result-set-mapping">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(SqlResultSetMappings.class)
        @Target({TYPE}) @Retention(RUNTIME)
        public @interface SqlResultSetMapping {
          String name();
          EntityResult[] entities() default {};
          ConstructorResult[] classes() default{};
          ColumnResult[] columns() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="entity-result" type="orm:entity-result"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="constructor-result" type="orm:constructor-result"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="column-result" type="orm:column-result"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="stored-procedure-parameter">
    <xsd:annotation>
      <xsd:documentation><![CDATA[

        @Target({}) @Retention(RUNTIME)
        public @interface StoredProcedureParameter {
          String name() default "";
          ParameterMode mode() default ParameterMode.IN;
          Class<?> type();
        }

      ]]></xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
    <xsd:attribute name="mode" type="orm:parameter-mode"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="table">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface Table {
          String name() default "";
          String catalog() default "";
          String schema() default "";
          UniqueConstraint[] uniqueConstraints() default {};
          Index[] indexes() default {};
          CheckConstraint[] check() default {};
          String comment() default "";
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="comment" type="xsd:string" minOccurs="0" />
      <xsd:element name="unique-constraint" type="orm:unique-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="index" type="orm:index"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="check-constraint" type="orm:check-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="table-generator">
    <xsd:annotation>
      <xsd:documentation>

        @Repeatable(TableGenerators.class)
        @Target({TYPE, METHOD, FIELD, PACKAGE}) @Retention(RUNTIME)
        public @interface TableGenerator {
          String name() default "";
          String table() default "";
          String catalog() default "";
          String schema() default "";
          String pkColumnName() default "";
          String valueColumnName() default "";
          String pkColumnValue() default "";
          int initialValue() default 0;
          int allocationSize() default 50;
          UniqueConstraint[] uniqueConstraints() default {};
          Indexes[] indexes() default {};
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="unique-constraint" type="orm:unique-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="index" type="orm:index"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="check-constraint" type="orm:check-constraint"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="table" type="xsd:string"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
    <xsd:attribute name="pk-column-name" type="xsd:string"/>
    <xsd:attribute name="value-column-name" type="xsd:string"/>
    <xsd:attribute name="pk-column-value" type="xsd:string"/>
    <xsd:attribute name="initial-value" type="xsd:int"/>
    <xsd:attribute name="allocation-size" type="xsd:int"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:simpleType name="temporal">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Temporal {
          TemporalType value();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="orm:temporal-type"/>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:simpleType name="temporal-type">
    <xsd:annotation>
      <xsd:documentation>

        @Deprecated(since = "3.2")
        public enum TemporalType {
          DATE, // java.sql.Date
          TIME, // java.sql.Time
          TIMESTAMP // java.sql.Timestamp
        }

      </xsd:documentation>
    </xsd:annotation>
      <xsd:restriction base="xsd:token">
        <xsd:enumeration value="DATE"/>
        <xsd:enumeration value="TIME"/>
        <xsd:enumeration value="TIMESTAMP"/>
     </xsd:restriction>
  </xsd:simpleType>

<!-- **************************************************** -->

  <xsd:complexType name="transient">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Transient {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="unique-constraint">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface UniqueConstraint {
          String name() default "";
          String[] columnNames();
          String options() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column-name" type="xsd:string"
                   maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="options" type="xsd:string"/>
  </xsd:complexType>

<!-- **************************************************** -->

  <xsd:complexType name="version">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Version {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column" type="orm:column" minOccurs="0"/>
      <xsd:element name="temporal" type="orm:temporal" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
  </xsd:complexType>

</xsd:schema>
package jakarta.persistence;

import java.util.Map;
import java.util.List;

import jakarta.persistence.criteria.CriteriaSelect;
import jakarta.persistence.metamodel.Metamodel;
import jakarta.persistence.criteria.CriteriaBuilder;
import jakarta.persistence.criteria.CriteriaQuery;
import jakarta.persistence.criteria.CriteriaUpdate;
import jakarta.persistence.criteria.CriteriaDelete;

/**
 * Interface used to interact with the persistence context.
 *
 * An instance of {@code EntityManager} must be obtained from
 * an {@link EntityManagerFactory}, and is only able to manage
 * persistence of entities belonging to the associated persistence
 * unit.
 *
 * An application-managed {@code EntityManager} may be created
 * via a call to {@link EntityManagerFactory#createEntityManager()}.
 * The {@code EntityManager} must be explicitly closed via a call
 * to {@link #close()}, to allow resources to be cleaned up by the
 * persistence provider. This approach places almost complete
 * responsibility for cleanup and exception management on the client,
 * and is thus considered quite error-prone. It is much safer to use
 * the methods {@link EntityManagerFactory#runInTransaction} and
 * {@link EntityManagerFactory#callInTransaction}.
 * {@snippet :
 * entityManagerFactory.runInTransaction(entityManager -> {
 * // do work in a persistence context
 * ...
 * });
 * }
 *
 * In the Jakarta EE environment, a container-managed
 * {@link EntityManager} may be obtained by dependency injection,
 * using {@link PersistenceContext}.
 * {@snippet :
 * // inject the container-managed entity manager
 * @PersistenceContext(unitName="orderMgt")
 * EntityManager entityManager;
 * }
 *
 * If the persistence unit has
 * {@linkplain PersistenceUnitTransactionType#RESOURCE_LOCAL
 * resource local} transaction management, transactions must
 * be managed using the {@link EntityTransaction} obtained by
 * calling {@link #getTransaction()}.
 *
 * A complete idiom for custom application management of
 * the {@link EntityManager} and its associated resource-local
 * {@link EntityTransaction} is as follows:
 * {@snippet :
 * EntityManager entityManager = entityManagerFactory.createEntityManager();
 * EntityTransaction transaction = entityManager.getTransaction();
 * try {
 * transaction.begin();
 * // do work
 * ...
 * transaction.commit();
 * }
 * catch (Exception e) {
 * if (transaction.isActive()) transaction.rollback();
 * throw e;
 * }
 * finally {
 * entityManager.close();
 * }
 * }
 *
 * Each {@code EntityManager} instance is associated with a
 * distinct persistence context. A persistence context
 * is a set of entity instances in which for any given persistent
 * entity identity (defined by an entity type and primary key)
 * there is at most one entity instance. The entity instances
 * associated with a persistence context are considered managed
 * objects, with a well-defined lifecycle under the control of
 * the persistence provider.
 *
 * Any entity instance can be characterized as being in one of
 * the following lifecycle states:
 * <ul>
 * <li>A new entity has no persistent identity, and is
 * not yet associated with any persistence context.
 * <li>A managed entity is an instance with a persistent
 * identity that is currently associated with a persistence
 * context.
 * <li>A detached entity is an instance with a persistent
 * identity that is not (or no longer) associated with any
 * active persistence context.
 * <li>A removed entity is an instance with a persistent
 * identity, and associated with a persistence context, that
 * is scheduled for removal from the database upon transaction
 * commit.
 * </ul>
 *
 * The {@code EntityManager} API is used to perform operations
 * that affect the state of the persistence context, or that modify
 * the lifecycle state of individual entity instances. The client
 * may {@linkplain #persist} and {@linkplain #remove} instances,
 * {@linkplain #find(Class, Object) find} entities by their primary
 * key, and execute {@linkplain #createQuery(String) queries} which
 * range over entity types. An entity may be disassociated from
 * the persistence context by calling {@link #detach}, and a
 * persistence context may be completely cleared, detaching all
 * its entities, by calling {@link #clear()}.
 *
 * The client may also make changes to the state of an entity
 * instance by mutating the entity directly, or it may request
 * that the state of a detached instance be {@linkplain #merge
 * merged}, replacing the state of a managed instance with the
 * same persistent identity. Note that there is no explicit
 * "update" operation; since an entity is a managed object,
 * modifications to its persistent fields and properties are
 * automatically detected, as long as it is associated with an
 * active persistence context.
 *
 * Modifications to the state of entities associated with a
 * persistence context are not immediately synchronized with the
 * database. Synchronization happens during a process called
 * flush. The timing of the flush process depends on the
 * {@linkplain FlushModeType flush mode}, which may be set
 * explicitly by calling {@link #setFlushMode(FlushModeType)}.
 * <ul>
 * <li>For {@link FlushModeType#COMMIT}, the persistence context
 * is flushed before the transaction commits.
 * <li>For {@link FlushModeType#AUTO}, which is the default, the
 * persistence context must also be flushed before execution
 * of any query whose result set would be affected by
 * unflushed modifications to entities associated with the
 * persistence context.
 * </ul>
 * The client may force an immediate flush to occur by calling
 * {@link #flush()}.
 *
 * At any given moment, a persistence context might hold an
 * optimistic or pessimistic lock on an entity instance.
 * The full range of possible lock types is enumerated by
 * {@link LockModeType}. Some operations of this interface,
 * including the methods {@link #lock(Object, LockModeType)},
 * {@link #refresh(Object, LockModeType)}, and
 * {@link #find(Class, Object, LockModeType)}, accept an explicit
 * {@link LockModeType}, allowing the client to request a specific
 * type of lock.
 *
 * Interaction of the persistence context (or first-level cache)
 * with the second-level cache, if any, may be controlled by
 * calling {@link #setCacheRetrieveMode(CacheRetrieveMode)} and
 * {@link #setCacheStoreMode(CacheStoreMode)}.
 *
 * Some operations accept one or more built-in and vendor-specific
 * options:
 * <ul>
 * <li>{@link #find(Class, Object, FindOption...)} and 
 * {@link #find(EntityGraph, Object, FindOption...)} accept
 * {@link FindOption}s,
 * <li>{@link #refresh(Object, RefreshOption...)} accepts
 * {@link RefreshOption}s, and
 * <li>{@link #lock(Object, LockModeType, LockOption...)} accepts
 * {@link LockOption}s.
 * </ul>
 *
 * @see Query
 * @see TypedQuery
 * @see CriteriaQuery
 * @see PersistenceContext
 * @see StoredProcedureQuery
 * @see EntityManagerFactory
 * 
 * @since 1.0
 */
public interface EntityManager extends AutoCloseable {

    /**
     * Make a new entity instance managed and persistent, resulting in
     * its insertion in the database when the persistence context is
     * synchronized with the database, or make a removed entity managed,
     * undoing the effect of a previous call to {@link #remove(Object)}.
     * This operation cascades to every entity related by an association
     * marked {@link CascadeType#PERSIST cascade=PERSIST}. If the given
     * entity instance is already managed, that is, if it already belongs
     * to this persistence context, and has not been marked for removal,
     * it is itself ignored, but the operation still cascades.
     * @param entity  a new, managed, or removed entity instance
     * @throws EntityExistsException if the given entity is detached
     * (if the entity is detached, the {@code EntityExistsException}
     * may be thrown when the persist operation is invoked, or the
     * {@code EntityExistsException} or another {@code PersistenceException}
     * may be thrown at flush or commit time)
     * @throws IllegalArgumentException if the given instance is not an
     *         entity
     * @throws TransactionRequiredException if there is no transaction
     *         when invoked on a container-managed entity manager that
     *         is of type {@link PersistenceContextType#TRANSACTION}
     */
    void persist(Object entity);

    /**
     * Merge the state of the given new or detached entity instance
     * into the current persistence context, resulting in, respectively,
     * an insert or possible update when the persistence context is
     * synchronized with the database. Return a managed instance with
     * the same persistent state as the given entity instance, but a
     * distinct Java object identity. If the given entity is detached,
     * the returned entity has the same persistent identity. This
     * operation cascades to every entity related by an association
     * marked {@link CascadeType#MERGE cascade=MERGE}. If the given
     * entity instance is managed, that is, if it belongs to this
     * persistence context, and has not been marked for removal, it is
     * itself ignored, but the operation still cascades, and it is
     * returned directly.
     * @param entity  a new, managed, or detached entity instance
     * @return the managed instance that the state was merged to
     * @throws IllegalArgumentException if the instance is not an entity
     *         or is a removed entity
     * @throws TransactionRequiredException if there is no transaction
     *         when invoked on a container-managed entity manager of
     *         that is of type {@link PersistenceContextType#TRANSACTION}
     */
    <T> T merge(T entity);

    /**
     * Mark a managed entity instance as removed, resulting in its deletion
     * from the database when the persistence context is synchronized with
     * the database. This operation cascades to every entity related by an
     * association marked {@link CascadeType#REMOVE cascade=REMOVE}. If the
     * given entity instance is already removed, it is ignored. If the
     * given entity is new, it is itself ignored, but the operation still
     * cascades.
     * @param entity  a managed, new, or removed entity instance
     * @throws IllegalArgumentException if the instance is not an entity
     *         or is a detached entity
     * @throws TransactionRequiredException if invoked on a
     *         container-managed entity manager of type
     *         {@link PersistenceContextType#TRANSACTION} and there is
     *         no transaction
     */
    void remove(Object entity);

    /**
     * Find by primary key.
     * Search for an entity of the specified class and primary key.
     * If the entity instance is contained in the persistence context,
     * it is returned from there.
     * @param entityClass  entity class
     * @param primaryKey  primary key
     * @return the found entity instance or null if the entity does
     *         not exist
     * @throws IllegalArgumentException if the first argument does
     *         not denote an entity type or if the second argument is
     *         not a valid type for that entity's primary key or is
     *         null
     */
    <T> T find(Class<T> entityClass, Object primaryKey);

    /**
     * Find by primary key, using the specified properties. 
     * Search for an entity of the specified class and primary key. 
     * If the entity instance is contained in the persistence 
     * context, it is returned from there. 
     * If a vendor-specific property or hint is not recognized, 
     * it is silently ignored. 
     * @param entityClass  entity class
     * @param primaryKey   primary key
     * @param properties  standard and vendor-specific properties 
     *        and hints
     * @return the found entity instance or null if the entity does
     *         not exist
     * @throws IllegalArgumentException if the first argument does 
     *         not denote an entity type or if the second argument
     *         is not a valid type for that entity's primary key or
     *         is null
     * @since 2.0
     */
    <T> T find(Class<T> entityClass, Object primaryKey,
               Map<String, Object> properties);

    /**
     * Find by primary key and obtain the given lock type for the
     * resulting entity. Search for an entity of the specified class and
     * primary key, and lock it with respect to the specified lock type.
     * If the entity instance is contained in the persistence context,
     * it is returned from there, and the effect of this method is the
     * same as if the {@link #lock} method had been called on the entity.
     * <p> If the entity is found within the persistence context and
     * the lock mode type is pessimistic and the entity has a version
     * attribute, the persistence provider must perform optimistic
     * version checks when obtaining the database lock. If these checks
     * fail, the {@link OptimisticLockException} is thrown.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback
     * </ul>
     * @param entityClass  entity class
     * @param primaryKey  primary key
     * @param lockMode  lock mode
     * @return the found entity instance or null if the entity does
     *         not exist
     * @throws IllegalArgumentException if the first argument does
     *         not denote an entity type or the second argument is
     *         not a valid type for that entity's primary key or
     *         is null
     * @throws TransactionRequiredException if there is no 
     *         transaction and a lock mode other than {@code NONE} is
     *         specified or if invoked on an entity manager which has
     *         not been joined to the current transaction and a lock
     *         mode other than {@code NONE} is specified
     * @throws OptimisticLockException if the optimistic version 
     *         check fails
     * @throws PessimisticLockException if pessimistic locking 
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *         only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 2.0
     */
    <T> T find(Class<T> entityClass, Object primaryKey,
               LockModeType lockMode);

    /**
     * Find by primary key and lock the entity, using the specified
     * properties. Search for an entity of the specified class and
     * primary key, and lock it with respect to the specified lock type.
     * If the entity instance is contained in the persistence context,
     * it is returned from there.  
     * <p> If the entity is found within the persistence context and
     * the lock mode type is pessimistic and the entity has a version
     * attribute, the persistence provider must perform optimistic
     * version checks when obtaining the database lock. If these checks
     * fail, the {@link OptimisticLockException} is thrown.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback
     * </ul>
     * <p>If a vendor-specific property or hint is not recognized, 
     * it is silently ignored.  
     * <p>Portable applications should not rely on the standard
     * timeout hint. Depending on the database in use and the locking
     * mechanisms used by the provider, the hint may or may not be
     * observed.
     * @param entityClass  entity class
     * @param primaryKey  primary key
     * @param lockMode  lock mode
     * @param properties  standard and vendor-specific properties
     *        and hints
     * @return the found entity instance or null if the entity does
     *         not exist
     * @throws IllegalArgumentException if the first argument does
     *         not denote an entity type or the second argument is
     *         not a valid type for that entity's primary key or
     *         is null
     * @throws TransactionRequiredException if there is no 
     *         transaction and a lock mode other than {@code NONE} is
     *         specified or if invoked on an entity manager which has
     *         not been joined to the current transaction and a lock
     *         mode other than {@code NONE} is specified
     * @throws OptimisticLockException if the optimistic version check
     *         fails
     * @throws PessimisticLockException if pessimistic locking fails
     *         and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *        only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 2.0
     */
    <T> T find(Class<T> entityClass, Object primaryKey,
               LockModeType lockMode,
               Map<String, Object> properties);

    /**
     * Find an instance of the given entity class by primary key,
     * using the specified {@linkplain FindOption options}.
     * Search for an entity with the specified class and primary key.
     * If the given options include a {@link LockModeType}, lock it
     * with respect to the specified lock type.
     * If the entity instance is contained in the persistence context,
     * it is returned from there.
     * <p>If the entity is found within the persistence context and
     * the lock mode type is pessimistic and the entity has a version
     * attribute, the persistence provider must perform optimistic
     * version checks when obtaining the database lock.  If these checks
     * fail, the {@code OptimisticLockException} is thrown.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@code PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level
     *     rollback
     * <li>the {@code LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback
     * </ul>
     * <p>If a vendor-specific {@linkplain FindOption option} is not
     * recognized, it is silently ignored.
     * <p>Portable applications should not rely on the standard
     * {@linkplain Timeout timeout option}. Depending on the database
     * in use and the locking mechanisms used by the provider, this
     * option may or may not be observed.
     * @param entityClass  entity class
     * @param primaryKey  primary key
     * @param options  standard and vendor-specific options
     * @return the found entity instance or null if the entity does
     *         not exist
     * @throws IllegalArgumentException if there are contradictory
     *         options, if the first argument does not denote an entity
     *         type belonging to the persistence unit, or if the second
     *         argument is not a valid non-null instance of the entity
     *         primary key type
     * @throws TransactionRequiredException if there is no transaction
     *         and a lock mode other than {@code NONE} is
     *         specified or if invoked on an entity manager which has
     *         not been joined to the current transaction and a lock
     *         mode other than {@code NONE} is specified
     * @throws OptimisticLockException if the optimistic version check
     *         fails
     * @throws PessimisticLockException if pessimistic locking fails
     *         and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *         only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 3.2
     */
    <T> T find(Class<T> entityClass, Object primaryKey,
               FindOption... options);

    /**
     * Find an instance of the root entity of the given {@link EntityGraph}
     * by primary key, using the specified {@linkplain FindOption options},
     * and interpreting the {@code EntityGraph} as a load graph.
     * Search for an entity with the specified type and primary key.
     * If the given options include a {@link LockModeType}, lock it
     * with respect to the specified lock type.
     * If the entity instance is contained in the persistence context,
     * it is returned from there.
     * <p> If the entity is found within the persistence context and
     * the lock mode type is pessimistic and the entity has a version
     * attribute, the persistence provider must perform optimistic
     * version checks when obtaining the database lock. If these checks
     * fail, the {@code OptimisticLockException} is thrown.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback
     * </ul>
     * <p>If a vendor-specific {@linkplain FindOption option} is not
     * recognized, it is silently ignored.
     * <p>Portable applications should not rely on the standard
     * {@linkplain Timeout timeout option}. Depending on the database
     * in use and the locking mechanisms used by the provider, this
     * option may or may not be observed.
     * @param entityGraph  entity graph interpreted as a load graph
     * @param primaryKey  primary key
     * @param options  standard and vendor-specific options
     * @return the found entity instance or null if the entity does
     *         not exist
     * @throws IllegalArgumentException if there are contradictory
     *         options, if the first argument does not denote an entity
     *         type belonging to the persistence unit, or if the second
     *         argument is not a valid non-null instance of the entity
     *         primary key type
     * @throws TransactionRequiredException if there is no transaction
     *         and a lock mode other than {@code NONE} is
     *         specified or if invoked on an entity manager which has
     *         not been joined to the current transaction and a lock
     *         mode other than {@code NONE} is specified
     * @throws OptimisticLockException if the optimistic version check
     *         fails
     * @throws PessimisticLockException if pessimistic locking fails
     *         and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *         only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 3.2
     */
    <T> T find(EntityGraph<T> entityGraph, Object primaryKey,
               FindOption... options);

    /**
     * Obtain a reference to an instance of the given entity class
     * with the given primary key, whose state may be lazily fetched.
     * <p>If the requested instance does not exist in the database,
     * the {@link EntityNotFoundException} is thrown when the
     * instance state is first accessed.
     * (The persistence provider runtime is permitted but not
     * required to throw the {@code EntityNotFoundException} when
     * {@code getReference()} is called.)
     * <p>This operation allows the application to create an
     * association to an entity without loading its state from the
     * database.
     * <p>The application should not expect the instance state to
     * be available upon detachment, unless it was accessed by the
     * application while the entity manager was open.
     * @param entityClass  entity class
     * @param primaryKey  primary key
     * @return a reference to the entity instance
     * @throws IllegalArgumentException if the first argument does
     *         not denote an entity type or the second argument is
     *         not a valid type for that entity's primary key or
     *         is null
     * @throws EntityNotFoundException if the entity state cannot
     *         be accessed
     */
    <T> T getReference(Class<T> entityClass, Object primaryKey);

    /**
     * Obtain a reference to an instance of the entity class of the
     * given object, with the same primary key as the given object,
     * whose state may be lazily fetched. The given object may be
     * persistent or detached, but may be neither new nor removed.
     * <p>If the requested instance does not exist in the database,
     * the {@link EntityNotFoundException} is thrown when the
     * instance state is first accessed.
     * (The persistence provider runtime is permitted but not
     * required to throw the {@code EntityNotFoundException} when
     * {@code getReference()} is called.)
     * <p>This operation allows the application to create an
     * association to an entity without loading its state from the
     * database.
     * <p>The application should not expect the instance state to
     * be available upon detachment, unless it was accessed by the
     * application while the entity manager was open.
     * @param entity  a persistent or detached entity instance
     * @return a reference to the entity instance
     * @throws IllegalArgumentException if the given object is not
     *         an entity, or if it is neither persistent nor detached
     * @throws EntityNotFoundException if the entity state cannot be
     *         accessed
     * @since 3.2
     */
    <T> T getReference(T entity);

    /**
     * Synchronize changes held in the persistence context to the
     * underlying database.
     * @throws TransactionRequiredException if there is
     *        no transaction or if the entity manager has not been
     *        joined to the current transaction
     * @throws PersistenceException if the flush fails
     */
    void flush();

    /**
     * Set the {@linkplain FlushModeType flush mode} that applies to
     * all objects contained in the persistence context.
     * @param flushMode  flush mode
     */
    void setFlushMode(FlushModeType flushMode);

    /**
     * Get the {@linkplain FlushModeType flush mode} that applies to
     * all objects contained in the persistence context.
     * @return the current {@link FlushModeType}
     */
    FlushModeType getFlushMode();

    /**
     * Lock an entity instance belonging to the persistence context,
     * obtaining the specified {@linkplain LockModeType lock mode}.
     * <p>If a pessimistic lock mode type is specified and the entity
     * contains a version attribute, the persistence provider must 
     * also perform optimistic version checks when obtaining the 
     * database lock. If these checks fail, the
     * {@link OptimisticLockException} is thrown.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback
     * </ul>
     * @param entity  a managed entity instance
     * @param lockMode  lock mode
     * @throws IllegalArgumentException if the instance is not an
     *         entity or is a detached entity
     * @throws TransactionRequiredException if there is no 
     *         transaction or if invoked on an entity manager which
     *         has not been joined to the current transaction
     * @throws EntityNotFoundException if the entity does not exist 
     *         in the database when pessimistic locking is
     *         performed
     * @throws OptimisticLockException if the optimistic version check
     *         fails
     * @throws PessimisticLockException if pessimistic locking fails 
     *         and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *         only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     */
    void lock(Object entity, LockModeType lockMode);

    /**
     * Lock an entity instance belonging to the persistence context,
     * obtaining the specified {@linkplain LockModeType lock mode},
     * using the specified properties.
     * <p>If a pessimistic lock mode type is specified and the entity
     * contains a version attribute, the persistence provider must 
     * also perform optimistic version checks when obtaining the 
     * database lock. If these checks fail, the
     * {@link OptimisticLockException} is thrown.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} ia thrown if the database
     *     locking failure causes only statement-level rollback
     * </ul>
     * <p>If a vendor-specific property or hint is not recognized, 
     * it is silently ignored.  
     * <p>Portable applications should not rely on the standard
     * timeout hint. Depending on the database in use and the locking
     * mechanisms used by the provider, the hint may or may not be
     * observed.
     * @param entity  a managed entity instance
     * @param lockMode  lock mode
     * @param properties  standard and vendor-specific properties
     *        and hints
     * @throws IllegalArgumentException if the instance is not an
     *         entity or is a detached entity
     * @throws TransactionRequiredException if there is no 
     *         transaction or if invoked on an entity manager which
     *         has not been joined to the current transaction
     * @throws EntityNotFoundException if the entity does not exist 
     *         in the database when pessimistic locking is performed
     * @throws OptimisticLockException if the optimistic version check
     *         fails
     * @throws PessimisticLockException if pessimistic locking fails 
     *         and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *         only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 2.0
     */
    void lock(Object entity, LockModeType lockMode,
              Map<String, Object> properties);

    /**
     * Lock an entity instance belonging to the persistence context,
     * obtaining the specified {@linkplain LockModeType lock mode},
     * using the specified {@linkplain LockOption options}.
     * <p>If a pessimistic lock mode type is specified and the entity
     * contains a version attribute, the persistence provider must
     * also perform optimistic version checks when obtaining the
     * database lock. If these checks fail, the
     * {@link OptimisticLockException} is thrown.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback
     * </ul>
     * <p>If a vendor-specific {@link LockOption} is not recognized,
     * it is silently ignored.
     * <p>Portable applications should not rely on the standard
     * {@linkplain Timeout timeout option}. Depending on the database
     * in use and the locking mechanisms used by the provider, the
     * option may or may not be observed.
     * @param entity  a managed entity instance
     * @param lockMode  lock mode
     * @param options  standard and vendor-specific options
     * @throws IllegalArgumentException if the instance is not an
     *         entity or is a detached entity
     * @throws TransactionRequiredException if there is no
     *         transaction or if invoked on an entity manager which
     *         has not been joined to the current transaction
     * @throws EntityNotFoundException if the entity does not exist
     *         in the database when pessimistic locking is
     *         performed
     * @throws OptimisticLockException if the optimistic version
     *         check fails
     * @throws PessimisticLockException if pessimistic locking fails
     *         and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *         only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 3.2
     */
    void lock(Object entity, LockModeType lockMode,
              LockOption... options);

    /**
     * Refresh the state of the given managed entity instance from
     * the database, overwriting unflushed changes made to the entity,
     * if any. This operation cascades to every entity related by an
     * association marked {@link CascadeType#REFRESH cascade=REFRESH}.
     * @param entity  a managed entity instance
     * @throws IllegalArgumentException if the instance is not
     *         an entity or the entity is not managed
     * @throws TransactionRequiredException if there is no
     *         transaction when invoked on a container-managed
     *         entity manager of type
     *         {@link PersistenceContextType#TRANSACTION}
     * @throws EntityNotFoundException if the entity no longer
     *        exists in the database
     */
    void refresh(Object entity);

    /**
     * Refresh the state of the given managed entity instance from
     * the database, using the specified properties, and overwriting
     * unflushed changes made to the entity, if any. This operation
     * cascades to every entity related by an association marked
     * {@link CascadeType#REFRESH cascade=REFRESH}.
     * <p>If a vendor-specific property or hint is not recognized,
     * it is silently ignored. 
     * @param entity  a managed entity instance
     * @param properties  standard and vendor-specific properties 
     *        and hints
     * @throws IllegalArgumentException if the instance is not 
     *         an entity or the entity is not managed
     * @throws TransactionRequiredException if there is no
     *         transaction when invoked on a container-managed
     *         entity manager of type
     *         {@link PersistenceContextType#TRANSACTION}
     * @throws EntityNotFoundException if the entity no longer 
     *         exists in the database
     * @since 2.0
     */
    void refresh(Object entity,
                 Map<String, Object> properties);

    /**
     * Refresh the state of the given managed entity instance from
     * the database, overwriting unflushed changes made to the entity,
     * if any, and obtain the given {@linkplain LockModeType lock mode}.
     * This operation cascades to every entity related by an association
     * marked {@link CascadeType#REFRESH cascade=REFRESH}.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback.
     * </ul>
     * @param entity  a managed entity instance
     * @param lockMode  lock mode
     * @throws IllegalArgumentException if the instance is not an entity
     *         or if the entity is not managed
     * @throws TransactionRequiredException if invoked on a 
     *         container-managed entity manager of type
     *         {@link PersistenceContextType#TRANSACTION} when there is
     *         no transaction; if invoked on an extended entity manager
     *         when there is no transaction and a lock mode other than
     *         {@link LockModeType#NONE} was specified; or if invoked
     *         on an extended entity manager that has not been joined
     *         to the current transaction and any lock mode other than
     *         {@code NONE} was specified
     * @throws EntityNotFoundException if the entity no longer exists
     *         in the database
     * @throws PessimisticLockException if pessimistic locking fails
     *         and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *         only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 2.0
     */
    void refresh(Object entity, LockModeType lockMode);

    /**
     * Refresh the state of the given managed entity instance from
     * the database, overwriting unflushed changes made to the entity,
     * if any, and obtain the given {@linkplain LockModeType lock mode},
     * using the specified properties. This operation cascades to every
     * entity related by an association marked {@link CascadeType#REFRESH
     * cascade=REFRESH}.
     * <p>If the lock mode type is pessimistic and the entity instance
     * is found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback.
     * </ul>
     * <p>If a vendor-specific property or hint is not recognized, 
     * it is silently ignored.
     * <p>Portable applications should not rely on the standard
     * timeout hint. Depending on the database in use and the locking
     * mechanisms used by the provider, the hint may or may not be
     * observed.
     * @param entity  a managed entity instance
     * @param lockMode  lock mode
     * @param properties  standard and vendor-specific properties
     *        and hints
     * @throws IllegalArgumentException if the instance is not an
     *         entity or if the entity is not managed
     * @throws TransactionRequiredException if invoked on a 
     *         container-managed entity manager of type
     *         {@link PersistenceContextType#TRANSACTION} when there is
     *         no transaction; if invoked on an extended entity manager
     *         when there is no transaction and a lock mode other than
     *         {@link LockModeType#NONE} was specified; or if invoked
     *         on an extended entity manager that has not been joined
     *         to the current transaction and any lock mode other than
     *         {@code NONE} was specified
     * @throws EntityNotFoundException if the entity no longer exists
     *        in the database
     * @throws PessimisticLockException if pessimistic locking fails
     *        and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and
     *        only the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 2.0
     */
    void refresh(Object entity, LockModeType lockMode,
                 Map<String, Object> properties);

    /**
     * Refresh the state of the given managed entity instance from the
     * database, using the specified {@linkplain RefreshOption options},
     * overwriting changes made to the entity, if any. If the supplied
     * options include a {@link LockModeType}, lock the given entity,
     * obtaining the given lock mode. This operation cascades to every
     * entity related by an association marked {@link CascadeType#REFRESH
     * cascade=REFRESH}.
     * <p>If the lock mode type is pessimistic and the entity instance is
     * found but cannot be locked:
     * <ul>
     * <li>the {@link PessimisticLockException} is thrown if the
     *     database locking failure causes transaction-level rollback
     * <li>the {@link LockTimeoutException} is thrown if the database
     *     locking failure causes only statement-level rollback.
     * </ul>
     * <p>If a vendor-specific {@link RefreshOption} is not recognized,
     * it is silently ignored.
     * <p>Portable applications should not rely on the standard
     * {@linkplain Timeout timeout option}. Depending on the database in
     * use and the locking mechanisms used by the provider, the hint may
     * or may not be observed.
     * @param entity  a managed entity instance
     * @param options  standard and vendor-specific options
     * @throws IllegalArgumentException if the instance is not an entity
     *         or if the entity is not managed
     * @throws TransactionRequiredException if invoked on a
     *         container-managed entity manager of type
     *         {@link PersistenceContextType#TRANSACTION} when there is
     *         no transaction; if invoked on an extended entity manager
     *         when there is no transaction and a lock mode other than
     *         {@link LockModeType#NONE} was specified; or if invoked
     *         on an extended entity manager that has not been joined
     *         to the current transaction and any lock mode other than
     *         {@code NONE} was specified
     * @throws EntityNotFoundException if the entity no longer exists in
     *         the database
     * @throws PessimisticLockException if pessimistic locking fails and
     *         the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking fails and only
     *         the statement is rolled back
     * @throws PersistenceException if an unsupported lock call is made
     * @since 3.2
     */
    void refresh(Object entity,
                 RefreshOption... options);

    /**
     * Clear the persistence context, causing all managed entities to
     * become detached. Changes made to entities that have not already
     * been flushed to the database will never be made persistent.
     */
    void clear();

    /**
     * Evict the given managed or removed entity from the persistence
     * context, causing the entity to become immediately detached.
     * Unflushed changes made to the entity, if any, including deletion
     * of the entity, will never be synchronized to the database.
     * Managed entities which reference the given entity continue to
     * reference it. This operation cascades to every entity related by
     * an association marked {@link CascadeType#DETACH cascade=DETACH}.
     * If the given entity instance is new or detached, that is, if it
     * is not associated with this persistence context, it is ignored.
     * @param entity  a managed or removed entity instance
     * @throws IllegalArgumentException if the instance is not an 
     *         entity
     * @since 2.0
     */
    void detach(Object entity);

    /**
     * Determine if the given object is a managed entity instance
     * belonging to the current persistence context.
     * @param entity  entity instance
     * @return boolean value indicating if entity belongs to the
     *         persistence context
     * @throws IllegalArgumentException if not an entity
     */
    boolean contains(Object entity);

    /**
     * Get the current {@linkplain LockModeType lock mode} held by
     * this persistence context on the given managed entity instance.
     * @param entity  a managed entity instance
     * @return the lock mode currently held
     * @throws TransactionRequiredException if there is no active
     *         transaction or if the entity manager has not been
     *         joined to the current transaction
     * @throws IllegalArgumentException if a transaction is active
     *         but the given instance is not a managed entity
     * @since 2.0
     */
    LockModeType getLockMode(Object entity);

    /**
     * Set the default {@linkplain CacheRetrieveMode cache retrieval
     * mode} for this persistence context.
     * @param cacheRetrieveMode cache retrieval mode
     * @since 3.2
     */
    void setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode);

    /**
     * Set the default {@linkplain CacheStoreMode cache storage mode}
     * for this persistence context.
     * @param cacheStoreMode cache storage mode
     * @since 3.2
     */
    void setCacheStoreMode(CacheStoreMode cacheStoreMode);

    /**
     * The cache retrieval mode for this persistence context.
     * @since 3.2
     */
    CacheRetrieveMode getCacheRetrieveMode();

    /**
     * The cache storage mode for this persistence context.
     * @since 3.2
     */
    CacheStoreMode getCacheStoreMode();

    /**
     * Set an entity manager property or hint. 
     * If a vendor-specific property or hint is not recognized, it is
     * silently ignored. 
     * @param propertyName name of the property or hint
     * @param value  value for the property or hint
     * @throws IllegalArgumentException if the property or hint name
     *         is recognized by the implementation, but the second
     *         argument is not valid value
     * @since 2.0
     */
    void setProperty(String propertyName, Object value);

    /**
     * The properties and hints and their associated values which are
     * in effect for this entity manager. Modifying the contents of
     * the returned map does not change the configuration in effect.
     * @return a map of properties and hints currently in effect
     * @since 2.0
     */
    Map<String, Object> getProperties();

    /**
     * Create an instance of {@link Query} for executing a
     * Jakarta Persistence query language statement.
     * @param qlString a Jakarta Persistence query string
     * @return the new query instance
     * @throws IllegalArgumentException if the query string is
     *         found to be invalid
     */
    Query createQuery(String qlString);

    /**
     * Create an instance of {@link TypedQuery} for executing a
     * criteria query.
     * @param criteriaQuery  a criteria query object
     * @return the new query instance
     * @throws IllegalArgumentException if the criteria query is
     *         found to be invalid
     * @since 2.0
     */
    <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery);

    /**
     * Create an instance of {@link TypedQuery} for executing a
     * criteria query, which may be a union or intersection of
     * top-level queries.
     * @param selectQuery  a criteria query object
     * @return the new query instance
     * @throws IllegalArgumentException if the criteria query is
     *         found to be invalid
     * @since 3.2
     */
    <T> TypedQuery<T> createQuery(CriteriaSelect<T> selectQuery);

    /**
     * Create an instance of {@link Query} for executing a criteria
     * update query.
     * @param updateQuery  a criteria update query object
     * @return the new query instance
     * @throws IllegalArgumentException if the update query is
     *         found to be invalid
     * @since 2.1
     */
    Query createQuery(CriteriaUpdate<?> updateQuery);

    /**
     * Create an instance of {@link Query} for executing a criteria
     * delete query.
     * @param deleteQuery  a criteria delete query object
     * @return the new query instance
     * @throws IllegalArgumentException if the delete query is
     *         found to be invalid
     * @since 2.1
     */
    Query createQuery(CriteriaDelete<?> deleteQuery);

    /**
     * Create an instance of {@link TypedQuery} for executing a
     * Jakarta Persistence query language statement.
     * The select list of the query must contain only a single
     * item, which must be assignable to the type specified by
     * the {@code resultClass} argument.
     * @param qlString a Jakarta Persistence query string
     * @param resultClass the type of the query result
     * @return the new query instance
     * @throws IllegalArgumentException if the query string is
     *         found to be invalid or if the query result is
     *         found to not be assignable to the specified type
     * @since 2.0
     */
    <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass);

    /**
     * Create an instance of {@link Query} for executing a named
     * query written in the Jakarta Persistence query language or
     * in native SQL.
     * @param name the name of a query defined in metadata
     * @return the new query instance
     * @throws IllegalArgumentException if a query has not been
     *         defined with the given name or if the query string is
     *         found to be invalid
     * @see NamedQuery
     * @see NamedNativeQuery
     */
    Query createNamedQuery(String name);

    /**
     * Create an instance of {@link TypedQuery} for executing a
     * Jakarta Persistence query language named query.
     * The select list of the query must contain only a single
     * item, which must be assignable to the type specified by
     * the {@code resultClass} argument.
     * @param name the name of a query defined in metadata
     * @param resultClass the type of the query result
     * @return the new query instance
     * @throws IllegalArgumentException if a query has not been
     *         defined with the given name or if the query string is
     *         found to be invalid or if the query result is found to
     *         not be assignable to the specified type
     * @since 2.0
     */
    <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass);

    /**
     * Create an instance of {@link TypedQuery} for executing a
     * named query written in the Jakarta Persistence query
     * language or in native SQL.
     * @param reference a reference to the query defined in metadata
     * @return the new query instance
     * @throws IllegalArgumentException if a query has not been
     *         defined, or if the query string is found to be
     *         invalid, or if the query result is found to not be
     *         assignable to the specified type
     * @see EntityManagerFactory#getNamedQueries(Class)
     * @see NamedQuery
     * @see NamedNativeQuery
     */
    <T> TypedQuery<T> createQuery(TypedQueryReference<T> reference);

    /**
     * Create an instance of {@link Query} for executing a native
     * SQL statement, e.g., for update or delete.
     *
     * <p>If the query is not an update or delete query, query
     * execution will result in each row of the SQL result being
     * returned as a result of type {@code Object[]} (or a result
     * of type {@code Object} if there is only one column in the
     * select list.) Column values are returned in the order of
     * their occurrence in the select list and default JDBC type
     * mappings are applied.
     * @param sqlString a native SQL query string
     * @return the new query instance
     */
    Query createNativeQuery(String sqlString);

    /**
     * Create an instance of {@link Query} for executing a native
     * SQL query.
     *
     * <p><em>In the next release of this API, the return type of this
     * method will change to {@code TypedQuery<T>}.</em>
     * @param sqlString a native SQL query string
     * @param resultClass the type of the query result
     * @return the new query instance
     */
    <T> Query createNativeQuery(String sqlString, Class<T> resultClass);

    /**
     * Create an instance of {@link 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
     */
    Query createNativeQuery(String sqlString, String resultSetMapping);

    /**
     * Create an instance of {@link StoredProcedureQuery} for executing
     * a stored procedure in the database.
     * <p>Parameters must be registered before the stored procedure can
     * be executed.
     * <p>If the stored procedure returns one or more result sets, any
     * result set is returned as a list of type {@code Object[]}.
     * @param name name assigned to the stored procedure query in
     *        metadata
     * @return the new stored procedure query instance
     * @throws IllegalArgumentException if no query has been defined
     *         with the given name
     * @since 2.1
     */
    StoredProcedureQuery createNamedStoredProcedureQuery(String name);

    /**
     * Create an instance of {@link StoredProcedureQuery} for executing a
     * stored procedure in the database.
     * <p>Parameters must be registered before the stored procedure can
     * be executed.
     * <p>If the stored procedure returns one or more result sets, any
     * result set is returned as a list of type {@code Object[]}.
     * @param procedureName name of the stored procedure in the database
     * @return the new stored procedure query instance
     * @throws IllegalArgumentException if a stored procedure of the
     *         given name does not exist (or if query execution will
     *         fail)
     * @since 2.1
     */
    StoredProcedureQuery createStoredProcedureQuery(String procedureName);

    /**
     * Create an instance of {@link StoredProcedureQuery} for executing
     * a stored procedure in the database.
     * <p>Parameters must be registered before the stored procedure can
     * be executed.
     * <p>The {@code resultClass} arguments must be specified in the
     * order in which the result sets is returned by the stored procedure
     * invocation.
     * @param procedureName name of the stored procedure in the database
     * @param resultClasses classes to which the result sets
     *        produced by the stored procedure are to be mapped
     * @return the new stored procedure query instance
     * @throws IllegalArgumentException if a stored procedure of the
     *         given name does not exist (or if query execution will
     *         fail)
     * @since 2.1
     */
    StoredProcedureQuery createStoredProcedureQuery(
            String procedureName, Class<?>... resultClasses);

    /**
     * Create an instance of {@link StoredProcedureQuery} for executing
     * a stored procedure in the database.
     * <p>Parameters must be registered before the stored procedure can
     * be executed.
     * <p>The {@code resultSetMapping} arguments must be specified in
     * the order in which the result sets is returned by the stored
     * procedure invocation.
     * @param procedureName name of the stored procedure in the
     *        database
     * @param resultSetMappings the names of the result set mappings
     *        to be used in mapping result sets
     *        returned by the stored procedure
     * @return the new stored procedure query instance
     * @throws IllegalArgumentException if a stored procedure or
     *         result set mapping of the given name does not exist
     *         (or the query execution will fail)
     */
    StoredProcedureQuery createStoredProcedureQuery(
            String procedureName, String... resultSetMappings);

    /**
     * Indicate to the entity manager that a JTA transaction is
     * active and join the persistence context to it. 
     * <p>This method should be called on a JTA application 
     * managed entity manager that was created outside the scope
     * of the active transaction or on an entity manager of type
     * {@link SynchronizationType#UNSYNCHRONIZED} to associate
     * it with the current JTA transaction.
     * @throws TransactionRequiredException if there is no active
     *         transaction
     */
    void joinTransaction();

    /**
     * Determine whether the entity manager is joined to the
     * current transaction. Returns false if the entity manager
     * is not joined to the current transaction or if no
     * transaction is active.
     * @return boolean
     * @since 2.1
     */
    boolean isJoinedToTransaction();

    /**
     * Return an object of the specified type to allow access to
     * a provider-specific API. If the provider implementation
     * of {@code EntityManager} does not support the given type,
     * the {@link PersistenceException} is thrown.
     * @param cls  the class of the object to be returned.
     *             This is usually either the underlying class
     *             implementing {@code EntityManager} or an
     *             interface it implements.
     * @return an instance of the specified class
     * @throws PersistenceException if the provider does not 
     *         support the given type
     * @since 2.0
     */
    <T> T unwrap(Class<T> cls);

    /**
     * Return the underlying provider object for the
     * {@link EntityManager}, if available. The result of this
     * method is implementation-specific.
     * <p>The {@code unwrap} method is to be preferred for new
     * applications.
     * @return the underlying provider object
     */
    Object getDelegate();

    /**
     * Close an application-managed entity manager.
     * <p>After invocation of {@code close()}, every method of
     * the {@code EntityManager} instance and of any instance
     * of {@link Query}, {@link TypedQuery}, or
     * {@link StoredProcedureQuery} obtained from it throws
     * the {@link IllegalStateException}, except for
     * {@link #getProperties()}, {@link #getTransaction()},
     * and {@link #isOpen()} (which returns false).
     * <p>If this method is called when the entity manager is
     * joined to an active transaction, the persistence context
     * remains managed until the transaction completes.
     * @throws IllegalStateException if the entity manager is
     *         container-managed
     */
    void close();

    /**
     * Determine whether the entity manager is open. 
     * @return true until the entity manager has been closed
     */
    boolean isOpen();

    /**
     * Return the resource-level {@link EntityTransaction} object.
     * The {@code EntityTransaction} instance may be used serially
     * to begin and commit multiple transactions.
     * @return EntityTransaction instance
     * @throws IllegalStateException if invoked on a JTA entity
     *         manager
     */
    EntityTransaction getTransaction();

    /**
     * The {@linkplain EntityManagerFactory entity manager factory}
     * which created this entity manager.
     * @return the {@link EntityManagerFactory}
     * @throws IllegalStateException if the entity manager has 
     *         been closed
     * @since 2.0
     */
    EntityManagerFactory getEntityManagerFactory();

    /**
     * Obtain an instance of {@link CriteriaBuilder} which may be
     * used to construct {@link CriteriaQuery} objects.
     * @return an instance of {@link CriteriaBuilder}
     * @throws IllegalStateException if the entity manager has
     *         been closed
     * @see EntityManagerFactory#getCriteriaBuilder()
     * @since 2.0
     */
    CriteriaBuilder getCriteriaBuilder();

    /**
     * Obtain an instance of the {@link Metamodel} interface which
     * provides access to metamodel objects describing the managed
     * types belonging to the persistence unit.
     * @return an instance of {@link Metamodel}
     * @throws IllegalStateException if the entity manager has
     *         been closed
     * @since 2.0
     */
    Metamodel getMetamodel();

    /**
     * Create a new mutable {@link EntityGraph}, allowing dynamic
     * definition of an entity graph.
     * @param rootType class of entity graph
     * @return entity graph
     * @since 2.1
     */
    <T> EntityGraph<T> createEntityGraph(Class<T> rootType);

    /**
     * Obtain a mutable copy of a named {@link EntityGraph}, or
     * return null if there is no entity graph with the given
     * name.
     * @param graphName name of an entity graph
     * @return entity graph
     * @since 2.1
     */
    EntityGraph<?> createEntityGraph(String graphName);

    /**
     * Obtain a named {@link EntityGraph}. The returned instance
     * of {@code EntityGraph} should be considered immutable.
     * @param graphName  name of an existing entity graph
     * @return named entity graph
     * @throws IllegalArgumentException if there is no entity
     *         of graph with the given name
     * @since 2.1
     */
    EntityGraph<?> getEntityGraph(String graphName);

    /**
     * Return all named {@link EntityGraph}s that are defined for
     * the given entity class type.
     * @param entityClass  entity class
     * @return list of all entity graphs defined for the entity
     * @throws IllegalArgumentException if the class is not an entity
     * @since 2.1
     */
    <T> List<EntityGraph<? super T>> getEntityGraphs(Class<T> entityClass);

    /**
     * Execute the given action using the database connection underlying this
     * {@code EntityManager}. Usually, the connection is a JDBC connection, but a
     * provider might support some other native connection type, and is not required
     * to support {@code java.sql.Connection}. If this {@code EntityManager} is
     * associated with a transaction, the action is executed in the context of the
     * transaction. The given action should close any resources it creates, but should
     * not close the connection itself, nor commit or roll back the transaction. If
     * the given action throws an exception, the persistence provider must mark the
     * transaction for rollback.
     * @param action the action
     * @param <C> the connection type, usually {@code java.sql.Connection}
     * @throws PersistenceException wrapping the checked {@link Exception} thrown by
     *         {@link ConnectionConsumer#accept}, if any
     * @since 3.2
     */
    <C> void runWithConnection(ConnectionConsumer<C> action);

    /**
     * Call the given function and return its result using the database connection
     * underlying this {@code EntityManager}. Usually, the connection is a JDBC
     * connection, but a provider might support some other native connection type,
     * and is not required to support {@code java.sql.Connection}. If this
     * {@code EntityManager} is associated with a transaction, the function is
     * executed in the context of the transaction. The given function should close
     * any resources it creates, but should not close the connection itself, nor
     * commit or roll back the transaction. If the given action throws an exception,
     * the persistence provider must mark the transaction for rollback.
     * @param function the function
     * @param <C> the connection type, usually {@code java.sql.Connection}
     * @param <T> the type of result returned by the function
     * @return the value returned by {@link ConnectionFunction#apply}.
     * @throws PersistenceException wrapping the checked {@link Exception} thrown by
     *         {@link ConnectionFunction#apply}, if any
     * @since 3.2
     */
    <C,T> T callWithConnection(ConnectionFunction<C, T> function);

}
package jakarta.persistence;

/**
 * Interface used to control transactions on resource-local entity
 * managers. The {@link EntityManager#getTransaction} method returns
 * the {@code EntityTransaction} interface.
 *
 * @since 1.0
 */
public interface EntityTransaction {

     /**
      * Start a resource transaction. 
      * @throws IllegalStateException if {@link #isActive()} is true
      */
     void begin();

     /**
      * Commit the current resource transaction, writing any unflushed
      * changes to the database.
      * @throws IllegalStateException if {@link #isActive()} is false
      * @throws RollbackException if the commit fails
      */
     void commit();

     /**
      * Roll back the current resource transaction. 
      * @throws IllegalStateException if {@link #isActive()} is false
      * @throws PersistenceException if an unexpected error 
      *         condition is encountered
      */
     void rollback();

     /**
      * Mark the current resource transaction so that the only possible
      * outcome of the transaction is for the transaction
      * to be rolled back. 
      * @throws IllegalStateException if {@link #isActive()} is false
      */
     void setRollbackOnly();

     /**
      * Determine whether the current resource transaction has been 
      * marked for rollback.
      * @return boolean indicating whether the transaction has been
      *         marked for rollback
      * @throws IllegalStateException if {@link #isActive()} is false
      */
     boolean getRollbackOnly();

     /**
      * Indicate whether a resource transaction is in progress.
      * @return boolean indicating whether transaction is in progress
      * @throws PersistenceException if an unexpected error 
      *         condition is encountered
      */
     boolean isActive();

     /**
      * Set the transaction timeout, in seconds. This is a hint.
      * @param timeout the timeout, in seconds, or null to indicate
      *                that the database server should set the timeout
      * @since 3.2
      */
     void setTimeout(Integer timeout);

     /**
      * The transaction timeout.
      * @since 3.2
      */
     Integer getTimeout();
}
package jakarta.persistence;

import java.util.Map;
import java.util.function.Consumer;
import java.util.function.Function;

import jakarta.persistence.metamodel.Metamodel;
import jakarta.persistence.criteria.CriteriaBuilder;

/**
 * Interface used to interact with the persistence unit, and to
 * create new instances of {@link EntityManager}.
 *
 * 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. If two entity
 * types participate in an association, then they must belong to
 * the same persistence unit.
 *
 * A persistence unit may be defined by a {@code persistence.xml}
 * file, or it may be defined at runtime via the
 * {@link PersistenceConfiguration} API.
 *
 * Every persistence unit has a transaction type,
 * either {@link PersistenceUnitTransactionType#JTA JTA}, or
 * {@link PersistenceUnitTransactionType#RESOURCE_LOCAL RESOURCE_LOCAL}.
 * Resource-local transactions are managed programmatically via the
 * {@link EntityTransaction} interface.
 *
 * An {@link EntityManagerFactory} with a lifecycle managed by
 * the application may be created using the static operations of
 * the {@link Persistence} class:
 * <ul>
 * <li>if the persistence unit is defined in {@code persistence.xml},
 * an entity manager factory may be created by calling
 * {@link Persistence#createEntityManagerFactory(String)} or
 * {@link Persistence#createEntityManagerFactory(String,Map)},
 * or
 * <li>if the persistence unit was defined using
 * {@link PersistenceConfiguration}, an entity manager factory
 * may be created by calling
 * {@link Persistence#createEntityManagerFactory(PersistenceConfiguration)}.
 * </ul>
 *
 * Usually, there is exactly one {@code EntityManagerFactory} for
 * each persistence unit:
 * {@snippet :
 * // create a factory at initialization time
 * static final EntityManagerFactory entityManagerFactory =
 * Persistence.createEntityManagerFactory("orderMgt");
 * }
 *
 * Alternatively, in the Jakarta EE environment, a
 * container-managed {@code EntityManagerFactory} may be obtained
 * by dependency injection, using {@link PersistenceUnit}.
 * {@snippet :
 * // inject the container-managed factory
 * @PersistenceUnit(unitName="orderMgt")
 * EntityManagerFactory entityManagerFactory;
 * }
 *
 * An application-managed {@code EntityManager} may be created
 * via a call to {@link #createEntityManager()}. However, this
 * approach places complete responsibility for cleanup and exception
 * management on the client, and is thus considered error-prone. It
 * is much safer to use the methods {@link #runInTransaction} and
 * {@link #callInTransaction} to obtain {@code EntityManager}s.
 * Alternatively, in the Jakarta EE environment, a container-managed
 * {@link EntityManager} may be obtained by dependency injection,
 * using {@link PersistenceContext}, and the application need not
 * interact with the {@code EntityManagerFactory} directly.
 *
 * The {@code EntityManagerFactory} provides access to certain
 * other useful APIs:
 * <ul>
 * <li>an instance of {@link Metamodel} exposing a model of the
 * managed types associated with the persistence unit may be
 * obtained by calling {@link #getMetamodel()},
 * <li>an instance of {@link SchemaManager}, allowing programmatic
 * control over schema generation and validation, may be
 * obtained by calling {@link #getSchemaManager()},
 * <li>an instance of {@link Cache}, allowing direct programmatic
 * control over the second-level cache, may be obtained by
 * calling {@link #getCache()},
 * <li>the {@link CriteriaBuilder}, used to define criteria queries,
 * may be obtained by calling {@link #getCriteriaBuilder()},
 * and
 * <li>the {@link PersistenceUnitUtil} may be obtained by calling
 * {@link #getPersistenceUnitUtil()}.
 * </ul>
 *
 * When the application has finished using the entity manager
 * factory, or when the application terminates, the application
 * should {@linkplain #close} the entity manager factory. If
 * necessary, a {@link java.lang.ref.Cleaner} may be used:
 * {@snippet :
 * // factory should be destroyed before program terminates
 * Cleaner.create().register(entityManagerFactory, entityManagerFactory::close);
 * }
 * Once an {@code EntityManagerFactory} has been closed, all its
 * entity managers are considered to be in the closed state.
 *
 * @see EntityManager
 *
 * @since 1.0
 */
public interface EntityManagerFactory extends AutoCloseable {

    /**
     * Create a new application-managed {@link EntityManager}. This
     * method returns a new {@code EntityManager} instance each time
     * it is invoked. 
     * <p>The {@link EntityManager#isOpen} method will return true
     * on the returned instance.
     * @return entity manager instance
     * @throws IllegalStateException if the entity manager factory
     * has been closed
     */
    EntityManager createEntityManager();

    /**
     * Create a new application-managed {@link EntityManager} with
     * the given {@link Map} specifying property settings. This
     * method returns a new {@code EntityManager} instance each time
     * it is invoked.
     * <p>The {@link EntityManager#isOpen} method will return true
     * on the returned instance.
     * @param map properties for entity manager
     * @return entity manager instance
     * @throws IllegalStateException if the entity manager factory
     * has been closed
     */
    EntityManager createEntityManager(Map<?, ?> map);

    /**
     * Create a new JTA application-managed {@link EntityManager} with
     * the specified synchronization type. This method returns a new
     * {@code EntityManager} instance each time it is invoked.
     * <p>The {@link EntityManager#isOpen} method will return true on
     * the returned instance.
     * @param synchronizationType  how and when the entity manager should
     *                             be synchronized with the current JTA
     *                             transaction
     * @return entity manager instance
     * @throws IllegalStateException if the entity manager factory has
     * been configured for resource-local entity managers or is closed
     *
     * @since 2.1
     */
    EntityManager createEntityManager(SynchronizationType synchronizationType);

    /**
     * Create a new JTA application-managed {@link EntityManager} with
     * the specified synchronization type and map of properties. This
     * method returns a new {@code EntityManager} instance each time it
     * is invoked.
     * <p>The {@link EntityManager#isOpen} method will return true on the
     * returned instance.
     * @param synchronizationType  how and when the entity manager should
     *                             be synchronized with the current JTA
     *                             transaction
     * @param map properties for entity manager
     * @return entity manager instance
     * @throws IllegalStateException if the entity manager factory has
     * been configured for resource-local entity managers or is closed
     *
     * @since 2.1
     */
    EntityManager createEntityManager(SynchronizationType synchronizationType, Map<?, ?> map);

    /**
     * Return an instance of {@link CriteriaBuilder} which may be used
     * to construct {@link jakarta.persistence.criteria.CriteriaQuery}
     * objects.
     * @return an instance of {@link CriteriaBuilder}
     * @throws IllegalStateException if the entity manager factory has
     * been closed
     *
     * @see EntityManager#getCriteriaBuilder()
     *
     * @since 2.0
     */
    CriteriaBuilder getCriteriaBuilder();

    /**
     * Return an instance of the {@link Metamodel} interface for access
     * to the metamodel of the persistence unit.
     * @return an instance of {@link Metamodel}
     * @throws IllegalStateException if the entity manager factory
     * has been closed
     *
     * @since 2.0
     */
    Metamodel getMetamodel();

    /**
     * Indicates whether the factory is open. Returns true until the
     * factory has been closed.
     * @return boolean indicating whether the factory is open
     */
    boolean isOpen();

    /**
     * Close the factory, releasing any resources that it holds.
     * After a factory instance has been closed, all methods invoked
     * on it will throw the {@link IllegalStateException}, except
     * for {@link #isOpen}, which will return false. Once an
     * {@code EntityManagerFactory} has been closed, all its
     * entity managers are considered to be in the closed state.
     * @throws IllegalStateException if the entity manager factory
     * has been closed
     */
    void close();

    /**
     * The name of the persistence unit.
     *
     * @since 3.2
     */
    String getName();

    /**
     * Get the properties and associated values that are in effect
     * for the entity manager factory. Changing the contents of the
     * map does not change the configuration in effect.
     * @return properties
     * @throws IllegalStateException if the entity manager factory 
     * has been closed
     *
     * @since 2.0
     */
    Map<String, Object> getProperties();

    /**
     * Access the cache that is associated with the entity manager 
     * factory (the "second level cache").
     * @return an instance of {@link Cache}, or null if there is no
     * second-level cache in use
     * @throws IllegalStateException if the entity manager factory
     * has been closed
     *
     * @since 2.0
     */
    Cache getCache();

    /**
     * Return interface providing access to utility methods for the
     * persistence unit.
     * @return an instance of {@link PersistenceUnitUtil}
     * @throws IllegalStateException if the entity manager factory
     * has been closed
     *
     * @since 2.0
     */
    PersistenceUnitUtil getPersistenceUnitUtil();

    /**
     * The type of transaction management used by this persistence
     * unit, either resource-local transaction management, or JTA.
     *
     * @since 3.2
     */
    PersistenceUnitTransactionType getTransactionType();

    /**
     * Return interface providing access to schema management
     * operations for the persistence unit.
     * @return an instance of {@link SchemaManager}
     * @throws IllegalStateException if the entity manager factory
     * has been closed
     *
     * @since 3.2
     */
    SchemaManager getSchemaManager();

    /**
     * Define the query, typed query, or stored procedure query as
     * a named query such that future query objects can be created
     * from it using the {@link EntityManager#createNamedQuery} or
     * {@link EntityManager#createNamedStoredProcedureQuery} methods.
     * <p>Any configuration of the query object (except for actual
     * parameter binding) in effect when the named query is added
     * is retained as part of the named query definition. This
     * includes configuration information such as max results, hints,
     * flush mode, lock mode, result set mapping information, and
     * information about stored procedure parameters.
     * <p>When the query is executed, information that can be set by
     * means of the query APIs can be overridden. Information that is
     * overridden does not affect the named query as registered with
     * the entity manager factory, and thus does not affect subsequent
     * query objects created from it by calling {@code createNamedQuery}
     * or {@code createNamedStoredProcedureQuery}.
     * <p>If a named query of the same name has been previously defined,
     * either statically via metadata or via this method, that query
     * definition is replaced.
     *
     * @param name name for the query
     * @param query a {@link Query}, {@link TypedQuery},
     *             or {@link StoredProcedureQuery}
     *
     * @since 2.1
     */
    void addNamedQuery(String name, Query query);

    /**
     * Return an object of the specified type to allow access to
     * a provider-specific API. If the provider implementation of
     * {@code EntityManagerFactory} does not support the given
     * type, the {@link PersistenceException} is thrown.
     * @param cls the class of the object to be returned.
     *            This is usually either the underlying class
     *            implementing {@code EntityManagerFactory} or an
     *            interface it implements.
     * @return an instance of the specified class
     * @throws PersistenceException if the provider does not support
     *        the given type
     * @since 2.1
     */
    <T> T unwrap(Class<T> cls);

    /**
     * Add a named copy of the given {@link EntityGraph} to this
     * {@code EntityManagerFactory}. If an entity graph with the
     * given name already exists, it is replaced.
     * @param graphName  name for the entity graph
     * @param entityGraph  entity graph
     * @since 2.1
     */
    <T> void addNamedEntityGraph(String graphName, EntityGraph<T> entityGraph);

    /**
     * A map keyed by {@linkplain NamedQuery#name query name}, containing
     * {@linkplain TypedQueryReference references} to every named query whose
     * result type is assignable to the given Java type.
     * @param resultType any Java type, including {@code Object.class}
     *                   meaning all queries
     * @return a map keyed by query name
     * @param <R> the specified upper bound on the query result types
     *
     * @since 3.2
     */
    <R> Map<String, TypedQueryReference<R>> getNamedQueries(Class<R> resultType);

    /**
     * A map keyed by {@linkplain NamedEntityGraph#name graph name}, containing
     * every named {@linkplain EntityGraph entity graph} whose entity type is
     * assignable to the given Java type.
     * @param entityType any Java type, including {@code Object.class}
     *                   meaning all entity graphs
     * @return a map keyed by graph name
     * @param <E> the specified upper bound on the entity graph types
     *
     * @since 3.2
     */
    <E> Map<String, EntityGraph<? extends E>> getNamedEntityGraphs(Class<E> entityType);

    /**
     * Create a new application-managed {@link EntityManager} with an active
     * transaction, and execute the given function, passing the {@code EntityManager}
     * to the function.
     * <p>
     * If the transaction type of the persistence unit is JTA, and there is a JTA
     * transaction already associated with the caller, then the {@code EntityManager}
     * is associated with this current transaction. If the given function throws an
     * exception, the JTA transaction is marked for rollback, and the exception is
     * rethrown.
     * <p>
     * Otherwise, if the transaction type of the persistence unit is resource-local,
     * or if there is no JTA transaction already associated with the caller, then
     * the {@code EntityManager} is associated with a new transaction. If the given
     * function returns without throwing an exception, this transaction is committed.
     * If the function does throw an exception, the transaction is rolled back, and
     * the exception is rethrown.
     * <p>
     * Finally, the {@code EntityManager} is closed before this method returns
     * control to the client.
     *
     * @param work a function to be executed in the scope of the transaction
     *
     * @since 3.2
     */
    void runInTransaction(Consumer<EntityManager> work);
    /**
     * Create a new application-managed {@link EntityManager} with an active
     * transaction, and call the given function, passing the {@code EntityManager}
     * to the function.
     * <p>
     * If the transaction type of the persistence unit is JTA, and there is a JTA
     * transaction already associated with the caller, then the {@code EntityManager}
     * is associated with this current transaction. If the given function returns
     * without throwing an exception, the result of the function is returned. If the
     * given function throws an exception, the JTA transaction is marked for rollback,
     * and the exception is rethrown.
     * <p>
     * Otherwise, if the transaction type of the persistence unit is resource-local,
     * or if there is no JTA transaction already associated with the caller, then
     * the {@code EntityManager} is associated with a new transaction. If the given
     * function returns without throwing an exception, this transaction is committed
     * and the result of the function is returned. If the function does throw an
     * exception, the transaction is rolled back, and the exception is rethrown.
    * <p>
     * Finally, the {@code EntityManager} is closed before this method returns
     * control to the client.
     *
     * @param work a function to be called in the scope of the transaction
     * @return the value returned by the given function
     *
     * @since 3.2
     */
    <R> R callInTransaction(Function<EntityManager, R> work);
}
/**
 * Enumerates the kinds of optimistic or pessimistic lock which
 * may be obtained on an entity instance.
 *
 * <p> A specific lock mode may be requested by passing an explicit
 * {@code LockModeType} as an argument to:
 * <ul>
 * <li>one of the methods of {@link EntityManager} which obtains
 *     locks ({@link EntityManager#lock lock()},
 *     {@link EntityManager#find find()}, or
 *     {@link EntityManager#refresh refresh()}), or
 * <li>to {@link Query#setLockMode(LockModeType)} or
 *     {@link TypedQuery#setLockMode(LockModeType)}.
 * </ul>
 * 
 * <p> Optimistic locks are specified using
 * {@link LockModeType#OPTIMISTIC LockModeType.OPTIMISTIC} and
 * {@link LockModeType#OPTIMISTIC_FORCE_INCREMENT}. The lock mode
 * types {@link LockModeType#READ} and {@link LockModeType#WRITE} are
 * synonyms for {@code OPTIMISTIC} and {@code OPTIMISTIC_FORCE_INCREMENT}
 * respectively. The latter are preferred for new applications.
 *
 * <p> The semantics of requesting locks of type
 * {@code LockModeType.OPTIMISTIC} and
 * {@code LockModeType.OPTIMISTIC_FORCE_INCREMENT} are the
 * following.
 *
 * <p> If transaction T1 calls for a lock of type 
 * {@code LockModeType.OPTIMISTIC} on a versioned object, 
 * the entity manager must ensure that neither of the following 
 * phenomena can occur:
 * <ul>
 *   <li> P1 (Dirty read): Transaction T1 modifies a row. 
 * Another transaction T2 then reads that row and obtains the
 * modified value, before T1 has committed or rolled back.
 * Transaction T2 eventually commits successfully; it does not 
 * matter whether T1 commits or rolls back and whether it does 
 * so before or after T2 commits.
 *   </li>
 *   <li> P2 (Non-repeatable read): Transaction T1 reads a row. 
 * Another transaction T2 then modifies or deletes that row, 
 * before T1 has committed. Both transactions eventually commit 
 * successfully.
 *   </li>
 * </ul>
 *
 * <p> Lock modes must always prevent the phenomena P1 and P2.
 *
 * <p> In addition, obtaining a lock of type
 * {@code LockModeType.OPTIMISTIC_FORCE_INCREMENT} on a versioned
 * object, will also force an update (increment) to the entity's
 * version column.
 *
 * <p> The persistence implementation is not required to support
 * the use of optimistic lock modes on non-versioned objects. When
 * it cannot support such a lock request, it must throw the {@link
 * PersistenceException}.
 *
 * <p>The lock modes {@link LockModeType#PESSIMISTIC_READ},
 * {@link LockModeType#PESSIMISTIC_WRITE}, and
 * {@link LockModeType#PESSIMISTIC_FORCE_INCREMENT} are used to
 * immediately obtain long-term database locks.
 *
 * <p> The semantics of requesting locks of type
 * {@code LockModeType.PESSIMISTIC_READ},
 * {@code LockModeType.PESSIMISTIC_WRITE}, and
 * {@code LockModeType.PESSIMISTIC_FORCE_INCREMENT} are the
 * following.
 *
 * <p> If transaction T1 calls for a lock of type
 * {@code LockModeType.PESSIMISTIC_READ} or
 * {@code LockModeType.PESSIMISTIC_WRITE} on an object, the entity
 * manager must ensure that neither of the following phenomena can
 * occur: 
 * <ul> 
 * <li> P1 (Dirty read): Transaction T1 modifies a
 * row. Another transaction T2 then reads that row and obtains the
 * modified value, before T1 has committed or rolled back.
 *
 * <li> P2 (Non-repeatable read): Transaction T1 reads a row.
 * Another transaction T2 then modifies or deletes that row, before
 * T1 has committed or rolled back.
 * </ul>
 *
 * <p> A lock with {@code LockModeType.PESSIMISTIC_WRITE} can be
 * obtained on an entity instance to force serialization among
 * transactions attempting to update the entity data. A lock with
 * {@code LockModeType.PESSIMISTIC_READ} can be used to query data
 * using repeatable-read semantics without the need to reread the
 * data at the end of the transaction to obtain a lock, and without
 * blocking other transactions reading the data. A lock with
 * {@code LockModeType.PESSIMISTIC_WRITE} can be used when querying
 * data and there is a high likelihood of deadlock or update failure
 * among concurrent updating transactions.
 * 
 * <p> The persistence implementation must support the use of locks
 * of type {@code LockModeType.PESSIMISTIC_READ} and
 * {@code LockModeType.PESSIMISTIC_WRITE} with non-versioned entities
 * as well as with versioned entities.
 *
 * <p> When the lock cannot be obtained, and the database locking
 * failure results in transaction-level rollback, the provider must
 * throw the {@link PessimisticLockException} and ensure that the
 * JTA transaction or {@code EntityTransaction} has been marked for
 * rollback.
 * 
 * <p> When the lock cannot be obtained, and the database locking
 * failure results in only statement-level rollback, the provider
 * must throw the {@link LockTimeoutException} (and must not mark
 * the transaction for rollback).
 *
 * @since 1.0
 *
 */
public enum LockModeType implements FindOption, RefreshOption {
    /**
     * Synonymous with {@link #OPTIMISTIC}.
     * <p>
     * {@code OPTIMISTIC} is preferred for new applications.
     *
     */
    READ,

    /**
     * Synonymous with {@link #OPTIMISTIC_FORCE_INCREMENT}.
     * <p>
     * {@code OPTIMISTIC_FORCE_INCREMENT} is preferred for
     * new applications.
     *
     */
    WRITE,

    /**
     * Optimistic lock.
     *
     * @since 2.0
     */
    OPTIMISTIC,

    /**
     * Optimistic lock, with version update.
     *
     * @since 2.0
     */
    OPTIMISTIC_FORCE_INCREMENT,

    /**
     *
     * Pessimistic read lock.
     *
     * @since 2.0
     */
    PESSIMISTIC_READ,

    /**
     * Pessimistic write lock.
     *
     * @since 2.0
     */
    PESSIMISTIC_WRITE,

    /**
     * Pessimistic write lock, with version update.
     *
     * @since 2.0
     */
    PESSIMISTIC_FORCE_INCREMENT,

    /**
     * No lock.
     *
     * @since 2.0
     */
    NONE
}
/**
 * Interface used to interact with the second-level cache.
 * If no second-level cache is in use, the methods of this
 * interface have no effect, except for {@link #contains},
 * which returns false.
 *
 * @since 2.0
 */
public interface Cache {

    /**
     * Whether the cache contains data for the given entity.
     * @param cls  entity class 
     * @param primaryKey  primary key
     * @return boolean indicating whether the entity is in the cache
     */
    boolean contains(Class<?> cls, Object primaryKey);

    /**
     * Remove the data for the given entity from the cache.
     * @param cls  entity class
     * @param primaryKey  primary key
     */
    void evict(Class<?> cls, Object primaryKey);

    /**
     * Remove the data for entities of the specified class
     * (and its subclasses) from the cache.
     * @param cls  entity class
     */
    void evict(Class<?> cls);

    /**
     * Clear the cache.
     */
    void evictAll();

    /**
     * Return an object of the specified type to allow access to
     * the provider-specific API. If the provider's implementation
     * of the {@code Cache} interface does not support the specified
     * class, the {@link PersistenceException} is thrown.
     * @param cls  the class of the object to be returned.
     *             This is usually either the underlying class
     *             implementing {@code Cache}, or an interface it
     *             implements.
     * @return an instance of the specified type
     * @throws PersistenceException if the provider does not support
     *         the given type
     * @since 2.1
     */
    <T> T unwrap(Class<T> cls);
}
package jakarta.persistence;

import java.util.Calendar;
import java.util.Date;
import java.util.List;
import java.util.Set;
import java.util.Map;
import java.util.stream.Stream;

/**
 * Interface used to control query execution.
 *
 * @see TypedQuery
 * @see StoredProcedureQuery
 * @see Parameter
 *
 * @since 1.0
 */
public interface Query {

    /**
     * Execute a SELECT query and return the query results as an untyped
     * {@link List}.
     * @return a list of the results, or an empty list if there are
     *         no results
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language UPDATE or DELETE statement
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws TransactionRequiredException if a lock mode other than
     *         {@code NONE} has been set and there is no transaction
     *         or the persistence context has not been joined to the
     *         transaction
     * @throws PessimisticLockException if pessimistic locking
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking
     *         fails and only the statement is rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    @SuppressWarnings({"rawtypes"})
    List getResultList();

    /**
     * Execute a SELECT query and return the query results as an untyped
     * {@link java.util.stream.Stream}.
     *
     * <p>By default, this method delegates to {@code getResultList().stream()},
     * however persistence provider may choose to override this method
     * to provide additional capabilities.
     *
     * @return a stream of the results, or an empty stream if there
     *         are no results
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language UPDATE or DELETE statement
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws TransactionRequiredException if a lock mode other than
     *         {@code NONE} has been set and there is no transaction
     *         or the persistence context has not been joined to the
     *         transaction
     * @throws PessimisticLockException if pessimistic locking
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking
     *         fails and only the statement is rolled back
     * @throws PersistenceException if the query execution exceeds
     *         the query timeout value set and the transaction
     *         is rolled back
     * @see Stream
     * @see #getResultList()
     * @since 2.2
     */
    @SuppressWarnings({"rawtypes"})
    default Stream getResultStream() {
        return getResultList().stream();
    }

    /**
     * Execute a SELECT query that returns a single untyped result.
     * @return the result
     * @throws NoResultException if there is no result
     * @throws NonUniqueResultException if more than one result
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language UPDATE or DELETE statement
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws TransactionRequiredException if a lock mode other than
     *         {@code NONE} has been set and there is no transaction
     *         or the persistence context has not been joined to the
     *         transaction
     * @throws PessimisticLockException if pessimistic locking
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking
     *         fails and only the statement is rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    Object getSingleResult();

    /**
     * Execute a SELECT query that returns a single untyped result.
     * @return the result, or null if there is no result
     * @throws NonUniqueResultException if more than one result
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language UPDATE or DELETE statement
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws TransactionRequiredException if a lock mode other than
     *         {@code NONE} has been set and there is no transaction
     *         or the persistence context has not been joined to the
     *         transaction
     * @throws PessimisticLockException if pessimistic locking
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking
     *         fails and only the statement is rolled back
     * @throws PersistenceException if the query execution exceeds
     *         the query timeout value set and the transaction
     *         is rolled back
     *
     * @since 3.2
     */
    Object getSingleResultOrNull();

    /**
     * Execute an update or delete statement.
     * @return the number of entities updated or deleted
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language SELECT statement or for
     *         a criteria query
     * @throws TransactionRequiredException if there is 
     *         no transaction or the persistence context has not
     *         been joined to the transaction
     * @throws QueryTimeoutException if the statement execution 
     *         exceeds the query timeout value set and only
     *         the statement is rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    int executeUpdate();

    /**
     * Set the maximum number of results to retrieve.
     * @param maxResult  maximum number of results to retrieve
     * @return the same query instance
     * @throws IllegalArgumentException if the argument is negative
     */
    Query setMaxResults(int maxResult);

    /**
     * The maximum number of results the query object was set to retrieve.
     * Returns {@link Integer#MAX_VALUE} if {@link #setMaxResults} was not
     * applied to the query object.
     * @return maximum number of results
     * @since 2.0
     */
    int getMaxResults();

    /**
     * Set the position of the first result to retrieve.
     * @param startPosition position of the first result, numbered from 0
     * @return the same query instance
     * @throws IllegalArgumentException if the argument is negative
     */
    Query setFirstResult(int startPosition);

    /**
     * The position of the first result the query object was set to
     * retrieve. Returns {@code 0} if {@code setFirstResult} was not
     * applied to the query object.
     * @return position of the first result
     * @since 2.0
     */
    int getFirstResult();

    /**
     * Set a query property or hint. The hints elements may be used 
     * to specify query properties and hints. Properties defined by
     * this specification must be observed by the provider. 
     * Vendor-specific hints that are not recognized by a provider
     * must be silently ignored. Portable applications should not
     * rely on the standard timeout hint. Depending on the database
     * in use and the locking mechanisms used by the provider,
     * this hint may or may not be observed.
     * @param hintName  name of the property or hint
     * @param value  value for the property or hint
     * @return the same query instance
     * @throws IllegalArgumentException if the second argument is not
     *         valid for the implementation
     */
    Query setHint(String hintName, Object value);

    /**
     * Get the properties and hints and associated values that are in
     * effect for the query instance.
     * @return query properties and hints
     * @since 2.0
     */
    Map<String, Object> getHints();

    /**
     * Bind the value of a {@code Parameter} object.
     * @param param  parameter object
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter
     *         does not correspond to a parameter of the
     *         query
     * @since 2.0
     */
    <T> Query setParameter(Parameter<T> param, T value);

    /**
     * Bind an instance of {@link java.util.Calendar} to a {@link Parameter} object.
     * @param param parameter object
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     * @since 2.0
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    Query setParameter(Parameter<Calendar> param, Calendar value, 
                       TemporalType temporalType);

    /**
     * Bind an instance of {@link java.util.Date} to a {@link Parameter} object.
     * @param param parameter object
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     * @since 2.0
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    Query setParameter(Parameter<Date> param, Date value, 
                       TemporalType temporalType);

    /**
     * Bind an argument value to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does 
     *         not correspond to a parameter of the query or if
     *         the argument is of incorrect type
     */
    Query setParameter(String name, Object value);

    /**
     * Bind an instance of {@link java.util.Calendar} to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does 
     *         not correspond to a parameter of the query or if
     *         the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    Query setParameter(String name, Calendar value, 
                       TemporalType temporalType);

    /**
     * Bind an instance of {@link java.util.Date} to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does 
     *         not correspond to a parameter of the query or if
     *         the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    Query setParameter(String name, Date value, 
                       TemporalType temporalType);

    /**
     * Bind an argument value to a positional parameter.
     * @param position  position
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
     *         correspond to a positional parameter of the
     *         query or if the argument is of incorrect type
     */
    Query setParameter(int position, Object value);

    /**
     * Bind an instance of {@link java.util.Calendar} to a positional
     * parameter.
     * @param position  position
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
     *         correspond to a positional parameter of the query or
     *         if the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    Query setParameter(int position, Calendar value,  
                       TemporalType temporalType);

    /**
     * Bind an instance of {@link java.util.Date} to a positional
     * parameter.
     * @param position  position
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
     *         correspond to a positional parameter of the query or
     *         if the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    Query setParameter(int position, Date value,  
                       TemporalType temporalType);

    /**
     * Get the parameter objects corresponding to the declared
     * parameters of the query.
     * Returns empty set if the query has no parameters.
     * This method is not required to be supported for native
     * queries.
     * @return set of the parameter objects
     * @throws IllegalStateException if invoked on a native
     *         query when the implementation does not support
     *         this use
     * @since 2.0
     */
    Set<Parameter<?>> getParameters();

    /**
     * Get the parameter object corresponding to the declared
     * parameter of the given name.
     * This method is not required to be supported for native
     * queries.
     * @param name  parameter name
     * @return parameter object
     * @throws IllegalArgumentException if the parameter of the
     *         specified name does not exist
     * @throws IllegalStateException if invoked on a native
     *         query when the implementation does not support
     *         this use
     * @since 2.0
     */
    Parameter<?> getParameter(String name);

    /**
     * Get the parameter object corresponding to the declared
     * parameter of the given name and type.
     * This method is required to be supported for criteria queries
     * only.
     * @param name  parameter name
     * @param type  type
     * @return parameter object
     * @throws IllegalArgumentException if the parameter of the
     *         specified name does not exist or is not assignable
     *         to the type
     * @throws IllegalStateException if invoked on a native
     *         query or Jakarta Persistence query language query when
     *         the implementation does not support this use
     * @since 2.0
     */
    <T> Parameter<T> getParameter(String name, Class<T> type);

    /**
     * Get the parameter object corresponding to the declared
     * positional parameter with the given position.
     * This method is not required to be supported for native
     * queries.
     * @param position  position
     * @return parameter object
     * @throws IllegalArgumentException if the parameter with the
     *         specified position does not exist
     * @throws IllegalStateException if invoked on a native
     *         query when the implementation does not support
     *         this use
     * @since 2.0
     */
    Parameter<?> getParameter(int position);

    /**
     * Get the parameter object corresponding to the declared
     * positional parameter with the given position and type.
     * This method is not required to be supported by the provider.
     * @param position  position
     * @param type  type
     * @return parameter object
     * @throws IllegalArgumentException if the parameter with the
     *         specified position does not exist or is not assignable
     *         to the type
     * @throws IllegalStateException if invoked on a native
     *         query or Jakarta Persistence query language query when
     *         the implementation does not support this use
     * @since 2.0
     */
    <T> Parameter<T> getParameter(int position, Class<T> type);

    /**
     * Return a boolean indicating whether a value has been bound 
     * to the parameter.
     * @param param parameter object
     * @return boolean indicating whether parameter has been bound
     * @since 2.0
     */
    boolean isBound(Parameter<?> param);

    /**
     * Return the input value bound to the parameter.
     * (Note that OUT parameters are unbound.)
     * @param param parameter object
     * @return parameter value
     * @throws IllegalArgumentException if the parameter is not 
     *         a parameter of the query
     * @throws IllegalStateException if the parameter has not
     *         been bound
     * @since 2.0
     */
    <T> T getParameterValue(Parameter<T> param);

    /**
     * Return the input value bound to the named parameter.
     * (Note that OUT parameters are unbound.)
     * @param name  parameter name
     * @return parameter value
     * @throws IllegalStateException if the parameter has not
     *         been bound
     * @throws IllegalArgumentException if the parameter of the
     *         specified name does not exist
     * @since 2.0
     */
    Object getParameterValue(String name);

    /**
     * Return the input value bound to the positional parameter.
     * (Note that OUT parameters are unbound.)
     * @param position  position
     * @return parameter value
     * @throws IllegalStateException if the parameter has not
     *          been bound
     * @throws IllegalArgumentException if the parameter with the
     *          specified position does not exist
     * @since 2.0
     */
    Object getParameterValue(int position);

    /**
     * Set the flush mode type to be used for the query execution.
     * The flush mode type applies to the query regardless of the
     * flush mode type in use for the entity manager.
     * @param flushMode  flush mode
     * @return the same query instance
     */
    Query setFlushMode(FlushModeType flushMode);

    /**
     * Get the flush mode in effect for the query execution. 
     * If a flush mode has not been set for the query object, 
     * returns the flush mode in effect for the entity manager.
     * @return flush mode
     * @since 2.0
     */
    FlushModeType getFlushMode();

    /**
     * Set the lock mode type to be used for the query execution.
     * @param lockMode  lock mode
     * @return the same query instance
     * @throws IllegalStateException if the query is found not to
     *         be a Jakarta Persistence query language SELECT query
     *         or a {@link jakarta.persistence.criteria.CriteriaQuery}
     *         query
     * @since 2.0
     */
    Query setLockMode(LockModeType lockMode);

    /**
     * Get the current lock mode for the query. Returns null if a
     * lock mode has not been set on the query object.
     * @return lock mode
     * @throws IllegalStateException if the query is found not to
     *          be a Jakarta Persistence query language SELECT query
     *          or a {@link jakarta.persistence.criteria.CriteriaQuery}
     *          query
     * @since 2.0
     */
    LockModeType getLockMode();

    /**
     * Set the cache retrieval mode that is in effect during query
     * execution. This cache retrieval mode overrides the cache
     * retrieve mode in use by the entity manager.
     * @param cacheRetrieveMode cache retrieval mode
     * @return the same query instance
     * @since 3.2
     */
    Query setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode);

    /**
     * Set the cache storage mode that is in effect during query
     * execution. This cache storage mode overrides the cache
     * storage mode in use by the entity manager.
     * @param cacheStoreMode cache storage mode
     * @return the same query instance
     * @since 3.2
     */
    Query setCacheStoreMode(CacheStoreMode cacheStoreMode);

    /**
     * The cache retrieval mode that will be in effect during query
     * execution.
     * @since 3.2
     */
    CacheRetrieveMode getCacheRetrieveMode();

    /**
     * The cache storage mode that will be in effect during query
     * execution.
     * @since 3.2
     */
    CacheStoreMode getCacheStoreMode();

    /**
     * Set the query timeout, in milliseconds. This is a hint,
     * and is an alternative to {@linkplain #setHint setting
     * the hint} {@code jakarta.persistence.query.timeout}.
     * @param timeout the timeout, in milliseconds, or null to
     *                indicate no timeout
     * @return the same query instance
     * @since 3.2
     */
    Query setTimeout(Integer timeout);

    /**
     * The query timeout.
     * @since 3.2
     */
    Integer getTimeout();

    /**
     * Return an object of the specified type to allow access to 
     * a provider-specific API. If the provider implementation of
     * {@code Query} does not support the given type, the
     * {@link PersistenceException} is thrown.
     * @param cls  the type of the object to be returned.
     *             This is usually either the underlying class
     *             implementing {@code Query} or an interface it
     *             implements.
     * @return an instance of the specified class
     * @throws PersistenceException if the provider does not support
     *         the given type
     * @since 2.0
     */
    <T> T unwrap(Class<T> cls);
}
package jakarta.persistence;

import java.util.List;
import java.util.Date;
import java.util.Calendar;
import java.util.stream.Stream;

/**
 * Interface used to control the execution of typed queries.
 *
 * @param <X> query result type
 *
 * @see Query
 * @see Parameter
 *
 * @since 2.0
 */
public interface TypedQuery<X> extends Query {

    /**
     * Execute a SELECT query and return the query results as a typed
     * {@link List List&lt;X&gt;}.
     * @return a list of the results, each of type {@link X}, or an
     *         empty list if there are no results
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language UPDATE or DELETE statement
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws TransactionRequiredException if a lock mode other than
     *         {@code NONE} has been set and there is no transaction
     *         or the persistence context has not been joined to the
     *         transaction
     * @throws PessimisticLockException if pessimistic locking
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking
     *         fails and only the statement is rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    List<X> getResultList();

    /**
     * Execute a SELECT query and return the query result as a typed
     * {@link java.util.stream.Stream Stream&lt;X&gt;}.
     *
     * <p>By default, this method delegates to {@link List#stream()
     * getResultList().stream()}, however, persistence provider may
     * choose to override this method to provide additional capabilities.
     *
     * @return a stream of the results, each of type {@link X}, or an
     *         empty stream if there are no results
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language UPDATE or DELETE statement
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws TransactionRequiredException if a lock mode other than
     *         {@code NONE} has been set and there is no transaction
     *         or the persistence context has not been joined to the
     *         transaction
     * @throws PessimisticLockException if pessimistic locking
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking
     *         fails and only the statement is rolled back
     * @throws PersistenceException if the query execution exceeds
     *         the query timeout value set and the transaction
     *         is rolled back
     * @see Stream
     * @see #getResultList()
     * @since 2.2
     */
    default Stream<X> getResultStream() {
        return getResultList().stream();
    }

    /**
     * Execute a SELECT query that returns a single result.
     * @return the result, of type {@link X}
     * @throws NoResultException if there is no result
     * @throws NonUniqueResultException if more than one result
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language UPDATE or DELETE statement
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws TransactionRequiredException if a lock mode other than
     *         {@code NONE} has been set and there is no transaction
     *         or the persistence context has not been joined to the
     *         transaction
     * @throws PessimisticLockException if pessimistic locking
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking
     *         fails and only the statement is rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    X getSingleResult();

    /**
     * Execute a SELECT query that returns a single untyped result.
     * @return the result, of type {@link X}, or null if there is no
     *         result
     * @throws NonUniqueResultException if more than one result
     * @throws IllegalStateException if called for a Jakarta
     *         Persistence query language UPDATE or DELETE statement
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws TransactionRequiredException if a lock mode other than
     *         {@code NONE} has been set and there is no transaction
     *         or the persistence context has not been joined to the
     *         transaction
     * @throws PessimisticLockException if pessimistic locking
     *         fails and the transaction is rolled back
     * @throws LockTimeoutException if pessimistic locking
     *         fails and only the statement is rolled back
     * @throws PersistenceException if the query execution exceeds
     *         the query timeout value set and the transaction
     *         is rolled back
     *
     * @since 3.2
     */
    X getSingleResultOrNull();

    /**
     * Set the maximum number of results to retrieve.
     * @param maxResult  maximum number of results to retrieve
     * @return the same query instance
     * @throws IllegalArgumentException if the argument is negative
     */
    TypedQuery<X> setMaxResults(int maxResult);

    /**
     * Set the position of the first result to retrieve.
     * @param startPosition position of the first result, 
     *        numbered from 0
     * @return the same query instance
     * @throws IllegalArgumentException if the argument is negative
     */
    TypedQuery<X> setFirstResult(int startPosition);

    /**
     * Set a query property or hint. The hints elements may be used 
     * to specify query properties and hints. Properties defined by
     * this specification must be observed by the provider. 
     * Vendor-specific hints that are not recognized by a provider
     * must be silently ignored. Portable applications should not
     * rely on the standard timeout hint. Depending on the database
     * in use and the locking mechanisms used by the provider,
     * this hint may or may not be observed.
     * @param hintName  name of property or hint
     * @param value  value for the property or hint
     * @return the same query instance
     * @throws IllegalArgumentException if the second argument is not
     *         valid for the implementation
     */
    TypedQuery<X> setHint(String hintName, Object value);

    /**
     * Bind the value of a {@code Parameter} object.
     * @param param  parameter object
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter
     *         does not correspond to a parameter of the
     *         query
     */
     <T> TypedQuery<X> setParameter(Parameter<T> param, T value);

    /**
     * Bind an instance of {@link java.util.Calendar} to a {@link Parameter} object.
     * @param param  parameter object
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    TypedQuery<X> setParameter(Parameter<Calendar> param, 
                               Calendar value,  
                               TemporalType temporalType);

    /**
     * Bind an instance of {@link java.util.Date} to a {@link Parameter} object.
     * @param param  parameter object
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    TypedQuery<X> setParameter(Parameter<Date> param, Date value,  
                               TemporalType temporalType);

    /**
     * Bind an argument value to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does 
     *         not correspond to a parameter of the query or if
     *         the argument is of incorrect type
     */
    TypedQuery<X> setParameter(String name, Object value);

    /**
     * Bind an instance of {@link java.util.Calendar} to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does
     *         not correspond to a parameter of the query or if
     *         the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    TypedQuery<X> setParameter(String name, Calendar value, 
                               TemporalType temporalType);

    /**
     * Bind an instance of {@link java.util.Date} to a named parameter.
     * @param name   parameter name
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does
     *         not correspond to a parameter of the query or if
     *         the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    TypedQuery<X> setParameter(String name, Date value, 
                               TemporalType temporalType);

    /**
     * Bind an argument value to a positional parameter.
     * @param position  position
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
     *         correspond to a positional parameter of the
     *         query or if the argument is of incorrect type
     */
    TypedQuery<X> setParameter(int position, Object value);

    /**
     * Bind an instance of {@link java.util.Calendar} to a positional
     * parameter.
     * @param position  position
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
     *         correspond to a positional parameter of the query
     *         or if the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    TypedQuery<X> setParameter(int position, Calendar value,  
                               TemporalType temporalType);

    /**
     * Bind an instance of {@link java.util.Date} to a positional
     * parameter.
     * @param position  position
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
      *        correspond to a positional parameter of the query
     *         or if the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    TypedQuery<X> setParameter(int position, Date value,  
                               TemporalType temporalType);

     /**
      * Set the flush mode type to be used for the query execution.
      * The flush mode type applies to the query regardless of the
      * flush mode type in use for the entity manager.
      * @param flushMode  flush mode
      * @return the same query instance
      */
     TypedQuery<X> setFlushMode(FlushModeType flushMode);

     /**
      * Set the lock mode type to be used for the query execution.
      * @param lockMode  lock mode
      * @return the same query instance
      * @throws IllegalStateException if the query is found not to 
      *         be a Jakarta Persistence query language SELECT query
      *         or a {@link jakarta.persistence.criteria.CriteriaQuery}
      *         query
      */
     TypedQuery<X> setLockMode(LockModeType lockMode);

    /**
     * Set the cache retrieval mode that is in effect during
     * query execution. This cache retrieval mode overrides the
     * cache retrieve mode in use by the entity manager.
     * @param cacheRetrieveMode cache retrieval mode
     * @return the same query instance
     * @since 3.2
     */
    TypedQuery<X> setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode);

    /**
     * Set the cache storage mode that is in effect during
     * query execution. This cache storage mode overrides the
     * cache storage mode in use by the entity manager.
     * @param cacheStoreMode cache storage mode
     * @return the same query instance
     * @since 3.2
     */
    TypedQuery<X> setCacheStoreMode(CacheStoreMode cacheStoreMode);

    /**
     * Set the query timeout, in milliseconds. This is a hint,
     * and is an alternative to {@linkplain #setHint setting
     * the hint} {@code jakarta.persistence.query.timeout}.
     * @param timeout the timeout, in milliseconds, or null to
     *                indicate no timeout
     * @return the same query instance
     * @since 3.2
     */
    TypedQuery<X> setTimeout(Integer timeout);
}
import java.util.Calendar;
import java.util.Date;
import java.util.List;

/**
 * Interface used to control stored procedure query execution.
 *
 * 
 * Stored procedure query execution may be controlled in accordance with 
 * the following:
 * <ul>
 * <li>The {@link #setParameter} methods are used to set the values of
 * all required {@code IN} and {@code INOUT} parameters. It is not
 * required to set the values of stored procedure parameters for which
 * default values have been defined by the stored procedure.</li>
 * <li> When {@link #getResultList} and {@link #getSingleResult} are
 * called on a {@code StoredProcedureQuery} object, the provider calls
 * {@link #execute} on an unexecuted stored procedure query before
 * processing {@code getResultList} or {@code getSingleResult}.</li>
 * <li> When {@link #executeUpdate} is called on a
 * {@code StoredProcedureQuery} object, the provider will call
 * {@link #execute} on an unexecuted stored procedure query, followed
 * by {@link #getUpdateCount}. The results of {@code executeUpdate} will
 * be those of {@code getUpdateCount}.</li>
 * <li> The {@link #execute} method supports both the simple case where
 * scalar results are passed back only via {@code INOUT} and {@code OUT}
 * parameters as well as the most general case (multiple result sets
 * and/or update counts, possibly also in combination with output
 * parameter values).</li>
 * <li> The {@code execute} method returns true if the first result is
 * a result set, and false if it is an update count or there are no
 * results other than through {@code INOUT} and {@code OUT} parameters,
 * if any.</li>
 * <li> If the {@code execute} method returns true, the pending result
 * set can be obtained by calling {@link #getResultList} or
 * {@link #getSingleResult}.</li>
 * <li> The {@link #hasMoreResults} method can then be used to test for
 * further results.</li>
 * <li> If {@code execute} or {@code hasMoreResults} returns false, the
 * {@link #getUpdateCount} method can be called to obtain the pending
 * result if it is an update count. The {@code getUpdateCount} method
 * will return either the update count (zero or greater) or -1 if there
 * is no update count (i.e., either the next result is a result set or
 * there is no next update count).</li>
 * <li> For portability, results that correspond to JDBC result sets
 * and update counts need to be processed before the values of any
 * {@code INOUT} or {@code OUT} parameters are extracted.</li>
 * <li> After results returned through {@link #getResultList} and
 * {@link #getUpdateCount} have been exhausted, results returned through
 * {@code INOUT} and {@code OUT} parameters can be retrieved.</li>
 * <li> The {@link #getOutputParameterValue} methods are used to
 * retrieve the values passed back from the procedure through
 * {@code INOUT} and {@code OUT} parameters.</li>
 * <li> When using {@code REF_CURSOR} parameters for result sets the
 * update counts should be exhausted before calling {@link #getResultList}
 * to retrieve the result set. Alternatively, the {@code REF_CURSOR}
 * result set can be retrieved through {@link #getOutputParameterValue}.
 * Result set mappings are applied to results corresponding to
 * {@code REF_CURSOR} parameters in the order the {@code REF_CURSOR}
 * parameters were registered with the query.</li>
 * <li> In the simplest case, where results are returned only via
 * {@code INOUT} and {@code OUT} parameters, {@code execute} can be
 * followed immediately by calls to {@link #getOutputParameterValue}.
 * </li>
 * </ul>
 *
 * @see Query
 * @see Parameter
 *
 * @since 2.1
 */
public interface StoredProcedureQuery extends Query {

    /**
     * Set a query property or hint. The hints elements may be used 
     * to specify query properties and hints. Properties defined by
     * this specification must be observed by the provider. 
     * Vendor-specific hints that are not recognized by a provider
     * must be silently ignored. Portable applications should not
     * rely on the standard timeout hint. Depending on the database
     * in use, this hint may or may not be observed.
     * @param hintName  name of the property or hint
     * @param value  value for the property or hint
     * @return the same query instance
     * @throws IllegalArgumentException if the second argument is not
     *         valid for the implementation
     */
    StoredProcedureQuery setHint(String hintName, Object value);

    /**
     * Bind the value of a {@code Parameter} object.
     * @param param  parameter object
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     */
    <T> StoredProcedureQuery setParameter(Parameter<T> param, 
                                          T value);

    /**
     * Bind an instance of {@link java.util.Calendar} to a {@link Parameter} object.
     * @param param parameter object
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    StoredProcedureQuery setParameter(Parameter<Calendar> param,
                                      Calendar value, 
                                      TemporalType temporalType);

    /**
     * Bind an instance of {@link java.util.Date} to a {@link Parameter} object.
     * @param param parameter object
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    StoredProcedureQuery setParameter(Parameter<Date> param,
                                      Date value,
                                      TemporalType temporalType);

    /**
     * Bind an argument value to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does 
     *         not correspond to a parameter of the query or if the
     *         argument is of incorrect type
     */
    StoredProcedureQuery setParameter(String name, Object value);

    /**
     * Bind an instance of {@code java.util.Calendar} to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does 
     *         not correspond to a parameter of the query or if the
     *         value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    StoredProcedureQuery setParameter(String name, 
                                      Calendar value, 
                                      TemporalType temporalType);

    /**
     * Bind an instance of {@code java.util.Date} to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter name does 
     *         not correspond to a parameter of the query or if the
     *         value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    StoredProcedureQuery setParameter(String name, 
                                      Date value, 
                                      TemporalType temporalType);

    /**
     * Bind an argument value to a positional parameter.
     * @param position  position
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
     *         correspond to a positional parameter of the query
     *         or if the argument is of incorrect type
     */
    StoredProcedureQuery setParameter(int position, Object value);

    /**
     * Bind an instance of {@code java.util.Calendar} to a positional
     * parameter.
     * @param position  position
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
     *         correspond to a positional parameter of the query or
     *         if the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    StoredProcedureQuery setParameter(int position, 
                                      Calendar value,  
                                      TemporalType temporalType);

    /**
     * Bind an instance of {@code java.util.Date} to a positional parameter.
     * @param position  position
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if position does not
     *         correspond to a positional parameter of the query or
     *         if the value argument is of incorrect type
     * @deprecated Newly-written code should use the date/time types
     *             defined in {@link java.time}.
     */
    @Deprecated(since = "3.2")
    StoredProcedureQuery setParameter(int position, 
                                      Date value,  
                                      TemporalType temporalType);

    /**
     * Set the flush mode type to be used for the query execution.
     * The flush mode type applies to the query regardless of the
     * flush mode type in use for the entity manager.
     * @param flushMode  flush mode
     * @return the same query instance
     */
    StoredProcedureQuery setFlushMode(FlushModeType flushMode);

    /**
     * Set the cache retrieval mode that is in effect during
     * query execution. This cache retrieval mode overrides the
     * cache retrieve mode in use by the entity manager.
     * @param cacheRetrieveMode cache retrieval mode
     * @return the same query instance
     * @since 3.2
     */
    StoredProcedureQuery setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode);

    /**
     * Set the cache storage mode that is in effect during
     * query execution. This cache storage mode overrides the
     * cache storage mode in use by the entity manager.
     * @param cacheStoreMode cache storage mode
     * @return the same query instance
     * @since 3.2
     */
    StoredProcedureQuery setCacheStoreMode(CacheStoreMode cacheStoreMode);

    /**
     * Set the query timeout, in milliseconds. This is a hint,
     * and is an alternative to {@linkplain #setHint setting
     * the hint} {@code jakarta.persistence.query.timeout}.
     * @param timeout the timeout, in milliseconds, or null to
     *                indicate no timeout
     * @return the same query instance
     * @since 3.2
     */
    StoredProcedureQuery setTimeout(Integer timeout);

    /**
     * Register a positional parameter.
     * All parameters must be registered.
     * @param position  parameter position
     * @param type  type of the parameter
     * @param mode  parameter mode 
     * @return the same query instance
     */
    StoredProcedureQuery registerStoredProcedureParameter(
          int position,
          Class<?> type,
          ParameterMode mode);

    /**
     * Register a named parameter.
     * @param parameterName  name of the parameter as registered or
     *            specified in metadata
     * @param type  type of the parameter
     * @param mode  parameter mode 
     * @return the same query instance
     */
    StoredProcedureQuery registerStoredProcedureParameter(
          String parameterName,
          Class<?> type,
          ParameterMode mode);

    /**
     * Retrieve a value passed back from the procedure
     * through an INOUT or OUT parameter.
     * For portability, all results corresponding to result sets
     * and update counts must be retrieved before the values of 
     * output parameters.
     * @param position  parameter position
     * @return the result that is passed back through the parameter
     * @throws IllegalArgumentException if the position does
     *         not correspond to a parameter of the query or is
     *         not an INOUT or OUT parameter
     */
    Object getOutputParameterValue(int position);

    /**
     * Retrieve a value passed back from the procedure
     * through an INOUT or OUT parameter.
     * For portability, all results corresponding to result sets
     * and update counts must be retrieved before the values of 
     * output parameters.
     * @param parameterName  name of the parameter as registered or
     *        specified in metadata
     * @return the result that is passed back through the parameter
     * @throws IllegalArgumentException if the parameter name does
     *         not correspond to a parameter of the query or is
     *         not an INOUT or OUT parameter
     */
    Object getOutputParameterValue(String parameterName);

    /**
     * Return true if the first result corresponds to a result set,
     * and false if it is an update count or if there are no results
     * other than through INOUT and OUT parameters, if any.
     * @return  true if first result corresponds to result set
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    boolean execute();

    /**
     * Return the update count of -1 if there is no pending result or
     * if the first result is not an update count.  The provider will
     * call {@code execute} on the query if needed.
     * @return the update count or -1 if there is no pending result
     * or if the next result is not an update count.
     * @throws TransactionRequiredException if there is 
     *         no transaction or the persistence context has not
     *         been joined to the transaction
     * @throws QueryTimeoutException if the statement execution 
     *         exceeds the query timeout value set and only
     *         the statement is rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    int executeUpdate();

    /**
     * Retrieve the list of results from the next result set.
     * The provider will call {@code execute} on the query
     * if needed.
     * A {@code REF_CURSOR} result set, if any, is retrieved
     * in the order the {@code REF_CURSOR} parameter was 
     * registered with the query.
     * @return a list of the results or null is the next item is not 
     * a result set
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    List getResultList();

    /**
     * Retrieve a single result from the next result set.
     * The provider will call {@code execute} on the query
     * if needed.
     * A {@code REF_CURSOR} result set, if any, is retrieved
     * in the order the {@code REF_CURSOR} parameter was 
     * registered with the query.
     * @return the result or null if the next item is not a result set
     * @throws NoResultException if there is no result in the next
     *         result set
     * @throws NonUniqueResultException if more than one result
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    Object getSingleResult();

    /**
     * Retrieve a single result from the next result set.
     * The provider will call {@code execute} on the query
     * if needed.
     * A {@code REF_CURSOR} result set, if any, is retrieved
     * in the order the {@code REF_CURSOR} parameter was
     * registered with the query.
     * @return the result or null if the next item is not a result set
     *         or if there is no result in the next result set
     * @throws NonUniqueResultException if more than one result
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws PersistenceException if the query execution exceeds
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    Object getSingleResultOrNull();

    /**
     * Return true if the next result corresponds to a result set,
     * and false if it is an update count or if there are no results
     * other than through INOUT and OUT parameters, if any.
     * @return true if next result corresponds to result set
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    boolean hasMoreResults();

    /**
     * Return the update count or  -1 if there is no pending result
     * or if the next result is not an update count.
     * @return update count or -1 if there is no pending result or if
     *         the next result is not an update count
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction
     *         is rolled back
     */
    int getUpdateCount();

}
import java.util.List;

/**
 * Interface for extracting the elements of a query result tuple.
 *
 * @see TupleElement
 *
 * @since 2.0
 */
public interface Tuple {

    /**
     * Get the value of the specified tuple element.
     * @param tupleElement  tuple element
     * @return value of tuple element
     * @throws IllegalArgumentException if tuple element
     *         does not correspond to an element in the
     *         query result tuple
     */
    <X> X get(TupleElement<X> tupleElement);

    /**
     * Get the value of the tuple element to which the
     * specified alias has been assigned.
     * @param alias  alias assigned to tuple element
     * @param type of the tuple element
     * @return value of the tuple element
     * @throws IllegalArgumentException if alias
     *         does not correspond to an element in the
     *         query result tuple or element cannot be
     *         assigned to the specified type
     */
    <X> X get(String alias, Class<X> type); 

    /**
     * Get the value of the tuple element to which the
     * specified alias has been assigned.
     * @param alias  alias assigned to tuple element
     * @return value of the tuple element
     * @throws IllegalArgumentException if alias
      *        does not correspond to an element in the
     *         query result tuple
     */
    Object get(String alias); 

    /**
     * Get the value of the element at the specified
     * position in the result tuple. The first position
     * is 0.
     * @param i  position in result tuple
     * @param type  type of the tuple element
     * @return value of the tuple element
     * @throws IllegalArgumentException if i exceeds
     *         length of result tuple  or element cannot
     *         be assigned to the specified type
     */
    <X> X get(int i, Class<X> type);

    /**
     * Get the value of the element at the specified
     * position in the result tuple. The first position
     * is 0.
     * @param i  position in result tuple
     * @return value of the tuple element
     * @throws IllegalArgumentException if i exceeds
     *         length of result tuple
     */
    Object get(int i);

    /**
     * Return the values of the result tuple elements as
     * an array.
     * @return tuple element values
     */
    Object[] toArray();

    /**
     * Return the tuple elements.
     * @return tuple elements
     */
    List<TupleElement<?>> getElements();
}
/**
 * The {@code TupleElement} interface defines an element that is
 * returned in a query result tuple.
 * 
 * @param <X> the type of the element
 *
 * @see Tuple
 *
 * @since 2.0
 */
public interface TupleElement<X> {

    /**
     * Return the Java type of the tuple element.
     * @return the Java type of the tuple element
     */
    Class<? extends X> getJavaType();

    /**
     * Return the alias assigned to the tuple element or null, 
     * if no alias has been assigned.
     * @return alias
     */
    String getAlias();
}
/**
 * Type for query parameter objects.
 *
 * @param <T> the type of the parameter
 *
 * @see Query
 * @see TypedQuery
 *
 * @since 2.0
 */
public interface Parameter<T> {

    /**
     * Return the parameter name, or null if the parameter is
     * not a named parameter or no name has been assigned.
     * @return parameter name
     */
    String getName();

    /**
     * Return the parameter position, or null if the parameter
     * is not a positional parameter. 
     * @return position of parameter
     */
    Integer getPosition();

    /**
     * Return the Java type of the parameter. Values bound to
     * the parameter must be assignable to this type.
     * This method is required to be supported for criteria
     * queries only. Applications that use this method for
     * Jakarta Persistence query language queries and native
     * queries will not be portable.
     * @return the Java type of the parameter
     * @throws IllegalStateException if invoked on a parameter
     *         obtained from a query language query or native
     *         query when the implementation does not support
     *         this usage
     */
     Class<T> getParameterType();
}
import jakarta.persistence.metamodel.Attribute;
import jakarta.persistence.metamodel.MapAttribute;
import jakarta.persistence.metamodel.PluralAttribute;

import java.util.List;

/**
 * Declares operations common to {@link EntityGraph} and {@link Subgraph}.
 *
 * @see EntityGraph
 * @see Subgraph
 *
 * @since 3.2
 */
public interface Graph<T> {

    /**
     * Get an existing attribute node for the attribute with the given
     * name, or add a new attribute node if there is no existing node.
     *
     * @param attributeName  name of the attribute
     * @return the attribute node
     * @throws IllegalArgumentException if the attribute is not an
     *         attribute of this entity.
     * @throws IllegalStateException if the EntityGraph has been
     *         statically defined
     *
     * @since 3.2
     */
    <Y> AttributeNode<Y> addAttributeNode(String attributeName);

    /**
     * Get an existing attribute node for the given attribute, or add
     * a new attribute node if there is no existing node.
     *
     * @param attribute  attribute
     * @return the attribute node
     * @throws IllegalStateException if the EntityGraph has been
     *         statically defined
     *
     * @since 3.2
     */
    <Y> AttributeNode<Y> addAttributeNode(Attribute<? super T, Y> attribute);

    /**
     * Determine if there is an existing attribute node for the attribute
     * with the given name.
     *
     * @param attributeName  name of the attribute
     * @return true if there is an existing attribute node
     * @throws IllegalArgumentException if the attribute is not an
     *         attribute of this entity.
     *
     * @since 3.2
     */
    boolean hasAttributeNode(String attributeName);

    /**
     * Determine if there is an existing attribute node for the given
     * attribute.
     *
     * @param attribute  attribute
     * @return true if there is an existing attribute node
     *
     * @since 3.2
     */
    boolean hasAttributeNode(Attribute<? super T, ?> attribute);

    /**
     * Get an existing attribute node for the attribute with the given
     * name.
     *
     * @param attributeName  name of the attribute
     * @return the attribute node
     * @throws IllegalArgumentException if the attribute is not an
     *         attribute of this entity.
     * @throws java.util.NoSuchElementException if there is no existing
     *         node for the attribute
     *
     * @since 3.2
     */
    <Y> AttributeNode<Y> getAttributeNode(String attributeName);

    /**
     * Get an existing attribute node for the given attribute.
     *
     * @param attribute  attribute
     * @return the attribute node
     * @throws java.util.NoSuchElementException if there is no existing
     *         node for the attribute
     *
     * @since 3.2
     */
    <Y> AttributeNode<Y> getAttributeNode(Attribute<? super T, Y> attribute);

    /**
     * Remove an attribute node from the entity graph.
     * When this graph is interpreted as a load graph, this operation
     * suppresses inclusion of an attribute mapped for eager fetching.
     * The effect of this call may be overridden by subsequent
     * invocations of {@link #addAttributeNode} or {@link #addSubgraph}.
     * If there is no existing node for the given attribute name, this
     * operation has no effect.
     *
     * @param attributeName  name of the attribute
     *
     * @since 3.2
     */
    void removeAttributeNode(String attributeName);

    /**
     * Remove an attribute node from the entity graph.
     * When this graph is interpreted as a load graph, this operation
     * suppresses inclusion of an attribute mapped for eager fetching.
     * The effect of this call may be overridden by subsequent
     * invocations of {@link #addAttributeNode} or {@link #addSubgraph}.
     * If there is no existing node for the given attribute, this
     * operation has no effect.
     *
     * @param attribute  attribute
     *
     * @since 3.2
     */
    void removeAttributeNode(Attribute<? super T, ?> attribute);

    /**
     * Remove all attribute nodes of the given attribute types.
     * When this graph is interpreted as a load graph, this operation
     * suppresses inclusion of attributes mapped for eager fetching.
     * The effect of this call may be overridden by subsequent
     * invocations of {@link #addAttributeNode} or {@link #addSubgraph}.
     *
     * @since 3.2
     */
    void removeAttributeNodes(Attribute.PersistentAttributeType nodeTypes);

    /**
     * Add one or more attribute nodes to the entity graph.
     * If there is already an existing node for one of the given
     * attribute names, that particular argument is ignored and
     * has no effect.
     *
     * @param attributeName  name of the attribute     
     * @throws IllegalArgumentException if the attribute is not an 
     *         attribute of this managed type.
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     */
    void addAttributeNodes(String... attributeName);

    /**
     * Add one or more attribute nodes to the entity graph.
     * If there is already an existing node for one of the given
     * attributes, that particular argument is ignored and has no
     * effect.
     *
     * @param attribute  attribute
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     */
    void addAttributeNodes(Attribute<? super T, ?>... attribute);

    /**
     * Add a node to the graph that corresponds to a managed
     * type. This allows for construction of multi-node entity graphs
     * that include related managed types.
     *
     * @param attribute  attribute
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     */
    <X> Subgraph<X> addSubgraph(Attribute<? super T, X> attribute);

    /**
     * Add a node to the graph that corresponds to a managed
     * type with inheritance.  This allows for multiple subclass
     * subgraphs to be defined for this node of the entity
     * graph. Subclass subgraphs will automatically include the
     * specified attributes of superclass subgraphs.
     *
     * @param attribute  attribute
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute's target
     *         type is not a managed type
     * @throws IllegalStateException if the EntityGraph has been
     *         statically defined
     *
     * @since 3.2
     */
    <Y> Subgraph<Y> addTreatedSubgraph(Attribute<? super T, ? super Y> attribute, Class<Y> type);

    /**
     * Add a node to the graph that corresponds to a managed type
     * with inheritance. This allows for multiple subclass
     * subgraphs to be defined for this node of the entity graph.
     * Subclass subgraphs will automatically include the specified
     * attributes of superclass subgraphs
     *
     * @param attribute  attribute
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type
     * @throws IllegalStateException if this EntityGraph has been 
     *         statically defined
     * @deprecated use {@link #addTreatedSubgraph(Attribute, Class)}
     */
    @Deprecated(since = "3.2", forRemoval = true)
    <X> Subgraph<? extends X> addSubgraph(Attribute<? super T, X> attribute, Class<? extends X> type);

    /**
     * Add a node to the graph that corresponds to a managed type.
     * This allows for construction of multi-node entity graphs
     * that include related managed types.
     *
     * @param attributeName  name of the attribute 
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute is not an 
     *         attribute of this managed type.
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type
     * @throws IllegalStateException if this EntityGraph has been 
     *         statically defined
     */
    <X> Subgraph<X> addSubgraph(String attributeName);

    /**
     * Add a node to the graph that corresponds to a managed
     * type with inheritance.  This allows for multiple subclass
     * subgraphs to be defined for this node of the entity
     * graph. Subclass subgraphs will automatically include the
     * specified attributes of superclass subgraphs
     *
     * @param attributeName  name of the attribute 
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute is not 
     *         an attribute of this managed type.
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type
     * @throws IllegalStateException if this EntityGraph has been 
      *        statically defined
     */
    <X> Subgraph<X> addSubgraph(String attributeName, Class<X> type);

    /**
     * Add a node to the graph that corresponds to a collection element
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attribute  attribute
     * @return subgraph for the element attribute
     * @throws IllegalArgumentException if the attribute's target type
     *         is not an entity
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     *
     * @since 3.2
     */
    <E> Subgraph<E> addElementSubgraph(PluralAttribute<? super T, ?, E> attribute);

    /**
     * Add a node to the graph that corresponds to a collection element
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attribute  attribute
     * @return subgraph for the element attribute
     * @throws IllegalArgumentException if the attribute's target type
     *         is not an entity
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     *
     * @since 3.2
     */
    <E> Subgraph<E> addTreatedElementSubgraph(PluralAttribute<? super T, ?, ? super E> attribute, Class<E> type);

    /**
     * Add a node to the graph that corresponds to a collection element
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attributeName  name of the attribute
     * @return subgraph for the element attribute
     * @throws IllegalArgumentException if the attribute is not an
     *         attribute of this entity.
     * @throws IllegalArgumentException if the attribute's target
     *         type is not a managed type
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     */
    <X> Subgraph<X> addElementSubgraph(String attributeName);

    /**
     * Add a node to the graph that corresponds to a collection element
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attributeName  name of the attribute
     * @param type  entity subclass
     * @return subgraph for the element attribute
     * @throws IllegalArgumentException if the attribute is not an
     *         attribute of this entity.
     * @throws IllegalArgumentException if the attribute's target
     *         type is not a managed type
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     */
    <X> Subgraph<X> addElementSubgraph(String attributeName, Class<X> type);

    /**
     * Add a node to the graph that corresponds to a map key
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attribute  attribute
     * @return subgraph for the key attribute
     * @throws IllegalArgumentException if the attribute's target
     *         type is not a managed type entity
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     */
    <K> Subgraph<K> addMapKeySubgraph(MapAttribute<? super T, K, ?> attribute);

    /**
     * Add a node to the graph that corresponds to a map key
     * that is a managed type with inheritance. This allows for
     * construction of multi-node entity graphs that include related
     * managed types.  Subclass subgraphs will automatically include
     * the specified attributes of superclass subgraphs
     *
     * @param attribute  attribute
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute's target
     *         type is not a managed type entity
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     */
    <K> Subgraph<K> addTreatedMapKeySubgraph(MapAttribute<? super T, ? super K, ?> attribute, Class<K> type);

    /**
     * Add a node to the graph that corresponds to a map key
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attribute  attribute
     * @return subgraph for the key attribute
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type entity
     * @throws IllegalStateException if this EntityGraph has been 
     *         statically defined
     * @deprecated use {@link #addMapKeySubgraph(MapAttribute)}
     */
    @Deprecated(since = "3.2", forRemoval = true)
    <X> Subgraph<X> addKeySubgraph(Attribute<? super T, X> attribute);

    /**
     * Add a node to the graph that corresponds to a map key
     * that is a managed type with inheritance. This allows for
     * construction of multi-node entity graphs that include related
     * managed types.  Subclass subgraphs will automatically include
     * the specified attributes of superclass subgraphs
     *
     * @param attribute  attribute
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type entity
     * @throws IllegalStateException if this EntityGraph has been 
     *         statically defined
     * @deprecated use {@link #addTreatedMapKeySubgraph(MapAttribute, Class)}
     */
    @Deprecated(since = "3.2", forRemoval = true)
    <X> Subgraph<? extends X> addKeySubgraph(Attribute<? super T, X> attribute, Class<? extends X> type);

    /**
     * Add a node to the graph that corresponds to a map key
     * that is a managed type. This allows for construction of
     * multi-node entity graphs that include related managed types.
     *
     * @param attributeName  name of the attribute
     * @return subgraph for the key attribute
     * @throws IllegalArgumentException if the attribute is not an 
     *         attribute of this entity.
     * @throws IllegalArgumentException if the attribute's target 
     *         type is not a managed type
     * @throws IllegalStateException if this EntityGraph has been
     *         statically defined
     */
    <X> Subgraph<X> addKeySubgraph(String attributeName);

    /**
     * Add a node to the graph that corresponds to a map key
     * that is a managed type with inheritance. This allows for
     * construction of multi-node entity graphs that include related
     * managed types.  Subclass subgraphs will include the specified
     * attributes of superclass subgraphs
     *
     * @param attributeName  name of the attribute
     * @param type  entity subclass
     * @return subgraph for the attribute
     * @throws IllegalArgumentException if the attribute is not an 
     *         attribute of this entity.
     * @throws IllegalArgumentException if the attribute's target
     *         type is not a managed type
     * @throws IllegalStateException if this EntityGraph has been 
     *         statically defined
     */
    <X> Subgraph<X> addKeySubgraph(String attributeName, Class<X> type);

    /**
     * Return the attribute nodes corresponding to the attributes of
     * this managed type that are included in the graph.
     * @return list of attribute nodes included in the graph or an
     * empty list if none have been defined
     */
    List<AttributeNode<?>> getAttributeNodes();

}
/**
 * This type represents the root of an entity graph that will be
 * used as a template to define the attribute nodes and boundaries
 * of a graph of entities and entity relationships. The root must
 * be an entity type.
 * 
 * The methods to add subgraphs implicitly create the corresponding
 * attribute nodes as well; such attribute nodes should not be
 * redundantly specified.
 *
 * @param <T> The type of the root entity.
 *
 * @see AttributeNode
 * @see Subgraph
 * @see NamedEntityGraph
 *
 * @see EntityManager#createEntityGraph(Class)
 * @see EntityManager#createEntityGraph(String)
 * @see EntityManager#getEntityGraph(String)
 * @see EntityManagerFactory#addNamedEntityGraph(String, EntityGraph)
 * @see EntityManager#find(EntityGraph, Object, FindOption...)
 *
 * @since 2.1
 */
public interface EntityGraph<T> extends Graph<T> {

    /**
     * Return the name of a named {@code EntityGraph} (an entity
     * graph defined by means of the {@link NamedEntityGraph}
     * annotation, XML descriptor element, or added by means of the
     * {@link EntityManagerFactory#addNamedEntityGraph} method).
     * Returns null if the {@code EntityGraph} is not a named
     * {@code EntityGraph}.
     */
    String getName();

    /**
     * Add additional attributes to this entity graph that
     * correspond to attributes of subclasses of the entity type of
     * this {@code EntityGraph}. Subclass subgraphs automatically
     * include the specified attributes of superclass subgraphs.
     *
     * @param type  entity subclass
     * @return subgraph for the subclass
     * @throws IllegalArgumentException if the type is not an entity type
     * @throws IllegalStateException if the EntityGraph has been
     *         statically defined
     */
    <S extends T> Subgraph<S> addTreatedSubgraph(Class<S> type);

    /**
     * Add additional attributes to this entity graph that
     * correspond to attributes of subclasses of the entity type of
     * this {@code EntityGraph}. Subclass subgraphs automatically
     * include the specified attributes of superclass subgraphs.
     *
     * @param type  entity subclass
     * @return subgraph for the subclass
     * @throws IllegalArgumentException if the type is not an entity type
     * @throws IllegalStateException if the EntityGraph has been 
     *         statically defined
     * @deprecated use {@link #addTreatedSubgraph(Class)}
     */
    @Deprecated(since = "3.2", forRemoval = true)
    <T> Subgraph<? extends T> addSubclassSubgraph(Class<? extends T> type);

}
/**
 * This type represents a subgraph for an attribute node that
 * corresponds to a managed type. Using this class, an entity
 * subgraph can be embedded within an {@link EntityGraph}.
 *
 * @param <T> The type of the attribute.
 *
 * @see EntityGraph
 * @see AttributeNode
 * @see NamedSubgraph
 *
 * @since 2.1
 */
public interface Subgraph<T> extends Graph<T> {

    /**
     * Return the type for which this subgraph was defined.
     * @return managed type referenced by the subgraph
     */
    Class<T> getClassType();

}
import java.util.Map;

/**
 * Represents an attribute node of an entity graph.
 *
 * @param <T> The type of the attribute.
 *
 * @see EntityGraph
 * @see Subgraph
 * @see NamedAttributeNode
 *
 * @since 2.1
 */
public interface AttributeNode<T> {

    /**
     * Return the name of the attribute corresponding to the
     * attribute node.
     * @return name of the attribute
     */
    String getAttributeName();

    /**
     * Return a map of subgraphs associated with this attribute
     * node.
     * @return a {@link Map} of subgraphs associated with this
     * attribute node or an empty {@code Map} if none have been
     * defined
     */
    Map<Class, Subgraph> getSubgraphs();

    /**
     * Return a map of subgraphs associated with this attribute
     * node's map key.
     * @return a {@link Map} of subgraphs associated with this
     * attribute node's map key or an empty {@code Map} if none
     * have been defined
     */
    Map<Class, Subgraph> getKeySubgraphs();
}
import java.util.Map;

/**
 * Allows programmatic {@linkplain #create schema creation},
 * {@linkplain #validate schema validation},
 * {@linkplain #truncate data cleanup}, and
 * {@linkplain #drop schema cleanup} for entities belonging
 * to a certain persistence unit.
 * 
 * <p>Properties are inherited from the {@link EntityManagerFactory},
 * that is, they may be specified via {@code persistence.xml} or
 * {@link Persistence#createEntityManagerFactory(String, Map)}.
 *
 * @see EntityManagerFactory#getSchemaManager()
 *
 * @since 3.2
 */
public interface SchemaManager {
        /**
         * Create database objects mapped by entities belonging to the
         * persistence unit.
         *
         * <p>If a DDL operation fails, the behavior is undefined.
         * A provider may throw an exception, or it may ignore the problem
         * and continue.
         *
         * @param createSchemas if {@code true}, attempt to create schemas,
         *                      otherwise, assume the schemas already exist
         */
        void create(boolean createSchemas);

        /**
         * Drop database objects mapped by entities belonging to the
         * persistence unit, undoing the effects of the
         * {@linkplain #create(boolean) previous creation}.
         *
         * <p>If a DDL operation fails, the behavior is undefined.
         * A provider may throw an exception, or it may ignore the problem
         * and continue.
         *
         * @param dropSchemas if {@code true}, drop schemas,
         *                    otherwise, leave them be
         */
        void drop(boolean dropSchemas);

        /**
         * Validate that the database objects mapped by entities belonging
         * to the persistence unit have the expected definitions.
         *
         * <p>The persistence provider is not required to perform
         * any specific validation, so the semantics of this operation are
         * entirely provider-specific.
         *
         * @throws SchemaValidationException if a database object is missing or
         * does not have the expected definition
         */
        void validate() throws SchemaValidationException;

        /**
         * Truncate the database tables mapped by entities belonging to
         * the persistence unit, and then re-import initial data from any
         * configured SQL scripts for data loading.
         *
         * <p>If a SQL operation fails, the behavior is undefined.
         * A provider may throw an exception, or it may ignore the problem
         * and continue.
         */
        void truncate();
}
package jakarta.persistence;

import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.HashSet;
import jakarta.persistence.spi.PersistenceProvider;
import jakarta.persistence.spi.PersistenceProviderResolver;
import jakarta.persistence.spi.PersistenceProviderResolverHolder;
import jakarta.persistence.spi.LoadState;

/**
 * Bootstrap class used to obtain an {@link EntityManagerFactory}
 * in Java SE environments. It may also be used to cause schema
 * generation to occur.
 * 
 * The {@code Persistence} class is available in a Jakarta EE
 * container environment as well; however, support for the Java SE
 * bootstrapping APIs is not required in container environments.
 * 
 * The {@code Persistence} class is used to obtain a {@link
 * PersistenceUtil PersistenceUtil} instance in both Jakarta EE
 * and Java SE environments.
 *
 * @since 1.0
 */
public class Persistence {

    /**
     * Default constructor.
     * @deprecated This class is not intended to be extended nor instantiated,
     *     it is going to be marked {@code final} when this constructor becomes hidden.
     */
    @Deprecated(since = "3.2", forRemoval = true)
    public Persistence() {
        //kept for backward compatibility with pre-3.2 versions
    }

    /**
     * Create and return an {@link EntityManagerFactory} for the named
     * persistence unit.
     * 
     * @param persistenceUnitName the name of the persistence unit
     * @return the factory that creates {@link EntityManager}s configured
     *         according to the specified persistence unit
     */
    public static EntityManagerFactory createEntityManagerFactory(String persistenceUnitName) {
        return createEntityManagerFactory(persistenceUnitName, null);
    }

    /**
     * Create and return an {@link 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. These properties may include properties
     *                   to control schema generation. The values of these
     *                   properties override any values that may have been
     *                   configured elsewhere.
     * @return the factory that creates {@link EntityManager}s configured
     *        according to the specified persistence unit
     */
    public static EntityManagerFactory createEntityManagerFactory(String persistenceUnitName, Map<?,?> properties) {

        EntityManagerFactory emf = null;
        PersistenceProviderResolver resolver = PersistenceProviderResolverHolder.getPersistenceProviderResolver();

        List<PersistenceProvider> providers = resolver.getPersistenceProviders();

        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;
    }

    /**
     * Create and return an {@link EntityManagerFactory} for the named
     * persistence unit, using the given properties.
     *
     * @param configuration configuration of the persistence unit
     * @return the factory that creates {@link EntityManager}s configured
     *         according to the specified persistence unit
     *
     * @since 3.2
     */
    public static EntityManagerFactory createEntityManagerFactory(PersistenceConfiguration configuration) {

        EntityManagerFactory emf = null;
        PersistenceProviderResolver resolver = PersistenceProviderResolverHolder.getPersistenceProviderResolver();

        List<PersistenceProvider> providers = resolver.getPersistenceProviders();

        for (PersistenceProvider provider : providers) {
            emf = provider.createEntityManagerFactory(configuration);
            if (emf != null) {
                break;
            }
        }
        if (emf == null) {
            throw new PersistenceException("No Persistence provider for EntityManager named " + configuration.name());
        }
        return emf;
    }

    /**
     * Create database schemas and/or tables and/or create DDL scripts
     * as determined by the supplied properties.
     * <p>
     * Called when schema generation is to occur as a separate phase
     * from creation of the entity manager factory.
     * <p>
     * @param persistenceUnitName the name of the persistence unit
     * @param map properties for schema generation; these may also
     *            contain provider-specific properties. The values
     *            of these properties override any values that may
     *            have been configured elsewhere.
     * @throws PersistenceException if insufficient or inconsistent
     *         configuration information is provided or if schema
     *         generation otherwise fails.
     *
     * @since 2.1
     */
    public static void generateSchema(String persistenceUnitName, Map<?,?> map) {
        PersistenceProviderResolver resolver = PersistenceProviderResolverHolder.getPersistenceProviderResolver();
        List<PersistenceProvider> providers = resolver.getPersistenceProviders();

        for (PersistenceProvider provider : providers) {
            if (provider.generateSchema(persistenceUnitName, map)) {
                return;
            }
        }

        throw new PersistenceException("No Persistence provider to generate schema named " + persistenceUnitName);
    }

    /**
     * Return the {@link PersistenceUtil} instance
     * @return {@link PersistenceUtil} instance
     * @since 2.0
     */
    public static PersistenceUtil getPersistenceUtil() {
       return new PersistenceUtilImpl();
    }

    /**
     * Implementation of the {@link PersistenceUtil} interface
     * @since 2.0
     */
    private static class PersistenceUtilImpl implements PersistenceUtil {
        public boolean isLoaded(Object entity, String attributeName) {
            PersistenceProviderResolver resolver = PersistenceProviderResolverHolder.getPersistenceProviderResolver();

            List<PersistenceProvider> providers = resolver.getPersistenceProviders();

            for (PersistenceProvider provider : providers) {
                LoadState loadstate = provider.getProviderUtil().isLoadedWithoutReference(entity, attributeName);
                if(loadstate == LoadState.LOADED) {
                    return true;
                } else if (loadstate == LoadState.NOT_LOADED) {
                    return false;
                } // else continue
            }

            //None of the providers could determine the load state try isLoadedWithReference
            for (PersistenceProvider provider : providers) {
                LoadState loadstate = provider.getProviderUtil().isLoadedWithReference(entity, attributeName);
                if(loadstate == LoadState.LOADED) {
                    return true;
                } else if (loadstate == LoadState.NOT_LOADED) {
                    return false;
                } // else continue
            }

            //None of the providers could determine the load state.
            return true;
        }

        public boolean isLoaded(Object entity) {
            PersistenceProviderResolver resolver = PersistenceProviderResolverHolder.getPersistenceProviderResolver();

            List<PersistenceProvider> providers = resolver.getPersistenceProviders();

            for (PersistenceProvider provider : providers) {
                LoadState loadstate = provider.getProviderUtil().isLoaded(entity);
                if(loadstate == LoadState.LOADED) {
                    return true;
                } else if (loadstate == LoadState.NOT_LOADED) {
                    return false;
                } // else continue
            }
            //None of the providers could determine the load state
            return true;
        }
    }

    /**
     * This final String is deprecated and should be removed and is only here for TCK backward compatibility
     * @since 1.0
     * @deprecated
     *
     * TODO: Either change TCK reference to PERSISTENCE_PROVIDER field to expect 
     * "jakarta.persistence.spi.PersistenceProvider" or remove PERSISTENCE_PROVIDER field and also update TCK signature 
     * tests. 
     */
    @Deprecated(since = "3.2", forRemoval = true)
    public static final String PERSISTENCE_PROVIDER = "jakarta.persistence.spi.PersistenceProvider";

    /**
     * This instance variable is deprecated and should be removed and is only here for TCK backward compatibility
     * @since 1.0
     * @deprecated
     */
    @Deprecated(since = "3.2", forRemoval = true)
    protected static final Set<PersistenceProvider> providers = new HashSet<PersistenceProvider>();
}
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;

/**
 * Represents a configuration of a persistence unit, allowing programmatic
 * creation of an {@link EntityManagerFactory}. The configuration options
 * available via this API reflect the similarly-named elements of the
 * {@code persistence.xml} file.
 *
 * This API may not be used to configure a container-managed persistence
 * unit. That is, the configured persistence unit should be considered a
 * Java SE persistence unit, even when this API is used within the Jakarta
 * EE environment.
 *
 * If injection of the {@link EntityManagerFactory} is required, a CDI
 * {@code Producer} may be used to make the {@link EntityManagerFactory}
 * available as a CDI managed bean.
 *
 * {@snippet :
 * @Produces @ApplicationScoped @Documents
 * EntityManagerFactory configure() {
 * return new PersistenceConfiguration()
 * .name("DocumentData")
 * .nonJtaDataSource("java:global/jdbc/DocumentDatabase")
 * .managedClass(Document.class)
 * .createEntityManagerFactory();
 * }
 * }
 *
 * Similarly, if injection of an {@link EntityManager} is required,
 * a CDI {@code Producer} method/{@code Disposer} method pair may be
 * used to make the {@link EntityManager} available as a CDI managed
 * bean.
 *
 * {@snippet :
 * @Produces @TransactionScoped @Documents
 * EntityManager create(@Documents EntityManagerFactory factory) {
 * return factory.createEntityManager();
 * }
 *
 * void close(@Disposes @Documents EntityManager entityManager) {
 * entityManager.close();
 * }
 * }
 *
 * It is intended that persistence providers define subclasses of
 * this class with vendor-specific configuration options. A provider
 * must support configuration via any instance of this class or of any
 * subclass of this class.
 *
 * @see Persistence#createEntityManagerFactory(PersistenceConfiguration)
 *
 * @since 3.2
 */
public class PersistenceConfiguration {

    /**
     * Fully qualified name of the JDBC driver class.
     */
    public static final String JDBC_DRIVER = "jakarta.persistence.jdbc.driver";
    /**
     * JDBC URL.
     */
    public static final String JDBC_URL = "jakarta.persistence.jdbc.url";
    /**
     * Username for JDBC authentication.
     */
    public static final String JDBC_USER = "jakarta.persistence.jdbc.user";
    /**
     * Password for JDBC authentication.
     */
    public static final String JDBC_PASSWORD = "jakarta.persistence.jdbc.password";
    /**
     * An instance of {@code javax.sql.DataSource}.
     */
    public static final String JDBC_DATASOURCE = "jakarta.persistence.dataSource";

    /**
     * Default pessimistic lock timeout hint.
     */
    public static final String LOCK_TIMEOUT = "jakarta.persistence.lock.timeout";
    /**
     * Default query timeout hint.
     */
    public static final String QUERY_TIMEOUT = "jakarta.persistence.query.timeout";

    /**
     * The action to be performed against the database.
     *
     * <p>Standard actions are: {@code none}, {@code create},
     * {@code drop}, {@code drop-and-create}, {@code validate}.
     */
    public static final String SCHEMAGEN_DATABASE_ACTION = "jakarta.persistence.schema-generation.database.action";
    /**
     * The action to be generated as a SQL script.
     *
     * <p>The script is generated in the location specified by
     * {@value #SCHEMAGEN_CREATE_TARGET} or {@value #SCHEMAGEN_DROP_TARGET}.
     *
     * <p>Standard actions are: {@code none}, {@code create},
     * {@code drop}, {@code drop-and-create}.
     */
    public static final String SCHEMAGEN_SCRIPTS_ACTION = "jakarta.persistence.schema-generation.scripts.action";
    /**
     * The source of artifacts to be created.
     *
     * <p>Standard sources are: {@code metadata}, {@code script},
     * {@code metadata-then-script}, {@code script-then-metadata}.
     *
     * <p>The location of the script source is specified by
     * {@value #SCHEMAGEN_CREATE_SCRIPT_SOURCE}.
     */
    public static final String SCHEMAGEN_CREATE_SOURCE = "jakarta.persistence.schema-generation.create-source";
    /**
     * The source of artifacts to be dropped.
     *
     * <p>Standard sources are: {@code metadata}, {@code script},
     * {@code metadata-then-script}, {@code script-then-metadata}.
     *
     * <p>The location of the script source is specified by
     * {@value #SCHEMAGEN_DROP_SCRIPT_SOURCE}.
     */
    public static final String SCHEMAGEN_DROP_SOURCE = "jakarta.persistence.schema-generation.drop-source";
    /**
     * An application-provided SQL script to be executed when the
     * schema is created.
     */
    public static final String SCHEMAGEN_CREATE_SCRIPT_SOURCE = "jakarta.persistence.schema-generation.create-script-source";
    /**
     * An application-provided SQL script to be executed when the
     * schema is dropped.
     */
    public static final String SCHEMAGEN_DROP_SCRIPT_SOURCE = "jakarta.persistence.schema-generation.drop-script-source";
    /**
     * The provider-generated SQL script which creates the schema
     * when {@value SCHEMAGEN_SCRIPTS_ACTION} is set.
     */
    public static final String SCHEMAGEN_CREATE_TARGET = "jakarta.persistence.schema-generation.create-target";
    /**
     * The provider-generated SQL script which drops the schema
     * when {@value SCHEMAGEN_SCRIPTS_ACTION} is set.
     */
    public static final String SCHEMAGEN_DROP_TARGET = "jakarta.persistence.schema-generation.drop-target";

    /**
     * An instance of {@code jakarta.validation.ValidatorFactory},
     */
    public static final String VALIDATION_FACTORY = "jakarta.persistence.validation.factory";
    /**
     * Target groups for validation at {@link PrePersist}.
     */
    public static final String VALIDATION_GROUP_PRE_PERSIST = "jakarta.persistence.validation.group.pre-persist";
    /**
     * Target groups for validation at {@link PreUpdate}.
     */
    public static final String VALIDATION_GROUP_PRE_UPDATE = "jakarta.persistence.validation.group.pre-update";
    /**
     * Target groups for validation at {@link PreRemove}.
     */
    public static final String VALIDATION_GROUP_PRE_REMOVE = "jakarta.persistence.validation.group.pre-remove";

    /**
     * String specifying a {@link SharedCacheMode}.
     *
     * <p>Defined for use with
     * {@link Persistence#createEntityManagerFactory(String, Map)}.
     * Clients of this {@code PersistenceConfiguration} class
     * should use {@link #sharedCacheMode(SharedCacheMode)}.
     */
    public static final String CACHE_MODE = "jakarta.persistence.sharedCache.mode";

    private final String name;

    private String provider;
    private String jtaDataSource;
    private String nonJtaDataSource;

    private SharedCacheMode sharedCacheMode = SharedCacheMode.UNSPECIFIED;
    private ValidationMode validationMode = ValidationMode.AUTO;
    private PersistenceUnitTransactionType transactionType = PersistenceUnitTransactionType.RESOURCE_LOCAL;

    private final List<Class<?>> managedClasses = new ArrayList<>();
    private final List<String> mappingFileNames = new ArrayList<>();
    private final Map<String,Object> properties = new HashMap<>();

    /**
     * Create a new empty configuration. An empty configuration does not
     * typically hold enough information for successful invocation of
     * {@link #createEntityManagerFactory()}.
     *
     * @param name the name of the persistence unit, which may be used by
     *             the persistence provider for logging and error reporting
     */
    public PersistenceConfiguration(String name) {
        Objects.requireNonNull(name, "Persistence unit name should not be null");
        this.name = name;
    }

    /**
     * Create a new {@link EntityManagerFactory} based on this configuration.
     * @throws PersistenceException if required configuration is missing or
     *                             if the factory could not be created
     */
    public EntityManagerFactory createEntityManagerFactory() {
        return Persistence.createEntityManagerFactory(this);
    }

    /**
     * The name of the persistence unit, which may be used by the persistence
     * provider for logging and error reporting.
     * @return the name of the persistence unit.
     */
    public String name() {
        return name;
    }

    /**
     * Specify the persistence provider.
     * @param providerClassName the qualified name of the persistence provider class
     * @return this configuration
     */
    public PersistenceConfiguration provider(String providerClassName) {
        this.provider = providerClassName;
        return this;
    }

    /**
     * The fully-qualified name of a concrete class implementing
     * {@link jakarta.persistence.spi.PersistenceProvider}.
     * @return the qualified name of the persistence provider class.
     */
    public String provider() {
        return provider;
    }

    /**
     * Specify the JNDI name of a JTA {@code javax.sql.DataSource}.
     * @param dataSourceJndiName the JNDI name of a JTA datasource
     * @return this configuration
     */
    public PersistenceConfiguration jtaDataSource(String dataSourceJndiName) {
        this.jtaDataSource = dataSourceJndiName;
        return this;
    }

    /**
     * The JNDI name of a JTA {@code javax.sql.DataSource}.
     * @return the configured JTA datasource, if any, or null
     */
    public String jtaDataSource() {
        return jtaDataSource;
    }

    /**
     * Specify the JNDI name of a non-JTA {@code javax.sql.DataSource}.
     * @param dataSourceJndiName the JNDI name of a non-JTA datasource
     * @return this configuration
     */
    public PersistenceConfiguration nonJtaDataSource(String dataSourceJndiName) {
        this.nonJtaDataSource = dataSourceJndiName;
        return this;
    }

    /**
     * The JNDI name of a non-JTA {@code javax.sql.DataSource}.
     * @return the configured non-JTA datasource, if any, or null
     */
    public String nonJtaDataSource() {
        return nonJtaDataSource;
    }

    /**
     * Add a managed class (an {@link Entity}, {@link Embeddable},
     * {@link MappedSuperclass}, or {@link Converter}) to the
     * configuration.
     * @param managedClass the managed class
     * @return this configuration
     */
    public PersistenceConfiguration managedClass(Class<?> managedClass) {
        managedClasses.add(managedClass);
        return this;
    }

    /**
     * The configured managed classes, that is, a list of classes
     * annotated {@link Entity}, {@link Embeddable},
     * {@link MappedSuperclass}, or {@link Converter}.
     * @return all configured managed classes
     */
    public List<Class<?>> managedClasses() {
        return managedClasses;
    }

    /**
     * Add the path of an XML mapping file loaded as a resource to
     * the configuration.
     * @param name the resource path of the mapping file
     * @return this configuration
     */
    public PersistenceConfiguration mappingFile(String name) {
        mappingFileNames.add(name);
        return this;
    }

    /**
     * The configured resource paths of XML mapping files.
     * @return all configured mapping file resource paths
     */
    public List<String> mappingFiles() {
        return mappingFileNames;
    }

    /**
     * Specify the transaction type for the persistence unit.
     * @param transactionType the transaction type
     * @return this configuration
     */
    public PersistenceConfiguration transactionType(PersistenceUnitTransactionType transactionType) {
        this.transactionType = transactionType;
        return this;
    }

    /**
     * The {@linkplain PersistenceUnitTransactionType transaction type}.
     * <ul>
     * <li>If {@link PersistenceUnitTransactionType#JTA}, a JTA data
     *    source must be provided via {@link #jtaDataSource()},
     *    or by the container.
     * <li>If {@link PersistenceUnitTransactionType#RESOURCE_LOCAL},
     *    database connection properties may be specified via
     *    {@link #properties()}, or a non-JTA datasource may be
     *    provided via {@link #nonJtaDataSource()}.
     * </ul>
     * @return the transaction type
     */
    public PersistenceUnitTransactionType transactionType() {
        return transactionType;
    }

    /**
     * Specify the shared cache mode for the persistence unit.
     * @param sharedCacheMode the shared cache mode
     * @return this configuration
     */
    public PersistenceConfiguration sharedCacheMode(SharedCacheMode sharedCacheMode) {
        this.sharedCacheMode = sharedCacheMode;
        return this;
    }

    /**
     * The shared cache mode. The default behavior is unspecified
     * and {@linkplain SharedCacheMode#UNSPECIFIED provider-specific}.
     * @return the shared cache mode
     */
    public SharedCacheMode sharedCacheMode() {
        return sharedCacheMode;
    }

    /**
     * Specify the validation mode for the persistence unit.
     * @param validationMode the shared cache mode
     * @return this configuration
     */
    public PersistenceConfiguration validationMode(ValidationMode validationMode) {
        this.validationMode = validationMode;
        return this;
    }

    /**
     * The validation mode, {@link ValidationMode#AUTO} by default.
     * @return the validation mode
     */
    public ValidationMode validationMode() {
        return validationMode;
    }

    /**
     * Set a property of this persistence unit.
     * @param name the property name
     * @param value the property value
     * @return this configuration
     */
    public PersistenceConfiguration property(String name, Object value) {
        properties.put(name, value);
        return this;
    }

    /**
     * Set multiple properties of this persistence unit.
     * @param properties the properties
     * @return this configuration
     */
    public PersistenceConfiguration properties(Map<String,?> properties) {
        this.properties.putAll(properties);
        return this;
    }

    /**
     * Standard and vendor-specific property settings.
     * @return the configured properties
     */
    public Map<String, Object> properties() {
        return properties;
    }
}
package jakarta.persistence;

/**
 * Utility interface between the application and the persistence
 * provider(s). 
 * 
 * The {@code PersistenceUtil} interface instance obtained from
 * the {@link Persistence} class is used to determine the load state
 * of an entity or entity attribute regardless of which persistence
 * provider in the environment created the entity.
 *
 * @since 2.0
 */
public interface PersistenceUtil {

    /**
     * Determine the load state of a given persistent attribute.
     * @param entity  entity containing the attribute
     * @param attributeName name of attribute whose load state is
     *        to be determined
     * @return false if entity's state has not been loaded or if
     * the attribute state has not been loaded, else true
     */
    boolean isLoaded(Object entity, String attributeName);

    /**
     * Determine the load state of an entity.
     * This method can be used to determine the load state of an
     * entity passed as a reference. An entity is considered loaded
     * if all attributes for which {@link FetchType#EAGER} has been
     * specified have been loaded.
     * <p>The {@link #isLoaded(Object, String)} method should be
     * used to determine the load state of an attribute. Not doing
     * so might lead to unintended loading of state.
     * @param entity whose load state is to be determined
     * @return false if the entity has not been loaded, else true
     */
    boolean isLoaded(Object entity);
}
package jakarta.persistence;

import jakarta.persistence.metamodel.Attribute;

/**
 * Utility interface between the application and the persistence
 * provider managing the persistence unit.
 *
 * The methods of this interface should only be invoked on
 * entity instances obtained from or managed by entity managers
 * for this persistence unit or on new entity instances.
 *
 * @since 2.0
 */
public interface PersistenceUnitUtil extends PersistenceUtil {

    /**
     * Determine the load state of a given persistent attribute
     * of an entity belonging to the persistence unit.
     * @param entity  entity instance containing the attribute
     * @param attributeName name of attribute whose load state is
     *        to be determined
     * @return false if entity's state has not been loaded or if 
     *         the attribute state has not been loaded, else true
     */
    boolean isLoaded(Object entity, String attributeName);

    /**
     * Determine the load state of a given persistent attribute
     * of an entity belonging to the persistence unit.
     * @param entity  entity instance containing the attribute
     * @param attribute  attribute whose load state is to be determined
     * @return false if entity's state has not been loaded or if
     *         the attribute state has not been loaded, else true
     * @since 3.2
     */
    <E> boolean isLoaded(E entity, Attribute<? super E, ?> attribute);

    /**
     * Determine the load state of an entity belonging to the
     * persistence unit. This method can be used to determine the
     * load state of an entity passed as a reference. An entity is
     * considered loaded if all attributes for which
     * {@link FetchType#EAGER} has been specified have been loaded.
     * <p> The {@link #isLoaded(Object, String)} method should be
     * used to determine the load state of an attribute. Not doing
     * so might lead to unintended loading of state.
     * @param entity   entity instance whose load state is to be determined
     * @return false if the entity has not been loaded, else true
     */
    boolean isLoaded(Object entity);

    /**
     * Load the persistent value of a given persistent attribute
     * of an entity belonging to the persistence unit and to an
     * open persistence context.
     * After this method returns, {@link #isLoaded(Object,String)}
     * must return true with the given entity instance and attribute.
     * @param entity  entity instance
     * @param attributeName  the name of the attribute to be loaded
     * @throws IllegalArgumentException if the given object is not an
     * instance of an entity class belonging to the persistence unit
     * @throws PersistenceException if the entity is not associated
     * with an open persistence context or cannot be loaded from the
     * database
     * @since 3.2
     */
    void load(Object entity, String attributeName);

    /**
     * Load the persistent value of a given persistent attribute
     * of an entity belonging to the persistence unit and to an
     * open persistence context.
     * After this method returns, {@link #isLoaded(Object,Attribute)}
     * must return true with the given entity instance and attribute.
     * @param entity  entity instance to be loaded
     * @param attribute  the attribute to be loaded
     * @throws IllegalArgumentException if the given object is not an
     * instance of an entity class belonging to the persistence unit
     * @throws PersistenceException if the entity is not associated
     * with an open persistence context or cannot be loaded from the
     * database
     * @since 3.2
     */
    <E> void load(E entity, Attribute<? super E, ?> attribute);

    /**
     * Load the persistent state of an entity belonging to the
     * persistence unit and to an open persistence context.
     * After this method returns, {@link #isLoaded(Object)} must
     * return true with the given entity instance.
     * @param entity  entity instance to be loaded
     * @throws IllegalArgumentException if the given object is not an
     * instance of an entity class belonging to the persistence unit
     * @throws PersistenceException if the entity is not associated
     * with an open persistence context or cannot be loaded from the
     * database
     * @since 3.2
     */
    void load(Object entity);

    /**
     * Return true if the given entity belonging to the persistence
     * unit and to an open persistence context is an instance of the
     * given entity class, or false otherwise. This method may, but
     * is not required to, load the given entity by side effect.
     * @param entity  entity instance
     * @param entityClass  an entity class belonging to the persistence
     * unit
     * @throws IllegalArgumentException if the given object is not an
     * instance of an entity class belonging to the persistence unit
     * or if the given class is not an entity class belonging to the
     * persistence unit
     * @throws PersistenceException if the entity is not associated
     * with an open persistence context or cannot be loaded from the
     * database
     * @since 3.2
     */
    boolean isInstance(Object entity, Class<?> entityClass);

    /**
     * Return the concrete entity class if the given entity belonging
     * to the persistence unit and to an open persistence context.
     * This method may, but is not required to, load the given entity
     * by side effect.
     * @param entity  entity instance
     * @return an entity class belonging to the persistence unit
     * @throws IllegalArgumentException if the given object is not an
     * instance of an entity class belonging to the persistence unit
     * @throws PersistenceException if the entity is not associated
     * with an open persistence context or cannot be loaded from the
     * database
     * @since 3.2
     */
    <T> Class<? extends T> getClass(T entity);

    /**
     * Return the id of the entity.
     * A generated id is not guaranteed to be available until after
     * the database insert has occurred.
     * Returns null if the entity does not yet have an id.
     * @param entity  entity instance
     * @return id of the entity
     * @throws IllegalArgumentException if the object is found not 
     *         to be an entity
     */
    Object getIdentifier(Object entity);

    /**
     * Return the version of the entity.
     * A generated version is not guaranteed to be available until after
     * the database insert has occurred.
     * Returns null if the entity does not yet have an id.
     * @param entity  entity instance
     * @return id of the entity
     * @throws IllegalArgumentException if the object is found not
     *         to be an entity
     * @since 3.2
     */
    Object getVersion(Object entity);
}
package jakarta.persistence.criteria;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.temporal.Temporal;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;
import jakarta.persistence.Tuple;

/**
 * Used to construct criteria queries, compound selections, 
 * expressions, predicates, orderings.
 *
 * Note that {@link Predicate} is used instead of
 * {@code Expression<Boolean>} in this API in
 * order to work around the fact that Java generics are not
 * compatible with varags.
 *
 * @since 2.0
 */
public interface CriteriaBuilder {

    /**
     * Create a {@link CriteriaQuery} object.
     * @return criteria query object
     */
    CriteriaQuery<Object> createQuery();

    /**
     * Create a {@link CriteriaQuery} object with the given
     * result type.
     * @param resultClass  type of the query result
     * @return criteria query object
     */
    <T> CriteriaQuery<T> createQuery(Class<T> resultClass);

    /**
     * Create a {@link CriteriaQuery} object that returns a
     * tuple of objects as its result.
     * @return criteria query object
     */
    CriteriaQuery<Tuple> createTupleQuery();

    // methods to construct queries for bulk updates and deletes:

    /**
     * Create a {@link CriteriaUpdate} query object to perform a
     * bulk update operation.
     * @param targetEntity  target type for update operation
     * @return the query object
     * @since 2.1
     */
    <T> CriteriaUpdate<T> createCriteriaUpdate(Class<T> targetEntity);

    /**
     * Create a {@link CriteriaDelete} query object to perform a
     * bulk delete operation.
     * @param targetEntity  target type for delete operation
     * @return the query object
     * @since 2.1
     */
    <T> CriteriaDelete<T> createCriteriaDelete(Class<T> targetEntity);

    // selection construction methods:

    /**
     * Create a selection item corresponding to a constructor.
     * This method is used to specify a constructor that is
     * applied to the results of the query execution. If the
     * constructor is for an entity class, the resulting entities
     * will be in the new state after the query is executed.
     * @param resultClass  class whose instance is to be constructed
     * @param selections  arguments to the constructor
     * @return compound selection item
     * @throws IllegalArgumentException if an argument is a 
     *         tuple- or array-valued selection item
     */
    <Y> CompoundSelection<Y> construct(Class<Y> resultClass, Selection<?>... selections);

    /**
     * Create a tuple-valued selection item.
     * @param selections  selection items
     * @return tuple-valued compound selection
     * @throws IllegalArgumentException if an argument is a 
     *         tuple- or array-valued selection item
     */
    CompoundSelection<Tuple> tuple(Selection<?>... selections);

    /**
     * Create a tuple-valued selection item.
     * @param selections  list of selection items
     * @return tuple-valued compound selection
     * @throws IllegalArgumentException if an argument is a
     *         tuple- or array-valued selection item
     * @since 3.2
     */
    CompoundSelection<Tuple> tuple(List<Selection<?>> selections);

    /**
     * Create an array-valued selection item.
     * @param selections  selection items
     * @return array-valued compound selection
     * @throws IllegalArgumentException if an argument is a
     *         tuple- or array-valued selection item
     */
    CompoundSelection<Object[]> array(Selection<?>... selections);

    /**
     * Create an array-valued selection item.
     * @param selections  list of selection items
     * @return array-valued compound selection
     * @throws IllegalArgumentException if an argument is a
     *         tuple- or array-valued selection item
     * @since 3.2
     */
    CompoundSelection<Object[]> array(List<Selection<?>> selections);

    //ordering:

    /**
     * Create an ordering by the ascending value of the expression.
     * @param expression  expression used to define the ordering
     * @return ascending ordering corresponding to the expression
     */
    Order asc(Expression<?> expression);

    /**
     * Create an ordering by the descending value of the expression.
     * @param expression  expression used to define the ordering
     * @return descending ordering corresponding to the expression
     */
    Order desc(Expression<?> expression);

    /**
     * Create an ordering by the ascending value of the expression.
     * @param expression  expression used to define the ordering
     * @param nullPrecedence  the precedence of null values
     * @return ascending ordering corresponding to the expression
     * @since 3.2
     */
    Order asc(Expression<?> expression, Nulls nullPrecedence);

    /**
     * Create an ordering by the descending value of the expression.
     * @param expression  expression used to define the ordering
     * @param nullPrecedence  the precedence of null values
     * @return descending ordering corresponding to the expression
     * @since 3.2
     */
    Order desc(Expression<?> expression, Nulls nullPrecedence);

    //aggregate functions:

    /**
     * Create an aggregate expression applying the avg operation.
     * @param x  expression representing input value to avg operation
     * @return avg expression
     */
    <N extends Number> Expression<Double> avg(Expression<N> x);

    /**
     * Create an aggregate expression applying the sum operation.
     * @param x  expression representing input value to sum operation
     * @return sum expression
     */
    <N extends Number> Expression<N> sum(Expression<N> x);

    /**
     * Create an aggregate expression applying the sum operation to an
     * Integer-valued expression, returning a Long result.
     * @param x  expression representing input value to sum operation
     * @return sum expression
     */
    Expression<Long> sumAsLong(Expression<Integer> x);

    /**
     * Create an aggregate expression applying the sum operation to a
     * Float-valued expression, returning a Double result.
     * @param x  expression representing input value to sum operation
     * @return sum expression
     */
    Expression<Double> sumAsDouble(Expression<Float> x);

    /**
     * Create an aggregate expression applying the numerical max 
     * operation.
     * @param x  expression representing input value to max operation
     * @return max expression
     */
    <N extends Number> Expression<N> max(Expression<N> x);

    /**
     * Create an aggregate expression applying the numerical min 
     * operation.
     * @param x  expression representing input value to min operation
     * @return min expression
     */
    <N extends Number> Expression<N> min(Expression<N> x);

    /**
     * Create an aggregate expression for finding the greatest of
     * the values (strings, dates, etc).
     * @param x  expression representing input value to greatest
     *           operation
     * @return greatest expression
     */
    <X extends Comparable<? super X>> Expression<X> greatest(Expression<X> x);

    /**
     * Create an aggregate expression for finding the least of
     * the values (strings, dates, etc).
     * @param x  expression representing input value to least
     *           operation
     * @return least expression
     */
    <X extends Comparable<? super X>> Expression<X> least(Expression<X> x);

    /**
     * Create an aggregate expression applying the count operation.
     * @param x  expression representing input value to count 
     *           operation
     * @return count expression
     */
    Expression<Long> count(Expression<?> x);

    /**
     * Create an aggregate expression applying the count distinct 
     * operation.
     * @param x  expression representing input value to 
     *        count distinct operation
     * @return count distinct expression
     */
    Expression<Long> countDistinct(Expression<?> x);

    //subqueries:

    /**
     * Create a predicate testing the existence of a subquery result.
     * @param subquery  subquery whose result is to be tested
     * @return exists predicate
     */
    Predicate exists(Subquery<?> subquery);

    /**
     * Create an all expression over the subquery results.
     * @param subquery  subquery
     * @return all expression
     */
    <Y> Expression<Y> all(Subquery<Y> subquery);

    /**
     * Create a some expression over the subquery results.
     * This expression is equivalent to an {@code any} expression.
     * @param subquery  subquery
     * @return some expression
     */
    <Y> Expression<Y> some(Subquery<Y> subquery);

    /**
     * Create an any expression over the subquery results. 
     * This expression is equivalent to a {@code some} expression.
     * @param subquery  subquery
     * @return any expression
     */
    <Y> Expression<Y> any(Subquery<Y> subquery);

    //boolean functions:

    /**
     * Create a conjunction of the given boolean expressions.
     * @param x  boolean expression
     * @param y  boolean expression
     * @return and predicate
     */
    Predicate and(Expression<Boolean> x, Expression<Boolean> y);

    /**
     * Create a conjunction of the given restriction predicates.
     * A conjunction of zero predicates is true.
     * @param restrictions  zero or more restriction predicates
     * @return and predicate
     */
    Predicate and(Predicate... restrictions);

    /**
     * Create a conjunction of the given restriction predicates.
     * A conjunction of zero predicates is true.
     * @param restrictions  a list of zero or more restriction predicates
     * @return and predicate
     * @since 3.2
     */
    Predicate and(List<Predicate> restrictions);

    /**
     * Create a disjunction of the given boolean expressions.
     * @param x  boolean expression
     * @param y  boolean expression
     * @return or predicate
     */
    Predicate or(Expression<Boolean> x, Expression<Boolean> y);

    /**
     * Create a disjunction of the given restriction predicates.
     * A disjunction of zero predicates is false.
     * @param restrictions  zero or more restriction predicates
     * @return or predicate
     */
    Predicate or(Predicate... restrictions);

    /**
     * Create a disjunction of the given restriction predicates.
     * A disjunction of zero predicates is false.
     * @param restrictions  a list of zero or more restriction predicates
     * @return or predicate
     * @since 3.2
     */
    Predicate or(List<Predicate> restrictions);

    /**
     * Create a negation of the given restriction. 
     * @param restriction  restriction expression
     * @return not predicate
     */
    Predicate not(Expression<Boolean> restriction);

    /**
     * Create a conjunction (with zero conjuncts).
     * A conjunction with zero conjuncts is true.
     * @return and predicate
     */
    Predicate conjunction();

    /**
     * Create a disjunction (with zero disjuncts).
     * A disjunction with zero disjuncts is false.
     * @return or predicate
     */
    Predicate disjunction();

    //turn Expression<Boolean> into a Predicate
    //useful for use with varargs methods

    /**
     * Create a predicate testing for a true value.
     * @param x  expression to be tested
     * @return predicate
     */
    Predicate isTrue(Expression<Boolean> x);

    /**
     * Create a predicate testing for a false value.
     * @param x  expression to be tested
     * @return predicate
     */
    Predicate isFalse(Expression<Boolean> x);

    //null tests:

    /**
     * Create a predicate to test whether the expression is null.
     * @param x expression
     * @return is-null predicate
     */
    Predicate isNull(Expression<?> x);

    /**
     * Create a predicate to test whether the expression is not null.
     * @param x expression
     * @return is-not-null predicate
     */
    Predicate isNotNull(Expression<?> x);

    //equality:

    /**
     * Create a predicate for testing the arguments for equality.
     * @param x  expression
     * @param y  expression
     * @return equality predicate
     */
    Predicate equal(Expression<?> x, Expression<?> y);

    /**
     * Create a predicate for testing the arguments for equality.
     * @param x  expression
     * @param y  object
     * @return equality predicate
     */
    Predicate equal(Expression<?> x, Object y);

    /**
     * Create a predicate for testing the arguments for inequality.
     * @param x  expression
     * @param y  expression
     * @return inequality predicate
     */
    Predicate notEqual(Expression<?> x, Expression<?> y);

    /**
     * Create a predicate for testing the arguments for inequality.
     * @param x  expression
     * @param y  object
     * @return inequality predicate
     */
    Predicate notEqual(Expression<?> x, Object y);

    //comparisons for generic (non-numeric) operands:

    /**
     * Create a predicate for testing whether the first argument is 
     * greater than the second.
     * @param x  expression
     * @param y  expression
     * @return greater-than predicate
     */
    <Y extends Comparable<? super Y>> Predicate greaterThan(Expression<? extends Y> x, Expression<? extends Y> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * greater than the second.
     * @param x  expression
     * @param y  value
     * @return greater-than predicate
     */
    <Y extends Comparable<? super Y>> Predicate greaterThan(Expression<? extends Y> x, Y y);

    /**
     * Create a predicate for testing whether the first argument is 
     * greater than or equal to the second.
     * @param x  expression
     * @param y  expression
     * @return greater-than-or-equal predicate
     */
    <Y extends Comparable<? super Y>> Predicate greaterThanOrEqualTo(Expression<? extends Y> x, Expression<? extends Y> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * greater than or equal to the second.
     * @param x  expression
     * @param y  value
     * @return greater-than-or-equal predicate
     */
    <Y extends Comparable<? super Y>> Predicate greaterThanOrEqualTo(Expression<? extends Y> x, Y y);

    /**
     * Create a predicate for testing whether the first argument is 
     * less than the second.
     * @param x  expression
     * @param y  expression
     * @return less-than predicate
     */
    <Y extends Comparable<? super Y>> Predicate lessThan(Expression<? extends Y> x, Expression<? extends Y> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * less than the second.
     * @param x  expression
     * @param y  value
     * @return less-than predicate
     */
    <Y extends Comparable<? super Y>> Predicate lessThan(Expression<? extends Y> x, Y y);

    /**
     * Create a predicate for testing whether the first argument is 
     * less than or equal to the second.
     * @param x  expression
     * @param y  expression
     * @return less-than-or-equal predicate
     */
    <Y extends Comparable<? super Y>> Predicate lessThanOrEqualTo(Expression<? extends Y> x, Expression<? extends Y> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * less than or equal to the second.
     * @param x  expression
     * @param y  value
     * @return less-than-or-equal predicate
     */
    <Y extends Comparable<? super Y>> Predicate lessThanOrEqualTo(Expression<? extends Y> x, Y y);

    /**
     * Create a predicate for testing whether the first argument is 
     * between the second and third arguments in value.
     * @param v  expression 
     * @param x  expression
     * @param y  expression
     * @return between predicate
     */
    <Y extends Comparable<? super Y>> Predicate between(Expression<? extends Y> v, Expression<? extends Y> x, Expression<? extends Y> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * between the second and third arguments in value.
     * @param v  expression 
     * @param x  value
     * @param y  value
     * @return between predicate
     */
    <Y extends Comparable<? super Y>> Predicate between(Expression<? extends Y> v, Y x, Y y);

    //comparisons for numeric operands:

    /**
     * Create a predicate for testing whether the first argument is 
     * greater than the second.
     * @param x  expression
     * @param y  expression
     * @return greater-than predicate
     */
    Predicate gt(Expression<? extends Number> x, Expression<? extends Number> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * greater than the second.
     * @param x  expression
     * @param y  value
     * @return greater-than predicate
     */
    Predicate gt(Expression<? extends Number> x, Number y);

    /**
     * Create a predicate for testing whether the first argument is 
     * greater than or equal to the second.
     * @param x  expression
     * @param y  expression
     * @return greater-than-or-equal predicate
     */
    Predicate ge(Expression<? extends Number> x, Expression<? extends Number> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * greater than or equal to the second.
     * @param x  expression
     * @param y  value
     * @return greater-than-or-equal predicate
     */        
    Predicate ge(Expression<? extends Number> x, Number y);

    /**
     * Create a predicate for testing whether the first argument is 
     * less than the second.
     * @param x  expression
     * @param y  expression
     * @return less-than predicate
     */
    Predicate lt(Expression<? extends Number> x, Expression<? extends Number> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * less than the second.
     * @param x  expression
     * @param y  value
     * @return less-than predicate
     */
    Predicate lt(Expression<? extends Number> x, Number y);

    /**
     * Create a predicate for testing whether the first argument is 
     * less than or equal to the second.
     * @param x  expression
     * @param y  expression
     * @return less-than-or-equal predicate
     */
    Predicate le(Expression<? extends Number> x, Expression<? extends Number> y);

    /**
     * Create a predicate for testing whether the first argument is 
     * less than or equal to the second.
     * @param x  expression
     * @param y  value
     * @return less-than-or-equal predicate
     */
    Predicate le(Expression<? extends Number> x, Number y);

    //numerical operations:

    /**
     * Create an expression that returns the sign of its
     * argument, that is, {@code 1} if its argument is
     * positive, {@code -1} if its argument is negative,
     * or {@code 0} if its argument is exactly zero.
     * @param x expression
     * @return sign
     */
    Expression<Integer> sign(Expression<? extends Number> x);

    /**
     * Create an expression that returns the arithmetic negation
     * of its argument.
     * @param x expression
     * @return arithmetic negation
     */
    <N extends Number> Expression<N> neg(Expression<N> x);

    /**
     * Create an expression that returns the absolute value
     * of its argument.
     * @param x expression
     * @return absolute value
     */
    <N extends Number> Expression<N> abs(Expression<N> x);

    /**
     * Create an expression that returns the ceiling of its
     * argument, that is, the smallest integer greater than
     * or equal to its argument.
     * @param x expression
     * @return ceiling
     */
    <N extends Number> Expression<N> ceiling(Expression<N> x);

    /**
     * Create an expression that returns the floor of its
     * argument, that is, the largest integer smaller than
     * or equal to its argument.
     * @param x expression
     * @return floor
     */
    <N extends Number> Expression<N> floor(Expression<N> x);
    /**
     * Create an expression that returns the sum
     * of its arguments.
     * @param x expression
     * @param y expression
     * @return sum
     */
    <N extends Number> Expression<N> sum(Expression<? extends N> x, Expression<? extends N> y);

    /**
     * Create an expression that returns the sum
     * of its arguments.
     * @param x expression
     * @param y value
     * @return sum
     */
    <N extends Number> Expression<N> sum(Expression<? extends N> x, N y);

    /**
     * Create an expression that returns the sum
     * of its arguments.
     * @param x value
     * @param y expression
     * @return sum
     */
    <N extends Number> Expression<N> sum(N x, Expression<? extends N> y);

    /**
     * Create an expression that returns the product
     * of its arguments.
     * @param x expression
     * @param y expression
     * @return product
     */
    <N extends Number> Expression<N> prod(Expression<? extends N> x, Expression<? extends N> y);

    /**
     * Create an expression that returns the product
     * of its arguments.
     * @param x expression
     * @param y value
     * @return product
     */
    <N extends Number> Expression<N> prod(Expression<? extends N> x, N y);

    /**
     * Create an expression that returns the product
     * of its arguments.
     * @param x value
     * @param y expression
     * @return product
     */
    <N extends Number> Expression<N> prod(N x, Expression<? extends N> y);

    /**
     * Create an expression that returns the difference
     * between its arguments.
     * @param x expression
     * @param y expression
     * @return difference
     */
    <N extends Number> Expression<N> diff(Expression<? extends N> x, Expression<? extends N> y);

    /**
     * Create an expression that returns the difference
     * between its arguments.
     * @param x expression
     * @param y value
     * @return difference
     */
    <N extends Number> Expression<N> diff(Expression<? extends N> x, N y);

    /**
     * Create an expression that returns the difference
     * between its arguments.
     * @param x value
     * @param y expression
     * @return difference
     */
    <N extends Number> Expression<N> diff(N x, Expression<? extends N> y);

    /**
     * Create an expression that returns the quotient
     * of its arguments.
     * @param x expression
     * @param y expression
     * @return quotient
     */
    Expression<Number> quot(Expression<? extends Number> x, Expression<? extends Number> y);

    /**
     * Create an expression that returns the quotient
     * of its arguments.
     * @param x expression
     * @param y value
     * @return quotient
     */
    Expression<Number> quot(Expression<? extends Number> x, Number y);

    /**
     * Create an expression that returns the quotient
     * of its arguments.
     * @param x value
     * @param y expression
     * @return quotient
     */
    Expression<Number> quot(Number x, Expression<? extends Number> y);

    /**
     * Create an expression that returns the modulus
     * (remainder under integer division) 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
     * (remainder under integer division) 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
     * (remainder under integer division) of its
     * arguments.
     * @param x value
     * @param y expression
     * @return modulus
     */
    Expression<Integer> mod(Integer x, Expression<Integer> y);

    /**
     * Create an expression that returns the square root
     * of its argument.
     * @param x expression
     * @return square root
     */        
    Expression<Double> sqrt(Expression<? extends Number> x);

    /**
     * Create an expression that returns the exponential
     * of its argument, that is, Euler's number <i>e</i>
     * raised to the power of its argument.
     * @param x expression
     * @return exponential
     */
    Expression<Double> exp(Expression<? extends Number> x);

    /**
     * Create an expression that returns the natural logarithm
     * of its argument.
     * @param x expression
     * @return natural logarithm
     */
    Expression<Double> ln(Expression<? extends Number> x);

    /**
     * Create an expression that returns the first argument
     * raised to the power of its second argument.
     * @param x base
     * @param y exponent
     * @return the base raised to the power of the exponent
     */
    Expression<Double> power(Expression<? extends Number> x, Expression<? extends Number> y);

    /**
     * Create an expression that returns the first argument
     * raised to the power of its second argument.
     * @param x base
     * @param y exponent
     * @return the base raised to the power of the exponent
     */
    Expression<Double> power(Expression<? extends Number> x, Number y);

    /**
     * Create an expression that returns the first argument
     * rounded to the number of decimal places given by the
     * second argument.
     * @param x base
     * @param n number of decimal places
     * @return the rounded value
     */
    <T extends Number> Expression<T> round(Expression<T> x, Integer n);

    //typecasts:

    /**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return {@literal Expression<Long>}
     */
    Expression<Long> toLong(Expression<? extends Number> number);

    /**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return {@literal Expression<Integer>}
     */
    Expression<Integer> toInteger(Expression<? extends Number> number);

    /**
     * Typecast. Returns same expression object.
     * @param number  numeric expression
     * @return {@literal Expression<Float>}
     */
    Expression<Float> toFloat(Expression<? extends Number> number);

    /**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return {@literal Expression<Double>}
     */
    Expression<Double> toDouble(Expression<? extends Number> number);

    /**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return {@literal Expression<BigDecimal>}
     */
    Expression<BigDecimal> toBigDecimal(Expression<? extends Number> number);

    /**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return {@literal Expression<BigInteger>}
     */
    Expression<BigInteger> toBigInteger(Expression<? extends Number> number);

    /**
     * Typecast.  Returns same expression object.
     * @param character expression
     * @return {@literal Expression<String>}
     */
    Expression<String> toString(Expression<Character> character);

    //literals:

    /**
     * Create an expression for a literal.
     * @param value  value represented by the expression
     * @return expression literal
     * @throws IllegalArgumentException if value is null
     */
    <T> Expression<T> literal(T value);

    /**
     * Create an expression for a null literal with the given type.
     * @param resultClass  type of the null literal
     * @return null expression literal
     */
    <T> Expression<T> nullLiteral(Class<T> resultClass);

    //parameters:

    /**
     * Create a parameter expression.
     * @param paramClass parameter class
     * @return parameter expression
     */
    <T> ParameterExpression<T> parameter(Class<T> paramClass);

    /**
     * Create a parameter expression with the given name.
     * @param paramClass parameter class
     * @param name  name that can be used to refer to 
     *              the parameter
     * @return parameter expression
     */
    <T> ParameterExpression<T> parameter(Class<T> paramClass, String name);

    //collection operations:

    /**
     * Create a predicate that tests whether a collection is empty.
     * @param collection expression
     * @return is-empty predicate
     */
    <C extends Collection<?>> Predicate isEmpty(Expression<C> collection);

    /**
     * Create a predicate that tests whether a collection is
     * not empty.
     * @param collection expression
     * @return is-not-empty predicate
     */
    <C extends Collection<?>> Predicate isNotEmpty(Expression<C> collection);

    /**
     * Create an expression that tests the size of a collection.
     * @param collection expression
     * @return size expression
     */ 
    <C extends Collection<?>> Expression<Integer> size(Expression<C> collection);

    /**
     * Create an expression that tests the size of a collection.
     * @param collection collection
     * @return size expression
     */ 
    <C extends Collection<?>> Expression<Integer> size(C collection);

    /**
     * Create a predicate that tests whether an element is
     * a member of a collection.
     * If the collection is empty, the predicate will be false.
     * @param elem element expression
     * @param collection expression
     * @return is-member predicate
     */
    <E, C extends Collection<E>> Predicate isMember(Expression<E> elem, Expression<C> collection);

    /**
     * Create a predicate that tests whether an element is
     * a member of a collection.
     * If the collection is empty, the predicate will be false.
     * @param elem element
     * @param collection expression
     * @return is-member predicate
     */
    <E, C extends Collection<E>> Predicate isMember(E elem, Expression<C> collection);

    /**
     * Create a predicate that tests whether an element is
     * not a member of a collection.
     * If the collection is empty, the predicate will be true.
     * @param elem element expression
     * @param collection expression
     * @return is-not-member predicate
     */
    <E, C extends Collection<E>> Predicate isNotMember(Expression<E> elem, Expression<C> collection);

    /**
     * Create a predicate that tests whether an element is
     * not a member of a collection.
     * If the collection is empty, the predicate will be true.
     * @param elem element
     * @param collection expression
     * @return is-not-member predicate
     */
    <E, C extends Collection<E>> Predicate isNotMember(E elem, Expression<C> collection);

    //get the values and keys collections of the Map, which may then
    //be passed to size(), isMember(), isEmpty(), etc

    /**
     * Create an expression that returns the values of a map.
     * @param map  map
     * @return collection expression
     */
    <V, M extends Map<?, V>> Expression<Collection<V>> values(M map);

    /**
     * Create an expression that returns the keys of a map.
     * @param map  map
     * @return set expression
     */
    <K, M extends Map<K, ?>> Expression<Set<K>> keys(M map);

    //string functions:

    /**
     * Create a predicate for testing whether the expression
     * satisfies the given pattern.
     * @param x  string expression
     * @param pattern  string expression
     * @return like predicate
     */
    Predicate like(Expression<String> x, Expression<String> pattern);

    /**
     * Create a predicate for testing whether the expression
     * satisfies the given pattern.
     * @param x  string expression
     * @param pattern  string 
     * @return like predicate
     */
    Predicate like(Expression<String> x, String pattern);

    /**
     * Create a predicate for testing whether the expression
     * satisfies the given pattern.
     * @param x  string expression
     * @param pattern  string expression
     * @param escapeChar  escape character expression
     * @return like predicate
     */
    Predicate like(Expression<String> x, Expression<String> pattern, Expression<Character> escapeChar);

    /**
     * Create a predicate for testing whether the expression
     * satisfies the given pattern.
     * @param x  string expression
     * @param pattern  string expression
     * @param escapeChar  escape character
     * @return like predicate
     */
    Predicate like(Expression<String> x, Expression<String> pattern, char escapeChar);

    /**
     * Create a predicate for testing whether the expression
     * satisfies the given pattern.
     * @param x  string expression
     * @param pattern  string 
     * @param escapeChar  escape character expression
     * @return like predicate
     */
    Predicate like(Expression<String> x, String pattern, Expression<Character> escapeChar);

    /**
     * Create a predicate for testing whether the expression
     * satisfies the given pattern.
     * @param x  string expression
     * @param pattern  string 
     * @param escapeChar  escape character
     * @return like predicate
     */
    Predicate like(Expression<String> x, String pattern, char escapeChar);

    /**
     * Create a predicate for testing whether the expression
     * does not satisfy the given pattern.
     * @param x  string expression
     * @param pattern  string expression
     * @return not-like predicate
     */
    Predicate notLike(Expression<String> x, Expression<String> pattern);

    /**
     * Create a predicate for testing whether the expression
     * does not satisfy the given pattern.
     * @param x  string expression
     * @param pattern  string 
     * @return not-like predicate
     */
    Predicate notLike(Expression<String> x, String pattern);

    /**
     * Create a predicate for testing whether the expression
     * does not satisfy the given pattern.
     * @param x  string expression
     * @param pattern  string expression
     * @param escapeChar  escape character expression
     * @return not-like predicate
     */
    Predicate notLike(Expression<String> x, Expression<String> pattern, Expression<Character> escapeChar);

    /**
     * Create a predicate for testing whether the expression
     * does not satisfy the given pattern.
     * @param x  string expression
     * @param pattern  string expression
     * @param escapeChar  escape character
     * @return not-like predicate
     */
    Predicate notLike(Expression<String> x, Expression<String> pattern, char escapeChar);

    /**
     * Create a predicate for testing whether the expression
     * does not satisfy the given pattern.
     * @param x  string expression
     * @param pattern  string 
     * @param escapeChar  escape character expression
     * @return not-like predicate
     */
    Predicate notLike(Expression<String> x, String pattern, Expression<Character> escapeChar);

   /**
     * Create a predicate for testing whether the expression
     * does not satisfy the given pattern.
     * @param x  string expression
     * @param pattern  string 
     * @param escapeChar  escape character
     * @return not-like predicate
     */
    Predicate notLike(Expression<String> x, String pattern, char escapeChar);

    /**
     * Create an expression for string concatenation.
     * If the given list of expressions is empty, returns
     * an expression equivalent to {@code literal("")}.
     * @param expressions  string expressions
     * @return expression corresponding to concatenation
     */
    Expression<String> concat(List<Expression<String>> expressions);

    /**
     * Create an expression for string concatenation.
     * @param x  string expression
     * @param y  string expression
     * @return expression corresponding to concatenation
     */
    Expression<String> concat(Expression<String> x, Expression<String> y);

    /**
     * Create an expression for string concatenation.
     * @param x  string expression
     * @param y  string 
     * @return expression corresponding to concatenation
     */
    Expression<String> concat(Expression<String> x, String y);

    /**
     * Create an expression for string concatenation.
     * @param x  string 
     * @param y  string expression
     * @return expression corresponding to concatenation
     */
    Expression<String> concat(String x, Expression<String> y);

    /**
     * Create an expression for substring extraction.
     * Extracts a substring starting at the specified position
     * through to end of the string.
     * First position is 1.
     * @param x  string expression
     * @param from  start position expression 
     * @return expression corresponding to substring extraction
     */
    Expression<String> substring(Expression<String> x, Expression<Integer> from);

    /**
     * Create an expression for substring extraction.
     * Extracts a substring starting at the specified position
     * through to end of the string.
     * First position is 1.
     * @param x  string expression
     * @param from  start position 
     * @return expression corresponding to substring extraction
     */
    Expression<String> substring(Expression<String> x, int from);

    /**
     * Create an expression for substring extraction.
     * Extracts a substring of given length starting at the
     * specified position.
     * First position is 1.
     * @param x  string expression
     * @param from  start position expression 
     * @param len  length expression
     * @return expression corresponding to substring extraction
     */
    Expression<String> substring(Expression<String> x, Expression<Integer> from, Expression<Integer> len);

    /**
     * Create an expression for substring extraction.
     * Extracts a substring of given length starting at the
     * specified position.
     * First position is 1.
     * @param x  string expression
     * @param from  start position 
     * @param len  length
     * @return expression corresponding to substring extraction
     */
    Expression<String> substring(Expression<String> x, int from, int len);

    /**
     * Used to specify how strings are trimmed.
     */
    enum Trimspec {

        /**
         * Trim from leading end.
         */
        LEADING,

        /**
         * Trim from trailing end.
         */
        TRAILING, 

        /**
         * Trim from both ends.
         */
        BOTH 
    }

    /**
     * Create expression to trim blanks from both ends of
     * a string.
     * @param x  expression for string to trim
     * @return trim expression
     */
    Expression<String> trim(Expression<String> x);

    /**
     * Create expression to trim blanks from a string.
     * @param ts  trim specification
     * @param x  expression for string to trim
     * @return trim expression
     */
    Expression<String> trim(Trimspec ts, Expression<String> x);

    /**
     * Create expression to trim character from both ends of
     * a string.
     * @param t  expression for character to be trimmed
     * @param x  expression for string to trim
     * @return trim expression
     */
    Expression<String> trim(Expression<Character> t, Expression<String> x);

    /**
     * Create expression to trim character from a string.
     * @param ts  trim specification
     * @param t  expression for character to be trimmed
     * @param x  expression for string to trim
     * @return trim expression
     */
    Expression<String> trim(Trimspec ts, Expression<Character> t, Expression<String> x);

    /**
     * Create expression to trim character from both ends of
     * a string.
     * @param t  character to be trimmed
     * @param x  expression for string to trim
     * @return trim expression
     */
    Expression<String> trim(char t, Expression<String> x);

    /**
     * Create expression to trim character from a string.
     * @param ts  trim specification
     * @param t  character to be trimmed
     * @param x  expression for string to trim
     * @return trim expression
     */
    Expression<String> trim(Trimspec ts, char t, Expression<String> x);

    /**
     * Create expression for converting a string to lowercase.
     * @param x  string expression
     * @return expression to convert to lowercase
     */
    Expression<String> lower(Expression<String> x);

    /**
     * Create expression for converting a string to uppercase.
     * @param x  string expression
     * @return expression to convert to uppercase
     */
    Expression<String> upper(Expression<String> x);

    /**
     * Create expression to return length of a string.
     * @param x  string expression
     * @return length expression
     */
    Expression<Integer> length(Expression<String> x);

    /**
     * Create an expression for the leftmost substring of a string,
     * @param x  string expression
     * @param len  length of the substring to return
     * @return expression for the leftmost substring
     */
    Expression<String> left(Expression<String> x, int len);

    /**
     * Create an expression for the rightmost substring of a string,
     * @param x  string expression
     * @param len  length of the substring to return
     * @return expression for the rightmost substring
     */
    Expression<String> right(Expression<String> x, int len);

    /**
     * Create an expression for the leftmost substring of a string,
     * @param x  string expression
     * @param len  length of the substring to return
     * @return expression for the leftmost substring
     */
    Expression<String> left(Expression<String> x, Expression<Integer> len);

    /**
     * Create an expression for the rightmost substring of a string,
     * @param x  string expression
     * @param len  length of the substring to return
     * @return expression for the rightmost substring
     */
    Expression<String> right(Expression<String> x, Expression<Integer> len);

    /**
     * Create an expression replacing every occurrence of a substring
     * within a string.
     * @param x  string expression
     * @param substring  the literal substring to replace
     * @param replacement  the replacement string
     * @return expression for the resulting string
     */
    Expression<String> replace(Expression<String> x, Expression<String> substring, Expression<String> replacement);

    /**
     * Create an expression replacing every occurrence of a substring
     * within a string.
     * @param x  string expression
     * @param substring  the literal substring to replace
     * @param replacement  the replacement string
     * @return expression for the resulting string
     */
    Expression<String> replace(Expression<String> x, String substring, Expression<String> replacement);

    /**
     * Create an expression replacing every occurrence of a substring
     * within a string.
     * @param x  string expression
     * @param substring  the literal substring to replace
     * @param replacement  the replacement string
     * @return expression for the resulting string
     */
    Expression<String> replace(Expression<String> x, Expression<String> substring, String replacement);

    /**
     * Create an expression replacing every occurrence of a substring
     * within a string.
     * @param x  string expression
     * @param substring  the literal substring to replace
     * @param replacement  the replacement string
     * @return expression for the resulting string
     */
    Expression<String> replace(Expression<String> x, String substring, String replacement);

    /**
     * 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.
     * <p><strong>Warning:</strong> the order of the parameters
     * of this method is reversed compared to the corresponding
     * function in JPQL.
     * @param x  expression for string to be searched
     * @param pattern  expression for string to be located
     * @return expression corresponding to position
     */
    Expression<Integer> locate(Expression<String> x, Expression<String> pattern);

    /**
     * Create expression to locate the position of one string
     * within another, returning position of first character
     * if found.
     * The first position in a string is denoted by 1.  If the
     * string to be located is not found, 0 is returned.
     * <p><strong>Warning:</strong> the order of the parameters
     * of this method is reversed compared to the corresponding
     * function in JPQL.
     * @param x  expression for string to be searched
     * @param pattern  string to be located
     * @return expression corresponding to position
     */
    Expression<Integer> locate(Expression<String> x, String pattern);

    /**
     * Create expression to locate the position of one string
     * within another, returning position of first character
     * if found.
     * The first position in a string is denoted by 1.  If the
     * string to be located is not found, 0 is returned.
     * <p><strong>Warning:</strong> the order of the first two
     * parameters of this method is reversed compared to the
     * corresponding function in JPQL.
     * @param x  expression for string to be searched
     * @param pattern  expression for string to be located
     * @param from  expression for position at which to start search
     * @return expression corresponding to position
     */
    Expression<Integer> locate(Expression<String> x, Expression<String> pattern, Expression<Integer> from);

    /**
     * Create expression to locate the position of one string
     * within another, returning position of first character
     * if found.
     * The first position in a string is denoted by 1.  If the
     * string to be located is not found, 0 is returned.
     * <p><strong>Warning:</strong> the order of the first two
     * parameters of this method is reversed compared to the
     * corresponding function in JPQL.
     * @param x  expression for string to be searched
     * @param pattern  string to be located
     * @param from  position at which to start search
     * @return expression corresponding to position
     */        
    Expression<Integer> locate(Expression<String> x, String pattern, int from);

    // Date/time/timestamp functions:

    /**
     * Create expression to return current date.
     * @return expression for current date
     */
    Expression<java.sql.Date> currentDate();

    /**
     * Create expression to return current timestamp.
     * @return expression for current timestamp
     */        
    Expression<java.sql.Timestamp> currentTimestamp();

    /**
     * Create expression to return current time.
     * @return expression for current time
     */        
    Expression<java.sql.Time> currentTime();

    /**
     * Create expression to return current local date.
     * @return expression for current date
     */
    Expression<java.time.LocalDate> localDate();

    /**
     * Create expression to return current local datetime.
     * @return expression for current timestamp
     */
    Expression<java.time.LocalDateTime> localDateTime();

    /**
     * Create expression to return current local time.
     * @return expression for current time
     */
    Expression<java.time.LocalTime> localTime();

    /**
     * Create an expression that returns the value of a
     * field extracted from a date, time, or datetime.
     * @param field a temporal field type
     * @param temporal a date, time, or datetime
     * @return expression for the value of the extracted field
     * @since 3.2
     */
    <N,T extends Temporal> Expression<N> extract(TemporalField<N,T> field, Expression<T> temporal);

    //in builders:

    /**
     * Interface used to build in predicates.
     */
    interface In<T> extends Predicate {

         /**
          * Return the expression to be tested against the
          * list of values.
          * @return expression
          */
         Expression<T> getExpression();

         /**
          * Add to list of values to be tested against.
          * @param value value
          * @return in predicate
          */
         In<T> value(T value);

         /**
          * Add to list of values to be tested against.
          * @param value expression
          * @return in predicate
          */
         In<T> value(Expression<? extends T> value);
     }

    /**
     * Create predicate to test whether given expression
     * is contained in a list of values.
     * @param  expression to be tested against list of values
     * @return  in predicate
     */
    <T> In<T> in(Expression<? extends T> expression);

    // coalesce, nullif:

    /**
     * Create an expression that returns null if all its arguments
     * evaluate to null, and the value of the first non-null argument
     * otherwise.
     * @param x expression
     * @param y expression
     * @return coalesce expression
     */
    <Y> Expression<Y> coalesce(Expression<? extends Y> x, Expression<? extends Y> y);

    /**
     * Create an expression that returns null if all its arguments
     * evaluate to null, and the value of the first non-null argument
     * otherwise.
     * @param x expression
     * @param y value
     * @return coalesce expression
     */
    <Y> Expression<Y> coalesce(Expression<? extends Y> x, Y y);

    /**
     * Create an expression that tests whether its argument are
     * equal, returning null if they are and the value of the
     * first expression if they are not.
     * @param x expression
     * @param y expression
     * @return nullif expression
     */
    <Y> Expression<Y> nullif(Expression<Y> x, Expression<?> y);

    /**
     * Create an expression that tests whether its argument are
     * equal, returning null if they are and the value of the
     * first expression if they are not.
     * @param x expression
     * @param y value
     * @return nullif expression 
     */
    <Y> Expression<Y> nullif(Expression<Y> x, Y y);

    // coalesce builder:

    /**
     * Interface used to build coalesce expressions.  
     *  
     * A coalesce expression is equivalent to a case expression
     * that returns null if all its arguments evaluate to null,
     * and the value of its first non-null argument otherwise.
     */
    interface Coalesce<T> extends Expression<T> {

         /**
          * Add an argument to the coalesce expression.
          * @param value  value
          * @return coalesce expression
          */
         Coalesce<T> value(T value);

         /**
          * Add an argument to the coalesce expression.
          * @param value expression
          * @return coalesce expression
          */
         Coalesce<T> value(Expression<? extends T> value);
        }

    /**
     * Create a coalesce expression.
     * @return coalesce expression
     */
    <T> Coalesce<T> coalesce();

    //case builders:

    /**
     * Interface used to build simple case expressions.
     * Case conditions are evaluated in the order in which
     * they are specified.
     */
    interface SimpleCase<C,R> extends Expression<R> {

                /**
                 * Return the expression to be tested against the
                 * conditions.
                 * @return expression
                 */
                Expression<C> getExpression();

                /**
                 * Add a when/then clause to the case expression.
                 * @param condition  "when" condition
                 * @param result  "then" result value
                 * @return simple case expression
                 */
                SimpleCase<C, R> when(C condition, R result);

                /**
                 * Add a when/then clause to the case expression.
                 * @param condition  "when" condition
                 * @param result  "then" result expression
                 * @return simple case expression
                 */
                SimpleCase<C, R> when(C condition, Expression<? extends R> result);

                /**
                 * Add a when/then clause to the case expression.
                 * @param condition  "when" condition
                 * @param result  "then" result value
                 * @return simple case expression
                 */
                SimpleCase<C, R> when(Expression<? extends C> condition, R result);

                /**
                 * Add a when/then clause to the case expression.
                 * @param condition  "when" condition
                 * @param result  "then" result expression
                 * @return simple case expression
                 */
                SimpleCase<C, R> when(Expression<? extends C> condition, Expression<? extends R> result);

                /**
                 * Add an "else" clause to the case expression.
                 * @param result  "else" result
                 * @return expression
                 */
                Expression<R> otherwise(R result);

                /**
                 * Add an "else" clause to the case expression.
                 * @param result  "else" result expression
                 * @return expression
                 */
                Expression<R> otherwise(Expression<? extends R> result);
        }

    /**
     * Create a simple case expression.
     * @param expression  to be tested against the case conditions
     * @return simple case expression
     */
    <C, R> SimpleCase<C,R> selectCase(Expression<? extends C> expression);

    /**
     * Interface used to build general case expressions.
     * Case conditions are evaluated in the order in which
     * they are specified.
     */
    interface Case<R> extends Expression<R> {

                /**
                 * Add a when/then clause to the case expression.
                 * @param condition  "when" condition
                 * @param result  "then" result value
                 * @return general case expression
                 */
                Case<R> when(Expression<Boolean> condition, R result);

                /**
                 * Add a when/then clause to the case expression.
                 * @param condition  "when" condition
                 * @param result  "then" result expression
                 * @return general case expression
                 */
                Case<R> when(Expression<Boolean> condition, Expression<? extends R> result);

                /**
                 * Add an "else" clause to the case expression.
                 * @param result  "else" result
                 * @return expression
                 */
                Expression<R> otherwise(R result);

                /**
                 * Add an "else" clause to the case expression.
                 * @param result  "else" result expression
                 * @return expression
                 */
                Expression<R> otherwise(Expression<? extends R> result);
        }

    /**
     * Create a general case expression.
     * @return general case expression
     */
    <R> Case<R> selectCase();

    /**
     * Create an expression for the execution of a database
     * function.
     * @param name  function name
     * @param type  expected result type
     * @param args  function arguments
     * @return expression
     */
   <T> Expression<T> function(String name, Class<T> type,
Expression<?>... args);

    // methods for downcasting:

    /**
     * Downcast Join object to the specified type.
     * @param join  Join object
     * @param type type to be downcast to
     * @return  Join object of the specified type
     * @since 2.1
     */
    <X, T, V extends T> Join<X, V> treat(Join<X, T> join, Class<V> type);

    /**
     * Downcast CollectionJoin object to the specified type.
     * @param join  CollectionJoin object
     * @param type type to be downcast to
     * @return  CollectionJoin object of the specified type
     * @since 2.1
     */
    <X, T, E extends T> CollectionJoin<X, E> treat(CollectionJoin<X, T> join, Class<E> type);

    /**
     * Downcast SetJoin object to the specified type.
     * @param join  SetJoin object
     * @param type type to be downcast to
     * @return  SetJoin object of the specified type
     * @since 2.1
     */
    <X, T, E extends T> SetJoin<X, E> treat(SetJoin<X, T> join, Class<E> type);

    /**
     * Downcast ListJoin object to the specified type.
     * @param join  ListJoin object
     * @param type type to be downcast to
     * @return  ListJoin object of the specified type
     * @since 2.1
     */
    <X, T, E extends T> ListJoin<X, E> treat(ListJoin<X, T> join, Class<E> type);

    /**
     * Downcast MapJoin object to the specified type.
     * @param join  MapJoin object
     * @param type type to be downcast to
     * @return  MapJoin object of the specified type
     * @since 2.1
     */
    <X, K, T, V extends T> MapJoin<X, K, V> treat(MapJoin<X, K, T> join, Class<V> type);

    /**
     * Downcast Path object to the specified type.
     * @param path  path
     * @param type type to be downcast to
     * @return  Path object of the specified type
     * @since 2.1
     */
    <X, T extends X> Path<T> treat(Path<X> path, Class<T> type);

    /**
     * Downcast Root object to the specified type.
     * @param root  root
     * @param type type to be downcast to
     * @return  Root object of the specified type
     * @since 2.1
     */
    <X, T extends X> Root<T> treat(Root<X> root, Class<T> type);

    /**
     * Create a query which is the union of the given queries.
     * @return a new criteria query which returns the union of
     *         the results of the given queries
     * @since 3.2
     */
    <T> CriteriaSelect<T> union(CriteriaSelect<? extends T> left, CriteriaSelect<? extends T> right);

    /**
     * Create a query which is the union of the given queries,
     * without elimination of duplicate results.
     * @return a new criteria query which returns the union of
     *         the results of the given queries
     * @since 3.2
     */
    <T> CriteriaSelect<T> unionAll(CriteriaSelect<? extends T> left, CriteriaSelect<? extends T> right);

    /**
     * Create a query which is the intersection of the given queries.
     * @return a new criteria query which returns the intersection of
     *         the results of the given queries
     * @since 3.2
     */
    <T> CriteriaSelect<T> intersect(CriteriaSelect<? super T> left, CriteriaSelect<? super T> right);

    /**
     * Create a query which is the intersection of the given queries,
     * without elimination of duplicate results.
     * @return a new criteria query which returns the intersection of
     *         the results of the given queries
     * @since 3.2
     */
    <T> CriteriaSelect<T> intersectAll(CriteriaSelect<? super T> left, CriteriaSelect<? super T> right);

    /**
     * Create a query by (setwise) subtraction of the second query
     * from the first query.
     * @return a new criteria query which returns the result of
     *         subtracting the results of the second query from the
     *         results of the first query
     * @since 3.2
     */
    <T> CriteriaSelect<T> except(CriteriaSelect<T> left, CriteriaSelect<?> right);

    /**
     * Create a query by (setwise) subtraction of the second query
     * from the first query, without elimination of duplicate results.
     * @return a new criteria query which returns the result of
     *         subtracting the results of the second query from the
     *         results of the first query
     * @since 3.2
     */
    <T> CriteriaSelect<T> exceptAll(CriteriaSelect<T> left, CriteriaSelect<?> right);
}
import jakarta.persistence.metamodel.EntityType;

/**
 * The {@code CriteriaDelete} interface defines functionality for 
 * performing bulk delete operations using the Criteria API
 *
 * Criteria API bulk delete operations map directly to database 
 * delete operations. The persistence context is not synchronized 
 * with the result of the bulk delete.
 *
 * A {@code CriteriaDelete} object must have a single root.
 *
 * @param <T> the entity type that is the target of the DELETE
 *
 * @since 2.1
 */
public interface CriteriaDelete<T> extends CommonAbstractCriteria {

    /**
     * Create and add a query root corresponding to the entity
     * that is the target of the DELETE.
     * A {@code CriteriaDelete} object has a single root, the entity that
     * is being deleted.
     * @param entityClass  the entity class
     * @return query root corresponding to the given entity
     */
    Root<T> from(Class<T> entityClass);

    /**
     * Create and add a query root corresponding to the entity
     * that is the target of the DELETE.
     * A {@code CriteriaDelete} object has a single root, the entity that
     * is being deleted.
     * @param entity  metamodel entity representing the entity
     *                of type X
     * @return query root corresponding to the given entity
     */
    Root<T> from(EntityType<T> entity);

   /**
    * Return the query root.
    * @return the query root
    */
   Root<T> getRoot();

    /**
     * Modify the DELETE query to restrict the target of the deletion 
     * 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 delete query
     */    
   CriteriaDelete<T> where(Expression<Boolean> restriction);

    /**
     * Modify the DELETE query to restrict the target of the deletion
     * 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 delete query
     */
   CriteriaDelete<T> where(Predicate... restrictions);

}
package jakarta.persistence.criteria;

import jakarta.persistence.Tuple;

import java.util.List;

/**
 * The {@code CriteriaQuery} interface defines functionality that is
 * specific to top-level queries.
 *
 * @param <T> the type of the defined result
 *
 * @since 2.0
 */
public interface CriteriaQuery<T> extends AbstractQuery<T>, CriteriaSelect<T> {

    /**
     * Specify the item that is to be returned in the query result.
     * Replaces the previously specified selection(s), if any.
     * 
     * <p> Note: Applications using the string-based API may need to
     * specify the type of the select item when it results from
     * a get or join operation and the query result type is 
     * specified. 
     *
     * <p>For example:
     * {@snippet :
     * CriteriaQuery<String> q = cb.createQuery(String.class);
     * Root<Order> order = q.from(Order.class);
     * q.select(order.get("shippingAddress").<String>get("state"));
     * 
     * CriteriaQuery<Product> q2 = cb.createQuery(Product.class);
     * q2.select(q2.from(Order.class)
     *             .join("items")
     *             .<Item, Product>join("product"));
     * }
     *
     * @param selection  selection specifying the item that is
     *                   to be returned in the query result
     * @return the modified query
     * @throws IllegalArgumentException if the selection is
     *         a compound selection and more than one selection
     *         item has the same assigned alias
     */
    CriteriaQuery<T> select(Selection<? extends T> selection);

    /**
     * Specify the selection items that are to be returned in the query result.
     * Replaces the previously specified selection(s), if any.
     *
     * <p> The type of the result of the query execution depends on the specification
     * of the type of the criteria query object created as well as the arguments
     * to the {@code multiselect} method.
     *
     * <p> An argument to the multiselect method must not be a tuple- or array-valued
     * compound selection item.
     *
     * <p>The semantics of this method are as follows: 
     * <ul> 
     * <li> 
     * If the type of the criteria query is {@code CriteriaQuery<Tuple>}
     * (i.e., a criteria query object created by either the {@code createTupleQuery}
     * method or by passing a {@link Tuple} class argument to the {@code createQuery}
     * method), a {@link Tuple} object corresponding to the arguments of the
     * {@code multiselect} method, in the specified order, will be instantiated and
     * returned for each row that results from the query execution.
     *
     * <li> If the type of the criteria query is {@code CriteriaQuery<X>}
     * for some user-defined class X (i.e., a criteria query object created by
     * passing a X class argument to the {@code createQuery} method), the arguments
     * to the {@code multiselect} method will be passed to the X constructor and an
     * instance of type X will be returned for each row.
     *
     * <li> If the type of the criteria query is {@code CriteriaQuery<X[]>}
     * for some class X, an instance of type {@code X[]} will be returned for each row.
     * The elements of the array will correspond to the arguments of the
     * {@code multiselect} method, in the specified order.
     *
     * <li> If the type of the criteria query is {@code CriteriaQuery<Object>}
     * or if the criteria query was created without specifying a type, and only a single
     * argument is passed to the {@code multiselect} method, an instance of type
     * {@code Object} will be returned for each row.
     *
     * <li> If the type of the criteria query is {@code CriteriaQuery<Object>}
     * or if the criteria query was created without specifying a type, and more than one
     * argument is passed to the {@code multiselect} method, an instance of type
     * {@code Object[]} will be instantiated and returned for each row.  The elements of
     * the array will correspond to the arguments to the {@code multiselect} method, in
     * the specified order.
     * </ul>
     *
     * @param selections  selection items corresponding to the
     *                    results to be returned by the query
     * @return the modified query
     * @throws IllegalArgumentException if a selection item is
     *         not valid or if more than one selection item has
     *         the same assigned alias
     *
     * @deprecated Since this method is not typesafe, the use of
     * {@link CriteriaBuilder#array} or {@link CriteriaBuilder#tuple}
     * with {@link #select} is strongly preferred.
     */
    @Deprecated(since = "3.2")
    CriteriaQuery<T> multiselect(Selection<?>... selections);

    /**
     * Specify the selection items that are to be returned in the query result.
     * Replaces the previously specified selection(s), if any.
     *
     * <p> The type of the result of the query execution depends on the specification
     * of the type of the criteria query object created as well as the argument to the
     * {@code multiselect} method. An element of the list passed to the {@code multiselect}
     * method must not be a tuple- or array-valued compound selection item.
     *
     * <p> The semantics of this method are as follows:
     * <ul>
     * <li> If the type of the criteria query is {@code CriteriaQuery<Tuple>}
     * (i.e., a criteria query object created by either the {@code createTupleQuery}
     * method or by passing a {@link Tuple} class argument to the {@code createQuery}
     * method), a {@code Tuple} object corresponding to the elements of the list passed
     * to the {@code multiselect} method, in the specified order, will be instantiated
     * and returned for each row that results from the query execution.
     *
     * <li> If the type of the criteria query is {@code CriteriaQuery<X>}
     * for some user-defined class X (i.e., a criteria query object created by passing
     * a X class argument to the {@code createQuery} method), the elements of the list
     * passed to the {@code multiselect} method will be passed to the X constructor
     * and an instance of type X will be returned for each row.
     *
     * <li> If the type of the criteria query is {@code CriteriaQuery<X[]>}
     * for some class X, an instance of type {@code X[]} will be returned for
     * each row. The elements of the array will correspond to the elements of
     * the list passed to the {@code multiselect} method, in the specified order.
     *
     * <li> If the type of the criteria query is {@code CriteriaQuery<Object>}
     * or if the criteria query was created without specifying a type, and the list
     * passed to the {@code multiselect} method contains only a single element, an
     * instance of type {@code Object} will be returned for each row.
     *
     * <li> If the type of the criteria query is {@code CriteriaQuery<Object>}
     * or if the criteria query was created without specifying a type, and the list
     * passed to the {@code multiselect} method contains more than one element, an
     * instance of type {@code Object[]} will be instantiated and returned for each row.
     * The elements of the array will correspond to the elements of the list passed to
     * the {@code multiselect} method, in the specified order.
     * </ul>
     *
     * @param selectionList  list of selection items corresponding
     *                       to the results to be returned by the
     *                       query
     * @return the modified query
     * @throws IllegalArgumentException if a selection item is
     *         not valid or if more than one selection item has
     *         the same assigned alias
     *
     * @deprecated Since this method is not typesafe, the use of
     * {@link CriteriaBuilder#array} or {@link CriteriaBuilder#tuple}
     * with {@link #select} is strongly preferred.
     */
    @Deprecated(since = "3.2")
    CriteriaQuery<T> multiselect(List<Selection<?>> selectionList);

    /**
     * Modify the query to restrict the query result according
     * to the specified boolean expression.
     * Replaces the previously added restriction(s), if any.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param restriction  a simple or compound boolean expression
     * @return the modified query
     */
    CriteriaQuery<T> where(Expression<Boolean> restriction);

    /**
     * Modify the query to restrict the query result according 
     * to the conjunction of the specified restriction predicates.
     * Replaces the previously added restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param restrictions  zero or more restriction predicates
     * @return the modified query
     */
    CriteriaQuery<T> where(Predicate... restrictions);

    /**
     * Modify the query to restrict the query result according
     * to the conjunction of the specified restriction predicates.
     * Replaces the previously added restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * This method only overrides the return type of the
     * corresponding {@code AbstractQuery} method.
     * @param restrictions  a list of zero or more restriction predicates
     * @return the modified query
     * @since 3.2
     */
    CriteriaQuery<T> where(List<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 {@code AbstractQuery} method.
     * @param grouping  zero or more grouping expressions
     * @return the modified query
     */
    CriteriaQuery<T> groupBy(Expression<?>... grouping);

    /**
     * Specify the expressions that are used to form groups over
     * the query results.
     * Replaces the previous specified grouping expressions, if any.
     * If no grouping expressions are specified, any previously 
     * added grouping expressions are simply removed.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param grouping  list of zero or more grouping expressions
     * @return the modified query
     */
    CriteriaQuery<T> groupBy(List<Expression<?>> grouping);

    /**
     * Specify a restriction over the groups of the query.
     * Replaces the previous having restriction(s), if any.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param restriction  a simple or compound boolean expression
     * @return the modified query
     */
    CriteriaQuery<T> having(Expression<Boolean> restriction);

    /**
     * Specify restrictions over the groups of the query
     * according the conjunction of the specified restriction 
     * predicates.
     * Replaces the previously added having restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param restrictions  zero or more restriction predicates
     * @return the modified query
     */
    CriteriaQuery<T> having(Predicate... restrictions);

    /**
     * Specify restrictions over the groups of the query
     * according the conjunction of the specified restriction
     * predicates.
     * Replaces the previously added having restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * This method only overrides the return type of the
     * corresponding {@code AbstractQuery} method.
     * @param restrictions  a list of zero or more restriction predicates
     * @return the modified query
     * @since 3.2
     */
    CriteriaQuery<T> having(List<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 the
     * highest precedence.
     * @param o  zero or more ordering expressions
     * @return the modified query
     */
    CriteriaQuery<T> orderBy(Order... o);

    /**
     * Specify the ordering expressions that are used to
     * order the query results.
     * Replaces the previous ordering expressions, if any.
     * If no ordering expressions are specified, the previous
     * ordering, if any, is simply removed, and results will
     * be returned in no particular order.
     * The order of the ordering expressions in the list
     * determines the precedence, whereby the first element in
     * the list has the highest precedence.
     * @param o  list of zero or more ordering expressions
     * @return the modified query
     */
    CriteriaQuery<T> orderBy(List<Order> o);

    /**
     * Specify whether duplicate query results are eliminated.
     * A true value will cause duplicates to be eliminated.
     * A false value will cause duplicates to be retained.
     * If distinct has not been specified, duplicate results must
     * be retained.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param distinct  boolean value specifying whether duplicate
     *        results must be eliminated from the query result or
     *        whether they must be retained
     * @return the modified query.
     */
    CriteriaQuery<T> distinct(boolean distinct);

    /**
     * Return the ordering expressions in order of precedence.
     * Returns empty list if no ordering expressions have been
     * specified.
     * Modifications to the list do not affect the query.
     * @return the list of ordering expressions
     */
    List<Order> getOrderList();
}
/**
 * Abstracts over {@linkplain CriteriaQuery top-level queries} and
 * {@linkplain CriteriaBuilder#union unions} and
 * {@linkplain CriteriaBuilder#intersect intersections} of top-level
 * queries.
 *
 * @param <T>  the type returned by the query
 *
 * @since 3.2
 */
public interface CriteriaSelect<T> {
}
import jakarta.persistence.metamodel.SingularAttribute;
import jakarta.persistence.metamodel.EntityType;

/**
 * The {@code CriteriaUpdate} interface defines functionality for
 * performing bulk update operations using the Criteria API.
 *
 * Criteria API bulk update operations map directly to database
 * update operations, bypassing any optimistic locking checks.
 * Portable applications using bulk update operations must manually
 * update the value of the version column, if desired, and/or manually
 * validate the value of the version column. The persistence context
 * is not automatically synchronized with the result of the bulk update.
 *
 * A {@code CriteriaUpdate} object must have a single root.
 *
 * @param <T> the entity type that is the target of the update
 *
 * @since 2.1
 */
public interface CriteriaUpdate<T> extends CommonAbstractCriteria {

   /**
    * Create and add a query root corresponding to the entity
    * that is the target of the update.
    * A {@code CriteriaUpdate} object has a single root, the
    * entity that is being updated.
    * @param entityClass  the entity class
    * @return query root corresponding to the given entity
    */
   Root<T> from(Class<T> entityClass);

   /**
    * Create and add a query root corresponding to the entity
    * that is the target of the update.
    * A {@code CriteriaUpdate} object has a single root, the
    * entity that is being updated.
    * @param entity  metamodel entity representing the entity
    *                of type X
    * @return query root corresponding to the given entity
    */
   Root<T> from(EntityType<T> entity);

   /**
    * Return the query root.
    * @return the query root
    */
   Root<T> getRoot();

   /**
    * Update the value of the specified attribute.
    * @param attribute  attribute to be updated
    * @param value  new value
    * @return  the modified update query
    */
   <Y, X extends Y> CriteriaUpdate<T> set( SingularAttribute<? super T, Y> attribute, X value);

   /**
    * Update the value of the specified attribute.
    * @param attribute  attribute to be updated
    * @param value  new value
    * @return  the modified update query
    */
   <Y> CriteriaUpdate<T> set( SingularAttribute<? super T, Y> attribute, Expression<? extends Y> value);

   /**
    * Update the value of the specified attribute.
    * @param attribute  attribute to be updated
    * @param value  new value
    * @return  the modified update query
    */
   <Y, X extends Y> CriteriaUpdate<T> set(Path<Y> attribute, X value);

   /**
    * Update the value of the specified attribute.
    * @param attribute  attribute to be updated
    * @param value  new value
    * @return  the modified update query
    */
   <Y> CriteriaUpdate<T> set(Path<Y> attribute, Expression<? extends Y> value);

   /**
    * Update the value of the specified attribute.
    * @param attributeName  name of the attribute to be updated
    * @param value  new value
    * @return  the modified update query
    */
   CriteriaUpdate<T> set(String attributeName, Object value);

    /**
     * Modify the update query to restrict the target of the
     * update 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 update query
     */    
   CriteriaUpdate<T> where(Expression<Boolean> restriction);

    /**
     * Modify the update query to restrict the target of the
     * update 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 update query
     */
   CriteriaUpdate<T> where(Predicate... restrictions);
}
package jakarta.persistence.criteria;

import java.util.List;
import java.util.Set;
import jakarta.persistence.metamodel.EntityType;

/**
 * The {@code AbstractQuery} interface defines functionality that is common
 * to both top-level queries and subqueries.
 * It is not intended to be used directly in query construction.
 *
 * All queries must have:
 * a set of root entities (which may in turn own joins).
 * All queries may have:
 * a conjunction of restrictions.
 *
 * @param <T> the type of the result
 *
 * @since 2.0
 */
public interface AbstractQuery<T> extends CommonAbstractCriteria {

    /**
     * Create and add a query root corresponding to the given entity,
     * forming a cartesian product with any existing roots.
     * @param entityClass  the entity class
     * @return query root corresponding to the given entity
     */
    <X> Root<X> from(Class<X> entityClass);

    /**
     * Create and add a query root corresponding to the given entity,
     * forming a cartesian product with any existing roots.
     * @param entity  metamodel entity representing the entity
     *                of type X
     * @return query root corresponding to the given entity
     */
    <X> Root<X> from(EntityType<X> entity);

    /**
     * Modify the query to restrict the query results according
     * to the specified boolean expression.
     * Replaces the previously added restriction(s), if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified query
     */    
    AbstractQuery<T> where(Expression<Boolean> restriction);

    /**
     * Modify the query to restrict the query results according 
     * to the conjunction of the specified restriction predicates.
     * Replaces the previously added restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * @param restrictions  zero or more restriction predicates
     * @return the modified query
     */
    AbstractQuery<T> where(Predicate... restrictions);

    /**
     * Modify the query to restrict the query 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.
     * @param restrictions  a list of zero or more restriction predicates
     * @return the modified query
     * @since 3.2
     */
    AbstractQuery<T> where(List<Predicate> restrictions);

    /**
     * Specify the expressions that are used to form groups over
     * the query results.
     * Replaces the previous specified grouping expressions, if any.
     * If no grouping expressions are specified, any previously 
     * added grouping expressions are simply removed.
     * @param grouping  zero or more grouping expressions
     * @return the modified query
     */
    AbstractQuery<T> groupBy(Expression<?>... grouping);

    /**
     * Specify the expressions that are used to form groups over
     * the query results.
     * Replaces the previous specified grouping expressions, if any.
     * If no grouping expressions are specified, any previously 
     * added grouping expressions are simply removed.
     * @param grouping  list of zero or more grouping expressions
     * @return the modified query
     */
    AbstractQuery<T> groupBy(List<Expression<?>> grouping);

    /**
     * Specify a restriction over the groups of the query.
     * Replaces the previous having restriction(s), if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified query
     */
    AbstractQuery<T> having(Expression<Boolean> restriction);

    /**
     * Specify restrictions over the groups of the query
     * according the conjunction of the specified restriction 
     * predicates.
     * Replaces the previously having added restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * @param restrictions  zero or more restriction predicates
     * @return the modified query
     */
    AbstractQuery<T> having(Predicate... restrictions);

    /**
     * Specify restrictions over the groups of the query
     * according the conjunction of the specified restriction
     * predicates.
     * Replaces the previously added having restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * @param restrictions  a list of zero or more restriction predicates
     * @return the modified query
     * @since 3.2
     */
    AbstractQuery<T> having(List<Predicate> restrictions);

    /**
     * Specify whether duplicate query results are eliminated.
     * A true value will cause duplicates to be eliminated.
     * A false value will cause duplicates to be retained.
     * If distinct has not been specified, duplicate results must
     * be retained.
     * @param distinct  boolean value specifying whether duplicate
     *        results must be eliminated from the query result or
     *        whether they must be retained
     * @return the modified query
     */
    AbstractQuery<T> distinct(boolean distinct);

    /**
     * Return the query roots. These are the roots that are
     * defined for the {@link CriteriaQuery} or {@link Subquery}
     * itself, including any subquery roots defined as a result of
     * correlation. Returns an empty set if no roots have been
     * defined. Modifications to the set do not affect the query.
     * @return the set of query roots
     */   
    Set<Root<?>> getRoots();

    /**
     * Return the selection of the query, or null if no selection
     * has been set.
     * @return selection item 
     */
    Selection<T> getSelection();

    /**
     * Return a list of the grouping expressions.  Returns empty
     * list if no grouping expressions have been specified.
     * Modifications to the list do not affect the query.
     * @return the list of grouping expressions
     */
    List<Expression<?>> getGroupList();

    /**
     * Return the predicate that corresponds to the restriction(s)
     * over the grouping items, or null if no restrictions have 
     * been specified.
     * @return having clause predicate
     */
    Predicate getGroupRestriction();

    /**
     * Return whether duplicate query results must be eliminated or
     * retained.
     * @return boolean indicating whether duplicate query results 
     *         must be eliminated
     */
    boolean isDistinct();

    /**
     * Return the result type of the query or subquery. If
     * a result type was specified as an argument to the
     * {@code createQuery} or {@code subquery} method, that
     * type is returned. If the query was created using the
     * {@code createTupleQuery} method, the result type is
     * {@code Tuple}. Otherwise, the result type is
     * {@code Object}.
     * @return result type
     */
    Class<T> getResultType();          
}
package jakarta.persistence.criteria;

import java.util.Collection;
import jakarta.persistence.metamodel.CollectionAttribute;

/**
 * The {@code CollectionJoin} interface is the type of the result of
 * joining to a collection over an association or element 
 * collection that has been specified as a {@link java.util.Collection}.
 *
 * @param <Z> the source type of the join
 * @param <E> the element type of the target {@code Collection} 
 *
 * @since 2.0
 */
public interface CollectionJoin<Z, E> 
                extends PluralJoin<Z, Collection<E>, E> {

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified join object
     * @since 2.1
     */
    CollectionJoin<Z, E> on(Expression<Boolean> restriction);

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restrictions  zero or more restriction predicates
     * @return the modified join object
     * @since 2.1
     */
    CollectionJoin<Z, E> on(Predicate... restrictions);

    /**
     * Return the metamodel representation for the collection
     * attribute.
     * @return metamodel type representing the {@code Collection} that is
     *         the target of the join
     */
    CollectionAttribute<? super Z, E> getModel();
}
import jakarta.persistence.metamodel.EntityType;

import java.util.Set;

/**
 * The {@code CommonAbstractCriteria} interface defines functionality
 * that is common to both top-level criteria queries and subqueries as 
 * well as to update and delete criteria operations.
 * It is not intended to be used directly in query construction.
 *
 * Note that criteria queries and criteria update and delete operations
 * are typed differently.
 * Criteria queries are typed according to the query result type.
 * Update and delete operations are typed according to the target of the
 * update or delete.
 *
 * @since 2.1
 */
public interface CommonAbstractCriteria {

    /**
     * Create a subquery of the query. 
     * @param type  the subquery result type
     * @return subquery 
     */
    <U> Subquery<U> subquery(Class<U> type);

    /**
     * Create a subquery of the query.
     * @param type  the subquery result type
     * @return subquery
     */
    <U> Subquery<U> subquery(EntityType<U> type);

    /**
     * Return the predicate that corresponds to the where clause
     * restriction(s), or null if no restrictions have been
     * specified.
     * @return where clause predicate
     */
    Predicate getRestriction();

    /**
     * Return the parameters of the query.  Returns empty set if
     * there are no parameters.
     * Modifications to the set do not affect the query.
     * @return the query parameters
     */
    Set<ParameterExpression<?>> getParameters();
}
/**
 * The {@code CompoundSelection} interface defines a compound
 * selection item (a tuple, array, or result of a constructor).
 *
 * @param <X> the type of the selection item
 *
 * @since 2.0
 */
public interface CompoundSelection<X> extends Selection<X> {}
package jakarta.persistence.criteria;

import java.util.Collection;

/**
 * Type for query expressions.
 *
 * @param <T> the type of the expression
 *
 * @since 2.0
 */
public interface Expression<T> extends Selection<T> {

    /**
     * Create a predicate to test whether the expression is null.
     * @return predicate testing whether the expression is null
     */
    Predicate isNull();

    /**
     * Create a predicate to test whether the expression is 
     * not null.
     * @return predicate testing whether the expression is not null
     */
    Predicate isNotNull();

    /**
     * Create a predicate to test whether the expression is equal to
     * the argument.
     * @param value  expression to be tested against
     * @return predicate testing for equality
     * @since 3.2
     */
    Predicate equalTo(Expression<?> value);

    /**
     * Create a predicate to test whether the expression is equal to
     * the argument.
     * @param value  value to be tested against
     * @return predicate testing for equality
     * @since 3.2
     */
    Predicate equalTo(Object value);

    /**
     * Create a predicate to test whether the expression is unequal
     * to the argument.
     * @param value  expression to be tested against
     * @return predicate testing for inequality
     * @since 3.2
     */
    Predicate notEqualTo(Expression<?> value);

    /**
     * Create a predicate to test whether the expression is unequal
     * to the argument.
     * @param value  value to be tested against
     * @return predicate testing for inequality
     * @since 3.2
     */
    Predicate notEqualTo(Object value);

    /**
     * Create a predicate to test whether the expression is a member
     * of the argument list.
     * @param values  values to be tested against
     * @return predicate testing for membership
     */
    Predicate in(Object... values);

    /**
     * Create a predicate to test whether the expression is a member
     * of the argument list.
     * @param values  expressions to be tested against
     * @return predicate testing for membership
     */
    Predicate in(Expression<?>... values);

    /**
     * Create a predicate to test whether the expression is a member
     * of the collection.
     * @param values  collection of values to be tested against
     * @return predicate testing for membership
     */
    Predicate in(Collection<?> values);

    /**
     * Create a predicate to test whether the expression is a member
     * of the collection.
     * @param values expression corresponding to collection to be
     *        tested against
     * @return predicate testing for membership
     */
    Predicate in(Expression<Collection<?>> values);

    /**
     * Perform a typecast upon the expression, returning a new
     * expression object.
     * Unlike {@link #cast(Class)}, this method does not cause
     * type conversion: the runtime type is not changed.
     * <p><em>Warning: may result in a runtime failure.</em>
     * @param type  intended type of the expression
     * @return new expression of the given type
     * @see #cast(Class)
     */
    <X> Expression<X> as(Class<X> type);

    /**
     * Cast this expression to the specified type, returning a
     * new expression object.
     * Unlike {@link #as(Class)}, this method <em>does</em>
     * result in a runtime type conversion.
     * <p><em>Providers are required to support casting
     * scalar expressions to {@link String}, and
     * {@code String} expressions to {@link Integer},
     * {@link Long}, {@link Float}, and {@link Double}.
     * Support for typecasts between other basic types is
     * not required.</em>
     * @param type  a basic type
     * @return a scalar expression of the given basic type
     * @since 3.2
     */
    <X> Expression<X> cast(Class<X> type);
}
import jakarta.persistence.metamodel.Attribute;

/**
 * Represents a join-fetched association or attribute.
 *
 * @param <Z>  the source type of the fetch
 * @param <X>  the target type of the fetch
 *
 * @since 2.0
 */
public interface Fetch<Z, X> extends FetchParent<Z, X> {

    /**
     * Return the metamodel attribute corresponding to the 
     * fetch join.
     * @return metamodel attribute for the join
     */
    Attribute<? super Z, ?> getAttribute();

    /**
     * Return the 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();
}
import jakarta.persistence.metamodel.PluralAttribute;
import jakarta.persistence.metamodel.SingularAttribute;

/**
 * Represents an element of the from clause which may
 * function as the parent of Fetches.
 *
 * @param <Z>  the source type
 * @param <X>  the target type
 *
 * @since 2.0
 */
public interface FetchParent<Z, X> {

    /**
     * Return the fetch joins that have been made from this type.
     * Returns empty set if no fetch joins have been made from
     * this type.
     * Modifications to the set do not affect the query.
     * @return fetch joins made from this type
     */
    java.util.Set<Fetch<X, ?>> getFetches();

    /**
     * Create a fetch join to the specified single-valued attribute 
     * using an inner join.
     * @param attribute  target of the join
     * @return the resulting fetch join
     */        
    <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute);

    /**
     * Create a fetch join to the specified single-valued attribute 
     * using the given join type.
     * @param attribute  target of the join
     * @param jt  join type
     * @return the resulting fetch join
     */        
    <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute, JoinType jt);

    /**
     * Create a fetch join to the specified collection-valued 
     * attribute using an inner join. 
     * @param attribute  target of the join
     * @return the resulting join
     */
    <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute);

    /**
     * Create a fetch join to the specified collection-valued 
     * attribute using the given join type.
     * @param attribute  target of the join
     * @param jt  join type
     * @return the resulting join
     */
    <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute, JoinType jt);

    //String-based:

    /**
     * Create a fetch join to the specified attribute using an 
     * inner join.
     * @param attributeName  name of the attribute for the
     *        target of the join
     * @return the resulting fetch join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */        
    @SuppressWarnings("hiding")
    <X, Y> Fetch<X, Y> fetch(String attributeName);

    /**
     * Create a fetch join to the specified attribute using 
     * the given join type.
     * @param attributeName  name of the attribute for the
     *              target of the join
     * @param jt  join type
     * @return the resulting fetch join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */        
    @SuppressWarnings("hiding")
    <X, Y> Fetch<X, Y> fetch(String attributeName, JoinType jt);
}
package jakarta.persistence.criteria;

import jakarta.persistence.metamodel.EntityType;
import jakarta.persistence.metamodel.SingularAttribute;
import jakarta.persistence.metamodel.CollectionAttribute;
import jakarta.persistence.metamodel.ListAttribute;
import jakarta.persistence.metamodel.MapAttribute;
import jakarta.persistence.metamodel.SetAttribute;

import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * Represents a bound type, usually an entity that appears in
 * the from clause, but may also be an embeddable belonging to
 * an entity in the from clause. 
 * Serves as a factory for {@link Join}s of associations,
 * embeddables, and collections belonging to the type, and for
 * {@link Path}s of attributes belonging to the type.
 *
 * @param <Z> the source type
 * @param <X> the target type
 *
 * @since 2.0
 */
@SuppressWarnings("hiding")
public interface From<Z, X> extends Path<X>, FetchParent<Z, X> {

    /**
     * Return the joins that have been made from this bound type.
     * Returns empty set if no joins have been made from this
     * bound type.
     * Modifications to the set do not affect the query.
     * @return joins made from this type
     */
    Set<Join<X, ?>> getJoins();

    /**
     * Whether the {@link From} object has been obtained as a result
     * of correlation (use of a {@link Subquery#correlate} method).
     * @return boolean indicating whether the object has been
     *         obtained through correlation
     */
    boolean isCorrelated();

    /**
     * Returns the parent {@link From} object from which the correlated
     * {@link From} object has been obtained through correlation (use
     * of {@link Subquery#correlate} method).
     * @return  the parent of the correlated {@code From} object
     * @throws IllegalStateException if the {@code From} object has
     *         not been obtained through correlation
     */
    From<Z, X> getCorrelationParent();

    /**
     * Create and add an inner join to the given entity.
     * @param entityClass  the target entity class
     * @return the resulting join
     * @since 3.2
     */
    <Y> Join<X, Y> join(Class<Y> entityClass);

    /**
     * Create and add a join to the given entity.
     * @param entityClass  the target entity class
     * @param joinType  join type
     * @return the resulting join
     * @since 3.2
     */
    <Y> Join<X, Y> join(Class<Y> entityClass, JoinType joinType);

    /**
     * Create and add an inner join to the given entity.
     * @param entity  metamodel entity representing the join target
     * @return the resulting join
     * @since 3.2
     */
    <Y> Join<X, Y> join(EntityType<Y> entity);

    /**
     * Create and add a join to the given entity.
     * @param entity  metamodel entity representing the join target
     * @param joinType  join type
     * @return the resulting join
     * @since 3.2
     */
    <Y> Join<X, Y> join(EntityType<Y> entity, JoinType joinType);

    /**
     * Create an inner join to the specified single-valued 
     * attribute.
     * @param attribute  target of the join
     * @return the resulting join
     */
    <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute);

    /**
     * Create a join to the specified single-valued attribute 
     * using the given join type.
     * @param attribute  target of the join
     * @param jt  join type 
     * @return the resulting join
     */
    <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute, JoinType jt);

    /**
     * Create an inner join to the specified {@link Collection}-valued
     * attribute.
     * @param collection  target of the join
     * @return the resulting join
     */
    <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection);

    /**
     * Create an inner join to the specified {@link Set}-valued
     * attribute.
     * @param set  target of the join
     * @return the resulting join
     */
    <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set);

    /**
     * Create an inner join to the specified
     * {@link List}-valued attribute.
     * @param list  target of the join
     * @return the resulting join
     */
    <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list);

    /**
     * Create an inner join to the specified {@link Map}-valued
     * attribute.
     * @param map  target of the join
     * @return the resulting join
     */
    <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map);

    /**
     * Create a join to the specified {@link Collection}-valued
     * attribute using the given join type.
     * @param collection  target of the join
     * @param jt  join type 
     * @return the resulting join
     */
    <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection, JoinType jt);

    /**
     * Create a join to the specified {@link Set}-valued attribute
     * using the given join type.
     * @param set  target of the join
     * @param jt  join type 
     * @return the resulting join
     */
    <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set, JoinType jt);

    /**
     * Create a join to the specified {@link List}-valued attribute
     * using the given join type.
     * @param list  target of the join
     * @param jt  join type 
     * @return the resulting join
     */
    <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list, JoinType jt);

    /**
     * Create a join to the specified {@link Map}-valued attribute
     * using the given join type.
     * @param map  target of the join
     * @param jt  join type 
     * @return the resulting join
     */
    <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map, JoinType jt);

    //String-based:

    /**
     * Create an inner join to the specified attribute.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, Y> Join<X, Y> join(String attributeName);        

    /**
     * Create an inner join to the specified {@link Collection}-valued
     * attribute.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, Y> CollectionJoin<X, Y> joinCollection(String attributeName);        

    /**
     * Create an inner join to the specified {@link Set}-valued
     * attribute.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, Y> SetJoin<X, Y> joinSet(String attributeName);        

    /**
     * Create an inner join to the specified {@link List}-valued
     * attribute.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, Y> ListJoin<X, Y> joinList(String attributeName);                

    /**
     * Create an inner join to the specified {@link Map}-valued
     * attribute.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, K, V> MapJoin<X, K, V> joinMap(String attributeName);        

    /**
     * Create a join to the specified attribute using the given
     * join type.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @param jt  join type
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, Y> Join<X, Y> join(String attributeName, JoinType jt);        

    /**
     * Create a join to the specified {@link Collection}-valued
     * attribute using the given join type.
     * @param attributeName  name of the attribute for the 
     *                       target of the join
     * @param jt  join type
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, Y> CollectionJoin<X, Y> joinCollection(String attributeName, JoinType jt);        

    /**
     * Create a join to the specified {@link Set}-valued attribute
     * using the given join type.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @param jt  join type
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, Y> SetJoin<X, Y> joinSet(String attributeName, JoinType jt);        

    /**
     * Create a join to the specified {@link List}-valued attribute
     * using the given join type.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @param jt  join type
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *         name does not exist
     */
    <X, Y> ListJoin<X, Y> joinList(String attributeName, JoinType jt);        

    /**
     * Create a join to the specified {@link Map}-valued attribute
     * using the given join type.
     * @param attributeName  name of the attribute for the
     *                       target of the join
     * @param jt  join type
     * @return the resulting join
     * @throws IllegalArgumentException if attribute of the given
     *        name does not exist
     */
    <X, K, V> MapJoin<X, K, V> joinMap(String attributeName, JoinType jt);        
}
import jakarta.persistence.metamodel.Attribute;

/**
 * A join to an entity, embeddable, or basic type.
 *
 * @param <Z> the source type of the join
 * @param <X> the target type of the join
 *
 * @since 2.0
 */
public interface Join<Z, X> extends From<Z, X> {

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified join object
     * @since 2.1
     */
    Join<Z, X> on(Expression<Boolean> restriction);

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restrictions  zero or more restriction predicates
     * @return the modified join object
     * @since 2.1
     */
    Join<Z, X> on(Predicate... restrictions);

    /** 
     * Return the predicate that corresponds to the ON 
     * restriction(s) on the join, or null if no ON condition 
     * has been specified.
     * @return the ON restriction predicate
     * @since 2.1
     */
    Predicate getOn();

    /**
     * Return the metamodel attribute representing the join
     * target, if any, or null if the target of the join is an
     * entity type.
     * @return metamodel attribute or null
     */
    Attribute<? super Z, ?> getAttribute();

    /**
     * Return the parent of the join.
     * @return join parent
     */
    From<?, Z> getParent();

    /**
     * Return the join type.
     * @return join type
     */
    JoinType getJoinType();
}
/**
 * Defines the three varieties of join.
 *
 * <p>Support for {@link #RIGHT} outer joins is not required. Applications
 * which make use of right joins might not be portable between providers or
 * between SQL databases.
 *
 * @since 2.0
 */
public enum JoinType {

    /**
     * Inner join.
     */
    INNER, 

    /**
     * Left outer join.
     */
    LEFT, 

    /**
     * Right outer join.
     */
    RIGHT,
}
package jakarta.persistence.criteria;

import java.util.List;
import jakarta.persistence.metamodel.ListAttribute;

/**
 * The {@code ListJoin} interface is the type of the result of
 * joining to a collection over an association or element 
 * collection that has been specified as a {@link java.util.List}.
 *
 * @param <Z> the source type of the join
 * @param <E> the element type of the target List
 *
 * @since 2.0
 */
public interface ListJoin<Z, E> 
                extends PluralJoin<Z, List<E>, E> {

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified join object
     * @since 2.1
     */
    ListJoin<Z, E> on(Expression<Boolean> restriction);

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restrictions  zero or more restriction predicates
     * @return the modified join object
     * @since 2.1
     */
    ListJoin<Z, E> on(Predicate... restrictions);

    /**
     * Return the metamodel representation for the list attribute.
     * @return metamodel type representing the {@code List} that is
     *         the target of the join
     */
    ListAttribute<? super Z, E> getModel();

    /**
     * Create an expression that corresponds to the index of
     * the object in the referenced association or element
     * collection.
     * This method must only be invoked upon an object that
     * represents an association or element collection for
     * which an order column has been defined.
     * @return expression denoting the index
     */
    Expression<Integer> index();
}
import java.time.LocalDate;

/**
 * Each instance represents a type of field which can be
 * extracted from a {@link LocalDate}.
 *
 * @param <N> the resulting type of the extracted value
 *
 * @since 3.2
 */
public class LocalDateField<N> implements TemporalField<N, LocalDate> {

        private final String name;

        private LocalDateField(String name) {
                this.name = name;
        }

        @Override
        public String toString() {
                return name;
        }

        /**
         * The calendar year.
         */
        public static final LocalDateField<Integer> YEAR = new LocalDateField<>("year");
        /**
         * The calendar quarter, numbered from 1 to 4.
         */
        public static final LocalDateField<Integer> QUARTER = new LocalDateField<>("quarter");
        /**
         * The calendar month of the year, numbered from 1.
         */
        public static final LocalDateField<Integer> MONTH = new LocalDateField<>("month");
        /**
         * The ISO-8601 week number.
         */
        public static final LocalDateField<Integer> WEEK = new LocalDateField<>("week");
        /**
         * The calendar day of the month, numbered from 1.
         */
        public static final LocalDateField<Integer> DAY = new LocalDateField<>("day");
}
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;

/**
 * Each instance represents a type of field which can be
 * extracted from a {@link LocalDateTime}.
 *
 * @param <N> the resulting type of the extracted value
 *
 * @since 3.2
 */
public class LocalDateTimeField<N> implements TemporalField<N, LocalDateTime> {

        private final String name;

        private LocalDateTimeField(String name) {
                this.name = name;
        }

        @Override
        public String toString() {
                return name;
        }

        /**
         * The calendar year.
         */
        public static final LocalDateTimeField<Integer> YEAR = new LocalDateTimeField<>("year");
        /**
         * The calendar quarter, numbered from 1 to 4.
         */
        public static final LocalDateTimeField<Integer> QUARTER = new LocalDateTimeField<>("quarter");
        /**
         * The calendar month of the year, numbered from 1.
         */
        public static final LocalDateTimeField<Integer> MONTH = new LocalDateTimeField<>("month");
        /**
         * The ISO-8601 week number.
         */
        public static final LocalDateTimeField<Integer> WEEK = new LocalDateTimeField<>("week");
        /**
         * The calendar day of the month, numbered from 1.
         */
        public static final LocalDateTimeField<Integer> DAY = new LocalDateTimeField<>("day");

        /**
         * The hour of the day in 24-hour time, numbered from 0 to 23.
         */
        public static final LocalDateTimeField<Integer> HOUR = new LocalDateTimeField<>("hour");
        /**
         * The minute of the hour, numbered from 0 to 59.
         */
        public static final LocalDateTimeField<Integer> MINUTE = new LocalDateTimeField<>("minute");
        /**
         * The second of the minute, numbered from 0 to 59, including a fractional
         * part representing fractions of a second
         */
        public static final LocalDateTimeField<Double> SECOND = new LocalDateTimeField<>("second");

        /**
         * The {@linkplain LocalDate date} part of a datetime.
         */
        public static final LocalDateTimeField<LocalDate> DATE = new LocalDateTimeField<>("date");
        /**
         * The {@linkplain LocalTime time} part of a datetime.
         */
        public static final LocalDateTimeField<LocalTime> TIME = new LocalDateTimeField<>("time");
}
import java.time.LocalTime;

/**
 * Each instance represents a type of field which can be
 * extracted from a {@link LocalTime}.
 *
 * @param <N> the resulting type of the extracted value
 *
 * @since 3.2
 */
public class LocalTimeField<N> implements TemporalField<N, LocalTime> {

        private final String name;

        private LocalTimeField(String name) {
                this.name = name;
        }

        @Override
        public String toString() {
                return name;
        }

        /**
         * The hour of the day in 24-hour time, numbered from 0 to 23.
         */
        public static final LocalTimeField<Integer> HOUR = new LocalTimeField<>("hour");
        /**
         * The minute of the hour, numbered from 0 to 59.
         */
        public static final LocalTimeField<Integer> MINUTE = new LocalTimeField<>("minute");
        /**
         * The second of the minute, numbered from 0 to 59, including a fractional
         * part representing fractions of a second
         */
        public static final LocalTimeField<Double> SECOND = new LocalTimeField<>("second");
}
import java.util.Map;
import jakarta.persistence.metamodel.MapAttribute;

/**
 * The {@code MapJoin} interface is the type of the result of
 * joining to a collection over an association or element 
 * collection that has been specified as a {@link 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
 *
 * @since 2.0
 */
public interface MapJoin<Z, K, V> 
                extends PluralJoin<Z, Map<K, V>, V> {

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified join object
     * @since 2.1
     */
    MapJoin<Z, K, V> on(Expression<Boolean> restriction);

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restrictions  zero or more restriction predicates
     * @return the modified join object
     * @since 2.1
     */
    MapJoin<Z, K, V> on(Predicate... restrictions);

    /**
     * Return the metamodel representation for the map attribute.
     * @return metamodel type representing the {@code Map} that is
     *         the target of the join
     */
    MapAttribute<? super Z, K, V> getModel();

    /**
     * Create a path expression that corresponds to the map key.
     * @return path corresponding to map key
     */
    Path<K> key();

    /**
     * Create a path expression that corresponds to the map value.
     * This method is for stylistic use only: it just returns this.
     * @return path corresponding to the map value
     */
    Path<V> value(); 

    /**
     * Create an expression that corresponds to the map entry.
     * @return expression corresponding to the map entry
     */
    Expression<Map.Entry<K, V>> entry();
}
/**
 * Specifies the precedence of null values within query result sets.
 *
 * @see CriteriaBuilder#asc(Expression, Nulls)
 * @see CriteriaBuilder#desc(Expression, Nulls)
 *
 * @since 3.2
 */
public enum Nulls {
        /**
         * Null precedence not specified.
         */
        NONE,
        /**
         * Null values occur at the beginning of the result set.
         */
        FIRST,
        /**
         * Null values occur at the end of the result set.
         */
        LAST
}
/**
 * An object that defines an ordering over the query results.
 *
 * @since 2.0
 */
public interface Order {

   /**
    * Switch the ordering.
    * @return a new {@code Order} instance with the reversed ordering
    */
    Order reverse();

   /**
    * Whether ascending ordering is in effect.
    * @return boolean indicating whether ordering is ascending
    */
    boolean isAscending();

    /**
     * Return the precedence of null values.
     * @return the {@linkplain Nulls precedence of null values}
     * @since 3.2
     */
    Nulls getNullPrecedence();

   /**
    * Return the expression that is used for ordering.
    * @return expression used for ordering
    */
   Expression<?> getExpression();
}
import jakarta.persistence.Parameter;

/**
 * Type of criteria query parameter expressions.
 *
 * @param <T> the type of the parameter expression
 *
 * @since 2.0
 */
public interface ParameterExpression<T> extends Parameter<T>, Expression<T> {}
import jakarta.persistence.metamodel.PluralAttribute;
import jakarta.persistence.metamodel.SingularAttribute;
import jakarta.persistence.metamodel.Bindable;
import jakarta.persistence.metamodel.MapAttribute;

/**
 * Represents a simple or compound attribute path from a 
 * bound type or collection, and is a "primitive" expression.
 *
 * @param <X> the type referenced by the path
 *
 * @since 2.0
 */
public interface Path<X> extends Expression<X> {

    /** 
     * Return the bindable object that corresponds to the path
     * expression.
     * @return bindable object corresponding to the path
     */
    Bindable<X> getModel(); 

    /**
     * Return the parent "node" in the path or null if no parent.
     * @return parent
     */
    Path<?> getParentPath();

    /**
     * Create a path corresponding to the referenced
     * single-valued attribute.
     * @param attribute single-valued attribute
     * @return path corresponding to the referenced attribute
     */
    <Y> Path<Y> get(SingularAttribute<? super X, Y> attribute);

    /**
     * Create a path corresponding to the referenced 
     * collection-valued attribute.
     * @param collection collection-valued attribute
     * @return expression corresponding to the referenced attribute
     */
    <E, C extends java.util.Collection<E>> Expression<C> get(PluralAttribute<? super X, C, E> collection);

    /**
     * Create a path corresponding to the referenced 
     * map-valued attribute.
     * @param map map-valued attribute
     * @return expression corresponding to the referenced attribute
     */
    <K, V, M extends java.util.Map<K, V>> Expression<M> get(MapAttribute<? super X, K, V> map);

    /**
     * Create an expression corresponding to the type of the path.
     * @return expression corresponding to the type of the path
     */
    Expression<Class<? extends X>> type();

    //String-based:

    /**
     * Create a path corresponding to the referenced attribute.
     * 
     * <p> Note: Applications using the string-based API may need to 
     * specify the type resulting from the {@link #get} operation in
     * order to avoid the use of {@code Path} variables.
     *
     * <p>For example:
     * {@snippet :
     * CriteriaQuery<Person> q = cb.createQuery(Person.class);
     * Root<Person> p = q.from(Person.class);
     * q.select(p)
     *  .where(cb.isMember("joe",
     *                     p.<Set<String>>get("nicknames")));
     * }
     * <p>rather than:
     * {@snippet :
     * CriteriaQuery<Person> q = cb.createQuery(Person.class);
     * Root<Person> p = q.from(Person.class);
     * Path<Set<String>> nicknames = p.get("nicknames");
     * q.select(p)
     *  .where(cb.isMember("joe", nicknames));
     * }
     *
     * @param attributeName  name of the attribute
     * @return path corresponding to the referenced attribute
     * @throws IllegalStateException if invoked on a path that
     *         corresponds to a basic type
     * @throws IllegalArgumentException if attribute of the given
     *         name does not otherwise exist
     */
    <Y> Path<Y> get(String attributeName);
}
import jakarta.persistence.metamodel.PluralAttribute;

/**
 * The {@code PluralJoin} interface defines functionality
 * that is common to joins to all collection types. It is
 * not intended to be used directly in query construction.
 *
 * @param <Z> the source type
 * @param <C> the collection type
 * @param <E> the element type of the collection 
 *
 * @since 2.0
 */
public interface PluralJoin<Z, C, E> extends Join<Z, E> {

    /**
     * Return the metamodel representation for the collection-valued 
     * attribute corresponding to the join.
     * @return metamodel collection-valued attribute corresponding
     *         to the target of the join
     */
    PluralAttribute<? super Z, C, E> getModel();
}
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.
 *
 * @since 2.0
 */
public interface Predicate extends Expression<Boolean> {

        enum BooleanOperator {
              AND, OR
        }

    /**
     * Return the boolean operator for the predicate.
     * If the predicate is simple, this is {@code AND}.
     * @return boolean operator for the predicate
     */
    BooleanOperator getOperator();

    /**
     * Whether the predicate has been created from another
     * predicate by applying {@link Predicate#not()}
     * or by calling {@link CriteriaBuilder#not}.
     * @return boolean indicating if the predicate is 
     *                 a negated predicate
     */
    boolean isNegated();

    /**
     * Return the top-level conjuncts or disjuncts of the
     * predicate. Returns empty list if there are no top-level
     * conjuncts or disjuncts of the predicate.
     * Modifications to the list do not affect the query.
     * @return list of boolean expressions forming the predicate
     */
    List<Expression<Boolean>> getExpressions();

    /**
     * Create a negation of the predicate.
     * @return negated predicate 
     */
    Predicate not();

}
import jakarta.persistence.metamodel.EntityType;

/**
 * A root type in the from clause.
 * Query roots always reference entities.
 *
 * @param <X> the entity type referenced by the root
 *
 * @since 2.0
 */
public interface Root<X> extends From<X, X> {

    /**
     * Return the metamodel entity corresponding to the root.
     * @return metamodel entity corresponding to the root
     */
    EntityType<X> getModel();
}
import jakarta.persistence.TupleElement;
import java.util.List;

/**
 * The {@code Selection} interface defines an item that is to be
 * returned in a query result.
 *
 * @param <X> the type of the selection item
 *
 * @since 2.0
 */
public interface Selection<X> extends TupleElement<X> {

    /**
     * Assigns an alias to the selection item.
     * Once assigned, an alias cannot be changed or reassigned.
     * Returns the same selection item.
     * @param name  alias
     * @return selection item 
     */
    Selection<X> alias(String name);

    /**
     * Whether the selection item is a compound selection.
     * @return boolean indicating whether the selection is a compound
     *         selection
     */
    boolean isCompoundSelection();

    /**
     * Return the selection items composing a compound selection.
     * Modifications to the list do not affect the query.
     * @return list of selection items
     * @throws IllegalStateException if selection is not a 
     *         compound selection
     */
    List<Selection<?>> getCompoundSelectionItems();
}
import java.util.Set;
import jakarta.persistence.metamodel.SetAttribute;

/**
 * The {@code SetJoin} interface is the type of the result of
 * joining to a collection over an association or element 
 * collection that has been specified as a {@link java.util.Set}.
 *
 * @param <Z> the source type of the join
 * @param <E> the element type of the target {@code Set}
 *
 * @since 2.0
 */
public interface SetJoin<Z, E> extends PluralJoin<Z, Set<E>, E> {

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified join object
     * @since 2.1
     */
    SetJoin<Z, E> on(Expression<Boolean> restriction);

    /**
     * Modify the join to restrict the result according to the
     * specified ON condition and return the join object.  
     * Replaces the previous ON condition, if any.
     * @param restrictions  zero or more restriction predicates
     * @return the modified join object
     * @since 2.1
     */
    SetJoin<Z, E> on(Predicate... restrictions);

    /**
     * Return the metamodel representation for the set attribute.
     * @return metamodel type representing the {@code Set} that is
     *         the target of the join
     */
    SetAttribute<? super Z, E> getModel();
}
package jakarta.persistence.criteria;

import java.util.List;
import java.util.Set;

/**
 * The {@code Subquery} interface defines functionality that is
 * specific to subqueries.
 *
 * A subquery has an expression as its selection item.
 *
 * @param <T> the type of the selection item.
 *
 * @since 2.0
 */
public interface Subquery<T> extends AbstractQuery<T>, Expression<T> {

    /**
     * Specify the item that is to be returned as the subquery 
     * result.
     * Replaces the previously specified selection, if any.
     * @param expression  expression specifying the item that
     *        is to be returned as the subquery result
     * @return the modified subquery
     */
    Subquery<T> select(Expression<T> expression);

    /**
     * Modify the subquery to restrict the result according
     * to the specified boolean expression.
     * Replaces the previously added restriction(s), if any.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param restriction  a simple or compound boolean expression
     * @return the modified subquery
     */
    Subquery<T> where(Expression<Boolean> restriction);

    /**
     * Modify the subquery to restrict the result according 
     * to the conjunction of the specified restriction predicates.
     * Replaces the previously added restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param restrictions  zero or more restriction predicates
     * @return the modified subquery
     */
    Subquery<T> where(Predicate... restrictions);

    /**
     * Modify the query to restrict the query result according
     * to the conjunction of the specified restriction predicates.
     * Replaces the previously added restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * This method only overrides the return type of the
     * corresponding {@code AbstractQuery} method.
     * @param restrictions  a list of zero or more restriction predicates
     * @return the modified query
     * @since 3.2
     */
    Subquery<T> where(List<Predicate> restrictions);

    /**
     * Specify the expressions that are used to form groups over
     * the subquery results.
     * Replaces the previous specified grouping expressions, if any.
     * If no grouping expressions are specified, any previously 
     * added grouping expressions are simply removed.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param grouping  zero or more grouping expressions
     * @return the modified subquery
     */
    Subquery<T> groupBy(Expression<?>... grouping);

    /**
     * Specify the expressions that are used to form groups over
     * the subquery results.
     * Replaces the previous specified grouping expressions, if any.
     * If no grouping expressions are specified, any previously 
     * added grouping expressions are simply removed.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param grouping  list of zero or more grouping expressions
     * @return the modified subquery
     */
    Subquery<T> groupBy(List<Expression<?>> grouping);

    /**
     * Specify a restriction over the groups of the subquery.
     * Replaces the previous having restriction(s), if any.
     * This method only overrides the return type of the 
     * corresponding {@code 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 having restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param restrictions  zero or more restriction predicates
     * @return the modified subquery
     */
    Subquery<T> having(Predicate... restrictions);

    /**
     * Specify restrictions over the groups of the query
     * according the conjunction of the specified restriction
     * predicates.
     * Replaces the previously added having restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * This method only overrides the return type of the
     * corresponding {@code AbstractQuery} method.
     * @param restrictions  a list of zero or more restriction predicates
     * @return the modified query
     * @since 3.2
     */
    Subquery<T> having(List<Predicate> restrictions);

    /**
     * Specify whether duplicate query results are eliminated.
     * A true value will cause duplicates to be eliminated.
     * A false value will cause duplicates to be retained.
     * If distinct has not been specified, duplicate results must
     * be retained.
     * This method only overrides the return type of the 
     * corresponding {@code AbstractQuery} method.
     * @param distinct  boolean value specifying whether duplicate
     *        results must be eliminated from the subquery result or
     *        whether they must be retained
     * @return the modified subquery.
     */
    Subquery<T> distinct(boolean distinct);

    /**
     * Create a subquery root correlated to a root of the 
     * enclosing query.
     * @param parentRoot  a root of the containing query
     * @return subquery root
     */
    <Y> Root<Y> correlate(Root<Y> parentRoot);

    /**
     * Create a subquery join object correlated to a join object
     * of the enclosing query.
     * @param parentJoin  join object of the containing query
     * @return subquery join
     */
    <X, Y> Join<X, Y> correlate(Join<X, Y> parentJoin);

    /**
     * Create a subquery collection join object correlated to a 
     * collection join object of the enclosing query.
     * @param parentCollection  join object of the containing query
     * @return subquery join
     */
    <X, Y> CollectionJoin<X, Y> correlate(CollectionJoin<X, Y> parentCollection);

    /**
     * Create a subquery set join object correlated to a set join
     * object of the enclosing query.
     * @param parentSet  join object of the containing query
     * @return subquery join
     */
    <X, Y> SetJoin<X, Y> correlate(SetJoin<X, Y> parentSet);

    /**
     * Create a subquery list join object correlated to a list join
     * object of the enclosing query.
     * @param parentList join object of the containing query
     * @return subquery join
     */
    <X, Y> ListJoin<X, Y> correlate(ListJoin<X, Y> parentList);

    /**
     * Create a subquery map join object correlated to a map join
     * object of the enclosing query.
     * @param parentMap join object of the containing query
     * @return subquery join
     */
    <X, K, V> MapJoin<X, K, V> correlate(MapJoin<X, K, V> parentMap);

    /**
     * Return the query of which this is a subquery.
     * This must be a CriteriaQuery or a Subquery.
     * @return the enclosing query or subquery
     */
    AbstractQuery<?> getParent();

    /**
     * Return the query of which this is a subquery.
     * This may be a CriteriaQuery, CriteriaUpdate, CriteriaDelete,
     * or a Subquery.
     * @return the enclosing query or subquery
     * @since 2.1
     */
    CommonAbstractCriteria getContainingQuery();

    /**
     * Return the selection expression.
     * @return the item to be returned in the subquery result
     */
    Expression<T> getSelection();

    /**
     * Return the correlated joins of the subquery.
     * Returns empty set if the subquery has no correlated
     * joins.
     * Modifications to the set do not affect the query.
     * @return the correlated joins of the subquery
     */
    Set<Join<?, ?>> getCorrelatedJoins();

}
import java.time.temporal.Temporal;

/**
 * Each instance represents a type of field which can be
 * extracted from a date, time, or datetime.
 *
 * @param <N> the resulting type of the extracted value
 * @param <T> the temporal type (date, time, or datetime)
 *
 * @see LocalDateField
 * @see LocalTimeField
 * @see LocalDateTimeField
 * @see CriteriaBuilder#extract(TemporalField, Expression)
 *
 * @since 3.2
 */
public interface TemporalField<N,T extends Temporal> {}
package jakarta.persistence.metamodel;

import java.util.Set;

/**
 * Provides access to the metamodel of persistent entities in the
 * persistence unit.
 *
 * @since 2.0
 */
public interface Metamodel {

    /**
     * Return the metamodel entity type representing the entity.
     * @param entityName  the name of the represented entity
     * @return the metamodel entity type
     * @throws IllegalArgumentException if not an entity
     * @see jakarta.persistence.Entity#name
     * @since 3.2
     */
    EntityType<?> entity(String entityName);

    /**
     * Return the metamodel entity type representing the entity.
     * @param cls  the type of the represented entity
     * @return the metamodel entity type
     * @throws IllegalArgumentException if not an entity
     */
    <X> EntityType<X> entity(Class<X> cls);

    /**
     * Return the metamodel managed type representing the 
     * entity, mapped superclass, or embeddable class.
     * @param cls  the type of the represented managed class
     * @return the metamodel managed type
     * @throws IllegalArgumentException if not a managed class
     */
    <X> ManagedType<X> managedType(Class<X> cls);

    /**
     * Return the metamodel embeddable type representing the
     * embeddable class.
     * @param cls  the type of the represented embeddable class
     * @return the metamodel embeddable type
     * @throws IllegalArgumentException if not an embeddable class
     */
    <X> EmbeddableType<X> embeddable(Class<X> cls);

    /**
     * Return the metamodel managed types.
     * @return the metamodel managed types
     */
    Set<ManagedType<?>> getManagedTypes();

    /**
     * Return the metamodel entity types.
     * @return the metamodel entity types
     */
    Set<EntityType<?>> getEntities();

    /**
     * Return the metamodel embeddable types.
     * Returns am empty set if there are no embeddable types.
     * @return the metamodel embeddable types
     */
    Set<EmbeddableType<?>> getEmbeddables();
}
package jakarta.persistence.metamodel;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * The {@code StaticMetamodel} annotation specifies that the class is
 * a metamodel class that represents the entity, mapped superclass,
 * or embeddable class designated by the {@link #value} element.
 *
 * @since 2.0
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface StaticMetamodel {

    /** 
     * Class being modelled by the annotated class.
     */
    Class<?> value();
}
/**
 * Represents an attribute of a Java type.
 *
 * @param <X> The represented type that contains the attribute
 * @param <Y> The type of the represented attribute
 *
 * @since 2.0
 */
public interface Attribute<X, Y> {

        enum PersistentAttributeType {

             /** Many-to-one association */
             MANY_TO_ONE, 

              /** One-to-one association */
             ONE_TO_ONE, 

             /** Basic attribute */
             BASIC, 

             /** Embeddable class attribute */
             EMBEDDED,

             /** Many-to-many association */
             MANY_TO_MANY, 

             /** One-to-many association */
             ONE_TO_MANY, 

             /** Element collection */
             ELEMENT_COLLECTION
        }

    /**
     * Return the name of the attribute.
     * @return name
     */
    String getName();

    /**
     * Return the persistent attribute type for the attribute.
     * @return persistent attribute type
     */
    PersistentAttributeType getPersistentAttributeType();

    /**
     * Return the managed type representing the type in which 
     * the attribute was declared.
     * @return declaring type
     */
    ManagedType<X> getDeclaringType();

    /**
     * Return the Java type of the represented attribute.
     * @return Java type
     */
    Class<Y> getJavaType();

    /**
     * Return the {@link java.lang.reflect.Member} for the
         *  represented attribute.
     * @return corresponding {@link java.lang.reflect.Member}
     */
    java.lang.reflect.Member getJavaMember();

    /**
     * Is the attribute an association.
     * @return boolean indicating whether the attribute 
     *         corresponds to an association
     */
    boolean isAssociation();

    /**
     * Is the attribute collection-valued (represents a
         * {@code Collection}, {@code Set}, {@code List}, or
         * {@code Map}).
     * @return boolean indicating whether the attribute is 
     *         collection-valued
     */
    boolean isCollection();
}
/**
 * An instance of {@code BasicType} represents a
 * {@linkplain jakarta.persistence.Basic basic type}
 * (possibly an {@linkplain jakarta.persistence.Enumerated
 * enumerated}, {@linkplain jakarta.persistence.Lob LOB}, or
 * {@linkplain jakarta.persistence.Temporal temporal} type).
 *
 * @param <X> The represented basic type
 *
 * @since 2.0
 */
public interface BasicType<X> extends Type<X> {}
import jakarta.persistence.criteria.Path;

/**
 * An instances of the type {@code Bindable} represents an object
 * or attribute type that can be bound into a {@link Path Path}.
 *
 * @param <T> The type of the represented object or attribute
 *
 * @since 2.0
 *
 */
public interface Bindable<T> {

    enum BindableType {
        /**
         * Single-valued attribute type.
         *
         * @see SingularAttribute
         */
        SINGULAR_ATTRIBUTE, 

        /**
         * Multivalued attribute type, that is, a collection.
         *
         * @see PluralAttribute
         */
        PLURAL_ATTRIBUTE, 

        /**
         * Entity type.
         *
         * @see EntityType
         */
        ENTITY_TYPE
    }

    /**
     * Return the bindable type of the represented object.
     * @return bindable type
     */        
    BindableType getBindableType();

    /**
     * Return the Java type of the represented object.
     * If the bindable type of the object is {@code PLURAL_ATTRIBUTE},
     * the Java element type is returned. If the bindable type is
     * {@code SINGULAR_ATTRIBUTE} or {@code ENTITY_TYPE}, 
     * the Java type of the
     * represented entity or attribute is returned.
     * @return Java type
     */
    Class<T> getBindableJavaType();
}
/**
 * Instances of the type {@code CollectionAttribute} represent
 * persistent {@link java.util.Collection}-valued attributes.
 *
 * @param <X> The type the represented Collection belongs to
 * @param <E> The element type of the represented Collection
 *
 * @since 2.0
 *
 */
public interface CollectionAttribute<X, E> 
        extends PluralAttribute<X, java.util.Collection<E>, E> {}
/**
 * An instance of {@code EmbeddableType} represents an
 * {@linkplain jakarta.persistence.Embeddable embeddable}
 * type.
 *
 * @param <X> The represented embeddable type.
 *
 * @since 2.0
 */
public interface EmbeddableType<X> extends ManagedType<X> {}
/**
 * An instance of {@code EntityType} represents
 * an {@linkplain jakarta.persistence.Entity entity}
 * type.
 *
 * @param <X> The represented entity type.
 *
 * @since 2.0
 */
public interface EntityType<X> 
            extends IdentifiableType<X>, Bindable<X>{

    /**
     * Return the entity name.
     * @return entity name
     */
    String getName();
}
import java.util.Set;

/**
 * An instance of the type {@code IdentifiableType} represents an
 * entity or mapped superclass type.
 *
 * @param <X> The represented entity or mapped superclass type.
 *
 * @since 2.0
 *
 */
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
     *         type is not present in the identifiable type or if
     *         the identifiable type has an id class
     */
    <Y> SingularAttribute<? super X, Y> getId(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
     *         type is not declared in the identifiable type or if
     *         the identifiable type has an id class
     */
    <Y> SingularAttribute<X, Y> getDeclaredId(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 type is not present in the identifiable type
     */
    <Y> SingularAttribute<? super X, Y> getVersion(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 
     *         type is not declared in the identifiable type
     */
    <Y> SingularAttribute<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 or null if no 
     *         such supertype
     */
    IdentifiableType<? super X> getSupertype();

    /**
     * Whether the identifiable type has a single id attribute.
     * Returns true for a simple id or embedded id; returns false
     * for an idclass.
     * @return boolean indicating whether the identifiable
     *         type has a single id attribute
     */
    boolean hasSingleIdAttribute();

    /**
     * Whether the identifiable type has a version attribute.
     * @return boolean indicating whether the identifiable
     *         type has a version attribute
     */
    boolean hasVersionAttribute();

    /**
     *  Return the attributes corresponding to the id class of the
     *  identifiable type.
     *  @return id attributes
     *  @throws IllegalArgumentException if the identifiable type
     *          does not have an id class
     */
     Set<SingularAttribute<? super X, ?>> getIdClassAttributes();

    /**
     * Return the type that represents the type of the id.
     * @return type of id
     */
    Type<?> getIdType();
}
/**
 * Instances of the type {@code ListAttribute} represent persistent 
 * {@link java.util.List}-valued attributes.
 *
 * @param <X> The type the represented List belongs to
 * @param <E> The element type of the represented List
 *
 * @since 2.0
 *
 */
public interface ListAttribute<X, E> 
                extends PluralAttribute<X, java.util.List<E>, E> {}
import java.util.Set;

/**
 *  Instances of the type {@code ManagedType} represent entity, mapped 
 *  superclass, and embeddable types.
 *
 *  @param <X> The represented type.
 *
 *  @since 2.0
 *
 */
public interface ManagedType<X> extends Type<X> {

    /**
     * Return the attributes of the managed type.
     * @return attributes of the managed type
     */
     Set<Attribute<? super X, ?>> getAttributes();

    /**
     * Return the attributes declared by the managed type.
     * Returns empty set if the managed type has no declared
     * attributes.
     * @return declared attributes of the managed type
     */
     Set<Attribute<X, ?>> getDeclaredAttributes();

    /**
     * Return the single-valued attribute of the managed 
     * type that corresponds to the specified name and Java type.
     * @param name  the name of the represented attribute
     * @param type  the type of the represented attribute
     * @return single-valued attribute with given name and type
     * @throws IllegalArgumentException if attribute of the given
     *         name and type is not present in the managed type
     */
    <Y> SingularAttribute<? super X, Y> getSingularAttribute(String name, Class<Y> type);

    /**
     * Return the single-valued attribute declared by the 
     * managed type that corresponds to the specified name and 
     * Java type.
     * @param name  the name of the represented attribute
     * @param type  the type of the represented attribute
     * @return declared single-valued attribute of the given 
     *         name and type
     * @throws IllegalArgumentException if attribute of the given
     *         name and type is not declared in the managed type
     */
    <Y> SingularAttribute<X, Y> getDeclaredSingularAttribute(String name, Class<Y> type);

    /**
     * Return the single-valued attributes of the managed type.
     * Returns empty set if the managed type has no single-valued
     * attributes.
     * @return single-valued attributes
     */
    Set<SingularAttribute<? super X, ?>> getSingularAttributes();

    /**
     * Return the single-valued attributes declared by the managed
     * type.
     * Returns empty set if the managed type has no declared
     * single-valued attributes.
     * @return declared single-valued attributes
     */
    Set<SingularAttribute<X, ?>> getDeclaredSingularAttributes();

    /**
     * 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 CollectionAttribute 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> CollectionAttribute<? super X, E> getCollection(String name, Class<E> elementType);

    /**
     * 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 {@code CollectionAttribute} of the given name and 
     *         element type
     * @throws IllegalArgumentException if attribute of the given
     *         name and type is not declared in the managed type
     */
    <E> CollectionAttribute<X, E> getDeclaredCollection(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 SetAttribute of the given name and element type
     * @throws IllegalArgumentException if attribute of the given
     *         name and type is not present in the managed type
     */
    <E> SetAttribute<? super X, E> getSet(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 SetAttribute of the given name and 
     *         element type
     * @throws IllegalArgumentException if attribute of the given
     *         name and type is not declared in the managed type
     */
    <E> SetAttribute<X, E> getDeclaredSet(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 ListAttribute of the given name and element type
     * @throws IllegalArgumentException if attribute of the given
     *         name and type is not present in the managed type
     */
    <E> ListAttribute<? super X, E> getList(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 ListAttribute of the given name and 
     *         element type
     * @throws IllegalArgumentException if attribute of the given
     *         name and type is not declared in the managed type
     */
    <E> ListAttribute<X, E> getDeclaredList(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 MapAttribute 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> MapAttribute<? super X, K, V> getMap(String name, 
                                                Class<K> keyType, 
                                                Class<V> valueType);

    /**
     * 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 MapAttribute of the given name and key 
     *         and value types
     * @throws IllegalArgumentException if attribute of the given
     *         name and type is not declared in the managed type
     */
    <K, V> MapAttribute<X, K, V> getDeclaredMap(String name, 
                                                Class<K> keyType, 
                                                Class<V> valueType);

    /**
     * Return all multi-valued attributes (Collection-, Set-,
     * List-, and Map-valued attributes) of the managed type.
     * Returns empty set if the managed type has no multi-valued
     * attributes.
     * @return Collection-, Set-, List-, and Map-valued attributes
     */
    Set<PluralAttribute<? super X, ?, ?>> getPluralAttributes();

    /**
     * Return all multi-valued attributes (Collection-, Set-,
     * List-, and Map-valued attributes) declared by the 
     * managed type.
     * Returns empty set if the managed type has no declared
     * multivalued attributes.
     * @return declared Collection-, Set-, List-, and Map-valued
     *         attributes
     */
    Set<PluralAttribute<X, ?, ?>> getDeclaredPluralAttributes();

//String-based:

    /**
     * Return the attribute of the managed
     * type that corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return attribute with given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not present in the managed type
     */
    Attribute<? super X, ?> getAttribute(String name); 

    /**
     * Return the attribute declared by the managed
     * type that corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return attribute with given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not declared in the managed type
     */
    Attribute<X, ?> getDeclaredAttribute(String name); 

    /**
     * Return the single-valued attribute of the managed type that
     * corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return single-valued attribute with the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not present in the managed type
     */
    SingularAttribute<? super X, ?> getSingularAttribute(String name);

    /**
     * Return the single-valued attribute declared by the managed
     * type that corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return declared single-valued attribute of the given 
     *         name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not declared in the managed type
     */
    SingularAttribute<X, ?> getDeclaredSingularAttribute(String name);

    /**
     * Return the Collection-valued attribute of the managed type 
     * that corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return CollectionAttribute of the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not present in the managed type
     */    
    CollectionAttribute<? super X, ?> getCollection(String name); 

    /**
     * Return the Collection-valued attribute declared by the 
     * managed type that corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return declared CollectionAttribute of the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not declared in the managed type
     */
    CollectionAttribute<X, ?> getDeclaredCollection(String name); 

    /**
     * Return the Set-valued attribute of the managed type that
     * corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return SetAttribute of the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not present in the managed type
     */
    SetAttribute<? super X, ?> getSet(String name);

    /**
     * Return the Set-valued attribute declared by the managed type 
     * that corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return declared SetAttribute of the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not declared in the managed type
     */
    SetAttribute<X, ?> getDeclaredSet(String name);

    /**
     * Return the List-valued attribute of the managed type that
     * corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return ListAttribute of the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not present in the managed type
     */
    ListAttribute<? super X, ?> getList(String name);

    /**
     * Return the List-valued attribute declared by the managed 
     * type that corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return declared ListAttribute of the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not declared in the managed type
     */
    ListAttribute<X, ?> getDeclaredList(String name);

    /**
     * Return the Map-valued attribute of the managed type that
     * corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return MapAttribute of the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not present in the managed type
     */
    MapAttribute<? super X, ?, ?> getMap(String name); 

    /**
     * Return the Map-valued attribute declared by the managed 
     * type that corresponds to the specified name.
     * @param name  the name of the represented attribute
     * @return declared MapAttribute of the given name
     * @throws IllegalArgumentException if attribute of the given
     *         name is not declared in the managed type
     */
    MapAttribute<X, ?, ?> getDeclaredMap(String name);
}
/**
 * Instances of the type {@code MapAttribute} represent
 * persistent {@link java.util.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
 *
 * @since 2.0
 *
 */
public interface MapAttribute<X, K, V> 
        extends PluralAttribute<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();
}
package jakarta.persistence.metamodel;

/**
 * An instance of the type {@code MappedSuperclassType} represents a
 * {@linkplain jakarta.persistence.MappedSuperclass mapped superclass}
 * type.
 *
 * @param <X> The represented mapped superclass type
 *
 * @since 2.0
 */
public interface MappedSuperclassType<X> extends IdentifiableType<X> {}
/**
 * Instances of the type {@code PluralAttribute} represent 
 * persistent collection-valued attributes.
 *
 * @param <X> The type the represented collection belongs to
 * @param <C> The type of the represented collection
 * @param <E> The element type of the represented collection
 *
 * @since 2.0
 */
public interface PluralAttribute<X, C, E> 
                extends Attribute<X, C>, Bindable<E> {

        enum CollectionType {

            /** Collection-valued attribute */
            COLLECTION, 

            /** Set-valued attribute */
            SET, 

            /** List-valued attribute */
            LIST, 

            /** Map-valued attribute */
            MAP
        }

    /**
     * Return the collection type.
     * @return collection type
     */
    CollectionType getCollectionType();

    /**
     * Return the type representing the element type of the 
     * collection.
     * @return element type
     */
    Type<E> getElementType();
}
/**
 * Instances of the type {@code SetAttribute} represent
 * persistent {@link java.util.Set}-valued attributes.
 *
 * @param <X> The type the represented Set belongs to
 * @param <E> The element type of the represented Set
 *
 * @since 2.0
 */
public interface SetAttribute<X, E> 
        extends PluralAttribute<X, java.util.Set<E>, E> {} 
package jakarta.persistence.metamodel;

/**
 * Instances of the type {@code SingularAttribute} represents persistent
 * single-valued properties or fields.
 *
 * @param <X> The type containing the represented attribute
 * @param <T> The type of the represented attribute
 *
 * @since 2.0
 */
public interface SingularAttribute<X, T> 
                extends Attribute<X, T>, Bindable<T> {

    /**
     * Is the attribute an id attribute? This method returns true
     * if the attribute is a {@linkplain jakarta.persistence.Id simple
     * id}, an {@linkplain jakarta.persistence.EmbeddedId embedded id},
     * or an attribute of an {@linkplain jakarta.persistence.IdClass
     * id class}.
     * @return boolean indicating whether the attribute is an id
     */
    boolean isId();

    /**
     * Is the attribute a {@linkplain jakarta.persistence.Version
     * version} attribute?
     * @return boolean indicating whether the attribute is a
     *         version attribute
     */
    boolean isVersion();

    /** 
     * Can the attribute be null?
     * @return boolean indicating whether the attribute can
     *        be null
     * @see jakarta.persistence.Basic#optional
     */
    boolean isOptional();

    /**
     * Return the type that represents the type of the attribute.
     * @return type of attribute
     */
    Type<T> getType();
}
/**
 * An instance of the type {@code Type} represents a persistent
 * object or attribute type.
 *
 * @param <X>  The type of the represented object or attribute
 *
 * @since 2.0
 */
public interface Type<X> {

    enum PersistenceType {

        /** Entity class */
        ENTITY,

        /** Embeddable class */
        EMBEDDABLE,

        /** Mapped superclass */
        MAPPED_SUPERCLASS,

        /** Basic type */
        BASIC
    }

    /**
     * Return the persistence type.
     * @return persistence type
     */        
    PersistenceType getPersistenceType();

    /**
     * Return the represented Java type.
     * @return Java type
     */
    Class<X> getJavaType();
}
import java.security.ProtectionDomain;

/**
 * A persistence provider supplies an instance of this 
 * interface to the {@link PersistenceUnitInfo#addTransformer}
 * method. The supplied transformer instance will get 
 * called to transform entity class files when they are 
 * loaded or redefined. The transformation occurs before  
 * the class is defined by the JVM.
 *
 * @since 1.0
 */
public interface ClassTransformer {

    /**
     * Invoked when a class is being loaded or redefined.
     * The implementation of this method may transform the 
     * supplied class file and return a new replacement class 
     * file.
     *
     * @param loader  the defining loader of the class to be 
     *        transformed, may be null if the bootstrap loader
     * @param className  the name of the class in the internal form 
     *        of fully qualified class and interface names
     * @param classBeingRedefined  if this is a redefine, the 
     *        class being redefined, otherwise null
     * @param protectionDomain  the protection domain of the 
     *        class being defined or redefined
     * @param classfileBuffer  the input byte buffer in class 
     *        file format - must not be modified
     * @return a well-formed class file buffer (the result of 
     *         the transform), or null if no transform is performed
     * @throws TransformerException  if the input does
     *         not represent a well-formed class file
     */
    byte[] transform(ClassLoader loader,
                     String className,
                     Class<?> classBeingRedefined,
                     ProtectionDomain protectionDomain, 
                     byte[] classfileBuffer) 
        throws TransformerException;
}
/**
 * Load states returned by the {@link ProviderUtil} SPI methods.
 * @since 2.0
 *
 */
public enum LoadState {
    /** The state of the element is known to have been loaded. */
    LOADED,
    /** The state of the element is known not to have been loaded. */
    NOT_LOADED,
    /** The load state of the element cannot be determined. */
    UNKNOWN
}
package jakarta.persistence.spi;

import jakarta.persistence.EntityManagerFactory;
import jakarta.persistence.Persistence;
import jakarta.persistence.PersistenceConfiguration;
import jakarta.persistence.PersistenceException;
import java.util.Map;

/**
 * Interface implemented by the persistence provider.
 *
 * It is invoked by the container in Jakarta EE environments and
 * by the {@link Persistence} class in Java SE environments to create
 * an {@link EntityManagerFactory} and/or to cause schema generation
 * to occur.
 *
 * @since 1.0
 */
public interface PersistenceProvider {

    /**
     * Called by {@link Persistence} class when an
     * {@link 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 {@code persistence.xml} file or specify values for
     * properties not specified in the {@code 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
     *
     * @see Persistence#createEntityManagerFactory(String, Map)
     */
    EntityManagerFactory createEntityManagerFactory(String emName, Map<?, ?> map);

    /**
     * Called by {@link Persistence} class when an
     * {@link EntityManagerFactory} is to be created.
     *
     * @param configuration  the configuration of the persistence unit
     * @return EntityManagerFactory for the persistence unit,
     * or null if the provider is not the right provider
     * @throws IllegalStateException if required configuration is missing
     *
     * @see Persistence#createEntityManagerFactory(PersistenceConfiguration)
     *
     * @since 3.2
     */
    EntityManagerFactory createEntityManagerFactory(PersistenceConfiguration configuration);

    /**
     * Called by the container when an {@link 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). These properties may include properties to
     * control schema generation. If a Bean Validation provider is
     * present in the classpath, the container must pass the
     * {@code ValidatorFactory} instance in the map with the key
     * {@code "jakarta.persistence.validation.factory"}. If the
     * containing archive is a bean archive, the container must
     * pass the {@code BeanManager} instance in the map with the
     * key {@code "jakarta.persistence.bean.manager"}.
     * @return {@link EntityManagerFactory} for the persistence unit
     * specified by the metadata
     */
    EntityManagerFactory createContainerEntityManagerFactory(PersistenceUnitInfo info, Map<?, ?> map);

    /**
     * Create database schemas and/or tables and/or create DDL
     * scripts as determined by the supplied properties.
     * <p>
     * Called by the container when schema generation is to
     * occur as a separate phase from creation of the entity
     * manager factory.
     * <p>
     * @param info metadata for use by the persistence provider
     * @param map properties for schema generation;  these may
     *            also include provider-specific properties
     * @throws PersistenceException if insufficient or inconsistent
     *         configuration information is provided of if schema
     *         generation otherwise fails
     *
     * @since 2.1
     */
    void generateSchema(PersistenceUnitInfo info, Map<?, ?> map);

    /**
     * Create database schemas and/or tables and/or create DDL
     * scripts as determined by the supplied properties.
     * <p>
     * Called by the {@link Persistence} class when schema generation
     * is to occur as a separate phase from creation of the entity
     * manager factory.
     * <p>
     * @param persistenceUnitName the name of the persistence unit
     * @param map properties for schema generation;  these may
     *            also contain provider-specific properties.  The
     *            value of these properties override any values that
     *            may have been configured elsewhere.
     * @return true  if schema was generated, otherwise false
     * @throws PersistenceException if insufficient or inconsistent
     *         configuration information is provided or if schema
     *         generation otherwise fails
     *
     * @since 2.1
     */
    boolean generateSchema(String persistenceUnitName, Map<?, ?> map);

    /**
     * Return the utility interface implemented by the persistence
     * provider.
     * @return an instance of {@link ProviderUtil}
     *
     * @since 2.0
     */
    ProviderUtil getProviderUtil();
}
import java.util.List;

/**
 * Provides a list of {@linkplain PersistenceProvider persistence
 * providers} available in the runtime environment.
 * 
 * Implementations must be thread-safe.
 *
 * Note that the {@link #getPersistenceProviders} method can
 * potentially be called many times: it is recommended that the
 * implementation of this method make use of caching.
 *
 * @see PersistenceProvider
 * @since 2.0
 */
public interface PersistenceProviderResolver {

    /**
     * Returns a list of the {@linkplain PersistenceProvider
     * persistence provider} implementations available in the
     * runtime environment.
     *
     * @return list of the persistence providers available 
     *         in the environment
     */
    List<PersistenceProvider> getPersistenceProviders();

    /**
     * Clear cache of providers.
     */
    void clearCachedProviders();
} 
package jakarta.persistence.spi;

import java.lang.ref.ReferenceQueue;
import java.lang.ref.SoftReference;
import java.lang.ref.WeakReference;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.ArrayList;
import java.util.List;
import java.util.HashMap;
import java.util.Iterator;
import java.util.ServiceConfigurationError;
import java.util.ServiceLoader;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Holds the global {@link PersistenceProviderResolver} instance.
 * If no {@code PersistenceProviderResolver} is set by the environment,
 * the default {@code PersistenceProviderResolver} is used.
 *
 * Enable {@code "jakarta.persistence.spi"} logger to show diagnostic
 * information.
 * 
 * Implementations must be thread-safe.
 * 
 * @since 2.0
 */
public class PersistenceProviderResolverHolder {

    private static PersistenceProviderResolver singleton = new DefaultPersistenceProviderResolver();

    /**
     * Returns the current persistence provider resolver.
     * 
     * @return the current persistence provider resolver
     */
    public static PersistenceProviderResolver getPersistenceProviderResolver() {
        return singleton;
    }

    /**
     * Defines the persistence provider resolver used.
     * 
     * @param resolver persistence provider resolver to be used.
     */
    public static void setPersistenceProviderResolver(PersistenceProviderResolver resolver) {
        if (resolver == null) {
            singleton = new DefaultPersistenceProviderResolver();
        } else {
            singleton = resolver;
        }
    }

    /**
     * Default provider resolver class to use when none is explicitly set.
     * 
     * <p>Uses service loading mechanism as described in the Jakarta Persistence
     * specification. A ServiceLoader.load() call is made with the current context
     * classloader to find the service provider files on the classpath.
     */
    private static class DefaultPersistenceProviderResolver implements PersistenceProviderResolver {

        /**
         * Cached list of available providers cached by CacheKey to ensure
         * there is not potential for provider visibility issues. 
         */
        private volatile HashMap<CacheKey, PersistenceProviderReference> providers = new HashMap<CacheKey, PersistenceProviderReference>();

        /**
         * Queue for reference objects referring to class loaders or persistence providers.
         */
        private static final ReferenceQueue referenceQueue = new ReferenceQueue();

        public List<PersistenceProvider> getPersistenceProviders() {
            // Before we do the real loading work, see whether we need to
            // do some cleanup: If references to class loaders or
            // persistence providers have been nulled out, remove all related
            // information from the cache.
            processQueue();

            ClassLoader loader = getContextClassLoader();
            CacheKey cacheKey = new CacheKey(loader);
            PersistenceProviderReference providersReferent = this.providers.get(cacheKey);
            List<PersistenceProvider> loadedProviders = null;

            if (providersReferent != null) {
                loadedProviders = providersReferent.get();
            }

            if (loadedProviders == null) {
                loadedProviders = new ArrayList<>();
                Iterator<PersistenceProvider> ipp = ServiceLoader.load(PersistenceProvider.class, loader).iterator();
                try {
                    while (ipp.hasNext()) {
                        try {
                            PersistenceProvider pp = ipp.next();
                            loadedProviders.add(pp);
                        } catch (ServiceConfigurationError sce) {
                            log(Level.FINEST, sce.toString());
                        }
                    }
                } catch (ServiceConfigurationError sce) {
                    log(Level.FINEST, sce.toString());
                }

                // If none are found we'll log the provider names for diagnostic
                // purposes.
                if (loadedProviders.isEmpty()) {
                    log(Level.WARNING, "No valid providers found.");
                }

                providersReferent = new PersistenceProviderReference(loadedProviders, referenceQueue, cacheKey);

                this.providers.put(cacheKey, providersReferent);
            }

            return loadedProviders;
        }

        /**
         * Remove garbage collected cache keys & providers.
         */
        private void processQueue() {
            CacheKeyReference ref;
            while ((ref = (CacheKeyReference) referenceQueue.poll()) != null) {
                providers.remove(ref.getCacheKey());
            }            
        }

        /**
         * Wraps {@code Thread.currentThread().getContextClassLoader()} into a
         * doPrivileged block if security manager is present
         */
        private static ClassLoader getContextClassLoader() {
            if (System.getSecurityManager() == null) {
                return Thread.currentThread().getContextClassLoader();
            } else {
                return AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
                    public ClassLoader run() {
                        return Thread.currentThread().getContextClassLoader();
                    }
                });
            }
        }

        private static final String LOGGER_SUBSYSTEM = "jakarta.persistence.spi";

        private Logger logger;

        private void log(Level level, String message) {
            if (this.logger == null) {
                this.logger = Logger.getLogger(LOGGER_SUBSYSTEM);
            }
            this.logger.log(level, LOGGER_SUBSYSTEM + "::" + message);
        }

        /**
         * Clear all cached providers
         */
        public void clearCachedProviders() {
            this.providers.clear();
        }

        /**
         * The common interface to get a CacheKey implemented by
         * LoaderReference and PersistenceProviderReference.
         */
        private interface CacheKeyReference {
            CacheKey getCacheKey();
        }        

        /**
          * Key used for cached persistence providers. The key checks
          * the class loader to determine if the persistence providers
          * is a match to the requested one. The loader may be null.
          */
        private class CacheKey implements Cloneable {

            /* Weak Reference to ClassLoader */
            private LoaderReference loaderRef;

            /* Cached Hashcode */
            private int hashCodeCache;

            CacheKey(ClassLoader loader) {
                if (loader == null) {
                    this.loaderRef = null;
                } else {
                    loaderRef = new LoaderReference(loader, referenceQueue, this);
                }
                calculateHashCode();
            }

            ClassLoader getLoader() {
                return (loaderRef != null) ? loaderRef.get() : null;
            }

            public boolean equals(Object other) {
                if (this == other) {
                    return true;
                }
                try {
                    final CacheKey otherEntry = (CacheKey) other;
                    // quick check to see if they are not equal
                    if (hashCodeCache != otherEntry.hashCodeCache) {
                        return false;
                    }
                    // are refs (both non-null) or (both null)?
                    if (loaderRef == null) {
                        return otherEntry.loaderRef == null;
                    }
                    ClassLoader loader = loaderRef.get();
                    return (otherEntry.loaderRef != null)
                    // with a null reference we can no longer find
                    // out which class loader was referenced; so
                    // treat it as unequal
                    && (loader != null) && (loader == otherEntry.loaderRef.get());
                } catch (NullPointerException e) {
                } catch (ClassCastException e) {
                }

                return false;
            }

            public int hashCode() {
                return hashCodeCache;
            }

            private void calculateHashCode() {
                ClassLoader loader = getLoader();
                if (loader != null) {
                    hashCodeCache = loader.hashCode();
                }
            }

            public Object clone() {
                try {
                    CacheKey clone = (CacheKey) super.clone();
                    if (loaderRef != null) {
                        clone.loaderRef = new LoaderReference(loaderRef.get(), referenceQueue, clone);
                    }
                    return clone;
                } catch (CloneNotSupportedException e) {
                    // this should never happen
                    throw new InternalError();
                }
            }

            public String toString() {
                return "CacheKey[" + getLoader() + ")]";
            }
        }

       /**
         * References to class loaders are weak references, so that they can be
         * garbage collected when nobody else is using them. The DefaultPersistenceProviderResolver 
         * class has no reason to keep class loaders alive.
         */
        private class LoaderReference extends WeakReference<ClassLoader> 
                implements CacheKeyReference {
            private CacheKey cacheKey;

            @SuppressWarnings("unchecked")
            LoaderReference(ClassLoader referent, ReferenceQueue q, CacheKey key) {
                super(referent, q);
                cacheKey = key;
            }

            public CacheKey getCacheKey() {
                return cacheKey;
            }
        }

        /**
         * References to persistence provider are soft references so that they can be garbage
         * collected when they have no hard references.
         */
        private class PersistenceProviderReference extends SoftReference<List<PersistenceProvider>>
                implements CacheKeyReference {
            private CacheKey cacheKey;

            @SuppressWarnings("unchecked")
            PersistenceProviderReference(List<PersistenceProvider> referent, ReferenceQueue q, CacheKey key) {
                super(referent, q);
                cacheKey = key;
            }

            public CacheKey getCacheKey() {
                return cacheKey;
            }
        }
    }
}
package jakarta.persistence.spi;

import javax.sql.DataSource;
import java.util.List;
import java.util.Properties;
import java.net.URL;
import jakarta.persistence.SharedCacheMode;
import jakarta.persistence.ValidationMode;
import jakarta.persistence.EntityManagerFactory;

/**
 * Interface implemented by the container and used by the persistence
 * provider when creating an {@link EntityManagerFactory}.
 *
 * @since 1.0
 */
public interface PersistenceUnitInfo {

    /**
     * Returns the name of the persistence unit. Corresponds to the
     * {@code name} attribute in the {@code persistence.xml} file.
     * @return the name of the persistence unit
     */
    String getPersistenceUnitName();

    /**
     * Returns the fully qualified name of the persistence provider
     * implementation class. Corresponds to the {@code provider} element
     * in the {@code persistence.xml} file.
     * @return  the fully qualified name of the persistence provider 
     * implementation class
     */
    String getPersistenceProviderClassName();

    /**
     * Returns the fully-qualified class name of an annotation annotated
     * {@code Scope} or {@code NormalScope}. Corresponds to the {@code scope}
     * element in {@code persistence.xml}.
     * @return  the fully-qualified class name of the scope annotation,
     *          or null if no scope was explicitly specified
     */
    public String getScopeAnnotationName();

    /**
     * Returns the fully-qualified class names of annotations annotated
     * {@code Qualifier}. Corresponds to the {@code qualifier} element in
     * {@code persistence.xml}.
     * @return  the fully-qualified class names of the qualifier annotations,
     *          or an empty list if no qualifier annotations were explicitly
     *          specified
     */
    public List<String> getQualifierAnnotationNames();

    /**
     * Returns the transaction type of the entity managers created by
     * the {@link EntityManagerFactory}. The transaction type corresponds
     * to the {@code transaction-type} attribute in the {@code persistence.xml}
     * file.
     * @return  transaction type of the entity managers created
     * by the EntityManagerFactory
     *
     * <p>Note: This method will change its return type to {@link jakarta.persistence.PersistenceUnitTransactionType}
     * in the next major version.
     */
    PersistenceUnitTransactionType getTransactionType();

    /**
     * Returns the JTA-enabled data source to be used by the
     * persistence provider. The data source corresponds to the
     * {@code jta-data-source} element in the {@code persistence.xml}
     * file or is provided at deployment or by the container.
     * @return the JTA-enabled data source to be used by the 
     * persistence provider
     */
    DataSource getJtaDataSource();

    /**
     * Returns the non-JTA-enabled data source to be used by the
     * persistence provider for accessing data outside a JTA
     * transaction. The data source corresponds to the named
     * {@code non-jta-data-source} element in the {@code persistence.xml}
     * file or provided at deployment or by the container.
     * @return the non-JTA-enabled data source to be used by the 
     * persistence provider for accessing data outside a JTA 
     * transaction
     */
    DataSource getNonJtaDataSource();

    /**
     * Returns the list of the names of the mapping files that the
     * persistence provider must load to determine the mappings for
     * the entity classes. The mapping files must be in the standard
     * XML mapping format, be uniquely named and be resource-loadable
     * from the application classpath.  Each mapping file name
     * corresponds to a {@code mapping-file} element in the
     * {@code persistence.xml} file.
     * @return the list of mapping file names that the persistence
     * provider must load to determine the mappings for the entity
     * classes 
     */
    List<String> getMappingFileNames();

    /**
     * Returns a list of URLs for the jar files or exploded jar
     * file directories that the persistence provider must examine
     * for managed classes of the persistence unit. Each URL
     * corresponds to a {@code jar-file} element in the
     * {@code persistence.xml} file. A URL will either be a
     * file: URL referring to a jar file or referring to a directory
     * that contains an exploded jar file, or some other URL from
     * which an InputStream in jar format can be obtained.
     * @return a list of URL objects referring to jar files or
     * directories 
     */
    List<URL> getJarFileUrls();

    /**
     * Returns the URL for the jar file or directory that is the
     * root of the persistence unit. (If the persistence unit is
     * rooted in the WEB-INF/classes directory, this is the URL
     * of that directory.)
     * The URL will either be a file: URL referring to a jar file 
     * or referring to a directory that contains an exploded jar
     * file, or some other URL from which an InputStream in jar
     * format can be obtained.
     * @return a URL referring to a jar file or directory
     */
    URL getPersistenceUnitRootUrl();

    /**
     * Returns the list of the names of the classes that the
     * persistence provider must add to its set of managed
     * classes. Each name corresponds to a named {@code class} element in the
     * {@code persistence.xml} file.
     * @return the list of the names of the classes that the 
     * persistence provider must add to its set of managed 
     * classes 
     */
    List<String> getManagedClassNames();

    /**
     * Returns whether classes in the root of the persistence unit
     * that have not been explicitly listed are to be included in the
     * set of managed classes. This value corresponds to the
     * {@code exclude-unlisted-classes} element in the
     * {@code persistence.xml} file.
     * @return whether classes in the root of the persistence
     * unit that have not been explicitly listed are to be
     * included in the set of managed classes
     */
    boolean excludeUnlistedClasses();

    /**
     * Returns the specification of how the provider must use
     * a second-level cache for the persistence unit.
     * The result of this method corresponds to the {@code shared-cache-mode}
     * element in the {@code persistence.xml} file.
     * @return the second-level cache mode that must be used by the
     * provider for the persistence unit
     *
     * @since 2.0
     */
    SharedCacheMode getSharedCacheMode();

    /**
     * Returns the validation mode to be used by the persistence
     * provider for the persistence unit.  The validation mode
     * corresponds to the {@code validation-mode} element in the
     * {@code persistence.xml} file.
     * @return the validation mode to be used by the 
     * persistence provider for the persistence unit
     * 
     * @since 2.0
     */
    ValidationMode getValidationMode();

    /**
     * Returns a properties object. Each property corresponds to a
     * {@code property} element in the {@code persistence.xml} file
     * or to a property set by the container.
     * @return Properties object 
     */
    Properties getProperties();

    /**
     * Returns the schema version of the {@code persistence.xml} file.
     * @return {@code persistence.xml} schema version
     *
     * @since 2.0
     */
    String getPersistenceXMLSchemaVersion();

    /**
     * Returns ClassLoader that the provider may use to load any
     * classes, resources, or open URLs.
     * @return ClassLoader that the provider may use to load any 
     * classes, resources, or open URLs 
     */
    ClassLoader getClassLoader();

    /**
     * Add a transformer supplied by the provider that is called for
     * every new class definition or class redefinition that gets
     * loaded by the loader returned by the
     * {@link PersistenceUnitInfo#getClassLoader} method. The
     * transformer has no effect on the result returned by the
     * {@link PersistenceUnitInfo#getNewTempClassLoader} method.
     * Classes are only transformed once within the same classloading
     * scope, regardless of how many persistence units they may be 
     * a part of.
     * @param transformer   provider-supplied transformer that the
     * container invokes at class-(re)definition time
     */
    void addTransformer(ClassTransformer transformer);

    /**
     * Return a new instance of a {@link ClassLoader} that the provider
     * may use to temporarily load any classes, resources, or open
     * URLs. The scope and classpath of this loader is exactly the
     * same as that of the loader returned by {@link
     * PersistenceUnitInfo#getClassLoader}. None of the classes loaded
     * by this class loader are visible to application components. The
     * provider may only use this {@code ClassLoader} within the scope
     * of the {@link PersistenceProvider#createContainerEntityManagerFactory}
     * call.
     * @return temporary {@code ClassLoader} with same visibility as
     * current loader
     */
    ClassLoader getNewTempClassLoader();
}
import jakarta.persistence.FetchType;

/**
 * Utility interface implemented by the persistence provider. This
 * interface is invoked by the {@link jakarta.persistence.PersistenceUtil}
 * implementation to determine the load status of an entity or entity
 * attribute.
 *
 * @since 2.0
 */
public interface ProviderUtil { 

    /**
     * If the provider determines that the entity has been provided by
     * itself and that the state of the specified attribute has been loaded,
     * this method returns {@link LoadState#LOADED}.
     * <p> If the provider determines that the entity has been provided
     * by itself and that either entity attributes with {@link FetchType#EAGER}
     * have not been loaded or that the state of the specified attribute has
     * not been loaded, this method returns {@link LoadState#NOT_LOADED}.
     * <p> If a provider cannot determine the load state, this method
     * returns {@link LoadState#UNKNOWN}.
     * <p> The provider's implementation of this method must not obtain a
     * reference to an attribute value, as this could trigger the loading
     * of entity state if the entity has been provided by a different
     * provider.
     * @param entity  entity instance
     * @param attributeName  name of attribute whose load status is
     *        to be determined
     * @return load status of the attribute
     */
    LoadState isLoadedWithoutReference(Object entity, String attributeName);

    /**
     * If the provider determines that the entity has been provided by
     * itself and that the state of the specified attribute has been loaded,
     * this method returns {@link LoadState#LOADED}.
     * <p> If a provider determines that the entity has been provided by
     * itself and that either the entity attributes with {@link FetchType#EAGER}
     * have not been loaded or that the state of the specified attribute has
     * not been loaded, this method returns {@link LoadState#NOT_LOADED}.
     * <p> If the provider cannot determine the load state, this method
     * returns {@link LoadState#UNKNOWN}.
     * <p> The provider's implementation of this method is permitted to
     * obtain a reference to the attribute value. (This access is safe
     * because providers which might trigger the loading of the attribute
     * state will have already been determined by
     * {@link #isLoadedWithoutReference}.)
     *
     * @param entity  entity instance
     * @param attributeName  name of attribute whose load status is
     *        to be determined
     * @return load status of the attribute
     */
    LoadState isLoadedWithReference(Object entity, String attributeName);

    /**
     * If the provider determines that the entity has been provided by
     * itself and that the state of all attributes for which
     * {@link FetchType#EAGER} has been specified have been loaded, this
     * method returns {@link LoadState#LOADED}.
     * <p> If the provider determines that the entity has been provided
     * by itself and that not all attributes with {@link FetchType#EAGER}
     * have been loaded, this method returns {@link LoadState#NOT_LOADED}.
     * <p> If the provider cannot determine if the entity has been
     * provided by itself, this method returns {@link LoadState#UNKNOWN}.
     * <p> The provider's implementation of this method must not obtain
     * a reference to any attribute value, as this could trigger the
     * loading of entity state if the entity has been provided by a
     * different provider.
     * @param entity whose loaded status is to be determined
     * @return load status of the entity
     */
    LoadState isLoaded(Object entity);
}

Type	Name	Description	Default
String	name	(Required) The name of the relationship property whose mapping is being overridden if property-based access is being used, or the name of the relationship field if field-based access is used.
JoinColumn[]	joinColumns	The join column(s) being mapped to the persistent attribute(s). The joinColumns element must be specified if a foreign key mapping is used in the overriding of the mapping of the relationship. The joinColumns element must not be specified if a join table is used in the overriding of the mapping of the relationship
ForeignKey	foreignKey	(Optional) The foreign key constraint specification for the join columns. This is used only if table generation is in effect.	Provider’s default
JoinTable	joinTable	The join table that maps the relationship. The joinTable element must be specified if a join table is used in the overriding of the mapping of the relationship. The joinTable element must not be specified if a foreign key mapping is used in the overriding of the mapping of the relationship.	.

Type	Name	Description	Default
String	name	(Required) The name of the property whose mapping is being overridden if property-based access is being used, or the name of the field if field-based access is used.
Column	column	(Required) The column that is being mapped to the persistent attribute. The mapping type will remain the same as is defined in the embeddable class or mapped superclass.

Type	Name	Description	Default
FetchType	fetch	(Optional) 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.	EAGER
boolean	optional	(Optional) 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.	true

Type	Name	Description	Default
String	name	(Optional) The name of the collection table.	The concatenation of the name of the containing entity and the name of the collection attribute, separated by an underscore.
String	catalog	(Optional) The catalog of the table.	Default catalog.
String	schema	(Optional) The schema of the table.	Default schema for user.
JoinColumn[]	joinColumns	(Optional) The foreign key columns of the collection table which reference the primary table of the entity.	(Default only applies if a single join column is used.) The same defaults as for JoinColumn (i.e., the concatenation of the following: the name of the entity; “_”; the name of the referenced primary key column.) However, if there is more than one join column, a JoinColumn annotation must be specified for each join column using the JoinColumns annotation. Both the name and the referencedColumnName elements must be specified in each such JoinColumn annotation.
ForeignKey	foreignKey	(Optional) The foreign key constraint specification for the join columns. This is used only if table generation is in effect.	Provider’s default
UniqueConstraint[]	uniqueConstraints	(Optional) Unique constraints that are to be placed on the table. These are only used if table generation is in effect.	No additional constraints
Index[]	indexes	(Optional) Indexes for the table. These are only used if table generation is in effect.	No additional indexes
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.

Type	Name	Description	Default
String	name	(Optional) The name of the column.	The property or field name.
boolean	unique	(Optional) Whether the column 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 corresponds to only a single column. This constraint applies in addition to any constraint entailed by primary key mapping and to constraints specified at the table level.	false
boolean	nullable	(Optional) Whether the database column is nullable.	true
boolean	insertable	(Optional) Whether the column is included in SQL INSERT statements generated by the persistence provider.	true
boolean	updatable	(Optional) Whether the column is included in SQL UPDATE statements generated by the persistence provider.	true
String	columnDefinition	(Optional) The SQL fragment that is used when generating the DDL for the column. The specified DDL must be written in the native SQL dialect of the target database, and is not portable across databases.	Generated SQL to create a column of the inferred type.
String	options	(Optional) A SQL fragment appended to the generated DDL. The specified DDL must be written in the native SQL dialect of the target database, and is not portable across databases.	Nothing appended.
String	table	(Optional) The name of the table that contains the column. If absent the column is assumed to be in the primary table for the mapped object.	Column is in primary table.
int	length	(Optional) The column length Applies only to columns whose type is parameterized by length, for example, varchar or varbinary types.	255
int	precision	(Optional) The precision of a column of SQL type `decimal` or `numeric`, or of similar database-native type. Applies only to columns of exact numeric type. The default value `0` indicates that a provider-determined precision should be inferred.	0
int	scale	(Optional) The scale of a column of SQL type `decimal` or `numeric`, or of similar database-native type. Applies only to columns of exact numeric type. The default value `0` indicates that a provider-determined scale should be inferred.	0
int	secondPrecision	(Optional) The number of decimal digits to use for storing fractional seconds in a SQL time or timestamp column. Applies only to columns of time or timestamp type. The default value `-1` indicates that fractional seconds should not be stored in a time column, or that the maximum number of digits supported by the database and JDBC driver should be stored in a timestamp column.	-1
CheckConstraint[]	check	(Optional) Check constraints for the column. These are only used if table generation is in effect.	No check constraint
String	comment	(Optional) Comment for the column. This is only used if table generation is in effect.	No comment

Type	Name	Description	Default
Class	converter	(Optional) The converter to be applied.	No converter
String	attributeName	(Optional) The name of the attribute to convert. Must be specified unless the `Convert` annotation is applied to an attribute of basic type or to an element collection of basic type. Must not be specified otherwise.	The basic attribute or basic element collection attribute to which the annotation is applied
boolean	disableConversion	(Optional) Whether conversion of the attribute is to be disabled.	false

Type	Name	Description	Default
String	name	(Optional) The name of column to be used for the discriminator.	"DTYPE"
DiscriminatorType	discriminatorType	(Optional) The type of object/column to use as a class discriminator.	DiscriminatorType.STRING
String	columnDefinition	(Optional) The SQL fragment that is used when generating the DDL for the discriminator column.	Provider-generated SQL to create a column of the specified discriminator type.
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.
int	length	(Optional) The column length for String-based discriminator types. Ignored for other discriminator types.	31

Type	Name	Description	Default
Class	targetClass	(Optional) The basic or embeddable class that is the element type of the collection. Optional only if the collection field or property is defined using Java generics. Must be specified otherwise.	The parameterized type of the collection when defined using generics.
FetchType	fetch	(Optional) Whether the collection should be lazily loaded or must be eagerly fetched. The EAGER strategy is a requirement on the persistence provider runtime that the collection elements must be eagerly fetched. The LAZY strategy is a hint to the persistence provider runtime.	LAZY

Type	Name	Description	Default
String	name	(Optional) The name of the foreign key constraint.	A provider-generated name.
ConstraintMode	value	(Optional) Whether to generate a constraint.	CONSTRAINT
String	foreignKeyDefinition	(Optional) The foreign key constraint definition.	Provider-default. If the value of the `ConstraintMode` element is` NO_CONSTRAINT`, the provider must not generate a foreign key constraint.
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.

Type	Name	Description	Default
GenerationType	strategy	(Optional) The primary key generation strategy that the persistence provider must use to generate the annotated entity primary key.	GenerationType.AUTO
String	generator	(Optional) The name of the primary key generator to use as specified in the `SequenceGenerator` or `TableGenerator` annotation which declares the generator.	The entity name of the entity in which the annotation occurs.

Type	Name	Description	Default
String	name	(Optional) The name of the index.	A provider-generated name.
String	columnList	(Required) The names of the columns to be included in the index.
boolean	unique	(Optional) Whether the index is unique.	false
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.

Type	Name	Description	Default
JoinColumn[]	value	(Required) The join columns that map the relationship.
ForeignKey	foreignKey	(Optional) The foreign key constraint specification for the join columns. This is used only if table generation is in effect.	Provider’s default

Type	Name	Description	Default
String	name	(Optional) The name of the join table.	The concatenated names of the two associated primary entity tables (owning side first), separated by an underscore.
String	catalog	(Optional) The catalog of the table.	Default catalog.
String	schema	(Optional) The schema of the table.	Default schema for user.
JoinColumn[]	joinColumns	(Optional) The foreign key columns of the join table which reference the primary table of the entity owning the association (i.e. the owning side of the association).	The same defaults as for JoinColumn.
JoinColumn[]	inverseJoinColumns	(Optional) The foreign key columns of the join table which reference the primary table of the entity that does not own the association (i.e. the inverse side of the association).	The same defaults as for JoinColumn.
ForeignKey	foreignKey	(Optional) The foreign key constraint specification for the join columns. This is used only if table generation is in effect.	Provider’s default.
ForeignKey	inverseForeignKey	(Optional) The foreign key constraint specification for the inverse join columns. This is used only if table generation is in effect.	Provider’s default.
UniqueConstraint[]	uniqueConstraints	(Optional) Unique constraints that are to be placed on the table. These are only used if table generation is in effect.	No additional constraints
Index[]	indexes	(Optional) Indexes for the table. These are only used if table generation is in effect.	No additional indexes
CheckConstraint[]	check	(Optional) Check constraints for the table. These are only used if table generation is in effect.	No check constraint
String	comment	(Optional) Comment for the table. This is only used if table generation is in effect.	No comment
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.

Type	Name	Description	Default
Class	targetEntity	(Optional) The entity class that is the target of the association. Optional only if the collection-valued relationship property is defined using Java generics. Must be specified otherwise.	The parameterized type of the collection when defined using generics.
CascadeType[]	cascade	(Optional) The operations that must be cascaded to the target of the association.	No operations are cascaded.
FetchType	fetch	(Optional) Whether the association should be lazily loaded or must be eagerly fetched. The EAGER strategy is a requirement on the persistence provider runtime that the associated entities must be eagerly fetched. The LAZY strategy is a hint to the persistence provider runtime.	LAZY
String	mappedBy	The field or property that owns the relationship. Required unless the relationship is unidirectional.

Type	Name	Description	Default
String	name	(Optional) The name of the map key column. The table in which it is found depends upon the context. If the map key is for an element collection, the map key column is in the collection table for the map value. If the map key is for a ManyToMany entity relationship or for a OneToMany entity relationship using a join table, the map key column is in a join table. If the map key is for a OneToMany entity relationship using a foreign key mapping strategy, the map key column is in the table of the entity that is the value of the map.	The concatenation of the following: the name of the referencing property or field name; " `_` "; " `KEY` ".
boolean	unique	(Optional) Whether the column 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 corresponds to only a single column. This constraint applies in addition to any constraint entailed by primary key mapping and to constraints specified at the table level.	false
boolean	nullable	(Optional) Whether the database column is nullable.	true
boolean	insertable	(Optional) Whether the column is included in SQL INSERT statements generated by the persistence provider.	true
boolean	updatable	(Optional) Whether the column is included in SQL UPDATE statements generated by the persistence provider.	true
String	columnDefinition	(Optional) The SQL fragment that is used when generating the DDL for the column.	Generated SQL to create a column of the inferred type.
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.
String	table	(Optional) The name of the table that contains the column.	If the map key is for an element collection, the name of the collection table for the map value. If the map key is for a OneToMany or ManyToMany entity relationship using a join table, the name of the join table for the map. If the map key is for a OneToMany entity relationship using a foreign key mapping strategy, the name of the primary table of the entity that is the value of the map.
int	length	(Optional) The column length Applies only to columns whose type is parameterized by length, for example, varchar or varbinary types.	255
int	precision	(Optional) The precision of a column of SQL type `decimal` or `numeric`, or of similar database-native type. Applies only to columns of exact numeric type. The default value `0` indicates that a provider-determined precision should be inferred.	0
int	scale	(Optional) The scale of a column of SQL type `decimal` or `numeric`, or of similar database-native type. Applies only to columns of exact numeric type. The default value `0` indicates that a provider-determined scale should be inferred.	0

Type	Name	Description	Default
MapKeyJoinColumn[]	value	(Required) The map key join columns that are used to map to the entity that is the map key.
ForeignKey	foreignKey	(Optional) The foreign key constraint specification for the join columns. This is used only if table generation is in effect.	Provider’s default

Type	Name	Description	Default
String	name	(Optional) The name of the ordering column.	The concatenation of the name of the referencing property or field; " `_` "; " `ORDER` ".
boolean	nullable	(Optional) Whether the database column is nullable.	true
boolean	insertable	(Optional) Whether the column is included in SQL INSERT statements generated by the persistence provider.	true
boolean	updatable	(Optional) Whether the column is included in SQL UPDATE statements generated by the persistence provider.	true
String	columnDefinition	(Optional) The SQL fragment that is used when generating the DDL for the column.	Generated SQL to create a column of the inferred type.
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.

Type	Name	Description	Default
String	name	(Optional) The name of the primary key column of the current table.	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	(Optional) The name of the primary key column of the table being joined 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 of the table for the referenced entity (OneToOne mapping).
String	columnDefinition	(Optional) The SQL fragment that is used when generating the DDL for the column. This should not be specified for a OneToOne primary key association.	Generated SQL to create a column of the inferred type.
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.
ForeignKey	foreignKey	(Optional) The foreign key constraint specification for the join column. This is used only if table generation is in effect.	Provider’s default

Type	Name	Description	Default
PrimaryKeyJoinColumn[]	value	(Required) The primary key join columns.
ForeignKey	foreignKey	(Optional) The foreign key constraint specification for the join columns. This is used only if table generation is in effect.	Provider’s default

Type	Name	Description	Default
String	name	(Required) The name of the table.
String	catalog	(Optional) The catalog of the table.	Default catalog
String	schema	(Optional) The schema of the table.	Default schema for user
PrimaryKeyJoinColumn[]	pkJoinColumns	(Optional) The columns that are used to join with the primary table.	Column(s) of the same name(s) as the primary key column(s) in the primary table
ForeignKey	foreignKey	(Optional) The foreign key constraint for the join column. This is used only if table generation is in effect.	Provider’s default
UniqueConstraint[]	uniqueConstraints	(Optional) Unique constraints that are to be placed on the table. These are typically only used if table generation is in effect. These constraints apply in addition to any constraints specified by the Column and JoinColumn annotations and constraints entailed by primary key mappings.	No additional constraints
Index[]	indexes	(Optional) Indexes for the table. These are only used if table generation is in effect.	No additional indexes
CheckConstraint[]	check	(Optional) Check constraints for the table. These are only used if table generation is in effect.	No check constraint
String	comment	(Optional) Comment for the table. This is only used if table generation is in effect.	No comment
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.

Jakarta Persistence

Eclipse Foundation Specification License - v1.1

Disclaimers

1. Introduction

1.1. Authorship

1.2. Document Conventions

2. Entities

2.1. The Entity Class

2.2. Persistent Fields and Properties

2.2.1. Persistent Attribute Type

2.2.2. Property Access

2.3. Access Type

2.3.1. Default Access Type

2.3.2. Explicit Access Type

2.3.3. Access Type of an Embeddable Class

2.3.4. Defaulted Access Types of Embeddable Classes and Mapped Superclasses

2.4. Primary Keys and Entity Identity

2.4.1. Composite primary keys

2.4.2. Primary Keys Corresponding to Derived Identities

2.4.2.1. Specification of Derived Identities

2.4.2.2. Mapping of Derived Identities

2.4.2.3. Examples of Derived Identities

2.5. Entity Versions

2.6. Basic Types

2.7. Embeddable Classes

2.8. Collections of Embeddable Classes and Basic Types

2.9. Map Collections

2.9.1. Map Keys

2.9.2. Map Values

2.10. Mapping Defaults for Non-Relationship Fields or Properties

2.11. Entity Relationships

2.12. Relationship Mapping Defaults

2.12.1. Bidirectional OneToOne Relationships

2.12.2. Bidirectional ManyToOne / OneToMany Relationships

2.12.3. Unidirectional Single-Valued Relationships

2.12.3.1. Unidirectional OneToOne Relationships

2.12.3.2. Unidirectional ManyToOne Relationships

2.12.4. Bidirectional ManyToMany Relationships

2.12.5. Unidirectional Multi-Valued Relationships

2.12.5.1. Unidirectional OneToMany Relationships

2.12.5.2. Unidirectional ManyToMany Relationships

2.13. Inheritance

2.13.1. Abstract Entity Classes

2.13.2. Mapped Superclasses

2.13.3. Non-Entity Classes in the Entity Inheritance Hierarchy

2.14. Inheritance Mapping Strategies

2.14.1. Single Table per Class Hierarchy Strategy

2.14.2. Joined Subclass Strategy

2.14.3. Table per Concrete Class Strategy

2.15. Naming of Database Objects

3. Entity Operations

3.1. Overview

3.2. EntityManager Interface

3.3. Entity Instance’s Life Cycle

3.3.1. Entity Instance Creation

3.3.2. Persisting an Entity Instance

3.3.3. Removal

3.3.4. Synchronization to the Database

3.3.5. Refreshing an Entity Instance

3.3.6. Evicting an Entity Instance from the Persistence Context

3.3.7. Detached Entities

3.3.7.1. Merging Detached Entity State

3.3.7.2. Detached Entities and Lazy Loading

3.3.8. Managed Instances

3.3.9. Load State

3.4. Persistence Context Lifetime and Synchronization Type

3.4.1. Synchronization with the Current Transaction

3.4.2. Transaction Commit

3.4.3. Transaction Rollback

3.5. Locking and Concurrency

3.5.1. Optimistic Locking

3.5.2. Entity Versions and Optimistic Locking

3.5.3. Pessimistic Locking

3.5.4. Lock Modes

3.5.4.1. OPTIMISTIC, OPTIMISTIC_FORCE_INCREMENT

3.5.4.2. PESSIMISTIC_READ, PESSIMISTIC_WRITE, PESSIMISTIC_FORCE_INCREMENT

3.5.4.3. Lock Mode Properties and Uses

3.5.5. OptimisticLockException

3.6. Entity Listeners and Callback Methods

3.6.1. Entity Listeners

Type	Name	Description	Default
String	name	(Optional) A unique generator name that can be referenced by one or more classes to be the generator for primary key values.	See text above
String	sequenceName	(Optional) The name of the database sequence object from which to obtain primary key values.	A provider-chosen sequence name
String	catalog	(Optional) The catalog of the sequence generator.	Default catalog
String	schema	(Optional) The schema of the sequence generator.	Default schema for user
int	initialValue	(Optional) The value from which the sequence object is to start generating.	1
int	allocationSize	(Optional) The amount to increment by when allocating sequence numbers from the sequence.	50
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.

Type	Name	Description	Default
String	name	(Optional) The name of the table.	Entity name
String	catalog	(Optional) The catalog of the table.	Default catalog
String	schema	(Optional) The schema of the table.	Default schema for user
UniqueConstraint[]	uniqueConstraints	(Optional) Unique constraints that are to be placed on the table. These are only used if table generation is in effect. These constraints apply in addition to any constraints specified by the Column and JoinColumn annotations and constraints entailed by primary key mappings.	No additional constraints
Index[]	indexes	(Optional) Indexes for the table. These are only used if table generation is in effect.	No additional indexes
CheckConstraint[]	check	(Optional) Check constraints for the table. These are only used if table generation is in effect.	No check constraint
String	comment	(Optional) Comment for the table. This is only used if table generation is in effect.	No comment
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.

Type	Name	Description	Default
String	name	(Optional) Constraint name.	A provider-chosen name.
String[]	columnNames	(Required) An array of the column names that make up the constraint.
String	options	(Optional) A SQL fragment appended to the generated DDL.	Nothing appended.