Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce notification configuration, severity and category #1396

Merged
merged 2 commits into from
Mar 29, 2023

Conversation

injectives
Copy link
Contributor

@injectives injectives commented Mar 24, 2023

Objective

Improve and expand the existing notification API.

NotificationSeverity

A new NotificationSeverity type represents a notification severity level.

It includes 2 public constants:

  • INFORMATION
  • WARNING

NotificationCategory

A new NotificationCategory type represents a notification category.

It includes 6 public constants:

  • HINT
  • UNRECOGNIZED
  • UNSUPPORTED
  • PERFORMANCE
  • DEPRECATION
  • GENERIC

Notification

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.

NotificationConfig

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:

// 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();

Bolt

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.

@injectives injectives marked this pull request as draft March 24, 2023 14:17
@injectives injectives force-pushed the feature/notifications branch 11 times, most recently from 064c3c5 to e4343ba Compare March 27, 2023 23:28
@injectives injectives changed the title Feature/notifications Introduce notification configuration, severity and category Mar 27, 2023
@injectives injectives force-pushed the feature/notifications branch 8 times, most recently from 43630ea to d0d778e Compare March 28, 2023 00:12
@injectives injectives marked this pull request as ready for review March 28, 2023 09:18
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.
@injectives injectives force-pushed the feature/notifications branch 4 times, most recently from a1d61cc to 4f7519e Compare March 28, 2023 20:13
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.
Copy link
Contributor

@bigmontz bigmontz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔔

@injectives injectives merged commit a3912a5 into neo4j:5.0 Mar 29, 2023
@injectives injectives deleted the feature/notifications branch March 29, 2023 10:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants