Add doc page about the CDI Extension SPI

modules/ROOT/pages/cdi-extension-user-feature.adoc

@@ -0,0 +1,67 @@
+// Copyright (c) 2024 IBM Corporation and others.
+// Licensed under Creative Commons Attribution-NoDerivatives
+// 4.0 International (CC BY-ND 4.0)
+//   https://creativecommons.org/licenses/by-nd/4.0/
+//
+// Contributors:
+//     IBM Corporation
+//
+:page-description:
+:seo-title: Creating a CDI Extension inside a User Feature
+:seo-description:
+:page-layout: general-reference
+:page-type: general
+= Creating a CDI Extension inside a User Feature
+
+Contexts and Dependency Injection (CDI) provides powerful extensions to augment, extend, or override the behaviour of CDI. If you wish for the extensions inside a Open Liberty User Feature to be found by CDI you must implement an Open Liberty specific SPI: `io.openliberty.cdi.spi.CDIExtensionMetadata`.
+
+`CDIExtensionMetadata` also provides syntactic sugar for the two most common uses of a CDI Extension: Registering a class as a CDI bean, and registering an annotation as a Bean Defining Annotation (BDA).
+
+Here is an example of an implementation of `CDIExtensionMetadata`.
+
+
+[source,java]
+----
+package com.ibm.example.cdi;
+
+import static org.osgi.service.component.annotations.ConfigurationPolicy.IGNORE;
+
+import java.util.Set;
+import jakarta.enterprise.inject.spi.Extension;
+
+import io.openliberty.cdi.spi.CDIExtensionMetadata;
+import org.osgi.service.component.annotations.Component;
+
+@Component(service = CDIExtensionMetadata.class, configurationPolicy = IGNORE)
+public class CDIIntegrationMetaData implements CDIExtensionMetadata
+{
+    public Set<Class<?>> getBeanClasses() {
+        //CDIBean will become a CDI bean and can be injected with `@Inject CDIBean cdiBean`. If it does not have a scope, the scope will default to @Dependent.
+        return Set.of(CDIBean.class);
+    }
+
+    public Set<Class<? extends Annotation>> getBeanDefiningAnnotationClasses() {
+        //CDIAnnotation will become a BeanDefiningAnnotation. Any class annotated @Annotation can be injected via CDI. 
+        //Unless CDIAnnotation defines otherwise, the default scope is @Dependent. See https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#scopes 
+        //For details on how annotations define their scope.
+        return Set.of(CDIAnnotation.class);
+    }
+
+    public Set<Class<? extends Extension>> getExtensions() {
+        //CDIExtension will be processed as a full CDI extension. 
+        return Set.of(CDIExtension.class);
+    }
+
+}
+----
+
+The `@Component` annotation is required so that Open Liberty will process your implementation of CDIExtensionMetadata. The three methods all have a default implementation that returns an empty set, so you only have to implement the ones relevent to your needs.
+
+And this is all you need to make your user extension extend CDI. If you want a step by step guide to creating a user feature that extends CDI from scratch see the link below.
+
+
+= Useful Links
+Javadoc for `CDIExtensionMetadata` can be found at: https://openliberty.io/docs/latest/reference/javadoc/spi/cdi-1.2.html?path=24.0.0.8/com.ibm.websphere.appserver.spi.cdi_1.1-javadoc/io/openliberty/cdi/spi/package-summary.html
+
+A step by step guide to creating a user feature, including an implementation of `CDIExtensionMetadata`, can be found at: https://openliberty.io/blog/2024/06/28/liberty-user-feature-tutorial.html
+