Interface SharedSessionContract

All Superinterfaces:

AutoCloseable, EntityHandler, Serializable

All Known Subinterfaces:

EventSource, Session, SessionImplementor, SharedSessionContractImplementor, StatelessSession, StatelessSessionImplementor

All Known Implementing Classes:

SessionDelegatorBaseImpl, SessionLazyDelegator

public interface SharedSessionContract
extends EntityHandler, AutoCloseable, Serializable

Declares operations that are common between Session and StatelessSession.

Method Summary

Modifier and Type	Method	Description
Transaction	beginTransaction()	Begin a unit of work and return the associated Transaction object.
void	close()	End the session by releasing the JDBC connection and cleaning up.
<T> RootGraph<T>	createEntityGraph(Class<T> rootType)	Create a new mutable instance of EntityGraph, with only a root node, allowing programmatic definition of the graph from scratch.
<T> RootGraph<T>	createEntityGraph(Class<T> rootType, String graphName)	Deprecated, for removal: This API element is subject to removal in a future version. Use getEntityGraph(Class, String) instead.
RootGraph<?>	createEntityGraph(String graphName)	Deprecated, for removal: This API element is subject to removal in a future version. Use getEntityGraph(String) instead.
MutationQuery	createMutationQuery(CriteriaStatement<?> criteriaStatement)	Create a MutationQuery from the given update criteria tree
MutationQuery	createMutationQuery(String hqlString)	Create a MutationQuery reference for the given HQL insert, update, or delete statement.
MutationQuery	createMutationQuery(JpaCriteriaInsert<?> insert)	Create a MutationQuery from the given insert criteria tree
MutationQuery	createNamedMutationQuery(String name)	Create a MutationQuery instance for the given named insert, update, or delete HQL query.
MutationOrSelectionQuery	createNamedQuery(String name)	Create an instance of Query for the given named query or statement, without indicating the expected result type, if any, nor whether the query is a typed query which returns a result list, or an update, delete, or insert statement.
<R> SelectionQuery<R>	createNamedQuery(String name, Class<R> resultClass)	Create a typed Query instance for the given named query.
<R> NativeQuery<R>	createNamedQuery(String name, String resultSetMappingName)
<R> NativeQuery<R>	createNamedQuery(String name, String resultSetMappingName, Class<R> resultClass)
<R> SelectionQuery<R>	createNamedSelectionQuery(String name, Class<R> resultType)	Create a SelectionQuery instance for the named NamedQuery with the given result type.
MutationQuery	createNamedStatement(String name)
ProcedureCall	createNamedStoredProcedureQuery(String name)	Obtain a ProcedureCall based on a named template
MutationQuery	createNativeMutationQuery(String sqlString)	Create a NativeQuery instance for the given native SQL statement.
default <R> NativeQuery<R>	createNativeQuery(Class<R> resultClass, String queryString)	Synonym for createNativeQuery(String,Class), offering generally easier readability for use code.
NativeQuery<?>	createNativeQuery(String sqlString)	Create a NativeQuery instance for the given native SQL query.
<T> TypedQuery<T>	createNativeQuery(String sql, jakarta.persistence.sql.ResultSetMapping<T> resultSetMapping)
<R> NativeQuery<R>	createNativeQuery(String sqlString, Class<R> resultClass)	Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java type.
<R> NativeQuery<R>	createNativeQuery(String sqlString, Class<R> resultClass, String tableAlias)	Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java entity type.
NativeQuery<?>	createNativeQuery(String sql, String resultSetMapping)
<R> NativeQuery<R>	createNativeQuery(String sqlString, String resultSetMappingName, Class<R> resultClass)	Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.
MutationQuery	createNativeStatement(String sql)
<T> SelectionQuery<T>	createQuery(CriteriaSelect<T> criteriaSelect)
<R> SelectionQuery<R>	createQuery(TypedQueryReference<R> typedQueryReference)	Create a typed Query instance for the given typed query reference.
default <R> SelectionQuery<R>	createQuery(Class<R> resultClass, String hqlString)	Synonym for createQuery(String,Class), offering generally easier readability for use code.
MutationOrSelectionQuery	createQuery(String queryString)	Create an instance of Query for the given HQL query or statement, without indicating the expected result type, if any, nor whether the query is a typed query which returns a result list, or an update, delete, or insert statement.
<T> SelectionQuery<T>	createQuery(String hqlString, EntityGraph<T> entityGraph)
<R> SelectionQuery<R>	createQuery(String queryString, Class<R> resultClass)	Create a typed Query instance for the given HQL query string and given query result type.
<R> SelectionQuery<R>	createSelectionQuery(CriteriaQuery<R> criteria)	Create a SelectionQuery reference for the given CriteriaQuery.
<R> SelectionQuery<R>	createSelectionQuery(CriteriaSelect<R> criteria)	Create a SelectionQuery reference for the given CriteriaQuery.
<R> SelectionQuery<R>	createSelectionQuery(String hqlString, EntityGraph<R> resultGraph)	Create a SelectionQuery instance for the given HQL query string and given EntityGraph, which is interpreted as a load graph.
<R> SelectionQuery<R>	createSelectionQuery(String hqlString, Class<R> resultType)	Create a SelectionQuery instance for the given HQL query string and given query result type.
MutationQuery	createStatement(CriteriaStatement<?> criteriaStatement)
MutationQuery	createStatement(StatementReference statementReference)
MutationQuery	createStatement(String hqlString)
ProcedureCall	createStoredProcedureCall(String procedureName)	Create a ProcedureCall to a stored procedure.
ProcedureCall	createStoredProcedureCall(String procedureName, Class<?>... resultClasses)	Create a ProcedureCall to a stored procedure with the given result set entity mappings.
ProcedureCall	createStoredProcedureCall(String procedureName, String... resultSetMappings)	Create a ProcedureCall to a stored procedure with the given result set entity mappings.
ProcedureCall	createStoredProcedureQuery(String procedureName)	Create a ProcedureCall to a stored procedure.
ProcedureCall	createStoredProcedureQuery(String procedureName, Class<?>... resultClasses)	Create a ProcedureCall to a stored procedure with the given result set entity mappings.
ProcedureCall	createStoredProcedureQuery(String procedureName, String... resultSetMappings)	Create a ProcedureCall to a stored procedure with the given result set entity mappings.
void	disableFilter(String filterName)	Disable the named filter for the current session.
<T> T	doReturningWork(ReturningWork<T> work)	Perform work using the Connection underlying by this session, and return a result.
void	doWork(Work work)	Perform work using the Connection underlying by this session.
Filter	enableFilter(String filterName)	Enable the named filter for this current session.
default Object	find(String entityName, Object id)	Corollary to EntityHandler.find(Class,Object) for dynamic models.
Object	find(String entityName, Object key, FindOption... findOptions)	Corollary to EntityHandler.find(Class,Object,FindOption...) for dynamic models.
default <R> R	fromTransaction(Function<? super Transaction, R> action)	Obtain a value within the bounds of a transaction associated with this session.
default Object	get(String entityName, Object id)	Form of find(String,Object) throwing EntityNotFoundException if no entity exists for that id rather than returning null.
Object	get(String entityName, Object key, FindOption... findOptions)	Form of find(String,Object,FindOption...) throwing EntityNotFoundException if no entity exists for that id rather than returning null.
CacheMode	getCacheMode()	Get the current cache mode for this session.
HibernateCriteriaBuilder	getCriteriaBuilder()	Obtain a HibernateCriteriaBuilder which may be used to construct criteria queries.
Filter	getEnabledFilter(String filterName)	Retrieve a currently enabled filter by name.
<T> RootGraph<T>	getEntityGraph(Class<T> rootType, String graphName)	Obtain a mutable copy of a predefined named entity graph whose root type is exactly the given entity type.
RootGraph<?>	getEntityGraph(String graphName)	Obtain a mutable copy of a predefined named entity graph.
<T> List<EntityGraph<? super T>>	getEntityGraphs(Class<T> entityClass)	Retrieve all named EntityGraphs with the given root entity type.
SessionFactory	getFactory()	The factory which created this session.
Integer	getJdbcBatchSize()	Get the session-level JDBC batch size for the current session.
ProcedureCall	getNamedProcedureCall(String name)	Obtain a ProcedureCall based on a named template
String	getTenantIdentifier()	Obtain the tenant identifier associated with this session, as a string.
Object	getTenantIdentifierValue()	Obtain the tenant identifier associated with this session.
Transaction	getTransaction()	Get the Transaction instance associated with this session.
default void	inTransaction(Consumer<? super Transaction> action)	Perform an action within the bounds of a transaction associated with this session.
boolean	isConnected()	Check if the session is currently connected.
boolean	isJoinedToTransaction()	Check if the session is joined to the current transaction.
boolean	isOpen()	Check if the session is still open.
void	joinTransaction()	Join the currently active JTA transaction.
SharedSessionBuilder	sessionWithOptions()	Obtain a Session builder with the ability to copy certain information from this session.
void	setCacheMode(CacheMode cacheMode)	Set the current cache mode for this session.
void	setJdbcBatchSize(Integer jdbcBatchSize)	Set the session-level JDBC batch size.
SharedStatelessSessionBuilder	statelessWithOptions()	Obtain a StatelessSession builder with the ability to copy certain information from this session.

