HHH-14928 - Document CDI integration

documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc

@@ -28,6 +28,7 @@ include::chapters/query/native/Native.adoc[]
 include::chapters/query/spatial/Spatial.adoc[]
 include::chapters/multitenancy/MultiTenancy.adoc[]
 include::chapters/envers/Envers.adoc[]
+include::chapters/beans/Beans.adoc[]
 include::chapters/portability/Portability.adoc[]
 include::chapters/statistics/Statistics.adoc[]
 

documentation/src/main/asciidoc/userguide/chapters/beans/Beans.adoc

@@ -0,0 +1,90 @@
+[[beans]]
+== Managed Beans
+:rootProjectDir: ../../../../../../..
+:sourcedir: ../../../../../test/java/org/hibernate/userguide/beans
+:coreProjectDir: {rootProjectDir}/hibernate-core
+:coreTestSrcDir: {rootProjectDir}/hibernate-core/src/test/java
+:instantiatorTestDir: {coreTestSrcDir}/org/hibernate/orm/test/mapping/embeddable/strategy/instantiator
+:extrasdir: extras
+
+Hibernate supports consuming many of its extension points as "managed beans".  A bean being
+managed simply means that its creation and lifecycle are managed by a container of some sort.
+
+The main contract for managed beans is `org.hibernate.resource.beans.spi.ManagedBeanRegistry`
+
+Often these beans are managed by an external service, such as CDI.  The contract
+`org.hibernate.resource.beans.container.spi.BeanContainer` is used to integrate the
+external container. `ManagedBeanRegistry` integrates support for a `BeanContainer`
+if one is specified.
+
+By default, Hibernate creates references to the beans and links their lifecycle to
+the SessionFactory.  It supports a number of ways to influence how this process works.
+
+[[beans-cdi]]
+=== CDI Beans
+
+Hibernate provides built-in support for CDI as the `BeanContainer`.  Jakarta Persistence
+indicates that the setting `jakarta.persistence.bean.manager` be used to pass along a
+CDI `BeanManager` to use.
+
+Hibernate can use this `BeanManager` in a number of ways
+
+[[beans-cdi-default]]
+==== CDI Beans - default
+
+By default, Hibernate follows the Jakarta Persistence requirements for using
+CDI `BeanManager`.  Most importantly, this means accessing beans from the `BeanManager`
+immediately during bootstrap.
+
+In many cases this can cause circularity problems as CDI is often a consumer of
+persistence as well.  In such cases, <<beans-cdi-delayed,delayed>>
+or <<beans-cdi-extended,extended>> access should be used
+
+
+[[beans-cdi-delayed]]
+==== CDI Beans - delayed
+
+Rather than accessing the CDI managed beans immediately, Hibernate can be configured
+to delay accessing the beans until first needed using `hibernate.delay_cdi_access`.
+
+
+[[beans-cdi-extended]]
+==== CDI Beans - extended
+
+Sometimes the actual `BeanManager` instance is not known until after Hibernate
+has been bootstrapped.
+
+For such cases, Hibernate provides the `org.hibernate.resource.beans.container.spi.ExtendedBeanManager`
+contract, which is basically a "promise" for a `BeanManager` reference.
+
+An instance of `ExtendedBeanManager` passed as `jakarta.persistence.bean.manager` triggers this behavior.
+
+The `ExtendedBeanManager` implementation accepts the `LifecycleListener` passed to its
+`#registerLifecycleListener` method.  It will call `LifecycleListener#beanManagerInitialized`
+and `LifecycleListener#beforeBeanManagerDestroyed` as lifecycle callbacks for the real
+`BeanManager`.
+
+Hibernate uses the `LifecycleListener#beanManagerInitialized` callback to get access to the
+real `BeanManager`.
+
+NOTE: When used in WildFly, this is all automatically set up by the server
+
+[[beans-custom-container]]
+=== Custom BeanContainer
+
+Other containers (Spring, e.g.) can also be used and integrated by implementing `BeanContainer` and
+declaring it using `hibernate.resource.beans.container`.
+
+
+[[beans-manageable]]
+=== Manageable Beans
+
+Hibernate supports using the following integrations as managed beans:
+
+* `jakarta.persistence.AttributeConverter`
+* Jakarta Persistence "entity listener" classes
+* `org.hibernate.type.descriptor.jdbc.JdbcType`
+* `org.hibernate.type.descriptor.java.BasicJavaType`
+* `org.hibernate.type.descriptor.java.MutabilityPlan`
+* `org.hibernate.metamodel.spi.EmbeddableInstantiator`
+* `org.hibernate.envers.RevisionListener`