Interface Stage.Session
-
- All Superinterfaces:
Stage.Closeable
- Enclosing interface:
- Stage
public static interface Stage.Session extends Stage.Closeable
A non-blocking counterpart to the HibernateSession
interface, allowing a reactive style of interaction with the database.The semantics of operations on this interface are identical to the semantics of the similarly-named operations of
Session
, except that the operations are performed asynchronously, returning aCompletionStage
without blocking the calling thread.Entities associated with an
Session
do not support transparent lazy association fetching. Instead,fetch(Object)
should be used to explicitly request asynchronous fetching of an association, or the association should be fetched eagerly when the entity is first retrieved, for example, by:enabling a fetch profile
,- using an
EntityGraph
, or - writing a
join fetch
clause in a HQL query.
- See Also:
Session
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description Stage.Session
clear()
Completely clear the session.boolean
contains(Object entity)
Determine if the given instance belongs to this persistence context.<T> jakarta.persistence.EntityGraph<T>
createEntityGraph(Class<T> rootType)
Create a new mutableEntityGraph
<T> jakarta.persistence.EntityGraph<T>
createEntityGraph(Class<T> rootType, String graphName)
Create a new mutable copy of a namedEntityGraph
Stage.MutationQuery
createMutationQuery(String queryString)
Create an instance ofStage.MutationQuery
for the given HQL/JPQL update or delete statement.<R> Stage.Query<R>
createNamedQuery(String queryName)
Create an instance ofStage.Query
for the named query.<R> Stage.SelectionQuery<R>
createNamedQuery(String queryName, Class<R> resultType)
Create an instance ofStage.SelectionQuery
for the named query.<R> Stage.Query<R>
createNativeQuery(String queryString)
Create an instance ofStage.Query
for the given SQL query string, or SQL update, insert, or delete statement.<R> Stage.SelectionQuery<R>
createNativeQuery(String queryString, Class<R> resultType)
Create an instance ofStage.Query
for the given SQL query string, using the givenresultType
to interpret the results.<R> Stage.SelectionQuery<R>
createNativeQuery(String queryString, Class<R> resultType, AffectedEntities affectedEntities)
Create an instance ofStage.SelectionQuery
for the given SQL query string, using the givenresultType
to interpret the results.<R> Stage.Query<R>
createNativeQuery(String queryString, AffectedEntities affectedEntities)
Create an instance ofStage.Query
for the given SQL query string, or SQL update, insert, or delete statement.<R> Stage.SelectionQuery<R>
createNativeQuery(String queryString, ResultSetMapping<R> resultSetMapping)
Create an instance ofStage.SelectionQuery
for the given SQL query string, using the givenResultSetMapping
to interpret the result set.<R> Stage.SelectionQuery<R>
createNativeQuery(String queryString, ResultSetMapping<R> resultSetMapping, AffectedEntities affectedEntities)
Create an instance ofStage.SelectionQuery
for the given SQL query string, using the givenResultSetMapping
to interpret the result set.<R> Stage.MutationQuery
createQuery(jakarta.persistence.criteria.CriteriaDelete<R> criteriaDelete)
Create an instance ofStage.MutationQuery
for the given criteria delete.<R> Stage.SelectionQuery<R>
createQuery(jakarta.persistence.criteria.CriteriaQuery<R> criteriaQuery)
Create an instance ofStage.SelectionQuery
for the given criteria query.<R> Stage.MutationQuery
createQuery(jakarta.persistence.criteria.CriteriaUpdate<R> criteriaUpdate)
Create an instance ofStage.MutationQuery
for the given criteria update.<R> Stage.Query<R>
createQuery(String queryString)
Deprecated.See explanation inQueryProducer.createSelectionQuery(String)
<R> Stage.SelectionQuery<R>
createQuery(String queryString, Class<R> resultType)
Create an instance ofStage.SelectionQuery
for the given HQL/JPQL query string and query result type.<R> Stage.SelectionQuery<R>
createSelectionQuery(String queryString, Class<R> resultType)
Create an instance ofStage.SelectionQuery
for the given HQL/JPQL query string.Stage.Transaction
currentTransaction()
Obtain the transaction currently associated with this session, if any.Stage.Session
detach(Object entity)
Remove this instance from the session cache.Stage.Session
disableFetchProfile(String name)
Disable a particular fetch profile on this session, or do nothing if the requested fetch profile is not enabled.void
disableFilter(String filterName)
Disable the named filter for this session.Stage.Session
enableFetchProfile(String name)
Enable a particular fetch profile on this session, or do nothing if requested fetch profile is already enabled.Filter
enableFilter(String filterName)
Enable the named filter for this session.<E,T>
CompletionStage<T>fetch(E entity, jakarta.persistence.metamodel.Attribute<E,T> field)
Fetch a lazy property of the given entity, identified by a JPAattribute metamodel
.<T> CompletionStage<T>
fetch(T association)
Asynchronously fetch an association that's configured for lazy loading.<T> CompletionStage<T>
find(jakarta.persistence.EntityGraph<T> entityGraph, Object id)
Asynchronously return the persistent instance with the given identifier of an entity class, using the givenEntityGraph
as a fetch plan.<T> CompletionStage<T>
find(Class<T> entityClass, Object id)
Asynchronously return the persistent instance of the given entity class with the given identifier, ornull
if there is no such persistent instance.<T> CompletionStage<List<T>>
find(Class<T> entityClass, Object... ids)
Asynchronously return the persistent instances of the given entity class with the given identifiers, or null if there is no such persistent instance.default <T> CompletionStage<T>
find(Class<T> entityClass, Object id, jakarta.persistence.LockModeType lockModeType)
Asynchronously return the persistent instance of the given entity class with the given identifier, requesting the givenLockModeType
.<T> CompletionStage<T>
find(Class<T> entityClass, Object id, LockMode lockMode)
Asynchronously return the persistent instance of the given entity class with the given identifier, requesting the givenLockMode
.<T> CompletionStage<T>
find(Class<T> entityClass, Identifier<T> naturalId)
Asynchronously return the persistent instance of the given entity class with the given natural identifiers, or null if there is no such persistent instance.CompletionStage<Void>
flush()
Force this session to flush asynchronously.Integer
getBatchSize()
The session-level batch size, ornull
if it has not been overridden.CacheMode
getCacheMode()
Get the current cache mode.Filter
getEnabledFilter(String filterName)
Retrieve a currently enabled filter by name.<T> jakarta.persistence.EntityGraph<T>
getEntityGraph(Class<T> rootType, String graphName)
Obtain a namedEntityGraph
Stage.SessionFactory
getFactory()
TheStage.SessionFactory
which created this session.int
getFetchBatchSize()
Get the maximum batch size for batch fetching associations by id in this session.FlushMode
getFlushMode()
Get the current flush mode for this session.LockMode
getLockMode(Object entity)
Determine the current lock mode of the given entity.<T> T
getReference(Class<T> entityClass, Object id)
Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists.<T> T
getReference(T entity)
Return the persistent instance with the same identity as the given instance, which might be detached, assuming that the instance is still persistent in the database.<T> ResultSetMapping<T>
getResultSetMapping(Class<T> resultType, String mappingName)
Obtain a native SQL result set mapping defined via the annotationSqlResultSetMapping
.boolean
isDefaultReadOnly()
boolean
isFetchProfileEnabled(String name)
Determine if the fetch profile with the given name is enabled for this session.boolean
isOpen()
boolean
isReadOnly(Object entityOrProxy)
Is the specified entity or proxy read-only?boolean
isSubselectFetchingEnabled()
Determine if subselect fetching is enabled in this session.default CompletionStage<Void>
lock(Object entity, jakarta.persistence.LockModeType lockModeType)
Obtain the specified lock level upon the given object.CompletionStage<Void>
lock(Object entity, LockMode lockMode)
Obtain the specified lock level upon the given object.CompletionStage<Void>
merge(Object... entities)
Merge multiple entity instances at once.<T> CompletionStage<T>
merge(T entity)
Copy the state of the given object onto the persistent instance with the same identifier.CompletionStage<Void>
persist(Object entity)
Asynchronously persist the given transient instance, first assigning a generated identifier.CompletionStage<Void>
persist(Object... entities)
Persist multiple transient entity instances at once.CompletionStage<Void>
refresh(Object entity)
Re-read the state of the given instance from the underlying database.CompletionStage<Void>
refresh(Object... entities)
Refresh multiple entity instances at once.default CompletionStage<Void>
refresh(Object entity, jakarta.persistence.LockModeType lockModeType)
Re-read the state of the given instance from the underlying database, requesting the givenLockModeType
.CompletionStage<Void>
refresh(Object entity, LockMode lockMode)
Re-read the state of the given instance from the underlying database, requesting the givenLockMode
.CompletionStage<Void>
remove(Object entity)
Asynchronously remove a persistent instance from the datastore.CompletionStage<Void>
remove(Object... entities)
Remove multiple entity instances at once.Stage.Session
setBatchSize(Integer batchSize)
Set the session-level batch size, overriding the batch size set by the configuration propertyhibernate.jdbc.batch_size
.Stage.Session
setCacheMode(CacheMode cacheMode)
Set thecache mode
for this session.default Stage.Session
setCacheRetrieveMode(jakarta.persistence.CacheRetrieveMode cacheRetrieveMode)
Set theCacheRetrieveMode
for this session.default Stage.Session
setCacheStoreMode(jakarta.persistence.CacheStoreMode cacheStoreMode)
Set theCacheStoreMode
for this session.Stage.Session
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.Stage.Session
setFetchBatchSize(int batchSize)
Set the maximum batch size for batch fetching associations by id in this session.default Stage.Session
setFlushMode(jakarta.persistence.FlushModeType flushModeType)
Set theflush mode
for this session.Stage.Session
setFlushMode(FlushMode flushMode)
Set theflush mode
for this session.Stage.Session
setReadOnly(Object entityOrProxy, boolean readOnly)
Set an unmodified persistent object to read-only mode, or a read-only object to modifiable mode.Stage.Session
setSubselectFetchingEnabled(boolean enabled)
Enable or disable subselect fetching in this session.<T> CompletionStage<T>
unproxy(T association)
Asynchronously fetch an association that's configured for lazy loading, and unwrap the underlying entity implementation from any proxy.<T> CompletionStage<T>
withTransaction(Function<Stage.Transaction,CompletionStage<T>> work)
Performs the given work within the scope of a database transaction, automatically flushing the session.-
Methods inherited from interface org.hibernate.reactive.stage.Stage.Closeable
close
-
-
-
-
Method Detail
-
find
<T> CompletionStage<T> find(Class<T> entityClass, Object id)
Asynchronously return the persistent instance of the given entity class with the given identifier, ornull
if there is no such persistent instance. If the instance is already associated with the session, return the associated instance. This method never returns an uninitialized instance.session.find(Book.class, id).thenAccept(book -> print(book.getTitle()));
- Parameters:
entityClass
- The entity typeid
- an identifier- Returns:
- a persistent instance or null via a
CompletionStage
- See Also:
EntityManager.find(Class, Object)
-
find
<T> CompletionStage<T> find(Class<T> entityClass, Object id, LockMode lockMode)
Asynchronously return the persistent instance of the given entity class with the given identifier, requesting the givenLockMode
.- Parameters:
entityClass
- The entity typeid
- an identifierlockMode
- the requestedLockMode
- Returns:
- a persistent instance or null via a
CompletionStage
- See Also:
find(Class,Object)
,this discussion of lock modes
-
find
default <T> CompletionStage<T> find(Class<T> entityClass, Object id, jakarta.persistence.LockModeType lockModeType)
Asynchronously return the persistent instance of the given entity class with the given identifier, requesting the givenLockModeType
.- Parameters:
entityClass
- The entity typeid
- an identifierlockModeType
- the requestedLockModeType
- Returns:
- a persistent instance or null via a
CompletionStage
- See Also:
find(Class,Object)
,this discussion of lock modes
-
find
<T> CompletionStage<T> find(jakarta.persistence.EntityGraph<T> entityGraph, Object id)
Asynchronously return the persistent instance with the given identifier of an entity class, using the givenEntityGraph
as a fetch plan.- Parameters:
entityGraph
- anEntityGraph
specifying the entity and associations to be fetchedid
- an identifier- See Also:
find(Class,Object)
-
find
<T> CompletionStage<List<T>> find(Class<T> entityClass, Object... ids)
Asynchronously return the persistent instances of the given entity class with the given identifiers, or null if there is no such persistent instance.- Parameters:
entityClass
- The entity typeids
- the identifiers- Returns:
- a list of persistent instances and nulls via a
CompletionStage
-
find
@Incubating <T> CompletionStage<T> find(Class<T> entityClass, Identifier<T> naturalId)
Asynchronously return the persistent instance of the given entity class with the given natural identifiers, or null if there is no such persistent instance.- Parameters:
entityClass
- The entity typenaturalId
- the natural identifier- Returns:
- a persistent instance or null via a
CompletionStage
-
getReference
<T> T getReference(Class<T> entityClass, Object id)
Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists. This method never results in access to the underlying data store, and thus might return a proxy that must be initialized explicitly usingfetch(Object)
.You should not use this method to determine if an instance exists (use
find(java.lang.Class<T>, java.lang.Object)
instead). Use this only to retrieve an instance which you safely assume exists, where non-existence would be an actual error.- Parameters:
entityClass
- a persistent classid
- a valid identifier of an existing persistent instance of the class- Returns:
- the persistent instance or proxy
- See Also:
EntityManager.getReference(Class, Object)
-
getReference
<T> T getReference(T entity)
Return the persistent instance with the same identity as the given instance, which might be detached, assuming that the instance is still persistent in the database. This method never results in access to the underlying data store, and thus might return a proxy that must be initialized explicitly usingfetch(Object)
.- Parameters:
entity
- a detached persistent instance- Returns:
- the persistent instance or proxy
-
persist
CompletionStage<Void> persist(Object entity)
Asynchronously persist the given transient instance, first assigning a generated identifier. (Or using the current value of the identifier property if the entity has assigned identifiers.)This operation cascades to associated instances if the association is mapped with
CascadeType.PERSIST
.session.persist(newBook).thenAccept(v -> session.flush());
- Parameters:
entity
- a transient instance of a persistent class- See Also:
EntityManager.persist(Object)
-
persist
CompletionStage<Void> persist(Object... entities)
Persist multiple transient entity instances at once.- See Also:
persist(Object)
-
remove
CompletionStage<Void> remove(Object entity)
Asynchronously remove a persistent instance from the datastore. The argument may be an instance associated with the receiving session or a transient instance with an identifier associated with existing persistent state.This operation cascades to associated instances if the association is mapped with
CascadeType.REMOVE
.session.delete(book).thenAccept(v -> session.flush());
- Parameters:
entity
- the managed persistent instance to be removed- Throws:
IllegalArgumentException
- if the given instance is not managed- See Also:
EntityManager.remove(Object)
-
remove
CompletionStage<Void> remove(Object... entities)
Remove multiple entity instances at once.- See Also:
remove(Object)
-
merge
<T> CompletionStage<T> merge(T entity)
Copy the state of the given object onto the persistent instance with the same identifier. If there is no such persistent instance currently associated with the session, it will be loaded. Return the persistent instance. Or, if the given instance is transient, save a copy of it and return the copy 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
CascadeType.MERGE
.- Parameters:
entity
- a detached instance with state to be copied- Returns:
- an updated persistent instance
- See Also:
EntityManager.merge(Object)
-
merge
CompletionStage<Void> merge(Object... entities)
Merge multiple entity instances at once.- See Also:
merge(Object)
-
refresh
CompletionStage<Void> refresh(Object entity)
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:- where a database trigger alters the object state after insert or update, or
- after executing direct native SQL in the same session.
- Parameters:
entity
- a managed persistent instance- Throws:
IllegalArgumentException
- if the given instance is not managed- See Also:
EntityManager.refresh(Object)
-
refresh
CompletionStage<Void> refresh(Object entity, LockMode lockMode)
Re-read the state of the given instance from the underlying database, requesting the givenLockMode
.- Parameters:
entity
- a managed persistent entity instancelockMode
- the requested lock mode- See Also:
refresh(Object)
-
refresh
default CompletionStage<Void> refresh(Object entity, jakarta.persistence.LockModeType lockModeType)
Re-read the state of the given instance from the underlying database, requesting the givenLockModeType
.- Parameters:
entity
- a managed persistent entity instancelockModeType
- the requested lock mode- See Also:
refresh(Object)
-
refresh
CompletionStage<Void> refresh(Object... entities)
Refresh multiple entity instances at once.- See Also:
refresh(Object)
-
lock
CompletionStage<Void> lock(Object entity, LockMode lockMode)
Obtain the specified lock level upon the given object. For example, this operation may be used to:- perform a version check with
LockMode.PESSIMISTIC_READ
, - upgrade to a pessimistic lock with
LockMode.PESSIMISTIC_WRITE
, - force a version increment with
LockMode.PESSIMISTIC_FORCE_INCREMENT
, - schedule a version check just before the end of the transaction with
LockMode.OPTIMISTIC
, or - schedule a version increment just before the end of the transaction
with
LockMode.OPTIMISTIC_FORCE_INCREMENT
.
CascadeType.LOCK
.- Parameters:
entity
- a managed persistent instancelockMode
- the lock level- Throws:
IllegalArgumentException
- if the given instance is not managed
- perform a version check with
-
lock
default CompletionStage<Void> lock(Object entity, jakarta.persistence.LockModeType lockModeType)
Obtain the specified lock level upon the given object. For example, this operation may be used to:- perform a version check with
LockModeType.PESSIMISTIC_READ
, - upgrade to a pessimistic lock with
LockModeType.PESSIMISTIC_WRITE
, - force a version increment with
LockModeType.PESSIMISTIC_FORCE_INCREMENT
, - schedule a version check just before the end of the transaction with
LockModeType.OPTIMISTIC
, or - schedule a version increment just before the end of the transaction
with
LockModeType.OPTIMISTIC_FORCE_INCREMENT
.
CascadeType.LOCK
.- Parameters:
entity
- a managed persistent instancelockModeType
- the lock level- Throws:
IllegalArgumentException
- if the given instance is not managed
- perform a version check with
-
flush
CompletionStage<Void> flush()
Force this session to flush asynchronously. Must be called at the end of a unit of work, before committing the transaction and closing the session. Flushing is the process of synchronizing the underlying persistent store with state held in memory.session.flush().thenAccept(v -> print("done saving changes"));
- See Also:
EntityManager.flush()
-
fetch
<T> CompletionStage<T> fetch(T association)
Asynchronously fetch an association that's configured for lazy loading.session.fetch(author.getBook()).thenAccept(book -> print(book.getTitle()))
It can also initialize proxys. For example:
session.fetch(session.getReference(Author.class, authorId))
- Parameters:
association
- a lazy-loaded association, or a proxy- Returns:
- the fetched association, via a
CompletionStage
- See Also:
Stage.fetch(Object)
,getReference(Class, Object)
,Hibernate.initialize(Object)
-
fetch
<E,T> CompletionStage<T> fetch(E entity, jakarta.persistence.metamodel.Attribute<E,T> field)
Fetch a lazy property of the given entity, identified by a JPAattribute metamodel
. Note that this feature is only supported in conjunction with the Hibernate bytecode enhancer.session.fetch(book, Book_.isbn).thenAccept(isbn -> print(isbn))
-
unproxy
<T> CompletionStage<T> unproxy(T association)
Asynchronously fetch an association that's configured for lazy loading, and unwrap the underlying entity implementation from any proxy.session.unproxy(author.getBook()).thenAccept(book -> print(book.getTitle()));
- Parameters:
association
- a lazy-loaded association- Returns:
- the fetched association, via a
CompletionStage
- See Also:
Hibernate.unproxy(Object)
-
getLockMode
LockMode getLockMode(Object entity)
Determine the current lock mode of the given entity.
-
contains
boolean contains(Object entity)
Determine if the given instance belongs to this persistence context.
-
createSelectionQuery
<R> Stage.SelectionQuery<R> createSelectionQuery(String queryString, Class<R> resultType)
Create an instance ofStage.SelectionQuery
for the given HQL/JPQL query string.- Parameters:
queryString
- The HQL/JPQL query- Returns:
- The
Stage.SelectionQuery
instance for manipulation and execution - See Also:
EntityManager.createQuery(String, Class)
-
createMutationQuery
Stage.MutationQuery createMutationQuery(String queryString)
Create an instance ofStage.MutationQuery
for the given HQL/JPQL update or delete statement.- Parameters:
queryString
- The HQL/JPQL query, update or delete statement- Returns:
- The
Stage.MutationQuery
instance for manipulation and execution - See Also:
EntityManager.createQuery(String)
-
createQuery
@Deprecated <R> Stage.Query<R> createQuery(String queryString)
Deprecated.See explanation inQueryProducer.createSelectionQuery(String)
Create an instance ofStage.Query
for the given HQL/JPQL query string or HQL/JPQL update or delete statement. In the case of an update or delete, the returnedStage.Query
must be executed usingStage.MutationQuery.executeUpdate()
which returns an affected row count.- Parameters:
queryString
- The HQL/JPQL query, update or delete statement- Returns:
- The
Stage.Query
instance for manipulation and execution - See Also:
EntityManager.createQuery(String)
-
createQuery
<R> Stage.SelectionQuery<R> createQuery(String queryString, Class<R> resultType)
Create an instance ofStage.SelectionQuery
for the given HQL/JPQL query string and query result type.- Parameters:
queryString
- The HQL/JPQL queryresultType
- the Java type returned in each row of query results- Returns:
- The
Stage.Query
instance for manipulation and execution - See Also:
EntityManager.createQuery(String, Class)
-
createQuery
<R> Stage.MutationQuery createQuery(jakarta.persistence.criteria.CriteriaUpdate<R> criteriaUpdate)
Create an instance ofStage.MutationQuery
for the given criteria update.- Parameters:
criteriaUpdate
- TheCriteriaUpdate
- Returns:
- The
Stage.MutationQuery
instance for manipulation and execution
-
createQuery
<R> Stage.MutationQuery createQuery(jakarta.persistence.criteria.CriteriaDelete<R> criteriaDelete)
Create an instance ofStage.MutationQuery
for the given criteria delete.- Parameters:
criteriaDelete
- TheCriteriaDelete
- Returns:
- The
Stage.MutationQuery
instance for manipulation and execution
-
createNamedQuery
<R> Stage.Query<R> createNamedQuery(String queryName)
Create an instance ofStage.Query
for the named query.- Parameters:
queryName
- The name of the query- Returns:
- The
Stage.Query
instance for manipulation and execution - See Also:
EntityManager.createQuery(String)
-
createNamedQuery
<R> Stage.SelectionQuery<R> createNamedQuery(String queryName, Class<R> resultType)
Create an instance ofStage.SelectionQuery
for the named query.- Parameters:
queryName
- The name of the queryresultType
- the Java type returned in each row of query results- Returns:
- The
Stage.SelectionQuery
instance for manipulation and execution - See Also:
EntityManager.createQuery(String, Class)
-
createNativeQuery
<R> Stage.SelectionQuery<R> createNativeQuery(String queryString, Class<R> resultType)
Create an instance ofStage.Query
for the given SQL query string, using the givenresultType
to interpret the results.- If the given result type is
Object
, or a built-in type such asString
orInteger
, the result set must have a single column, which will be returned as a scalar. - If the given result type is
Object[]
, then the result set must have multiple columns, which will be returned as elements of arrays of typeObject[]
. - Otherwise, the given result type must be an entity class, in which case the result set column aliases must map to the fields of the entity, and the query will return instances of the entity.
- Parameters:
queryString
- The SQL queryresultType
- the Java type returned in each row of query results- Returns:
- The
Stage.SelectionQuery
instance for manipulation and execution - See Also:
EntityManager.createNativeQuery(String, Class)
- If the given result type is
-
createNativeQuery
<R> Stage.SelectionQuery<R> createNativeQuery(String queryString, Class<R> resultType, AffectedEntities affectedEntities)
Create an instance ofStage.SelectionQuery
for the given SQL query string, using the givenresultType
to interpret the results.- If the given result type is
Object
, or a built-in type such asString
orInteger
, the result set must have a single column, which will be returned as a scalar. - If the given result type is
Object[]
, then the result set must have multiple columns, which will be returned as elements of arrays of typeObject[]
. - Otherwise, the given result type must be an entity class, in which case the result set column aliases must map to the fields of the entity, and the query will return instances of the entity.
affected entities
are synchronized with the database before execution of the query.- Parameters:
queryString
- The SQL queryresultType
- the Java type returned in each row of query resultsaffectedEntities
- The entities which are affected by the query- Returns:
- The
Stage.Query
instance for manipulation and execution - See Also:
EntityManager.createNativeQuery(String, Class)
- If the given result type is
-
createNativeQuery
<R> Stage.SelectionQuery<R> createNativeQuery(String queryString, ResultSetMapping<R> resultSetMapping)
Create an instance ofStage.SelectionQuery
for the given SQL query string, using the givenResultSetMapping
to interpret the result set.- Parameters:
queryString
- The SQL queryresultSetMapping
- the result set mapping- Returns:
- The
Stage.Query
instance for manipulation and execution - See Also:
getResultSetMapping(Class, String)
,EntityManager.createNativeQuery(String, String)
-
createNativeQuery
<R> Stage.SelectionQuery<R> createNativeQuery(String queryString, ResultSetMapping<R> resultSetMapping, AffectedEntities affectedEntities)
Create an instance ofStage.SelectionQuery
for the given SQL query string, using the givenResultSetMapping
to interpret the result set.Any
affected entities
are synchronized with the database before execution of the query.- Parameters:
queryString
- The SQL queryresultSetMapping
- the result set mappingaffectedEntities
- The entities which are affected by the query- Returns:
- The
Stage.Query
instance for manipulation and execution - See Also:
getResultSetMapping(Class, String)
,EntityManager.createNativeQuery(String, String)
-
createNativeQuery
<R> Stage.Query<R> createNativeQuery(String queryString)
Create an instance ofStage.Query
for the given SQL query string, or SQL update, insert, or delete statement. In the case of an update, insert, or delete, the returnedStage.Query
must be executed usingStage.MutationQuery.executeUpdate()
which returns an affected row count. In the case of a query:- If the result set has a single column, the results will be returned as scalars.
- Otherwise, if the result set has multiple columns, the results will
be returned as elements of arrays of type
Object[]
.
- Parameters:
queryString
- The SQL select, update, insert, or delete statement
-
createNativeQuery
<R> Stage.Query<R> createNativeQuery(String queryString, AffectedEntities affectedEntities)
Create an instance ofStage.Query
for the given SQL query string, or SQL update, insert, or delete statement. In the case of an update, insert, or delete, the returnedStage.Query
must be executed usingStage.MutationQuery.executeUpdate()
which returns an affected row count. In the case of a query:- If the result set has a single column, the results will be returned as scalars.
- Otherwise, if the result set has multiple columns, the results will
be returned as elements of arrays of type
Object[]
.
affected entities
are synchronized with the database before execution of the statement.- Parameters:
queryString
- The SQL select, update, insert, or delete statementaffectedEntities
- The entities which are affected by the statement
-
createQuery
<R> Stage.SelectionQuery<R> createQuery(jakarta.persistence.criteria.CriteriaQuery<R> criteriaQuery)
Create an instance ofStage.SelectionQuery
for the given criteria query.- Parameters:
criteriaQuery
- TheCriteriaQuery
- Returns:
- The
Stage.SelectionQuery
instance for manipulation and execution - See Also:
EntityManager.createQuery(String)
-
setFlushMode
Stage.Session setFlushMode(FlushMode flushMode)
Set theflush mode
for this session.The flush mode determines the points at which the session is flushed. Flushing is the process of synchronizing the underlying persistent store with persistable state held in memory.
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).- Parameters:
flushMode
- the new flush mode
-
setFlushMode
default Stage.Session setFlushMode(jakarta.persistence.FlushModeType flushModeType)
Set theflush mode
for this session.The flush mode determines the points at which the session is flushed. Flushing is the process of synchronizing the underlying persistent store with persistable state held in memory.
- Parameters:
flushModeType
- the new flush mode
-
getFlushMode
FlushMode getFlushMode()
Get the current flush mode for this session.- Returns:
- the flush mode
-
detach
Stage.Session detach(Object entity)
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
CascadeType.DETACH
.- Parameters:
entity
- The entity to evict- Throws:
NullPointerException
- if the passed object isnull
IllegalArgumentException
- if the passed object is not defined as an entity- See Also:
EntityManager.detach(Object)
-
clear
Stage.Session clear()
Completely clear the session. Detach all persistent instances and cancel all pending insertions, updates and deletions.- See Also:
EntityManager.clear()
-
enableFetchProfile
Stage.Session enableFetchProfile(String name)
Enable a particular fetch profile on this session, or do nothing if requested fetch profile is already enabled.- Parameters:
name
- The name of the fetch profile to be enabled.- Throws:
UnknownProfileException
- Indicates that the given name does not match any known profile names- See Also:
for discussion of this feature
-
getResultSetMapping
<T> ResultSetMapping<T> getResultSetMapping(Class<T> resultType, String mappingName)
Obtain a native SQL result set mapping defined via the annotationSqlResultSetMapping
.
-
getEntityGraph
<T> jakarta.persistence.EntityGraph<T> getEntityGraph(Class<T> rootType, String graphName)
Obtain a namedEntityGraph
-
createEntityGraph
<T> jakarta.persistence.EntityGraph<T> createEntityGraph(Class<T> rootType)
Create a new mutableEntityGraph
-
createEntityGraph
<T> jakarta.persistence.EntityGraph<T> createEntityGraph(Class<T> rootType, String graphName)
Create a new mutable copy of a namedEntityGraph
-
disableFetchProfile
Stage.Session disableFetchProfile(String name)
Disable a particular fetch profile on this session, or do nothing if the requested fetch profile is not enabled.- Parameters:
name
- The name of the fetch profile to be disabled.- Throws:
UnknownProfileException
- Indicates that the given name does not match any known profile names- See Also:
for discussion of this feature
-
isFetchProfileEnabled
boolean isFetchProfileEnabled(String name)
Determine if the fetch profile with the given name is enabled for this session.- Parameters:
name
- The name of the profile to be checked.- Returns:
- True if fetch profile is enabled; false if not.
- Throws:
UnknownProfileException
- Indicates that the given name does not match any known profile names- See Also:
for discussion of this feature
-
setDefaultReadOnly
Stage.Session 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.
- See Also:
Session.setDefaultReadOnly(boolean)
-
isDefaultReadOnly
boolean isDefaultReadOnly()
- Returns:
- the default read-only mode for entities and proxies loaded in this session
-
setReadOnly
Stage.Session 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.- See Also:
Session.setReadOnly(Object, boolean)
-
isReadOnly
boolean isReadOnly(Object entityOrProxy)
Is the specified entity or proxy read-only?- See Also:
Session.isReadOnly(Object)
-
setCacheMode
Stage.Session setCacheMode(CacheMode cacheMode)
Set thecache mode
for this session.The cache mode determines the manner in which this session interacts with the second level cache.
- Parameters:
cacheMode
- The new cache mode.
-
setCacheStoreMode
default Stage.Session setCacheStoreMode(jakarta.persistence.CacheStoreMode cacheStoreMode)
Set theCacheStoreMode
for this session.- Parameters:
cacheStoreMode
- The new cache store mode.
-
setCacheRetrieveMode
default Stage.Session setCacheRetrieveMode(jakarta.persistence.CacheRetrieveMode cacheRetrieveMode)
Set theCacheRetrieveMode
for this session.- Parameters:
cacheRetrieveMode
- The new cache retrieve mode.
-
getCacheMode
CacheMode getCacheMode()
Get the current cache mode.- Returns:
- The current cache mode.
-
setBatchSize
Stage.Session setBatchSize(Integer batchSize)
Set the session-level batch size, overriding the batch size set by the configuration propertyhibernate.jdbc.batch_size
.
-
getBatchSize
Integer getBatchSize()
The session-level batch size, ornull
if it has not been overridden.
-
getFetchBatchSize
int getFetchBatchSize()
Get the maximum batch size for batch fetching associations by id in this session.- Since:
- 2.1
-
setFetchBatchSize
Stage.Session setFetchBatchSize(int batchSize)
Set the maximum batch size for batch fetching associations by id in this session. Override the default controlled by the configuration propertyhibernate.default_batch_fetch_size
.- If
batchSize>1
, then batch fetching is enabled. - If
batchSize<0
, the batch size is inherited from the factory-level setting. - Otherwise, batch fetching is disabled.
- Parameters:
batchSize
- the maximum batch size for batch fetching- Since:
- 2.1
- If
-
isSubselectFetchingEnabled
boolean isSubselectFetchingEnabled()
Determine if subselect fetching is enabled in this session.- Returns:
true
if subselect fetching is enabled- Since:
- 2.1
-
setSubselectFetchingEnabled
Stage.Session setSubselectFetchingEnabled(boolean enabled)
Enable or disable subselect fetching in this session. Override the default controlled by the configuration propertyhibernate.use_subselect_fetch
.- Parameters:
enabled
-true
to enable subselect fetching- Since:
- 2.1
-
enableFilter
Filter enableFilter(String filterName)
Enable the named filter for this session.- Parameters:
filterName
- The name of the filter to be enabled.- Returns:
- The Filter instance representing the enabled filter.
-
disableFilter
void disableFilter(String filterName)
Disable the named filter for this session.- Parameters:
filterName
- The name of the filter to be disabled.
-
getEnabledFilter
Filter getEnabledFilter(String filterName)
Retrieve a currently enabled filter by name.- Parameters:
filterName
- The name of the filter to be retrieved.- Returns:
- The Filter instance representing the enabled filter.
-
withTransaction
<T> CompletionStage<T> withTransaction(Function<Stage.Transaction,CompletionStage<T>> work)
Performs the given work within the scope of a database transaction, automatically flushing the session. The transaction will be rolled back if the work completes with an uncaught exception, or ifStage.Transaction.markForRollback()
is called.The resulting
Stage.Transaction
object may also be obtained viacurrentTransaction()
.- If there is already a transaction associated with this session, the work is executed in the context of the existing transaction, and no new transaction is initiated.
- If there is no transaction associated with this session, a new transaction is started, and the work is executed in the context of the new transaction.
- Parameters:
work
- a function which acceptsStage.Transaction
and returns the result of the work as aCompletionStage
.- See Also:
Stage.SessionFactory.withTransaction(BiFunction)
-
currentTransaction
Stage.Transaction currentTransaction()
Obtain the transaction currently associated with this session, if any.- Returns:
- the
Stage.Transaction
, or null if no transaction was started usingwithTransaction(Function)
. - See Also:
withTransaction(Function)
,Stage.SessionFactory.withTransaction(BiFunction)
-
isOpen
boolean isOpen()
- Returns:
- false if
Stage.Closeable.close()
has been called
-
getFactory
Stage.SessionFactory getFactory()
TheStage.SessionFactory
which created this session.
-
-