Methods inherited from interface EntityHandler

callWithConnection, find, find, find, findMultiple, findMultiple, get, get, get, getCacheRetrieveMode, getCacheStoreMode, getEntityManagerFactory, getMetamodel, getMultiple, getMultiple, getProperties, runWithConnection, setCacheRetrieveMode, setCacheStoreMode, setProperty, unwrap

Method Details

getTenantIdentifier

@Nullable
String getTenantIdentifier()

Obtain the tenant identifier associated with this session, as a string.

Returns:

The tenant identifier associated with this session, or null

See Also:

• CurrentTenantIdentifierResolver
• SessionBuilder.tenantIdentifier(Object)
• SessionCreationOption.TenantId

getTenantIdentifierValue

@Nullable
Object getTenantIdentifierValue()

Obtain the tenant identifier associated with this session.

Returns:

The tenant identifier associated with this session, or null

Since:

6.4

See Also:

• CurrentTenantIdentifierResolver
• SessionBuilder.tenantIdentifier(Object)
• SessionCreationOption.TenantId

getCacheMode

@Nonnull
CacheMode getCacheMode()

Get the current cache mode for this session.

Returns:

the current cache mode

setCacheMode

void setCacheMode(@Nonnull
 CacheMode cacheMode)

Set the current cache mode for this session.

