public interface Session extends SharedSessionContract, EntityManager, HibernateEntityManager, AutoCloseable, Closeable
The main runtime interface between a Java application and Hibernate. This is the central API class abstracting the notion of a persistence service.<br> <br> The lifecycle of a <tt>Session</tt> is bounded by the beginning and end of a logical transaction. (Long transactions might span several database transactions.)<br> <br> The main function of the <tt>Session</tt> is to offer create, read and delete operations for instances of mapped entity classes. Instances may exist in one of three states:<br> <br> <i>transient:</i> never persistent, not associated with any <tt>Session</tt><br> <i>persistent:</i> associated with a unique <tt>Session</tt><br> <i>detached:</i> previously persistent, not associated with any <tt>Session</tt><br> <br> Transient instances may be made persistent by calling <tt>save()</tt>, <tt>persist()</tt> or <tt>saveOrUpdate()</tt>. Persistent instances may be made transient by calling<tt> delete()</tt>. Any instance returned by a <tt>get()</tt> or <tt>load()</tt> method is persistent. Detached instances may be made persistent by calling <tt>update()</tt>, <tt>saveOrUpdate()</tt>, <tt>lock()</tt> or <tt>replicate()</tt>. The state of a transient or detached instance may also be made persistent as a new persistent instance by calling <tt>merge()</tt>.<br> <br> <tt>save()</tt> and <tt>persist()</tt> result in an SQL <tt>INSERT</tt>, <tt>delete()</tt> in an SQL <tt>DELETE</tt> and <tt>update()</tt> or <tt>merge()</tt> in an SQL <tt>UPDATE</tt>. Changes to <i>persistent</i> instances are detected at flush time and also result in an SQL <tt>UPDATE</tt>. <tt>saveOrUpdate()</tt> and <tt>replicate()</tt> result in either an <tt>INSERT</tt> or an <tt>UPDATE</tt>.<br> <br> It is not intended that implementors be threadsafe. Instead each thread/transaction should obtain its own instance from a <tt>SessionFactory</tt>.<br> <br> A <tt>Session</tt> instance is serializable if its persistent classes are serializable.<br> <br> A typical transaction should use the following idiom: <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> If the <tt>Session</tt> throws an exception, the transaction must be rolled back and the session discarded. The internal state of the <tt>Session</tt> might not be consistent with the database after the exception occurs.
SessionFactory
Modifier and Type | Interface and Description |
---|---|
static interface |
Session.LockRequest
Contains locking details (LockMode, Timeout and Scope).
|
Modifier and Type | Method and Description |
---|---|
void |
addEventListeners(SessionEventListener... listeners)
Add one or more listeners to the Session
|
Session.LockRequest |
buildLockRequest(LockOptions lockOptions)
Build a LockRequest that specifies the LockMode, pessimistic lock timeout and lock scope.
|
<T> IdentifierLoadAccess<T> |
byId(Class<T> entityClass)
Create an
IdentifierLoadAccess instance to retrieve the specified entity by
primary key. |
IdentifierLoadAccess |
byId(String entityName)
Create an
IdentifierLoadAccess instance to retrieve the specified entity type by
primary key. |
<T> MultiIdentifierLoadAccess<T> |
byMultipleIds(Class<T> entityClass)
Create a
MultiIdentifierLoadAccess instance to retrieve multiple entities at once
as specified by primary key values. |
MultiIdentifierLoadAccess |
byMultipleIds(String entityName)
Create a
MultiIdentifierLoadAccess instance to retrieve multiple entities at once
as specified by primary key values. |
<T> NaturalIdLoadAccess<T> |
byNaturalId(Class<T> entityClass)
Create a
NaturalIdLoadAccess instance to retrieve the specified entity by
its natural id. |
NaturalIdLoadAccess |
byNaturalId(String entityName)
Create a
NaturalIdLoadAccess instance to retrieve the specified entity by
its natural id. |
<T> SimpleNaturalIdLoadAccess<T> |
bySimpleNaturalId(Class<T> entityClass)
Create a
SimpleNaturalIdLoadAccess instance to retrieve the specified entity by
its simple (single attribute) natural id. |
SimpleNaturalIdLoadAccess |
bySimpleNaturalId(String entityName)
Create a
SimpleNaturalIdLoadAccess instance to retrieve the specified entity by
its natural id. |
void |
cancelQuery()
Cancel the execution of the current query.
|
void |
clear()
Completely clear the session.
|
boolean |
contains(String entityName,
Object object)
Check if this entity is associated with this Session.
|
Query |
createFilter(Object collection,
String queryString)
Deprecated.
(since 5.3) with no real replacement.
|
<T> Query<T> |
createNamedQuery(String name,
Class<T> resultType)
The JPA-defined named, typed query creation method.
|
Query |
createQuery(CriteriaDelete deleteQuery) |
<T> Query<T> |
createQuery(CriteriaQuery<T> criteriaQuery) |
Query |
createQuery(CriteriaUpdate updateQuery) |
Query |
createQuery(String queryString)
Create a
Query instance for the given HQL/JPQL query string. |
<T> Query<T> |
createQuery(String queryString,
Class<T> resultType)
Create a typed
Query instance for the given HQL/JPQL query string. |
void |
delete(Object object)
Remove a persistent instance from the datastore.
|
void |
delete(String entityName,
Object object)
Remove a persistent instance from the datastore.
|
void |
disableFetchProfile(String name)
Disable a particular fetch profile on this session.
|
void |
disableFilter(String filterName)
Disable the named filter for the current session.
|
Connection |
disconnect()
Disconnect the session from its underlying JDBC connection.
|
<T> T |
doReturningWork(ReturningWork<T> work)
Controller for allowing users to perform JDBC related work using the Connection managed by this Session.
|
void |
doWork(Work work)
Controller for allowing users to perform JDBC related work using the Connection managed by this Session.
|
void |
enableFetchProfile(String name)
Enable a particular fetch profile on this session.
|
Filter |
enableFilter(String filterName)
Enable the named filter for this current session.
|
void |
evict(Object object)
Remove this instance from the session cache.
|
void |
flush()
Force this session to flush.
|
<T> T |
get(Class<T> entityType,
Serializable id)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance.
|
<T> T |
get(Class<T> entityType,
Serializable id,
LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance.
|
<T> T |
get(Class<T> entityType,
Serializable id,
LockOptions lockOptions)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance.
|
Object |
get(String entityName,
Serializable id)
Return the persistent instance of the given named entity with the given identifier,
or null if there is no such persistent instance.
|
Object |
get(String entityName,
Serializable id,
LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance.
|
Object |
get(String entityName,
Serializable id,
LockOptions lockOptions)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance.
|
CacheMode |
getCacheMode()
Get the current cache mode.
|
LockMode |
getCurrentLockMode(Object object)
Determine the current lock mode of the given object.
|
Filter |
getEnabledFilter(String filterName)
Retrieve a currently enabled filter by name.
|
String |
getEntityName(Object object)
Return the entity name for a persistent entity.
|
FlushModeType |
getFlushMode()
<p/>
For users of the Hibernate native APIs, we’ve had to rename this method
as defined by Hibernate historically because the JPA contract defines a method of the same
name, but returning the JPA
FlushModeType rather than Hibernate’s FlushMode . |
FlushMode |
getHibernateFlushMode()
Get the current flush mode for this session.
|
Serializable |
getIdentifier(Object object)
Return the identifier value of the given entity as associated with this
session.
|
LobHelper |
getLobHelper()
Retrieve this session’s helper/delegate for creating LOB instances.
|
SessionFactory |
getSessionFactory()
Get the session factory which created this session.
|
SessionStatistics |
getStatistics()
Get the statistics for this session.
|
TypeHelper |
getTypeHelper()
Convenience access to the
TypeHelper associated with this session’s SessionFactory . |
boolean |
isDefaultReadOnly()
Will entities and proxies that are loaded into this session be made
read-only by default?
|
boolean |
isDirty()
Does this session contain any changes which must be synchronized with
the database? In other words, would any DML operations be executed if
we flushed this session?
|
boolean |
isFetchProfileEnabled(String name)
Is a particular fetch profile enabled on this session?
|
boolean |
isReadOnly(Object entityOrProxy)
Is the specified entity or proxy read-only?
|
<T> T |
load(Class<T> theClass,
Serializable id)
Return the persistent instance of the given entity class with the given identifier,
assuming that the instance exists.
|
<T> T |
load(Class<T> theClass,
Serializable id,
LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
obtaining the specified lock mode, assuming the instance exists.
|
<T> T |
load(Class<T> theClass,
Serializable id,
LockOptions lockOptions)
Return the persistent instance of the given entity class with the given identifier,
obtaining the specified lock mode, assuming the instance exists.
|
void |
load(Object object,
Serializable id)
Read the persistent state associated with the given identifier into the given transient
instance.
|
Object |
load(String entityName,
Serializable id)
Return the persistent instance of the given entity class with the given identifier,
assuming that the instance exists.
|
Object |
load(String entityName,
Serializable id,
LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
obtaining the specified lock mode, assuming the instance exists.
|
Object |
load(String entityName,
Serializable id,
LockOptions lockOptions)
Return the persistent instance of the given entity class with the given identifier,
obtaining the specified lock mode, assuming the instance exists.
|
void |
lock(Object object,
LockMode lockMode)
Obtain the specified lock level upon the given object.
|
void |
lock(String entityName,
Object object,
LockMode lockMode)
Obtain the specified lock level upon the given object.
|
Object |
merge(Object object)
Copy the state of the given object onto the persistent object with the same
identifier.
|
Object |
merge(String entityName,
Object object)
Copy the state of the given object onto the persistent object with the same
identifier.
|
void |
persist(Object object)
Make a transient instance persistent.
|
void |
persist(String entityName,
Object object)
Make a transient instance persistent.
|
void |
reconnect(Connection connection)
Reconnect to the given JDBC connection.
|
void |
refresh(Object object)
Re-read the state of the given instance from the underlying database.
|
void |
refresh(Object object,
LockMode lockMode)
Re-read the state of the given instance from the underlying database, with
the given <tt>LockMode</tt>.
|
void |
refresh(Object object,
LockOptions lockOptions)
Re-read the state of the given instance from the underlying database, with
the given <tt>LockMode</tt>.
|
void |
refresh(String entityName,
Object object)
Re-read the state of the given instance from the underlying database.
|
void |
refresh(String entityName,
Object object,
LockOptions lockOptions)
Re-read the state of the given instance from the underlying database, with
the given <tt>LockMode</tt>.
|
void |
replicate(Object object,
ReplicationMode replicationMode)
Persist the state of the given detached instance, reusing the current
identifier value.
|
void |
replicate(String entityName,
Object object,
ReplicationMode replicationMode)
Persist the state of the given detached instance, reusing the current
identifier value.
|
Serializable |
save(Object object)
Persist the given transient instance, first assigning a generated identifier.
|
Serializable |
save(String entityName,
Object object)
Persist the given transient instance, first assigning a generated identifier.
|
void |
saveOrUpdate(Object object)
Either
save(Object) or update(Object) the given
instance, depending upon resolution of the unsaved-value checks (see the
manual for discussion of unsaved-value checking). |
void |
saveOrUpdate(String entityName,
Object object)
Either
save(String, Object) or update(String, Object)
the given instance, depending upon resolution of the unsaved-value checks
(see the manual for discussion of unsaved-value checking). |
SharedSessionBuilder |
sessionWithOptions()
Obtain a
Session builder with the ability to grab certain information from this session. |
void |
setCacheMode(CacheMode cacheMode)
Set the cache mode.
|
void |
setDefaultReadOnly(boolean readOnly)
Change the default for entities and proxies loaded into this session
from modifiable to read-only mode, or from modifiable to read-only mode.
|
void |
setFlushMode(FlushMode flushMode)
Deprecated.
(since 5.2) use
setHibernateFlushMode(FlushMode) instead |
void |
setHibernateFlushMode(FlushMode flushMode)
Set the flush mode for this session.
|
void |
setReadOnly(Object entityOrProxy,
boolean readOnly)
Set an unmodified persistent object to read-only mode, or a read-only
object to modifiable mode.
|
void |
update(Object object)
Update the persistent instance with the identifier of the given detached
instance.
|
void |
update(String entityName,
Object object)
Update the persistent instance with the identifier of the given detached
instance.
|
beginTransaction, close, createCriteria, createCriteria, createCriteria, createCriteria, createStoredProcedureCall, createStoredProcedureCall, createStoredProcedureCall, getJdbcBatchSize, getNamedProcedureCall, getTenantIdentifier, getTransaction, isConnected, isOpen, setJdbcBatchSize
getSession
close, contains, createEntityGraph, createEntityGraph, createNamedQuery, createNamedStoredProcedureQuery, createNativeQuery, createNativeQuery, createNativeQuery, createStoredProcedureQuery, createStoredProcedureQuery, createStoredProcedureQuery, detach, find, find, find, find, getCriteriaBuilder, getDelegate, getEntityGraph, getEntityGraphs, getEntityManagerFactory, getLockMode, getMetamodel, getProperties, getReference, getTransaction, isJoinedToTransaction, isOpen, joinTransaction, lock, lock, refresh, refresh, refresh, remove, setFlushMode, setProperty, unwrap
createNamedQuery, createNativeQuery, createNativeQuery, createNativeQuery, createSQLQuery, getNamedNativeQuery, getNamedQuery, getNamedSQLQuery
SharedSessionBuilder sessionWithOptions()
Obtain a Session
builder with the ability to grab certain information from this session.
void flush() throws HibernateException
Force this session to flush. Must be called at the end of a
unit of work, before committing the transaction and closing the
session (depending on setFlushMode(FlushMode)
,
EntityTransaction.commit()
calls this method).
<p/>
<i>Flushing</i> is the process of synchronizing the underlying persistent
store with persistable state held in memory.
flush
in interface EntityManager
HibernateException
- Indicates problems flushing the session or
talking to the database.@Deprecated void setFlushMode(FlushMode flushMode)
setHibernateFlushMode(FlushMode)
insteadSet the flush mode for this session.
<p/>
The flush mode determines the points at which the session is flushed.
<i>Flushing</i> is the process of synchronizing the underlying persistent
store with persistable state held in memory.
<p/>
For a logically "read only" session, it is reasonable to set the session’s
flush mode to FlushMode.MANUAL
at the start of the session (in
order to achieve some extra performance).
flushMode
- the new flush modeFlushModeType getFlushMode()
<p/>
For users of the Hibernate native APIs, we’ve had to rename this method
as defined by Hibernate historically because the JPA contract defines a method of the same
name, but returning the JPA FlushModeType
rather than Hibernate’s FlushMode
. For
the former behavior, use getHibernateFlushMode()
instead.
getFlushMode
in interface EntityManager
void setHibernateFlushMode(FlushMode flushMode)
Set the flush mode for this session.
<p/>
The flush mode determines the points at which the session is flushed.
<i>Flushing</i> is the process of synchronizing the underlying persistent
store with persistable state held in memory.
<p/>
For a logically "read only" session, it is reasonable to set the session’s
flush mode to FlushMode.MANUAL
at the start of the session (in
order to achieve some extra performance).
flushMode
- the new flush modeFlushMode getHibernateFlushMode()
Get the current flush mode for this session.
void setCacheMode(CacheMode cacheMode)
Set the cache mode. <p/> Cache mode determines the manner in which this session can interact with the second level cache.
cacheMode
- The new cache mode.CacheMode getCacheMode()
Get the current cache mode.
SessionFactory getSessionFactory()
Get the session factory which created this session.
SessionFactory
void cancelQuery() throws HibernateException
Cancel the execution of the current query. <p/> This is the sole method on session which may be safely called from another thread.
HibernateException
- There was a problem canceling the queryboolean isDirty() throws HibernateException
Does this session contain any changes which must be synchronized with the database? In other words, would any DML operations be executed if we flushed this session?
HibernateException
- could not perform dirtying checkingboolean isDefaultReadOnly()
Will entities and proxies that are loaded into this session be made read-only by default?
To determine the read-only/modifiable setting for a particular entity or proxy:
isReadOnly(Object)
void setDefaultReadOnly(boolean readOnly)
Change the default for entities and proxies loaded into this session from modifiable to read-only mode, or from modifiable to read-only mode.
Read-only entities are not dirty-checked and snapshots of persistent state are not maintained. Read-only entities can be modified, but changes are not persisted.
When a proxy is initialized, the loaded entity will have the same read-only/modifiable setting as the uninitialized proxy has, regardless of the session’s current setting.
To change the read-only/modifiable setting for a particular entity or proxy that is already in this session:
readOnly
- true, the default for loaded entities/proxies is read-only;
false, the default for loaded entities/proxies is modifiablesetReadOnly(Object,boolean)
,
Query.setReadOnly(boolean)
Serializable getIdentifier(Object object)
Return the identifier value of the given entity as associated with this session. An exception is thrown if the given entity instance is transient or detached in relation to this session.
object
- a persistent instanceTransientObjectException
- if the instance is transient or associated with
a different sessionboolean contains(String entityName, Object object)
Check if this entity is associated with this Session. This form caters to non-POJO entities, by allowing the entity-name to be passed in
entityName
- The entity nameobject
- an instance of a persistent classvoid evict(Object object)
Remove this instance from the session cache. Changes to the instance will not be synchronized with the database. This operation cascades to associated instances if the association is mapped with <tt>cascade="evict"</tt>.
object
- The entity to evictNullPointerException
- if the passed object is null
IllegalArgumentException
- if the passed object is not defined as an entity<T> T load(Class<T> theClass, Serializable id, LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
obtaining the specified lock mode, assuming the instance exists.
<p/>
Convenient form of load(Class, Serializable, LockOptions)
theClass
- a persistent classid
- a valid identifier of an existing persistent instance of the classlockMode
- the lock levelload(Class, Serializable, LockOptions)
<T> T load(Class<T> theClass, Serializable id, LockOptions lockOptions)
Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.
theClass
- a persistent classid
- a valid identifier of an existing persistent instance of the classlockOptions
- contains the lock levelObject load(String entityName, Serializable id, LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
obtaining the specified lock mode, assuming the instance exists.
<p/>
Convenient form of load(String, Serializable, LockOptions)
entityName
- a persistent classid
- a valid identifier of an existing persistent instance of the classlockMode
- the lock levelload(String, Serializable, LockOptions)
Object load(String entityName, Serializable id, LockOptions lockOptions)
Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.
entityName
- a persistent classid
- a valid identifier of an existing persistent instance of the classlockOptions
- contains the lock level<T> T load(Class<T> theClass, Serializable id)
Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists. This method might return a proxied instance that is initialized on-demand, when a non-identifier method is accessed. <br><br> You should not use this method to determine if an instance exists (use <tt>get()</tt> instead). Use this only to retrieve an instance that you assume exists, where non-existence would be an actual error.
theClass
- a persistent classid
- a valid identifier of an existing persistent instance of the classObject load(String entityName, Serializable id)
Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists. This method might return a proxied instance that is initialized on-demand, when a non-identifier method is accessed. <br><br> You should not use this method to determine if an instance exists (use <tt>get()</tt> instead). Use this only to retrieve an instance that you assume exists, where non-existence would be an actual error.
entityName
- a persistent classid
- a valid identifier of an existing persistent instance of the classvoid load(Object object, Serializable id)
Read the persistent state associated with the given identifier into the given transient instance.
object
- an "empty" instance of the persistent classid
- a valid identifier of an existing persistent instance of the classvoid replicate(Object object, ReplicationMode replicationMode)
Persist the state of the given detached instance, reusing the current
identifier value. This operation cascades to associated instances if
the association is mapped with cascade="replicate"
object
- a detached instance of a persistent classreplicationMode
- The replication mode to usevoid replicate(String entityName, Object object, ReplicationMode replicationMode)
Persist the state of the given detached instance, reusing the current
identifier value. This operation cascades to associated instances if
the association is mapped with cascade="replicate"
entityName
- The entity nameobject
- a detached instance of a persistent classreplicationMode
- The replication mode to useSerializable save(Object object)
Persist the given transient instance, first assigning a generated identifier. (Or
using the current value of the identifier property if the <tt>assigned</tt>
generator is used.) This operation cascades to associated instances if the
association is mapped with cascade="save-update"
object
- a transient instance of a persistent classSerializable save(String entityName, Object object)
Persist the given transient instance, first assigning a generated identifier. (Or
using the current value of the identifier property if the <tt>assigned</tt>
generator is used.) This operation cascades to associated instances if the
association is mapped with cascade="save-update"
entityName
- The entity nameobject
- a transient instance of a persistent classvoid saveOrUpdate(Object object)
Either save(Object)
or update(Object)
the given
instance, depending upon resolution of the unsaved-value checks (see the
manual for discussion of unsaved-value checking).
<p/>
This operation cascades to associated instances if the association is mapped
with cascade="save-update"
object
- a transient or detached instance containing new or updated statesave(java.lang.Object)
,
update(Object object)
void saveOrUpdate(String entityName, Object object)
Either save(String, Object)
or update(String, Object)
the given instance, depending upon resolution of the unsaved-value checks
(see the manual for discussion of unsaved-value checking).
<p/>
This operation cascades to associated instances if the association is mapped
with cascade="save-update"
entityName
- The entity nameobject
- a transient or detached instance containing new or updated statesave(String,Object)
,
update(String,Object)
void update(Object object)
Update the persistent instance with the identifier of the given detached
instance. If there is a persistent instance with the same identifier,
an exception is thrown. This operation cascades to associated instances
if the association is mapped with cascade="save-update"
object
- a detached instance containing updated statevoid update(String entityName, Object object)
Update the persistent instance with the identifier of the given detached
instance. If there is a persistent instance with the same identifier,
an exception is thrown. This operation cascades to associated instances
if the association is mapped with cascade="save-update"
entityName
- The entity nameobject
- a detached instance containing updated stateObject merge(Object object)
Copy the state of the given object onto the persistent object with the same
identifier. If there is no persistent instance currently associated with
the session, it will be loaded. Return the persistent instance. If the
given instance is unsaved, save a copy of and return it as a newly persistent
instance. The given instance does not become associated with the session.
This operation cascades to associated instances if the association is mapped
with cascade="merge"
<p/>
The semantics of this method are defined by JSR-220.
merge
in interface EntityManager
object
- a detached instance with state to be copiedObject merge(String entityName, Object object)
Copy the state of the given object onto the persistent object with the same
identifier. If there is no persistent instance currently associated with
the session, it will be loaded. Return the persistent instance. If the
given instance is unsaved, save a copy of and return it as a newly persistent
instance. The given instance does not become associated with the session.
This operation cascades to associated instances if the association is mapped
with cascade="merge"
<p/>
The semantics of this method are defined by JSR-220.
entityName
- The entity nameobject
- a detached instance with state to be copiedvoid persist(Object object)
Make a transient instance persistent. This operation cascades to associated
instances if the association is mapped with cascade="persist"
<p/>
The semantics of this method are defined by JSR-220.
persist
in interface EntityManager
object
- a transient instance to be made persistentvoid persist(String entityName, Object object)
Make a transient instance persistent. This operation cascades to associated
instances if the association is mapped with cascade="persist"
<p/>
The semantics of this method are defined by JSR-220.
entityName
- The entity nameobject
- a transient instance to be made persistentvoid delete(Object object)
Remove a persistent instance from the datastore. The argument may be
an instance associated with the receiving <tt>Session</tt> or a transient
instance with an identifier associated with existing persistent state.
This operation cascades to associated instances if the association is mapped
with cascade="delete"
object
- the instance to be removedvoid delete(String entityName, Object object)
Remove a persistent instance from the datastore. The <b>object</b> argument may be
an instance associated with the receiving <tt>Session</tt> or a transient
instance with an identifier associated with existing persistent state.
This operation cascades to associated instances if the association is mapped
with cascade="delete"
entityName
- The entity name for the instance to be removed.object
- the instance to be removedvoid lock(Object object, LockMode lockMode)
Obtain the specified lock level upon the given object. This may be used to
perform a version check (<tt>LockMode.READ</tt>), to upgrade to a pessimistic
lock (<tt>LockMode.PESSIMISTIC_WRITE</tt>), or to simply reassociate a transient instance
with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
instances if the association is mapped with <tt>cascade="lock"</tt>.
<p/>
Convenient form of Session.LockRequest.lock(Object)
via buildLockRequest(LockOptions)
object
- a persistent or transient instancelockMode
- the lock levelbuildLockRequest(LockOptions)
,
Session.LockRequest.lock(Object)
void lock(String entityName, Object object, LockMode lockMode)
Obtain the specified lock level upon the given object. This may be used to
perform a version check (<tt>LockMode.OPTIMISTIC</tt>), to upgrade to a pessimistic
lock (<tt>LockMode.PESSIMISTIC_WRITE</tt>), or to simply reassociate a transient instance
with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
instances if the association is mapped with <tt>cascade="lock"</tt>.
<p/>
Convenient form of Session.LockRequest.lock(String, Object)
via buildLockRequest(LockOptions)
entityName
- The name of the entityobject
- a persistent or transient instancelockMode
- the lock levelbuildLockRequest(LockOptions)
,
Session.LockRequest.lock(String, Object)
Session.LockRequest buildLockRequest(LockOptions lockOptions)
Build a LockRequest that specifies the LockMode, pessimistic lock timeout and lock scope.
timeout and scope is ignored for optimistic locking. After building the LockRequest,
call LockRequest.lock to perform the requested locking.
<p/>
Example usage:
session.buildLockRequest().setLockMode(LockMode.PESSIMISTIC_WRITE).setTimeOut(60000).lock(entity);
lockOptions
- contains the lock levelvoid refresh(Object object)
Re-read the state of the given instance from the underlying database. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances. For example <ul> <li>where a database trigger alters the object state upon insert or update <li>after executing direct SQL (eg. a mass update) in the same session <li>after inserting a <tt>Blob</tt> or <tt>Clob</tt> </ul>
refresh
in interface EntityManager
object
- a persistent or detached instancevoid refresh(String entityName, Object object)
Re-read the state of the given instance from the underlying database. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances. For example <ul> <li>where a database trigger alters the object state upon insert or update <li>after executing direct SQL (eg. a mass update) in the same session <li>after inserting a <tt>Blob</tt> or <tt>Clob</tt> </ul>
entityName
- a persistent classobject
- a persistent or detached instancevoid refresh(Object object, LockMode lockMode)
Re-read the state of the given instance from the underlying database, with
the given <tt>LockMode</tt>. It is inadvisable to use this to implement
long-running sessions that span many business tasks. This method is, however,
useful in certain special circumstances.
<p/>
Convenient form of refresh(Object, LockOptions)
object
- a persistent or detached instancelockMode
- the lock mode to userefresh(Object, LockOptions)
void refresh(Object object, LockOptions lockOptions)
Re-read the state of the given instance from the underlying database, with the given <tt>LockMode</tt>. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances.
object
- a persistent or detached instancelockOptions
- contains the lock mode to usevoid refresh(String entityName, Object object, LockOptions lockOptions)
Re-read the state of the given instance from the underlying database, with the given <tt>LockMode</tt>. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances.
entityName
- a persistent classobject
- a persistent or detached instancelockOptions
- contains the lock mode to useLockMode getCurrentLockMode(Object object)
Determine the current lock mode of the given object.
object
- a persistent instance@Deprecated Query createFilter(Object collection, String queryString)
Create a Query
instance for the given collection and filter string. Contains an implicit FROM
element named this
which refers to the defined table for the collection elements, as well as an implicit
WHERE
restriction for this particular collection instance’s key value.
collection
- a persistent collectionqueryString
- a Hibernate query fragment.void clear()
Completely clear the session. Evict all loaded instances and cancel all pending saves, updates and deletions. Do not close open iterators or instances of <tt>ScrollableResults</tt>.
clear
in interface EntityManager
<T> T get(Class<T> entityType, Serializable id)
Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.)
entityType
- The entity typeid
- an identifier<T> T get(Class<T> entityType, Serializable id, LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance. (If the instance is already associated
with the session, return that instance. This method never returns an uninitialized instance.)
Obtain the specified lock mode if the instance exists.
<p/>
Convenient form of get(Class, Serializable, LockOptions)
entityType
- The entity typeid
- an identifierlockMode
- the lock modeget(Class, Serializable, LockOptions)
<T> T get(Class<T> entityType, Serializable id, LockOptions lockOptions)
Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.) Obtain the specified lock mode if the instance exists.
entityType
- The entity typeid
- an identifierlockOptions
- the lock modeObject get(String entityName, Serializable id)
Return the persistent instance of the given named entity with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.)
entityName
- the entity nameid
- an identifierObject get(String entityName, Serializable id, LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance. (If the instance is already associated
with the session, return that instance. This method never returns an uninitialized instance.)
Obtain the specified lock mode if the instance exists.
<p/>
Convenient form of get(String, Serializable, LockOptions)
entityName
- the entity nameid
- an identifierlockMode
- the lock modeget(String, Serializable, LockOptions)
Object get(String entityName, Serializable id, LockOptions lockOptions)
Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.) Obtain the specified lock mode if the instance exists.
entityName
- the entity nameid
- an identifierlockOptions
- contains the lock modeString getEntityName(Object object)
Return the entity name for a persistent entity.
object
- a persistent entityIdentifierLoadAccess byId(String entityName)
Create an IdentifierLoadAccess
instance to retrieve the specified entity type by
primary key.
entityName
- The entity name of the entity type to be retrievedHibernateException
- If the specified entity name cannot be resolved as an entity name<T> MultiIdentifierLoadAccess<T> byMultipleIds(Class<T> entityClass)
Create a MultiIdentifierLoadAccess
instance to retrieve multiple entities at once
as specified by primary key values.
entityClass
- The entity type to be retrievedHibernateException
- If the specified Class cannot be resolved as a mapped entityMultiIdentifierLoadAccess byMultipleIds(String entityName)
Create a MultiIdentifierLoadAccess
instance to retrieve multiple entities at once
as specified by primary key values.
entityName
- The entity name of the entity type to be retrievedHibernateException
- If the specified entity name cannot be resolved as an entity name<T> IdentifierLoadAccess<T> byId(Class<T> entityClass)
Create an IdentifierLoadAccess
instance to retrieve the specified entity by
primary key.
entityClass
- The entity type to be retrievedHibernateException
- If the specified Class cannot be resolved as a mapped entityNaturalIdLoadAccess byNaturalId(String entityName)
Create a NaturalIdLoadAccess
instance to retrieve the specified entity by
its natural id.
entityName
- The entity name of the entity type to be retrievedHibernateException
- If the specified entity name cannot be resolved as an entity name<T> NaturalIdLoadAccess<T> byNaturalId(Class<T> entityClass)
Create a NaturalIdLoadAccess
instance to retrieve the specified entity by
its natural id.
entityClass
- The entity type to be retrievedHibernateException
- If the specified Class cannot be resolved as a mapped entitySimpleNaturalIdLoadAccess bySimpleNaturalId(String entityName)
Create a SimpleNaturalIdLoadAccess
instance to retrieve the specified entity by
its natural id.
entityName
- The entity name of the entity type to be retrievedHibernateException
- If the specified entityClass cannot be resolved as a mapped entity, or if the
entity does not define a natural-id or if its natural-id is made up of multiple attributes.<T> SimpleNaturalIdLoadAccess<T> bySimpleNaturalId(Class<T> entityClass)
Create a SimpleNaturalIdLoadAccess
instance to retrieve the specified entity by
its simple (single attribute) natural id.
entityClass
- The entity type to be retrievedHibernateException
- If the specified entityClass cannot be resolved as a mapped entity, or if the
entity does not define a natural-id or if its natural-id is made up of multiple attributes.Filter enableFilter(String filterName)
Enable the named filter for this current session.
filterName
- The name of the filter to be enabled.Filter getEnabledFilter(String filterName)
Retrieve a currently enabled filter by name.
filterName
- The name of the filter to be retrieved.void disableFilter(String filterName)
Disable the named filter for the current session.
filterName
- The name of the filter to be disabled.SessionStatistics getStatistics()
Get the statistics for this session.
boolean isReadOnly(Object entityOrProxy)
Is the specified entity or proxy read-only?
To get the default read-only/modifiable setting used for entities and proxies that are loaded into the session:
entityOrProxy
- an entity or HibernateProxytrue
if the entity or proxy is read-only, false
if the entity or proxy is modifiable.isDefaultReadOnly()
void setReadOnly(Object entityOrProxy, boolean readOnly)
Set an unmodified persistent object to read-only mode, or a read-only object to modifiable mode. In read-only mode, no snapshot is maintained, the instance is never dirty checked, and changes are not persisted.
If the entity or proxy already has the specified read-only/modifiable setting, then this method does nothing.
To set the default read-only/modifiable setting used for entities and proxies that are loaded into the session:
entityOrProxy
- an entity or HibernateProxyreadOnly
- true
if the entity or proxy should be made read-only; false
if the entity or
proxy should be made modifiablesetDefaultReadOnly(boolean)
,
Query.setReadOnly(boolean)
void doWork(Work work) throws HibernateException
Controller for allowing users to perform JDBC related work using the Connection managed by this Session.
work
- The work to be performed.HibernateException
- Generally indicates wrapped SQLException
<T> T doReturningWork(ReturningWork<T> work) throws HibernateException
Controller for allowing users to perform JDBC related work using the Connection managed by this Session. After
execution returns the result of the ReturningWork.execute(java.sql.Connection)
call.
T
- The type of the result returned from the workwork
- The work to be performed.ReturningWork.execute(java.sql.Connection)
.HibernateException
- Generally indicates wrapped SQLException
Connection disconnect()
Disconnect the session from its underlying JDBC connection. This is intended for use in cases where the application has supplied the JDBC connection to the session and which require long-sessions (aka, conversations). <p/> It is considered an error to call this method on a session which was not opened by supplying the JDBC connection and an exception will be thrown. <p/> For non-user-supplied scenarios, normal transaction management already handles disconnection and reconnection automatically.
null
reconnect(Connection)
void reconnect(Connection connection)
Reconnect to the given JDBC connection.
connection
- a JDBC connectiondisconnect()
boolean isFetchProfileEnabled(String name) throws UnknownProfileException
Is a particular fetch profile enabled on this session?
name
- The name of the profile to be checked.UnknownProfileException
- Indicates that the given name does not
match any known profile namesfor discussion of this feature
void enableFetchProfile(String name) throws UnknownProfileException
Enable a particular fetch profile on this session. No-op if requested profile is already enabled.
name
- The name of the fetch profile to be enabled.UnknownProfileException
- Indicates that the given name does not
match any known profile namesfor discussion of this feature
void disableFetchProfile(String name) throws UnknownProfileException
Disable a particular fetch profile on this session. No-op if requested profile is already disabled.
name
- The name of the fetch profile to be disabled.UnknownProfileException
- Indicates that the given name does not
match any known profile namesfor discussion of this feature
TypeHelper getTypeHelper()
Convenience access to the TypeHelper
associated with this session’s SessionFactory
.
<p/>
Equivalent to calling getSessionFactory()
.getTypeHelper()
TypeHelper
associated with this session’s SessionFactory
LobHelper getLobHelper()
Retrieve this session’s helper/delegate for creating LOB instances.
void addEventListeners(SessionEventListener... listeners)
Add one or more listeners to the Session
listeners
- The listener(s) to addQuery createQuery(String queryString)
QueryProducer
Create a Query
instance for the given HQL/JPQL query string.
createQuery
in interface EntityManager
createQuery
in interface QueryProducer
queryString
- The HQL/JPQL queryEntityManager.createQuery(String)
<T> Query<T> createQuery(String queryString, Class<T> resultType)
QueryProducer
Create a typed Query
instance for the given HQL/JPQL query string.
createQuery
in interface EntityManager
createQuery
in interface QueryProducer
queryString
- The HQL/JPQL queryEntityManager.createQuery(String,Class)
<T> Query<T> createQuery(CriteriaQuery<T> criteriaQuery)
createQuery
in interface EntityManager
Query createQuery(CriteriaUpdate updateQuery)
createQuery
in interface EntityManager
Query createQuery(CriteriaDelete deleteQuery)
createQuery
in interface EntityManager
<T> Query<T> createNamedQuery(String name, Class<T> resultType)
QueryProducer
The JPA-defined named, typed query creation method. This form can only represent an HQL/JPQL query (not a native query).
createNamedQuery
in interface EntityManager
createNamedQuery
in interface QueryProducer
name
- the name of a query defined in metadataresultType
- the type of the query resultEntityManager.createNamedQuery(String,Class)
Copyright © 2001-2018 Red Hat, Inc. All Rights Reserved.