Идея поэкспериментировать с интеграцией Neo4j с Helidon возникла вполне естественно.

Neo4j — графовая система управления базами данных с открытым исходным кодом, реализованная на Java. По состоянию на 2015 год считается самой распространённой графовой СУБД. (Википедия, 21.10.2021)

Neo4j написана на Java и доступна из ПО, написанного на других языках с использованием языка запросов Cypher, через HTTP endpoint или через протокол «bolt». Neo4j в настоящее время является стандартом де-факто для графовых баз данных, используемых во многих отраслях.

Вообще, в се началось с небольшого разговора с Michael Simonis, одним из авторов Spring Data Neo4j 6 и сопровождающим Neo4j-OGM. Мы спросили Михаеля, что он думает о том, как Helidon и Neo4J могут работать вместе. Менее чем через час Михаель прислал мне ссылку на этот репозиторий с полнофункциональным примером для Helidon MP и Neo4j SDN.

Когда я начал читать код, я увидел странную зависимость в файле pom.xml:

<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-neo4j</artifactId>
</dependency>

Spring? Да ладна! Почему в нашем проекте есть Spring?

Но продолжая изучать код, я был весьма удивлен, увидев расширение CDI 2.0, обрабатывающее инициализацию и подготовку драйвера. Это расширение CDI запустилось без проблем в Helidon, поскольку он полностью поддерживает контейнер CDI - шикарно! Я снова почувствовал красоту и силу стандартов.

На следующий день Михаель прислал мне другое репо. На этот раз он включил свои идеи о том, как использовать Neo4j с Helidon SE. Интеграция тоже получилась очень простой. Было легко использовать Helidon Config для переноса всей конфигурации Neo4j в единую конфигурацию. А поскольку драйвер Neo4j полностью поддерживает native image, все можно скомпилировать в native-image исполняемый файл без каких-либо дополнительных действий с точки зрения программиста.

Это породило дискуссии между командами Helidon и Neo4j о том, какой вид интеграции более подходит для Helidon. В результате мы создали официальную интеграцию!

После некоторых консультаций с представителем Neo4j и моим хорошим другом Михаелем Симонисом мы пришли к выводу, что нам нужно только прдоставлять инициализированный драйвер пользователям Helidon. Метрики и Health Checks из Neo4j должны быть проброшены в метрики Helidon / MicroProfile и должны предоставляться как отдельные модули - отдельные зависимости Maven.

Итак, как же нам написать интеграцию Neo4j с Helidon? существуют две разновидности Helidon - MP и SE. SE представляет собой набор реактивных API, реализованных на чистой Java. Абсолютно никакой «магии» вроде рефлекшана или других хитростей. Helidon MP, по сути, оборачивает SE и приводит его к стандартам MicroProfile. Это означает, что рекомендуется сначала реализовать интеграцию с Neo4j для Helidon SE, а затем обернуть ее как расширения CDI для Helidon MP.

Давайте сделаем это!

Дисклеймер: в этой статье я продемонстрирую только основные фрагменты кода. Поскольку Helidon опенсорс проект под лицензией Apache 2.0, полный код доступен в официальном репозитории Helidon.

В Helidon мы обычно создаем так называемый support объект для реализации интеграции. Этот объект содержит всю информацию о конфигурации и инициализации. Мы следуем Builder pattern для чтения из конфигурации. Это означает, что мы создаем внутренний объект Builder, который должен читать все данные из конфигурации:

public Builder config(Config config) {
   config.get("authentication.username").asString().ifPresent(this::username);
   config.get("authentication.password").asString().ifPresent(this::password);
   config.get("authentication.enabled").asBoolean().ifPresent(this::authenticationEnabled);
   config.get("uri").asString().ifPresent(this::uri);
   config.get("encrypted").asBoolean().ifPresent(this::encrypted);
   //pool
   config.get("pool.metricsEnabled").asBoolean().ifPresent(this::metricsEnabled);
   config.get("pool.logLeakedSessions").asBoolean().ifPresent(this::logLeakedSessions);
   config.get("pool.maxConnectionPoolSize").asInt().ifPresent(this::maxConnectionPoolSize);
   config.get("pool.idleTimeBeforeConnectionTest").as(Duration.class).ifPresent(this::idleTimeBeforeConnectionTest);
   config.get("pool.maxConnectionLifetime").as(Duration.class).ifPresent(this::maxConnectionLifetime);
   config.get("pool.connectionAcquisitionTimeout").as(Duration.class).ifPresent(this::connectionAcquisitionTimeout);
   //trust   
   config.get("trustsettings.trustStrategy").asString().map(TrustStrategy::valueOf).ifPresent(this::trustStrategy);
   config.get("trustsettings.certificate").as(Path.class).ifPresent(this::certificate);
   config.get("trustsettings.hostnameVerificationEnabled").asBoolean().ifPresent(this::hostnameVerificationEnabled);
   return this;
}