The cache mode determines the manner in which this session can interact with the second-level cache.

Parameters:

cacheMode - the new cache mode

close

void close()
    throws HibernateException

End the session by releasing the JDBC connection and cleaning up.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface EntityHandler

Throws:

HibernateException - Indicates problems cleaning up.

isOpen

boolean isOpen()

Check if the session is still open.

Specified by:

isOpen in interface EntityHandler

Returns:

true if it is open

isConnected

boolean isConnected()

Check if the session is currently connected.

Returns:

true if it is connected

beginTransaction

@Nonnull
Transaction beginTransaction()

Begin a unit of work and return the associated Transaction object. If a new underlying transaction is required, begin the transaction. Otherwise, continue the new work in the context of the existing underlying transaction.

Returns:

an instance of Transaction representing the new transaction

See Also:

• getTransaction()
• EntityTransaction.begin()

API Note:

The JPA-standard way to begin a new resource-local transaction is by calling getTransaction().begin(). But it's not always safe to execute this idiom.

• JPA doesn't allow an EntityTransaction to represent a JTA transaction context. Therefore, when strict JPA transaction compliance is enabled via, for example, setting "hibernate.jpa.compliance.transaction", the call to getTransaction() fails if transactions are managed by JTA.

  On the other hand, this method does not fail when JTA transaction management is used, not even if strict JPA transaction compliance is enabled.

• Even when resource-local transactions are in use, and even when strict JPA transaction compliance is disabled, the call to begin() fails if a transaction is already active.

  This method never fails when a transaction is already active. Instead, beginTransaction() simply returns the Transaction object representing the active transaction.

getTransaction

@Nonnull
Transaction getTransaction()

Get the Transaction instance associated with this session.

Specified by:

getTransaction in interface EntityHandler

Returns:

an instance of Transaction representing the transaction associated with this session

See Also:

• EntityHandler.getTransaction()

API Note:

This method is the JPA-standard way to obtain an instance of EntityTransaction representing a resource-local transaction. But JPA doesn't allow an EntityTransaction to represent a JTA transaction. Therefore, when strict JPA transaction compliance is enabled via, for example, setting "hibernate.jpa.compliance.transaction", this method fails if transactions are managed by JTA.

On the other hand, when JTA transaction management is used, and when strict JPA transaction compliance is disabled, this method happily returns a Transaction representing the current JTA transaction context.

joinTransaction

void joinTransaction()

Join the currently active JTA transaction.

Since:

6.2

See Also:

• EntityManager.joinTransaction()

isJoinedToTransaction

boolean isJoinedToTransaction()

Check if the session is joined to the current transaction.

Since:

6.2

See Also:

• joinTransaction()
• EntityManager.isJoinedToTransaction()

find

@Nullable
default Object find(@Nonnull
 String entityName,
 @Nonnull
 Object id)

Corollary to EntityHandler.find(Class,Object) for dynamic models.

Parameters:

entityName - The entity name

id - The identifier

Returns:

The persistent instance, or null

Throws:

IllegalArgumentException - If the given name does not match a mapped dynamic entity

See Also:

• SessionFactory.createGraphForDynamicEntity(String)
• EntityHandler.find(EntityGraph, Object, FindOption...)

find

@Nullable
Object find(@Nonnull
 String entityName,
 @Nonnull
 Object key,
 @Nullable
 FindOption... findOptions)

Corollary to EntityHandler.find(Class,Object,FindOption...) for dynamic models.

Parameters:

entityName - The entity name

key - The key (primary or natural, based on KeyType)

findOptions - Options for the load operation.

Returns:

The persistent instance, or null

Throws:

IllegalArgumentException - If the given name does not match a mapped dynamic entity

See Also:

• SessionFactory.createGraphForDynamicEntity(String)
• EntityHandler.find(EntityGraph,Object,FindOption...)

get

@Nonnull
default Object get(@Nonnull
 String entityName,
 @Nonnull
 Object id)

Form of find(String,Object) throwing EntityNotFoundException if no entity exists for that id rather than returning null.

Parameters:

