Merge pull request #113 from oracle/object-javadoc

Fixing JavaDocs

Author: jeandelavarene

README.md

@@ -697,7 +697,7 @@ Publisher<Result> objectOutBindExample(Connection connection) {
 `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
+all 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) {

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

@@ -20,8 +20,59 @@
 */
 package oracle.r2dbc;
 
+/**
+ * <p>
+ * A {@link io.r2dbc.spi.Readable} that represents an instance of a user 
+ * defined OBJECT type.
+ * </p><p>
+ * An OBJECT returned by a {@link io.r2dbc.spi.Result} may be mapped to an
+ * {@code OracleR2dbcObject}:
+ * <pre>{@code
+ * 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));
+ *   });
+ * }
+ *
+ * }</pre>
+ * As seen in the example above, the values of an OBJECT's attributes may be 
+ * accessed by name with {@link #get(String)} or {@link #get(String, Class)}.
+ * Alternatively, attribute values may be accessed by index with {@link #get(int)} or
+ * {@link #get(int, Class)}. The {@code get} methods support all standard
+ * SQL-to-Java type mappings defined by the
+ * <a href="https://r2dbc.io/spec/1.0.0.RELEASE/spec/html/#datatypes.mapping">
+ * R2DBC Specification.
+ * </a>
+ * <p>
+ * Instances of {@code OracleR2dbcObject} may be set as a bind value when 
+ * passed to {@link io.r2dbc.spi.Statement#bind(int, Object)} or
+ * {@link io.r2dbc.spi.Statement#bind(String, Object)}:
+ * <pre>{@code
+ * Publisher<Result> objectBindExample(
+ *   OracleR2dbcObject oracleObject, Connection connection) {
+ *
+ *   Statement statement =
+ *     connection.createStatement("INSERT INTO petTable VALUES (:petObject)");
+ *   
+ *   statement.bind("petObject", oracleObject);
+ * 
+ *   return statement.execute();
+ * }
+ * }</pre>
+ */
 public interface OracleR2dbcObject extends io.r2dbc.spi.Readable {
 
+  /**
+   * Returns metadata for the attributes of this OBJECT.
+   * @return The metadata of this OBJECT's attributes. Not null.
+   */
   OracleR2dbcObjectMetadata getMetadata();
 
 }

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

@@ -114,7 +114,7 @@ private OracleR2dbcTypes() {}
    * name.
    * </p><p>
    * The {@code ArrayType} object returned by this method may be used to create
-   * a {@link Parameter} that binds an array value to a {@link Statement}.
+   * a {@link Parameter} that binds an array value to a {@link Statement}:
    * </p><pre>{@code
    * Publisher<Result> arrayBindExample(Connection connection) {
    *   Statement statement =
@@ -137,6 +137,39 @@ public static ArrayType arrayType(String name) {
     return new ArrayTypeImpl(Objects.requireNonNull(name, "name is null"));
   }
 
+  /**
+   * <p>
+   * Creates an {@link ObjectType} representing a user defined {@code OBJECT}
+   * type. The {@code name} passed to this method must identify the name of a
+   * user defined {@code OBJECT} type.
+   * </p><p>
+   * Typically, the name passed to this method should be UPPER CASE, unless the
+   * {@code CREATE TYPE} command that created the type used an "enquoted" type
+   * name.
+   * </p><p>
+   * The {@code ObjectType} object returned by this method may be used to create
+   * a {@link Parameter} that binds an OBJECT value to a {@link Statement}:
+   * </p><pre>{@code
+   * 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();
+   * }
+   * }</pre>
+   * @param name Name of a user defined OBJECT type. Not null.
+   * @return A {@code Type} object representing the user defined OBJECT type.
+   * Not null.
+   */
   public static ObjectType objectType(String name) {
     return new ObjectTypeImpl(Objects.requireNonNull(name, "name is null"));
   }
@@ -183,25 +216,32 @@ public interface ArrayType extends Type {
     String getName();
   }
 
+  /**
+   * Extension of the standard {@link Type} interface used to represent user
+   * defined OBJECT types. An instance of {@code ObjectType} must be used when
+   * binding an OBJECT value to a {@link Statement} created by the Oracle R2DBC
+   * Driver.
+   */
   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.
+     * Returns the class of {@link OracleR2dbcObject}, which is the default mapping
+     * of OBJECT types returned by Oracle R2DBC.
      */
     @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:
+     * Returns the name of this user defined {@code OBJECT} type. For instance,
+     * this method returns "PET" if the type is declared as:
      * <pre>{@code
-     * CREATE TYPE MY_ARRAY AS ARRAY(8) OF NUMBER
+     * CREATE TYPE PET AS OBJECT(
+     *   name VARCHAR(128),
+     *   species VARCHAR(128),
+     *   weight NUMBER,
+     *   birthday DATE)
      * }</pre>
      */
     @Override

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

@@ -142,6 +142,8 @@ private OracleReadableImpl(
    * </p>
    * @param jdbcConnection JDBC connection that created the
    *   {@code jdbcReadable}. Not null.
+   * @param dependentCounter Counter that is increased for each dependent
+   * {@code Result} created by the returned {@code Row}
    * @param jdbcReadable Row data from the Oracle JDBC Driver. Not null.
    * @param metadata Meta-data for the specified row. Not null.
    * @param adapter Adapts JDBC calls into reactive streams. Not null.
@@ -164,6 +166,8 @@ static Row createRow(
    * </p>
    * @param jdbcConnection JDBC connection that created the
    *   {@code jdbcReadable}. Not null.
+   * @param dependentCounter Counter that is increased for each dependent
+   * {@code Result} created by the returned {@code OutParameters}
    * @param jdbcReadable Row data from the Oracle JDBC Driver. Not null.
    * @param metadata Meta-data for the specified row. Not null.
    * @param adapter Adapts JDBC calls into reactive streams. Not null.

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

@@ -105,6 +105,8 @@ static RowMetadataImpl createRowMetadata(
   /**
    * Creates {@code OracleR2dbcObjectMetadata} that supplies attribute metadata
    * from a JDBC {@code OracleStruct} object.
+   * @param oracleStruct Struct created by Oracle JDBC. Not null.
+   * @return R2DBC metadata for the attributes of the struct. Not null.
    */
   static OracleR2dbcObjectMetadataImpl createAttributeMetadata(
     OracleStruct oracleStruct) {
@@ -369,4 +371,4 @@ public boolean equals(Object other) {
     }
   }
 
-}
+}