Вы можете увидеть строки с ключами, они фактически взяты из файла конфигурации. причем, либо из конфигурации SE, либо из конфигурации MicroProfile. Каждый элемент настраивается следуя шаблону Builder:

...
public Builder password(String password) {
   Objects.requireNonNull(password);
   this.password = password;
   return this;
}
...

Когда все поля установлены, мы можем сбилдить support объект:

@Override
public Neo4j build() {
   if (driver == null) {
       driver = initDriver();
   }
   return new Neo4j(this);
}

Таким образом мы гарантируем, что все значения не будут нулевыми. Фактическая инициализация драйвера довольно проста (некоторые методы опущены):

private Driver initDriver() {
   AuthToken authToken = AuthTokens.none();
   if (authenticationEnabled) {
       authToken = AuthTokens.basic(username, password);
   }
   org.neo4j.driver.Config.ConfigBuilder configBuilder = createBaseConfig();
   configureSsl(configBuilder);
   configurePoolSettings(configBuilder);
   return GraphDatabase.driver(uri, authToken, configBuilder.build());
}

Support объект далее просто возвращает драйвер:

public Driver driver() {
   return driver;
}

... и его можно использовать:

Neo4jMetricsSupport.builder()
       .driver(neo4j.driver())
       .build()
       .initialize();
Driver neo4jDriver = neo4j.driver();

Helidon позаботится о его инициализации из файла application.yaml:

neo4j:
 uri: bolt://localhost:7687
 authentication:
   username: neo4j
   password: secret
 pool:
   metricsEnabled: true

Собственно все - можно использовать уже в своем коде:

public List<Movie> findAll(){
   try (var session = driver.session()) {
       var query = ""
               + "match (m:Movie) "
               + "match (m) <- [:DIRECTED] - (d:Person) "
               + "match (m) <- [r:ACTED_IN] - (a:Person) "
               + "return m, collect(d) as directors, collect({name:a.name, roles: r.roles}) as actors";
       return session.readTransaction(tx -> tx.run(query).list(r -> {
           var movieNode = r.get("m").asNode();
           var directors = r.get("directors").asList(v -> {
               var personNode = v.asNode();
               return new Person(personNode.get("born").asInt(), personNode.get("name").asString());
           });
           var actors = r.get("actors").asList(v -> {
               return new Actor(v.get("name").asString(), v.get("roles").asList(Value::asString));
           });
           var m = new Movie(movieNode.get("title").asString(), movieNode.get("tagline").asString());
           m.setReleased(movieNode.get("released").asInt());
           m.setDirectorss(directors);
           m.setActors(actors);
           return m;
       }));
   }
}

И вуаля! Helidon и Neo4j теперь могут работать вместе.

А как же MP?

Нам просто нужно обернуть нашу интеграцию в расширение CDI - это действительно довольно просто:

public class Neo4jCdiExtension implements Extension {
   private static final String NEO4J_METRIC_NAME_PREFIX = "neo4j";
   void afterBeanDiscovery(@Observes AfterBeanDiscovery addEvent) {
       addEvent.addBean()
               .types(Driver.class)
               .qualifiers(Default.Literal.INSTANCE, Any.Literal.INSTANCE)
               .scope(ApplicationScoped.class)
               .name(Driver.class.getName())
               .beanClass(Driver.class)
               .createWith(creationContext -> {
                   org.eclipse.microprofile.config.Config config = ConfigProvider.getConfig();
                   Config helidonConfig = MpConfig.toHelidonConfig(config).get(NEO4J_METRIC_NAME_PREFIX);

                   ConfigValue<Neo4j> configValue = helidonConfig.as(Neo4j::create);
                   if (configValue.isPresent()) {
                       return configValue.get().driver();
                   }
                   throw new Neo4jException("There is no Neo4j driver configured in configuration under key 'neo4j");
               });
   }
}

