Merge branch 'main' of https://github.com/oracle/oracle-r2dbc into 22-poolable-connections

Author: Michael-A-McMahon

README.md

@@ -25,10 +25,17 @@ Oracle R2DBC can be built from source using Maven:
 
 `mvn clean install -DskipTests=true`
 
-> The build is not yet available on the Maven Central Repository. It will be published there soon.
-
 > Omitting -DskipTests=true from the command above will execute the test suite, where end-to-end tests connect to an Oracle Database instance. The connection configuration is read from [src/test/resources/config.properties](src/test/resources/example-config.properties).
 
+Artifacts can also be found on Maven Central.
+```
+<dependency>
+  <groupId>com.oracle.database.r2dbc</groupId>
+  <artifactId>oracle-r2dbc</artifactId>
+  <version>${version}</version>
+</dependency>
+```
+
 Oracle R2DBC is compatible with JDK 11 (or newer), and has the following runtime dependencies:
 - R2DBC SPI 0.8.2
 - Reactive Streams 1.0.3
@@ -150,6 +157,10 @@ Options. For Options having any of the following names, a CharSequence value may
   - [oracle.net.ssl_context_protocol](https://docs.oracle.com/en/database/oracle/oracle-database/21/jajdb/oracle/jdbc/OracleConnection.html?is-external=true#CONNECTION_PROPERTY_SSL_CONTEXT_PROTOCOL)
   - [oracle.jdbc.fanEnabled](https://docs.oracle.com/en/database/oracle/oracle-database/21/jajdb/oracle/jdbc/OracleConnection.html?is-external=true#CONNECTION_PROPERTY_FAN_ENABLED)
   - [oracle.jdbc.implicitStatementCacheSize](https://docs.oracle.com/en/database/oracle/oracle-database/21/jajdb/oracle/jdbc/OracleConnection.html?is-external=true#CONNECTION_PROPERTY_IMPLICIT_STATEMENT_CACHE_SIZE)
+- Descriptor URLs of the form ```(DESCRIPTION=...)``` may be specified in a tnsnames.ora file. 
+  - The directory containing the tnsnames.ora file may be specified as an ```Option``` having the name "TNS_ADMIN"
+  - An alias of a tnsnames.ora file may be specified as the value of ```ConnectionFactoryOptions.HOST```. 
+  - An alias of a tnsnames.ora file may be specified with an R2DBC URL: ```r2dbc:oracle://my_alias?TNS_ADMIN=/path/to/tnsnames/```
 
 
 ### Thread Safety and Parallel Execution
@@ -188,15 +199,25 @@ be used when setting the bind value of an unnamed parameter.
 colon character (:) is followed by an alphanumeric parameter name. A name
 or numeric index may be used when setting the bind value of a named parameter.
 - Parameter names are case-sensitive.
-- The [ROWID](https://docs.oracle.com/en/database/oracle/oracle-database/21/cncpt/tables-and-table-clusters.html#GUID-0258C4C2-2BF2-445F-B1E1-F282A57A6859) 
-of each row affected by an INSERT or UPDATE is returned as the generated value
-for the empty set of column names.
+- When an empty set of column names is specified to Statement.returnGeneratedValues(String...), executing that ```Statement``` returns the [ROWID](https://docs.oracle.com/en/database/oracle/oracle-database/21/cncpt/tables-and-table-clusters.html#GUID-0258C4C2-2BF2-445F-B1E1-F282A57A6859) 
+of each row affected by an INSERT or UPDATE.
+  - This behavior may change in a later release.
+  - Programmers are advised not to use the ROWID as if it were a primary key.
+    - The ROWID of a row may change.
+    - After a row is deleted, it's ROWID may be reassigned to a new row.
+    - Further Reading: https://asktom.oracle.com/pls/apex/asktom.search?tag=is-it-safe-to-use-rowid-to-locate-a-row
 - A **blocking database call** is executed by a Statement returning generated 
 values for a non-empty set of column names.
   - The **blocking database call** is a known limitation that will be resolved
   with a non-blocking implementation of 
   java.sql.Connection.prepareStatement(String, String[]) in the Oracle JDBC Driver. 
   The Oracle JDBC Team is aware of this problem and is working on a fix.
+- Returning generated values is only supported for INSERT and UPDATE commands when a RETURNING INTO clause can be appended to the end of that command. (This limitation may be resolved in a later release)
+  - Example: `INSERT INTO my_table(val) VALUES (:val)` is supported because a RETURNING INTO clause may be appended to this command.
+  - Example: `INSERT INTO my_table(val) SELECT 1 FROM sys.dual` is not supported because a RETURNING INTO clause may not be appended to this command.
+  - The Oracle Database SQL Language Reference defines INSERT and UPDATE commands for which a RETURNING INTO clause is supported.
+  - INSERT: https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/INSERT.html#GUID-903F8043-0254-4EE9-ACC1-CB8AC0AF3423
+  - UPDATE: https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/UPDATE.html#GUID-027A462D-379D-4E35-8611-410F3AC8FDA5
 
 ### Type Mappings
 - Blob and Clob objects are the default mapping implemented by Row.get(...) for 

sample/build.gradle

@@ -36,7 +36,7 @@ dependencies {
 sourceCompatibility = 1.11
 targetCompatibility = 1.11
 
-mainClassName = 'TcpsConnectDemo'
+mainClassName = 'oracle.r2dbc.samples.TcpsConnectDemo'
 
 run {
   // To enable network debugging:

sample/example-config.properties

@@ -11,7 +11,7 @@ HOST=db.host.example.com
 PORT=1521
 
 # Service name of a test database
-DATABASE=db.service.name
+SERVICE_NAME=db.service.name
 
 # User name authenticated by a test database
 USER=db_user

sample/src/main/java/oracle/r2dbc/samples/DatabaseConfig.java

@@ -0,0 +1,75 @@
+/*
+  Copyright (c) 2020, 2021, Oracle and/or its affiliates.
+
+  This software is dual-licensed to you under the Universal Permissive License
+  (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl or Apache License
+  2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+  either license.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+     https://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+package oracle.r2dbc.samples;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Properties;
+
+/**
+ * <p>
+ * Configuration for connecting code samples to an Oracle Database instance.
+ * </p><p>
+ * The configuration is read from a properties file in the current directory
+ * by default, or from a file specified as
+ * <code>-DCONFIG_FILE=/path/to/your/config.properties</code>
+ * </p>
+ */
+public class DatabaseConfig {
+
+  /** Path to a configuration file: config.properties */
+  private static final Path CONFIG_PATH =
+    Path.of(System.getProperty("CONFIG_FILE", "config.properties"));
+
+  /** Configuration that is read from a file at {@link #CONFIG_PATH} */
+  private static final Properties CONFIG;
+  static {
+    try (var fileStream = Files.newInputStream(CONFIG_PATH)) {
+      CONFIG = new Properties();
+      CONFIG.load(fileStream);
+    }
+    catch (IOException readFailure) {
+      throw new UncheckedIOException(readFailure);
+    }
+  }
+
+  /** Host name where an Oracle Database instance is running */
+  static final String HOST = CONFIG.getProperty("HOST");
+
+  /** Port number where an Oracle Database instance is listening */
+  static final int PORT = Integer.parseInt(CONFIG.getProperty("PORT"));
+
+  /** Service name of an Oracle Database */
+  static final String SERVICE_NAME = CONFIG.getProperty("SERVICE_NAME");
+
+  /** User name that connects to an Oracle Database */
+  static final String USER = CONFIG.getProperty("USER");
+
+  /** Password of the user that connects to an Oracle Database */
+  static final String PASSWORD = CONFIG.getProperty("PASSWORD");
+
+  /** The file system path of a wallet directory */
+  static final String WALLET_LOCATION =
+    CONFIG.getProperty("WALLET_LOCATION");
+}

sample/src/main/java/oracle/r2dbc/samples/DescriptorURL.java

@@ -0,0 +1,93 @@
+/*
+  Copyright (c) 2020, 2021, Oracle and/or its affiliates.
+
+  This software is dual-licensed to you under the Universal Permissive License
+  (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl or Apache License
+  2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+  either license.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+     https://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+package oracle.r2dbc.samples;
+
+import io.r2dbc.spi.ConnectionFactories;
+import io.r2dbc.spi.ConnectionFactoryOptions;
+import reactor.core.publisher.Mono;
+
+import static oracle.r2dbc.samples.DatabaseConfig.HOST;
+import static oracle.r2dbc.samples.DatabaseConfig.PORT;
+import static oracle.r2dbc.samples.DatabaseConfig.SERVICE_NAME;
+import static oracle.r2dbc.samples.DatabaseConfig.USER;
+import static oracle.r2dbc.samples.DatabaseConfig.PASSWORD;
+
+/**
+ * This code example shows how to use TNS descriptor URLs with Oracle R2DBC.
+ * The TNS descriptor has the form:
+ * <pre>
+ *   (DESCRIPTION=...)
+ * </pre>
+ * The full syntax of the TNS descriptor is described in the
+ * <a href=https://docs.oracle.com/en/database/oracle/oracle-database/21/netag/identifying-and-accessing-database.html#GUID-8D28E91B-CB72-4DC8-AEFC-F5D583626CF6>
+ *   Oracle Net Services Administrator's Guide
+ * </a>
+ */
+public class DescriptorURL {
+
+  /**
+   * A TNS descriptor specifying the HOST, PORT, and SERVICE_NAME read from
+   * {@link DatabaseConfig}.
+   */
+  private static final String DESCRIPTOR = "(DESCRIPTION=" +
+    "(ADDRESS=(HOST="+HOST+")(PORT="+PORT+")(PROTOCOL=tcp))" +
+    "(CONNECT_DATA=(SERVICE_NAME="+SERVICE_NAME+")))";
+
+  public static void main(String[] args) {
+    // A descriptor may appear in the host section of an R2DBC URL:
+    String r2dbcUrl = "r2dbc:oracle://"+DESCRIPTOR;
+    Mono.from(ConnectionFactories.get(ConnectionFactoryOptions.parse(r2dbcUrl)
+      .mutate()
+      .option(ConnectionFactoryOptions.USER, USER)
+      .option(ConnectionFactoryOptions.PASSWORD, PASSWORD)
+      .build())
+      .create())
+      .flatMapMany(connection ->
+        Mono.from(connection.createStatement(
+          "SELECT 'Connected with TNS descriptor' FROM sys.dual")
+          .execute())
+          .flatMapMany(result ->
+            result.map((row, metadata) -> row.get(0, String.class)))
+          .concatWith(Mono.from(connection.close()).cast(String.class)))
+      .toStream()
+      .forEach(System.out::println);
+
+    // A descriptor may also be specified as the value of
+    // ConnectionFactoryOptions.HOST
+    Mono.from(ConnectionFactories.get(ConnectionFactoryOptions.builder()
+      .option(ConnectionFactoryOptions.DRIVER, "oracle")
+      .option(ConnectionFactoryOptions.HOST, DESCRIPTOR)
+      .option(ConnectionFactoryOptions.USER, USER)
+      .option(ConnectionFactoryOptions.PASSWORD, PASSWORD)
+      .build())
+      .create())
+      .flatMapMany(connection ->
+        Mono.from(connection.createStatement(
+          "SELECT 'Connected with TNS descriptor' FROM sys.dual")
+          .execute())
+          .flatMapMany(result ->
+            result.map((row, metadata) -> row.get(0, String.class)))
+          .concatWith(Mono.from(connection.close()).cast(String.class)))
+      .toStream()
+      .forEach(System.out::println);
+  }
+}

sample/src/main/java/TcpsConnectDemo.java renamed to sample/src/main/java/oracle/r2dbc/samples/TcpsConnectDemo.java

@@ -19,6 +19,8 @@
   limitations under the License.
 */
 
+package oracle.r2dbc.samples;
+
 import io.r2dbc.spi.ConnectionFactories;
 import io.r2dbc.spi.ConnectionFactory;
 import io.r2dbc.spi.ConnectionFactoryOptions;
@@ -28,14 +30,16 @@
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
-import java.io.IOException;
-import java.io.UncheckedIOException;
 import java.net.URI;
 import java.net.URISyntaxException;
-import java.nio.file.Files;
-import java.nio.file.Path;
 import java.time.Duration;
-import java.util.Properties;
+
+import static oracle.r2dbc.samples.DatabaseConfig.HOST;
+import static oracle.r2dbc.samples.DatabaseConfig.PASSWORD;
+import static oracle.r2dbc.samples.DatabaseConfig.PORT;
+import static oracle.r2dbc.samples.DatabaseConfig.SERVICE_NAME;
+import static oracle.r2dbc.samples.DatabaseConfig.USER;
+import static oracle.r2dbc.samples.DatabaseConfig.WALLET_LOCATION;
 
 /**
  * Sample code that uses an Oracle Wallet to authenticate with an Oracle
@@ -67,40 +71,6 @@
  */
 public class TcpsConnectDemo {
 
-  /** Path to a configuration file: config.properties */
-  private static final Path CONFIG_PATH =
-    Path.of(System.getProperty("CONFIG_FILE", "config.properties"));
-
-  /** Configuration that is read from a file at {@link #CONFIG_PATH} */
-  private static final Properties CONFIG;
-  static {
-    try (var fileStream = Files.newInputStream(CONFIG_PATH)) {
-      CONFIG = new Properties();
-      CONFIG.load(fileStream);
-    }
-    catch (IOException readFailure) {
-      throw new UncheckedIOException(readFailure);
-    }
-  }
-
-  /** Host name where an Oracle Database instance is running */
-  private static final String HOST = CONFIG.getProperty("HOST");
-
-  /** Port number where an Oracle Database instance is listening */
-  private static final int PORT = Integer.parseInt(CONFIG.getProperty("PORT"));
-
-  /** Service name of an Oracle Database */
-  private static final String SERVICE_NAME = CONFIG.getProperty("SERVICE_NAME");
-
-  /** User name that connects to an Oracle Database */
-  private static final String USER = CONFIG.getProperty("USER");
-
-  /** Password of the user that connects to an Oracle Database */
-  private static final String PASSWORD = CONFIG.getProperty("PASSWORD");
-
-  /** The file system path of a wallet directory */
-  private static final String WALLET_LOCATION =
-    CONFIG.getProperty("WALLET_LOCATION");
 
   public static void main(String[] args) throws URISyntaxException {