entityName - The entity name

id - The identifier

Returns:

The persistent instance

Throws:

IllegalArgumentException - If the given name does not match a mapped dynamic entity

EntityNotFoundException - if no entity was found for the given id

See Also:

• SessionFactory.createGraphForDynamicEntity(String)
• EntityHandler.get(EntityGraph, Object, FindOption...)

get

@Nonnull
Object get(@Nonnull
 String entityName,
 @Nonnull
 Object key,
 @Nullable
 FindOption... findOptions)

Form of find(String,Object,FindOption...) throwing EntityNotFoundException if no entity exists for that id rather than returning null.

Parameters:

entityName - The entity name

key - The key (primary or natural, based on KeyType)

findOptions - Options for the load operation.

Returns:

a persistent instance

Throws:

IllegalArgumentException - If the given name does not match a mapped dynamic entity

EntityNotFoundException - if no entity was found for the given key

See Also:

• SessionFactory.createGraphForDynamicEntity(String)
• EntityHandler.get(EntityGraph,Object,FindOption...)

createQuery

@Nonnull
<R> SelectionQuery<R> createQuery(@Nonnull
 String queryString,
 @Nonnull
 Class<R> resultClass)

Create a typed Query instance for the given HQL query string and given query result type.

• If the query has a single item in the select list, then the select item must be assignable to the given result type.
• Otherwise, if there are multiple select items, then the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], List, Map, or Tuple.

If a query has no explicit select list, the select list is inferred from the given query result type:

• if the result type is an entity type, the query must have exactly one root entity in the from clause, it must be assignable to the result type, and the inferred select list will contain just that entity, or
• otherwise, the select list contains every root entity and every non-fetch joined entity, and each query result will be packaged into an instance of the result type, just as specified above.

If a query has no explicit from clause, and the given result type is an entity type, the root entity is inferred to be the result type.

Passing Object.class as the query result type is not recommended.

The returned Query may be executed by calling SelectionQuery.getResultList() or SelectionQuery.getSingleResult().

Specified by:

createQuery in interface EntityHandler

Parameters:

queryString - The HQL query

resultClass - The Class object representing the query result type, which should not be Object.class

Returns:

The Query instance for manipulation and execution

See Also:

• EntityHandler.createQuery(String,Class)

createQuery

@Nonnull
default <R> SelectionQuery<R> createQuery(@Nonnull
 Class<R> resultClass,
 @Nonnull
 String hqlString)

Synonym for createQuery(String,Class), offering generally easier readability for use code. For example

var peeps = session.createQuery(Person.class, "some really long query string" )
		...
		.list();

as opposed to

var peeps = session.createQuery("some really long query string", Person.class)
		...
		.list();

createQuery

@Nonnull
<T> SelectionQuery<T> createQuery(@Nonnull
 String hqlString,
 @Nonnull
 EntityGraph<T> entityGraph)

Specified by:

createQuery in interface EntityHandler

See Also:

• EntityHandler.createQuery(String,EntityGraph)

createSelectionQuery

<R> SelectionQuery<R> createSelectionQuery(String hqlString,
 Class<R> resultType)

Create a SelectionQuery instance for the given HQL query string and given query result type.

• If the query has a single item in the select list, then the select item must be assignable to the given result type.
• Otherwise, if there are multiple select items, then the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], List, Map, or Tuple.

If a query has no explicit select list, the select list is inferred from the given query result type:

• if the result type is an entity type, the query must have exactly one root entity in the from clause, it must be assignable to the result type, and the inferred select list will contain just that entity, or
• otherwise, the select list contains every root entity and every non-fetch joined entity, and each query result will be packaged into an instance of the result type, just as specified above.

If a query has no explicit from clause, and the given result type is an entity type, the root entity is inferred to be the result type.

Passing Object.class as the query result type is not recommended.

The returned Query may be executed by calling SelectionQuery.getResultList() or SelectionQuery.getSingleResult().

Parameters:

hqlString - The HQL select query as a string

resultType - The Class object representing the query result type, which should not be Object.class

Throws:

IllegalSelectQueryException - if the given HQL query is an insert, update or delete statement

See Also:

• EntityHandler.createQuery(String)

createSelectionQuery

<R> SelectionQuery<R> createSelectionQuery(String hqlString,
 EntityGraph<R> resultGraph)

Create a SelectionQuery instance for the given HQL query string and given EntityGraph, which is interpreted as a load graph. The query result type is the root entity of the given graph.

• If the query has an explicit select clause, there must be a single item in the select list, and the select item must be assignable to the root type of the given graph.
• Otherwise, if a query has no explicit select list, the select list is inferred from the given entity graph. The query must have exactly one root entity in the from clause, it must be assignable to the root type of the given graph, and the inferred select list will contain just that entity.

If a query has no explicit from clause, and the given result type is an entity type, the root entity is inferred to be the result type.

The returned Query may be executed by calling SelectionQuery.getResultList() or SelectionQuery.getSingleResult().

