Merge pull request #77 from oracle/1-0-0-javadoc

Repairing javadocs

pom.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
-  Copyright (c) 2020, 2021, Oracle and/or its affiliates.
+  Copyright (c) 2020, 2022, 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
@@ -26,7 +26,7 @@
 
   <groupId>com.oracle.database.r2dbc</groupId>
   <artifactId>oracle-r2dbc</artifactId>
-  <version>0.4.0</version>
+  <version>1.0.0</version>
   <name>oracle-r2dbc</name>
   <description>
     Oracle R2DBC Driver implementing version 1.0.0 of the R2DBC SPI for Oracle Database.
@@ -163,9 +163,16 @@
         <configuration>
           <header>Oracle R2DBC ${project.version}</header>
           <footer>
-            Copyright (c) 2020, 2021, Oracle and/or its affiliates.
+            Copyright (c) 2020, 2022, Oracle and/or its affiliates.
           </footer>
           <show>package</show>
+          <!--
+            If sourcepath is not configured, then docs are only generated for
+            the oracle.r2dbc package, and not for the oracle.r2dbc.impl package.
+            The author of this comment could not find any explaination for this
+            in the documentation of the Maven JavaDoc plugin.
+          -->
+          <sourcepath>src/main/java</sourcepath>
           <links>
             <link>https://r2dbc.io/spec/${r2dbc.version}/api/</link>
             <link>https://www.reactive-streams.org/reactive-streams-1.0.3-javadoc/</link>

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

