org.hibernate.Session Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of hibernate-core-jakarta Show documentation
Show all versions of hibernate-core-jakarta Show documentation
Hibernate O/RM implementation of the Jakarta Persistence specification
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* License: GNU Lesser General Public License (LGPL), version 2.1 or later.
* See the lgpl.txt file in the root directory or .
*/
package org.hibernate;
import java.io.Closeable;
import java.io.Serializable;
import java.sql.Connection;
import java.util.List;
import jakarta.persistence.EntityGraph;
import jakarta.persistence.EntityManager;
import jakarta.persistence.FlushModeType;
import jakarta.persistence.criteria.CriteriaDelete;
import jakarta.persistence.criteria.CriteriaQuery;
import jakarta.persistence.criteria.CriteriaUpdate;
import org.hibernate.graph.RootGraph;
import org.hibernate.jpa.HibernateEntityManager;
import org.hibernate.query.NativeQuery;
import org.hibernate.stat.SessionStatistics;
/**
* The main runtime interface between a Java application and Hibernate. This is the
* central API class abstracting the notion of a persistence service.
*
* The lifecycle of a Session is bounded by the beginning and end of a logical
* transaction. (Long transactions might span several database transactions.)
*
* The main function of the Session is to offer create, read and delete operations
* for instances of mapped entity classes. Instances may exist in one of three states:
*
* transient: never persistent, not associated with any Session
* persistent: associated with a unique Session
* detached: previously persistent, not associated with any Session
*
* Transient instances may be made persistent by calling save(),
* persist() or saveOrUpdate(). Persistent instances may be made transient
* by calling delete(). Any instance returned by a get() or
* load() method is persistent. Detached instances may be made persistent
* by calling update(), saveOrUpdate(), lock() or replicate().
* The state of a transient or detached instance may also be made persistent as a new
* persistent instance by calling merge().
*
* save() and persist() result in an SQL INSERT, delete()
* in an SQL DELETE and update() or merge() in an SQL UPDATE.
* Changes to persistent instances are detected at flush time and also result in an SQL
* UPDATE. saveOrUpdate() and replicate() result in either an
* INSERT or an UPDATE.
*
* It is not intended that implementors be threadsafe. Instead each thread/transaction
* should obtain its own instance from a SessionFactory.
*
* A Session instance is serializable if its persistent classes are serializable.
*
* A typical transaction should use the following idiom:
*
* Session sess = factory.openSession();
* Transaction tx;
* try {
* tx = sess.beginTransaction();
* //do some work
* ...
* tx.commit();
* }
* catch (Exception e) {
* if (tx!=null) tx.rollback();
* throw e;
* }
* finally {
* sess.close();
* }
*
*
* If the Session throws an exception, the transaction must be rolled back
* and the session discarded. The internal state of the Session might not
* be consistent with the database after the exception occurs.
*
* @see SessionFactory
*
* @author Gavin King
* @author Steve Ebersole
*/
public interface Session extends SharedSessionContract, EntityManager, HibernateEntityManager, AutoCloseable, Closeable {
/**
* Obtain a {@link Session} builder with the ability to grab certain information from this session.
*
* @return The session builder
*/
SharedSessionBuilder sessionWithOptions();
/**
* Force this session to flush. Must be called at the end of a
* unit of work, before committing the transaction and closing the
* session (depending on {@link #setFlushMode(FlushMode)},
* {@link Transaction#commit()} calls this method).
*
* Flushing is the process of synchronizing the underlying persistent
* store with persistable state held in memory.
*
* @throws HibernateException Indicates problems flushing the session or
* talking to the database.
*/
void flush() throws HibernateException;
/**
* Set the flush 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 {@link FlushMode#MANUAL} at the start of the session (in
* order to achieve some extra performance).
*
* @param flushMode the new flush mode
*
* @deprecated (since 5.2) use {@link #setHibernateFlushMode(FlushMode)} instead
*/
@Deprecated
void setFlushMode(FlushMode flushMode);
/**
* {@inheritDoc}
*
* For users of the Hibernate native APIs, we've had to rename this method
* as defined by Hibernate historically because the JPA contract defines a method of the same
* name, but returning the JPA {@link FlushModeType} rather than Hibernate's {@link FlushMode}. For
* the former behavior, use {@link Session#getHibernateFlushMode()} instead.
*
* @return The FlushModeType in effect for this Session.
*/
@Override
FlushModeType getFlushMode();
/**
* Set the flush 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 {@link FlushMode#MANUAL} at the start of the session (in
* order to achieve some extra performance).
*
* @param flushMode the new flush mode
*/
void setHibernateFlushMode(FlushMode flushMode);
/**
* Get the current flush mode for this session.
*
* @return The flush mode
*/
FlushMode getHibernateFlushMode();
/**
* Set the cache mode.
*
* Cache mode determines the manner in which this session can interact with
* the second level cache.
*
* @param cacheMode The new cache mode.
*/
void setCacheMode(CacheMode cacheMode);
/**
* Get the current cache mode.
*
* @return The current cache mode.
*/
CacheMode getCacheMode();
/**
* Get the session factory which created this session.
*
* @return The session factory.
* @see SessionFactory
*/
SessionFactory getSessionFactory();
/**
* Cancel the execution of the current query.
*
* This is the sole method on session which may be safely called from
* another thread.
*
* @throws HibernateException There was a problem canceling the query
*/
void cancelQuery() throws HibernateException;
/**
* Does this session contain any changes which must be synchronized with
* the database? In other words, would any DML operations be executed if
* we flushed this session?
*
* @return True if the session contains pending changes; false otherwise.
* @throws HibernateException could not perform dirtying checking
*/
boolean isDirty() throws HibernateException;
/**
* Will entities and proxies that are loaded into this session be made
* read-only by default?
*
* To determine the read-only/modifiable setting for a particular entity
* or proxy:
* @see Session#isReadOnly(Object)
*
* @return true, loaded entities/proxies will be made read-only by default;
* false, loaded entities/proxies will be made modifiable by default.
*/
boolean isDefaultReadOnly();
/**
* Change the default for entities and proxies loaded into this session
* from modifiable to read-only mode, or from modifiable to read-only mode.
*
* Read-only entities are not dirty-checked and snapshots of persistent
* state are not maintained. Read-only entities can be modified, but
* changes are not persisted.
*
* When a proxy is initialized, the loaded entity will have the same
* read-only/modifiable setting as the uninitialized
* proxy has, regardless of the session's current setting.
*
* To change the read-only/modifiable setting for a particular entity
* or proxy that is already in this session:
* @see Session#setReadOnly(Object,boolean)
*
* To override this session's read-only/modifiable setting for entities
* and proxies loaded by a Query:
* @see Query#setReadOnly(boolean)
*
* @param readOnly true, the default for loaded entities/proxies is read-only;
* false, the default for loaded entities/proxies is modifiable
*/
void setDefaultReadOnly(boolean readOnly);
/**
* Return the identifier value of the given entity as associated with this
* session. An exception is thrown if the given entity instance is transient
* or detached in relation to this session.
*
* @param object a persistent instance
* @return the identifier
* @throws TransientObjectException if the instance is transient or associated with
* a different session
*/
Serializable getIdentifier(Object object);
/**
* Check if this entity is associated with this Session. This form caters to
* non-POJO entities, by allowing the entity-name to be passed in
*
* @param entityName The entity name
* @param object an instance of a persistent class
*
* @return true if the given instance is associated with this Session
*/
boolean contains(String entityName, Object object);
/**
* Remove this instance from the session cache. Changes to the instance will
* not be synchronized with the database. This operation cascades to associated
* instances if the association is mapped with cascade="evict".
*
* @param object The entity to evict
*
* @throws NullPointerException if the passed object is {@code null}
* @throws IllegalArgumentException if the passed object is not defined as an entity
*/
void evict(Object object);
/**
* Return the persistent instance of the given entity class with the given identifier,
* obtaining the specified lock mode, assuming the instance exists.
*
* Convenient form of {@link #load(Class, Serializable, LockOptions)}
*
* @param theClass a persistent class
* @param id a valid identifier of an existing persistent instance of the class
* @param lockMode the lock level
*
* @return the persistent instance or proxy
*
* @see #load(Class, Serializable, LockOptions)
*/
T load(Class theClass, Serializable id, LockMode lockMode);
/**
* Return the persistent instance of the given entity class with the given identifier,
* obtaining the specified lock mode, assuming the instance exists.
*
* @param theClass a persistent class
* @param id a valid identifier of an existing persistent instance of the class
* @param lockOptions contains the lock level
* @return the persistent instance or proxy
*/
T load(Class theClass, Serializable id, LockOptions lockOptions);
/**
* Return the persistent instance of the given entity class with the given identifier,
* obtaining the specified lock mode, assuming the instance exists.
*
* Convenient form of {@link #load(String, Serializable, LockOptions)}
*
* @param entityName a persistent class
* @param id a valid identifier of an existing persistent instance of the class
* @param lockMode the lock level
*
* @return the persistent instance or proxy
*
* @see #load(String, Serializable, LockOptions)
*/
Object load(String entityName, Serializable id, LockMode lockMode);
/**
* Return the persistent instance of the given entity class with the given identifier,
* obtaining the specified lock mode, assuming the instance exists.
*
* @param entityName a persistent class
* @param id a valid identifier of an existing persistent instance of the class
* @param lockOptions contains the lock level
*
* @return the persistent instance or proxy
*/
Object load(String entityName, Serializable id, LockOptions lockOptions);
/**
* Return the persistent instance of the given entity class with the given identifier,
* assuming that the instance exists. This method might return a proxied instance that
* is initialized on-demand, when a non-identifier method is accessed.
*
* You should not use this method to determine if an instance exists (use get()
* instead). Use this only to retrieve an instance that you assume exists, where non-existence
* would be an actual error.
*
* @param theClass a persistent class
* @param id a valid identifier of an existing persistent instance of the class
*
* @return the persistent instance or proxy
*/
T load(Class theClass, Serializable id);
/**
* Return the persistent instance of the given entity class with the given identifier,
* assuming that the instance exists. This method might return a proxied instance that
* is initialized on-demand, when a non-identifier method is accessed.
*
* You should not use this method to determine if an instance exists (use get()
* instead). Use this only to retrieve an instance that you assume exists, where non-existence
* would be an actual error.
*
* @param entityName a persistent class
* @param id a valid identifier of an existing persistent instance of the class
*
* @return the persistent instance or proxy
*/
Object load(String entityName, Serializable id);
/**
* Read the persistent state associated with the given identifier into the given transient
* instance.
*
* @param object an "empty" instance of the persistent class
* @param id a valid identifier of an existing persistent instance of the class
*/
void load(Object object, Serializable id);
/**
* Persist the state of the given detached instance, reusing the current
* identifier value. This operation cascades to associated instances if
* the association is mapped with {@code cascade="replicate"}
*
* @param object a detached instance of a persistent class
* @param replicationMode The replication mode to use
*/
void replicate(Object object, ReplicationMode replicationMode);
/**
* Persist the state of the given detached instance, reusing the current
* identifier value. This operation cascades to associated instances if
* the association is mapped with {@code cascade="replicate"}
*
* @param entityName The entity name
* @param object a detached instance of a persistent class
* @param replicationMode The replication mode to use
*/
void replicate(String entityName, Object object, ReplicationMode replicationMode) ;
/**
* Persist the given transient instance, first assigning a generated identifier. (Or
* using the current value of the identifier property if the assigned
* generator is used.) This operation cascades to associated instances if the
* association is mapped with {@code cascade="save-update"}
*
* @param object a transient instance of a persistent class
*
* @return the generated identifier
*/
Serializable save(Object object);
/**
* Persist the given transient instance, first assigning a generated identifier. (Or
* using the current value of the identifier property if the assigned
* generator is used.) This operation cascades to associated instances if the
* association is mapped with {@code cascade="save-update"}
*
* @param entityName The entity name
* @param object a transient instance of a persistent class
*
* @return the generated identifier
*/
Serializable save(String entityName, Object object);
/**
* Either {@link #save(Object)} or {@link #update(Object)} the given
* instance, depending upon resolution of the unsaved-value checks (see the
* manual for discussion of unsaved-value checking).
*
* This operation cascades to associated instances if the association is mapped
* with {@code cascade="save-update"}
*
* @param object a transient or detached instance containing new or updated state
*
* @see Session#save(java.lang.Object)
* @see Session#update(Object object)
*/
void saveOrUpdate(Object object);
/**
* Either {@link #save(String, Object)} or {@link #update(String, Object)}
* the given instance, depending upon resolution of the unsaved-value checks
* (see the manual for discussion of unsaved-value checking).
*
* This operation cascades to associated instances if the association is mapped
* with {@code cascade="save-update"}
*
* @param entityName The entity name
* @param object a transient or detached instance containing new or updated state
*
* @see Session#save(String,Object)
* @see Session#update(String,Object)
*/
void saveOrUpdate(String entityName, Object object);
/**
* Update the persistent instance with the identifier of the given detached
* instance. If there is a persistent instance with the same identifier,
* an exception is thrown. This operation cascades to associated instances
* if the association is mapped with {@code cascade="save-update"}
*
* @param object a detached instance containing updated state
*/
void update(Object object);
/**
* Update the persistent instance with the identifier of the given detached
* instance. If there is a persistent instance with the same identifier,
* an exception is thrown. This operation cascades to associated instances
* if the association is mapped with {@code cascade="save-update"}
*
* @param entityName The entity name
* @param object a detached instance containing updated state
*/
void update(String entityName, Object object);
/**
* Copy the state of the given object onto the persistent object with the same
* identifier. If there is no persistent instance currently associated with
* the session, it will be loaded. Return the persistent instance. If the
* given instance is unsaved, save a copy of and return it as a newly persistent
* instance. The given instance does not become associated with the session.
* This operation cascades to associated instances if the association is mapped
* with {@code cascade="merge"}
*
* The semantics of this method are defined by JSR-220.
*
* @param object a detached instance with state to be copied
*
* @return an updated persistent instance
*/
Object merge(Object object);
/**
* Copy the state of the given object onto the persistent object with the same
* identifier. If there is no persistent instance currently associated with
* the session, it will be loaded. Return the persistent instance. If the
* given instance is unsaved, save a copy of and return it as a newly persistent
* instance. The given instance does not become associated with the session.
* This operation cascades to associated instances if the association is mapped
* with {@code cascade="merge"}
*
* The semantics of this method are defined by JSR-220.
*
* @param entityName The entity name
* @param object a detached instance with state to be copied
*
* @return an updated persistent instance
*/
Object merge(String entityName, Object object);
/**
* Make a transient instance persistent. This operation cascades to associated
* instances if the association is mapped with {@code cascade="persist"}
*
* The semantics of this method are defined by JSR-220.
*
* @param object a transient instance to be made persistent
*/
void persist(Object object);
/**
* Make a transient instance persistent. This operation cascades to associated
* instances if the association is mapped with {@code cascade="persist"}
*
* The semantics of this method are defined by JSR-220.
*
* @param entityName The entity name
* @param object a transient instance to be made persistent
*/
void persist(String entityName, Object object);
/**
* 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 {@code cascade="delete"}
*
* @param object the instance to be removed
*/
void delete(Object object);
/**
* Remove a persistent instance from the datastore. The object 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 {@code cascade="delete"}
*
* @param entityName The entity name for the instance to be removed.
* @param object the instance to be removed
*/
void delete(String entityName, Object object);
/**
* Obtain the specified lock level upon the given object. This may be used to
* perform a version check (LockMode.READ), to upgrade to a pessimistic
* lock (LockMode.PESSIMISTIC_WRITE), or to simply reassociate a transient instance
* with a session (LockMode.NONE). This operation cascades to associated
* instances if the association is mapped with cascade="lock".
*
* Convenient form of {@link LockRequest#lock(Object)} via {@link #buildLockRequest(LockOptions)}
*
* @param object a persistent or transient instance
* @param lockMode the lock level
*
* @see #buildLockRequest(LockOptions)
* @see LockRequest#lock(Object)
*/
void lock(Object object, LockMode lockMode);
/**
* Obtain the specified lock level upon the given object. This may be used to
* perform a version check (LockMode.OPTIMISTIC), to upgrade to a pessimistic
* lock (LockMode.PESSIMISTIC_WRITE), or to simply reassociate a transient instance
* with a session (LockMode.NONE). This operation cascades to associated
* instances if the association is mapped with cascade="lock".
*
* Convenient form of {@link LockRequest#lock(String, Object)} via {@link #buildLockRequest(LockOptions)}
*
* @param entityName The name of the entity
* @param object a persistent or transient instance
* @param lockMode the lock level
*
* @see #buildLockRequest(LockOptions)
* @see LockRequest#lock(String, Object)
*/
void lock(String entityName, Object object, LockMode lockMode);
/**
* Build a LockRequest that specifies the LockMode, pessimistic lock timeout and lock scope.
* timeout and scope is ignored for optimistic locking. After building the LockRequest,
* call LockRequest.lock to perform the requested locking.
*
* Example usage:
* {@code session.buildLockRequest().setLockMode(LockMode.PESSIMISTIC_WRITE).setTimeOut(60000).lock(entity);}
*
* @param lockOptions contains the lock level
*
* @return a lockRequest that can be used to lock the passed object.
*/
LockRequest buildLockRequest(LockOptions lockOptions);
/**
* 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 upon insert or update
*
- after executing direct SQL (eg. a mass update) in the same session
*
- after inserting a Blob or Clob
*
*
* @param object a persistent or detached instance
*/
void refresh(Object object);
/**
* Re-read the state of the given instance from the underlying database. It is
* inadvisable to use this to implement long-running sessions that span many
* business tasks. This method is, however, useful in certain special circumstances.
* For example
*
* - where a database trigger alters the object state upon insert or update
*
- after executing direct SQL (eg. a mass update) in the same session
*
- after inserting a Blob or Clob
*
*
* @param entityName a persistent class
* @param object a persistent or detached instance
*/
void refresh(String entityName, Object object);
/**
* Re-read the state of the given instance from the underlying database, with
* the given LockMode. 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.
*
* Convenient form of {@link #refresh(Object, LockOptions)}
*
* @param object a persistent or detached instance
* @param lockMode the lock mode to use
*
* @see #refresh(Object, LockOptions)
*/
void refresh(Object object, LockMode lockMode);
/**
* Re-read the state of the given instance from the underlying database, with
* the given LockMode. 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.
*
* @param object a persistent or detached instance
* @param lockOptions contains the lock mode to use
*/
void refresh(Object object, LockOptions lockOptions);
/**
* Re-read the state of the given instance from the underlying database, with
* the given LockMode. 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.
*
* @param entityName a persistent class
* @param object a persistent or detached instance
* @param lockOptions contains the lock mode to use
*/
void refresh(String entityName, Object object, LockOptions lockOptions);
/**
* Determine the current lock mode of the given object.
*
* @param object a persistent instance
*
* @return the current lock mode
*/
LockMode getCurrentLockMode(Object object);
/**
* Create a {@link Query} instance for the given collection and filter string. Contains an implicit {@code FROM}
* element named {@code this} which refers to the defined table for the collection elements, as well as an implicit
* {@code WHERE} restriction for this particular collection instance's key value.
*
* @param collection a persistent collection
* @param queryString a Hibernate query fragment.
*
* @return The query instance for manipulation and execution
*
* @deprecated (since 5.3) with no real replacement.
*/
@Deprecated
org.hibernate.Query createFilter(Object collection, String queryString);
/**
* Completely clear the session. Evict all loaded instances and cancel all pending
* saves, updates and deletions. Do not close open iterators or instances of
* ScrollableResults.
*/
void clear();
/**
* Return the persistent instance of the given entity class with the given identifier,
* or null if there is no such persistent instance. (If the instance is already associated
* with the session, return that instance. This method never returns an uninitialized instance.)
*
* @param entityType The entity type
* @param id an identifier
*
* @return a persistent instance or null
*/
T get(Class entityType, Serializable id);
/**
* Return the persistent instance of the given entity class with the given identifier,
* or null if there is no such persistent instance. (If the instance is already associated
* with the session, return that instance. This method never returns an uninitialized instance.)
* Obtain the specified lock mode if the instance exists.
*
* Convenient form of {@link #get(Class, Serializable, LockOptions)}
*
* @param entityType The entity type
* @param id an identifier
* @param lockMode the lock mode
*
* @return a persistent instance or null
*
* @see #get(Class, Serializable, LockOptions)
*/
T get(Class entityType, Serializable id, LockMode lockMode);
/**
* Return the persistent instance of the given entity class with the given identifier,
* or null if there is no such persistent instance. (If the instance is already associated
* with the session, return that instance. This method never returns an uninitialized instance.)
* Obtain the specified lock mode if the instance exists.
*
* @param entityType The entity type
* @param id an identifier
* @param lockOptions the lock mode
*
* @return a persistent instance or null
*/
T get(Class entityType, Serializable id, LockOptions lockOptions);
/**
* Return the persistent instance of the given named entity with the given identifier,
* or null if there is no such persistent instance. (If the instance is already associated
* with the session, return that instance. This method never returns an uninitialized instance.)
*
* @param entityName the entity name
* @param id an identifier
*
* @return a persistent instance or null
*/
Object get(String entityName, Serializable id);
/**
* Return the persistent instance of the given entity class with the given identifier,
* or null if there is no such persistent instance. (If the instance is already associated
* with the session, return that instance. This method never returns an uninitialized instance.)
* Obtain the specified lock mode if the instance exists.
*
* Convenient form of {@link #get(String, Serializable, LockOptions)}
*
* @param entityName the entity name
* @param id an identifier
* @param lockMode the lock mode
*
* @return a persistent instance or null
*
* @see #get(String, Serializable, LockOptions)
*/
Object get(String entityName, Serializable id, LockMode lockMode);
/**
* Return the persistent instance of the given entity class with the given identifier,
* or null if there is no such persistent instance. (If the instance is already associated
* with the session, return that instance. This method never returns an uninitialized instance.)
* Obtain the specified lock mode if the instance exists.
*
* @param entityName the entity name
* @param id an identifier
* @param lockOptions contains the lock mode
*
* @return a persistent instance or null
*/
Object get(String entityName, Serializable id, LockOptions lockOptions);
/**
* Return the entity name for a persistent entity.
*
* @param object a persistent entity
*
* @return the entity name
*/
String getEntityName(Object object);
/**
* Create an {@link IdentifierLoadAccess} instance to retrieve the specified entity type by
* primary key.
*
* @param entityName The entity name of the entity type to be retrieved
*
* @return load delegate for loading the specified entity type by primary key
*
* @throws HibernateException If the specified entity name cannot be resolved as an entity name
*/
IdentifierLoadAccess byId(String entityName);
/**
* Create a {@link MultiIdentifierLoadAccess} instance to retrieve multiple entities at once
* as specified by primary key values.
*
* @param entityClass The entity type to be retrieved
*
* @return load delegate for loading the specified entity type by primary key values
*
* @throws HibernateException If the specified Class cannot be resolved as a mapped entity
*/
MultiIdentifierLoadAccess byMultipleIds(Class entityClass);
/**
* Create a {@link MultiIdentifierLoadAccess} instance to retrieve multiple entities at once
* as specified by primary key values.
*
* @param entityName The entity name of the entity type to be retrieved
*
* @return load delegate for loading the specified entity type by primary key values
*
* @throws HibernateException If the specified entity name cannot be resolved as an entity name
*/
MultiIdentifierLoadAccess byMultipleIds(String entityName);
/**
* Create an {@link IdentifierLoadAccess} instance to retrieve the specified entity by
* primary key.
*
* @param entityClass The entity type to be retrieved
*
* @return load delegate for loading the specified entity type by primary key
*
* @throws HibernateException If the specified Class cannot be resolved as a mapped entity
*/
IdentifierLoadAccess byId(Class entityClass);
/**
* Create a {@link NaturalIdLoadAccess} instance to retrieve the specified entity by
* its natural id.
*
* @param entityName The entity name of the entity type to be retrieved
*
* @return load delegate for loading the specified entity type by natural id
*
* @throws HibernateException If the specified entity name cannot be resolved as an entity name
*/
NaturalIdLoadAccess byNaturalId(String entityName);
/**
* Create a {@link NaturalIdLoadAccess} instance to retrieve the specified entity by
* its natural id.
*
* @param entityClass The entity type to be retrieved
*
* @return load delegate for loading the specified entity type by natural id
*
* @throws HibernateException If the specified Class cannot be resolved as a mapped entity
*/
NaturalIdLoadAccess byNaturalId(Class entityClass);
/**
* Create a {@link SimpleNaturalIdLoadAccess} instance to retrieve the specified entity by
* its natural id.
*
* @param entityName The entity name of the entity type to be retrieved
*
* @return load delegate for loading the specified entity type by natural id
*
* @throws HibernateException If the specified entityClass cannot be resolved as a mapped entity, or if the
* entity does not define a natural-id or if its natural-id is made up of multiple attributes.
*/
SimpleNaturalIdLoadAccess bySimpleNaturalId(String entityName);
/**
* Create a {@link SimpleNaturalIdLoadAccess} instance to retrieve the specified entity by
* its simple (single attribute) natural id.
*
* @param entityClass The entity type to be retrieved
*
* @return load delegate for loading the specified entity type by natural id
*
* @throws HibernateException If the specified entityClass cannot be resolved as a mapped entity, or if the
* entity does not define a natural-id or if its natural-id is made up of multiple attributes.
*/
SimpleNaturalIdLoadAccess bySimpleNaturalId(Class entityClass);
/**
* Enable the named filter for this current session.
*
* @param filterName The name of the filter to be enabled.
*
* @return The Filter instance representing the enabled filter.
*/
Filter enableFilter(String filterName);
/**
* Retrieve a currently enabled filter by name.
*
* @param filterName The name of the filter to be retrieved.
*
* @return The Filter instance representing the enabled filter.
*/
Filter getEnabledFilter(String filterName);
/**
* Disable the named filter for the current session.
*
* @param filterName The name of the filter to be disabled.
*/
void disableFilter(String filterName);
/**
* Get the statistics for this session.
*
* @return The session statistics being collected for this session
*/
SessionStatistics getStatistics();
/**
* Is the specified entity or proxy read-only?
*
* To get the default read-only/modifiable setting used for
* entities and proxies that are loaded into the session:
* @see org.hibernate.Session#isDefaultReadOnly()
*
* @param entityOrProxy an entity or HibernateProxy
* @return {@code true} if the entity or proxy is read-only, {@code false} if the entity or proxy is modifiable.
*/
boolean isReadOnly(Object entityOrProxy);
/**
* Set an unmodified persistent object to read-only mode, or a read-only
* object to modifiable mode. In read-only mode, no snapshot is maintained,
* the instance is never dirty checked, and changes are not persisted.
*
* If the entity or proxy already has the specified read-only/modifiable
* setting, then this method does nothing.
*
* To set the default read-only/modifiable setting used for
* entities and proxies that are loaded into the session:
* @see org.hibernate.Session#setDefaultReadOnly(boolean)
*
* To override this session's read-only/modifiable setting for entities
* and proxies loaded by a Query:
* @see Query#setReadOnly(boolean)
*
* @param entityOrProxy an entity or HibernateProxy
* @param readOnly {@code true} if the entity or proxy should be made read-only; {@code false} if the entity or
* proxy should be made modifiable
*/
void setReadOnly(Object entityOrProxy, boolean readOnly);
@Override
RootGraph createEntityGraph(Class rootType);
@Override
RootGraph createEntityGraph(String graphName);
@Override
RootGraph getEntityGraph(String graphName);
@Override
@SuppressWarnings({"unchecked", "RedundantCast"})
default List> getEntityGraphs(Class entityClass) {
return (List) getSessionFactory().findEntityGraphsByType( entityClass );
}
/**
* Disconnect the session from its underlying JDBC connection. This is intended for use in cases where the
* application has supplied the JDBC connection to the session and which require long-sessions (aka, conversations).
*
* It is considered an error to call this method on a session which was not opened by supplying the JDBC connection
* and an exception will be thrown.
*
* For non-user-supplied scenarios, normal transaction management already handles disconnection and reconnection
* automatically.
*
* @return the application-supplied connection or {@code null}
*
* @see #reconnect(Connection)
*/
Connection disconnect();
/**
* Reconnect to the given JDBC connection.
*
* @param connection a JDBC connection
*
* @see #disconnect()
*/
void reconnect(Connection connection);
/**
* Is a particular fetch profile enabled on this session?
*
* @param name The name of the profile to be checked.
* @return True if fetch profile is enabled; false if not.
* @throws UnknownProfileException Indicates that the given name does not
* match any known profile names
*
* @see org.hibernate.engine.profile.FetchProfile for discussion of this feature
*/
boolean isFetchProfileEnabled(String name) throws UnknownProfileException;
/**
* Enable a particular fetch profile on this session. No-op if requested
* profile is already enabled.
*
* @param 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 org.hibernate.engine.profile.FetchProfile for discussion of this feature
*/
void enableFetchProfile(String name) throws UnknownProfileException;
/**
* Disable a particular fetch profile on this session. No-op if requested
* profile is already disabled.
*
* @param 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 org.hibernate.engine.profile.FetchProfile for discussion of this feature
*/
void disableFetchProfile(String name) throws UnknownProfileException;
/**
* Convenience access to the {@link TypeHelper} associated with this session's {@link SessionFactory}.
*
* Equivalent to calling {@link #getSessionFactory()}.{@link SessionFactory#getTypeHelper getTypeHelper()}
*
* @return The {@link TypeHelper} associated with this session's {@link SessionFactory}
*/
TypeHelper getTypeHelper();
/**
* Retrieve this session's helper/delegate for creating LOB instances.
*
* @return This session's LOB helper
*/
LobHelper getLobHelper();
/**
* Contains locking details (LockMode, Timeout and Scope).
*/
interface LockRequest {
/**
* Constant usable as a time out value that indicates no wait semantics should be used in
* attempting to acquire locks.
*/
int PESSIMISTIC_NO_WAIT = 0;
/**
* Constant usable as a time out value that indicates that attempting to acquire locks should be allowed to
* wait forever (apply no timeout).
*/
int PESSIMISTIC_WAIT_FOREVER = -1;
/**
* Get the lock mode.
*
* @return the lock mode.
*/
LockMode getLockMode();
/**
* Specify the LockMode to be used. The default is LockMode.none.
*
* @param lockMode The lock mode to use for this request
*
* @return this LockRequest instance for operation chaining.
*/
LockRequest setLockMode(LockMode lockMode);
/**
* Get the timeout setting.
*
* @return timeout in milliseconds, -1 for indefinite wait and 0 for no wait.
*/
int getTimeOut();
/**
* Specify the pessimistic lock timeout (check if your dialect supports this option).
* The default pessimistic lock behavior is to wait forever for the lock.
*
* @param timeout is time in milliseconds to wait for lock. -1 means wait forever and 0 means no wait.
*
* @return this LockRequest instance for operation chaining.
*/
LockRequest setTimeOut(int timeout);
/**
* Check if locking is cascaded to owned collections and relationships.
*
* @return true if locking will be extended to owned collections and relationships.
*/
boolean getScope();
/**
* Specify if LockMode should be cascaded to owned collections and relationships.
* The association must be mapped with {@code cascade="lock"} for scope=true to work.
*
* @param scope {@code true} to cascade locks; {@code false} to not.
*
* @return {@code this}, for method chaining
*/
LockRequest setScope(boolean scope);
/**
* Perform the requested locking.
*
* @param entityName The name of the entity to lock
* @param object The instance of the entity to lock
*/
void lock(String entityName, Object object);
/**
* Perform the requested locking.
*
* @param object The instance of the entity to lock
*/
void lock(Object object);
}
/**
* Add one or more listeners to the Session
*
* @param listeners The listener(s) to add
*/
void addEventListeners(SessionEventListener... listeners);
@Override
org.hibernate.query.Query createQuery(String queryString, Class resultType);
// Override the JPA return type with the one exposed in QueryProducer
@Override
org.hibernate.query.Query createQuery(CriteriaQuery criteriaQuery);
// Override the JPA return type with the one exposed in QueryProducer
@Override
org.hibernate.query.Query createQuery(CriteriaUpdate updateQuery);
// Override the JPA return type with the one exposed in QueryProducer
@Override
org.hibernate.query.Query createQuery(CriteriaDelete deleteQuery);
org.hibernate.query.Query createNamedQuery(String name, Class resultType);
@Override
NativeQuery createSQLQuery(String queryString);
}