Introduce notification configuration, severity and category

This update extends the existing `Notification` API to support new 5.7 server features.

A new `NotificationSeverity` type represents a curated set of ordered notification severity levels.

It includes 2 levels:
- `INFORMATION`
- `WARNING`

A new `NotificationCategory` type represents a curated set of notification categories.

It includes 6 categories:
- `HINT`
- `UNRECOGNIZED`
- `UNSUPPORTED`
- `PERFORMANCE`
- `DEPRECATION`
- `GENERIC`

The `Notification` class has been extended with the following 4 methods:
- `Optional<NotificationSeverity> severityLevel()`
- `Optional<String> rawSeverityLevel()`
- `Optional<NotificationCategory> category()`
- `Optional<String> rawCategory()`

The `raw` methods return a `String` representation returned by the server. In case of an unrecognised value, both `severityLevel()` and `category()` methods will return an empty `Optional`. This may happen if a new value is introduced in a future server version and a previous driver version does not support it. Additionally, empty `Optional` may be returned when driver communicates with a server version that does not support these entries.

The `severity()` method has been deprecated in favour of the `rawSeverityLevel()` method.

A new `NotificationConfig` type has been introduced to allow notification preferences management. By default, the server determines what notifications are provided to the driver. However, user can set a minimum severity level and/or a set of disabled notification categories to manage its expectations. This feature is only supported on Bolt protocol version 5.2 and above.

Both the `Config` and the `SessionConfig` support this new configuration.

Sample usage:
```java
// sets minimum notification severity level to WARNING
// and explicitly disables both GENERIC and HINT notification categories
var driverConfig = Config.builder()
        .withNotificationConfig(NotificationConfig.enableMinimumSeverityAndDisableCategories(NotificationSeverity.WARNING, Set.of(NotificationCategory.GENERIC, NotificationCategory.HINT)))
        .build();
// disables all notifications
var sessionConfig = SessionConfig.builder()
        .withNotificationConfig(NotificationConfig.disableAll())
        .build();
```

This update includes support for both 5.1 and 5.2 versions. The latter is required for the full support of the new notification updates.

Author: injectives

driver/clirr-ignored-differences.xml

@@ -433,4 +433,28 @@
         <method>org.neo4j.driver.BookmarkManager queryTaskBookmarkManager()</method>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/summary/Notification</className>
+        <differenceType>7012</differenceType>
+        <method>java.util.Optional severityLevel()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/summary/Notification</className>
+        <differenceType>7012</differenceType>
+        <method>java.util.Optional rawSeverityLevel()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/summary/Notification</className>
+        <differenceType>7012</differenceType>
+        <method>java.util.Optional category()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/summary/Notification</className>
+        <differenceType>7012</differenceType>
+        <method>java.util.Optional rawCategory()</method>
+    </difference>
+
 </differences>

driver/pom.xml

@@ -238,6 +238,15 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-failsafe-plugin</artifactId>
       </plugin>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <configuration>
+                <source>17</source>
+                <target>17</target>
+                <compilerArgs>--enable-preview</compilerArgs>
+            </configuration>
+        </plugin>
     </plugins>
   </build>
 

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