Parameters:

hqlString - The HQL select query as a string

resultGraph - An EntityGraph whose root type is the query result type, which is interpreted as a load graph

Throws:

IllegalSelectQueryException - if the given HQL query is an insert, update or delete statement

Since:

7.0

See Also:

• EntityHandler.createQuery(String)

createMutationQuery

MutationQuery createMutationQuery(String hqlString)

Create a MutationQuery reference for the given HQL insert, update, or delete statement.

Parameters:

hqlString - The HQL insert, update, or delete statement

Throws:

IllegalMutationQueryException - if the given HQL query is a select query

createStatement

@Nonnull
MutationQuery createStatement(@Nonnull
 String hqlString)

Specified by:

createStatement in interface EntityHandler

createStatement

@Nonnull
MutationQuery createStatement(@Nonnull
 StatementReference statementReference)

Specified by:

createStatement in interface EntityHandler

createQuery

@Nonnull
<R> SelectionQuery<R> createQuery(@Nonnull
 TypedQueryReference<R> typedQueryReference)

Create a typed Query instance for the given typed query reference.

Specified by:

createQuery in interface EntityHandler

Parameters:

typedQueryReference - the type query reference

Returns:

The Query instance for execution

Throws:

IllegalArgumentException - if a query has not been defined with the name of the typed query reference or if the query result is found to not be assignable to result class of the typed query reference

See Also:

• EntityHandler.createQuery(TypedQueryReference)

createQuery

@Nonnull
<T> SelectionQuery<T> createQuery(@Nonnull
 CriteriaSelect<T> criteriaSelect)

Specified by:

createQuery in interface EntityHandler

See Also:

• createSelectionQuery(CriteriaSelect)
• EntityHandler.createQuery(CriteriaSelect)

createStatement

@Nonnull
MutationQuery createStatement(@Nonnull
 CriteriaStatement<?> criteriaStatement)

Specified by:

createStatement in interface EntityHandler

See Also:

• createMutationQuery(CriteriaStatement)
• EntityHandler.createStatement(CriteriaStatement)

createSelectionQuery

@Nonnull
<R> SelectionQuery<R> createSelectionQuery(@Nonnull
 CriteriaSelect<R> criteria)

Create a SelectionQuery reference for the given CriteriaQuery.

See Also:

• EntityHandler.createQuery(CriteriaSelect)

createSelectionQuery

@Nonnull
<R> SelectionQuery<R> createSelectionQuery(@Nonnull
 CriteriaQuery<R> criteria)

Create a SelectionQuery reference for the given CriteriaQuery.

See Also:

• EntityHandler.createQuery(CriteriaSelect)

createMutationQuery

@Nonnull
MutationQuery createMutationQuery(@Nonnull
 CriteriaStatement<?> criteriaStatement)

Create a MutationQuery from the given update criteria tree

createMutationQuery

@Nonnull
MutationQuery createMutationQuery(@Nonnull
 JpaCriteriaInsert<?> insert)

Create a MutationQuery from the given insert criteria tree

createNativeQuery

@Nonnull
NativeQuery<?> createNativeQuery(@Nonnull
 String sqlString)

Create a NativeQuery instance for the given native SQL query.

Specified by:

createNativeQuery in interface EntityHandler

Parameters:

sqlString - The native (SQL) query string

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityHandler.createNativeQuery(String)

createNativeQuery

@Nonnull
<R> NativeQuery<R> createNativeQuery(@Nonnull
 String sqlString,
 @Nonnull
 Class<R> resultClass)

Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java type.

• If the given class is an entity class, this method is equivalent to createNativeQuery(sqlString).addEntity(resultClass).
• If the given class has a registered JavaType, then the query must return a result set with a single column whose JdbcType is compatible with that JavaType.
• Otherwise, the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], List, Map, or Tuple.

Specified by:

createNativeQuery in interface EntityHandler

Parameters:

sqlString - The native (SQL) query string

resultClass - The Java type to map results to

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityHandler.createNativeQuery(String,Class)

createNativeQuery

default <R> NativeQuery<R> createNativeQuery(Class<R> resultClass,
 String queryString)

Synonym for createNativeQuery(String,Class), offering generally easier readability for use code. For example

var peeps = session.createNativeQuery(Person.class, "some really long query string" )
		...
		.list();

as opposed to

var peeps = session.createNativeQuery("some really long query string", Person.class)
		...
		.list();

createNativeQuery

<R> NativeQuery<R> createNativeQuery(String sqlString,
 Class<R> resultClass,
 String tableAlias)

Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java entity type.

The given class must be an entity class. This method is equivalent to createNativeQuery(sqlString).addEntity(tableAlias, resultClass).

Parameters:

sqlString - Native (SQL) query string

resultClass - The Java entity class to map results to

tableAlias - The table alias for columns in the result set

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityHandler.createNativeQuery(String,Class)

createNativeQuery

