feat(gql-status-object): Add GqlNotification interface

Following up on the feedback received on the GQL Status Object feature, which is currently in preview, this update introduces a new `GqlNotification` interface that extends the `GqlStatusObject` and separates the new GQL Status Object hierarchy from the legacy `Notification` type. Eventually, the new hierarchy is expected to replace the legacy `Notification` that is expected to be deprecated and removed at a later date.

Author: injectives

driver/clirr-ignored-differences.xml

@@ -645,4 +645,28 @@
         <method>java.lang.Object as(java.lang.Class)</method>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/summary/Notification</className>
+        <differenceType>4001</differenceType>
+        <to>org/neo4j/driver/summary/GqlStatusObject</to>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/summary/Notification</className>
+        <differenceType>7002</differenceType>
+        <method>java.util.Optional inputPosition()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/summary/Notification</className>
+        <differenceType>7002</differenceType>
+        <method>java.util.Optional classification()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/summary/Notification</className>
+        <differenceType>7002</differenceType>
+        <method>java.util.Optional rawClassification()</method>
+    </difference>
+
 </differences>

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

@@ -23,6 +23,7 @@
  *
  * @since 5.7
  */
+// to be deprecated
 public sealed interface NotificationCategory extends Serializable permits NotificationClassification {
     /**
      * A hint category.

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

@@ -21,7 +21,6 @@
 import org.neo4j.driver.internal.InternalNotificationConfig;
 import org.neo4j.driver.internal.InternalNotificationSeverity;
 import org.neo4j.driver.summary.ResultSummary;
-import org.neo4j.driver.util.Preview;
 
 /**
  * A notification configuration defining what notifications should be supplied by the server.
@@ -40,7 +39,7 @@
  * @see ResultSummary#notifications()
  * @see org.neo4j.driver.summary.Notification
  */
-@Preview(name = "GQL-status object")
+// to be deprecated
 public sealed interface NotificationConfig extends Serializable permits InternalNotificationConfig {
     /**
      * Returns a default notification configuration.

driver/src/main/java/org/neo4j/driver/internal/summary/InternalGqlNotification.java

@@ -0,0 +1,83 @@
+/*
+ * 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.summary;
+
+import java.util.Map;
+import java.util.Optional;
+import org.neo4j.driver.NotificationClassification;
+import org.neo4j.driver.NotificationSeverity;
+import org.neo4j.driver.Value;
+import org.neo4j.driver.summary.GqlNotification;
+import org.neo4j.driver.summary.InputPosition;
+
+public class InternalGqlNotification extends InternalGqlStatusObject implements GqlNotification {
+    private final InputPosition position;
+    private final NotificationSeverity severityLevel;
+    private final String rawSeverityLevel;
+    private final NotificationClassification classification;
+    private final String rawClassification;
+
+    public InternalGqlNotification(
+            String gqlStatus,
+            String statusDescription,
+            Map<String, Value> diagnosticRecord,
+            InputPosition position,
+            NotificationSeverity severityLevel,
+            String rawSeverityLevel,
+            NotificationClassification classification,
+            String rawClassification) {
+        super(gqlStatus, statusDescription, diagnosticRecord);
+        this.position = position;
+        this.severityLevel = severityLevel;
+        this.rawSeverityLevel = rawSeverityLevel;
+        this.classification = classification;
+        this.rawClassification = rawClassification;
+    }
+
+    @Override
+    public Optional<InputPosition> inputPosition() {
+        return Optional.ofNullable(position);
+    }
+
+    @Override
+    public Optional<NotificationSeverity> severityLevel() {
+        return Optional.ofNullable(severityLevel);
+    }
+
+    @Override
+    public Optional<String> rawSeverityLevel() {
+        return Optional.ofNullable(rawSeverityLevel);
+    }
+
+    @Override
+    public Optional<NotificationClassification> classification() {
+        return Optional.ofNullable(classification);
+    }
+
+    @Override
+    public Optional<String> rawClassification() {
+        return Optional.ofNullable(rawClassification);
+    }
+
+    @Override
+    public String toString() {
+        return "InternalGqlNotification{" + "gqlStatus='"
+                + gqlStatus + '\'' + ", statusDescription='"
+                + statusDescription + '\'' + ", diagnosticRecord="
+                + diagnosticRecord + '}';
+    }
+}

driver/src/main/java/org/neo4j/driver/internal/summary/InternalGqlStatusObject.java

@@ -52,9 +52,9 @@ public class InternalGqlStatusObject implements GqlStatusObject {
                     Map.entry("OPERATION", Values.value("")),
                     Map.entry("OPERATION_CODE", Values.value("0"))));
 
-    private final String gqlStatus;
-    private final String statusDescription;
-    private final Map<String, Value> diagnosticRecord;
+    protected final String gqlStatus;
+    protected final String statusDescription;
+    protected final Map<String, Value> diagnosticRecord;
 
     public InternalGqlStatusObject(String gqlStatus, String statusDescription, Map<String, Value> diagnosticRecord) {
         this.gqlStatus = Objects.requireNonNull(gqlStatus);

driver/src/main/java/org/neo4j/driver/internal/summary/InternalNotification.java

@@ -16,18 +16,20 @@
  */
 package org.neo4j.driver.internal.summary;
 
+import static org.neo4j.driver.internal.value.NullValue.NULL;
+
 import java.util.Arrays;
-import java.util.Map;
-import java.util.Objects;
 import java.util.Optional;
+import java.util.function.Function;
 import org.neo4j.driver.NotificationCategory;
 import org.neo4j.driver.NotificationClassification;
 import org.neo4j.driver.NotificationSeverity;
 import org.neo4j.driver.Value;
+import org.neo4j.driver.internal.InternalNotificationSeverity;
 import org.neo4j.driver.summary.InputPosition;
 import org.neo4j.driver.summary.Notification;
 
-public class InternalNotification extends InternalGqlStatusObject implements Notification {
+public class InternalNotification implements Notification {
     public static Optional<NotificationCategory> valueOf(String value) {
         return Arrays.stream(NotificationClassification.values())
                 .filter(type -> type.toString().equals(value))
@@ -45,57 +47,73 @@ public static Optional<NotificationCategory> valueOf(String value) {
                 });
     }
 
+    public static final Function<Value, Notification> VALUE_TO_NOTIFICATION = value -> {
+        var code = value.get("code").asString();
+        var title = value.get("title").asString();
+        var description = value.get("description").asString();
+        var rawSeverityLevel =
+                value.containsKey("severity") ? value.get("severity").asString() : null;
+        var severityLevel =
+                InternalNotificationSeverity.valueOf(rawSeverityLevel).orElse(null);
+        var rawCategory = value.containsKey("category") ? value.get("category").asString() : null;
+        var category = valueOf(rawCategory).orElse(null);
+
+        var posValue = value.get("position");
+        InputPosition position = null;
+        if (posValue != NULL) {
+            position = new InternalInputPosition(
+                    posValue.get("offset").asInt(),
+                    posValue.get("line").asInt(),
+                    posValue.get("column").asInt());
+        }
+
+        return new InternalNotification(
+                code, title, description, severityLevel, rawSeverityLevel, category, rawCategory, position);
+    };
+
     private final String code;
     private final String title;
     private final String description;
     private final NotificationSeverity severityLevel;
     private final String rawSeverityLevel;
-    private final NotificationClassification classification;
-    private final String rawClassification;
+    private final NotificationCategory category;
+    private final String rawCategory;
     private final InputPosition position;
 
     public InternalNotification(
-            String gqlStatus,
-            String statusDescription,
-            Map<String, Value> diagnosticRecord,
             String code,
             String title,
             String description,
             NotificationSeverity severityLevel,
             String rawSeverityLevel,
-            NotificationClassification classification,
-            String rawClassification,
+            NotificationCategory category,
+            String rawCategory,
             InputPosition position) {
-        super(gqlStatus, statusDescription, diagnosticRecord);
-        this.code = Objects.requireNonNull(code);
+        this.code = code;
         this.title = title;
         this.description = description;
         this.severityLevel = severityLevel;
         this.rawSeverityLevel = rawSeverityLevel;
-        this.classification = classification;
-        this.rawClassification = rawClassification;
+        this.category = category;
+        this.rawCategory = rawCategory;
         this.position = position;
     }
 
-    @SuppressWarnings({"deprecation", "RedundantSuppression"})
     @Override
     public String code() {
         return code;
     }
 
-    @SuppressWarnings({"deprecation", "RedundantSuppression"})
     @Override
     public String title() {
         return title;
     }
 
-    @SuppressWarnings({"deprecation", "RedundantSuppression"})
     @Override
     public String description() {
         return description;
     }
 
-    @SuppressWarnings({"deprecation", "RedundantSuppression"})
     @Override
     public InputPosition position() {
         return position;
@@ -111,62 +129,21 @@ public Optional<String> rawSeverityLevel() {
         return Optional.ofNullable(rawSeverityLevel);
     }
 
-    @Override
-    public Optional<NotificationClassification> classification() {
-        return Optional.ofNullable(classification);
-    }
-
-    @Override
-    public Optional<String> rawClassification() {
-        return Optional.ofNullable(rawClassification);
-    }
-
     @Override
     public Optional<NotificationCategory> category() {
-        return Optional.ofNullable(classification);
+        return Optional.ofNullable(category);
     }
 
     @Override
     public Optional<String> rawCategory() {
-        return Optional.ofNullable(rawClassification);
-    }
-
-    @Override
-    public boolean equals(Object o) {
-        if (this == o) return true;
-        if (o == null || getClass() != o.getClass()) return false;
-        if (!super.equals(o)) return false;
-        var that = (InternalNotification) o;
-        return Objects.equals(code, that.code)
-                && Objects.equals(title, that.title)
-                && Objects.equals(description, that.description)
-                && Objects.equals(severityLevel, that.severityLevel)
-                && Objects.equals(rawSeverityLevel, that.rawSeverityLevel)
-                && classification == that.classification
-                && Objects.equals(rawClassification, that.rawClassification)
-                && Objects.equals(position, that.position);
-    }
-
-    @Override
-    public int hashCode() {
-        return Objects.hash(
-                super.hashCode(),
-                code,
-                title,
-                description,
-                severityLevel,
-                rawSeverityLevel,
-                classification,
-                rawClassification,
-                position);
+        return Optional.ofNullable(rawCategory);
     }
 
     @Override
     public String toString() {
         var info = "code=" + code + ", title=" + title + ", description=" + description + ", severityLevel="
-                + severityLevel + ", rawSeverityLevel=" + rawSeverityLevel + ", classification=" + classification
-                + ", rawClassification="
-                + rawClassification;
+                + severityLevel + ", rawSeverityLevel=" + rawSeverityLevel + ", category=" + category + ", rawCategory="
+                + rawCategory;
         return position == null ? info : info + ", position={" + position + "}";
     }
 }