Introduce PreferredCodec for codec preference.

We now provide a two-pass lookup to express codec preference to handle assignable types (i.e. decoding a value with a requested Object or Number type).

Previously, we relied on canDecode(…) outcome but that would render certain codecs not being able to decode values when requesting an assignable type.

[resolves #693]

Author: mp911de

README.md

@@ -477,6 +477,8 @@ This reference table shows the type mapping between [PostgreSQL][p] and Java dat
 | [`xml`][psql-xml-ref]                            | Not yet supported.                                                                                                                                                                                                                                                                                       |
 | [`vector`][psql-vector-ref]                      | **`Vector`**, [`float[]`][java-float-ref]                                                                                                                                                                                                                                                                | 
 
+**Note on `Integer` `oid` usage**: Postgres OIDs are unsigned 32 bit integers. Make sure to consider how Java represents unsigned integers when working with large OID values or convert the value to
+`long` through `Integer.toUnsignedLong(int)`.
 
 Types in **bold** indicate the native (default) Java type.
 
@@ -649,7 +651,7 @@ You don't need to build from source to use R2DBC PostgreSQL (binaries in Maven C
  $ ./mvnw clean install
 ```
 
-If you want to build with the regular `mvn` command, you will need [Maven v3.5.0 or above](https://maven.apache.org/run-maven/index.html).
+If you want to build with the regular `mvn` command, you will need [Maven v3.9.0 or above](https://maven.apache.org/run-maven/index.html).
 
 _Also see [CONTRIBUTING.adoc](.github/CONTRIBUTING.adoc) if you wish to submit pull requests._
 

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

@@ -44,7 +44,7 @@
  *
  * @param <T> the type that is handled by this {@link Codec}.
  */
-abstract class AbstractNumericCodec<T extends Number> extends AbstractCodec<T> implements ArrayCodecDelegate<T> {
+abstract class AbstractNumericCodec<T extends Number> extends AbstractCodec<T> implements ArrayCodecDelegate<T>, PreferredCodec {
 
     private static final Set<PostgresqlObjectId> SUPPORTED_TYPES = EnumSet.of(INT2, INT4, INT8, FLOAT4, FLOAT8, NUMERIC, OID);
 
@@ -56,16 +56,8 @@ abstract class AbstractNumericCodec<T extends Number> extends AbstractCodec<T> i
     }
 
     @Override
-    public boolean canDecode(int dataType, Format format, Class<?> type) {
-        Assert.requireNonNull(format, "format must not be null");
-        Assert.requireNonNull(type, "type must not be null");
-
-        if (type == Object.class) {
-            if (PostgresqlObjectId.isValid(dataType) && PostgresqlObjectId.valueOf(dataType) != getDefaultType()) {
-                return false;
-            }
-        }
-        return super.canDecode(dataType, format, type);
+    public boolean isPreferred(int dataType, Format format, Class<?> type) {
+        return isPreferenceType(type) && PostgresqlObjectId.isValid(dataType) && PostgresqlObjectId.valueOf(dataType) == getDefaultType();
     }
 
     @Override
@@ -157,6 +149,10 @@ public Iterable<PostgresTypeIdentifier> getDataTypes() {
      */
     abstract PostgresqlObjectId getDefaultType();
 
+    static boolean isPreferenceType(Class<?> type) {
+        return type == Object.class || type == Number.class;
+    }
+
     private static <T> T potentiallyConvert(Number number, Class<T> expectedType, Function<Number, T> converter) {
         return expectedType.isInstance(number) ? expectedType.cast(number) : converter.apply(number);
     }

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

@@ -45,7 +45,7 @@
  *
  * @param <T> the type that is handled by this {@link Codec}
  */
-abstract class AbstractTemporalCodec<T extends Temporal> extends BuiltinCodecSupport<T> {
+abstract class AbstractTemporalCodec<T extends Temporal> extends BuiltinCodecSupport<T> implements PreferredCodec {
 
     private static final Set<PostgresqlObjectId> SUPPORTED_TYPES = EnumSet.of(DATE, TIMESTAMP, TIMESTAMPTZ, TIME, TIMETZ);
 
@@ -62,16 +62,8 @@ abstract class AbstractTemporalCodec<T extends Temporal> extends BuiltinCodecSup
     }
 
     @Override
-    public boolean canDecode(int dataType, Format format, Class<?> type) {
-        Assert.requireNonNull(format, "format must not be null");
-        Assert.requireNonNull(type, "type must not be null");
-
-        if (type == Object.class) {
-            if (PostgresqlObjectId.isValid(dataType) && PostgresqlObjectId.valueOf(dataType) != getDefaultType()) {
-                return false;
-            }
-        }
-        return super.canDecode(dataType, format, type);
+    public boolean isPreferred(int dataType, Format format, Class<?> type) {
+        return isPreferenceType(type) && PostgresqlObjectId.isValid(dataType) && PostgresqlObjectId.valueOf(dataType) == getDefaultType();
     }
 
     @Override
@@ -166,4 +158,8 @@ static <T> T potentiallyConvert(Temporal temporal, Class<T> expectedType, Functi
         return expectedType.isInstance(temporal) ? expectedType.cast(temporal) : converter.apply(temporal);
     }
 
+    private static boolean isPreferenceType(Class<?> type) {
+        return type == Object.class || type == Temporal.class;
+    }
+
 }

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

@@ -45,7 +45,12 @@ public EncodedParameter encodeNull() {
     }
 
     @Override
-    boolean doCanDecode(PostgresqlObjectId type, @Nullable Format format) {
+    public boolean canDecode(int dataType, Format format, Class<?> type) {
+        return super.canDecode(dataType, format, type) && this.delegate.canDecode(dataType, format, Short.class);
+    }
+
+    @Override
+    boolean doCanDecode(PostgresqlObjectId type, Format format) {
         Assert.requireNonNull(type, "type must not be null");
 
         return this.delegate.doCanDecode(type, format);

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

@@ -21,6 +21,7 @@
 import io.r2dbc.postgresql.message.Format;
 import io.r2dbc.postgresql.util.Assert;
 
+import java.lang.reflect.Array;
 import java.util.EnumSet;
 import java.util.Set;
 
@@ -43,7 +44,7 @@
  *
  * @param <T>
  */
-final class ConvertingArrayCodec<T> extends ArrayCodec<T> {
+final class ConvertingArrayCodec<T> extends ArrayCodec<T> implements PreferredCodec {
 
     static final Set<PostgresqlObjectId> NUMERIC_ARRAY_TYPES = EnumSet.of(INT2_ARRAY, INT4_ARRAY, INT8_ARRAY, FLOAT4_ARRAY, FLOAT8_ARRAY, NUMERIC_ARRAY, OID_ARRAY);
 
@@ -53,25 +54,27 @@ final class ConvertingArrayCodec<T> extends ArrayCodec<T> {
 
     private final Class<T> componentType;
 
+    private final Class<?> arrayClass;
+
     private final Set<PostgresqlObjectId> supportedTypes;
 
     public ConvertingArrayCodec(ByteBufAllocator byteBufAllocator, ArrayCodecDelegate<T> delegate, Class<T> componentType, Set<PostgresqlObjectId> supportedTypes) {
         super(byteBufAllocator, delegate, componentType);
         this.delegate = delegate;
         this.componentType = componentType;
+        this.arrayClass = Array.newInstance(this.componentType, 0).getClass();
         this.supportedTypes = supportedTypes;
     }
 
     @Override
-    public boolean canDecode(int dataType, Format format, Class<?> type) {
-
-        // consider delegate priority
-        if (type == Object.class && dataType == getDelegate().getArrayDataType().getObjectId()) {
-            return true;
-        }
+    public boolean isPreferred(int dataType, Format format, Class<?> type) {
+        return type == Object.class && dataType == getDelegate().getArrayDataType().getObjectId();
+    }
 
+    @Override
+    public boolean canDecode(int dataType, Format format, Class<?> type) {
         return PostgresqlObjectId.isValid(dataType) && this.supportedTypes.contains(PostgresqlObjectId.valueOf(dataType)) &&
-            type.isArray() && getActualComponentType(type).isAssignableFrom(getComponentType());
+            (type.isAssignableFrom(this.arrayClass) || (type.isArray() && getActualComponentType(type).isAssignableFrom(getComponentType())));
     }
 
     @Override

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

@@ -50,6 +50,10 @@ synchronized <T> Codec<T> findCodec(Predicate<Codec<?>> predicate) {
 
     @Override
     public <T> Codec<T> findDecodeCodec(int dataType, Format format, Class<? extends T> type) {
+        Codec<T> preferred = findCodec(codec -> codec instanceof PreferredCodec && ((PreferredCodec) codec).isPreferred(dataType, format, type) && codec.canDecode(dataType, format, type));
+        if (preferred != null) {
+            return preferred;
+        }
         return findCodec(codec -> codec.canDecode(dataType, format, type));
     }
 

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

@@ -31,6 +31,11 @@ final class IntegerCodec extends AbstractNumericCodec<Integer> implements Primit
         super(Integer.class, byteBufAllocator);
     }
 
+    @Override
+    public boolean isPreferred(int dataType, Format format, Class<?> type) {
+        return (isPreferenceType(type) && dataType == PostgresqlObjectId.OID.getObjectId()) || super.isPreferred(dataType, format, type);
+    }
+
     @Override
     public PrimitiveCodec<Integer> getPrimitiveCodec() {
         return new PrimitiveCodec<>(Integer.TYPE, Integer.class, this);

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

@@ -40,6 +40,11 @@ class IntegerCodecDelegate<T> extends AbstractCodec<T> {
         this.fromIntegerConverter = fromIntegerConverter;
     }
 
+    @Override
+    public boolean canDecode(int dataType, Format format, Class<?> type) {
+        return super.canDecode(dataType, format, type) && this.delegate.canDecode(dataType, format, Integer.class);
+    }
+
     @Override
     boolean doCanDecode(PostgresqlObjectId type, Format format) {
         return this.delegate.doCanDecode(type, format);

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

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.r2dbc.postgresql.codec;
+
+import io.r2dbc.postgresql.message.Format;
+
+/**
+ * Marker interface to indicate a codec expresses preference for certain data types and formats.
+ *
+ * @since 1.0.9
+ */
+interface PreferredCodec {
+
+    /**
+     * Determine whether the codec expresses preference for the given data type, format and type.
+     * <p>Codecs that return {@code true} should also return {@code true} from {@link Codec#canDecode(int, Format, Class)} for the same arguments to honor the API contract between the two methods.
+     *
+     * @param dataType the Postgres OID to decode
+     * @param format   the data type {@link Format}, text or binary
+     * @param type     the desired value type
+     * @return {@code true} if this codec wants to be preferred to decode values for tge given {@code dataType} and {@link Format}
+     */
+    boolean isPreferred(int dataType, Format format, Class<?> type);
+
+}

src/test/java/io/r2dbc/postgresql/codec/DefaultCodecLookupUnitTest.java

@@ -19,14 +19,12 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
-import org.mockito.ArgumentCaptor;
-import org.mockito.Captor;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 
+import java.time.temporal.Temporal;
 import java.util.Arrays;
 import java.util.List;
-import java.util.function.Predicate;
 
 import static io.r2dbc.postgresql.codec.PostgresqlObjectId.INT2;
 import static io.r2dbc.postgresql.message.Format.FORMAT_TEXT;
@@ -44,9 +42,6 @@ class DefaultCodecLookupUnitTest {
 
     DefaultCodecLookup codecFinder;
 
-    @Captor
-    ArgumentCaptor<Predicate<Codec<?>>> predicateArgumentCaptor;
-
     @Mock
     Codec<String> stringCodec;
 
@@ -112,4 +107,15 @@ void findEncodeNullCodecNotFound() {
         assertThat(this.codecFinder.findEncodeNullCodec(DefaultCodecsUnitTests.class)).isNull();
     }
 
+    @Test
+    void considersPreference() {
+        assertThat(this.codecFinder.findDecodeCodec(PostgresqlObjectId.OID.getObjectId(), FORMAT_TEXT, Object.class)).isInstanceOf(IntegerCodec.class);
+        assertThat(this.codecFinder.findDecodeCodec(PostgresqlObjectId.OID.getObjectId(), FORMAT_TEXT, Number.class)).isInstanceOf(IntegerCodec.class);
+        assertThat(this.codecFinder.findDecodeCodec(PostgresqlObjectId.INT4.getObjectId(), FORMAT_TEXT, Object.class)).isInstanceOf(IntegerCodec.class);
+
+        assertThat(this.codecFinder.findDecodeCodec(PostgresqlObjectId.INT8.getObjectId(), FORMAT_TEXT, Object.class)).isInstanceOf(LongCodec.class);
+        assertThat(this.codecFinder.findDecodeCodec(PostgresqlObjectId.INT8.getObjectId(), FORMAT_TEXT, Number.class)).isInstanceOf(LongCodec.class);
+        assertThat(this.codecFinder.findDecodeCodec(PostgresqlObjectId.DATE.getObjectId(), FORMAT_TEXT, Temporal.class)).isInstanceOf(LocalDateCodec.class);
+    }
+
 }