Package com.axelor.db

Class JPA

java.lang.Object
com.axelor.db.JPA
@Singleton public final class JPA extends Object
This class provides easy access to EntityManager and related API. It also provides some convenient methods like create Model instances or creating Query.

This class should be initialized using Guice container as eager singleton during application startup.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    JPA.JDBCWork
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T extends Model>
    Query<T>
    all(Class<T> klass)
    Prepare a Query for the given model class.
    static <T> T
    callInTransaction(Supplier<T> task)
     
    static void
    clear()
    Clear the persistence context, causing all managed entities to become detached.
    static <T extends Model>
    T
    copy(T bean, boolean deep)
    Create a duplicate copy of the given bean instance.

    In case of deep copy, one-to-many records are duplicated.
    static <T extends Model>
    T
    edit(Class<T> klass, Map<String,Object> values)
    Edit an instance of the given model class using the given values.

    This is a convenient method to reconstruct model object from a key value map, for example HTTP params.
    static jakarta.persistence.EntityManager
    em()
    Get an instance of EntityManager.
    static int
    execute(String query)
    Execute a JPQL update query.
    static <T extends Model>
    Property
    field(Class<T> klass, String name)
    Return a Property of the given model class.
    static <T extends Model>
    Property[]
    fields(Class<T> klass)
    Return all the properties of the given model class.
    static <T extends Model>
    T
    find(Class<T> klass, Long id)
    Finds an entity by its primary key.
    static <T extends Model>
    Optional<T>
    findById(Class<T> klass, Long id)
    Finds an entity by its primary key.
    static <T extends Model>
    List<T>
    findByIds(Class<T> klass, List<Long> ids)
    Find multiple entities by their primary key.
    static void
    flush()
    Synchronize the persistence context to the underlying database.
    static <T extends Model>
    T
    getReferenceById(Class<T> modelClass, Long id)
    Retrieves a reference (proxy) to an entity instance with the specified ID without immediately loading its state from the database.
    static void
    jdbcWork(JPA.JDBCWork work)
    Perform JDBC related work using the Connection managed by the current EntityManager.
    static <T extends Model>
    T
    manage(T bean)
    A convenient method to persist reconstructed unmanaged objects.

    This method takes care of relational fields by inspecting the managed state of the referenced objects and also sets reverse lookup fields annotated with OneToMany.mappedBy() annotation.
    static <T extends Model>
    T
    merge(T entity)
    Merge the state of the given entity into the current persistence context.
    static Class<?>
    model(String name)
    Return the model class for the given name.
    static Set<Class<?>>
    models()
    Return all the non-abstract models found in all the activated modules.
    static <T extends Model>
    T
    persist(T entity)
    Make an entity managed and persistent.
    static <T extends Model>
    void
    refresh(T entity)
    Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
    static <T extends Model>
    void
    remove(T entity)
    Remove the entity instance.
    static void
    runInTransaction(Runnable task)
    Run the given task inside a transaction that is committed after the task is completed.
    static <T extends Model>
    T
    save(T entity)
    Save the state of the entity.

    It uses either persist(Model) or merge(Model) and calls flush() to synchronize values with database.
    static void
    verify(Class<? extends Model> model, Map<String,Object> values)
    Verify the values against the database values to ensure the records involved are not modified.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • em

      public static jakarta.persistence.EntityManager em()
      Get an instance of EntityManager.

    • execute

      public static int execute(String query)
      Execute a JPQL update query.
      Parameters:
      query - JPQL query

    • all

      public static <T extends Model> Query<T> all(Class<T> klass)
      Prepare a Query for the given model class.
      Parameters:
      klass - the model class

    • find

      public static <T extends Model> T find(Class<T> klass, Long id)
      Finds an entity by its primary key.
      Type Parameters:
      T - the type of the model class
      Parameters:
      klass - the class of the entity to find
      id - the primary key of the entity to find
      Returns:
      entity found by the given id, null otherwise
      See Also:
      • EntityManager.find(Class, Object)

    • findById

      public static <T extends Model> Optional<T> findById(Class<T> klass, Long id)
      Finds an entity by its primary key.
      Type Parameters:
      T - the type of the model class
      Parameters:
      klass - the class of the entity to find
      id - the primary key of the entity to find
      Returns:
      an Optional containing the found entity, or Optional#empty() if not found

    • findByIds

      public static <T extends Model> List<T> findByIds(Class<T> klass, List<Long> ids)
      Find multiple entities by their primary key.

      Ensure to check the first-level cache first, then the second-level cache. If the entity is found and already managed by the Hibernate Session, the cached entity will be added to the returned List. Therefore, skipping it from being fetched via the multi-load query.

      WARNING: The list may contain NULL elements if an id was not found. The list size and order will match the input ids.

      Parameters:
      klass - The model class
      ids - The ids to load
      Returns:
      list of all the matched records
      See Also:

    • getReferenceById

      public static <T extends Model> T getReferenceById(Class<T> modelClass, Long id)
      Retrieves a reference (proxy) to an entity instance with the specified ID without immediately loading its state from the database.

      This method delegates to EntityManager.getReference(Class, Object). It is designed for performance optimization, particularly when you need to associate an entity (set a foreign key) without the overhead of a database SELECT query.

      Note: The returned object is likely a dynamic proxy. The database will only be accessed when you invoke a method on the proxy (other than getting the ID). If the entity does not exist in the database, an EntityNotFoundException will be thrown at the time of that access, not at the time of calling this method.

      Type Parameters:
      T - the type of the model class
      Parameters:
      modelClass - the class of the entity to retrieve
      id - the primary key of the entity
      Returns:
      a managed entity proxy instance with the state lazily fetched
      Throws:
      jakarta.persistence.EntityNotFoundException - if the entity state is accessed, and the entity does not exist in the database
      See Also:
      • EntityManager.getReference(Class, Object)

    • persist

      public static <T extends Model> T persist(T entity)
      Make an entity managed and persistent.
      See Also:
      • EntityManager.persist(Object)

    • merge

      public static <T extends Model> T merge(T entity)
      Merge the state of the given entity into the current persistence context.
      See Also:
      • EntityManager.merge(Object)

    • save

      public static <T extends Model> T save(T entity)
      Save the state of the entity.

      It uses either persist(Model) or merge(Model) and calls flush() to synchronize values with database.
      See Also:

    • remove

      public static <T extends Model> void remove(T entity)
      Remove the entity instance.
      See Also:
      • EntityManager.remove(Object)

    • refresh

      public static <T extends Model> void refresh(T entity)
      Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
      See Also:
      • EntityManager.refresh(Object)

    • flush

      public static void flush()
      Synchronize the persistence context to the underlying database.
      See Also:
      • EntityManager.flush()

    • clear

      public static void clear()
      Clear the persistence context, causing all managed entities to become detached.
      See Also:
      • EntityManager.clear()

    • verify

      public static void verify(Class<? extends Model> model, Map<String,Object> values)
      Verify the values against the database values to ensure the records involved are not modified.
      Throws:
      jakarta.persistence.OptimisticLockException - if version mismatch of any a record is deleted

    • edit

      public static <T extends Model> T edit(Class<T> klass, Map<String,Object> values)
      Edit an instance of the given model class using the given values.

      This is a convenient method to reconstruct model object from a key value map, for example HTTP params.
      Parameters:
      klass - a model class
      values - key value map where key represents a field name
      Returns:
      a JPA managed object of the given model class

    • manage

      public static <T extends Model> T manage(T bean)
      A convenient method to persist reconstructed unmanaged objects.

      This method takes care of relational fields by inspecting the managed state of the referenced objects and also sets reverse lookup fields annotated with OneToMany.mappedBy() annotation.
      Parameters:
      bean - model instance
      Returns:
      JPA managed model instance
      See Also:

    • models

      public static Set<Class<?>> models()
      Return all the non-abstract models found in all the activated modules.
      Returns:
      Set of model classes

    • model

      public static Class<?> model(String name)
      Return the model class for the given name.
      Parameters:
      name - name of the model
      Returns:
      model class

    • fields

      public static <T extends Model> Property[] fields(Class<T> klass)
      Return all the properties of the given model class.

    • field

      public static <T extends Model> Property field(Class<T> klass, String name)
      Return a Property of the given model class.
      Parameters:
      klass - a model class
      name - name of the property
      Returns:
      property or null if property doesn't exist

    • copy

      public static <T extends Model> T copy(T bean, boolean deep)
      Create a duplicate copy of the given bean instance.

      In case of deep copy, one-to-many records are duplicated. Otherwise, one-to-many records will be skipped.
      Parameters:
      bean - the bean to copy
      deep - whether to create a deep copy
      Returns:
      a copy of the given bean

    • runInTransaction

      public static void runInTransaction(Runnable task)
      Run the given task inside a transaction that is committed after the task is completed.
      Parameters:
      task - the task to run.

    • callInTransaction

      public static <T> T callInTransaction(Supplier<T> task)

    • jdbcWork

      public static void jdbcWork(JPA.JDBCWork work)
      Perform JDBC related work using the Connection managed by the current EntityManager.
      Parameters:
      work - The work to be performed
      Throws:
      jakarta.persistence.PersistenceException - Generally indicates wrapped SQLException