improvements to javadoc for StatelessSession, Session, and overview page

This commit is contained in:
Gavin King 2022-11-05 12:21:51 +01:00
parent c7b42097aa
commit 4a2792bed8
3 changed files with 67 additions and 32 deletions

View File

@ -25,16 +25,19 @@ import jakarta.persistence.criteria.CriteriaUpdate;
* with a logical transaction. * with a logical transaction.
* <p> * <p>
* The lifecycle of a {@code Session} is bounded by the beginning and end of the logical * 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> * <p>
* The primary purpose of the {@code Session} is to offer create, read, and delete * 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 * 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> * <ul>
* <li><em>transient:</em> never persistent, not associated with any {@code Session}, * <li><em>transient:</em> never persistent, and not associated with the {@code Session},
* <li><em>persistent:</em> associated with a unique {@code Session}, or * <li><em>persistent:</em> currently associated with the {@code Session}, or
* <li><em>detached:</em> previously persistent, not associated with any {@code Session} * <li><em>detached:</em> previously persistent, but not currently associated with the
* {@code Session}.
* </ul> * </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. * Any instance returned by {@link #get(Class, Object)} or by a query is persistent.
* <p> * <p>
* A transient instance may be made persistent by calling {@link #persist(Object)}. * A transient instance may be made persistent by calling {@link #persist(Object)}.

View File

@ -7,18 +7,37 @@
package org.hibernate; 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> * <p>
* A stateless session does not implement a first-level cache nor interact * Viewed in opposition to to {@link Session}, the {@code StatelessSession}
* with any second-level cache, nor does it implement transactional * is a whole competing programming model, one preferred by some developers
* write-behind or automatic dirty checking, nor do operations cascade to * for its simplicity and somewhat lower level of abstraction. But the two
* associated instances. Collections are ignored by a stateless session. * kinds of session are not enemies, and may comfortably coexist in a single
* Operations performed via a stateless session bypass Hibernate's event model * program.
* and interceptors. Stateless sessions are vulnerable to data aliasing
* effects, due to the lack of a first-level cache.
* <p> * <p>
* For certain kinds of transactions, a stateless session may perform slightly * A stateless session comes some with designed-in limitations:
* faster than a stateful session. * <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 * @author Gavin King
*/ */

View File

@ -8,26 +8,29 @@
<h2>Hibernate ORM Aggregated Javadoc</h2> <h2>Hibernate ORM Aggregated Javadoc</h2>
Hibernate provides:<ul> Hibernate is a library for object/relation mapping (ORM). It provides:<ul>
<li> <li>
a <em>native API</em> centered around {@link org.hibernate.SessionFactory} and a <em>native API</em> centered around {@link org.hibernate.SessionFactory} and
{@link org.hibernate.Session}, {@link org.hibernate.Session},
</li> </li>
<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>
<li> <li>
a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined by JPA, a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined
and which may be used with either API. by JPA, and which may be used with either API.
</li> </li>
</ul> </ul>
<h3>Native API</h3> <h3>Native API</h3>
Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications using Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications
the native API will often make use of the following interfaces:<ul> 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.cfg.Configuration} to configure and bootstrap Hibernate,</li>
<li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</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.Transaction} to control local transactions, and</li>
<li>{@link org.hibernate.query.Query} to execute HQL queries.</li> <li>{@link org.hibernate.query.Query} to execute HQL queries.</li>
</ul> </ul>
@ -35,31 +38,41 @@ the native API will often make use of the following interfaces:<ul>
<h3>JPA</h3> <h3>JPA</h3>
The JPA interfaces are defined by the JPA specification. For details see the latest 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 <a href="https://jakarta.ee/specifications/persistence/">specification</a> along with the
{@link jakarta.persistence}. <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 <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> (for example,<code>SessionFactory</code> extends <code>EntityManagerFactory</code>).</p>
<h3>Mapping annotations</h3> <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> <h3>Note about package categories</h3>
Hibernate categorizes packages into a number of groups based on intended consumers:<ul> Hibernate categorizes packages into a number of groups based on intended consumers:<ul>
<li> <li>
<strong>API</strong> - classes to which application code will generally bind directly. These <strong>API</strong> - classes to which application code will generally bind directly.
are generally classes which do not have "spi" nor "internal" in their package path and are These are generally classes which do not have <code>spi</code> nor <code>internal</code>
not under the "org.hibernate.testing" package in their package path and are not under the package <code>org.hibernate.testing</code>.
</li> </li>
<li> <li>
<strong>SPI</strong> - classes to which integrator developers will commonly bind directly in <strong>SPI</strong> - classes to which integrator developers will commonly bind directly
order to develop extensions to Hibernate, or to alter its behavior in some way. These are in order to develop extensions to Hibernate, or to alter its behavior in some way. These
generally under packages with "spi" in the package path. are generally under packages with <code>spi</code> in the package path.
</li> </li>
<li> <li>
<strong>Testing Support</strong> - classes from the hibernate-testing artifact used in building <strong>Testing Support</strong> - classes from the <code>hibernate-testing</code>
Hibernate test cases. These are classes under the "org.hibernate.testing" package artifact used in building Hibernate test cases. These are classes under the package
<code>org.hibernate.testing</code>.
</li> </li>
</ul> </ul>
<p></p> <p></p>