-
Notifications
You must be signed in to change notification settings - Fork 155
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Introduce notification configuration, severity and category (#1396)
* Introduce notification configuration, severity and category
Improve and expand the existing notification API.
A new `NotificationSeverity` type represents a notification severity level.
It includes 2 public constants:
- `INFORMATION`
- `WARNING`
A new `NotificationCategory` type represents a notification category.
It includes 6 public constants:
- `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 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, an empty `Optional` may be returned when driver communicates with a server version that does not supply these values.
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.defaultConfig().enableMinimumSeverity(NotificationSeverity.WARNING).disableCategories(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.
* Throw exception when notification configuration is not supported
This update introduces a new `UnsupportedFeatureException`. An instance of this exception will be emitted if a custom `NotificationConfig` is used and the driver comes across a Bolt connection that does not support the notification configuration.- Loading branch information
1 parent
e2962b8
commit a3912a5
Showing
81 changed files
with
2,423 additions
and
266 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
73 changes: 73 additions & 0 deletions
73
driver/src/main/java/org/neo4j/driver/NotificationCategory.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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; | ||
|
|
||
| /** | ||
| * 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); | ||
| } |
81 changes: 81 additions & 0 deletions
81
driver/src/main/java/org/neo4j/driver/NotificationConfig.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| /* | ||
| * 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.Set; | ||
| import org.neo4j.driver.internal.InternalNotificationConfig; | ||
| import org.neo4j.driver.internal.InternalNotificationSeverity; | ||
| import org.neo4j.driver.summary.ResultSummary; | ||
|
|
||
| /** | ||
| * A notification configuration defining what notifications should be supplied by the server. | ||
| * <p> | ||
| * There are currently 2 optional settings that may be activated: | ||
| * <ul> | ||
| * <li>Minimum notification severity - sets a baseline severity for notifications, similar to the logging levels.</li> | ||
| * <li>A set of disabled notification categories - explicitly disables a set of notification categories.</li> | ||
| * </ul> | ||
| * <p> | ||
| * By default, both options are not activated. | ||
| * | ||
| * @since 5.7 | ||
| * @see ResultSummary#notifications() | ||
| * @see org.neo4j.driver.summary.Notification | ||
| */ | ||
| public sealed interface NotificationConfig extends Serializable permits InternalNotificationConfig { | ||
| /** | ||
| * Returns a default notification configuration. | ||
| * <p> | ||
| * The default configuration has no settings activated, meaning the resulting behaviour depends on an upstream | ||
| * context. For instance, when this config is set on the session level, the resulting behaviour depends on the | ||
| * driver's config. Likewise, when this config is set on the 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 disableAllConfig() { | ||
| 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 | ||
| */ | ||
| NotificationConfig enableMinimumSeverity(NotificationSeverity minimumSeverity); | ||
|
|
||
| /** | ||
| * 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 | ||
| */ | ||
| NotificationConfig disableCategories(Set<NotificationCategory> disabledCategories); | ||
| } |
41 changes: 41 additions & 0 deletions
41
driver/src/main/java/org/neo4j/driver/NotificationSeverity.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| /* | ||
| * 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; | ||
|
|
||
| /** | ||
| * 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); | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.