org.hibernate.Session中文源码(hibernate-core-4.1.0.Final.jar)
该文档借助Google翻译和百度翻译,在中文语意上百度更加强大,但是专业名词解析部分Google更厉害,本章翻译依赖于上述两种翻译工具,错误之处请留言指出。
文档持续更新中……
/*
* Hibernate、习惯Java的关系持久性
*
* 版权所有(c)2008-2011,红帽公司或第三方贡献者
* 由@author标签表示或表达版权归属作者所作的陈述。
* 所有第三方贡献都是由Red Hat Inc.授权分发
*
* 这个受版权保护的材料可供任何希望使用,修改,
* 根据GNU的条款和条件复制或重新分发它
* 较小的通用公共许可证,由自由软件基金会发布。
*
* 该程序的分发是希望它有用,但没有任何保证;
* 甚至没有适销性的暗示保证或适用于特定目的。
* 请参阅GNU较宽松通用公共许可证更多细节。
*
* 您应该已收到GNU宽通用公共许可证的副本以及此发行版;
* 如果没有,请写信给:
* 自由软件基金会
* 富兰克林街51号,五楼
* 波士顿,MA 02110-1301 美国
*/
package org.hibernate;
import java.io.Serializable;
import java.sql.Connection;
import org.hibernate.jdbc.ReturningWork;
import org.hibernate.jdbc.Work;
import org.hibernate.stat.SessionStatistics;
/**
* Java应用程序和Hibernate之间的主要运行时接口。
* 这是抽象持久性服务概念的中央API类。<br>
* <br>
* <tt> Session </tt>的生命周期受逻辑事务的开始和结束的限制。
* (长事务可能跨越多个数据库事务。)<br>
* <br>
* <tt>Session</tt>的主要功能是为映射实体类的实例提供创建,读取和删除操作。
* 实例可能存在以下三种状态之一:<br>
* <br>
* <i>transient:</i> 永远不会持久,与<tt>Session</tt>没有任何关联 <br>
* <i>persistent:</i> 与唯一的 <tt>Session</tt> 相关联 <br>
* <i>detached:</i> 以前是持久的,不与任何<tt>Session</tt>相关联 <br>
* <br>
* 通过调用<tt>save()</tt>,<tt>persist()</tt>或<tt>saveOrUpdate()</tt> 可以使临时实例持久化.
* 通过调用<tt>delete()</tt>可以使持久实例变为临时(删除).
* <tt>load()</tt>或<tt>get()</tt>方法返回的任何实例都是持久的.
* 可以通过调用<tt>update()</tt>,<tt>saveOrUpdate()</tt>,
* <tt>lock()</tt>或<tt>replicate()</tt>使分离的实例持久化.
* 通过调用<tt>merge()</tt>,瞬态或分离实例的状态也可以作为新的持久实例持久化.<br>
* <br>
* <tt>save()</tt>和<tt>persist()</tt>导致SQL <tt>DELETE</tt>中的
* SQL <tt>INSERT</tt>,<tt>delete()</tt>
* 和SQL<tt>UPDATE</tt>中的<tt>update()</tt>或<tt>merge()</tt>.
*
* 在刷新时检测到对<i>persistent</i>实例的更改,并且还会生成SQL<tt>UPDATE</tt>
* <tt>saveOrUpdate()</tt>和<tt>replicate()</tt>产生<tt>INSERT</tt>或<tt>UPDATE</tt><br>
* <br>
* 并不意味着实现者是线程安全的.
* 相反,每个线程/事务应从<tt>SessionFactory</tt>获取自己的实例.<br>
* <br>
* 如果<tt>Session</tt>实例的持久化类是可序列化的,则它是可序列化的.<br>
* <br>
* 典型的事务应该使用以下习惯用法:
* <pre>
* Session sess = factory.openSession();
* Transaction tx;
* try {
* tx = sess.beginTransaction();
* //do some work
* ...
* tx.commit();
* }
* catch (Exception e) {
* if (tx!=null) tx.rollback();
* throw e;
* }
* finally {
* sess.close();
* }
* </pre>
* <br>
* 如果<tt>Session</tt>抛出异常(exception),则必须回滚(rolled)事务并丢弃会话
* 发生异常后,<tt>Session</tt>的内部状态可能与数据库不一致
*
* @see SessionFactory
* @author Gavin King
*/
public interface Session extends SharedSessionContract {
/**
* 获得一个能从本次会话中获取某些信息的{@link Session}生成器。
*
* @return 会话生成器(The session builder)
*/
public SharedSessionBuilder sessionWithOptions();
/**
* 强制刷新此会话。在提交事务和关闭会话之前,必须在工作单元结束时调用
* (取决于 {@link #setFlushMode(FlushMode)}、 {@link Transaction#commit()}调用此方法)
* <p/>
* <i>Flushing</i> 是将底层持久存储与内存中的持久状态进行同步的过程.
*
* @throws HibernateException 表示刷新会话或与数据库通信的问题
*/
public void flush() throws HibernateException;
/**
* 设置此会话的刷新模式
* <p/>
* 刷新模式确定刷新会话的点.
* <i>Flushing</i> 是将底层持久存储与内存中的持久状态进行同步的过程.
* <p/>
* 对于逻辑上的“只读(read only)”会话,在会话开始时将会话的
* 刷新模式设置为{@link FlushMode#MANUAL}是合理的(为了获得一些额外的性能).
*
* @param flushMode 新的刷新模式
* @see FlushMode
*/
public void setFlushMode(FlushMode flushMode);
/**
* 获取此会话的当前刷新模式.
*
* @return 刷新模式
*/
public FlushMode getFlushMode();
/**
* 设置缓存模式.
* <p/>
* 缓存模式确定此会话与二级缓存交互的方式.
*
* @param cacheMode 新的缓存模式.
*/
public void setCacheMode(CacheMode cacheMode);
/**
* 获取当前缓存模式.
*
* @return 当前缓存模式.
*/
public CacheMode getCacheMode();
/**
* 获取创建此会话的会话工厂.
*
* @return 会话工厂.
* @see SessionFactory
*/
public SessionFactory getSessionFactory();
/**
* 通过释放JDBC连接并清理结束会话.
* 没有严格要求关闭会话,但您必须至少{@link #disconnect()}它。
*
* @return 应用程序提供的连接或空.
* @throws HibernateException 指示清除问题.
*/
public Connection close() throws HibernateException;
/**
* 取消执行当前查询.
* <p/>
* 这是会话上可以从另一个线程安全调用的唯一方法.
*
* @throws HibernateException 取消查询时出现问题
*/
public void cancelQuery() throws HibernateException;
/**
* 检查会话是否仍然打开.
*
* @return boolean
*/
public boolean isOpen();
/**
* 检查会话当前是否已连接.
*
* @return boolean
*/
public boolean isConnected();
/**
* 此会话是否包含必须与数据库同步的任何更改?
* 换句话说,如果刷新这个会话,是否会执行任何DML操作?
*
* @return 如果会话包含挂起的更改,则为true;否则为false.
* @throws HibernateException 无法进行脏数据检查
*/
public boolean isDirty() throws HibernateException;
/**
* 加载到此会话中的实体和代理是否默认为只读?
*
* 要确定特定实体或代理的只读/可修改设置:
* @see Session#isReadOnly(Object)
*
* @return true,加载的实体/代理默认为只读;
* false,加载的实体/代理将默认为可修改.
*/
public boolean isDefaultReadOnly();
/**
* 将加载到此会话中的实体和代理的默认值从可修改模式更改为只读模式,或从可修改模式更改为只读模式.
*
* 只读实体不进行脏检查,并且不维护持久状态的快照.
* 可以修改只读实体,但不会保留更改.
*
* 初始化代理时,无论会话的当前设置如何,加载的实体将具有与未初始化代理相同的只读/可修改设置.
*
* 要更改此会话中已有的特定实体或代理的只读/可修改设置:
* @see Session#setReadOnly(Object,boolean)
*
* 为查询加载的实体和代理重写此会话的只读/可修改设置:
* @see Query#setReadOnly(boolean)
*
* @param readOnly true, 加载的实体/代理的默认值是只读的;
* false, 加载的实体/代理的默认值是可修改的
*/
public void setDefaultReadOnly(boolean readOnly);
/**
* 返回与此会话关联的给定实体的标识符值.
* 如果给定实体实例相对于此会话是临时的或分离的,则抛出异常.
*
* @param object 一个持久的实例
* @return 标识符
* @throws TransientObjectException 如果实例是临时的或与其他会话关联
*/
public Serializable getIdentifier(Object object);
/**
* 检查此实例是否与此tt>Session</tt>相关联.
*
* @param object 持久类的实例
* @return 如果给定实例与此会话关联,则为true
*/
public boolean contains(Object object);
/**
* 从会话缓存中删除此实例.
* 对实例的更改将不会与数据库同步.
* 如果关联与<tt>cascade="evict"</tt>映射,则此操作级联到关联的实例.
*
* @param object 持久实例
*/
public void evict(Object object);
/**
* 返回具有给定标识符的给定实体类的持久实例,获取指定的锁模式(假定该实例存在).
*
* @param theClass 持久类
* @param id 类的现有持久实例的有效标识符
* @param lockMode 锁定级别
*
* @return 持久实例或代理
*
* @deprecated LockMode 参数应替换为 LockOptions
*/
@Deprecated
public Object load(Class theClass, Serializable id, LockMode lockMode);
/**
* 返回具有给定标识符的给定实体类的持久实例,获取指定的锁模式(假定该实例存在).
*
* @param theClass 持久类
* @param id 类的现有持久实例的有效标识符
* @param lockOptions 包含锁定级别
* @return 持久实例或代理
*/
public Object load(Class theClass, Serializable id, LockOptions lockOptions);
/**
* 返回具有给定标识符的给定实体类的持久实例,获取指定的锁模式(假定该实例存在).
*
* @param entityName 持久类
* @param id 类的现有持久实例的有效标识符
* @param lockMode 锁定级别
*
* @return 持久实例或代理
*
* @deprecated LockMode 参数应替换为 LockOptions
*/
@Deprecated
public Object load(String entityName, Serializable id, LockMode lockMode);
/**
* 返回具有给定标识符的给定实体类的持久实例,获取指定的锁模式(假定该实例存在).
*
* @param entityName 持久类
* @param id 类的现有持久实例的有效标识符
* @param lockOptions 包含锁定级别
*
* @return 持久实例或代理
*/
public Object load(String entityName, Serializable id, LockOptions lockOptions);
/**
* 返回具有给定标识符的给定实体类的持久实例,假定该实例存在.
* 当访问非标识符方法时,此方法可能返回按需初始化的代理实例.
* <br><br>
* 不应使用此方法来确定实例是否存在(请改用<tt>get()</tt>).
* 仅用于检索假定存在的实例,其中不存在将是实际错误.
*
* @param theClass 持久类
* @param id 类的现有持久实例的有效标识符
*
* @return 持久实例或代理
*/
public Object load(Class theClass, Serializable id);
/**
* 返回具有给定标识符的给定实体类的持久实例,假定该实例存在.
* 当访问非标识符方法时,此方法可能返回按需初始化的代理实例.
* <br><br>
* 不应使用此方法来确定实例是否存在(请改用<tt>get()</tt>).
* 仅用于检索假定存在的实例,其中不存在将是实际错误.
*
* @param entityName 持久类
* @param id 类的现有持久实例的有效标识符
*
* @return 持久实例或代理
*/
public Object load(String entityName, Serializable id);
/**
* 将与给定标识符关联的持久状态读取到给定的瞬态实例中.
*
* @param object 持久化类的“空”实例
* @param id 类的现有持久实例的有效标识符
*/
public void load(Object object, Serializable id);
/**
* 保持给定分离实例的状态,重用当前标识符值.
* 如果关联映射为 {@code cascade="replicate"},则此操作会级联到关联的实例
*
* @param object 持久化类的分离实例
* @param replicationMode 要使用的复制模式
*/
public void replicate(Object object, ReplicationMode replicationMode);
/**
* 保持给定分离实例的状态,重用当前标识符值.
* 如果关联与{@code cascade="replicate"}映射,则此操作级联到关联实例
*
* @param entityName 实体名称
* @param object 持久化类的分离实例
* @param replicationMode 要使用的复制模式
*/
public void replicate(String entityName, Object object, ReplicationMode replicationMode) ;
/**
* 保留给定的瞬态实例,首先分配生成的标识符.
* (或者,如果使用 <tt>assigned</tt>生成器,则使用identifier属性的当前值.)
* 如果关联与{@code cascade="save-update"}映射,则此操作级联到关联实例
*
* @param object 持久化类的瞬态实例
*
* @return 生成的标识符
*/
public Serializable save(Object object);
/**
* 保留给定的瞬态实例,首先分配生成的标识符.
* (或者,如果使用<tt>assigned</tt>生成器,则使用identifier属性的当前值.)
* 如果关联与{@code cascade="save-update"}映射,则此操作级联到关联实例
*
* @param entityName 实体名称
* @param object 持久化类的瞬态实例
*
* @return 生成的标识符
*/
public Serializable save(String entityName, Object object);
/**
* {@link #save(Object)} 或{@link #update(Object)}给定实例,
* 具体取决于未保存值检查的分辨率(有关未保存值检查的讨论,请参阅手册)
* <p/>
* 如果关联与{@code cascade="save-update"}映射,则此操作级联到关联实例
*
* @param object 包含新状态或更新状态的瞬态或分离实例
*
* @see Session#save(java.lang.Object)
* @see Session#update(Object object)
*/
public void saveOrUpdate(Object object);
/**
* 给定实例的{@link #save(String, Object)}或{@link #update(String, Object)},
* 取决于未保存值检查的解决方案(有关未保存值检查的讨论,请参见手册)
* <p/>
* 如果关联与{@code cascade="save-update"}映射,则此操作级联到关联的实例
*
* @param entityName 实体名称
* @param object 包含新状态或更新状态的临时或分离实例
*
* @see Session#save(String,Object)
* @see Session#update(String,Object)
*/
public void saveOrUpdate(String entityName, Object object);
/**
* 使用给定分离实例的标识符更新持久实例.
* 如果存在具有相同标识符的持久实例,则引发异常.
* 如果关联与{@code cascade="save-update"}映射,则此操作级联到关联的实例
*
* @param object 包含更新状态的分离实例
*/
public void update(Object object);
/**
* 使用给定分离实例的标识符更新持久实例.
* 如果存在具有相同标识符的持久实例,则引发异常.
* 如果关联与{@code cascade="save-update"}映射,则此操作级联到关联的实例
*
* @param entityName 实体名称
* @param object 包含更新状态的分离实例
*/
public void update(String entityName, Object object);
/**
* 将给定对象的状态复制到具有相同标识符的持久对象上.
* 如果当前没有与会话关联的持久实例,则将加载该实例.
* 返回持久实例.
* 如果给定实例未保存,请保存的副本并将其作为新的持久实例返回.
* 给定实例未与会话关联.
* 如果关联与{@code cascade="merge"}映射,则此操作级联到关联的实例
* <p/>
* 该方法的语义由JSR-220定义.
*
* @param object 状态为要复制的分离实例
*
* @return 更新的永久实例
*/
public Object merge(Object object);
/**
* 将给定对象的状态复制到具有相同标识符的持久对象上.
* 如果当前没有与会话关联的持久实例,则将加载该实例.
* 返回持久实例.
* 如果给定实例未保存,请保存的副本并将其作为新的持久实例返回.
* 给定实例未与会话关联.
* 如果关联与{@code cascade="merge"}映射,则此操作级联到关联的实例
* <p/>
* 该方法的语义由JSR-220定义.
*
* @param entityName 实体名称
* @param object 状态为要复制的分离实例
*
* @return 更新的永久实例
*/
public Object merge(String entityName, Object object);
/**
* 使临时实例持久化。如果关联与{@code cascade="persist"}映射,则此操作级联到关联的实例
* <p/>
* 该方法的语义由JSR-220定义.
*
* @param object 要持久化的临时实例
*/
public void persist(Object object);
/**
* 使临时实例持久化。如果关联与{@code cascade="persist"}映射,则此操作级联到关联的实例
* <p/>
* 该方法的语义由JSR-220定义.
*
* @param entityName 实体名称
* @param object 要持久化的临时实例
*/
public void persist(String entityName, Object object);
/**
* 从数据存储中删除永久实例。参数可以是与接收<tt>Session</tt>相关联的实例,
* 或者是与此操作相关联的瞬时实例(如果关联映射到{@code cascade="delete"})
*
* @param object 要删除的实例
*/
public void delete(Object object);
/**
* 从数据存储中删除永久实例。<b>object</b>参数可以是与接收<tt>Session</tt>关联的实例,
* 也可以是具有与现有持久状态关联的标识符的瞬时实例。
* 如果关联与{@code cascade="delete"}映射,则此操作级联到关联的实例
*
* @param entityName 要删除的实例的实体名称
* @param object 要删除的实例
*/
public void delete(String entityName, Object object);
/**
* 获取给定对象的指定锁级别.
* 这可用于执行版本检查(<tt>LockMode.READ</tt>),
* 升级到悲观锁(<tt>LockMode.PESSIMISTIC_WRITE</tt>),
* 或简单地将瞬态实例与会话重新关联(<tt>LockMode.NONE</tt>)
* 如果关联与<tt>cascade="lock"</tt>映射,则此操作级联到关联实例.
*
* @param object 持久或瞬态实例
* @param lockMode 锁定水平
*
* @deprecated instead call buildLockRequest(LockMode).lock(object)
*/
@Deprecated
public void lock(Object object, LockMode lockMode);
/**
* 获取给定对象的指定锁级别.
* 这可用于执行版本检查(<tt>LockMode.READ</tt>),
* 升级到悲观锁(<tt>LockMode.PESSIMISTIC_WRITE</tt>),
* 或简单地将瞬态实例与会话重新关联(<tt>LockMode.NONE</tt>)
* 如果关联与<tt>cascade="lock"</tt>映射,则此操作级联到关联实例.
*
* @param object 持久或瞬态实例
* @param lockMode 锁定水平
*
* @deprecated instead call buildLockRequest(LockMode).lock(entityName, object)
*/
@SuppressWarnings( {"JavaDoc"})
@Deprecated
public void lock(String entityName, Object object, LockMode lockMode);
/**
* 建立一个锁定模式,悲观锁定时间和锁定范围.
* 乐观锁定忽略超时和范围.
* 生成LockRequest后,调用LockRequest.lock以执行请求的锁定.
* <p/>
* 示例用法:
* {@code session.buildLockRequest().setLockMode(LockMode.PESSIMISTIC_WRITE).setTimeOut(60000).lock(entity);}
*
* @param lockOptions 包含锁定级别
*
* @return 可用于锁定传递的对象的锁请求.
*/
public LockRequest buildLockRequest(LockOptions lockOptions);
/**
* 从基础数据库重新读取给定实例的状态.
* 使用它来实现跨越许多业务任务的长时间运行会话是不可取的.
* 然而,这种方法在某些特殊情况下是有用的.
* 例如
* <ul>
* <li>数据库触发器在插入或更新时更改对象状态
* <li>在同一会话中执行直接SQL(如批量更新)之后
* <li>插入<tt>Blob</tt>或<tt>Clob</tt>后
* </ul>
*
* @param object 持久的或分离的实例
*/
public void refresh(Object object);
/**
* 从基础数据库重新读取给定实例的状态.
* 使用它来实现跨越许多业务任务的长时间运行会话是不可取的.
* 然而,这种方法在某些特殊情况下是有用的.
* 例如
* <ul>
* <li>数据库触发器在插入或更新时更改对象状态
* <li>在同一会话中执行直接SQL(如批量更新)之后
* <li>插入<tt>Blob</tt>或<tt>Clob</tt>后
* </ul>
*
* @param entityName a persistent class
* @param object 持久的或分离的实例
*/
public void refresh(String entityName, Object object);
/**
* 使用给定的<tt>LockMode</tt>从基础数据库重新读取给定实例的状态.
* 使用它来实现跨越许多业务任务的长时间运行会话是不可取的。
* 然而,这种方法在某些特殊情况下是有用的。
*
* @param object 持久的或分离的实例
* @param lockMode 要使用的锁定模式
*
* @deprecated LockMode参数应替换为LockOptions
*/
@Deprecated
public void refresh(Object object, LockMode lockMode);
/**
* 使用给定的<tt>LockMode</tt>从基础数据库重新读取给定实例的状态.
* 使用它来实现跨越许多业务任务的长时间运行会话是不可取的。
* 然而,这种方法在某些特殊情况下是有用的。
*
* @param object 持久的或分离的实例
* @param 包含锁定模式的锁定
*/
public void refresh(Object object, LockOptions lockOptions);
/**
* 使用给定的<tt>LockMode</tt>从基础数据库重新读取给定实例的状态.
* 使用它来实现跨越许多业务任务的长时间运行会话是不可取的。
* 然而,这种方法在某些特殊情况下是有用的。
*
* @param entityName 持久类
* @param object 持久的或分离的实例
* @param 包含锁定模式的锁定
*/
public void refresh(String entityName, Object object, LockOptions lockOptions);
/**
* 确定给定对象的当前锁定模式.
*
* @param object 持久实例
*
* @return 当前锁定模式
*/
public LockMode getCurrentLockMode(Object object);
/**
* 为给定的集合和筛选字符串创建{@link Query}实例。
*
* 包含一个名为{@code this}的隐式{@code FROM}元素,
* 该元素引用为集合元素定义的表,以及此特定集合实例的键值的隐式{@code WHERE}限制。
*
* @param collection 永久性集合
* @param queryString Hibernate查询片段.
*
* @return 用于操作和执行的查询实例
*/
public Query createFilter(Object collection, String queryString);
/**
* 完全清除会话.
* 逐出所有加载的实例并取消所有挂起的保存、更新和删除.
* 不要关闭打开的迭代器或<tt>ScrollableResults</tt>的实例.
*/
public void clear();
/**
* 返回具有给定标识符的给定实体类的持久实例;
* 如果没有此类持久实例,则返回空值.
* (如果实例已与会话关联,则返回该实例.此方法从不返回未初始化的实例.)
*
* @param clazz 持久类
* @param id 标识符
*
* @return 持久实例或空
*/
public Object get(Class clazz, Serializable id);
/**
* 返回具有给定标识符的给定实体类的持久实例;
* 如果没有此类持久实例,则返回空值.
* (如果实例已与会话关联,则返回该实例.此方法从不返回未初始化的实例.)
* 如果实例存在,则获取指定的锁定模式.
*
* @param clazz 持久类
* @param id 标识符
* @param lockMode 锁定模式
*
* @return 持久实例或空
*
* @deprecated LockMode参数应替换为LockOptions
*/
@Deprecated
public Object get(Class clazz, Serializable id, LockMode lockMode);
/**
* 返回具有给定标识符的给定实体类的持久实例;
* 如果没有此类持久实例,则返回空值.
* (如果实例已与会话关联,则返回该实例.此方法从不返回未初始化的实例.)
* 如果实例存在,则获取指定的锁定模式.
*
* @param clazz 持久类
* @param id 标识符
* @param lockOptions 锁定模式
*
* @return 持久实例或空
*/
public Object get(Class clazz, Serializable id, LockOptions lockOptions);
/**
* 返回具有给定标识符的给定命名实体的持久实例;
* 如果没有此类持久实例,则返回空.
* (如果实例已与会话关联,则返回该实例.此方法从不返回未初始化的实例.)
*
* @param entityName 实体名称
* @param id 标识符
*
* @return 持久实例或空
*/
public Object get(String entityName, Serializable id);
/**
* 返回具有给定标识符的给定实体类的持久实例;
* 如果没有此类持久实例,则返回空值.
* (如果实例已与会话关联,则返回该实例.此方法从不返回未初始化的实例.)
* 如果实例存在,则获取指定的锁定模式.
*
* @param entityName 实体名称
* @param id 标识符
* @param lockMode 锁定模式
*
* @return 持久实例或空
*
* @deprecated LockMode参数应替换为LockOptions
*/
@Deprecated
public Object get(String entityName, Serializable id, LockMode lockMode);
/**
* 返回具有给定标识符的给定实体类的持久实例;
* 如果没有此类持久实例,则返回空值.
* (如果实例已与会话关联,则返回该实例.此方法从不返回未初始化的实例.)
* 如果实例存在,则获取指定的锁定模式.
*
* @param entityName 实体名称
* @param id 标识符
* @param lockOptions 锁定模式
*
* @return 持久实例或空
*/
public Object get(String entityName, Serializable id, LockOptions lockOptions);
/**
* 返回持久实体的实体名称
*
* @param object 持久实体
*
* @return 实体名称
*/
public String getEntityName(Object object);
/**
* 创建{@link IdentifierLoadAccess}实例以按主键检索指定的实体类型.
*
* @param entityName 被检索的实体名称
*
* @return load 用于按主键加载指定实体类型的委托
*
* @throws HibernateException 如果无法将指定的实体名称解析为实体名称
*/
public IdentifierLoadAccess byId(String entityName);
/**
* 创建一个{@link IdentifierLoadAccess}实例以按主键检索指定的实体.
*
* @param entityClass 要检索的实体类型
*
* @return load 用于按主键加载指定实体类型的委托
*
* @throws HibernateException 如果指定的类无法解析为映射实体
*/
public IdentifierLoadAccess byId(Class entityClass);
/**
* 创建一个{@link NaturalIdLoadAccess}实例以根据其自然ID检索指定的实体.
*
* @param entityName 被检索的实体名称
*
* @return load 用于按自然ID加载指定实体类型的委托
*
* @throws HibernateException 如果无法将指定的实体名称解析为实体名称
*/
public NaturalIdLoadAccess byNaturalId(String entityName);
/**
* 创建一个{@link NaturalIdLoadAccess}实例以根据其自然ID检索指定的实体.
*
* @param entityClass 要检索的实体类型
*
* @return load 用于按自然ID加载指定实体类型的委托
*
* @throws HibernateException 如果指定的类无法解析为映射实体
*/
public NaturalIdLoadAccess byNaturalId(Class entityClass);
/**
* 创建一个{@link SimpleNaturalIdLoadAccess}实例以按其自然ID检索指定的实体.
*
* @param entityName 被检索的实体名称
*
* @return 用于按自然ID加载指定实体类型的加载委托
*
* @throws HibernateException 如果指定的EntityClass无法解析为映射的实体,
* 或者实体未定义自然ID,或者其自然ID由多个属性组成
*/
public SimpleNaturalIdLoadAccess bySimpleNaturalId(String entityName);
/**
* 创建一个{@link SimpleNaturalIdLoadAccess}实例以通过其简单(单个属性)自然ID检索指定的实体
*
* @param entityClass 要检索的实体类型
*
* @return 用于按自然ID加载指定实体类型的加载委托
*
* @throws HibernateException 如果指定的EntityClass无法解析为映射的实体,
* 或者实体未定义自然ID,或者其自然ID由多个属性组成
*/
public SimpleNaturalIdLoadAccess bySimpleNaturalId(Class entityClass);
/**
* 为当前会话启用命名过滤器.
*
* @param filterName 为当前会话启用命名过滤器.
*
* @return Filter实例表示启用的过滤器.
*/
public Filter enableFilter(String filterName);
/**
* 按名称检索当前启用的过滤器.
*
* @param filterName 要检索的过滤器的名称.
*
* @return Filter实例表示启用的过滤器.
*/
public Filter getEnabledFilter(String filterName);
/**
* 禁用当前会话的命名过滤器.
*
* @param filterName 要禁用的过滤器的名称.
*/
public void disableFilter(String filterName);
/**
* 获取此会话的统计信息.
*
* @return 正在为此会话收集会话统计信息
*/
public SessionStatistics getStatistics();
/**
* 指定的实体或代理是否为只读?
*
* 获取用于加载到会话中的实体和代理的默认只读/可修改设置:
* @see org.hibernate.Session#isDefaultReadOnly()
*
* @param entityOrProxy 实体或HibernateProxy
* @return {@code true} 如果实体或代理是只读的,{@code false}如果实体或代理是可修改的.
*/
public boolean isReadOnly(Object entityOrProxy);
/**
* 将未修改的持久对象设置为只读模式,或将只读对象设置为可修改模式.
* 在只读模式下,不维护快照,永远不会检查实例,并且不会保留更改.
*
* 如果实体或代理已经具有指定的只读/可修改设置,则此方法不执行任何操作.
*
* 设置用于加载到会话中的实体和代理的默认只读/可修改设置:
* @see org.hibernate.Session#setDefaultReadOnly(boolean)
*
* 要覆盖此会话的由Query加载的实体和代理的只读/可修改设置:
* @see Query#setReadOnly(boolean)
*
* @param entityOrProxy 实体或HibernateProxy
* @param readOnly {@code true} 如果实体或代理人应该是只读的; {@code false}如果实体或代理人应该可以修改
*/
public void setReadOnly(Object entityOrProxy, boolean readOnly);
/**
*控制器,允许用户使用此会话管理的Connection执行与JDBC相关的工作.
*
* @param work 要完成的工作.
* @throws HibernateException 通常表示包裹的 {@link java.sql.SQLException}
*/
public void doWork(Work work) throws HibernateException;
/**
* 控制器,允许用户使用此会话管理的Connection执行与JDBC相关的工作.
* 执行后返回{@link ReturningWork#execute}调用的结果
*
* @param work 要完成的工作.
*
* @return the 调用{@link ReturningWork#execute}的结果
*
* @throws HibernateException 通常表示包裹的 {@link java.sql.SQLException}
*/
public <T> T doReturningWork(ReturningWork<T> work) throws HibernateException;
/**
* 断开会话与其基础JDBC连接的连接。这适用于以下情况:
* 应用程序提供了与会话的JDBC连接,并且需要长会话(也称为会话).
* <p/>
* 在未通过提供JDBC连接打开的会话上调用此方法被认为是错误,并且将引发异常.
* <p/>
* 对于非用户提供的方案,正常的事务管理已经自动处理断开连接和重新连接.
*
* @return 应用程序提供的连接或{@code null}
*
* @see #reconnect(Connection)
*/
Connection disconnect();
/**
* 重新连接到给定的JDBC连接.
*
* @param connection JDBC连接
*
* @see #disconnect()
*/
void reconnect(Connection connection);
/**
* 此会话是否启用了特定的提取配置文件?
*
* @param name 要检查的配置文件的名称
* @return 如果启用了获取配置文件,则为True; 否则为false。.
* @throws UnknownProfileException 表示给定名称与任何已知的配置文件名称都不匹配
*
* @see org.hibernate.engine.profile.FetchProfile for discussion of this feature
*/
public boolean isFetchProfileEnabled(String name) throws UnknownProfileException;
/**
* 在此会话上启用特定的提取配置文件。 如果已启用请求的配置文件,则为无操作.
*
* @param name 要启用的提取配置文件的名称.
* @throws UnknownProfileException 表示给定名称与任何已知的配置文件名称都不匹配
*
* @see org.hibernate.engine.profile.FetchProfile for discussion of this feature
*/
public void enableFetchProfile(String name) throws UnknownProfileException;
/**
* 禁用此会话上的特定提取配置文件. 如果请求的配置文件已被禁用,则为No-op.
*
* @param name 要禁用的提取配置文件的名称.
* @throws UnknownProfileException 表示给定名称与任何已知的配置文件名称都不匹配
*
* @see org.hibernate.engine.profile.FetchProfile for discussion of this feature
*/
public void disableFetchProfile(String name) throws UnknownProfileException;
/**
* 方便地访问与此会话的{@link SessionFactory}相关联的{@link TypeHelper}
* <p/>
* 相当于调用{@link #getSessionFactory()}.{@link SessionFactory#getTypeHelper getTypeHelper()}
*
* @return {@link TypeHelper}与此会话的{@link SessionFactory}相关联
*/
public TypeHelper getTypeHelper();
/**
* 检索此会话的帮助程序/委托以创建LOB实例.
*
* @return 这个会话的LOB助手
*/
public LobHelper getLobHelper();
/**
* 包含锁定详细信息(LockMode, Timeout and Scope).
*/
public interface LockRequest {
static final int PESSIMISTIC_NO_WAIT = 0;
static final int PESSIMISTIC_WAIT_FOREVER = -1;
/**
* 获取锁定模式.
*
* @return 锁定模式.
*/
LockMode getLockMode();
/**
* 指定要使用的LockMode.默认值为LockMode.none.
*
* @param lockMode 用于此请求的锁定模式
*
* @return 这个LockRequest实例用于操作链接.
*/
LockRequest setLockMode(LockMode lockMode);
/**
* 获取超时设置.
*
* @return timeout(以毫秒为单位),-1表示无限期等待,0表示无等待.
*/
int getTimeOut();
/**
* 指定悲观锁定超时(检查您的方言是否支持此选项).
* 默认的悲观锁定行为是永远等待锁定
*
* @param timeout 是等待锁定的时间(以毫秒为单位)。 -1表示永远等待,0表示不等待.
*
* @return 这个LockRequest实例用于操作链接.
*/
LockRequest setTimeOut(int timeout);
/**
* 检查锁定是否级联到拥有的集合和关系.
*
* @return 如果锁定将扩展到拥有的集合和关系,则为true.
*/
boolean getScope();
/**
* 指定是否应将LockMode级联为拥有的集合和关系.
* 必须使用{@code cascade="lock"}映射关联,才能使scope = true起作用
*
* @param scope {@code true} 级联锁; {@code false} 没有.
*
* @return {@code this}, 方法链接
*/
LockRequest setScope(boolean scope);
void lock(String entityName, Object object) throws HibernateException;
public void lock(Object object) throws HibernateException;
}
}