Squashable commit; adding documentation and supporting cruft

Signed-off-by: Laird Nelson <laird.nelson@oracle.com>

all/pom.xml

@@ -569,6 +569,10 @@
             <groupId>io.helidon.integrations.db</groupId>
             <artifactId>helidon-integrations-db-mysql</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.helidon.integrations.cdi</groupId>
+            <artifactId>helidon-integrations-cdi-configurable</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.helidon.integrations.cdi</groupId>
             <artifactId>helidon-integrations-cdi-delegates</artifactId>

dependencies/pom.xml

@@ -127,7 +127,8 @@
         <version.lib.neo4j>5.12.0</version.lib.neo4j>
         <version.lib.netty>4.1.100.Final</version.lib.netty>
         <version.lib.oci>3.31.1</version.lib.oci>
-        <version.lib.ojdbc8>21.4.0.0</version.lib.ojdbc8>
+        <version.lib.ojdbc.family>21</version.lib.ojdbc.family>
+        <version.lib.ojdbc8>${version.lib.ojdbc.family}.4.0.0</version.lib.ojdbc8>
         <!-- Force upgrade okio for CVE-2023-3635. When okhttp 4.12.0 is available we can remove this -->
         <version.lib.okio>3.4.0</version.lib.okio>
         <!-- Force upgrade okhttp3 for CVE-2023-0833 -->

etc/javadoc/ojdbc/element-list

@@ -0,0 +1,12 @@
+oracle.jdbc
+oracle.jdbc.aq
+oracle.jdbc.babelfish
+oracle.jdbc.datasource
+oracle.jdbc.datasource.impl
+oracle.jdbc.dcn
+oracle.jdbc.pool
+oracle.jdbc.replay
+oracle.jdbc.xa
+oracle.jdbc.xa.client
+oracle.sql
+oracle.sql.json

etc/javadoc/ucp/element-list

@@ -0,0 +1,5 @@
+oracle.ucp
+oracle.ucp.admin
+oracle.ucp.jdbc
+oracle.ucp.jdbc.oracle
+oracle.ucp.util.logging

integrations/cdi/datasource-ucp/src/main/java/io/helidon/integrations/datasource/ucp/cdi/UniversalConnectionPoolExtension.java

@@ -39,6 +39,49 @@
  * An {@link AbstractConfigurableExtension} that provides injection support for {@link UniversalConnectionPoolManager}
  * and {@link UniversalConnectionPool} instances.
  *
+ * <p>As with all portable extensions, to begin to make use of the features enabled by this class, ensure its containing
+ * artifact (normally a jar file) is on the classpath of your CDI-enabled application.</p>
+ *
+ * <p>To support injection of the {@link UniversalConnectionPoolManager}, use normal CDI injection idioms:</p>
+ *
+ * {@snippet :
+ *   // Inject the UniversalConnectionPoolManager into a private field named ucpManager:
+ *   @jakarta.inject.Inject
+ *   private oracle.ucp.admin.UniversalConnectionPoolManager ucpManager;
+ *   }
+ *
+ * <p>To support injection of a {@link UniversalConnectionPool} named {@code test}, first ensure that enough MicroProfile
+ * Config configuration is present to create a valid {@link PoolDataSource}. For example, the following sample system
+ * properties are sufficient for a {@link PoolDataSource} named {@code test} to be created:</p>
+ *
+ * {@snippet lang="properties" :
+ *   # @link substring="oracle.ucp.jdbc.PoolDataSource" target="PoolDataSource" @link substring="oracle.jdbc.pool.OracleDataSource" target="oracle.jdbc.pool.OracleDataSource" :
+ *   oracle.ucp.jdbc.PoolDataSource.test.connectionFactoryClassName=oracle.jdbc.pool.OracleDataSource
+ *   oracle.ucp.jdbc.PoolDataSource.test.URL=jdbc:oracle:thin://@localhost:1521/XE
+ *   oracle.ucp.jdbc.PoolDataSource.test.user=scott
+ *   oracle.ucp.jdbc.PoolDataSource.test.password=tiger
+ *   }
+ *
+ * <p>See the {@link UCPBackedDataSourceExtension} documentation for more information about how {@link PoolDataSource}
+ * instances are made eligible for injection from configuration such as this.</p>
+ *
+ * <p>With configuration such as the above, you can now inject the implicit {@link UniversalConnectionPool} it also
+ * defines:</p>
+ *
+ * {@snippet :
+ *   // Inject a UniversalConnectionPool whose getName() method returns test into a private field named ucp:
+ *   @jakarta.inject.Inject
+ *   @jakarta.inject.Named("test")
+ *   private oracle.ucp.UniversalConnectionPool ucp; // assert "test".equals(ucp.getName());
+ *   }
+ *
+ * <p><strong>Note:</strong> Working directly with a {@link UniversalConnectionPool} is for advanced use cases
+ * only. Injecting and working with {@link PoolDataSource} instances is much more common, and {@link PoolDataSource} is
+ * the interface recommended by Oracle's documentation for users to interact with. See {@link
+ * UCPBackedDataSourceExtension}'s documentation for more details.</p>
+ *
+ * @see UniversalConnectionPool
+ *
  * @see UCPBackedDataSourceExtension
  */
 public class UniversalConnectionPoolExtension extends AbstractConfigurableExtension<UniversalConnectionPool> {

integrations/cdi/datasource-ucp/src/main/java/module-info.java

@@ -26,6 +26,7 @@
 @SuppressWarnings({ "requires-automatic"})
 module io.helidon.integrations.datasource.ucp.cdi {
 
+    requires com.oracle.database.jdbc; // com.oracle.database.ucp needs this (!)
     requires com.oracle.database.ucp;
     requires java.desktop; // For java.beans
     requires java.naming; // PoolDataSourceImpl implements javax.naming.Referenceable

pom.xml

@@ -165,6 +165,8 @@
         <javadoc.link.narayana>https://narayana.io/docs/api/</javadoc.link.narayana>
         <javadoc.link.eclipselink>https://www.eclipse.org/eclipselink/api/4.0/</javadoc.link.eclipselink>
         <javadoc.link.hibernate>https://docs.jboss.org/hibernate/orm/${version.lib.hibernate.family}/javadocs/</javadoc.link.hibernate>
+        <javadoc.link.ojdbc>https://docs.oracle.com/en/database/oracle/oracle-database/${version.lib.ojdbc.family}/jajdb/</javadoc.link.ojdbc>
+        <javadoc.link.ucp>https://docs.oracle.com/en/database/oracle/oracle-database/${version.lib.ojdbc.family}/jjuar/</javadoc.link.ucp>
 
         <javadoc.jackson.version>2.14</javadoc.jackson.version>
         <javadoc.link.jackson-annotations>https://fasterxml.github.io/jackson-annotations/javadoc/${javadoc.jackson.version}/</javadoc.link.jackson-annotations>
@@ -399,6 +401,14 @@
                                 <url>${javadoc.link.hibernate}</url>
                                 <location>${javadoc.pkg.dir}/hibernate</location>
                             </offlineLink>
+                            <offlineLink>
+                                <url>${javadoc.link.ojdbc}</url>
+                                <location>${javadoc.pkg.dir}/ojdbc</location>
+                            </offlineLink>
+                            <offlineLink>
+                                <url>${javadoc.link.ucp}</url>
+                                <location>${javadoc.pkg.dir}/ucp</location>
+                            </offlineLink>
                         </offlineLinks>
                         <additionalJOptions combine.children="append">
                             <additionalJOption>-J-Dhttp.agent=maven-javadoc-plugin</additionalJOption>