JPA中EntityManager接口详解

public interface EntityManager {
    /**
     * 创建实体,将实体保存到数据库中,也就是将一个Java实体持久化到数据库中
     * 如果不是实体对象或者是游离实体,或者实体已经存在,或者没有关联事务或者事务属性设置为事务类型,抛出异常
     *
     * @param entity 新创建的实体对象
     */
    public void persist(Object entity);

    /**
     * 更新持久化上下文中的实体,并将更新保存到数据库中
     * 如果参数不是实体对象,或者是被删除的实体,或者没有关联事务或者事务属性设置为事务类型,抛出异常
     *
     * @param entity 需要更新的实体
     * @return 更新后的实体
     */
    public <T> T merge(T entity);

    /**
     * 删除实体,将实体从数据库中移除
     * 如果参数不是实体对象,或者是游离实体,或者没有关联事务或者事务属性设置为事务类型,抛出异常
     *
     * @param entity 需要删除的实体对象
     */
    public void remove(Object entity);

    /**
     * 通过实体主键查找实体对象
     * 如果参数entityClass不是实体或主键对象与实体的主键设置不匹配,抛出异常
     *
     * @param entityClass 实体类型
     * @param primaryKey  实体主键对象
     * @return 查询到的实体对象
     */
    public <T> T find(Class<T> entityClass, Object primaryKey);

    public <T> T find(Class<T> entityClass, Object primaryKey, Map<String, Object> properties);