Как видите, мы можем прочитать конфигурацию с помощью функций SE:

Config helidonConfig = MpConfig.toHelidonConfig(config).get(NEO4J_METRIC_NAME_PREFIX);

Затем просто повторно используем наш support объект Neo4j SE:

ConfigValue<Neo4j> configValue = helidonConfig.as(Neo4j::create);

… и возвращаем драйвер:

return configValue.get().driver();

И тоже собственно все - просто инжектим драйвер:

@Inject
public MovieRepository(Driver driver) {
   this.driver = driver;
}

Конфигурация будет взята из файла microprofile-config.properties:

# Neo4j settings
neo4j.uri=bolt://localhost:7687
neo4j.authentication.username=neo4j
neo4j.authentication.password: secret
neo4j.pool.metricsEnabled: true

Далее можно использовать драйвер как в примере с SE.

Теперь и Helidon MP может работать с Neo4j!

Но это еще не все!

Метрики

Как я уже упоминал, для надлежащей работе в облаках нам также необходимо пробросить метрики и health checks из Neo4j.

Сделаем как и раньше - сначала для SE, а потом все обернем в MP.

Начнем с метрик! Сделаем отдельный модуль для метрик Neo4j.

Как и в Helidon SE, в support объекте Neo4j мы будем следовать шаблону Builder для настройки поддержки метрик. На самом деле нам нужен только драйвер Neo4j, так как мы можем все показатели получить из него:

public static class Builder implements io.helidon.common.Builder<Neo4jMetricsSupport> {
   private Driver driver;
   private Builder() {
   }
   public Neo4jMetricsSupport build() {
       Objects.requireNonNull(driver, "Must set driver before building");
       return new Neo4jMetricsSupport(this);
   }
   public Builder driver(Driver driver) {
       this.driver = driver;
       return this;
   }
}

Затем мы должны обернуть counter–ы и gauge–ы Neo4j:

private static class Neo4JCounterWrapper implements Counter {
   private final Supplier<Long> fn;
   private Neo4JCounterWrapper(Supplier<Long> fn) {
       this.fn = fn;
   }
   @Override
   public void inc() {
       throw new UnsupportedOperationException();
   }
   @Override
   public void inc(long n) {
       throw new UnsupportedOperationException();
   }
   @Override
   public long getCount() {
       return fn.get();
   }
}

private static class Neo4JGaugeWrapper<T> implements Gauge<T> {
   private final Supplier<T> supplier;
   private Neo4JGaugeWrapper(Supplier<T> supplier) {
       this.supplier = supplier;
   }
   @Override
   public T getValue() {
       return supplier.get();
   }
}

Далее нужно зарегистрировать эти счетчики в MetricsRegistry:

private void registerCounter(MetricRegistry metricRegistry,
                            ConnectionPoolMetrics cpm,
                            String poolPrefix,
                            String name,
                            Function<ConnectionPoolMetrics, Long> fn) {
   String counterName = poolPrefix + name;
   if (metricRegistry.getCounters().get(new MetricID(counterName)) == null) {
       Metadata metadata = Metadata.builder()
               .withName(counterName)
               .withType(MetricType.COUNTER)
               .notReusable()
               .build();
       Neo4JCounterWrapper wrapper = new Neo4JCounterWrapper(() -> fn.apply(cpm));
       metricRegistry.register(metadata, wrapper);
   }
}
private void registerGauge(MetricRegistry metricRegistry,
                          ConnectionPoolMetrics cpm,
                          String poolPrefix,
                          String name,
                          Function<ConnectionPoolMetrics, Integer> fn) {
   String gaugeName = poolPrefix + name;
   if (metricRegistry.getGauges().get(new MetricID(gaugeName)) == null) {
       Metadata metadata = Metadata.builder()
               .withName(poolPrefix + name)
               .withType(MetricType.GAUGE)
               .notReusable()
               .build();
       Neo4JGaugeWrapper<Integer> wrapper =
               new Neo4JGaugeWrapper<>(() -> fn.apply(cpm));
       metricRegistry.register(metadata, wrapper);
   }
}

