Package org.hibernate

Interface StatelessSession

All Superinterfaces:

AutoCloseable, Closeable, QueryProducer, Serializable, SharedSessionContract

All Known Implementing Classes:

StatelessSessionImpl

public interface StatelessSession
extends SharedSessionContract

A command-oriented API often used for performing bulk operations against the database. A stateless session has no persistence context, and always works directly with detached entity instances. When a method of this interface is called, any necessary interaction with the database happens immediately and synchronously.

Viewed in opposition to Session, the StatelessSession is a whole competing programming model, one preferred by some developers for its simplicity and somewhat lower level of abstraction. But the two kinds of session are not enemies, and may comfortably coexist in a single program.

A stateless session comes some with designed-in limitations:

• it does not have a first-level cache,
• nor interact with any second-level cache,
• nor does it implement transactional write-behind or automatic dirty checking.

Furthermore, the basic operations of a stateless session do not have corresponding cascade types, and so an operation performed via a stateless session never cascades to associated instances.

The basic operations of a stateless session are get(Class, Object), insert(Object), update(Object), delete(Object), and upsert(Object). These operations are always performed synchronously, resulting in immediate access to the database. Notice that update is an explicit operation. There is no "flush" operation for a stateless session, and so modifications to entities are never automatically detected and made persistent.

Similarly, lazy association fetching is an explicit operation. A collection or proxy may be fetched by calling fetch(Object).

Stateless sessions are vulnerable to data aliasing effects, due to the lack of a first-level cache.

On the other hand, for certain kinds of transactions, a stateless session may perform slightly faster than a stateful session.

Certain rules applying to stateful sessions are relaxed in a stateless session:

• it is not necessary to discard a session and its entities after an exception is thrown by a stateless sessions, and
• when an exception is thrown by a stateless session, the current transaction is not automatically marked for rollback.

Method Summary

Modifier and Type	Method	Description
void	close()	Close the stateless session and release the JDBC connection.
void	delete(Object entity)	Delete a record.
void	delete(String entityName, Object entity)	Delete a record.
void	fetch(Object association)	Fetch an association or collection that's configured for lazy loading.
<T> T	get(EntityGraph<T> graph, GraphSemantic graphSemantic, Object id)	Retrieve a record, fetching associations specified by the given EntityGraph.
<T> T	get(EntityGraph<T> graph, GraphSemantic graphSemantic, Object id, LockMode lockMode)	Retrieve a record, fetching associations specified by the given EntityGraph, and obtaining the specified lock mode.
<T> T	get(Class<T> entityClass, Object id)	Retrieve a record.
<T> T	get(Class<T> entityClass, Object id, LockMode lockMode)	Retrieve a record, obtaining the specified lock mode.
Object	get(String entityName, Object id)	Retrieve a record.
Object	get(String entityName, Object id, LockMode lockMode)	Retrieve a record, obtaining the specified lock mode.
Object	getIdentifier(Object entity)	Return the identifier value of the given entity, which may be detached.
Object	insert(Object entity)	Insert a record.
Object	insert(String entityName, Object entity)	Insert a record.
void	refresh(Object entity)	Refresh the entity instance state from the database.
void	refresh(Object entity, LockMode lockMode)	Refresh the entity instance state from the database.
void	refresh(String entityName, Object entity)	Refresh the entity instance state from the database.
void	refresh(String entityName, Object entity, LockMode lockMode)	Refresh the entity instance state from the database.
void	update(Object entity)	Update a record.
void	update(String entityName, Object entity)	Update a record.
void	upsert(Object entity)	Use a SQL merge into statement to perform an upsert, that is, to insert the record if it does not exist, or update it if it already exists.
void	upsert(String entityName, Object entity)	Use a SQL merge into statement to perform an upsert.

Methods inherited from interface org.hibernate.query.QueryProducer

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

Methods inherited from interface org.hibernate.SharedSessionContract

beginTransaction, createEntityGraph, createEntityGraph, createEntityGraph, createNamedStoredProcedureQuery, createStoredProcedureCall, createStoredProcedureCall, createStoredProcedureCall, createStoredProcedureQuery, createStoredProcedureQuery, createStoredProcedureQuery, disableFilter, doReturningWork, doWork, enableFilter, getCriteriaBuilder, getEnabledFilter, getEntityGraph, getEntityGraphs, getFactory, getJdbcBatchSize, getNamedProcedureCall, getTenantIdentifier, getTenantIdentifierValue, getTransaction, isConnected, isJoinedToTransaction, isOpen, joinTransaction, setJdbcBatchSize

Method Detail

close

void close()

Close the stateless session and release the JDBC connection.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in interface SharedSessionContract

insert

Object insert(Object entity)

Insert a record.

If the entity @Id field is declared to be generated, for example, if it is annotated @GeneratedId, the id is generated and assigned to the given instance.

The PostPersist callback will be triggered if the operation is successful.

Parameters:

entity - a new transient instance

Returns:

The identifier of the inserted entity

insert

Object insert(String entityName,
              Object entity)

Insert a record.

The PostPersist callback will be triggered if the operation is successful.

Parameters:

