Merge branch 'main' of https://github.com/oracle/oracle-r2dbc into array-types

Author: Michael-A-McMahon

.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 
@@ -508,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 
@@ -600,6 +617,36 @@ Publisher<Integer[]> arrayMapExample(Result result) {
   return result.map(readable -> readable.get("arrayValue", Integer[].class));
 }
 ```
+
+### REF Cursor
+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>
@@ -278,7 +290,6 @@
       <artifactId>reactor-test</artifactId>
       <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;