feat(gql-status-object): Introduce GqlNotification

Following up on the feedback received on the GQL Status Object feature, which is currently in preview, this update separates the new GQL Status Object hierarchy from the legacy `Notification` type by introducing a new `GqlNotification` interface that extends the `GqlStatusObject`. This should make it easier to understand the new GQL Status Objects and migrate from using the legacy `Notification` to the new types.

Eventually, the new hierarchy is expected to replace the legacy `Notification` that is expected to be deprecated and phased out 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,6 @@
  * @see ResultSummary#notifications()
  * @see org.neo4j.driver.summary.Notification
  */
-@Preview(name = "GQL-status object")
 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 + "}";
     }
 }