improvements to javadoc for StatelessSession, Session, and overview page
This commit is contained in:
parent
c7b42097aa
commit
4a2792bed8
|
@ -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)}.
|
||||||
|
|
|
@ -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
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -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>
|
||||||
|
|
Loading…
Reference in New Issue