<R> NativeQuery<R> createNativeQuery(String sqlString,
 String resultSetMappingName,
 Class<R> resultClass)

Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.

The given result set mapping name must identify a mapping defined by a SqlResultSetMapping annotation.

Parameters:

sqlString - The native (SQL) query string

resultSetMappingName - The explicit result mapping name

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityHandler.createNativeQuery(String,Class)
• SqlResultSetMapping

createNativeMutationQuery

MutationQuery createNativeMutationQuery(String sqlString)

Create a NativeQuery instance for the given native SQL statement.

Parameters:

sqlString - a native SQL statement string

Returns:

The NativeQuery instance for manipulation and execution

createNamedQuery

@Nonnull
<R> SelectionQuery<R> createNamedQuery(@Nonnull
 String name,
 @Nonnull
 Class<R> resultClass)

Create a typed Query instance for the given named query. The named query might be defined in HQL or in native SQL.

Specified by:

createNamedQuery in interface EntityHandler

Parameters:

name - the name of a query defined in metadata

resultClass - the type of the query result

Returns:

The Query instance for manipulation and execution

Throws:

IllegalArgumentException - if a query has not been defined with the given name or if the query string is found to be invalid or if the query result is found to not be assignable to the specified type

See Also:

• EntityHandler.createNamedQuery(String,Class)

createNamedStatement

@Nonnull
MutationQuery createNamedStatement(@Nonnull
 String name)

Specified by:

createNamedStatement in interface EntityHandler

createNamedQuery

@Nonnull
<R> NativeQuery<R> createNamedQuery(@Nonnull
 String name,
 @Nonnull
 String resultSetMappingName)

createNamedQuery

@Nonnull
<R> NativeQuery<R> createNamedQuery(@Nonnull
 String name,
 @Nonnull
 String resultSetMappingName,
 @Nonnull
 Class<R> resultClass)

createNativeStatement

@Nonnull
MutationQuery createNativeStatement(@Nonnull
 String sql)

Specified by:

createNativeStatement in interface EntityHandler

createNativeQuery

@Nonnull
NativeQuery<?> createNativeQuery(@Nonnull
 String sql,
 @Nonnull
 String resultSetMapping)

Specified by:

createNativeQuery in interface EntityHandler

createNativeQuery

@Nonnull
<T> TypedQuery<T> createNativeQuery(@Nonnull
 String sql,
 @Nonnull
 jakarta.persistence.sql.ResultSetMapping<T> resultSetMapping)

Specified by:

createNativeQuery in interface EntityHandler

createNamedSelectionQuery

@Nonnull
<R> SelectionQuery<R> createNamedSelectionQuery(@Nonnull
 String name,
 @Nonnull
 Class<R> resultType)

Create a SelectionQuery instance for the named NamedQuery with the given result type.

Throws:

IllegalSelectQueryException - if the given HQL query is not a select query

UnknownNamedQueryException - if no query has been defined with the given name

createNamedMutationQuery

@Nonnull
MutationQuery createNamedMutationQuery(@Nonnull
 String name)

Create a MutationQuery instance for the given named insert, update, or delete HQL query. The named query might be defined as HQL) or native-SQL.

Throws:

IllegalMutationQueryException - if the given HQL query is a select query

UnknownNamedQueryException - if no query has been defined with the given name

getNamedProcedureCall

@Nonnull
ProcedureCall getNamedProcedureCall(@Nonnull
 String name)

Obtain a ProcedureCall based on a named template

Parameters:

name - The name given to the template

Returns:

The ProcedureCall

See Also:

• NamedStoredProcedureQuery

createStoredProcedureCall

@Nonnull
ProcedureCall createStoredProcedureCall(@Nonnull
 String procedureName)

Create a ProcedureCall to a stored procedure.

Parameters:

procedureName - The name of the procedure.

Returns:

The representation of the procedure call.

createStoredProcedureCall

@Nonnull
ProcedureCall createStoredProcedureCall(@Nonnull
 String procedureName,
 @Nonnull
 Class<?>... resultClasses)

Create a ProcedureCall to a stored procedure with the given result set entity mappings. Each given class is considered a "root return".

Parameters:

procedureName - The name of the procedure.

resultClasses - The entity(s) to map the result on to.

Returns:

The representation of the procedure call.

createStoredProcedureCall

@Nonnull
ProcedureCall createStoredProcedureCall(@Nonnull
 String procedureName,
 @Nonnull
 String... resultSetMappings)

Create a ProcedureCall to a stored procedure with the given result set entity mappings.

Parameters:

procedureName - The name of the procedure.

resultSetMappings - The explicit result set mapping(s) to use for mapping the results

Returns:

The representation of the procedure call.

createNamedStoredProcedureQuery

@Nonnull
ProcedureCall createNamedStoredProcedureQuery(@Nonnull
 String name)

Obtain a ProcedureCall based on a named template

Specified by:

createNamedStoredProcedureQuery in interface EntityHandler

