feat(unknownType): add support for Bolt Unknown Type

Author: injectives

driver/clirr-ignored-differences.xml

@@ -905,5 +905,10 @@
         <differenceType>8001</differenceType>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/types/TypeSystem</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.types.Type UNKNOWN()</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.UnknownTypeData;
 import org.neo4j.driver.util.Immutable;
 import org.neo4j.driver.util.Preview;
 
@@ -679,6 +680,10 @@ public interface Value extends MapAccessor, MapAccessorWithDefaultValue {
      *             <td>{@link TypeSystem#RELATIONSHIP}</td>
      *             <td>{@link Relationship}</td>
      *         </tr>
+     *         <tr>
+     *             <td>{@link TypeSystem#UNKNOWN}</td>
+     *             <td>{@link UnknownTypeData}</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.UnknownValue;
 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.UnknownTypeData;
 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 UnknownTypeData) {
+            return value((UnknownTypeData) 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(UnknownTypeData unknownTypeData) {
+        return new UnknownValue(unknownTypeData);
+    }
 }

driver/src/main/java/org/neo4j/driver/internal/InternalUnknownTypeData.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.UnknownTypeData;
+
+public record InternalUnknownTypeData(String name, String minProtocolVersion, String messageValue)
+        implements UnknownTypeData {
+    @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.UNKNOWN;
 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 unknownType = constructType(UNKNOWN);
 
     private InternalTypeSystem() {}
 
@@ -180,6 +182,11 @@ public Type VECTOR() {
         return vectorType;
     }
 
+    @Override
+    public Type UNKNOWN() {
+        return unknownType;
+    }
+
     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,
+    UNKNOWN;
 
     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.InternalUnknownTypeData;
 
 public class BoltValueFactory implements ValueFactory {
     private static final BoltValueFactory INSTANCE = new BoltValueFactory();
@@ -265,6 +268,14 @@ public Value vector(Class<?> elementType, Object elements) {
         return value;
     }
 
+    @Override
+    public Value unknown(String name, BoltProtocolVersion minBoltVersion, Map<String, Value> extra) {
+        var message = extra.get("message");
+        var messageString = message.boltValueType().equals(Type.STRING) ? message.asString() : null;
+        return (InternalValue)
+                Values.value((Object) new InternalUnknownTypeData(name, minBoltVersion.toString(), messageString));
+    }
+
     @Override
     public Value unsupportedDateTimeValue(DateTimeException e) {
         return new UnsupportedDateTimeValue(e);

driver/src/main/java/org/neo4j/driver/internal/value/UnknownValue.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.UnknownTypeData;
+
+public final class UnknownValue extends ObjectValueAdapter<UnknownTypeData> {
+    public UnknownValue(UnknownTypeData adapted) {
+        super(adapted);
+    }
+
+    @Override
+    public org.neo4j.bolt.connection.values.Type boltValueType() {
+        return org.neo4j.bolt.connection.values.Type.UNKNOWN;
+    }
+
+    @Override
+    public org.neo4j.driver.types.Type type() {
+        return InternalTypeSystem.TYPE_SYSTEM.UNKNOWN();
+    }
+
+    @Override
+    public <T> T as(Class<T> targetClass) {
+        if (targetClass.isAssignableFrom(UnknownTypeData.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 unknown type.
+     * <p>
+     * An unknown 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 UnknownTypeData} object provides information
+     * about the unknown type and the {@link UnknownTypeData#minProtocolVersion()} needed to transmit it. However, the
+     * {@link UnknownTypeData} object itself requires at least Bolt Protocol 6.0.
+     * <p>
+     * Note that the unknown type MUST NOT be sent to the server.
+     *
+     * @return the type instance
+     * @since 6.0.0
+     * @see UnknownTypeData
+     */
+    Type UNKNOWN();
 }

driver/src/main/java/org/neo4j/driver/types/UnknownTypeData.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#UNKNOWN()} type.
+ * <p>
+ * This object contains information about the unknown type and the {@link #minProtocolVersion()} needed to transmit it.
+ * <p>
+ * Note that this object MUST NOT be sent to the server.
+ *
+ * @since 6.0.0
+ */
+public interface UnknownTypeData {
+    /**
+     * Returns the type name.
+     * @return the type name
+     */
+    String name();
+
+    /**
+     * The minimum Bolt Protocol version needed to transmit this type.
+     * @return the minimum Bolt Protocol version
+     */
+    String minProtocolVersion();
+
+    /**
+     * An optional message.
+     * @return the message
+     */
+    Optional<String> message();
+}