yet more work on the API documentation

- and get rid of people's email addresses, they don't belong in the code
This commit is contained in:
Gavin 2022-12-29 11:39:20 +01:00 committed by Gavin King
parent 5246ec508c
commit c6f0be990c
225 changed files with 1068 additions and 578 deletions

View File

@ -13,9 +13,6 @@ apply from: rootProject.file( 'gradle/base-information.gradle' )
javadoc { javadoc {
exclude( "**/internal/*" ) exclude( "**/internal/*" )
exclude( "**/generated-src/**" ) exclude( "**/generated-src/**" )
exclude( "**/sqm/tree/*" )
exclude( "**/ast/tree/*" )
exclude( "**/sql/results/*" )
final int currentYear = new GregorianCalendar().get( Calendar.YEAR ) final int currentYear = new GregorianCalendar().get( Calendar.YEAR )

View File

@ -54,7 +54,7 @@ import static org.hibernate.type.SqlTypes.VARCHAR;
/** /**
* A dialect for Mimer SQL 11. * A dialect for Mimer SQL 11.
* *
* @author <a href="mailto:fredrik.alund@mimer.se">Fredrik lund</a> * @author Fredrik lund
* @author Gavin King * @author Gavin King
*/ */
public class MimerSQLDialect extends Dialect { public class MimerSQLDialect extends Dialect {

View File

@ -14,7 +14,7 @@ import java.util.StringTokenizer;
import jakarta.persistence.Index; import jakarta.persistence.Index;
/** /**
* @author <a href="mailto:stliu@hibernate.org">Strong Liu</a> * @author Strong Liu
*/ */
public class JPAIndexHolder { public class JPAIndexHolder {
private final String name; private final String name;

View File

@ -28,7 +28,7 @@ import jakarta.persistence.NamedQuery;
import jakarta.persistence.QueryHint; import jakarta.persistence.QueryHint;
/** /**
* @author <a href="mailto:stliu@hibernate.org">Strong Liu</a> * @author Strong Liu
*/ */
public class QueryHintDefinition { public class QueryHintDefinition {
private final String queryName; private final String queryName;

View File

@ -65,7 +65,7 @@ import org.hibernate.sql.results.graph.entity.EntityValuedFetchable;
import org.hibernate.type.BasicType; import org.hibernate.type.BasicType;
/** /**
* Boot-time descriptor of a result-set mapping as defined in an `hbm.xml` file * Boot-time descriptor of a result set mapping as defined in an {@code hbm.xml} file
* either implicitly or explicitly * either implicitly or explicitly
* *
* @author Steve Ebersole * @author Steve Ebersole

View File

@ -13,7 +13,7 @@ import org.hibernate.engine.spi.CompositeOwner;
/** /**
* small low memory class to keep references to composite owners * small low memory class to keep references to composite owners
* *
* @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a> * @author Ståle W. Pedersen
*/ */
public final class CompositeOwnerTracker { public final class CompositeOwnerTracker {

View File

@ -9,7 +9,7 @@ package org.hibernate.bytecode.enhance.internal.tracker;
/** /**
* Interface to be implemented by dirty trackers, a simplified Set of String. * Interface to be implemented by dirty trackers, a simplified Set of String.
* *
* @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a> * @author Luis Barreiro
*/ */
public interface DirtyTracker { public interface DirtyTracker {

View File

@ -11,7 +11,7 @@ import org.hibernate.bytecode.enhance.spi.CollectionTracker;
/** /**
* small low memory class to keep track of the number of elements in a collection * small low memory class to keep track of the number of elements in a collection
* *
* @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a> * @author Ståle W. Pedersen
*/ */
public final class NoopCollectionTracker implements CollectionTracker { public final class NoopCollectionTracker implements CollectionTracker {

View File

@ -14,7 +14,7 @@ import org.hibernate.internal.util.collections.ArrayHelper;
/** /**
* small low memory class to keep track of the number of elements in a collection * small low memory class to keep track of the number of elements in a collection
* *
* @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a> * @author Ståle W. Pedersen
*/ */
public final class SimpleCollectionTracker implements CollectionTracker { public final class SimpleCollectionTracker implements CollectionTracker {

View File

@ -16,7 +16,7 @@ import org.hibernate.internal.util.collections.ArrayHelper;
* uses an array as a set (under the assumption that the number of elements will be low) to avoid having to instantiate an HashSet. * uses an array as a set (under the assumption that the number of elements will be low) to avoid having to instantiate an HashSet.
* if the assumption does not, hold the array can be kept ordered to reduce the cost of verifying duplicates * if the assumption does not, hold the array can be kept ordered to reduce the cost of verifying duplicates
* *
* @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a> * @author Luis Barreiro
*/ */
public final class SimpleFieldTracker implements DirtyTracker { public final class SimpleFieldTracker implements DirtyTracker {

View File

@ -13,7 +13,7 @@ import org.hibernate.internal.util.collections.ArrayHelper;
* *
* similar to BasicTracker but where the array is kept ordered to reduce the cost of verifying duplicates * similar to BasicTracker but where the array is kept ordered to reduce the cost of verifying duplicates
* *
* @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a> * @author Luis Barreiro
*/ */
public final class SortedFieldTracker implements DirtyTracker { public final class SortedFieldTracker implements DirtyTracker {

View File

@ -9,7 +9,7 @@ package org.hibernate.bytecode.enhance.spi;
/** /**
* Interface to be implemented by collection trackers that hold the expected size od collections, a simplified {@code Map<String, int>}. * Interface to be implemented by collection trackers that hold the expected size od collections, a simplified {@code Map<String, int>}.
* *
* @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a> * @author Luis Barreiro
*/ */
public interface CollectionTracker { public interface CollectionTracker {

View File

@ -19,7 +19,7 @@ import jakarta.persistence.Transient;
/** /**
* default implementation of EnhancementContext. May be sub-classed as needed. * default implementation of EnhancementContext. May be sub-classed as needed.
* *
* @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a> * @author Luis Barreiro
*/ */
public class DefaultEnhancementContext implements EnhancementContext { public class DefaultEnhancementContext implements EnhancementContext {

View File

@ -6,6 +6,6 @@
*/ */
/** /**
* interceptor implementations * Support for bytecode interceptor implementations.
*/ */
package org.hibernate.bytecode.enhance.spi.interceptor; package org.hibernate.bytecode.enhance.spi.interceptor;

View File

@ -6,6 +6,6 @@
*/ */
/** /**
* package defining bytecode code enhancement (instrumentation) support. * Package defining bytecode code enhancement (instrumentation) support.
*/ */
package org.hibernate.bytecode.enhance.spi; package org.hibernate.bytecode.enhance.spi;

View File

@ -11,22 +11,25 @@ import java.security.ProtectionDomain;
import jakarta.persistence.spi.TransformerException; import jakarta.persistence.spi.TransformerException;
/** /**
* A persistence provider provides an instance of this interface * A persistence provider provides an instance of this interface to the
* to the PersistenceUnitInfo.addTransformer method. * {@link jakarta.persistence.spi.PersistenceUnitInfo#addTransformer} method.
* The supplied transformer instance will get called to transform * The supplied transformer instance will get called to transform entity class
* entity class files when they are loaded and redefined. The transformation * files when they are loaded and redefined. The transformation occurs before
* occurs before the class is defined by the JVM * the class is defined by the JVM.
* *
* @author <a href="mailto:bill@jboss.org">Bill Burke</a> * @author Bill Burke
* @author Emmanuel Bernard * @author Emmanuel Bernard
*/ */
public interface ClassTransformer extends jakarta.persistence.spi.ClassTransformer { public interface ClassTransformer extends jakarta.persistence.spi.ClassTransformer {
/** /**
* Invoked when a class is being loaded or redefined to add hooks for persistence bytecode manipulation. * Invoked when a class is being loaded or redefined to add hooks for persistence
* bytecode manipulation.
* *
* @param loader the defining class loader of the class being transformed. It may be null if using bootstrap loader * @param loader The defining class loader of the class being transformed.
* It may be null if using bootstrap loader
* @param className The name of the class being transformed * @param className The name of the class being transformed
* @param classBeingRedefined If an already loaded class is being redefined, then pass this as a parameter * @param classBeingRedefined If an already loaded class is being redefined,
* then pass this as a parameter
* @param protectionDomain ProtectionDomain of the class being (re)-defined * @param protectionDomain ProtectionDomain of the class being (re)-defined
* @param classfileBuffer The input byte buffer in class file format * @param classfileBuffer The input byte buffer in class file format
* @return A well-formed class file that can be loaded * @return A well-formed class file that can be loaded

View File

@ -6,6 +6,6 @@
*/ */
/** /**
* Internal implementations and support for persistent collections * Internal implementations and support for persistent collections.
*/ */
package org.hibernate.collection.internal; package org.hibernate.collection.internal;

View File

@ -6,11 +6,13 @@
*/ */
/** /**
* This package defines a framework for collection wrappers. The * This package defines a framework for lazy-initializing and state-tracking
* interface {@link org.hibernate.collection.spi.PersistentCollection} * collection wrappers.
* and all its implementations belong to an SPI. They are not part of * <p>
* the public API of Hibernate, and are not meant to be used directly * The interface {@link org.hibernate.collection.spi.PersistentCollection}
* by typical programs which use Hibernate for persistence. * and all its implementations belong to an SPI. They are not part of the
* public API of Hibernate, and are not meant to be used directly by typical
* programs which use Hibernate for persistence.
* *
* @see org.hibernate.proxy * @see org.hibernate.proxy
*/ */

View File

@ -16,7 +16,7 @@ import org.hibernate.sql.results.graph.FetchParentAccess;
import org.hibernate.sql.results.graph.collection.CollectionInitializer; import org.hibernate.sql.results.graph.collection.CollectionInitializer;
/** /**
* Functional contract to create a CollectionInitializer * Functional contract to create a {@link CollectionInitializer}.
* *
* @author Steve Ebersole * @author Steve Ebersole
* *
@ -26,15 +26,20 @@ import org.hibernate.sql.results.graph.collection.CollectionInitializer;
@FunctionalInterface @FunctionalInterface
public interface CollectionInitializerProducer { public interface CollectionInitializerProducer {
/** /**
* Create an initializer for `attribute` relative to `navigablePath`. * Create an initializer for the given attribute relative to the given
* navigable path.
* *
* `parentAccess` may be null to indicate that the initializer is for * @param navigablePath the navigable path
* a {@link org.hibernate.sql.results.graph.DomainResult} rather than * @param attribute the attribute
* a {@link org.hibernate.sql.results.graph.Fetch} * @param parentAccess may be null to indicate that the initializer is
* * for a {@link org.hibernate.sql.results.graph.DomainResult}
* `collectionKeyAssembler` and `collectionValueKeyAssembler` allow * rather than a {@link org.hibernate.sql.results.graph.Fetch}
* creating {@link org.hibernate.sql.results.graph.DomainResult} for * @param collectionKeyAssembler allows creation of a
* either side of the collection foreign-key * {@link org.hibernate.sql.results.graph.DomainResult} for
* either side of the collection foreign key
* @param collectionValueKeyAssembler allows creation of a
* {@link org.hibernate.sql.results.graph.DomainResult} for
* either side of the collection foreign key
*/ */
CollectionInitializer produceInitializer( CollectionInitializer produceInitializer(
NavigablePath navigablePath, NavigablePath navigablePath,

View File

@ -20,10 +20,12 @@ import org.hibernate.sql.results.graph.Fetch;
import org.hibernate.sql.results.graph.FetchParent; import org.hibernate.sql.results.graph.FetchParent;
/** /**
* Describes the semantics of a persistent collection such that Hibernate * Each instance of this interface describes the semantics of some sort of
* understands how to use it - create one, handle elements, etc. * persistent collection so that Hibernate understands how to manage the
* * lifecycle of instances of that sort of collection.
* @apiNote The described collection need not be part of the "Java Collection Framework" * <p>
* A collection type with semantics described by a {@code CollectionSemantics}
* object need not be part of the Java Collections Framework.
* *
* @param <E> the collection element or map key type * @param <E> the collection element or map key type
* @param <CE> the type of the collection * @param <CE> the type of the collection

View File

@ -10,13 +10,12 @@ import org.hibernate.Incubating;
import org.hibernate.mapping.Collection; import org.hibernate.mapping.Collection;
/** /**
* Resolve the collection semantics for the given mapped collection * Resolve the collection semantics for the given mapped collection.
* *
* todo (6.0) ... * @apiNote Ideally, this would act as the contract that allows pluggable
* * resolution of non-Java Collection types, perhaps as part of a
* Ideally would act as the contract that allows pluggable resolution of * generalized reflection on the attribute to determine its
* non-Java Collection types - maybe as part of a generalized reflection * nature/classification
* on the attribute to determine its nature/classification
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -36,29 +36,23 @@ public class InitializerProducerBuilder {
Fetch elementFetch, Fetch elementFetch,
DomainResultCreationState creationState) { DomainResultCreationState creationState) {
switch ( classification ) { switch ( classification ) {
case ARRAY: { case ARRAY:
return createArrayInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState ); return createArrayInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState );
}
case BAG: case BAG:
case ID_BAG: { case ID_BAG:
return createBagInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, elementFetch, creationState ); return createBagInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, elementFetch, creationState );
} case LIST:
case LIST: {
return createListInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState ); return createListInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState );
}
case MAP: case MAP:
case ORDERED_MAP: case ORDERED_MAP:
case SORTED_MAP: { case SORTED_MAP:
return createMapInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState ); return createMapInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState );
}
case SET: case SET:
case ORDERED_SET: case ORDERED_SET:
case SORTED_SET: { case SORTED_SET:
return createSetInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, elementFetch, creationState ); return createSetInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, elementFetch, creationState );
} default:
default: {
throw new IllegalArgumentException( "Unknown CollectionClassification : " + classification ); throw new IllegalArgumentException( "Unknown CollectionClassification : " + classification );
}
} }
} }
@ -228,7 +222,7 @@ public class InitializerProducerBuilder {
Fetch elementFetch, Fetch elementFetch,
DomainResultCreationState creationState) { DomainResultCreationState creationState) {
switch ( classification ) { switch ( classification ) {
case ARRAY: { case ARRAY:
return createArrayInitializerProducer( return createArrayInitializerProducer(
navigablePath, navigablePath,
attributeMapping, attributeMapping,
@ -238,9 +232,8 @@ public class InitializerProducerBuilder {
elementFetch, elementFetch,
creationState creationState
); );
}
case BAG: case BAG:
case ID_BAG: { case ID_BAG:
assert indexFetch == null; assert indexFetch == null;
return createBagInitializerProducer( return createBagInitializerProducer(
navigablePath, navigablePath,
@ -250,8 +243,7 @@ public class InitializerProducerBuilder {
elementFetch, elementFetch,
creationState creationState
); );
} case LIST:
case LIST: {
return createListInitializerProducer( return createListInitializerProducer(
navigablePath, navigablePath,
attributeMapping, attributeMapping,
@ -261,10 +253,9 @@ public class InitializerProducerBuilder {
elementFetch, elementFetch,
creationState creationState
); );
}
case MAP: case MAP:
case ORDERED_MAP: case ORDERED_MAP:
case SORTED_MAP: { case SORTED_MAP:
return createMapInitializerProducer( return createMapInitializerProducer(
navigablePath, navigablePath,
attributeMapping, attributeMapping,
@ -274,10 +265,9 @@ public class InitializerProducerBuilder {
elementFetch, elementFetch,
creationState creationState
); );
}
case SET: case SET:
case ORDERED_SET: case ORDERED_SET:
case SORTED_SET: { case SORTED_SET:
return createSetInitializerProducer( return createSetInitializerProducer(
navigablePath, navigablePath,
attributeMapping, attributeMapping,
@ -286,10 +276,8 @@ public class InitializerProducerBuilder {
elementFetch, elementFetch,
creationState creationState
); );
} default:
default: {
throw new IllegalArgumentException( "Unknown CollectionClassification : " + classification ); throw new IllegalArgumentException( "Unknown CollectionClassification : " + classification );
}
} }
} }

View File

@ -9,9 +9,21 @@ package org.hibernate.collection.spi;
import org.hibernate.Incubating; import org.hibernate.Incubating;
/** /**
* Hibernate "wraps" a java collection in an instance of PersistentCollection. Envers uses custom collection * The most general abstraction over collections which may be fetched lazily.
* wrappers (ListProxy, SetProxy, etc). All of them need to extend LazyInitializable, so the * <ul>
* Hibernate.isInitialized method can check if the collection is initialized or not. * <li>Hibernate core "wraps" a Java collection in an instance of
* {@link PersistentCollection}.
* <li>Similarly, Envers uses its own custom collection wrappers:
* {@code ListProxy}, {@code SetProxy}, and friends).
* </ul>
* <p>
* All of these wrapper objects extend {@code LazyInitializable}, allowing:
* <ul>
* <li>the method {@link org.hibernate.Hibernate#isInitialized(Object)} to
* determine if the collection was already fetched, and
* <li>the method {@link org.hibernate.Hibernate#initialize(Object)} to
* force it to be fetched.
* </ul>
* *
* @author Fabricio Gregorio * @author Fabricio Gregorio
*/ */
@ -22,11 +34,15 @@ public interface LazyInitializable {
* Is this instance initialized? * Is this instance initialized?
* *
* @return Was this collection initialized? Or is its data still not (fully) loaded? * @return Was this collection initialized? Or is its data still not (fully) loaded?
*
* @see org.hibernate.Hibernate#isInitialized(Object)
*/ */
boolean wasInitialized(); boolean wasInitialized();
/** /**
* To be called internally by the session, forcing immediate initialization. * To be called internally by the session, forcing immediate initialization.
*
* @see org.hibernate.Hibernate#initialize(Object)
*/ */
void forceInitialization(); void forceInitialization();

View File

@ -12,7 +12,7 @@ import java.util.function.BiConsumer;
import java.util.function.Consumer; import java.util.function.Consumer;
/** /**
* Extension of CollectionSemantics for Maps * Extension of {@link CollectionSemantics} for Maps
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -24,12 +24,13 @@ import org.hibernate.persister.collection.CollectionPersister;
import org.hibernate.type.Type; import org.hibernate.type.Type;
/** /**
* A persistent wrapper for an array. Lazy initialization * A dummy collection wrapper for an array. Lazy initialization is
* is NOT supported. Use of Hibernate arrays is not really * <em>not</em> supported. The use of arrays to represent persistent
* recommended. * collections in Hibernate is discouraged.
* *
* @apiNote Incubating in terms of making this non-internal. These contracts * @apiNote Incubating in terms of making this non-internal.
* will be getting cleaned up in following releases. * These contracts will be getting cleaned up in following
* releases.
* *
* @author Gavin King * @author Gavin King
*/ */

View File

@ -26,13 +26,15 @@ import org.hibernate.persister.collection.CollectionPersister;
import org.hibernate.type.Type; import org.hibernate.type.Type;
/** /**
* An unordered, unkeyed collection that can contain the same element * An unordered, un-keyed collection that can contain the same element
* multiple times. The Java collections API, curiously, has no {@code Bag}. * multiple times. The Java Collections Framework, curiously, has no
* Most developers seem to use {@code List}s to represent bag semantics, * {@code Bag} interface. It is, however, common to use {@code List}s
* so Hibernate follows this practice. * to represent a collection with bag semantics, so Hibernate follows
* this practice.
* *
* @apiNote Incubating in terms of making this non-internal. These contracts * @apiNote Incubating in terms of making this non-internal.
* will be getting cleaned up in following releases. * These contracts will be getting cleaned up in following
* releases.
* *
* @author Gavin King * @author Gavin King
*/ */

View File

@ -21,26 +21,29 @@ import org.hibernate.type.Type;
/** /**
* Persistent collections are treated as value objects by Hibernate. * Persistent collections are treated as value objects by Hibernate.
* ie. they have no independent existence beyond the object holding * They have no independent existence beyond the entity holding a
* a reference to them. Unlike instances of entity classes, they are * reference to them. Unlike instances of entity classes, they are
* automatically deleted when unreferenced and automatically become * automatically deleted when unreferenced and automatically become
* persistent when held by a persistent object. Collections can be * persistent when held by a persistent object. Collections can be
* passed between different objects (change "roles") and this might * passed between different objects (change "roles") and this might
* cause their elements to move from one database table to another. * cause their elements to move from one database table to another.
* <p> * <p>
* Hibernate "wraps" a java collection in an instance of * Hibernate "wraps" a Java collection in an instance of
* PersistentCollection. This mechanism is designed to support * {@code PersistentCollection}. This mechanism is allows for
* tracking of changes to the collection's persistent state and * tracking of changes to the persistent state of the collection and
* lazy instantiation of collection elements. The downside is that * lazy fetching of the collection elements. The downside is that
* only certain abstract collection types are supported and any * only certain abstract collection types are supported and any
* extra semantics are lost * extra semantics associated with the particular implementation of
* the generic collection type are lost. For example, every
* {@link java.util.List} behaves like an {@code ArrayList}, and
* every {@link java.util.SortedMap} behaves like a {@code TreeMap}.
* <p> * <p>
* Applications should <em>never</em> use classes in this package * Applications should <em>never</em> use classes in this package
* directly, unless extending the "framework" here. * directly, unless extending the "framework" here.
* <p> * <p>
* Changes to <em>structure</em> of the collection are recorded by the * Changes to <em>structure</em> of the collection are recorded by
* collection calling back to the session. Changes to mutable * the collection calling back to the session. Changes to mutable
* elements (ie. composite elements) are discovered by cloning their * elements (composite elements) are discovered by cloning their
* state when the collection is initialized and comparing at flush * state when the collection is initialized and comparing at flush
* time. * time.
* *

View File

@ -26,17 +26,18 @@ import org.hibernate.type.Type;
import static org.hibernate.generator.EventType.INSERT; import static org.hibernate.generator.EventType.INSERT;
/** /**
* An {@code IdentifierBag} implements "bag" semantics more efficiently than * An "identifier bag" implements "bag" semantics more efficiently than a
* a regular {@code Bag} by adding a synthetic identifier column to the * regular bag by adding a synthetic identifier column to the table. This
* table. This identifier is unique for all rows in the table, allowing very * identifier is unique over all rows in the table, allowing very efficient
* efficient updates and deletes. The value of the identifier is never exposed * updates and deletes. The value of the identifier is never exposed to the
* to the application. * application.
* <p> * <p>
* {@code IdentifierBag}s may not be used for a many-to-one association. * Identifier bags may not be used for a many-to-one association.
* Furthermore, there is no reason to use {@code inverse="true"}. * Furthermore, there is no reason to use {@code inverse="true"}.
* *
* @apiNote Incubating in terms of making this non-internal. These contracts * @apiNote Incubating in terms of making this non-internal.
* will be getting cleaned up in following releases. * These contracts will be getting cleaned up in following
* releases.
* *
* @author Gavin King * @author Gavin King
*/ */

View File

@ -23,11 +23,12 @@ import org.hibernate.persister.collection.CollectionPersister;
import org.hibernate.type.Type; import org.hibernate.type.Type;
/** /**
* A persistent wrapper for a {@code java.util.List}. Underlying * A persistent wrapper for a {@link java.util.List}. Underlying
* collection is an {@code ArrayList}. * collection is an {@code ArrayList}.
* *
* @apiNote Incubating in terms of making this non-internal. These contracts * @apiNote Incubating in terms of making this non-internal.
* will be getting cleaned up in following releases. * These contracts will be getting cleaned up in following
* releases.
* *
* @author Gavin King * @author Gavin King
*/ */

View File

@ -28,11 +28,12 @@ import org.hibernate.type.Type;
/** /**
* A persistent wrapper for a {@code java.util.Map}. Underlying collection * A persistent wrapper for a {@link java.util.Map}. Underlying collection
* is a {@code HashMap}. * is a {@code HashMap}.
* *
* @apiNote Incubating in terms of making this non-internal. These contracts * @apiNote Incubating in terms of making this non-internal.
* will be getting cleaned up in following releases. * These contracts will be getting cleaned up in following
* releases.
* *
* @author Gavin King * @author Gavin King
*/ */

View File

@ -26,11 +26,12 @@ import org.hibernate.type.Type;
/** /**
* A persistent wrapper for a {@code java.util.Set}. The underlying * A persistent wrapper for a {@link java.util.Set}. The underlying
* collection is a {@code HashSet}. * collection is a {@code HashSet}.
* *
* @apiNote Incubating in terms of making this non-internal. These contracts * @apiNote Incubating in terms of making this non-internal.
* will be getting cleaned up in following releases. * These contracts will be getting cleaned up in following
* releases.
* *
* @author Gavin King * @author Gavin King
*/ */

View File

@ -20,13 +20,14 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
import org.hibernate.persister.collection.BasicCollectionPersister; import org.hibernate.persister.collection.BasicCollectionPersister;
/** /**
* A persistent wrapper for a {@code java.util.SortedMap}. Underlying * A persistent wrapper for a {@link java.util.SortedMap}. Underlying
* collection is a {@code TreeMap}. * collection is a {@code TreeMap}.
* *
* @apiNote Incubating in terms of making this non-internal. These contracts * @apiNote Incubating in terms of making this non-internal.
* will be getting cleaned up in following releases. * These contracts will be getting cleaned up in following
* releases.
* *
* @author <a href="mailto:doug.currie@alum.mit.edu">e</a> * @author Doug Currie
*/ */
@Incubating @Incubating
public class PersistentSortedMap<K,E> extends PersistentMap<K,E> implements SortedMap<K,E> { public class PersistentSortedMap<K,E> extends PersistentMap<K,E> implements SortedMap<K,E> {

View File

@ -17,13 +17,14 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
import org.hibernate.persister.collection.BasicCollectionPersister; import org.hibernate.persister.collection.BasicCollectionPersister;
/** /**
* A persistent wrapper for a {@code java.util.SortedSet}. Underlying * A persistent wrapper for a {@link java.util.SortedSet}. Underlying
* collection is a {@code TreeSet}. * collection is a {@code TreeSet}.
* *
* @apiNote Incubating in terms of making this non-internal. These contracts * @apiNote Incubating in terms of making this non-internal.
* will be getting cleaned up in following releases. * These contracts will be getting cleaned up in following
* releases.
* *
* @author <a href="mailto:doug.currie@alum.mit.edu">e</a> * @author Doug Currie
*/ */
@Incubating @Incubating
public class PersistentSortedSet<E> extends PersistentSet<E> implements SortedSet<E> { public class PersistentSortedSet<E> extends PersistentSet<E> implements SortedSet<E> {

View File

@ -6,6 +6,15 @@
*/ */
/** /**
* SPI definitions for persistent collections. * This package defines the SPI of a framework for lazy-initializing
* and state-tracking collection wrappers.
* <p>
* The interface {@link org.hibernate.collection.spi.PersistentCollection}
* and all its implementations belong to an SPI. They are not part of the
* public API of Hibernate, and are not meant to be used directly by typical
* programs which use Hibernate for persistence.
*
* @see org.hibernate.collection.spi.PersistentCollection
* @see org.hibernate.collection.spi.CollectionSemantics
*/ */
package org.hibernate.collection.spi; package org.hibernate.collection.spi;

View File

@ -160,8 +160,8 @@ import static org.hibernate.type.descriptor.DateTimeUtils.appendAsTimestampWithM
* <p> * <p>
* Note: This dialect is configured to create foreign keys with {@code on update cascade}. * Note: This dialect is configured to create foreign keys with {@code on update cascade}.
* *
* @author <a href="mailto:andrew.clemons@sap.com">Andrew Clemons</a> * @author Andrew Clemons
* @author <a href="mailto:jonathan.bregler@sap.com">Jonathan Bregler</a> * @author Jonathan Bregler
*/ */
public abstract class AbstractHANADialect extends Dialect { public abstract class AbstractHANADialect extends Dialect {
private static final CoreMessageLogger LOG = CoreLogging.messageLogger( AbstractHANADialect.class ); private static final CoreMessageLogger LOG = CoreLogging.messageLogger( AbstractHANADialect.class );

View File

@ -17,7 +17,7 @@ package org.hibernate.dialect;
* <p> * <p>
* Column tables are created by this dialect when using the auto-ddl feature. * Column tables are created by this dialect when using the auto-ddl feature.
* *
* @author <a href="mailto:jonathan.bregler@sap.com">Jonathan Bregler</a> * @author Jonathan Bregler
* *
* @deprecated use HANAColumnStoreDialect(400) * @deprecated use HANAColumnStoreDialect(400)
*/ */

View File

@ -32,8 +32,8 @@ import static org.hibernate.query.sqm.produce.function.FunctionParameterType.ANY
* <p> * <p>
* Column tables are created by this dialect when using the auto-ddl feature. * Column tables are created by this dialect when using the auto-ddl feature.
* *
* @author <a href="mailto:andrew.clemons@sap.com">Andrew Clemons</a> * @author Andrew Clemons
* @author <a href="mailto:jonathan.bregler@sap.com">Jonathan Bregler</a> * @author Jonathan Bregler
*/ */
public class HANAColumnStoreDialect extends AbstractHANADialect { public class HANAColumnStoreDialect extends AbstractHANADialect {

View File

@ -27,8 +27,8 @@ import org.hibernate.query.sqm.mutation.spi.SqmMultiTableMutationStrategy;
* <p> * <p>
* Row tables are created by this dialect when using the auto-ddl feature. * Row tables are created by this dialect when using the auto-ddl feature.
* *
* @author <a href="mailto:andrew.clemons@sap.com">Andrew Clemons</a> * @author Andrew Clemons
* @author <a href="mailto:jonathan.bregler@sap.com">Jonathan Bregler</a> * @author Jonathan Bregler
*/ */
public class HANARowStoreDialect extends AbstractHANADialect { public class HANARowStoreDialect extends AbstractHANADialect {

View File

@ -41,9 +41,9 @@ import static org.hibernate.engine.internal.ManagedTypeHelper.isPersistentAttrib
* A base implementation of EntityEntry * A base implementation of EntityEntry
* *
* @author Gavin King * @author Gavin King
* @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a> * @author Emmanuel Bernard
* @author Gunnar Morling * @author Gunnar Morling
* @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero </a> * @author Sanne Grinovero
*/ */
public abstract class AbstractEntityEntry implements Serializable, EntityEntry { public abstract class AbstractEntityEntry implements Serializable, EntityEntry {

View File

@ -11,7 +11,7 @@ import org.hibernate.engine.spi.EntityEntryExtraState;
/** /**
* Contains optional state from {@link org.hibernate.engine.spi.EntityEntry}. * Contains optional state from {@link org.hibernate.engine.spi.EntityEntry}.
* *
* @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a> * @author Emmanuel Bernard
*/ */
public class EntityEntryExtraStateHolder implements EntityEntryExtraState { public class EntityEntryExtraStateHolder implements EntityEntryExtraState {
private EntityEntryExtraState next; private EntityEntryExtraState next;

View File

@ -23,9 +23,9 @@ import org.hibernate.persister.entity.EntityPersister;
* immutable in terms of its internal state; the term immutable here refers to the entity it describes. * immutable in terms of its internal state; the term immutable here refers to the entity it describes.
* *
* @author Gavin King * @author Gavin King
* @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a> * @author Emmanuel Bernard
* @author Gunnar Morling * @author Gunnar Morling
* @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero </a> * @author Sanne Grinovero
* *
* @see org.hibernate.annotations.Immutable * @see org.hibernate.annotations.Immutable
*/ */

View File

@ -20,9 +20,9 @@ import org.hibernate.persister.entity.EntityPersister;
* An EntityEntry implementation for mutable entities. * An EntityEntry implementation for mutable entities.
* *
* @author Gavin King * @author Gavin King
* @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a> * @author Emmanuel Bernard
* @author Gunnar Morling * @author Gunnar Morling
* @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero </a> * @author Sanne Grinovero
*/ */
public final class MutableEntityEntry extends AbstractEntityEntry { public final class MutableEntityEntry extends AbstractEntityEntry {

View File

@ -6,6 +6,6 @@
*/ */
/** /**
* Internals for accessing JDBC Connections * Various implementations of the SPI contracts for obtaining JDBC {@link java.sql.Connection}s.
*/ */
package org.hibernate.engine.jdbc.connections.internal; package org.hibernate.engine.jdbc.connections.internal;

View File

@ -6,6 +6,9 @@
*/ */
/** /**
* Defines contracts for accessing JDBC Connections * Defines SPI contracts for obtaining JDBC {@link java.sql.Connection}s from a
* provider implemented as a {@linkplain org.hibernate.service.Service service}.
*
* @see org.hibernate.engine.jdbc.connections.spi.ConnectionProvider
*/ */
package org.hibernate.engine.jdbc.connections.spi; package org.hibernate.engine.jdbc.connections.spi;

View File

@ -6,6 +6,6 @@
*/ */
/** /**
* Support for various aspects of JDBC interaction * Support for various aspects of JDBC interaction.
*/ */
package org.hibernate.engine.jdbc; package org.hibernate.engine.jdbc;

View File

@ -6,6 +6,6 @@
*/ */
/** /**
* SPI contracts for supporting various aspects of JDBC interaction * SPI contracts supporting various aspects of JDBC interaction.
*/ */
package org.hibernate.engine.jdbc.spi; package org.hibernate.engine.jdbc.spi;

View File

@ -6,6 +6,6 @@
*/ */
/** /**
* The SPI contracts for Hibernate JNDI support * The SPI contracts for integration with JNDI.
*/ */
package org.hibernate.engine.jndi.spi; package org.hibernate.engine.jndi.spi;

View File

@ -6,6 +6,6 @@
*/ */
/** /**
* Models the fetch profiles defined by the application * Models the fetch profiles defined by the application.
*/ */
package org.hibernate.engine.profile; package org.hibernate.engine.profile;

View File

@ -7,7 +7,7 @@
package org.hibernate.engine.spi; package org.hibernate.engine.spi;
/** /**
* @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a> * @author Ståle W. Pedersen
*/ */
public interface CompositeOwner extends PrimeAmongSecondarySupertypes { public interface CompositeOwner extends PrimeAmongSecondarySupertypes {
/** /**

View File

@ -7,7 +7,7 @@
package org.hibernate.engine.spi; package org.hibernate.engine.spi;
/** /**
* @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a> * @author Ståle W. Pedersen
*/ */
public interface CompositeTracker extends PrimeAmongSecondarySupertypes { public interface CompositeTracker extends PrimeAmongSecondarySupertypes {

View File

@ -20,9 +20,9 @@ import org.hibernate.persister.entity.EntityPersister;
* therefore we need to take care of its impact on memory consumption. * therefore we need to take care of its impact on memory consumption.
* *
* @author Gavin King * @author Gavin King
* @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a> * @author Emmanuel Bernard
* @author Gunnar Morling * @author Gunnar Morling
* @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero </a> * @author Sanne Grinovero
*/ */
public interface EntityEntry { public interface EntityEntry {
LockMode getLockMode(); LockMode getLockMode();

View File

@ -10,7 +10,7 @@ package org.hibernate.engine.spi;
/** /**
* Navigation methods for extra state objects attached to {@link EntityEntry}. * Navigation methods for extra state objects attached to {@link EntityEntry}.
* *
* @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a> * @author Emmanuel Bernard
*/ */
public interface EntityEntryExtraState { public interface EntityEntryExtraState {

View File

@ -6,18 +6,20 @@
*/ */
package org.hibernate.engine.spi; package org.hibernate.engine.spi;
import org.hibernate.Internal;
import org.hibernate.engine.internal.ManagedTypeHelper; import org.hibernate.engine.internal.ManagedTypeHelper;
import org.hibernate.proxy.HibernateProxy; import org.hibernate.proxy.HibernateProxy;
import org.hibernate.proxy.ProxyConfiguration; import org.hibernate.proxy.ProxyConfiguration;
/** /**
* For a full explanation of the purpose of this interface * For a full explanation of the purpose of this interface see {@link ManagedTypeHelper}.
* see {@link ManagedTypeHelper}. *
* This is an internal, private marking interface; it's exposed in the spi * @apiNote This is an internal, private marking interface; it's exposed in the SPI
* package as bytecode enhanced usercode needs to be able to refer to it. * package as bytecode enhanced user code needs to be able to reference it.
* *
* @author Sanne Grinovero * @author Sanne Grinovero
*/ */
@Internal
public interface PrimeAmongSecondarySupertypes { public interface PrimeAmongSecondarySupertypes {
default ManagedEntity asManagedEntity() { default ManagedEntity asManagedEntity() {

View File

@ -16,7 +16,7 @@ import org.hibernate.bytecode.enhance.spi.CollectionTracker;
* also introduced into the entity when using bytecode enhancement and requesting * also introduced into the entity when using bytecode enhancement and requesting
* that entities track their own dirtiness. * that entities track their own dirtiness.
* *
* @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a> * @author Ståle W. Pedersen
*/ */
public interface SelfDirtinessTracker extends PrimeAmongSecondarySupertypes { public interface SelfDirtinessTracker extends PrimeAmongSecondarySupertypes {
/** /**

View File

@ -61,7 +61,7 @@ import jakarta.persistence.metamodel.Metamodel;
* Another difference with SessionDelegatorBaseImpl is that * Another difference with SessionDelegatorBaseImpl is that
* this type only implements Session. * this type only implements Session.
* *
* @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero</a> (C) 2022 Red Hat Inc. * @author Sanne Grinovero
*/ */
public class SessionLazyDelegator implements Session { public class SessionLazyDelegator implements Session {

View File

@ -35,7 +35,7 @@ import org.hibernate.HibernateException;
* This class is reported to work on WAS version 6 in any of the standard J2EE/Java EE component containers. * This class is reported to work on WAS version 6 in any of the standard J2EE/Java EE component containers.
* *
* @author Gavin King * @author Gavin King
* @author <a href="mailto:jesper@udby.com>Jesper Udby</a> * @author Jesper Udby
* @author Steve Ebersole * @author Steve Ebersole
*/ */
public class WebSphereExtendedJtaPlatform extends AbstractJtaPlatform { public class WebSphereExtendedJtaPlatform extends AbstractJtaPlatform {

View File

@ -16,7 +16,7 @@ import org.hibernate.persister.entity.EntityPersister;
/** /**
* The standard PostDeleteEventListener implementation * The standard PostDeleteEventListener implementation
* *
* @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a> * @author Kabir Khan
* @author Steve Ebersole * @author Steve Ebersole
*/ */
public class PostDeleteEventListenerStandardImpl implements PostDeleteEventListener, CallbackRegistryConsumer { public class PostDeleteEventListenerStandardImpl implements PostDeleteEventListener, CallbackRegistryConsumer {

View File

@ -14,7 +14,7 @@ import org.hibernate.jpa.event.spi.CallbackType;
import org.hibernate.persister.entity.EntityPersister; import org.hibernate.persister.entity.EntityPersister;
/** /**
* @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a> * @author Kabir Khan
* @author Steve Ebersole * @author Steve Ebersole
*/ */
public class PostInsertEventListenerStandardImpl implements PostInsertEventListener, CallbackRegistryConsumer { public class PostInsertEventListenerStandardImpl implements PostInsertEventListener, CallbackRegistryConsumer {

View File

@ -11,7 +11,7 @@ import org.hibernate.persister.entity.EntityPersister;
/** /**
* Occurs after an entity instance is fully loaded. * Occurs after an entity instance is fully loaded.
* *
* @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>, Gavin King * @author Kabir Khan, Gavin King
*/ */
public class PostLoadEvent extends AbstractEvent { public class PostLoadEvent extends AbstractEvent {
private Object entity; private Object entity;

View File

@ -9,7 +9,7 @@ package org.hibernate.event.spi;
/** /**
* Occurs after an entity instance is fully loaded. * Occurs after an entity instance is fully loaded.
* *
* @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a> * @author Kabir Khan
*/ */
public interface PostLoadEventListener { public interface PostLoadEventListener {
void onPostLoad(PostLoadEvent event); void onPostLoad(PostLoadEvent event);

View File

@ -14,7 +14,7 @@ import org.hibernate.metamodel.model.domain.PersistentAttribute;
/** /**
* Hibernate extension to the JPA entity-graph AttributeNode contract. * Hibernate extension to the JPA entity-graph AttributeNode contract.
* *
* @author <a href="mailto:stliu@hibernate.org">Strong Liu</a> * @author Strong Liu
* @author Steve Ebersole * @author Steve Ebersole
* @author Andrea Boriero * @author Andrea Boriero
*/ */

View File

@ -23,14 +23,15 @@ import org.hibernate.graph.spi.RootGraphImplementor;
/** /**
* A collection of {@link EntityGraph} utilities. * A collection of {@link EntityGraph} utilities.
* These methods really belong inside other classes that we cannot modify, hence here. *
* @apiNote These methods really belong inside other classes that we cannot modify.
* *
* @author asusnjar * @author asusnjar
*/ */
public final class EntityGraphs { public final class EntityGraphs {
/** /**
* Merges multiple entity graphs into a single graph that specifies the fetching/loading of all attributes the input * Merges multiple entity graphs into a single graph that specifies the
* graphs specify. * fetching/loading of all attributes the input graphs specify.
* *
* @param <T> Root entity type of the query and graph. * @param <T> Root entity type of the query and graph.
* *
@ -70,8 +71,8 @@ public final class EntityGraphs {
} }
/** /**
* Convenience method for {@linkplain Query#getResultList() executing} the Query, applying the * Convenience method for {@linkplain Query#getResultList() executing the query},
* given EntityGraph using the specified semantic * applying the given {@link EntityGraph} using the specified semantic
* *
* @param query The JPA Query * @param query The JPA Query
* @param graph The graph to apply * @param graph The graph to apply
@ -85,15 +86,16 @@ public final class EntityGraphs {
} }
/** /**
* Form of {@link #executeList(Query, EntityGraph, GraphSemantic)} accepting a TypedQuery. * Form of {@link #executeList(Query, EntityGraph, GraphSemantic)} accepting a
* {@link TypedQuery}.
* *
* @param query The JPA Query * @param query The JPA Query
* @param graph The graph to apply * @param graph The graph to apply
* @param semantic The semantic to use when applying the graph * @param semantic The semantic to use when applying the graph
* *
* @apiNote This signature assumes that the Query's return is an entity and that the graph * @apiNote This signature assumes that the Query's return is an entity and that
* applies to that entity's type. JPA does not necessarily require that, but it is by * the graph applies to that entity's type. JPA does not necessarily
* far the most common usage. * require that, but it is by far the most common usage.
*/ */
@SuppressWarnings({"unused", "unchecked"}) @SuppressWarnings({"unused", "unchecked"})
public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph, GraphSemantic semantic) { public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph, GraphSemantic semantic) {
@ -101,9 +103,9 @@ public final class EntityGraphs {
} }
/** /**
* Convenience method for {@linkplain Query#getResultList() executing} the Query, applying the * Convenience method for {@linkplain Query#getResultList() executing the query},
* given EntityGraph using the named semantic using JPA's "hint name" - see * applying the given {@link EntityGraph} using the named semantic using JPA's
* {@link GraphSemantic#fromHintName} * "hint name". See {@link GraphSemantic#fromHintName}.
* *
* @param query The JPA Query * @param query The JPA Query
* @param graph The graph to apply * @param graph The graph to apply
@ -119,15 +121,16 @@ public final class EntityGraphs {
} }
/** /**
* Form of {@link #executeList(Query, EntityGraph, String)} accepting a TypedQuery * Form of {@link #executeList(Query, EntityGraph, String)} accepting a
* {@link TypedQuery}.
* *
* @param query The JPA Query * @param query The JPA Query
* @param graph The graph to apply * @param graph The graph to apply
* @param semanticJpaHintName See {@link GraphSemantic#fromHintName} * @param semanticJpaHintName See {@link GraphSemantic#fromHintName}
* *
* @apiNote This signature assumes that the Query's return is an entity and that the graph * @apiNote This signature assumes that the Query's return is an entity and that
* applies to that entity's type. JPA does not necessarily require that, but it is by * the graph applies to that entity's type. JPA does not necessarily
* far the most common usage. * require that, but it is by far the most common usage.
*/ */
@SuppressWarnings({"unused", "unchecked"}) @SuppressWarnings({"unused", "unchecked"})
public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph, String semanticJpaHintName) { public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph, String semanticJpaHintName) {
@ -135,16 +138,16 @@ public final class EntityGraphs {
} }
/** /**
* Convenience method for {@linkplain Query#getResultList() executing} the Query using the * Convenience method for {@linkplain Query#getResultList() executing the query}
* given EntityGraph * using the given {@link EntityGraph}.
* *
* @param query The JPA Query * @param query The JPA Query
* @param graph The graph to apply * @param graph The graph to apply
* *
* @apiNote operates on the assumption that the "default" semantic for an * @apiNote Operates on the assumption that the "default" semantic for an
* entity graph applied to a Query is {@link GraphSemantic#FETCH}. This is simply * entity graph applied to a query is {@link GraphSemantic#FETCH}.
* knowledge from JPA EG discussions, nothing that is specifically mentioned or * This is simply knowledge from JPA EG discussions, nothing that
* discussed in the spec. * is specifically mentioned or discussed in the spec.
*/ */
@SuppressWarnings({"unused", "unchecked"}) @SuppressWarnings({"unused", "unchecked"})
public static List executeList(Query query, EntityGraph graph) { public static List executeList(Query query, EntityGraph graph) {
@ -154,14 +157,15 @@ public final class EntityGraphs {
} }
/** /**
* Form of {@link #executeList(Query, EntityGraph, String)} accepting a TypedQuery * Form of {@link #executeList(Query, EntityGraph, String)} accepting a
* {@link TypedQuery}.
* *
* @param query The JPA Query * @param query The JPA Query
* @param graph The graph to apply * @param graph The graph to apply
* *
* @apiNote This signature assumes that the Query's return is an entity and that the graph * @apiNote This signature assumes that the Query's return is an entity and that
* applies to that entity's type. JPA does not necessarily require that, but it is by * the graph applies to that entity's type. JPA does not necessarily
* far the most common usage. * require that, but it is by far the most common usage.
*/ */
@SuppressWarnings("unused") @SuppressWarnings("unused")
public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph) { public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph) {
@ -172,9 +176,9 @@ public final class EntityGraphs {
// but really, I think unwrapping as Hibernate's Query and using our // but really, I think unwrapping as Hibernate's Query and using our
// "proprietary" methods is better (this class is "proprietary" too). // "proprietary" methods is better (this class is "proprietary" too).
/** /**
* Compares two entity graphs and returns {@code true} if they are equal, ignoring attribute order. * Compares two entity graphs and returns {@code true} if they are equal,
* ignoring attribute order.
* *
* @param <T> Root entity type of BOTH graphs. * @param <T> Root entity type of BOTH graphs.
* @param a Graph to compare. * @param a Graph to compare.
@ -213,8 +217,8 @@ public final class EntityGraphs {
} }
/** /**
* Compares two entity graph attribute node and returns {@code true} if they are equal, ignoring subgraph attribute * Compares two entity graph attribute node and returns {@code true} if they are equal,
* order. * ignoring subgraph attribute order.
*/ */
public static boolean areEqual(AttributeNode<?> a, AttributeNode<?> b) { public static boolean areEqual(AttributeNode<?> a, AttributeNode<?> b) {
if ( a == b ) { if ( a == b ) {
@ -232,7 +236,8 @@ public final class EntityGraphs {
} }
/** /**
* Compares two entity subgraph maps and returns {@code true} if they are equal, ignoring order. * Compares two entity subgraph maps and returns {@code true} if they are equal,
* ignoring order.
*/ */
public static boolean areEqual(@SuppressWarnings("rawtypes") Map<Class, Subgraph> a, @SuppressWarnings("rawtypes") Map<Class, Subgraph> b) { public static boolean areEqual(@SuppressWarnings("rawtypes") Map<Class, Subgraph> a, @SuppressWarnings("rawtypes") Map<Class, Subgraph> b) {
if ( a == b ) { if ( a == b ) {
@ -264,7 +269,8 @@ public final class EntityGraphs {
} }
/** /**
* Compares two entity subgraphs and returns {@code true} if they are equal, ignoring attribute order. * Compares two entity subgraphs and returns {@code true} if they are equal,
* ignoring attribute order.
*/ */
public static boolean areEqual(@SuppressWarnings("rawtypes") Subgraph a, @SuppressWarnings("rawtypes") Subgraph b) { public static boolean areEqual(@SuppressWarnings("rawtypes") Subgraph a, @SuppressWarnings("rawtypes") Subgraph b) {
if ( a == b ) { if ( a == b ) {

View File

@ -14,30 +14,33 @@ import org.hibernate.metamodel.model.domain.PersistentAttribute;
/** /**
* A container for {@link AttributeNode} references. * A container for {@link AttributeNode} references.
* <p> * <p>
* Acts as a "bridge" between JPA's {@link jakarta.persistence.EntityGraph} and {@link jakarta.persistence.Subgraph} * Acts as a "bridge" between JPA's {@link jakarta.persistence.EntityGraph}
* and {@link jakarta.persistence.Subgraph}.
* *
* @author <a href="mailto:stliu@hibernate.org">Strong Liu</a> * @author Strong Liu
* @author Steve Ebersole * @author Steve Ebersole
* @author Andrea Boriero * @author Andrea Boriero
*/ */
@SuppressWarnings({"unused", "UnusedReturnValue"}) @SuppressWarnings({"unused", "UnusedReturnValue"})
public interface Graph<J> extends GraphNode<J> { public interface Graph<J> extends GraphNode<J> {
/** /**
* Graphs apply only to ManagedTypes. Returns the ManagedType being graphed here. * Graphs apply only to {@link jakarta.persistence.metamodel.ManagedType}s.
*
* @return the {@code ManagedType} being graphed here.
*/ */
ManagedDomainType<J> getGraphedType(); ManagedDomainType<J> getGraphedType();
/** /**
* Create a named (if passed `name` != null) root Graph. The `mutable` * Create a named root {@link Graph} if the given name is not null.
* parameter controls whether the created Graph is mutable.
* *
* @throws CannotBecomeEntityGraphException For named attributes * @param mutable controls whether the resulting {@code Graph} is mutable
* that are not entity valued *
* @throws CannotBecomeEntityGraphException If the named attribute is not entity-valued
*/ */
RootGraph<J> makeRootGraph(String name, boolean mutable) throws CannotBecomeEntityGraphException; RootGraph<J> makeRootGraph(String name, boolean mutable) throws CannotBecomeEntityGraphException;
/** /**
* Create a (mutable/immutable) SubGraph based on this Graph * Create a (mutable or immutable) {@link SubGraph} rooted at this {@link Graph}.
*/ */
SubGraph<J> makeSubGraph(boolean mutable); SubGraph<J> makeSubGraph(boolean mutable);

View File

@ -7,8 +7,7 @@
package org.hibernate.graph; package org.hibernate.graph;
/** /**
* Commonality between {@link AttributeNode} and * Commonality between {@link AttributeNode} and {@link Graph}.
* {@link Graph}.
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -8,7 +8,7 @@
/** /**
* Implements and extends the JPA-defined {@linkplain jakarta.persistence.EntityGraph entity graph} API. * Implements and extends the JPA-defined {@linkplain jakarta.persistence.EntityGraph entity graph} API.
* *
* @apiNote This entire package (including sub-packages) is considered incubating * @apiNote This entire package, including its subpackages, is considered incubating.
*/ */
@Incubating @Incubating
package org.hibernate.graph; package org.hibernate.graph;

View File

@ -17,7 +17,7 @@ import org.hibernate.metamodel.model.domain.ManagedDomainType;
/** /**
* Integration version of the AttributeNode contract * Integration version of the AttributeNode contract
* *
* @author <a href="mailto:stliu@hibernate.org">Strong Liu</a> * @author Strong Liu
* @author Steve Ebersole * @author Steve Ebersole
*/ */
public interface AttributeNodeImplementor<J> extends AttributeNode<J>, GraphNodeImplementor<J> { public interface AttributeNodeImplementor<J> extends AttributeNode<J>, GraphNodeImplementor<J> {

View File

@ -20,7 +20,7 @@ import org.hibernate.metamodel.model.domain.PersistentAttribute;
/** /**
* Integration version of the Graph contract * Integration version of the Graph contract
* *
* @author <a href="mailto:stliu@hibernate.org">Strong Liu</a> * @author Strong Liu
* @author Steve Ebersole * @author Steve Ebersole
* @author Andrea Boriero * @author Andrea Boriero
*/ */

View File

@ -12,7 +12,7 @@ import org.hibernate.graph.GraphNode;
* Integration version of the GraphNode contract * Integration version of the GraphNode contract
* *
* @author Steve Ebersole * @author Steve Ebersole
* @author <a href="mailto:stliu@hibernate.org">Strong Liu</a> * @author Strong Liu
*/ */
public interface GraphNodeImplementor<J> extends GraphNode<J> { public interface GraphNodeImplementor<J> extends GraphNode<J> {
@Override @Override

View File

@ -6,7 +6,7 @@
*/ */
/** /**
* Enhanced/improved versions of table and sequence based identifier generators targeting portability and unified * Enhanced/improved versions of table and sequence based identifier generators
* configuration * targeting portability and unified configuration.
*/ */
package org.hibernate.id.enhanced; package org.hibernate.id.enhanced;

View File

@ -22,8 +22,8 @@ import org.hibernate.internal.CoreMessageLogger;
import org.hibernate.type.SerializationException; import org.hibernate.type.SerializationException;
/** /**
* <p>Assists with the serialization process and performs additional functionality based * Assists with the serialization process and performs additional
* on serialization.</p> * functionality based on serialization.
* <p> * <p>
* <ul> * <ul>
* <li>Deep clone using serialization * <li>Deep clone using serialization
@ -31,12 +31,11 @@ import org.hibernate.type.SerializationException;
* <li>Deserialize managing finally and IOException * <li>Deserialize managing finally and IOException
* </ul> * </ul>
* <p> * <p>
* <p>This class throws exceptions for invalid <code>null</code> inputs. * This class throws exceptions for invalid {@code null} inputs.
* Each method documents its behaviour in more detail.</p>
* *
* @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a> * @author Nissim Karpenstein
* @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a> * @author Janek Bogucki
* @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a> * @author Daniel Rall
* @author Stephen Colebourne * @author Stephen Colebourne
* @author Jeff Varszegi * @author Jeff Varszegi
* @author Gary Gregory * @author Gary Gregory
@ -53,15 +52,15 @@ public final class SerializationHelper {
//----------------------------------------------------------------------- //-----------------------------------------------------------------------
/** /**
* <p>Deep clone an <code>Object</code> using serialization.</p> * Deep clone an object using serialization.
* <p> * <p>
* <p>This is many times slower than writing clone methods by hand * This is many times slower than writing clone methods by hand
* on all objects in your object graph. However, for complex object * on all objects in your object graph. However, for complex object
* graphs, or for those that don't support deep cloning this can * graphs, or for those that don't support deep cloning this can
* be a simple alternative implementation. Of course all the objects * be a simple alternative implementation. Of course all the objects
* must be <code>Serializable</code>.</p> * must be {@code Serializable}.
* *
* @param object the <code>Serializable</code> object to clone * @param object the {@code Serializable} object to clone
* *
* @return the cloned object * @return the cloned object
* *
@ -79,19 +78,19 @@ public final class SerializationHelper {
//----------------------------------------------------------------------- //-----------------------------------------------------------------------
/** /**
* <p>Serializes an <code>Object</code> to the specified stream.</p> * <p>Serializes an object to the given stream.
* <p> * <p>
* <p>The stream will be closed once the object is written. * The stream will be closed once the object is written.
* This avoids the need for a finally clause, and maybe also exception * This avoids the need for a finally clause, and maybe also
* handling, in the application code.</p> * for exception handling, in the application code.
* <p> * <p>
* <p>The stream passed in is not buffered internally within this method. * The stream passed in is not buffered internally within this
* This is the responsibility of your application if desired.</p> * method. This is the responsibility of the caller, if desired.
* *
* @param obj the object to serialize to bytes, may be null * @param obj the object to serialize to bytes, may be null
* @param outputStream the stream to write to, must not be null * @param outputStream the stream to write to, must not be null
* *
* @throws IllegalArgumentException if <code>outputStream</code> is <code>null</code> * @throws IllegalArgumentException if {@code outputStream} is null
* @throws SerializationException (runtime) if the serialization fails * @throws SerializationException (runtime) if the serialization fails
*/ */
public static void serialize(Serializable obj, OutputStream outputStream) throws SerializationException { public static void serialize(Serializable obj, OutputStream outputStream) throws SerializationException {
@ -130,8 +129,8 @@ public final class SerializationHelper {
} }
/** /**
* <p>Serializes an <code>Object</code> to a byte array for * Serializes an object to a byte array for storage or
* storage/serialization.</p> * externalization.
* *
* @param obj the object to serialize to bytes * @param obj the object to serialize to bytes
* *
@ -149,8 +148,8 @@ public final class SerializationHelper {
//----------------------------------------------------------------------- //-----------------------------------------------------------------------
/** /**
* Deserializes an object from the specified stream using the Thread Context * Deserializes an object from the given stream using the
* ClassLoader (TCCL). * Thread Context ClassLoader (TCCL).
* <p> * <p>
* Delegates to {@link #doDeserialize} * Delegates to {@link #doDeserialize}
* *
@ -158,7 +157,7 @@ public final class SerializationHelper {
* *
* @return the deserialized object * @return the deserialized object
* *
* @throws IllegalArgumentException if <code>inputStream</code> is <code>null</code> * @throws IllegalArgumentException if {@code inputStream} is null
* @throws SerializationException (runtime) if the serialization fails * @throws SerializationException (runtime) if the serialization fails
*/ */
public static <T> T deserialize(InputStream inputStream) throws SerializationException { public static <T> T deserialize(InputStream inputStream) throws SerializationException {
@ -179,16 +178,16 @@ public final class SerializationHelper {
} }
/** /**
* Deserializes an object from the specified stream using the Thread Context * Deserializes an object from the given stream using the
* ClassLoader (TCCL). If there is no TCCL set, the classloader of the calling * Thread Context ClassLoader (TCCL). If there is no TCCL set,
* class is used. * the classloader of the calling class is used.
* <p> * <p>
* The stream will be closed once the object is read. This avoids the need * The stream will be closed once the object is read. This
* for a finally clause, and maybe also exception handling, in the application * avoids the need for a finally clause, and maybe also for
* code. * exception handling, in the application code.
* <p> * <p>
* The stream passed in is not buffered internally within this method. This is * The stream passed in is not buffered internally within this
* the responsibility of the caller, if desired. * method. This is the responsibility of the caller, if desired.
* *
* @param inputStream the serialized object input stream, must not be null * @param inputStream the serialized object input stream, must not be null
* @param loader The classloader to use * @param loader The classloader to use
@ -245,9 +244,9 @@ public final class SerializationHelper {
} }
/** /**
* Deserializes an object from an array of bytes using the Thread Context * Deserializes an object from an array of bytes using the
* ClassLoader (TCCL). If there is no TCCL set, the classloader of the calling * Thread Context ClassLoader (TCCL). If there is no TCCL set,
* class is used. * the classloader of the calling class is used.
* <p> * <p>
* Delegates to {@link #deserialize(byte[], ClassLoader)} * Delegates to {@link #deserialize(byte[], ClassLoader)}
* *
@ -290,10 +289,10 @@ public final class SerializationHelper {
/** /**
* By default, to resolve the classes being deserialized JDK serialization uses the * By default, to resolve the classes being deserialized JDK serialization uses the
* classes loader which loaded the class which initiated the deserialization call. Here * classes loader which loaded the class which initiated the deserialization call. Here
* that would be hibernate classes. However, there are cases where that is not the correct * that would be Hibernate classes. However, there are cases where that is not the correct
* class loader to use; mainly here we are worried about deserializing user classes in * class loader to use; mainly here we are worried about deserializing user classes in
* environments (app servers, etc) where Hibernate is on a parent classes loader. To * environments (app servers, etc) where Hibernate is on a parent classes loader. To
* facilitate for that we allow passing in the class loader we should use. * facilitate for that we allow passing in the class loader we should use.
*/ */
private static final class CustomObjectInputStream extends ObjectInputStream { private static final class CustomObjectInputStream extends ObjectInputStream {
@ -312,9 +311,6 @@ public final class SerializationHelper {
this.loader3 = loader3; this.loader3 = loader3;
} }
/**
* {@inheritDoc}
*/
@Override @Override
protected Class resolveClass(ObjectStreamClass v) throws IOException, ClassNotFoundException { protected Class resolveClass(ObjectStreamClass v) throws IOException, ClassNotFoundException {
final String className = v.getName(); final String className = v.getName();

View File

@ -10,9 +10,13 @@ import java.sql.Connection;
import java.sql.SQLException; import java.sql.SQLException;
/** /**
* A discrete piece of work following the lines of {@link Work} but returning a result. * A discrete piece of work making use of a {@linkplain Connection JDBC connection}
* and returning a result.
* *
* @author Steve Ebersole * @author Steve Ebersole
*
* @see Work
* @see org.hibernate.SharedSessionContract#doReturningWork(ReturningWork)
*/ */
@FunctionalInterface @FunctionalInterface
public interface ReturningWork<T> { public interface ReturningWork<T> {

View File

@ -10,9 +10,12 @@ import java.sql.Connection;
import java.sql.SQLException; import java.sql.SQLException;
/** /**
* Contract for performing a discrete piece of JDBC work. * A discrete piece of work making use of a {@linkplain Connection JDBC connection}.
* *
* @author Steve Ebersole * @author Steve Ebersole
*
* @see ReturningWork
* @see org.hibernate.SharedSessionContract#doWork(Work)
*/ */
@FunctionalInterface @FunctionalInterface
public interface Work { public interface Work {

View File

@ -6,10 +6,15 @@
*/ */
/** /**
* Abstracts certain very specific aspects of the low-level interaction between Hibernate * Defines the notion of a unit of JDBC work that may be executed by the session
* and JDBC. * at the request of the client.
* <p> * <p>
* Defines {@link org.hibernate.jdbc.Work}, {@link org.hibernate.jdbc.ReturningWork} and * Execution of a unit of work may be requested by calling
* {@link org.hibernate.jdbc.Expectation}, along with some exceptions * {@link org.hibernate.SharedSessionContract#doWork(org.hibernate.jdbc.Work)} or
* {@link org.hibernate.SharedSessionContract#doReturningWork(org.hibernate.jdbc.ReturningWork)}.
*
* @see org.hibernate.jdbc.Work
* @see org.hibernate.jdbc.ReturningWork
* @see org.hibernate.jdbc.Expectation
*/ */
package org.hibernate.jdbc; package org.hibernate.jdbc;

View File

@ -20,7 +20,7 @@ import org.hibernate.jpa.event.spi.CallbackType;
/** /**
* Keep track of all lifecycle callbacks and listeners for a given persistence unit * Keep track of all lifecycle callbacks and listeners for a given persistence unit
* *
* @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a> * @author Kabir Khan
* @author Steve Ebersole * @author Steve Ebersole
* @author Sanne Grinovero * @author Sanne Grinovero
*/ */

View File

@ -17,7 +17,7 @@ import org.hibernate.resource.beans.spi.ManagedBeanRegistry;
/** /**
* Represents a JPA callback on the entity itself * Represents a JPA callback on the entity itself
* *
* @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a> * @author Kabir Khan
* @author Steve Ebersole * @author Steve Ebersole
*/ */
final class EntityCallback extends AbstractCallback { final class EntityCallback extends AbstractCallback {

View File

@ -18,7 +18,7 @@ import org.hibernate.resource.beans.spi.ManagedBeanRegistry;
/** /**
* Represents a JPA callback using a dedicated listener * Represents a JPA callback using a dedicated listener
* *
* @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a> * @author Kabir Khan
* @author Steve Ebersole * @author Steve Ebersole
*/ */
class ListenerCallback extends AbstractCallback { class ListenerCallback extends AbstractCallback {

View File

@ -15,7 +15,7 @@ import java.io.Serializable;
* or an annotated method on a separate "listener" class. This contract presents * or an annotated method on a separate "listener" class. This contract presents
* a unified abstraction for both cases * a unified abstraction for both cases
* *
* @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a> * @author Kabir Khan
* @author Steve Ebersole * @author Steve Ebersole
*/ */
public interface Callback extends Serializable { public interface Callback extends Serializable {

View File

@ -21,8 +21,8 @@ import org.hibernate.type.descriptor.java.JavaType;
/** /**
* Base descriptor, within the mapping model, for any part of the * Base descriptor, within the mapping model, for any part of the
* application's domain model - an attribute, * application's domain model: an attribute, an entity identifier,
* an entity identifier, collection elements, etc * collection elements, and so on.
* *
* @see DomainResultProducer * @see DomainResultProducer
* @see jakarta.persistence.metamodel.Bindable * @see jakarta.persistence.metamodel.Bindable

View File

@ -7,21 +7,25 @@
package org.hibernate.proxy; package org.hibernate.proxy;
import java.io.Serializable; import java.io.Serializable;
import org.hibernate.Internal;
import org.hibernate.engine.spi.PrimeAmongSecondarySupertypes; import org.hibernate.engine.spi.PrimeAmongSecondarySupertypes;
/** /**
* Marker interface for entity proxies * Interface implemented directly by entity proxies, exposing
* access to the associated {@link LazyInitializer}.
* *
* @author Gavin King * @author Gavin King
*/ */
public interface HibernateProxy extends Serializable, PrimeAmongSecondarySupertypes { public interface HibernateProxy extends Serializable, PrimeAmongSecondarySupertypes {
/** /**
* Extract the LazyInitializer from the object, if * Extract the {@link LazyInitializer} from the given object,
* and only if the object is actually an HibernateProxy. * if and only if the object is actually a proxy. Otherwise,
* If not, null is returned. * return a null value.
* @param object any entity *
* @return either null (if object is not an HibernateProxy) or the LazyInitializer of the HibernateProxy. * @param object any reference to an entity
* @return the associated {@link LazyInitializer} if the given
* object is a proxy, or {@code null} otherwise.
*/ */
static LazyInitializer extractLazyInitializer(final Object object) { static LazyInitializer extractLazyInitializer(final Object object) {
if ( object instanceof PrimeAmongSecondarySupertypes ) { if ( object instanceof PrimeAmongSecondarySupertypes ) {
@ -42,17 +46,21 @@ public interface HibernateProxy extends Serializable, PrimeAmongSecondarySuperty
Object writeReplace(); Object writeReplace();
/** /**
* Get the underlying lazy initialization handler. * Get the {@linkplain LazyInitializer lazy initialization handler}
* for this object.
* *
* @return The lazy initializer. * @return The associated {@link LazyInitializer}.
*/ */
LazyInitializer getHibernateLazyInitializer(); LazyInitializer getHibernateLazyInitializer();
/** /**
* Special internal contract to optimize type checking * Special internal contract to optimize type checking.
*
* @see PrimeAmongSecondarySupertypes * @see PrimeAmongSecondarySupertypes
* @return this same instance *
* @return this instance
*/ */
@Internal
@Override @Override
default HibernateProxy asHibernateProxy() { default HibernateProxy asHibernateProxy() {
return this; return this;

View File

@ -10,7 +10,7 @@ import org.hibernate.HibernateException;
import org.hibernate.engine.spi.SharedSessionContractImplementor; import org.hibernate.engine.spi.SharedSessionContractImplementor;
/** /**
* Handles fetching of the underlying entity for a proxy * Handles fetching of the underlying entity for a proxy.
* *
* @author Gavin King * @author Gavin King
* @author Steve Ebersole * @author Steve Ebersole
@ -20,6 +20,8 @@ public interface LazyInitializer {
* Initialize the proxy, fetching the target entity if necessary. * Initialize the proxy, fetching the target entity if necessary.
* *
* @throws HibernateException Indicates a problem initializing the proxy. * @throws HibernateException Indicates a problem initializing the proxy.
*
* @see org.hibernate.Hibernate#initialize(Object)
*/ */
void initialize() throws HibernateException; void initialize() throws HibernateException;
@ -33,8 +35,9 @@ public interface LazyInitializer {
} }
/** /**
* Retrieve the identifier value for the entity our owning proxy represents. * Retrieve the identifier value for the entity our owning proxy represents,
* * without initializing the proxy.
* <p>
* When JPA proxy compliance is enabled the proxy is initialized. * When JPA proxy compliance is enabled the proxy is initialized.
* *
* @return The identifier value. * @return The identifier value.
@ -66,6 +69,8 @@ public interface LazyInitializer {
* Is the proxy uninitialized? * Is the proxy uninitialized?
* *
* @return True if uninitialized; false otherwise. * @return True if uninitialized; false otherwise.
*
* @see org.hibernate.Hibernate#isInitialized(Object)
*/ */
boolean isUninitialized(); boolean isUninitialized();
@ -104,10 +109,10 @@ public interface LazyInitializer {
/** /**
* Is the proxy read-only? * Is the proxy read-only?
* * <p>
* The read-only/modifiable setting is not available when the proxy is * The read-only/modifiable setting is not available when the proxy is
* detached or its associated session is closed. * detached or its associated session is closed.
* * <p>
* To check if the read-only/modifiable setting is available: * To check if the read-only/modifiable setting is available:
* *
* @return true, if this proxy is read-only; false, otherwise * @return true, if this proxy is read-only; false, otherwise
@ -126,7 +131,7 @@ public interface LazyInitializer {
* proxy is initialized, its implementation will have the same read-only/ * proxy is initialized, its implementation will have the same read-only/
* modifiable setting as the proxy. In read-only mode, no snapshot is * modifiable setting as the proxy. In read-only mode, no snapshot is
* maintained and the instance is never dirty checked. * maintained and the instance is never dirty checked.
* * <p>
* If the associated proxy already has the specified read-only/modifiable * If the associated proxy already has the specified read-only/modifiable
* setting, then this method does nothing. * setting, then this method does nothing.
* *

View File

@ -14,7 +14,7 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
import org.hibernate.type.CompositeType; import org.hibernate.type.CompositeType;
/** /**
* Contract for run-time, proxy-based lazy initialization proxies. * Contract for runtime, proxy-based lazy initialization proxies.
* *
* @author Gavin King * @author Gavin King
*/ */

View File

@ -0,0 +1,11 @@
/*
* 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 <http://www.gnu.org/licenses/lgpl-2.1.html>.
*/
/**
* Proxies for entity objects represented as Java {@linkplain java.util.Map maps}.
*/
package org.hibernate.proxy.map;

View File

@ -7,6 +7,7 @@
/** /**
* This package defines a framework for lazy-initializing entity proxies. * This package defines a framework for lazy-initializing entity proxies.
* <p>
* The interfaces here and all their implementations belong to an SPI. * The interfaces here and all their implementations belong to an SPI.
* They are not part of the public API of Hibernate, and are not meant to * They are not part of the public API of Hibernate, and are not meant to
* be used directly by typical programs which use Hibernate for persistence. * be used directly by typical programs which use Hibernate for persistence.

View File

@ -14,7 +14,7 @@ import org.hibernate.proxy.AbstractLazyInitializer;
import org.hibernate.type.CompositeType; import org.hibernate.type.CompositeType;
/** /**
* Lazy initializer for POJOs * Lazy initializer for plain Java objects.
* *
* @author Gavin King * @author Gavin King
*/ */

View File

@ -0,0 +1,11 @@
/*
* 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 <http://www.gnu.org/licenses/lgpl-2.1.html>.
*/
/**
* Proxies for plain Java objects.
*/
package org.hibernate.proxy.pojo;

View File

@ -13,7 +13,7 @@ import org.hibernate.query.sqm.tree.domain.SqmPath;
import org.hibernate.query.sqm.tree.expression.SqmExpression; import org.hibernate.query.sqm.tree.expression.SqmExpression;
/** /**
* Specialized "intermediate" SemanticPathPart for processing domain model paths * Specialized "intermediate" SemanticPathPart for processing domain model paths/
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -17,7 +17,7 @@ import org.antlr.v4.runtime.CommonTokenStream;
import org.antlr.v4.runtime.Token; import org.antlr.v4.runtime.Token;
/** /**
* Leverages Antlr to build a parse tree from an HQL query * Leverages ANTLR to build a parse tree from an HQL query.
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -30,7 +30,7 @@ import org.hibernate.query.sqm.tree.from.SqmRoot;
import org.jboss.logging.Logger; import org.jboss.logging.Logger;
/** /**
* Specialized "intermediate" SemanticPathPart for processing domain model paths * Specialized "intermediate" SemanticPathPart for processing domain model paths.
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -24,7 +24,7 @@ import org.hibernate.query.sqm.tree.select.SqmSubQuery;
/** /**
* Specialized consumer for processing domain model paths occurring as part * Specialized consumer for processing domain model paths occurring as part
* of a join predicate * of a join predicate.
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -245,7 +245,7 @@ import static org.hibernate.type.spi.TypeConfiguration.isJdbcTemporalType;
/** /**
* Responsible for producing an SQM using visitation over an HQL parse tree generated by * Responsible for producing an SQM using visitation over an HQL parse tree generated by
* Antlr via {@link HqlParseTreeBuilder}. * ANTLR via {@link HqlParseTreeBuilder}.
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -33,7 +33,7 @@ import org.antlr.v4.runtime.dfa.DFA;
import org.antlr.v4.runtime.misc.ParseCancellationException; import org.antlr.v4.runtime.misc.ParseCancellationException;
/** /**
* Standard implementation of SemanticQueryInterpreter * Standard implementation of {@link HqlTranslator}.
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

View File

@ -0,0 +1,11 @@
/*
* 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 http://www.gnu.org/licenses/lgpl-2.1.html
*/
/**
* Implementation of the SPIs for HQL support.
*/
package org.hibernate.query.hql.internal;

View File

@ -6,11 +6,30 @@
*/ */
/** /**
* Package defining support for HQL queries (including supprt for JPQL * Package defining support for HQL, including JPQL as a subset of HQL.
* as a subset of HQL).
* <p> * <p>
* This includes transformation via Antlr, {@link org.hibernate.query.Query} * Concerns handled by subpackages include:
* manipulation and execution * <ul>
* <li>query language transformation via ANTLR, and
* <li>query execution via an instance of {@link org.hibernate.query.Query}.
* </ul>
* <p>
* Translation of HQL to SQL involves the following steps:
* <ul>
* <li>First, the ANTLR-generated
* {@link org.hibernate.grammars.hql.HqlLexer tokenizer} and
* {@link org.hibernate.grammars.hql.HqlParser parser} work
* in series to parse the text of the query and produce an AST.
* <li>Next, {@link org.hibernate.query.hql.internal.SemanticQueryBuilder}
* translates the AST into an instance of the SQM (Semantic Query
* Model) defined in {@link org.hibernate.query.sqm}.
* <li>Next, {@link org.hibernate.query.sqm.sql.internal.StandardSqmTranslator}
* transforms the SQM tree and produces a SQL AST, an instance of
* the syntax tree defined by {@link org.hibernate.sql.ast.tree}.
* <li>Finally, a SQL dialect-specific implementation of
* {@link org.hibernate.sql.ast.SqlAstTranslator} produces an
* executable SQL statement.
* </ul>
* *
* @see org.hibernate.query.hql.HqlTranslator * @see org.hibernate.query.hql.HqlTranslator
* @see org.hibernate.query.hql.spi.SqmQueryImplementor * @see org.hibernate.query.hql.spi.SqmQueryImplementor

View File

@ -0,0 +1,11 @@
/*
* 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 http://www.gnu.org/licenses/lgpl-2.1.html
*/
/**
* SPIs for HQL support.
*/
package org.hibernate.query.hql.spi;

View File

@ -0,0 +1,16 @@
/*
* 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 http://www.gnu.org/licenses/lgpl-2.1.html
*/
/**
* Support SQL functions in the SQM model.
*
* @see org.hibernate.query.sqm.function.SqmFunctionDescriptor
*/
@Incubating
package org.hibernate.query.procedure;
import org.hibernate.Incubating;

View File

@ -7,8 +7,8 @@
/** /**
* Support for immutable result/fetch builder graph nodes built from static sources * Support for immutable result/fetch builder graph nodes built from static sources
* such as JPA's {@link jakarta.persistence.SqlResultSetMapping} or `hbm.xml` mapping * such as {@link jakarta.persistence.SqlResultSetMapping} or the {@code hbm.xml}
* {@code <resultset/>}. * mapping element {@code <resultset/>}.
* <p> * <p>
* The differentiation from {@link org.hibernate.query.results.dynamic} is that here * The differentiation from {@link org.hibernate.query.results.dynamic} is that here
* we have up-front knowledge of the complete mapping graph and can perform optimized * we have up-front knowledge of the complete mapping graph and can perform optimized

View File

@ -6,18 +6,20 @@
*/ */
/** /**
* Support for defining result-set mappings used in {@link org.hibernate.query.NativeQuery} * Support for defining result set mappings used in {@link org.hibernate.query.NativeQuery},
* and {@link org.hibernate.procedure.ProcedureCall} / {@link jakarta.persistence.StoredProcedureQuery}. * {@link org.hibernate.procedure.ProcedureCall}, and {@link jakarta.persistence.StoredProcedureQuery}.
* These result-set mappings are used to map the values in the JDBC {@link java.sql.ResultSet} * These result set mappings are used to map the values in the JDBC {@link java.sql.ResultSet} into
* into the query result graph. * the query result graph.
* <p> * <p>
* Handling the different sources of results and fetches is split into multiple packages and * Subpackages handle different sources of result set mappings:
* multiple impls for performance reasons. The classes in {@link org.hibernate.query.results.complete} * <ul>
* represent result/fetch definitions that are completely known up-front and are faster to * <li>{@link org.hibernate.query.results.complete} handles result set mappings which are completely
* resolve. The definitions in {@link org.hibernate.query.results.dynamic} are built incrementally * known upfront and are faster to resolve.
* via Hibernate's {@link org.hibernate.query.NativeQuery} contract need to resolve themselves * <li>{@link org.hibernate.query.results.dynamic} handles result set mappings which are defined
* against other dynamic result/fetch definitions and therefore take more resources to resolve. * incrementally via the {@link org.hibernate.query.NativeQuery} interface and need to resolve
* The classes in {@link org.hibernate.query.results.implicit} represent results that are implied. * themselves against other dynamic mappings. These take more resources to resolve.
* <li>{@link org.hibernate.query.results.implicit} handles implicit result set mappings.
* </ul>
* *
* @see org.hibernate.query.results.ResultSetMapping * @see org.hibernate.query.results.ResultSetMapping
* *

View File

@ -0,0 +1,11 @@
/*
* 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 http://www.gnu.org/licenses/lgpl-2.1.html
*/
/**
* Implementation of the SPIs for native SQL query support.
*/
package org.hibernate.query.sql.internal;

View File

@ -6,7 +6,7 @@
*/ */
/** /**
* Package defining support for native SQL queries * Package defining support for native SQL queries.
* *
* @see org.hibernate.query.NativeQuery * @see org.hibernate.query.NativeQuery
* @see org.hibernate.query.sql.spi.NativeQueryImplementor * @see org.hibernate.query.sql.spi.NativeQueryImplementor

View File

@ -0,0 +1,11 @@
/*
* 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 http://www.gnu.org/licenses/lgpl-2.1.html
*/
/**
* SPIs for native SQL query support.
*/
package org.hibernate.query.sql.spi;

Some files were not shown because too many files have changed in this diff Show More