feat(unsupportedType): add support for Bolt Unsupported Type

This update adds support for a new `TypeSystem#UNSUPPORTED()` type. The unsupported type may occur when a new type is introduced in the Neo4j server and the driver is connected over an older Bolt Protocol version that does not support this type. A new `UnsupportedTypeData` object provides information about the unsupported type and the minimum Bolt version needed to support it. However, the `UnsupportedTypeData` object itself requires at least Bolt Protocol 6.0.

Author: injectives

driver/clirr-ignored-differences.xml

@@ -935,4 +935,10 @@
         <differenceType>8001</differenceType>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/types/TypeSystem</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.types.Type UNSUPPORTED()</method>
+    </difference>
+
 </differences>

driver/src/main/java/org/neo4j/driver/Value.java

@@ -42,6 +42,7 @@
 import org.neo4j.driver.types.Relationship;
 import org.neo4j.driver.types.Type;
 import org.neo4j.driver.types.TypeSystem;
+import org.neo4j.driver.types.UnsupportedTypeData;
 import org.neo4j.driver.types.Vector;
 import org.neo4j.driver.util.Immutable;
 import org.neo4j.driver.util.Preview;
@@ -684,6 +685,10 @@ public interface Value extends MapAccessor, MapAccessorWithDefaultValue {
      *             <td>{@link TypeSystem#VECTOR}</td>
      *             <td>{@link Vector}</td>
      *         </tr>
+     *         <tr>
+     *             <td>{@link TypeSystem#UNSUPPORTED}</td>
+     *             <td>{@link UnsupportedTypeData}</td>
+     *         </tr>
      *     </tbody>
      * </table>
      *

driver/src/main/java/org/neo4j/driver/Values.java

@@ -67,6 +67,7 @@
 import org.neo4j.driver.internal.value.PointValue;
 import org.neo4j.driver.internal.value.StringValue;
 import org.neo4j.driver.internal.value.TimeValue;
+import org.neo4j.driver.internal.value.UnsupportedValue;
 import org.neo4j.driver.internal.value.VectorValue;
 import org.neo4j.driver.mapping.Property;
 import org.neo4j.driver.types.Entity;
@@ -77,6 +78,7 @@
 import org.neo4j.driver.types.Point;
 import org.neo4j.driver.types.Relationship;
 import org.neo4j.driver.types.TypeSystem;
+import org.neo4j.driver.types.UnsupportedTypeData;
 import org.neo4j.driver.types.Vector;
 import org.neo4j.driver.util.Preview;
 
@@ -182,6 +184,9 @@ public static Value value(Object value) {
         if (value instanceof Vector vector) {
             return value(vector);
         }
+        if (value instanceof UnsupportedTypeData) {
+            return value((UnsupportedTypeData) value);
+        }
 
         if (value instanceof List<?>) {
             return value((List<Object>) value);
@@ -1149,4 +1154,8 @@ private static Value vector(Object array) {
                     "Unsupported vector element type: " + array.getClass().getName());
         }
     }
+
+    private static Value value(UnsupportedTypeData unsupportedTypeData) {
+        return new UnsupportedValue(unsupportedTypeData);
+    }
 }

driver/src/main/java/org/neo4j/driver/internal/InternalUnsupportedTypeData.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * 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
+ *
+ *     http://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 org.neo4j.driver.internal;
+
+import java.util.Optional;
+import org.neo4j.driver.types.UnsupportedTypeData;
+
+public record InternalUnsupportedTypeData(String name, String minProtocolVersion, String messageValue)
+        implements UnsupportedTypeData {
+    @Override
+    public Optional<String> message() {
+        return Optional.ofNullable(messageValue);
+    }
+}

driver/src/main/java/org/neo4j/driver/internal/types/InternalTypeSystem.java

@@ -36,6 +36,7 @@
 import static org.neo4j.driver.internal.types.TypeConstructor.RELATIONSHIP;
 import static org.neo4j.driver.internal.types.TypeConstructor.STRING;
 import static org.neo4j.driver.internal.types.TypeConstructor.TIME;
+import static org.neo4j.driver.internal.types.TypeConstructor.UNSUPPORTED;
 import static org.neo4j.driver.internal.types.TypeConstructor.VECTOR;
 
 import org.neo4j.driver.Value;
@@ -72,6 +73,7 @@ public class InternalTypeSystem implements TypeSystem {
     private final TypeRepresentation durationType = constructType(DURATION);
     private final TypeRepresentation nullType = constructType(NULL);
     private final TypeRepresentation vectorType = constructType(VECTOR);
+    private final TypeRepresentation unsupportedType = constructType(UNSUPPORTED);
 
     private InternalTypeSystem() {}
 
@@ -180,6 +182,11 @@ public Type VECTOR() {
         return vectorType;
     }
 
+    @Override
+    public Type UNSUPPORTED() {
+        return unsupportedType;
+    }
+
     private TypeRepresentation constructType(TypeConstructor tyCon) {
         return new TypeRepresentation(tyCon);
     }

driver/src/main/java/org/neo4j/driver/internal/types/TypeConstructor.java

@@ -57,7 +57,8 @@ public boolean covers(Value value) {
     DATE_TIME,
     DURATION,
     NULL,
-    VECTOR;
+    VECTOR,
+    UNSUPPORTED;
 
     private static TypeConstructor typeConstructorOf(Value value) {
         return ((InternalValue) value).typeConstructor();

driver/src/main/java/org/neo4j/driver/internal/value/BoltValueFactory.java

@@ -29,16 +29,19 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
+import org.neo4j.bolt.connection.BoltProtocolVersion;
 import org.neo4j.bolt.connection.values.Node;
 import org.neo4j.bolt.connection.values.Path;
 import org.neo4j.bolt.connection.values.Relationship;
 import org.neo4j.bolt.connection.values.Segment;
+import org.neo4j.bolt.connection.values.Type;
 import org.neo4j.bolt.connection.values.Value;
 import org.neo4j.bolt.connection.values.ValueFactory;
 import org.neo4j.driver.Values;
 import org.neo4j.driver.internal.InternalNode;
 import org.neo4j.driver.internal.InternalPath;
 import org.neo4j.driver.internal.InternalRelationship;
+import org.neo4j.driver.internal.InternalUnsupportedTypeData;
 
 public class BoltValueFactory implements ValueFactory {
     private static final BoltValueFactory INSTANCE = new BoltValueFactory();
@@ -265,6 +268,15 @@ public Value vector(Class<?> elementType, Object elements) {
         return value;
     }
 
+    @Override
+    public Value unsupportedTypeData(String name, BoltProtocolVersion minBoltVersion, Map<String, Value> extra) {
+        var message = extra.get("message");
+        var messageString =
+                message != null ? message.boltValueType().equals(Type.STRING) ? message.asString() : null : null;
+        return (InternalValue)
+                Values.value((Object) new InternalUnsupportedTypeData(name, minBoltVersion.toString(), messageString));
+    }
+
     @Override
     public Value unsupportedDateTimeValue(DateTimeException e) {
         return new UnsupportedDateTimeValue(e);

driver/src/main/java/org/neo4j/driver/internal/value/UnsupportedValue.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * 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
+ *
+ *     http://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 org.neo4j.driver.internal.value;
+
+import org.neo4j.driver.internal.types.InternalTypeSystem;
+import org.neo4j.driver.types.UnsupportedTypeData;
+
+public final class UnsupportedValue extends ObjectValueAdapter<UnsupportedTypeData> {
+    public UnsupportedValue(UnsupportedTypeData adapted) {
+        super(adapted);
+    }
+
+    @Override
+    public org.neo4j.bolt.connection.values.Type boltValueType() {
+        return org.neo4j.bolt.connection.values.Type.UNSUPPORTED;
+    }
+
+    @Override
+    public org.neo4j.driver.types.Type type() {
+        return InternalTypeSystem.TYPE_SYSTEM.UNSUPPORTED();
+    }
+
+    @Override
+    public <T> T as(Class<T> targetClass) {
+        if (targetClass.isAssignableFrom(UnsupportedTypeData.class)) {
+            return targetClass.cast(asObject());
+        }
+        return asMapped(targetClass);
+    }
+}

driver/src/main/java/org/neo4j/driver/types/TypeSystem.java

@@ -164,4 +164,20 @@ static TypeSystem getDefault() {
      */
     @Preview(name = "Neo4j Vector")
     Type VECTOR();
+
+    /**
+     * Returns a {@link Type} instance representing an unsupported type.
+     * <p>
+     * An unsupported type may occur when a new type is introduced in the Neo4j server and the driver is connected over
+     * an older Bolt Protocol version that does not support this type. The {@link UnsupportedTypeData} object provides
+     * information about the unsupported type and the {@link UnsupportedTypeData#minProtocolVersion()} needed to support
+     * it. However, the {@link UnsupportedTypeData} object itself requires at least Bolt Protocol 6.0.
+     * <p>
+     * Note that the unsupported type MUST NOT be sent to the server.
+     *
+     * @return the type instance
+     * @since 6.0.0
+     * @see UnsupportedTypeData
+     */
+    Type UNSUPPORTED();
 }

driver/src/main/java/org/neo4j/driver/types/UnsupportedTypeData.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * 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
+ *
+ *     http://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 org.neo4j.driver.types;
+
+import java.util.Optional;
+
+/**
+ * An object instance of {@link TypeSystem#UNSUPPORTED()} type.
+ * <p>
+ * This object holds information about the unsupported type and the {@link #minProtocolVersion()} needed to support it.
+ * <p>
+ * Note that this object MUST NOT be sent to the server.
+ *
+ * @since 6.0.0
+ */
+public interface UnsupportedTypeData {
+    /**
+     * Returns the type name.
+     * @return the type name
+     */
+    String name();
+
+    /**
+     * The minimum Bolt Protocol version needed to support this type.
+     * @return the minimum Bolt Protocol version
+     */
+    String minProtocolVersion();
+
+    /**
+     * An optional message.
+     * @return the message
+     */
+    Optional<String> message();
+}