@@ -88,8 +88,11 @@ final class AsyncLock {
     new ConcurrentLinkedDeque<>();
 
   /**
-   * Returns a {@code Publisher} that emits {@code onComplete} when this lock is
-   * acquired.
+   * Acquires this lock, executes a {@code callback}, and then releases this 
+   * lock. The {@code callback} may be executed before this method returns
+   * if this lock is currently available. Otherwise, the {@code callback} is
+   * executed asynchronously after this lock becomes available.
+   * @param callback Task to be executed with lock ownership. Not null.
    */
   void lock(Runnable callback) {
     assert waitCount.get() >= 0 : "Wait count is less than 0: " + waitCount;
@@ -151,6 +154,7 @@ Publisher<Void> run(JdbcRunnable jdbcRunnable) {
    * emits {@code onNext} if the supplier returns a non-null value, and then
    * emits {@code onComplete}. Or, the {@code Publisher} emits {@code onError}
    * with any {@code Throwable} thrown by the supplier.
+   * @param <T> The class of object output by the {@code jdbcSupplier}
    * @param jdbcSupplier Supplier to execute. Not null.
    * @return A publisher that emits the result of the {@code jdbcSupplier}.
    */
@@ -177,9 +181,10 @@ <T> Publisher<T> get(JdbcSupplier<T> jdbcSupplier) {
    * {@code null}, the returned publisher just emits {@code onComplete}. If the
    * supplier throws an error, the returned publisher emits that as
    * {@code onError}.
+   * @param <T> The class of object emitted by the supplied publisher
    * @param publisherSupplier Supplier to execute. Not null.
-   * @return A flat-mapping of the publisher output by the {
-   * @code publisherSupplier}.
+   * @return A flat-mapping of the publisher output by the 
+   * {@code publisherSupplier}.
    */
   <T> Publisher<T> flatMap(JdbcSupplier<Publisher<T>> publisherSupplier) {
     return Mono.from(get(publisherSupplier))
@@ -194,6 +199,7 @@ <T> Publisher<T> flatMap(JdbcSupplier<Publisher<T>> publisherSupplier) {
    * {@link Subscription#request(long)} will only occur when the JDBC connection
    * is not being used by another thread or another publisher.
    *
+   * @param <T> The class of object emitted by the {@code publisher}
    * @param publisher A publisher that uses the JDBC connection
    * @return A Publisher that
    */

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

@@ -84,6 +84,7 @@ static <T> T requireNonNull(T obj, String message) {
   /**
    * Checks if a {@code jdbcConnection} is open, and throws an exception if the
    * check fails.
+   * @param jdbcConnection Connection to check. Not null.
    * @throws IllegalStateException If {@code jdbcConnection} is closed
    */
   static void requireOpenConnection(java.sql.Connection jdbcConnection) {
@@ -289,9 +290,10 @@ static <T> T fromJdbc(JdbcSupplier<T> supplier)
    * caused the error is repeated, and stops reoccurring only if the
    * condition that caused the failure is corrected.
    * @param message A descriptive message that helps another programmer
-   *                understand the cause of failure. Not null.
+   *   understand the cause of failure. Not null.
+   * @param sql The SQL statement which resulted in error. May be null.
    * @param cause An error thrown by other code to indicate a failure, if any.
-   *             May be null.
+   *   May be null.
    * @return A new non-transient exception.
    */
   static R2dbcNonTransientException newNonTransientException(

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

@@ -257,7 +257,7 @@ public AsyncLock getLock() {
    *   jdbc:oracle:thin:@HOST:PORT/DATABASE
    * </pre><p>
    * Alternatively, the host, port, and service name may be specified using an
-   * <a href="https://docs.oracle.com/en/database/oracle/oracle-database/21/netag/identifying-and-accessing-database.html#GUID-8D28E91B-CB72-4DC8-AEFC-F5D583626CF6"></a>
+   * <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 Descriptor</a>. The descriptor may be set as the value of an
    * {@link Option} having the name "descriptor". When the descriptor option is
    * present, the JDBC URL is composed as:

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

@@ -71,9 +71,9 @@ class OracleReadableImpl implements io.r2dbc.spi.Readable {
    * {@code jdbcReadable} and obtains metadata of the values from
    * {@code resultMetadata}.
    * </p>
-   * @param jdbcReadable Readable values from a JDBC Driver.
-   * @param readablesMetadata Metadata of each value
-   * @param adapter Adapts JDBC calls into reactive streams.
+   * @param jdbcReadable Readable values from a JDBC Driver. Not null.
+   * @param readablesMetadata Metadata of each value. Not null.
+   * @param adapter Adapts JDBC calls into reactive streams. Not null.
    */
   private OracleReadableImpl(
     JdbcReadable jdbcReadable, ReadablesMetadata<?> readablesMetadata,
@@ -89,9 +89,11 @@ private OracleReadableImpl(
    * provided {@code jdbcReadable} and {@code metadata}. The metadata
    * object is used to determine the default type mapping of column values.
    * </p>
-   * @param adapter Adapts JDBC calls into reactive streams.
-   * @param jdbcReadable Row data from the Oracle JDBC Driver.
-   * @param metadata Meta-data for the specified 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.
+   * @return A {@code Row} backed by the {@code jdbcReadable} and
+   *   {@code metadata}. Not null.
    */
   static Row createRow(
     JdbcReadable jdbcReadable, RowMetadataImpl metadata,
@@ -104,9 +106,11 @@ static Row createRow(
    * the provided {@code jdbcReadable} and {@code rowMetadata}. The metadata
    * object is used to determine the default type mapping of column values.
    * </p>
-   * @param adapter Adapts JDBC calls into reactive streams.
-   * @param jdbcReadable Row data from the Oracle JDBC Driver.
-   * @param metadata Meta-data for the specified 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.
+   * @return An {@code OutParameters} backed by the {@code jdbcReadable} and
+   *   {@code metadata}. Not null.
    */
   static OutParameters createOutParameters(
     JdbcReadable jdbcReadable, OutParametersMetadataImpl metadata,
@@ -160,7 +164,7 @@ public <T> T get(String name, Class<T> type) {
    * method implements a case-insensitive name match. If more than one
    * value has a matching name, this method returns lowest index of all
    * matching values.
-   * @param name The name of a value
+   * @param name The name of a value. Not null.
    * @return The index of the named value within this {@code Readable}
    * @throws NoSuchElementException If no column has a matching name.
    */
@@ -184,9 +188,9 @@ private int indexOf(String name) {
    * </p>
    *
    * @param index 0-based index of a value
-   * @param type Java type that the value is converted to
+   * @param type Java type that the value is converted to. Not null.
    * @param <T> Java type that the value is converted to
-   * @return The converted column value
+   * @return The converted column value. May be null.
    * @throws R2dbcException If the conversion is not supported.
    */
   private <T> T convert(int index, Class<T> type) {
@@ -359,9 +363,9 @@ private static final class RowImpl
      * determine the default type mapping of column values.
      * </p>
      *
-     * @param jdbcReadable Row data from the Oracle JDBC Driver.
-     * @param metadata Meta-data for the specified row.
-     * @param adapter Adapts JDBC calls into reactive streams.
+     * @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.
      */
     private RowImpl(
       JdbcReadable jdbcReadable,
@@ -401,9 +405,9 @@ private static final class OutParametersImpl
      * {@code outParametersMetaData}.
      * </p>
      *
-     * @param jdbcReadable Readable values from a JDBC Driver.
-     * @param metadata Metadata of each value
-     * @param adapter Adapts JDBC calls into reactive streams.
+     * @param jdbcReadable Readable values from a JDBC Driver. Not null.
+     * @param metadata Metadata of each value. Not null.
+     * @param adapter Adapts JDBC calls into reactive streams. Not null.
      */
     private OutParametersImpl(
       JdbcReadable jdbcReadable,
@@ -419,4 +423,4 @@ public OutParametersMetadata getMetadata() {
     }
   }
 
-}
+}

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

@@ -243,7 +243,6 @@ public Integer getScale() {
    * <p>
    * Implements the R2DBC SPI method by returning the R2DBC {@code Type}.
    * </p>
-   * @return
    */
   @Override
   public Type getType() {
@@ -532,4 +531,4 @@ public int hashCode() {
     }
   }
 
-}
+}

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

@@ -95,7 +95,7 @@ private OracleResultImpl() { }
   /**
    * Publishes the output of a {@code mappingFunction} for each {@code Segment}
    * of this {@code Result}.
-   * @param mappingFunction {@code Segment} mapping function.
+   * @param mappingFunction {@code Segment} mapping function. Not null.
    * @param <T> Output type of the {@code mappingFunction}
    * @return {@code Publisher} of values output by the {@code mappingFunction}
    */
@@ -127,8 +127,8 @@ abstract <T> Publisher<T> publishSegments(
    * {@link #map(BiFunction)}, {@link #map(BiFunction)}, and
    * {@link #getRowsUpdated()}
    * </p>
-   * @param type {@code Segment} type to be mapped
-   * @param mappingFunction {@code Segment} mapping function
+   * @param type {@code Segment} type to be mapped. Not null.
+   * @param mappingFunction {@code Segment} mapping function. Not null.
    * @param <T> {@code Segment} type to be mapped
    * @param <U> Output type of the {@code mappingFunction}
    * @return {@code Publisher} of mapped {@code Segment}s
@@ -277,7 +277,7 @@ public OracleResultImpl filter(Predicate<Segment> filter) {
    * A subsequent call to this method overwrites the publisher that has been
    * set by the current call.
    * </p>
-   * @param onConsumed Publisher to subscribe to when consumed
+   * @param onConsumed Publisher to subscribe to when consumed. Not null.
    * @return true if this result has not already been consumed, and the
    * publisher will be subscribed to. Returns false if the publisher will not
    * be subscribed to because this result is already consumed.
@@ -316,8 +316,8 @@ private static IllegalStateException multipleConsumptionException() {
   /**
    * Creates a {@code Result} that publishes a JDBC {@code resultSet} as
    * {@link RowSegment}s
-   * @param resultSet {@code ResultSet} to publish
-   * @param adapter Adapts JDBC calls into reactive streams.
+   * @param resultSet {@code ResultSet} to publish. Not null.
+   * @param adapter Adapts JDBC calls into reactive streams. Not null.
    * @return A {@code Result} for a ResultSet
    */
   public static OracleResultImpl createQueryResult(
@@ -328,7 +328,8 @@ public static OracleResultImpl createQueryResult(
   /**
    * Creates a {@code Result} that publishes {@code outParameters} as
    * {@link OutSegment}s
-   * @param outParameters {@code OutParameters} to publish
+   * @param outParameters {@code OutParameters} to publish. Not null.
+   * @param adapter Adapts JDBC calls into reactive streams. Not null.
    * @return A {@code Result} for {@code OutParameters}
    */
   static OracleResultImpl createCallResult(
@@ -342,8 +343,8 @@ static OracleResultImpl createCallResult(
    * {@code ResultSet} as {@link RowSegment}s
    * @return A {@code Result} for values generated by DML
    * @param updateCount Update count to publish
-   * @param generatedKeys Generated values to publish
-   * @param adapter Adapts JDBC calls into reactive streams.
+   * @param generatedKeys Generated values to publish. Not null.
+   * @param adapter Adapts JDBC calls into reactive streams. Not null.
    */
   static OracleResultImpl createGeneratedValuesResult(
     long updateCount, ResultSet generatedKeys, ReactiveJdbcAdapter adapter) {
@@ -364,7 +365,7 @@ static OracleResultImpl createUpdateCountResult(long updateCount) {
    * Creates a {@code Result} that publishes a batch of {@code updateCounts}
    * as {@link UpdateCount} segments
    * @return A {@code Result} for a batch DML update
-   * @param updateCounts Update counts to publish
+   * @param updateCounts Update counts to publish. Not null.
    */
   static OracleResultImpl createBatchUpdateResult(long[] updateCounts) {
     return new BatchUpdateResult(updateCounts);
@@ -375,7 +376,7 @@ static OracleResultImpl createBatchUpdateResult(long[] updateCounts) {
    * {@code batchUpdateException} as {@link UpdateCount} segments, followed a
    * {@link Message} segment with the {@code batchUpdateException} mapped to
    * an {@link R2dbcException}
-   * @param batchUpdateException BatchUpdateException to publish
+   * @param batchUpdateException BatchUpdateException to publish. Not null.
    * @return A {@code Result} for a failed DML batch update
    */
   static OracleResultImpl createBatchUpdateErrorResult(
@@ -386,7 +387,7 @@ static OracleResultImpl createBatchUpdateErrorResult(
   /**
    * Creates a {@code Result} that publishes an {@code r2dbcException} as a
    * {@link Message} segment
-   * @param r2dbcException Error to publish
+   * @param r2dbcException Error to publish. Not null.
    * @return A {@code Result} for failed {@code Statement} execution
    */
   static OracleResultImpl createErrorResult(R2dbcException r2dbcException) {
@@ -397,8 +398,8 @@ static OracleResultImpl createErrorResult(R2dbcException r2dbcException) {
    * Creates a {@code Result} that publishes a {@code warning} as a
    * {@link Message} segment, followed by any {@code Segment}s of a
    * {@code result}.
-   * @param warning Warning to publish
-   * @param result Result to publisher
+   * @param warning Warning to publish. Not null.
+   * @param result Result to publisher. Not null.
    * @return A {@code Result} for a {@code Statement} execution that
    * completed with a warning.
    */
@@ -635,8 +636,8 @@ private static final class WarningResult extends OracleResultImpl {
     /**
      * Constructs a result that publishes a {@code warning} as a
      * {@link Message}, and then publishes the segments of a {@code result}.
-     * @param warning Warning to publish
-     * @param result Result of segments to publish after the warning
+     * @param warning Warning to publish. Not null.
+     * @param result Result of segments to publish after the warning. Not null.
      */
     private WarningResult(
       SQLWarning warning, OracleResultImpl result) {
@@ -807,7 +808,7 @@ public String message() {
    * to a single {@link org.reactivestreams.Subscriber}, and rejects additional
    * {@code Subscriber}s by emitting {@code onError} with
    * {@link IllegalStateException}.
-   * @param publisher Publisher that emits signals
+   * @param publisher Publisher that emits signals. Not null.
    * @param <T> Value type of {@code onNext} signals
    * @return A {@code Publisher} that allows a single subscriber
    */

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

@@ -288,10 +288,9 @@ public Statement bind(int index, Object value) {
    * matching name. For instance, when {@code 9} is bound to the parameter
    * named "x", the following SQL would return all names having a birthday on
    * the 9th day of the 9th month:
-   * <pre>
+   * </p><pre>
    * SELECT name FROM birthday WHERE month=:x AND day=:x
    * </pre>
-   * </p>
    * @throws IllegalArgumentException {@inheritDoc}
    * @throws IllegalArgumentException If the {@code identifier} does match a
    * case sensitive parameter name that appears in this {@code Statement's}
@@ -348,17 +347,15 @@ public Statement bindNull(int index, Class<?> type) {
    * SQL command is read from left to right. (Note: It is not recommended to use
    * duplicate parameter names. Use {@link #bindNull(int, Class)} to set the
    * SQL {@code NULL} value for a duplicate parameter name at a given index).
-   * </p>
    * </p><p>
    * If the specified {@code identifier} matches more than one parameter name,
    * then this method binds the SQL {@code NULL} value to all parameters
    * having a matching name. For instance, when {@code NULL} is bound to the
    * parameter named "x", the following SQL would create a birthday with
    * {@code NULL} values for month and day:
-   * <pre>
+   * </p><pre>
    * INSERT INTO birthday (name, month, day) VALUES ('Plato', :x, :x)
    * </pre>
-   * </p>
    * @throws IllegalArgumentException {@inheritDoc}
    * @throws IllegalArgumentException If the {@code identifier} does match a
    * case sensitive parameter name that appears in this {@code Statement's}
@@ -1590,4 +1587,4 @@ protected Publisher<OracleResultImpl> executeJdbc() {
     }
 
   }
-}
+}