There are four kinds of names defined by this extension:
+ * + *As with all CDI portable extensions, this class' instances are not safe for concurrent use by multiple + * threads.
+ * + * @paramImplementations of this method must not return {@code null}.
+ * + *Given a {@link String} that is a configuration property name, like
+ * com.foo.Bar.name.propertyName, any implementation of this method must return a
+ * non-{@code null} {@link Matcher} that is capable of being supplied to the {@link #name(Matcher)} and {@link
+ * #propertyName(Matcher)} methods.
Implementations of this method may return {@code null}.
+ * + * @param configPropertyNameMatcher a {@link Matcher} produced by the {@link #matcher(String)} method; must not be + * {@code null} + * + * @return a name, or {@code null} + * + * @exception NullPointerException if {@code configPropertyNameMatcher} is {@code null} + * + * @see #matcher(String) + */ + protected abstract String name(Matcher configPropertyNameMatcher); + + /** + * Given a {@link Matcher} that has been produced by the {@link #matcher(String)} method, returns the relevant + * property name, or {@code null} if there is no such property name. + * + *Most implementations of this method will use the {@link Matcher#group(int)} method to produce the required + * property name.
+ * + *Implementations of this method may return {@code null}.
+ * + * @param configPropertyNameMatcher a {@link Matcher} produced by the {@link #matcher(String)} method; must not be + * {@code null} + * + * @return a property name, or {@code null} + * + * @exception NullPointerException if {@code configPropertyNameMatcher} is {@code null} + * + * @see #matcher(String) + */ + protected abstract String propertyName(Matcher configPropertyNameMatcher); + + /** + * Called internally to permit subclasses to add a {@code T}-typed bean, qualified with at least the supplied {@link + * Named}, using the supplied {@link BeanConfigurator}. + * + *Implementations of this method will be called from an observer method that is observing the {@link + * AfterBeanDiscovery} container lifecycle event.
+ * + * @param beanConfigurator the {@link BeanConfigurator} to use to actually add a new bean; must not be {@code null} + * + * @param name a {@link Named} instance qualifying the {@code T}-typed bean to be added; may be {@code + * null} + * + * @param properties a {@link Properties} instance containing properties relevant to the object; must not be {@code + * null} + * + * @exception NullPointerException if {@code beanConfigurator} or {@code properties} is {@code null} + * + * @see AfterBeanDiscovery + */ + protected abstract void addBean(BeanConfiguratorOptional} if no such configuration property value
+ * exists.
+ *
+ * This method never returns {@code null}.
+ * + *Overrides of this method must not return {@code null}.
+ * + * @param configPropertyName a configuration property name; must not be {@code null} + * + * @return a non-{@code null} {@link Optional} + * + * @exception NullPointerException if {@code configPropertyName} is {@code null} + */ + protected OptionalThis method never returns {@code null}.
+ * + *The {@link Set} returned by this method is {@linkplain Collections#unmodifiableSet(Set) unmodifiable}.
+ * + * @return a non-{@code null}, {@linkplain Collections#unmodifiableSet(Set) unmodifiableSet} of known
+ * names
+ */
+ protected final SetThis method may return {@code null}.
+ * + * @param name the name of the object under which the supplied {@link Properties} will be indexed; may be + * {@code null} + * + * @param properties the {@link Properties} to put consisting of property names and their values; must not be {@code + * null} + * + * @return the prior {@link Properties} indexed under the supplied {@code name}, or {@code null} + * + * @exception NullPointerException if {@code properties} is {@code null} + */ + protected final Properties put(String name, Properties properties) { + return this.explicitlySetProperties.put(name, Objects.requireNonNull(properties, "properties")); + } + + /** + * {@linkplain Map#clear() Clears}, and then builds or rebuilds, an internal set of properties + * whose contents will be processed eventually by the {@link #addBean(BeanConfigurator, Named, Properties)} method. + * + *If no subclass explicitly calls this method, as is common, it will be called by the {@link + * #addBean(BeanConfigurator, Named, Properties)} method just prior to its other activities.
+ * + *Once the {@link #addBean(BeanConfigurator, Named, Properties)} method has run to completion, while this method + * may be called freely, its use is discouraged and its effects will no longer be used.
+ * + * @see #addBean(BeanConfigurator, Named, Properties) + */ + protected final void initializeNamedProperties() { + this.namedProperties.clear(); + Set allConfigPropertyNames = this.configPropertyNames(); + if (!allConfigPropertyNames.isEmpty()) { + for (String configPropertyName : allConfigPropertyNames) { + OptionalThis method never returns {@code null}.
+ * + *Overrides of this method must not return {@code null}.
+ * + *The {@link Set} returned by this method is {@linkplain Collections#unmodifiableSet(Set) unmodifiable}.
+ * + *Overrides of this method must ensure that the returned {@link Set} is {@linkplain + * Collections#unmodifiableSet(Set) unmodifiable}.
+ * + *The {@link Set} returned by this method is not safe for concurrent use by multiple threads.
+ * + *Overrides of this method may return {@link Set} instances that are not safe for concurrent use by multiple + * threads.
+ * + *The {@link Set} returned by this method and its overrides may be {@linkplain Set#isEmpty() empty}.
+ * + *The ordering of the elements contained by the {@link Set} returned by this method and its overrides is + * indeterminate.
+ * + * @return a non-{@code null}, {@linkplain Collections#unmodifiableSet(Set) unmodifiableSet} of all
+ * known configuration property names
+ */
+ protected SetAs 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 runtime classpath of your CDI-enabled application.
+ * *In accordance with the CDI specification, instances of this class are not necessarily safe for concurrent use by * multiple threads.
+ * + *To support injection of a {@linkplain PoolDataSource Universal Connection Pool-backed PoolDataSource}
+ * 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:
With configuration such as the above, you can now inject the implicit {@link PoolDataSource} it defines:
+ * + * {@snippet : + * // Inject a PoolDataSource qualified with the name test into a private javax.sql.DataSource-typed field named ds: + * @jakarta.inject.Inject // @link substring="jakarta.inject.Inject" target="jakarta.inject.Inject" + * @jakarta.inject.Named("test") // @link substring="jakarta.inject.Named" target="jakarta.inject.Named" + * private javax.sql.DataSource ds; // @link substring="javax.sql.DataSource" target="DataSource" + * } */ public class UCPBackedDataSourceExtension extends AbstractDataSourceExtension { - private static final Pattern DATASOURCE_NAME_PATTERN = + /** + * A {@link Pattern} capable of producing {@link Matcher} instances that identify certain portions of a + * configuration property name. + */ + static final Pattern DATASOURCE_NAME_PATTERN = Pattern.compile("^(?:javax\\.sql\\.|oracle\\.ucp\\.jdbc\\.Pool)(XA)?DataSource\\.([^.]+)\\.(.*)$"); // Capturing groups: (1 ) (2 ) (3 ) - // Are we XA? DS name DS Property + // Are we XA? DS name DS property name private final MapAs 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 runtime classpath of your CDI-enabled application.
+ * + *To support injection of the {@link UniversalConnectionPoolManager}, use normal CDI injection idioms:
+ * + * {@snippet : + * // Inject the UniversalConnectionPoolManager into a private field named ucpManager: + * @jakarta.inject.Inject // @link substring="jakarta.inject.Inject" target="jakarta.inject.Inject" + * private oracle.ucp.admin.UniversalConnectionPoolManager ucpManager; + * } + * + *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:
+ * + * {@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 + * } + * + *See the {@link UCPBackedDataSourceExtension} documentation for more information about how {@link PoolDataSource} + * instances are made eligible for injection from configuration such as this.
+ * + *With configuration such as the above, you can now inject the implicit {@link UniversalConnectionPool} it also + * defines:
+ * + * {@snippet : + * // Inject a UniversalConnectionPool whose getName() method returns test into a private field named ucp: + * @jakarta.inject.Inject // @link substring="jakarta.inject.Inject" target="jakarta.inject.Inject" + * @jakarta.inject.Named("test") // @link substring="jakarta.inject.Named" target="jakarta.inject.Named" + * private oracle.ucp.UniversalConnectionPool ucp; // assert "test".equals(ucp.getName()); + * } + * + *Note: 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.
+ * + * @see UniversalConnectionPool + * + * @see UCPBackedDataSourceExtension + */ +public class UniversalConnectionPoolExtension extends AbstractConfigurableExtensionAs with all CDI portable extensions, this class' instances are - * not safe for concurrent use by multiple threads.
+ *As with all CDI portable extensions, this class' instances are not safe for concurrent use by multiple + * threads.
*/ -public abstract class AbstractDataSourceExtension implements Extension { - - private final MapThis method never returns {@code null}.
+ * + *This method exists for backwards compatibility only and its usage is discouraged.
+ * + * @return a non-{@code null} {@link Config} instance + * + * @deprecated This method exists for backwards compatibility only and has no replacement. + */ + @Deprecated // For backwards compatibility only. + protected final Config getConfig() { + return this.config; + } + + /** + * Calls the {@link #configPropertyNames()} method and returns its return value. + * + *This method never returns {@code null}.
+ * + *This method exists for backwards compatibility only and the {@link #configPropertyNames()} method is + * preferred.
+ * + * @return the return value of an invocation of the {@link #configPropertyNames()} method + * + * @see #configPropertyNames() + * + * @deprecated This method exists for backwards compatibility only. Please use the {@link #configPropertyNames()} method instead. + */ + @Deprecated + protected final SetImplementations of this method must not return {@code null}.
* + *Implementations of this method must not invoke the {@link #matcher(String)} method or an infinite loop may + * result.
+ * *Given a {@link String} like
- * javax.sql.DataSource.dataSourceName.dataSourcePropertyName,
- * any implementation of this method should return a non-{@code
- * null} {@link Matcher} that is capable of being supplied to the
- * {@link #getDataSourceName(Matcher)} and {@link
- * #getDataSourcePropertyName(Matcher)} methods.
javax.sql.DataSource.dataSourceName.dataSourcePropertyName, any implementation of
+ * this method should return a non-{@code null} {@link Matcher} that is capable of being supplied to the {@link
+ * #getDataSourceName(Matcher)} and {@link #getDataSourcePropertyName(Matcher)} methods.
*
- * @param configPropertyName the name of a configuration property
- * that logically contains a data source name and a
- * data source property name; must not be {@code null}
+ * @param configPropertyName the name of a configuration property that logically contains a data source
+ * name and a data source property name; must not be {@code null}
*
* @return a non-{@code null} {@link Matcher}
*
@@ -88,17 +115,22 @@ protected AbstractDataSourceExtension() {
*/
protected abstract Matcher getDataSourcePropertyPatternMatcher(String configPropertyName);
+ @Override
+ protected final String name(Matcher propertyPatternMatcher) {
+ return this.getDataSourceName(propertyPatternMatcher);
+ }
+
/**
- * Given a {@link Matcher} that has been produced by the {@link
- * #getDataSourcePropertyPatternMatcher(String)} method, returns
- * the relevant data source name.
+ * Given a {@link Matcher} that has been produced by the {@link #getDataSourcePropertyPatternMatcher(String)}
+ * method, returns the relevant data source name.
*
* Implementations of this method may return {@code null}.
* - * @param dataSourcePropertyPatternMatcher a {@link Matcher} - * produced by the {@link - * #getDataSourcePropertyPatternMatcher(String)} method; must not - * be {@code null} + *Implementations of this method must not invoke the {@link #name(Matcher)} method or an infinite loop may + * result.
+ * + * @param dataSourcePropertyPatternMatcher a {@link Matcher} produced by the {@link + * #getDataSourcePropertyPatternMatcher(String)} method; must not be {@code null} * * @return a data source name, or {@code null} * @@ -106,17 +138,22 @@ protected AbstractDataSourceExtension() { */ protected abstract String getDataSourceName(Matcher dataSourcePropertyPatternMatcher); + @Override + protected final String propertyName(Matcher propertyPatternMatcher) { + return this.getDataSourcePropertyName(propertyPatternMatcher); + } + /** - * Given a {@link Matcher} that has been produced by the {@link - * #getDataSourcePropertyPatternMatcher(String)} method, returns - * the relevant data source property name. + * Given a {@link Matcher} that has been produced by the {@link #getDataSourcePropertyPatternMatcher(String)} + * method, returns the relevant data source property name. * *Implementations of this method may return {@code null}.
* - * @param dataSourcePropertyPatternMatcher a {@link Matcher} - * produced by the {@link - * #getDataSourcePropertyPatternMatcher(String)} method; must not - * be {@code null} + *Implementations of this method must not invoke the {@link #propertyName(Matcher)} method or an infinite loop + * may result.
+ * + * @param dataSourcePropertyPatternMatcher a {@link Matcher} produced by the {@link + * #getDataSourcePropertyPatternMatcher(String)} method; must not be {@code null} * * @return a data source property name, or {@code null} * @@ -125,185 +162,55 @@ protected AbstractDataSourceExtension() { protected abstract String getDataSourcePropertyName(Matcher dataSourcePropertyPatternMatcher); /** - * Called to permit subclasses to add a {@link DataSource}-typed - * bean using the supplied {@link BeanConfigurator}. - * - *Implementations of this method will be called from an - * observer method that is observing the {@link - * AfterBeanDiscovery} container lifecycle event.
- * - * @param beanConfigurator the {@link BeanConfigurator} to use to - * actually add a new bean; must not be {@code null} - * - * @param name a {@link Named} instance qualifying the {@link - * DataSource}-typed bean to be added; may be {@code null} - * - * @param properties a {@link Properties} instance containing - * properties relevant to the data source; must not be {@code - * null} - */ - protected abstract void addBean(BeanConfiguratorThis method never returns {@code null}.
* - * @return a non-{@code null} {@link Config} instance - * - * @see Config - */ - protected final Config getConfig() { - return this.config; - } - - /** - * Returns a {@link Set} of data source names known to this {@link - * AbstractDataSourceExtension} implementation. - * - *This method never returns {@code null}.
+ *The {@link Set} returned by this method is {@linkplain Collections#unmodifiableSet(Set) unmodifiable}.
* - *The {@link Set} returned by this method is {@linkplain - * Collections#unmodifiableSet(Set) unmodifiable}.
+ * @return a non-{@code null}, {@linkplain Collections#unmodifiableSet(Set) unmodifiableSet} of known
+ * data source names
*
- * @return a non-{@code null}, {@linkplain
- * Collections#unmodifiableSet(Set) unmodifiable Set}
- * of known data source names
+ * @deprecated This method exists for backwards compatibility only. Please use the {@link #names()} method
+ * instead.
*/
+ @Deprecated // for backwards compatibility only
protected final SetThis method may return {@code null}.
* - * @param dataSourceName the name of the data source under which - * the supplied {@link Properties} will be indexed; may be {@code - * null} + * @param dataSourceName the name of the data source under which the supplied {@link Properties} will be indexed; + * may be {@code null} * - * @param properties the {@link Properties} to put; may be {@code null} + * @param properties the {@link Properties} to put; must not be {@code null} * - * @return the prior {@link Properties} indexed under the supplied - * {@code dataSourceName}, or {@code null} - */ - protected final Properties putDataSourceProperties(final String dataSourceName, final Properties properties) { - return this.explicitlySetProperties.put(dataSourceName, properties); - } - - /** - * {@linkplain Map#clear() Clears} and then - * builds or rebuilds an internal map of data source properties - * whose contents will be processed eventually by the {@link - * #addBean(BeanConfigurator, Named, Properties)} method. + * @return the prior {@link Properties} indexed under the supplied {@code dataSourceName}, or {@code null} * - *If no subclass explicitly calls this method, it will be - * called by the {@link #addBean(BeanConfigurator, Named, - * Properties)} method just prior to its other activities.
+ * @exception NullPointerException if {@code properties} is {@code null} * - *Once the {@link #addBean(BeanConfigurator, Named, - * Properties)} method has run to completion, while this method - * may be called freely its use is discouraged and its effects - * will no longer be used.
- * - * @see #addBean(BeanConfigurator, Named, Properties) + * @deprecated This method exists for backwards compatibility only. Please use the {@link #put(String, Properties)} + * method instead. */ - protected final void initializeMasterProperties() { - this.masterProperties.clear(); - final Set allPropertyNames = this.getPropertyNames(); - if (allPropertyNames != null && !allPropertyNames.isEmpty()) { - for (final String propertyName : allPropertyNames) { - final OptionalThis method never returns {@code null}.
- * - *The {@link Set} returned by this method is {@linkplain - * Collections#unmodifiableSet(Set) unmodifiable}.
+ * Calls the {@link #initializeNamedProperties()} method. * - *The {@link Set} returned by this method is not safe for - * concurrent use by multiple threads.
- * - *Any other semantics of the {@link Set} returned by this - * method are governed by the MicroProfile Config specification.
- * - * @return a non-{@code null}, {@linkplain - * Collections#unmodifiableSet(Set) unmodifiableSet}
- * of all known configuration property names
- *
- * @see Config#getConfigSources()
- *
- * @see ConfigSource#getPropertyNames()
+ * @deprecated This method exists for backwards compatibility only. Please use the {@link
+ * #initializeNamedProperties()} method instead.
*/
- protected final Set