Merge branch 'main' of https://github.com/oracle/oracle-r2dbc into 1-1-0-dep-update

Author: Michael-A-McMahon

.github/workflows/startup/01_createUser.sql

@@ -36,12 +36,13 @@
 --   v$transaction (to verify if TransactionDefinitions are applied).
 --   v$session (to verify if VSESSION_* Options are applied).
 ALTER SESSION SET CONTAINER=xepdb1;
-CREATE ROLE r2dbc_test_user;
-GRANT SELECT ON v_$open_cursor TO r2dbc_test_user;
-GRANT SELECT ON v_$transaction TO r2dbc_test_user;
-GRANT SELECT ON v_$session TO r2dbc_test_user;
+CREATE ROLE r2dbc_test_role;
+GRANT SELECT ON v_$open_cursor TO r2dbc_test_role;
+GRANT SELECT ON v_$transaction TO r2dbc_test_role;
+GRANT SELECT ON v_$session TO r2dbc_test_role;
+GRANT CREATE VIEW TO r2dbc_test_role;
 
 CREATE USER test IDENTIFIED BY test;
-GRANT connect, resource, unlimited tablespace, r2dbc_test_user TO test;
+GRANT connect, resource, unlimited tablespace, r2dbc_test_role TO test;
 ALTER USER test DEFAULT TABLESPACE users;
 ALTER USER test TEMPORARY TABLESPACE temp;

.github/workflows/test.sh

@@ -81,6 +81,6 @@ echo "HOST=localhost" >> src/test/resources/config.properties
 echo "PORT=1521" >> src/test/resources/config.properties
 echo "USER=test" >> src/test/resources/config.properties
 echo "PASSWORD=test" >> src/test/resources/config.properties
-echo "CONNECT_TIMEOUT=60" >> src/test/resources/config.properties
-echo "SQL_TIMEOUT=60" >> src/test/resources/config.properties
+echo "CONNECT_TIMEOUT=120" >> src/test/resources/config.properties
+echo "SQL_TIMEOUT=120" >> src/test/resources/config.properties
 mvn clean compile test

README.md

@@ -191,22 +191,22 @@ are supported by Oracle R2DBC:
  - `HOST`
  - `PORT`
  - `DATABASE`