Parameters:

name - The name given to the template

Returns:

The ProcedureCall

See Also:

• NamedStoredProcedureQuery

createStoredProcedureQuery

@Nonnull
ProcedureCall createStoredProcedureQuery(@Nonnull
 String procedureName)

Create a ProcedureCall to a stored procedure.

Specified by:

createStoredProcedureQuery in interface EntityHandler

Parameters:

procedureName - The name of the procedure.

Returns:

The representation of the procedure call.

createStoredProcedureQuery

@Nonnull
ProcedureCall createStoredProcedureQuery(@Nonnull
 String procedureName,
 @Nonnull
 Class<?>... resultClasses)

Create a ProcedureCall to a stored procedure with the given result set entity mappings. Each given class is considered a "root return".

Specified by:

createStoredProcedureQuery in interface EntityHandler

Parameters:

procedureName - The name of the procedure.

resultClasses - The entity(s) to map the result on to.

Returns:

The representation of the procedure call.

createStoredProcedureQuery

@Nonnull
ProcedureCall createStoredProcedureQuery(@Nonnull
 String procedureName,
 @Nonnull
 String... resultSetMappings)

Create a ProcedureCall to a stored procedure with the given result set entity mappings.

Specified by:

createStoredProcedureQuery in interface EntityHandler

Parameters:

procedureName - The name of the procedure.

resultSetMappings - The explicit result set mapping(s) to use for mapping the results

Returns:

The representation of the procedure call.

getJdbcBatchSize

Integer getJdbcBatchSize()

Get the session-level JDBC batch size for the current session.

Returns:

the current session-level JDBC batch size

Since:

5.2

See Also:

• SessionFactoryOptions.getJdbcBatchSize()
• SessionFactoryBuilder.applyJdbcBatchSize(int)

setJdbcBatchSize

void setJdbcBatchSize(Integer jdbcBatchSize)

Set the session-level JDBC batch size. Override the factory-level JDBC batch size controlled by the configuration property "hibernate.jdbc.batch_size".

Parameters:

jdbcBatchSize - the new session-level JDBC batch size

Since:

5.2

See Also:

• BatchSettings.STATEMENT_BATCH_SIZE
• SessionFactoryOptions.getJdbcBatchSize()
• SessionFactoryBuilder.applyJdbcBatchSize(int)

API Note:

Setting a session-level JDBC batch size for a StatelessSession triggers a sort of write-behind behaviour where operations are batched and executed asynchronously, undermining the semantics of the stateless programming model. We recommend the use of explicitly batching operations like insertMultiple(), updateMultiple(), and deleteMultiple() instead.

getCriteriaBuilder

@Nonnull
HibernateCriteriaBuilder getCriteriaBuilder()

Obtain a HibernateCriteriaBuilder which may be used to construct criteria queries.

Specified by:

getCriteriaBuilder in interface EntityHandler

Returns:

an instance of HibernateCriteriaBuilder

Throws:

IllegalStateException - if the session has been closed

See Also:

• SessionFactory.getCriteriaBuilder()

doWork

void doWork(@Nonnull
 Work work)
     throws HibernateException

Perform work using the Connection underlying by this session.

Parameters:

work - The work to be performed.

Throws:

HibernateException - Generally indicates wrapped SQLException

API Note:

This method competes with the JPA-defined method EntityHandler.runWithConnection(ConnectionConsumer)

doReturningWork

<T> T doReturningWork(@Nonnull
 ReturningWork<T> work)

Perform work using the Connection underlying by this session, and return a result.

Type Parameters:

T - The type of the result returned from the work

Parameters:

work - The work to be performed.

Returns:

the result of calling ReturningWork.execute(Connection).

Throws:

HibernateException - Generally indicates wrapped SQLException

API Note:

This method competes with the JPA-defined method EntityHandler.callWithConnection(ConnectionFunction)

createEntityGraph

@Nonnull
<T> RootGraph<T> createEntityGraph(@Nonnull
 Class<T> rootType)

Create a new mutable instance of EntityGraph, with only a root node, allowing programmatic definition of the graph from scratch.

Specified by:

createEntityGraph in interface EntityHandler

Parameters:

rootType - the root entity class of the graph

Since:

6.3

See Also:

• EntityGraphs.createGraph(jakarta.persistence.metamodel.EntityType)

createEntityGraph

@Deprecated(since="8.0",
            forRemoval=true)
@Nullable
RootGraph<?> createEntityGraph(@Nonnull
 String graphName)

Deprecated, for removal: This API element is subject to removal in a future version.

Use getEntityGraph(String) instead.

Create a new mutable instance of EntityGraph, based on a predefined named entity graph, allowing customization of the graph, or return null if there is no predefined graph with the given name.

Parameters:

graphName - the name of the graph

Since:

6.3

createEntityGraph

@Deprecated(since="8.0",
            forRemoval=true)
