improvements to javadoc for StatelessSession, Session, and overview page
This commit is contained in:
Gavin King
parent
c7b42097aa
commit
4a2792bed8
|
|
@ -25,16 +25,19 @@ import jakarta.persistence.criteria.CriteriaUpdate;
|
|||
* with a logical transaction.
|
||||
* <p>
|
||||
* The lifecycle of a {@code Session} is bounded by the beginning and end of the logical
|
||||
* transaction. (But a long logical transaction might span several database transactions.)
|
||||
* transaction. But a long logical transaction might span several database transactions.
|
||||
* <p>
|
||||
* The primary purpose of the {@code Session} is to offer create, read, and delete
|
||||
* operations for instances of mapped entity classes. An instance may be in one of three
|
||||
* states with respect to a given session:
|
||||
* states with respect to a given open session:
|
||||
* <ul>
|
||||
* <li><em>transient:</em> never persistent, not associated with any {@code Session},
|
||||
* <li><em>persistent:</em> associated with a unique {@code Session}, or
|
||||
* <li><em>detached:</em> previously persistent, not associated with any {@code Session}
|
||||
* <li><em>transient:</em> never persistent, and not associated with the {@code Session},
|
||||
* <li><em>persistent:</em> currently associated with the {@code Session}, or
|
||||
* <li><em>detached:</em> previously persistent, but not currently associated with the
|
||||
* {@code Session}.
|
||||
* </ul>
|
||||
* At any given time, an instance may be associated with at most one open session.
|
||||
* <p>
|
||||
* Any instance returned by {@link #get(Class, Object)} or by a query is persistent.
|
||||
* <p>
|
||||
* A transient instance may be made persistent by calling {@link #persist(Object)}.
|
||||
|
|
|
|||
|
|
@ -7,18 +7,37 @@
|
|||
package org.hibernate;
|
||||
|
||||
/**
|
||||
* A command-oriented API for performing bulk operations against a database.
|
||||
* 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.
|
||||
* <p>
|
||||
* A stateless session does not implement a first-level cache nor interact
|
||||
* with any second-level cache, nor does it implement transactional
|
||||
* write-behind or automatic dirty checking, nor do operations cascade to
|
||||
* associated instances. Collections are ignored by a stateless session.
|
||||
* Operations performed via a stateless session bypass Hibernate's event model
|
||||
* and interceptors. Stateless sessions are vulnerable to data aliasing
|
||||
* effects, due to the lack of a first-level cache.
|
||||
* Viewed in opposition to to {@link Session}, the {@code 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.
|
||||
* <p>
|
||||
* For certain kinds of transactions, a stateless session may perform slightly
|
||||
* faster than a stateful session.
|
||||
* A stateless session comes some with designed-in limitations:
|
||||
* <ul>
|
||||
* <li>it does not have a first-level cache,
|
||||
* <li>nor interact with any second-level cache,
|
||||
* <li>nor does it implement transactional write-behind or automatic dirty
|
||||
* checking, and
|
||||
* <li>nor do operations cascade to associated instances.
|
||||
* </ul>
|
||||
* Furthermore:
|
||||
* <ul>
|
||||
* <li>collections are completely ignored by a stateless session, and
|
||||
* <li>operations performed via a stateless session bypass Hibernate's event
|
||||
* model, lifecycle callbacks, and interceptors.
|
||||
* </ul>
|
||||
* Stateless sessions are vulnerable to data aliasing effects, due to the
|
||||
* lack of a first-level cache.
|
||||
* <p>
|
||||
* On the other hand, for certain kinds of transactions, a stateless session
|
||||
* may perform slightly faster than a stateful session.
|
||||
*
|
||||
* @author Gavin King
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -8,26 +8,29 @@
|
|||
|
||||
<h2>Hibernate ORM Aggregated Javadoc</h2>
|
||||
|
||||
Hibernate provides:<ul>
|
||||
Hibernate is a library for object/relation mapping (ORM). It provides:<ul>
|
||||
<li>
|
||||
a <em>native API</em> centered around {@link org.hibernate.SessionFactory} and
|
||||
{@link org.hibernate.Session},
|
||||
</li>
|
||||
<li>
|
||||
an implementation of the <em>Java (or Jakarta) Persistence API</em> (JPA), and
|
||||
an implementation of the <em>Java (or Jakarta) Persistence API</em> (JPA),
|
||||
where the equivalent central interfaces are {@link jakarta.persistence.EntityManagerFactory}
|
||||
and {@link jakarta.persistence.EntityManager}, and
|
||||
</li>
|
||||
<li>
|
||||
a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined by JPA,
|
||||
and which may be used with either API.
|
||||
a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined
|
||||
by JPA, and which may be used with either API.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h3>Native API</h3>
|
||||
|
||||
Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications using
|
||||
the native API will often make use of the following interfaces:<ul>
|
||||
Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications
|
||||
using the native API will often make use of the following interfaces:<ul>
|
||||
<li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
|
||||
<li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
|
||||
<li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
|
||||
<li>{@link org.hibernate.Transaction} to control local transactions, and</li>
|
||||
<li>{@link org.hibernate.query.Query} to execute HQL queries.</li>
|
||||
</ul>
|
||||
|
|
@ -35,31 +38,41 @@ the native API will often make use of the following interfaces:<ul>
|
|||
<h3>JPA</h3>
|
||||
|
||||
The JPA interfaces are defined by the JPA specification. For details see the latest
|
||||
<a href="https://jakarta.ee/specifications/persistence/">specification</a> along with
|
||||
{@link jakarta.persistence}.
|
||||
<a href="https://jakarta.ee/specifications/persistence/">specification</a> along with the
|
||||
<a href="https://jakarta.ee/specifications/persistence/2.2/apidocs/">API documentation</a>
|
||||
for the package {@link jakarta.persistence}.
|
||||
|
||||
<p>Note that since Hibernate 5.2, the native API extends the JPA API rather than wrapping it
|
||||
(for example,<code>SessionFactory</code> extends <code>EntityManagerFactory</code>).</p>
|
||||
|
||||
<h3>Mapping annotations</h3>
|
||||
|
||||
See {@link org.hibernate.annotations}.
|
||||
The mapping annotations defined by the JPA specification provide a foundation for expressing
|
||||
object/relational mappings in Hibernate and other JPA implementations.
|
||||
|
||||
The annotations in the package {@link org.hibernate.annotations} extend this foundation and
|
||||
accommodate more specialized requirements. These annotation are not tied to the native API,
|
||||
and may be used in conjunction with the JPA API.
|
||||
|
||||
The full power of Hibernate can only be unlocked via judicious use of these extra annotations.
|
||||
|
||||
<h3>Note about package categories</h3>
|
||||
|
||||
Hibernate categorizes packages into a number of groups based on intended consumers:<ul>
|
||||
<li>
|
||||
<strong>API</strong> - classes to which application code will generally bind directly. These
|
||||
are generally classes which do not have "spi" nor "internal" in their package path and are
|
||||
not under the "org.hibernate.testing" package
|
||||
<strong>API</strong> - classes to which application code will generally bind directly.
|
||||
These are generally classes which do not have <code>spi</code> nor <code>internal</code>
|
||||
in their package path and are not under the package <code>org.hibernate.testing</code>.
|
||||
</li>
|
||||
<li>
|
||||
<strong>SPI</strong> - classes to which integrator developers will commonly bind directly in
|
||||
order to develop extensions to Hibernate, or to alter its behavior in some way. These are
|
||||
generally under packages with "spi" in the package path.
|
||||
<strong>SPI</strong> - classes to which integrator developers will commonly bind directly
|
||||
in order to develop extensions to Hibernate, or to alter its behavior in some way. These
|
||||
are generally under packages with <code>spi</code> in the package path.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Testing Support</strong> - classes from the hibernate-testing artifact used in building
|
||||
Hibernate test cases. These are classes under the "org.hibernate.testing" package
|
||||
<strong>Testing Support</strong> - classes from the <code>hibernate-testing</code>
|
||||
artifact used in building Hibernate test cases. These are classes under the package
|
||||
<code>org.hibernate.testing</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<p></p>
|
||||
|
|
|
|||
Loading…
Reference in New Issue