Идея поэкспериментировать с интеграцией 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 опенсорсный продукт, мы приглашаем вас в него контрибьютить!
