completey rewrite the javadoc I just wrote and pushed

ooops, I suck :-(
This commit is contained in:
Gavin 2022-11-21 18:58:25 +01:00 committed by Gavin King
parent a72c8744a8
commit 5160ac3192
2 changed files with 57 additions and 41 deletions

View File

@ -29,26 +29,30 @@ import java.lang.annotation.Target;
* of the association.
* </ul>
* By default, an unfetched lazy association is represented
* by a <em>proxy object</em>. This approach comes with the
* major advantage that the program may obtain the identifier
* (foreign key) of the associated entity instance without
* fetching it from the database. Since a proxy carries a
* foreign key, it's even possible to set an association
* using an unfetched proxy. On the other hand, for a
* polymorphic association, the concrete type of the entity
* instance represented by a proxy is unknown, and so
* {@link org.hibernate.Hibernate#getClass(Object)} must
* by a <em>proxy object</em> which holds the identifier
* (foreign key) of the associated entity instance.
* It's possible to obtain the identifier from an unfetched
* proxy, without fetching the entity from the database, by
* calling the corresponding getter method. (It's even
* possible to set an association to reference an unfetched
* proxy.) Lazy fetching occurs when any other method of the
* proxy is called. Once fetched, the proxy delegates all
* method invocations to the fetched entity instance.
* For a polymorphic association, the concrete type of the
* entity instance represented by a proxy is unknown, and
* so {@link org.hibernate.Hibernate#getClass(Object)} must
* be used to obtain the concrete type, fetching the entity
* by side effect.
* by side effect. Similarly, typecasts must be performed
* using {@link org.hibernate.Hibernate#unproxy(Object, Class)}.
* <p>
* With {@code LazyToOne(NO_PROXY)}, lazy fetching occurs
* when the field holding the reference to the associated
* entity is accessed. With this approach, it's impossible
* to obtain the identifier of the associated entity without
* fetching the entity from the database. On the other hand,
* {@code instanceof} and {@link Object#getClass()} work as
* normal, since the concrete type of the entity instance is
* known immediately. This is usually bad tradeoff.
* With {@code LazyToOne(NO_PROXY)}, an associated entity
* instance begins in an unloaded state, with only its
* identifier field set. Thus, it's possible to obtain the
* identifier if an unloaded entity, without triggering
* lazy loading. Typecasts, {@code instanceof}, and
* {@link Object#getClass()} work as normal. But this
* option is only available when bytecode enhancement is
* used.
* <p>
* <strong>Currently, Hibernate does not support
* {@code LazyToOne(NO_PROXY)} for polymorphic associations,

View File

@ -19,40 +19,52 @@ package org.hibernate.annotations;
public enum LazyToOneOption {
/**
* The association is always loaded eagerly. The identifier
* and concrete type of the associated entity instance are
* always known immediately.
* and concrete type of the associated entity instance,
* along with all the rest of its non-lazy fields, are always
* available immediately.
*/
FALSE,
/**
* The association is proxied and loaded lazily, by
* intercepting calls on the proxy object.
* The association is proxied and a delegate entity instance
* is lazily fetched when any method of the proxy other than
* the getter method for the identifier property is first
* called.
* <ul>
* <li>The program may obtain the entity identifier value
* <li>The identifier property of the proxy object is set
* when the proxy is instantiated.
* The program may obtain the entity identifier value
* of an unfetched proxy, without triggering lazy
* fetching.
* <li>For a polymorphic association, the proxy does not
* have the concrete type of the proxied instance, and
* so {@link org.hibernate.Hibernate#getClass(Object)}
* must be used in place of {@link Object#getClass()}
* and the Java {@code instanceof} operator.
* fetching, by calling the corresponding getter method.
* <li>The proxy does not have the same concrete type as the
* proxied delegate, and so
* {@link org.hibernate.Hibernate#getClass(Object)}
* must be used in place of {@link Object#getClass()}.
* <li>For a polymorphic association, the concrete type of
* the proxied entity instance is not known until the
* delegate is fetched from the database, and so
* {@link org.hibernate.Hibernate#unproxy(Object, Class)}}
* must be used to perform typecasts, and
* {@link org.hibernate.Hibernate#getClass(Object)}
* must be used instead of the Java {@code instanceof}
* operator.
* </ul>
*/
PROXY,
/**
* The association is loaded lazily when the field holding
* the reference to the associated object is first accessed.
* The associated entity instance is initially in an unloaded
* state, and is loaded lazily when any field other than the
* field containing the identifier is first accessed.
* <ul>
* <li>There is no way for the program to obtain the
* identifier of the associated entity without triggering
* lazy fetching, and therefore this option is not
* recommended.
* <li>On the other hand, {@link Object#getClass()} and the
* {@code instanceof} operator may be used even if the
* association is polymorphic.
* <li>The identifier field of an unloaded entity instance is
* set when the unloaded instance is instantiated.
* The program may obtain the identifier of an unloaded
* entity, without triggering lazy fetching, by accessing
* the field containing the identifier.
* <li>Typecasts, the Java {@code instanceof} operator, and
* {@link Object#getClass()} may be used as normal.
* <li>Bytecode enhancement is required. If the class is not
* enhanced, this option is equivalent to {@link #PROXY}.
* </ul>
* Bytecode enhancement is required. If the class is not
* enhanced, this option is equivalent to {@link #PROXY}.
* <p>
* <strong>Currently, Hibernate does not support this setting
* for polymorphic associations, and instead falls back to
* {@link #PROXY}!</strong>