Merge pull request #104 from oracle/83-struct-types

OBJECT Types

Author: jeandelavarene

.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=180" >> src/test/resources/config.properties
-echo "SQL_TIMEOUT=180" >> src/test/resources/config.properties
+echo "CONNECT_TIMEOUT=240" >> src/test/resources/config.properties
+echo "SQL_TIMEOUT=240" >> src/test/resources/config.properties
 mvn clean compile test

README.md

@@ -618,6 +618,120 @@ Publisher<Integer[]> arrayMapExample(Result result) {
 }
 ```
 
+### OBJECT
+Oracle Database supports `OBJECT` as a user defined type. A `CREATE TYPE`
+command is used to define an `OBJECT` type:
+```sql
+CREATE TYPE PET AS OBJECT(
+  name VARCHAR(128),
+  species VARCHAR(128),
+  weight NUMBER,
+  birthday DATE)
+```
+Oracle R2DBC defines `oracle.r2dbc.OracleR2dbcType.ObjectType` as a `Type` for
+representing user defined `OBJECT` types. A `Parameter` with a type of
+`ObjectType` may be used to bind `OBJECT` values to a `Statement`.
+
+Use an `Object[]` to bind the attribute values of an `OBJECT` by index:
+```java
+Publisher<Result> objectArrayBindExample(Connection connection) {
+  Statement statement =
+    connection.createStatement("INSERT INTO petTable VALUES (:petObject)");
+
+  // Bind the attributes of the PET OBJECT defined above
+  ObjectType objectType = OracleR2dbcTypes.objectType("PET");
+  Object[] attributeValues = {
+    "Derby",
+    "Dog",
+    22.8,
+    LocalDate.of(2015, 11, 07)
+  };
+  statement.bind("petObject", Parameters.in(objectType, attributeValues));
+
+  return statement.execute();
+}
+```
+
+Use a `Map<String,Object>` to bind the attribute values of an `OBJECT` by name:
+```java
+Publisher<Result> objectMapBindExample(Connection connection) {
+  Statement statement =
+    connection.createStatement("INSERT INTO petTable VALUES (:petObject)");
+
+  // Bind the attributes of the PET OBJECT defined above
+  ObjectType objectType = OracleR2dbcTypes.objectType("PET");
+  Map<String,Object> attributeValues = Map.of(
+    "name", "Derby",
+    "species", "Dog",
+    "weight", 22.8,
+    "birthday", LocalDate.of(2015, 11, 07));
+  statement.bind("petObject", Parameters.in(objectType, attributeValues));
+
+  return statement.execute();
+}
+```
+A `Parameter` with a type of `ObjectType` must be used when binding OUT
+parameters of `OBJECT` types for a PL/SQL call:
+```java
+Publisher<Result> objectOutBindExample(Connection connection) {
+  Statement statement =
+    connection.createStatement("BEGIN; getPet(:petObject); END;");
+
+  ObjectType objectType = OracleR2dbcTypes.objectType("PET");
+  statement.bind("petObject", Parameters.out(objectType));
+
+  return statement.execute();
+}
+```
+`OBJECT` values may be consumed from a `Row` or `OutParameter` as an
+`oracle.r2dbc.OracleR2dbcObject`. The `OracleR2dbcObject` interface is a subtype
+of `io.r2dbc.spi.Readable`. Attribute values may be accessed using the standard
+`get` methods of `Readable`. The `get` methods of `OracleR2dbcObject` support
+alll SQL to Java type mappings defined by the
+[R2DBC Specification](https://r2dbc.io/spec/1.0.0.RELEASE/spec/html/#datatypes.mapping):
+```java
+Publisher<Pet> objectMapExample(Result result) {
+  return result.map(row -> {
+    OracleR2dbcObject oracleObject = row.get(0, OracleR2dbcObject.class); 
+    return new Pet(
+      oracleObject.get("name", String.class),
+      oracleObject.get("species", String.class),
+      oracleObject.get("weight", Float.class),
+      oracleObject.get("birthday", LocalDate.class));
+  });
+}
+```
+
+Instances of `OracleR2dbcObject` may be passed directly to `Statement` bind 
+methods:
+```java
+Publisher<Result> objectBindExample(
+  OracleR2dbcObject oracleObject, Connection connection) {
+  Statement statement =
+    connection.createStatement("INSERT INTO petTable VALUES (:petObject)");
+  
+  statement.bind("petObject", oracleObject);
+
+  return statement.execute();
+}
+```
+Attribute metadata is exposed by the `getMetadata` method of
+`OracleR2dbcObject`:
+```java
+void printObjectMetadata(OracleR2dbcObject oracleObject) {
+  OracleR2dbcObjectMetadata metadata = oracleObject.getMetadata();
+  OracleR2dbcTypes.ObjectType objectType = metadata.getObjectType();
+  
+  System.out.println("Object Type: " + objectType);
+  metadata.getAttributeMetadatas()
+    .stream()
+    .forEach(attributeMetadata -> {
+      System.out.println("\tAttribute Name: " + attributeMetadata.getName()));
+      System.out.println("\tAttribute Type: " + attributeMetadata.getType()));
+    });
+}
+```
+
 ### REF Cursor
 Use the `oracle.r2dbc.OracleR2dbcTypes.REF_CURSOR` type to bind `SYS_REFCURSOR` out 
 parameters:

src/main/java/oracle/r2dbc/OracleR2dbcObject.java

@@ -0,0 +1,7 @@
+package oracle.r2dbc;
+
+public interface OracleR2dbcObject extends io.r2dbc.spi.Readable {
+
+  OracleR2dbcObjectMetadata getMetadata();
+
+}

src/main/java/oracle/r2dbc/OracleR2dbcObjectMetadata.java

@@ -0,0 +1,49 @@
+package oracle.r2dbc;
+
+import io.r2dbc.spi.ReadableMetadata;
+
+import java.util.List;
+import java.util.NoSuchElementException;
+
+/**
+ * Represents the metadata for attributes of an OBJECT. Metadata for attributes
+ * can either be retrieved by index or by name. Attribute indexes are
+ * {@code 0}-based. Retrieval by attribute name is case-insensitive.
+ */
+public interface OracleR2dbcObjectMetadata {
+
+  /**
+   * Returns the type of the OBJECT which metadata is provided for.
+   * @return The type of the OBJECT. Not null.
+   */
+  OracleR2dbcTypes.ObjectType getObjectType();
+
+  /**
+   * Returns the {@link ReadableMetadata} for one attribute.
+   *
+   * @param index the attribute index starting at 0
+   * @return the {@link ReadableMetadata} for one attribute. Not null.
+   * @throws IndexOutOfBoundsException if {@code index} is out of range
+   * (negative or equals/exceeds {@code getParameterMetadatas().size()})
+   */
+  ReadableMetadata getAttributeMetadata(int index);
+
+  /**
+   * Returns the {@link ReadableMetadata} for one attribute.
+   *
+   * @param name the name of the attribute. Not null. Parameter names are
+   * case-insensitive.
+   * @return the {@link ReadableMetadata} for one attribute. Not null.
+   * @throws IllegalArgumentException if {@code name} is {@code null}
+   * @throws NoSuchElementException if there is no attribute with the
+   * {@code name}
+   */
+  ReadableMetadata getAttributeMetadata(String name);
+
+  /**
+   * Returns the {@link ReadableMetadata} for all attributes.
+   *
+   * @return the {@link ReadableMetadata} for all attributes. Not null.
+   */
+  List<? extends ReadableMetadata> getAttributeMetadatas();
+}

src/main/java/oracle/r2dbc/OracleR2dbcTypes.java

@@ -137,6 +137,10 @@ public static ArrayType arrayType(String name) {
     return new ArrayTypeImpl(Objects.requireNonNull(name, "name is null"));
   }
 
+  public static ObjectType objectType(String name) {
+    return new ObjectTypeImpl(Objects.requireNonNull(name, "name is null"));
+  }
+
   /**
    * Extension of the standard {@link Type} interface used to represent user
    * defined ARRAY types. An instance of {@code ArrayType} must be used when
@@ -179,22 +183,60 @@ public interface ArrayType extends Type {
     String getName();
   }
 
+  public interface ObjectType extends Type {
+
+    /**
+     * {@inheritDoc}
+     * Returns {@code Object[].class}, which is the standard mapping for
+     * {@link R2dbcType#COLLECTION}. The true default type mapping is the array
+     * variant of the default mapping for the element type of the {@code ARRAY}.
+     * For instance, an {@code ARRAY} of {@code VARCHAR} maps to a
+     * {@code String[]} by default.
+     */
+    @Override
+    Class<?> getJavaType();
+
+    /**
+     * {@inheritDoc}
+     * Returns the name of this user defined {@code ARRAY} type. For instance,
+     * this method returns "MY_ARRAY" if the type is declared as:
+     * <pre>{@code
+     * CREATE TYPE MY_ARRAY AS ARRAY(8) OF NUMBER
+     * }</pre>
+     */
+    @Override
+    String getName();
+  }
+
   /** Concrete implementation of the {@code ArrayType} interface */
   private static final class ArrayTypeImpl
     extends TypeImpl implements ArrayType {
 
     /**
-     * Constructs an ARRAY type with the given {@code name}. The constructed
-     * {@code ArrayType} as a default Java type mapping of
-     * {@code Object[].class}. This is consistent with the standard
-     * {@link R2dbcType#COLLECTION} type.
+     * Constructs an ARRAY type with the given {@code name}. {@code Object[]} is
+     * the default mapping of the constructed type. This is consistent with the
+     * standard {@link R2dbcType#COLLECTION} type.
      * @param name User defined name of the type. Not null.
      */
     ArrayTypeImpl(String name) {
       super(Object[].class, name);
     }
   }
 
+  /** Concrete implementation of the {@code ObjectType} interface */
+  private static final class ObjectTypeImpl
+    extends TypeImpl implements ObjectType {
+
+    /**
+     * Constructs an OBJECT type with the given {@code name}.
+     * {@code OracleR2dbcObject} is the default mapping of the constructed type.
+     * @param name User defined name of the type. Not null.
+     */
+    ObjectTypeImpl(String name) {
+      super(OracleR2dbcObject.class, name);
+    }
+  }
+
   /**
    * Implementation of the {@link Type} SPI.
    */
@@ -259,6 +301,19 @@ public String getName() {
     public String toString() {
       return getName();
     }
+
+    @Override
+    public boolean equals(Object other) {
+      if (! (other instanceof Type))
+        return false;
+
+      return sqlName.equals(((Type)other).getName());
+    }
+
+    @Override
+    public int hashCode() {
+      return sqlName.hashCode();
+    }
   }
 
 }

src/main/java/oracle/r2dbc/impl/OracleR2dbcExceptions.java

@@ -81,6 +81,7 @@ static <T> T requireNonNull(T obj, String message) {
       return obj;
   }
 
+
   /**
    * Checks if a {@code jdbcConnection} is open, and throws an exception if the
    * check fails.