@Nullable
<T> RootGraph<T> createEntityGraph(@Nonnull
 Class<T> rootType,
 @Nonnull
 String graphName)

Deprecated, for removal: This API element is subject to removal in a future version.

Use getEntityGraph(Class, String) instead.

Create a new mutable instance of EntityGraph, based on a predefined named entity graph, allowing customization of the graph, or return null if there is no predefined graph with the given name.

Parameters:

rootType - the root entity class of the graph

graphName - the name of the predefined named entity graph

Throws:

IllegalArgumentException - if the graph with the given name does not have the given entity type as its root

Since:

6.3

getEntityGraph

@Nonnull
RootGraph<?> getEntityGraph(@Nonnull
 String graphName)

Obtain a mutable copy of a predefined named entity graph.

Specified by:

getEntityGraph in interface EntityHandler

Parameters:

graphName - the name of the predefined named entity graph

Throws:

IllegalArgumentException - if there is no predefined graph with the given name

Since:

6.3

See Also:

• EntityHandler.getEntityGraph(String)
• EntityManagerFactory.getNamedEntityGraphs(Class)
• EntityManagerFactory.addNamedEntityGraph(String, EntityGraph)

API Note:

This method returns RootGraph<?>, requiring an unchecked typecast before use. It's cleaner to obtain a graph using the static metamodel for the class which defines the graph, by calling getEntityGraph(Class, String), or by calling EntityManagerFactory.getNamedEntityGraphs(Class).

getEntityGraph

@Nonnull
<T> RootGraph<T> getEntityGraph(@Nonnull
 Class<T> rootType,
 @Nonnull
 String graphName)

Obtain a mutable copy of a predefined named entity graph whose root type is exactly the given entity type.

Specified by:

getEntityGraph in interface EntityHandler

Parameters:

rootType - the root entity class of the graph

graphName - the name of the predefined named entity graph

Throws:

IllegalArgumentException - if there is no predefined graph with the given name, or if the graph with the given name does not have the given entity type as its root

Since:

8.0

See Also:

• EntityHandler.getEntityGraph(Class,String)
• EntityManagerFactory.getNamedEntityGraphs(Class)
• EntityManagerFactory.addNamedEntityGraph(String, EntityGraph)

getEntityGraphs

@Nonnull
<T> List<EntityGraph<? super T>> getEntityGraphs(@Nonnull
 Class<T> entityClass)

Retrieve all named EntityGraphs with the given root entity type.

Specified by:

getEntityGraphs in interface EntityHandler

Since:

6.3

See Also:

• EntityManagerFactory.getNamedEntityGraphs(Class)
• EntityManagerFactory.addNamedEntityGraph(String, EntityGraph)

enableFilter

@Nonnull
Filter enableFilter(@Nonnull
 String filterName)

Enable the named filter for this current session.

The returned Filter object must be used to bind arguments to parameters of the filter, and every parameter must be set before any other operation of this session is called.

Parameters:

filterName - the name of the filter to be enabled.

Returns:

the Filter instance representing the enabled filter.

Throws:

UnknownFilterException - if there is no such filter

See Also:

• FilterDef

getEnabledFilter

@Nullable
Filter getEnabledFilter(@Nonnull
 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.

disableFilter

void disableFilter(@Nonnull
 String filterName)

Disable the named filter for the current session.

Parameters:

filterName - the name of the filter to be disabled.

getFactory

@Nonnull
SessionFactory getFactory()

The factory which created this session.

inTransaction

default void inTransaction(@Nonnull
 Consumer<? super Transaction> action)

Perform an action within the bounds of a transaction associated with this session.

Parameters:

action - a void function which accepts the Transaction

Since:

7.0

fromTransaction

default <R> R fromTransaction(@Nonnull
 Function<? super Transaction, R> action)

Obtain a value within the bounds of a transaction associated with this session.

Parameters:

action - a function which accepts the Transaction and returns the value

Since:

7.0

statelessWithOptions

@Incubating
SharedStatelessSessionBuilder statelessWithOptions()

Obtain a StatelessSession builder with the ability to copy certain information from this session.

Returns:

the session builder

Since:

7.2

sessionWithOptions

@Nonnull
SharedSessionBuilder sessionWithOptions()

Obtain a Session builder with the ability to copy certain information from this session.

Returns:

the session builder

createQuery

@Nonnull
MutationOrSelectionQuery createQuery(@Nonnull
 String queryString)

Create an instance of Query for the given HQL query or statement, without indicating the expected result type, if any, nor whether the query is a typed query which returns a result list, or an update, delete, or insert statement.

Specified by:

createQuery in interface EntityHandler

createNamedQuery

@Nonnull
MutationOrSelectionQuery createNamedQuery(@Nonnull
 String name)

Create an instance of Query for the given named query or statement, without indicating the expected result type, if any, nor whether the query is a typed query which returns a result list, or an update, delete, or insert statement.

Specified by:

createNamedQuery in interface EntityHandler