    public <T> T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode);

    public <T> T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode, Map<String, Object> properties);


    /**
     * 与find类似,也是通过实体主键查询实体对象,当查询的实体在数据库中不存在的时候,抛出异常,而不返回null
     *
     * @param entityClass 实体类型
     * @param primaryKey  实体主键对象
     * @return 查询到的实体对象
     */
    public <T> T getReference(Class<T> entityClass, Object primaryKey);

    /**
     * 将实体锁定
     * 如果实体不支持锁定,不是实体对象或者是游离实体,或者没有关联事务或者事务属性设置为事务类型抛出异常
     *
     * @param entity   实体对象
     * @param lockMode 锁定类型
     */
    public void lock(Object entity, LockModeType lockMode);

    public void lock(Object entity, LockModeType lockMode, Map<String, Object> properties);

    /**
     * 将持久化上下文实体保存到数据库中,实现与数据库同步
     * 如果与数据库同步失败,或者没有关联事务或者事务属性设置为事务类型抛出异常
     */
    public void flush();

    /**
     * 设置持久化上下文鱼数据库同步的方式
     *
     * @param flushMode 同步的方式
     */
    public void setFlushMode(FlushModeType flushMode);

    /**
     * 获取当前持久化上下文与数据库同步的方式
     *
     * @return 同步类型
     */
    public FlushModeType getFlushMode();

    /**
     * 将数据库中的数据重新读取到持久化上下文中的实体中,实现与数据库同步
     * 如果参数不是实体对象,或者不是托管实体,或者所重新更新的实体未找到,或者没有关联事务或者事务属性设置为事务类型,抛出异常
     *
     * @param entity 重新读取数据库中的实体对象
     */
    public void refresh(Object entity);

    public void refresh(Object entity, Map<String, Object> properties);

    public void refresh(Object entity, LockModeType lockMode);

    public void refresh(Object entity, LockModeType lockMode, Map<String, Object> properties);

    /**
     * 将持久化上下文中实体全部转变为游离状态,此时还没有被flush,与数据库同步的实体将不会被持久化到数据库中
     */
    public void clear();

    /**
     * 将一个托管状态的实体转变为分离状态。这意味着此实体不再由持久化上下文管理
     * 对该实体的任何更改都不会自动同步到数据库中,但是,实体本身在数据库中的记录保持不变
     * 如果不是实体对象,抛出异常
     *
     * @param entity 需要游离的实体
     */
    public void detach(Object entity);

    /**
     * 当前持久化上下文中是否包含该实体
     * 如果参数不是实体对象抛出异常
     *
     * @param entity 需要判断的实体对象
     * @return 包含返回true
     */
    public boolean contains(Object entity);

    /**
     * 获取给定实体的锁定模式。锁定模式用于控制在并发环境下对实体的访问
     */
    public LockModeType getLockMode(Object entity);

    /**
     * 设置实体管理器属性或提示,如果无法识别特定于供应商的属性或提示，它将被静默忽略
     *
     * @param propertyName 属性名
     * @param value        属性值
     */
    public void setProperty(String propertyName, Object value);

    /**
     * 获取当前持久化上下文的属性。可以用来查看持久化上下文的当前属性设置
     */
    public Map<String, Object> getProperties();

    /**
     * 根据传入的JPQL字符串创建一个查询对象,JPQL类似于SQL,用于查询实体对象
     */
    public Query createQuery(String qlString);

    /**
     * 根据标准查询CriteriaQuery对象,创建一个类型化查询. CriteriaQuery提供了一种类型安全且面向对象的查询方式
     */
    public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery);

    /**
     * 根据更新标准查询对象创建一个查询，用于执行更新操作。
     */
    public Query createQuery(CriteriaUpdate updateQuery);

    /**
     * 根据删除标准查询对象创建一个查询，用于执行删除操作。
     */
    public Query createQuery(CriteriaDelete deleteQuery);

    /**
     * 根据传入的JPQL字符串和结果类型创建一个类型化查询。这个方法允许你指定查询的返回类型。
     */
    public <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass);

    /**
     * 根据命名查询创建一个查询对象。命名查询是在持久化单元中预定义的查询
     */
    public Query createNamedQuery(String name);

    public <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass);

    /**
     * 据SQL查询字符串创建一个查询对象。SQL查询允许你执行原生SQL查询
     */
    public Query createNativeQuery(String sqlString);
    public Query createNativeQuery(String sqlString, Class resultClass);
    public Query createNativeQuery(String sqlString, String resultSetMapping);

    /**
     * 根据命名的存储过程查询创建一个存储过程查询对象
     */
    public StoredProcedureQuery createNamedStoredProcedureQuery(String name);

    /**
     * 根据存储过程名称创建一个存储过程查询对象
     */
    public StoredProcedureQuery createStoredProcedureQuery(String procedureName);
    public StoredProcedureQuery createStoredProcedureQuery(String procedureName, Class... resultClasses);
    public StoredProcedureQuery createStoredProcedureQuery(String procedureName, String... resultSetMappings);


    /**
     * 使实体管理器对象与JTA事务关联
     */
    public void joinTransaction();

    /**
     * 检查当前操作是否已经加入了事务
     */
    public boolean isJoinedToTransaction();

    /**
     * 如果此实现对指定的Class可用，则返回由指定Class表示的实例
     */
    public <T> T unwrap(Class<T> cls);

    /**
     * 获取当前实体管理器具体的实现对象,根据不同的JPA实现者所返回的对象不同
     *
     * @return 实体管理器所实现的对象
     */
    public Object getDelegate();

    /**
     * 关闭当前持久化上下文
     * 如果当前的实体管理器对象与事务关联,或者实体管理是容器负责管理的,也不能关闭,会抛出异常
     */
    public void close();

    /**
     * 判断当前持久化上下文是否打开
     */
    public boolean isOpen();

    /**
     * 获取当前事务管理器所关联的事务处理对象
     */
    public EntityTransaction getTransaction();

    /**
     * 获取EntityManagerFactory实例
     */
    public EntityManagerFactory getEntityManagerFactory();

    /**
     * 获取用于构建标准查询的CriteriaBuilder实例
     */
    public CriteriaBuilder getCriteriaBuilder();

    /**
     * 获取持久化单元的元模型，用于访问实体类的元数据。
     */
    public Metamodel getMetamodel();

    /**
     * 根据给定的根类型创建一个新的实体图，用于定义实体的加载行为
     */
    public <T> EntityGraph<T> createEntityGraph(Class<T> rootType);

    /**
     * 根据给定的图名称创建一个新的实体图
     */
    public EntityGraph<?> createEntityGraph(String graphName);

    /**
     * 获取具有给定名称的实体图
     */
    public EntityGraph<?> getEntityGraph(String graphName);

    /**
     * 获取与给定实体类相关联的所有实体图列表，用于查看实体类的加载行为
     */
    public <T> List<EntityGraph<? super T>> getEntityGraphs(Class<T> entityClass);

}