Polishing

Consistent param/return/throws formatting. Add since tags to types introduced after the initial release. Consistent method naming.

Author: mp911de

src/main/java/io/r2dbc/postgresql/Extensions.java

@@ -44,8 +44,8 @@ private Extensions(List<Extension> extensions) {
     /**
      * Create a new {@link Extensions} object.
      *
-     * @param extensions the extensions to hold.
-     * @return a new {@link Extensions} object.
+     * @param extensions the extensions to hold
+     * @return a new {@link Extensions} object
      */
     static Extensions from(Collection<Extension> extensions) {
         return new Extensions(new ArrayList<>(extensions));
@@ -54,7 +54,7 @@ static Extensions from(Collection<Extension> extensions) {
     /**
      * Autodetect extensions using {@link ServiceLoader} mechanism.
      *
-     * @return the detected {@link Extension}s.
+     * @return the detected {@link Extension}s
      */
     static Extensions autodetect() {
         logger.debug("Discovering Extensions using ServiceLoader");
@@ -93,8 +93,8 @@ <T extends Extension> void forEach(Class<T> extensionType, Consumer<T> consumer)
     /**
      * Create a new {@link Extensions} object that contains all extensions from this and {@code other}.
      *
-     * @param other the additional {@link Extensions} to add.
-     * @return a new {@link Extensions} object that contains all extensions from this and {@code other}.
+     * @param other the additional {@link Extensions} to add
+     * @return a new {@link Extensions} object that contains all extensions from this and {@code other}
      */
     Extensions mergeWith(Extensions other) {
         List<Extension> extensions = new ArrayList<>(size() + other.size());
@@ -106,7 +106,7 @@ Extensions mergeWith(Extensions other) {
     /**
      * Returns the number of {@link Extension}s.
      *
-     * @return the number of {@link Extension}s.
+     * @return the number of {@link Extension}s
      */
     public int size() {
         return this.extensions.size();

src/main/java/io/r2dbc/postgresql/api/Notification.java

@@ -26,7 +26,7 @@ public interface Notification {
     /**
      * Returns name of this notification.
      *
-     * @return name of this notification.
+     * @return name of this notification
      */
     String getName();
 

src/main/java/io/r2dbc/postgresql/api/PostgresqlConnection.java

@@ -71,7 +71,7 @@ public interface PostgresqlConnection extends Connection {
      * connection are published as they are received. When the client gets {@link #close() closed}, the subscription {@link Subscriber#onComplete() completes normally}. Otherwise (transport
      * connection disconnected unintentionally) with an {@link R2dbcNonTransientResourceException error}.
      *
-     * @return a hot {@link Flux} of {@link Notification Notifications}.
+     * @return a hot {@link Flux} of {@link Notification Notifications}
      */
     Flux<Notification> getNotifications();
 

src/main/java/io/r2dbc/postgresql/api/PostgresqlException.java

@@ -28,7 +28,7 @@ public interface PostgresqlException {
     /**
      * Returns additional error information.
      *
-     * @return the {@link ErrorDetails}.
+     * @return the {@link ErrorDetails}
      */
     ErrorDetails getErrorDetails();
 

src/main/java/io/r2dbc/postgresql/api/PostgresqlReplicationConnection.java

@@ -37,24 +37,24 @@ public interface PostgresqlReplicationConnection extends Closeable {
     /**
      * Create a replication slot for logical or physical replication.
      *
-     * @param request description of the slot to create.
-     * @return {@link Mono} emitting {@link ReplicationSlot} information once the slot was created.
+     * @param request description of the slot to create
+     * @return {@link Mono} emitting {@link ReplicationSlot} information once the slot was created
      */
     Mono<ReplicationSlot> createSlot(ReplicationSlotRequest request);
 
     /**
      * Starts the {@link ReplicationStream} for logical or physical replication.
      * After starting the replication stream this connection becomes unavailable for slot creation and other streams unless the {@link ReplicationStream} is {@link ReplicationStream#close() closed}.
      *
-     * @param request description of the replication stream to create.
-     * @return {@link Mono} emitting {@link ReplicationStream} once the replication was started.
+     * @param request description of the replication stream to create
+     * @return {@link Mono} emitting {@link ReplicationStream} once the replication was started
      */
     Mono<ReplicationStream> startReplication(ReplicationRequest request);
 
     /**
      * Returns the {@link PostgresqlConnectionMetadata} for this connection.
      *
-     * @return the {@link PostgresqlConnectionMetadata} for this connection.
+     * @return the {@link PostgresqlConnectionMetadata} for this connection
      */
     PostgresqlConnectionMetadata getMetadata();
 

src/main/java/io/r2dbc/postgresql/api/PostgresqlStatement.java

@@ -33,7 +33,7 @@ public interface PostgresqlStatement extends Statement {
     /**
      * {@inheritDoc}
      *
-     * @throws IllegalArgumentException if {@code identifier} is not a {@link String} like {@code $1}, {@code $2}, etc.
+     * @throws IllegalArgumentException if {@code identifier} is not a {@link String} like {@code $1}, {@code $2}, …
      */
     @Override
     PostgresqlStatement bind(String identifier, Object value);
@@ -47,7 +47,7 @@ public interface PostgresqlStatement extends Statement {
     /**
      * {@inheritDoc}
      *
-     * @throws IllegalArgumentException if {@code identifier} is not a {@link String} like {@code $1}, {@code $2}, etc.
+     * @throws IllegalArgumentException if {@code identifier} is not a {@link String} like {@code $1}, {@code $2}, …
      */
     @Override
     PostgresqlStatement bindNull(String identifier, Class<?> type);
@@ -75,7 +75,7 @@ default PostgresqlStatement fetchSize(int rows) {
     /**
      * {@inheritDoc}
      *
-     * @throws IllegalStateException if this {@link Statement} already has a {@code RETURNING clause} or isn't a {@code DELETE}, {@code INSERT}, or {@code UPDATE} command.
+     * @throws IllegalStateException if this {@link Statement} already has a {@code RETURNING clause} or isn't a {@code DELETE}, {@code INSERT}, or {@code UPDATE} command
      */
     @Override
     PostgresqlStatement returnGeneratedValues(String... columns);

src/main/java/io/r2dbc/postgresql/client/Client.java

@@ -43,7 +43,7 @@ public interface Client {
      * disconnects are not visible to the {@link Consumer notification consumer}.
      *
      * @param consumer the consumer of notification messages
-     * @return a new {@link Disposable} that can be used to cancel the underlying subscription.
+     * @return a new {@link Disposable} that can be used to cancel the underlying subscription
      * @throws IllegalArgumentException if {@code consumer} is {@code null}
      */
     Disposable addNotificationListener(Consumer<NotificationResponse> consumer);
@@ -53,7 +53,7 @@ public interface Client {
      * subscription {@link Subscriber#onComplete() completes normally}. Otherwise (transport connection disconnected unintentionally) with an {@link R2dbcNonTransientResourceException error}.
      *
      * @param consumer the consumer of notification messages
-     * @return a new {@link Disposable} that can be used to cancel the underlying subscription.
+     * @return a new {@link Disposable} that can be used to cancel the underlying subscription
      * @throws IllegalArgumentException if {@code consumer} is {@code null}
      * @since 0.8.1
      */
@@ -70,7 +70,7 @@ public interface Client {
      * Perform an exchange of messages. Note that the {@link ReadyForQuery} frame is not emitted through the resulting {@link Flux}.
      *
      * @param requests the publisher of outbound messages
-     * @return a {@link Flux} of incoming messages that ends with the end of conversation (i.e. reception of a {@link ReadyForQuery} message. Th
+     * @return a {@link Flux} of incoming messages that ends with the end of conversation (i.e. reception of a {@link ReadyForQuery} message
      * @throws IllegalArgumentException if {@code requests} is {@code null}
      */
     default Flux<BackendMessage> exchange(Publisher<FrontendMessage> requests) {
@@ -83,7 +83,7 @@ default Flux<BackendMessage> exchange(Publisher<FrontendMessage> requests) {
      * @param takeUntil the predicate that signals the resulting {@link Flux} to terminate. Typically a check if the {@link BackendMessage} is the last frame of a conversation. Note that the
      *                  {@link BackendMessage} that matches the predicate is not emitted through the resulting {@link Flux}.
      * @param requests  the publisher of outbound messages
-     * @return a {@link Flux} of incoming messages that ends with the end of conversation matching {@code takeUntil}. (i.e. reception of a {@link ReadyForQuery} message.
+     * @return a {@link Flux} of incoming messages that ends with the end of conversation matching {@code takeUntil}. (i.e. reception of a {@link ReadyForQuery} message
      * @throws IllegalArgumentException if {@code requests} is {@code null}
      * @since 0.9
      */
@@ -129,14 +129,14 @@ default Flux<BackendMessage> exchange(Publisher<FrontendMessage> requests) {
     /**
      * Return the server version.
      *
-     * @return the server version from {@code server_version}/{@code server_version_num} startup parameters.
+     * @return the server version from {@code server_version}/{@code server_version_num} startup parameters
      */
     Version getVersion();
 
     /**
      * Returns whether the client is connected to a server.
      *
-     * @return {@literal true} if the client is connected to a server.
+     * @return {@code true} if the client is connected to a server
      */
     boolean isConnected();
 

src/main/java/io/r2dbc/postgresql/client/ReactorNettyClient.java

@@ -248,11 +248,11 @@ private static boolean isSslException(Throwable throwable) {
     }
 
     /**
-     * Consume a {@link BackendMessage}. This method can either fully consume the message or it can signal by returning {@literal false} that the method wasn't able to fully consume the message and
+     * Consume a {@link BackendMessage}. This method can either fully consume the message or it can signal by returning {@code false} that the method wasn't able to fully consume the message and
      * that the message needs to be passed to an active {@link Conversation}.
      *
      * @param message the {@link BackendMessage} to handle
-     * @return {@literal false} if the message could not be fully consumed and should be propagated to the active {@link Conversation}
+     * @return {@code false} if the message could not be fully consumed and should be propagated to the active {@link Conversation}
      */
     private boolean consumeMessage(BackendMessage message) {
 

src/main/java/io/r2dbc/postgresql/codec/AbstractArrayCodec.java

@@ -37,7 +37,7 @@
  * Abstract codec class that provides a basis for all concrete
  * implementations of a array-typed {@link Codec}.
  *
- * @param <T> the type that is handled by this {@link Codec}.
+ * @param <T> the type that is handled by this {@link Codec}
  */
 abstract class AbstractArrayCodec<T> extends AbstractCodec<Object[]> {
 
@@ -94,10 +94,6 @@ static String escapeArrayElement(String s) {
         return b.toString();
     }
 
-    abstract T decodeItem(ByteBuf byteBuf);
-
-    abstract T decodeItem(String strValue);
-
     @Override
     final Object[] doDecode(ByteBuf buffer, PostgresqlObjectId dataType, Format format, Class<? extends Object[]> type) {
         Assert.requireNonNull(buffer, "byteBuf must not be null");
@@ -111,20 +107,48 @@ final Object[] doDecode(ByteBuf buffer, PostgresqlObjectId dataType, Format form
         }
     }
 
+    /**
+     * Decode value using binary format.
+     *
+     * @param byteBuffer buffer containing the binary representation of the value to decode
+     * @return decoded value
+     */
+    abstract T doDecodeBinary(ByteBuf byteBuffer);
+
+    /**
+     * Decode value using text format.
+     *
+     * @param text string containing the textual representation of the value to decode
+     * @return decoded value
+     */
+    abstract T doDecodeText(String text);
+
     @Override
     final Parameter doEncode(Object[] value) {
         Assert.requireNonNull(value, "value must not be null");
 
         return encodeArray(() -> {
             ByteBuf byteBuf = this.byteBufAllocator.buffer();
-            encodeAsText(byteBuf, value, this::encodeItem);
+            encodeAsText(byteBuf, value, this::doEncodeText);
             return byteBuf;
         });
     }
 
+    /**
+     * Create the encoded array representation.
+     *
+     * @param encodedSupplier supplies the
+     * @return encoded {@link Parameter} item
+     */
     abstract Parameter encodeArray(Supplier<ByteBuf> encodedSupplier);
 
-    abstract String encodeItem(T value);
+    /**
+     * Encode a single array item using text format.
+     *
+     * @param value the value to encode
+     * @return encoded array item
+     */
+    abstract String doEncodeText(T value);
 
     boolean isTypeAssignable(Class<?> type) {
         Assert.requireNonNull(type, "type must not be null");
@@ -148,18 +172,22 @@ private static int getDimensions(List<?> list) {
         Object inner = list.get(0);
 
         while (inner instanceof List) {
-            inner = ((List) inner).get(0);
+            inner = ((List<?>) inner).get(0);
             dims++;
         }
 
         return dims;
     }
 
     private static Object[] toArray(List<?> list, Class<?> returnType) {
-        return list
-            .stream()
-            .map(e -> (e instanceof List ? toArray((List) e, returnType.getComponentType()) : e))
-            .toArray(r -> (Object[]) Array.newInstance(returnType, list.size()));
+        List<Object> result = new ArrayList<>(list.size());
+
+        for (Object e : list) {
+            Object o = (e instanceof List ? toArray((List<?>) e, returnType.getComponentType()) : e);
+            result.add(o);
+        }
+
+        return result.toArray((Object[]) Array.newInstance(returnType, list.size()));
     }
 
     private List<Object> buildArrayList(ByteBuf buf) {
@@ -245,7 +273,7 @@ private List<Object> buildArrayList(ByteBuf buf) {
 
                 // add element to current array
                 if (b != null && (!b.isEmpty() || wasInsideString)) {
-                    curArray.add(!wasInsideString && b.equals("NULL") ? null : decodeItem(b));
+                    curArray.add(!wasInsideString && b.equals("NULL") ? null : doDecodeText(b));
                 }
 
                 wasInsideString = false;
@@ -352,7 +380,7 @@ private void readArrayAsBinary(ByteBuf buffer, Object[] array, int[] dims, int t
                     continue;
 
                 }
-                array[i] = decodeItem(buffer.readSlice(len));
+                array[i] = doDecodeBinary(buffer.readSlice(len));
             }
         } else {
             for (int i = 0; i < dims[thisDimension]; ++i) {

src/main/java/io/r2dbc/postgresql/codec/AbstractBinaryCodec.java

@@ -33,6 +33,11 @@
 import static io.r2dbc.postgresql.message.Format.FORMAT_TEXT;
 import static io.r2dbc.postgresql.type.PostgresqlObjectId.BYTEA;
 
+/**
+ * Support class for codecs that read/write {@code BYTEA} values.
+ *
+ * @param <T> the type that is handled by this {@link Codec}
+ */
 abstract class AbstractBinaryCodec<T> extends AbstractCodec<T> {
 
     private static final Pattern BLOB_PATTERN = Pattern.compile("\\\\x([\\p{XDigit}]+)?");

src/main/java/io/r2dbc/postgresql/codec/AbstractCodec.java

@@ -34,7 +34,7 @@
  * Abstract codec class that provides a basis for all concrete
  * implementations of a {@link Codec} for well-known {@link PostgresqlObjectId}.
  *
- * @param <T> the type that is handled by this {@link Codec}.
+ * @param <T> the type that is handled by this {@link Codec}
  */
 abstract class AbstractCodec<T> implements Codec<T> {
 
@@ -100,9 +100,10 @@ public Class<?> type() {
      *
      * @param type   the well-known {@link PostgresqlObjectId type OID}
      * @param format the format to use
-     * @param value  {@link Publisher} emitting {@link ByteBuf buffers}. Make sure to use deferred buffer creation instead of {@link Mono#just(Object)} and {@link Flux#just(Object)} to avoid memory
-     *               leaks
+     * @param value  {@link Publisher} emitting {@link ByteBuf buffers}
      * @return the encoded  {@link Parameter}
+     * @implNote use deferred buffer creation instead of {@link Mono#just(Object)} and {@link Flux#just(Object)} to avoid memory
+     * leaks
      */
     static Parameter create(PostgresqlObjectId type, Format format, Publisher<? extends ByteBuf> value) {
         return new Parameter(format, type.getObjectId(), value);
@@ -125,7 +126,7 @@ static Parameter create(PostgresqlObjectId type, Format format, Supplier<? exten
      *
      * @param type   the well-known {@link PostgresqlObjectId type OID}
      * @param format the data type {@link Format}, text or binary
-     * @return the encoded {@code null} value.
+     * @return the encoded {@code null} value
      */
     static Parameter createNull(PostgresqlObjectId type, Format format) {
         return create(type, format, NULL_VALUE);
@@ -136,7 +137,7 @@ static Parameter createNull(PostgresqlObjectId type, Format format) {
      *
      * @param type   the well-known {@link PostgresqlObjectId type OID}
      * @param format the data type {@link Format}, text or binary
-     * @return {@code true} if this codec is able to decode values of {@link Format} and {@link PostgresqlObjectId}.
+     * @return {@code true} if this codec is able to decode values of {@link Format} and {@link PostgresqlObjectId}
      */
     abstract boolean doCanDecode(PostgresqlObjectId type, Format format);
 
@@ -146,14 +147,14 @@ static Parameter createNull(PostgresqlObjectId type, Format format) {
      * @param buffer   the data buffer
      * @param dataType the well-known {@link PostgresqlObjectId type OID}
      * @param format   data type format
-     * @param type     the desired value type.
-     * @return the decoded value. Can be {@code null} if the column value is {@code null}.
+     * @param type     the desired value type
+     * @return the decoded value, can be {@code null} if the column value is {@code null}
      */
     abstract T doDecode(ByteBuf buffer, PostgresqlObjectId dataType, Format format, Class<? extends T> type);
 
     /**
-     * @param value the  {@code value}.
-     * @return the encoded value.
+     * @param value the  {@code value}
+     * @return the encoded value
      */
     abstract Parameter doEncode(T value);