entityName - The entityName for the entity to be inserted

entity - a new transient instance

Returns:

the identifier of the instance

update

void update(Object entity)

Update a record.

The PostUpdate callback will be triggered if the operation is successful.

Parameters:

entity - a detached entity instance

update

void update(String entityName,
            Object entity)

Update a record.

The PostUpdate callback will be triggered if the operation is successful.

Parameters:

entityName - The entityName for the entity to be updated

entity - a detached entity instance

delete

void delete(Object entity)

Delete a record.

The PostRemove callback will be triggered if the operation is successful.

Parameters:

entity - a detached entity instance

delete

void delete(String entityName,
            Object entity)

Delete a record.

The PostRemove callback will be triggered if the operation is successful.

Parameters:

entityName - The entityName for the entity to be deleted

entity - a detached entity instance

upsert

@Incubating
void upsert(Object entity)

Use a SQL merge into statement to perform an upsert, that is, to insert the record if it does not exist, or update it if it already exists.

This method never performs id generation, and does not accept an entity instance with a null identifier. When id generation is required, use insert(Object).

On the other hand, upsert() does accept an entity instance with an assigned identifier value, even if the entity @Id field is declared to be generated, for example, if it is annotated @GeneratedId. Thus, this method may be used to import data from an external source.

Parameters:

entity - a detached entity instance, or a new instance with an assigned identifier

Throws:

TransientObjectException - is the entity has a null id

Since:

6.3

upsert

@Incubating
void upsert(String entityName,
            Object entity)

Use a SQL merge into statement to perform an upsert.

Parameters:

entityName - The entityName for the entity to be merged

entity - a detached entity instance

Throws:

TransientObjectException - is the entity has a null id

Since:

6.3

get

Object get(String entityName,
           Object id)

Retrieve a record.

Parameters:

entityName - The name of the entity to retrieve

id - The id of the entity to retrieve

Returns:

a detached entity instance

get

<T> T get(Class<T> entityClass,
          Object id)

Retrieve a record.

Parameters:

entityClass - The class of the entity to retrieve

id - The id of the entity to retrieve

Returns:

a detached entity instance

get

Object get(String entityName,
           Object id,
           LockMode lockMode)

Retrieve a record, obtaining the specified lock mode.

Parameters:

entityName - The name of the entity to retrieve

id - The id of the entity to retrieve

lockMode - The lock mode to apply to the entity

Returns:

a detached entity instance

get

<T> T get(Class<T> entityClass,
          Object id,
          LockMode lockMode)

Retrieve a record, obtaining the specified lock mode.

Parameters:

entityClass - The class of the entity to retrieve

id - The id of the entity to retrieve

lockMode - The lock mode to apply to the entity

Returns:

a detached entity instance

get

<T> T get(EntityGraph<T> graph,
          GraphSemantic graphSemantic,
          Object id)

Retrieve a record, fetching associations specified by the given EntityGraph.

Parameters:

graph - The EntityGraph

graphSemantic - a GraphSemantic specifying how the graph should be interpreted

id - The id of the entity to retrieve

Returns:

a detached entity instance

Since:

6.3

get

<T> T get(EntityGraph<T> graph,
          GraphSemantic graphSemantic,
          Object id,
          LockMode lockMode)

Retrieve a record, fetching associations specified by the given EntityGraph, and obtaining the specified lock mode.

Parameters:

graph - The EntityGraph

graphSemantic - a GraphSemantic specifying how the graph should be interpreted

id - The id of the entity to retrieve

lockMode - The lock mode to apply to the entity

Returns:

a detached entity instance

Since:

6.3

refresh

void refresh(Object entity)

Refresh the entity instance state from the database.

Parameters:

entity - The entity to be refreshed.

refresh

void refresh(String entityName,
             Object entity)

Refresh the entity instance state from the database.

Parameters:

entityName - The entityName for the entity to be refreshed.

entity - The entity to be refreshed.

refresh

void refresh(Object entity,
             LockMode lockMode)

Refresh the entity instance state from the database.

Parameters:

entity - The entity to be refreshed.

lockMode - The LockMode to be applied.

refresh

void refresh(String entityName,
             Object entity,
             LockMode lockMode)

Refresh the entity instance state from the database.

Parameters:

entityName - The entityName for the entity to be refreshed.

entity - The entity to be refreshed.

lockMode - The LockMode to be applied.

fetch

void fetch(Object association)

Fetch an association or collection that's configured for lazy loading.

 Book book = session.get(Book.class, isbn);  // book is immediately detached
 session.fetch(book.getAuthors());           // fetch the associated authors
 book.getAuthors().forEach(author -> ... );  // iterate the collection
 

Warning: this operation in a stateless session is quite sensitive to data aliasing effects and should be used with great care. It's usually better to fetch associations using eager join fetching.

Parameters:

association - a lazy-loaded association

Since:

6.0

See Also:

Hibernate.initialize(Object)

getIdentifier

Object getIdentifier(Object entity)

Return the identifier value of the given entity, which may be detached.

Parameters:

entity - a persistent instance associated with this session

Returns:

the identifier

Since:

6.6