И мы практически готовы:

private void reinit() {
   Map<String, Function<ConnectionPoolMetrics, Long>> counters = Map.ofEntries(
           entry("acquired", ConnectionPoolMetrics::acquired),
           entry("closed", ConnectionPoolMetrics::closed),
           entry("created", ConnectionPoolMetrics::created),
           entry("failedToCreate", ConnectionPoolMetrics::failedToCreate),
           entry("timedOutToAcquire", ConnectionPoolMetrics::timedOutToAcquire),
           entry("totalAcquisitionTime", ConnectionPoolMetrics::totalAcquisitionTime),
           entry("totalConnectionTime", ConnectionPoolMetrics::totalConnectionTime),
           entry("totalInUseCount", ConnectionPoolMetrics::totalInUseCount),
           entry("totalInUseTime", ConnectionPoolMetrics::totalInUseTime));

   Map<String, Function<ConnectionPoolMetrics, Integer>> gauges = Map.ofEntries(
           entry("acquiring", ConnectionPoolMetrics::acquiring),
           entry("creating", ConnectionPoolMetrics::creating),
           entry("idle", ConnectionPoolMetrics::idle),
           entry("inUse", ConnectionPoolMetrics::inUse)
   );
   for (ConnectionPoolMetrics it : lastPoolMetrics.get()) {
       String poolPrefix = NEO4J_METRIC_NAME_PREFIX + "-";
       counters.forEach((name, supplier) -> registerCounter(metricRegistry.get(), it, poolPrefix, name, supplier));
       gauges.forEach((name, supplier) -> registerGauge(metricRegistry.get(), it, poolPrefix, name, supplier));
       // we only care about the first one
       metricsInitialized.set(true);
       break;
   }
}

Всегда полезно обновлять вовремя метрики, и для этого у нас есть функция:

private void refreshMetrics(ScheduledExecutorService executor) {
   Collection<ConnectionPoolMetrics> currentPoolMetrics = driver.metrics().connectionPoolMetrics();
   if (!metricsInitialized.get() && currentPoolMetrics.size() >= 1) {
       lastPoolMetrics.set(currentPoolMetrics);
       reinit();
       if (metricsInitialized.get()) {
           reinitFuture.get().cancel(false);
           executor.shutdown();
       }
   }
}

Нам нужно только предоставить драйвер Neo4j для предоставления нам информации о метриках в нашем файле application.yaml:

neo4j:
 pool:
   metricsEnabled: true

… Или в нашем microprofile-config.properties :

neo4j.pool.metricsEnabled = true

Теперь, если вы пойдете по «/health», вы также получите показания от Neo4j.

Для MP, нам нужно только обернуть регистрацию метрик как расширение CDI. Событие это должно произойти после того, как драйвер уже инициализирован:

public class Neo4jMetricsCdiExtension implements Extension {
   private void addMetrics(@Observes @Priority(PLATFORM_AFTER + 101) @Initialized(ApplicationScoped.class) Object event) {
       Instance<Driver> driver = CDI.current().select(Driver.class);
       Neo4jMetricsSupport.builder()
               .driver(driver.get())
               .build()
               .initialize();
   }
}

Вот и все! Метрики Neo4j теперь доступны и в Helidon MP!

И теперь, последнее, но не менее важное, проверка работоспособности!

Health Checks

И опять же, это должен быть отдельный модуль, чтобы все было чисто и красиво.

На этот раз мы начнем с MP:

@Readiness
@ApplicationScoped
public class Neo4jHealthCheck implements HealthCheck {
   private static final String CYPHER = "RETURN 1 AS result";
   private static final SessionConfig DEFAULT_SESSION_CONFIG = SessionConfig.builder()
           .withDefaultAccessMode(AccessMode.WRITE)
           .build();
   private final Driver driver;
  