+   - The database option is interpreted as the
+     [service name](https://docs.oracle.com/en/database/oracle/oracle-database/21/netag/identifying-and-accessing-database.html#GUID-153861C1-16AD-41EC-A179-074146B722E6)
+      of an Oracle Database instance. _System Identifiers (SID) are not recognized_.
  - `USER`
  - `PASSWORD`
  - `SSL`
  - `CONNECT_TIMEOUT`
  - `STATEMENT_TIMEOUT`.
-
-> Oracle R2DBC interprets the `DATABASE` option as the
-> [service name](https://docs.oracle.com/en/database/oracle/oracle-database/21/netag/identifying-and-accessing-database.html#GUID-153861C1-16AD-41EC-A179-074146B722E6)
-> of an Oracle Database instance. _System Identifiers (SID) are not recognized_.
+ - `PROTOCOL`
+   - (For inclusion in the next release) Accepted protocol values are "tcps", "ldap", and "ldaps"
 
 #### Support for Extended R2DBC Options
 Oracle R2DBC extends the standard set of R2DBC options to offer functionality 
 that is specific to Oracle Database and the Oracle JDBC Driver. Extended options
 are declared in the
-[OracleR2dbcOptions](src/main/java/oracle/r2dbc/OracleR2dbcOptions.java)
-class.
+[OracleR2dbcOptions](src/main/java/oracle/r2dbc/OracleR2dbcOptions.java) class.
 
 #### Configuring an Oracle Net Descriptor
 The `oracle.r2dbc.OracleR2dbcOptions.DESCRIPTOR` option may be used to configure
@@ -234,6 +234,22 @@ located:
 r2dbc:oracle://?oracle.r2dbc.descriptor=myAlias&TNS_ADMIN=/path/to/tnsnames/
 ```
 
+#### (For inclusion in the next release) Configuring an LDAP URL
+Use `ldap` or `ldaps` as the URL protocol to have an Oracle Net Descriptor 
+retrieved from an LDAP server:
+```
+r2dbc:oracle:ldap://ldap.example.com:7777/sales,cn=OracleContext,dc=com
+r2dbc:oracle:ldaps://ldap.example.com:7778/sales,cn=OracleContext,dc=com
+```
+Use a space separated list of LDAP URIs for fail over and load balancing:
+```
+r2dbc:oracle:ldap://ldap1.example.com:7777/sales,cn=OracleContext,dc=com%20ldap://ldap2.example.com:7777/sales,cn=OracleContext,dc=com%20ldap://ldap3.example.com:7777/sales,cn=OracleContext,dc=com
+```
+> Space characters in a URL must be percent encoded as `%20`
+
+An LDAP server request will **block a thread for network I/O** when Oracle R2DBC
+creates a new connection.
+
 #### Configuring a java.util.concurrent.Executor
 The `oracle.r2dbc.OracleR2dbcOptions.EXECUTOR` option configures a 
 `java.util.concurrent.Executor` for executing asynchronous callbacks. The 
@@ -344,12 +360,32 @@ Oracle R2DBC's implementation of Publishers that emit multiple items will
 typically defer execution until a Subscriber signals demand, and not support 
 multiple subscribers.
 
-### Errors
+### Errors and Warnings
 Oracle R2DBC creates R2dbcExceptions having the same ORA-XXXXX error codes 
-used by Oracle Database and Oracle JDBC.
+used by Oracle Database and Oracle JDBC. The
+[Database Error Messages](https://docs.oracle.com/en/database/oracle/oracle-database/21/errmg/ORA-00000.html#GUID-27437B7F-F0C3-4F1F-9C6E-6780706FB0F6)
+document provides a reference for all ORA-XXXXX error codes.
 
-A reference for the ORA-XXXXX error codes can be found 
-[here](https://docs.oracle.com/en/database/oracle/oracle-database/21/errmg/ORA-00000.html#GUID-27437B7F-F0C3-4F1F-9C6E-6780706FB0F6)
+Warning messages from Oracle Database are emitted as 
+`oracle.r2dbc.OracleR2dbcWarning` segments. These segments may be consumed using
+`Result.flatMap(Function)`:
+```java
+result.flatMap(segment -> {
+  if (segment instanceof OracleR2dbcWarning) {
+    logWarning(((OracleR2dbcWarning)segment).getMessage());
+    return emptyPublisher();
+  }
+  else if (segment instanceof Result.Message){
+    ... handle an error ...
+  }
+  else {
+    ... handle other segment types ...
+  }
+})
+```
+Unlike the errors of standard `Result.Message` segments, if a warning is not
+consumed by `flatMap`, then it will be silently discarded when a `Result` is 
+consumed using the `map` or `getRowsUpdated` methods.
 
 ### Transactions
 Oracle R2DBC uses READ COMMITTED as the default transaction isolation level.
@@ -488,12 +524,13 @@ for the out parameters is emitted last, after the `Result` for each cursor.
 Oracle R2DBC supports type mappings between Java and SQL for non-standard data 
 types of Oracle Database.
 
-| Oracle SQL Type                                                                                                                                         | Java Type |
-|---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
-| [JSON](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-E441F541-BA31-4E8C-B7B4-D2FB8C42D0DF)                   |  `javax.json.JsonObject` or `oracle.sql.json.OracleJsonObject` |
-| [DATE](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-5405B652-C30E-4F4F-9D33-9A4CB2110F1B)                                                                                                                                                | `java.time.LocalDateTime` |
-| [INTERVAL DAY TO SECOND](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-B03DD036-66F8-4BD3-AF26-6D4433EBEC1C) | `java.time.Duration` |
-| [INTERVAL YEAR TO MONTH](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-ED59E1B3-BA8D-4711-B5C8-B0199C676A95) | `java.time.Period` |
+| Oracle SQL Type                                                                                                                                         | Java Type                                                     |
+|---------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|
+| [JSON](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-E441F541-BA31-4E8C-B7B4-D2FB8C42D0DF)                   | `javax.json.JsonObject` or `oracle.sql.json.OracleJsonObject` |
+| [DATE](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-5405B652-C30E-4F4F-9D33-9A4CB2110F1B)                   | `java.time.LocalDateTime`                                     |
+| [INTERVAL DAY TO SECOND](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-B03DD036-66F8-4BD3-AF26-6D4433EBEC1C) | `java.time.Duration`                                          |
+| [INTERVAL YEAR TO MONTH](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-ED59E1B3-BA8D-4711-B5C8-B0199C676A95) | `java.time.Period`                                            |
+| [SYS_REFCURSOR](https://docs.oracle.com/en/database/oracle/oracle-database/21/lnpls/static-sql.html#GUID-470A7A99-888A-46C2-BDAF-D4710E650F27)          | `io.r2dbc.spi.Result`                                         |
 > Unlike the standard SQL type named "DATE", the Oracle Database type named 
 > "DATE" stores values for year, month, day, hour, minute, and second. The 
 > standard SQL type only stores year, month, and day. LocalDateTime objects are able 
@@ -533,6 +570,35 @@ prefetched entirely, a smaller prefetch size can be configured using the
 option, and the LOB can be consumed as a stream. By mapping LOB columns to 
 `Blob` or `Clob` objects, the content can be consumed as a reactive stream. 
 
+### REF Cursors 
+Use the `oracle.r2dbc.OracleR2dbcTypes.REF_CURSOR` type to bind `SYS_REFCURSOR` out 
+parameters:
+```java
+Publisher<Result> executeProcedure(Connection connection) {
+  connection.createStatement(
+    "BEGIN example_procedure(:cursor_parameter); END;")
+  .bind("cursor_parameter", Parameters.out(OracleR2dbcTypes.REF_CURSOR))
+  .execute()
+}
+```
+A `SYS_REFCURSOR` out parameter can be mapped to an `io.r2dbc.spi.Result`:
+```java
+Publisher<Result> mapOutParametersResult(Result outParametersResult) {
+  return outParametersResult.map(outParameters ->
+    outParameters.get("cursor_parameter", Result.class));
+}
+```
+The rows of a `SYS_REFCURSOR` may be consumed from the `Result` it is 
+mapped to:
+```java
+Publisher<ExampleObject> mapRefCursorRows(Result refCursorResult) {
+  return refCursorResult.map(row ->
+    new ExampleObject(
+      row.get("id_column", Long.class),
+      row.get("value_column", String.class)));
+}
+```
+
 ## Secure Programming Guidelines
 The following security related guidelines should be adhered to when programming
 with the Oracle R2DBC Driver.

pom.xml

@@ -87,6 +87,17 @@
             <arg>-Xlint:-processing</arg>
             <arg>-Xlint:-serial</arg>
           </compilerArgs>
+          <!-- LDAP URL tests require the java.naming module -->
+          <!-- Maven seems to ignore the forceJavacCompilerUse.
+            This results in an error when passing the addModules option to
+            the javax.tools API. For this reason, Oracle R2DBC's module-info is
+            declaring a depency on the java.naming module.
+            TODO: Figure out how to make maven compile tests correctly, and 
+            remove the java.naming depenency from Oracle R2DBC.
+          <fork>true</fork>
+          <forceJavacCompilerUse>true</forceJavacCompilerUse>
+          <testCompilerArgument>- -add-modules java.naming</testCompilerArgument>
+          -->
           <showWarnings>true</showWarnings>
           <release>${java.version}</release>
         </configuration>
@@ -150,6 +161,7 @@
         <artifactId>maven-surefire-plugin</artifactId>
         <version>3.0.0-M5</version>
         <configuration>
+          <!-- Include tests in the oracle.r2dbc.test package -->
           <includes>
             <include>**/*Test.java</include>
             <include>**/*TestKit.java</include>
@@ -283,7 +295,6 @@
       <scope>test</scope>
     </dependency>
     -->
-
   </dependencies>
 
   <profiles>

src/main/java/module-info.java

@@ -30,6 +30,7 @@
     with oracle.r2dbc.impl.OracleConnectionFactoryProviderImpl;
 
   requires java.sql;
+  requires java.naming;
   requires com.oracle.database.jdbc;
   requires reactor.core;
   requires transitive org.reactivestreams;