explain what a second-level cache is in Javadoc

hibernate-core/src/main/java/org/hibernate/Cache.java

@@ -9,7 +9,22 @@
 /**
  * An API for directly querying and managing the second level cache.
  * <p>
- * Note that only entities and collection roles explicitly annotated
+ * Hibernate has two levels of caching:
+ * <ul>
+ * <li>The <em>first-level cache</em> is better known as the persistence context.
+ *     It's the collection of managed entity instances associated with an open
+ *     {@link Session}.
+ * <li>The <em>second-level cache</em> is shared between all sessions belonging to
+ *     a given {@link SessionFactory}. It stores the state of an entity instance
+ *     in a destructured format, as a tuple of persistent attribute values.
+ * </ul>
+ * By nature, a second-level cache tends to undermine the ACID properties of
+ * transaction processing in a relation database. A second-level cache is often by
+ * far the easiest way to improve the performance of a system, but only at the cost
+ * of making it much more difficult to reason about concurrency. And so the cache
+ * is a potential source of bugs which are difficult to isolate and reproduce.
+ * <p>
+ * Therefore, only entities and collection roles explicitly annotated
  * {@link jakarta.persistence.Cacheable} or {@link org.hibernate.annotations.Cache}
  * are eligible for storage in the second-level cache, and so by default the state
  * of an entity is always retrieved from the database when requested.

hibernate-core/src/main/java/org/hibernate/SessionFactory.java

@@ -46,6 +46,12 @@
  * fixed as soon as the {@code SessionFactory} is created. Of course, any
  * {@code SessionFactory} is threadsafe.
  * <p>
+ * An exception to this rule is the {@link Cache second-level cache}. Each
+ * {@code SessionFactory} has its own isolated second-level cache, shared
+ * between the sessions it creates, and it {@link #getCache() exposes the cache}
+ * to clients as a stateful object with entries that may be queried and managed
+ * directly.
+ * <p>
  * Every {@code SessionFactory} is a JPA {@link EntityManagerFactory}.
  * Furthermore, when Hibernate is acting as the JPA persistence provider, the
  * method {@link EntityManagerFactory#unwrap(Class)} may be used to obtain the

hibernate-core/src/main/java/org/hibernate/StatelessSession.java

@@ -13,8 +13,8 @@
  * interface is called, any necessary interaction with the database happens
  * immediately and synchronously.
  * <p>
- * Viewed in opposition to to {@link Session}, the {@code StatelessSession}
- * is a whole competing programming model, one preferred by some developers
+ * Viewed in opposition 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.