Package org.hibernate

Interface SharedSessionContract

All Superinterfaces:

AutoCloseable, QueryProducer, Serializable

All Known Subinterfaces:

EventSource, Session, SessionImplementor, SharedSessionContractImplementor, StatelessSession

All Known Implementing Classes:

SessionDelegatorBaseImpl, SessionLazyDelegator, SharedSessionDelegatorBaseImpl

public interface SharedSessionContract
extends QueryProducer, 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)	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.
RootGraph<?>	createEntityGraph(String graphName)	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.
ProcedureCall	createNamedStoredProcedureQuery(String name)	Obtain a ProcedureCall based on a named template
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 <R> R	fromTransaction(Function<? super Transaction,R> action)	Obtain a value within the bounds of a transaction associated with this session.
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.
RootGraph<?>	getEntityGraph(String graphName)	Obtain an immutable reference to a predefined named entity graph or return null if there is no predefined graph with the given name.
<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.
void	setCacheMode(CacheMode cacheMode)	Set the current cache mode for this session.
void	setJdbcBatchSize(Integer jdbcBatchSize)	Set the session-level JDBC batch size.

Methods inherited from interface org.hibernate.query.QueryProducer

createMutationQuery, createMutationQuery, createMutationQuery, createMutationQuery, createNamedMutationQuery, createNamedQuery, createNamedQuery, createNamedSelectionQuery, createNamedSelectionQuery, createNativeMutationQuery, createNativeQuery, createNativeQuery, createNativeQuery, createNativeQuery, createNativeQuery, createQuery, createQuery, createQuery, createQuery, createQuery, createQuery, createSelectionQuery, createSelectionQuery, createSelectionQuery, createSelectionQuery, getNamedNativeQuery, getNamedNativeQuery, getNamedQuery

Method Details

getTenantIdentifier

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)

getTenantIdentifierValue

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)

getCacheMode

CacheMode getCacheMode()

Get the current cache mode for this session.

Returns:

the current cache mode

setCacheMode

void setCacheMode(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

Throws:

HibernateException - Indicates problems cleaning up.

isOpen

boolean isOpen()

Check if the session is still open.

Returns:

true if it is open

isConnected

boolean isConnected()

Check if the session is currently connected.

Returns:

true if it is connected

beginTransaction

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

Transaction getTransaction()

Get the Transaction instance associated with this session.

Returns:

an instance of Transaction representing the transaction associated with this session

See Also:

• EntityManager.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()

getNamedProcedureCall

ProcedureCall getNamedProcedureCall(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

ProcedureCall createStoredProcedureCall(String procedureName)

Create a ProcedureCall to a stored procedure.

Parameters:

procedureName - The name of the procedure.

Returns:

The representation of the procedure call.

createStoredProcedureCall

ProcedureCall createStoredProcedureCall(String procedureName,
 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

ProcedureCall createStoredProcedureCall(String procedureName,
 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

ProcedureCall createNamedStoredProcedureQuery(String name)

Obtain a ProcedureCall based on a named template

Parameters:

name - The name given to the template

Returns:

The ProcedureCall

See Also:

• NamedStoredProcedureQuery

createStoredProcedureQuery

ProcedureCall createStoredProcedureQuery(String procedureName)

Create a ProcedureCall to a stored procedure.

Parameters:

procedureName - The name of the procedure.

Returns:

The representation of the procedure call.

createStoredProcedureQuery

ProcedureCall createStoredProcedureQuery(String procedureName,
 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.

createStoredProcedureQuery

ProcedureCall createStoredProcedureQuery(String procedureName,
 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.

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

HibernateCriteriaBuilder getCriteriaBuilder()

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

Returns:

an instance of HibernateCriteriaBuilder

Throws:

IllegalStateException - if the session has been closed

See Also:

• SessionFactory.getCriteriaBuilder()

doWork

void doWork(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 EntityManager.runWithConnection(jakarta.persistence.ConnectionConsumer<C>)

doReturningWork

<T> T doReturningWork(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(java.sql.Connection).

Throws:

HibernateException - Generally indicates wrapped SQLException

API Note:

This method competes with the JPA-defined method EntityManager.callWithConnection(jakarta.persistence.ConnectionFunction<C, T>)

createEntityGraph

<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.

Parameters:

rootType - the root entity class of the graph

Since:

6.3

See Also:

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

createEntityGraph

RootGraph<?> createEntityGraph(String graphName)

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

See Also:

• 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 createEntityGraph(Class, String) instead.

createEntityGraph

<T> RootGraph<T> createEntityGraph(Class<T> rootType,
 String graphName)

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

See Also:

• EntityManagerFactory.addNamedEntityGraph(String, EntityGraph)

getEntityGraph

RootGraph<?> getEntityGraph(String graphName)

Obtain an immutable reference to a predefined named entity graph or return null if there is no predefined graph with the given name.

Parameters:

graphName - the name of the predefined named entity graph

Since:

6.3

See Also:

• 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, or by calling EntityManagerFactory.getNamedEntityGraphs(Class) instead.

getEntityGraphs

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

Retrieve all named EntityGraphs with the given root entity type.

Since:

6.3

See Also:

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

enableFilter

Filter enableFilter(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

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.

disableFilter

void disableFilter(String filterName)

Disable the named filter for the current session.

Parameters:

filterName - the name of the filter to be disabled.

getFactory

SessionFactory getFactory()

The factory which created this session.

inTransaction

default void inTransaction(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(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