   @Inject
   //will be ignored outside of CDI
   Neo4jHealthCheck(Driver driver) {
       this.driver = driver;
   }
   public static Neo4jHealthCheck create(Driver driver) {
       return new Neo4jHealthCheck(driver);
   }
   private static HealthCheckResponse buildStatusUp(ResultSummary resultSummary, HealthCheckResponseBuilder builder) {
       ServerInfo serverInfo = resultSummary.server();
       builder.withData("server", serverInfo.version() + "@" + serverInfo.address());
       String databaseName = resultSummary.database().name();
       if (!(databaseName == null || databaseName.trim().isEmpty())) {
           builder.withData("database", databaseName.trim());
       }
       return builder.build();
   }
   @Override
   public HealthCheckResponse call() {
       HealthCheckResponseBuilder builder = HealthCheckResponse.named("Neo4j connection health check").up();
       try {
           ResultSummary resultSummary;
           // Retry one time when the session has been expired
           try {
               resultSummary = runHealthCheckQuery();
           } catch (SessionExpiredException sessionExpiredException) {
               resultSummary = runHealthCheckQuery();
           }
           return buildStatusUp(resultSummary, builder);
       } catch (Exception e) {
           return builder.down().withData("reason", e.getMessage()).build();
       }
   }
   private ResultSummary runHealthCheckQuery() {
       // We use WRITE here to make sure UP is returned for a server that supports
       // all possible workloads
       if (driver != null) {
           Session session = this.driver.session(DEFAULT_SESSION_CONFIG);
           Result run = session.run(CYPHER);
           return run.consume();
       }
       return null;
   }
}

Технически для health check-a, мы выполняем простой запрос на Cypher, и если он работает, значит, Neo4j жив, этого достаточно!

Нам нужно только добавить Maven зависимость в наш проект:

<dependency>
   <groupId>io.helidon.integrations.neo4j</groupId>
   <artifactId>helidon-integrations-neo4j-health</artifactId>
</dependency>

И снова - Вуаля, все работает!

Что касается SE, поскольку это чистая Java, нам просто нужно все инициализировать:

Neo4j neo4j = Neo4j.create(config.get("neo4j"));
Neo4jHealthCheck healthCheck = Neo4jHealthCheck.create(neo4j.driver());
Driver neo4jDriver = neo4j.driver();
HealthSupport health = HealthSupport.builder()
     .addLiveness(HealthChecks.healthChecks())   // Adds a convenient set of checks
     .addReadiness(healthCheck)
     .build();

return Routing.builder()
        .register(health)                   // Health at "/health"
        //other services
        .build();
}

Теперь наше Helidon приложение, как MP, так и SE, может работать с Neo4j, читать его метрики и выполнять health checks.

Кстати, поскольку драйвер Neo4j полностью поддерживает GraalVM native-image, приложения на Helidon MP или SE могут быть в него скомпилированы!

В этой статье было продемонстрировано, как создать интеграцию разных технологий с Helidon. Что касается Neo4j, мы уже официально сделали это за вас!

Просто нужно включить в свои Maven проект следующие зависимости:

<dependency>
   <groupId>io.helidon.integrations.neo4j</groupId>
   <artifactId>helidon-integrations-neo4j</artifactId>
</dependency>
<dependency>
   <groupId>io.helidon.integrations.neo4j</groupId>
   <artifactId>helidon-integrations-neo4j-metrics</artifactId>
</dependency>
<dependency>
   <groupId>io.helidon.integrations.neo4j</groupId>
   <artifactId>helidon-integrations-neo4j-health</artifactId>
</dependency>

… И это все, что вам нужно для начала работы с Helidon и Neo4j!

Заключение

Как видите, интеграция с Helidon довольно проста. Стандартный способ сделать это - сначала написать supportобъект Helidon SE, следуя шаблону Builder для его инициализации, а затем просто обернуть его в CDI расширение, чтобы MicroProfile мог воспользоваться этой "магией"!

Вы можете поиграть с примерами Helidon ин Neo4j в нашем официальном репозитории интеграции Helidon Neo4j .

Что касается Neo4j, вас также может заинтересовать CypherDsl и пример с ним.

Следующие шаги

В этой статье я хотел показать вам не только, как Neo4j работает с Helidon, но и как вы можете писать свои собственные расширения. Поскольку Helidon опенсорсный продукт, мы приглашаем вас в него контрибьютить!

Как мы Neo4j к Helidon прикручивали