@@ -143,6 +143,10 @@ public final class Config implements Serializable {
      * The user_agent configured for this driver.
      */
     private final String userAgent;
+    /**
+     * The notification config.
+     */
+    private final NotificationConfig notificationConfig;
     /**
      * The {@link MetricsAdapter}.
      */
@@ -166,6 +170,7 @@ private Config(ConfigBuilder builder) {
         this.maxTransactionRetryTimeMillis = builder.maxTransactionRetryTimeMillis;
         this.resolver = builder.resolver;
         this.fetchSize = builder.fetchSize;
+        this.notificationConfig = builder.notificationConfig;
 
         this.eventLoopThreads = builder.eventLoopThreads;
         this.metricsAdapter = builder.metricsAdapter;
@@ -311,6 +316,15 @@ public long fetchSize() {
         return fetchSize;
     }
 
+    /**
+     * Returns notification config.
+     * @return the notification config
+     * @since 5.7
+     */
+    public NotificationConfig notificationConfig() {
+        return notificationConfig;
+    }
+
     /**
      * Returns the number of {@link io.netty.channel.EventLoop} threads.
      * @return the number of threads
@@ -363,6 +377,7 @@ public static final class ConfigBuilder {
         private MetricsAdapter metricsAdapter = MetricsAdapter.DEV_NULL;
         private long fetchSize = FetchSizeUtil.DEFAULT_FETCH_SIZE;
         private int eventLoopThreads = 0;
+        private NotificationConfig notificationConfig = NotificationConfig.defaultConfig();
 
         private ConfigBuilder() {}
 
@@ -757,6 +772,17 @@ public ConfigBuilder withUserAgent(String userAgent) {
             return this;
         }
 
+        /**
+         * Sets notification config.
+         * @param notificationConfig the notification config
+         * @return this builder
+         * @since 5.7
+         */
+        public ConfigBuilder withNotificationConfig(NotificationConfig notificationConfig) {
+            this.notificationConfig = Objects.requireNonNull(notificationConfig, "notificationConfig must not be null");
+            return this;
+        }
+
         /**
          * Extracts the driver version from the driver jar MANIFEST.MF file.
          */

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

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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;
+
+import java.io.Serializable;
+import org.neo4j.driver.internal.InternalNotificationCategory;
+import org.neo4j.driver.internal.InternalNotificationCategory.Type;
+
+/**
+ * A notification category.
+ *
+ * @since 5.7
+ */
+public sealed interface NotificationCategory extends Serializable permits InternalNotificationCategory {
+    /**
+     * A hint category.
+     * <p>
+     * For instance, the given hint cannot be satisfied.
+     */
+    NotificationCategory HINT = new InternalNotificationCategory(Type.HINT);
+
+    /**
+     * An unrecognized category.
+     * <p>
+     * For instance, the query or command mentions entities that are unknown to the system.
+     */
+    NotificationCategory UNRECOGNIZED = new InternalNotificationCategory(Type.UNRECOGNIZED);
+
+    /**
+     * An unsupported category.
+     * <p>
+     * For instance, the query/command is trying to use features that are not supported by the current system or using
+     * features that are experimental and should not be used in production.
+     */
+    NotificationCategory UNSUPPORTED = new InternalNotificationCategory(Type.UNSUPPORTED);
+
+    /**
+     * A performance category.
+     * <p>
+     * For instance, the query uses costly operations and might be slow.
+     */
+    NotificationCategory PERFORMANCE = new InternalNotificationCategory(Type.PERFORMANCE);
+
+    /**
+     * A deprecation category.
+     * <p>
+     * For instance, the query/command use deprecated features that should be replaced.
+     */
+    NotificationCategory DEPRECATION = new InternalNotificationCategory(Type.DEPRECATION);
+
+    /**
+     * A generic category.
+     * <p>
+     * For instance, notifications that are not part of a more specific class.
+     */
+    NotificationCategory GENERIC = new InternalNotificationCategory(Type.GENERIC);
+}

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

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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;
+
+import java.io.Serializable;
+import java.util.Objects;
+import java.util.Set;
+import org.neo4j.driver.internal.InternalNotificationConfig;
+import org.neo4j.driver.internal.InternalNotificationSeverity;
+
+/**
+ * Notification configuration that defines what notifications the server may supply to the driver.
+ * <p>
+ * Please note that such configurations are only recognised by the server version 5.7 and above.
+ * @since 5.7
+ */
+public sealed interface NotificationConfig extends Serializable permits InternalNotificationConfig {
+    /**
+     * Returns a default notification config.
+     * <p>
+     * It has no options activated, meaning they the resulting behaviour depends on upstream entity. For instance,
+     * when this config is set on session level, the resulting behaviour depends on config set on driver level.
+     * Likewise, when this config is set on driver level, the resulting behaviour depends on the server.
+     * @return the default config
+     */
+    static NotificationConfig defaultConfig() {
+        return new InternalNotificationConfig(null, null);
+    }
+
+    /**
+     * A config that disables all notifications.
+     * @return the config that disables all notifications
+     */
+    static NotificationConfig disableAll() {
+        return new InternalNotificationConfig(InternalNotificationSeverity.OFF, null);
+    }
+
+    /**
+     * Returns a config that sets a minimum severity level for notifications.
+     *
+     * @param minimumSeverity the minimum severity level
+     * @return the config
+     */
+    static NotificationConfig enableMinimumSeverity(NotificationSeverity minimumSeverity) {
+        Objects.requireNonNull(minimumSeverity, "minimumSeverity must not be null");
+        return new InternalNotificationConfig(minimumSeverity, null);
+    }
+
+    /**
+     * Returns a config that disables a set of notification categories.
+     *
+     * @param disabledCategories the categories to disable, an empty set means no categories are disabled
+     * @return the config
+     */
+    static NotificationConfig disableCategories(Set<NotificationCategory> disabledCategories) {
+        Objects.requireNonNull(disabledCategories, "disabledCategories must not be null");
+        return new InternalNotificationConfig(null, Set.copyOf(disabledCategories));
+    }
+
+    /**
+     * Returns a config that sets a minimum severity level for notifications and also disables a set of notification categories.
+     *
+     * @param minimumSeverity the minimum severity level
+     * @param disabledCategories the categories to disable, an empty set means no categories are disabled
+     * @return the config
+     */
+    static NotificationConfig enableMinimumSeverityAndDisableCategories(
+            NotificationSeverity minimumSeverity, Set<NotificationCategory> disabledCategories) {
+        Objects.requireNonNull(minimumSeverity, "minimumSeverity must not be null");
+        Objects.requireNonNull(disabledCategories, "disabledCategories must not be null");
+        return new InternalNotificationConfig(minimumSeverity, Set.copyOf(disabledCategories));
+    }
+}

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

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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;
+
+import static org.neo4j.driver.internal.InternalNotificationSeverity.Type;
+
+import java.io.Serializable;
+import org.neo4j.driver.internal.InternalNotificationSeverity;
+
+/**
+ * A notification severity level.
+ * @since 5.7
+ */
+public sealed interface NotificationSeverity extends Serializable, Comparable<NotificationSeverity>
+        permits InternalNotificationSeverity {
+    /**
+     * An information severity level.
+     */
+    NotificationSeverity INFORMATION = new InternalNotificationSeverity(Type.INFORMATION, 800);
+    /**
+     * A warning severity level.
+     */
+    NotificationSeverity WARNING = new InternalNotificationSeverity(Type.WARNING, 900);
+}

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

@@ -65,6 +65,10 @@ public final class SessionConfig implements Serializable {
      * The bookmark manager.
      */
     private final BookmarkManager bookmarkManager;
+    /**
+     * The notification config.
+     */
+    private final NotificationConfig notificationConfig;
 
     private SessionConfig(Builder builder) {
         this.bookmarks = builder.bookmarks;
@@ -73,6 +77,7 @@ private SessionConfig(Builder builder) {
         this.fetchSize = builder.fetchSize;
         this.impersonatedUser = builder.impersonatedUser;
         this.bookmarkManager = builder.bookmarkManager;
+        this.notificationConfig = builder.notificationConfig;
     }
 
     /**
@@ -161,6 +166,15 @@ public Optional<BookmarkManager> bookmarkManager() {
         return Optional.ofNullable(bookmarkManager);
     }
 
+    /**
+     * Returns notification config.
+     * @return the notification config
+     * @since 5.7
+     */
+    public NotificationConfig notificationConfig() {
+        return notificationConfig;
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) {
@@ -175,7 +189,8 @@ public boolean equals(Object o) {
                 && Objects.equals(database, that.database)
                 && Objects.equals(fetchSize, that.fetchSize)
                 && Objects.equals(impersonatedUser, that.impersonatedUser)
-                && Objects.equals(bookmarkManager, that.bookmarkManager);
+                && Objects.equals(bookmarkManager, that.bookmarkManager)
+                && Objects.equals(notificationConfig, that.notificationConfig);
     }
 
     @Override
@@ -203,6 +218,7 @@ public static final class Builder {
         private String database = null;
         private String impersonatedUser = null;
         private BookmarkManager bookmarkManager;
+        private NotificationConfig notificationConfig = NotificationConfig.defaultConfig();
 
         private Builder() {}
 
@@ -366,6 +382,17 @@ public Builder withBookmarkManager(BookmarkManager bookmarkManager) {
             return this;
         }
 
+        /**
+         * Sets notification config.
+         * @param notificationConfig the notification config
+         * @return this builder
+         * @since 5.7
+         */
+        public Builder withNotificationConfig(NotificationConfig notificationConfig) {
+            this.notificationConfig = Objects.requireNonNull(notificationConfig, "notificationConfig must not be null");
+            return this;
+        }
+
         /**
          * Builds the {@link SessionConfig}.
          * @return the config

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

@@ -179,7 +179,13 @@ protected ChannelConnector createConnector(
             Clock clock,
             RoutingContext routingContext) {
         return new ChannelConnectorImpl(
-                settings, securityPlan, config.logging(), clock, routingContext, getDomainNameResolver());
+                settings,
+                securityPlan,
+                config.logging(),
+                clock,
+                routingContext,
+                getDomainNameResolver(),
+                config.notificationConfig());
     }
 
     private InternalDriver createDriver(