se.integrations.neo4j.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2022, 2024 Oracle and/or its affiliates.
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.
///////////////////////////////////////////////////////////////////////////////
= Neo4j
:description: Neo4j integration
:keywords: neo4j
:feature-name: Neo4j
:rootdir: {docdir}/../..
include::{rootdir}/includes/se.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
- <>
- <>
== Overview
Neo4j is a graph database management system developed by Neo4j, Inc. It is an ACID-compliant transactional database with native graph storage and processing. Neo4j is available in a GPL3-licensed open-source “community edition”.
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
io.helidon.integrations.neo4j
helidon-integrations-neo4j
----
NOTE: Check <> and <> for additional dependencies for _Neo4j_ `Metrics` and `Health Checks` integration.
== Usage
The support for Neo4j is implemented in Neo4j driver level. Just add the dependency, add configuration in `application.yaml` file and Neo4j driver will be configured by Helidon and can be used with `Neo4j` support object.
First describe Neo4j connection properties:
[source,yaml]
----
neo4j:
uri: bolt://localhost:7687
authentication:
username: neo4j
password: secret
pool:
metricsEnabled: true
----
Then just get the driver:
[source,java]
----
include::{sourcedir}/se/integrations/Neo4jSnippets.java[tag=snippet_1, indent=0]
----
The driver can be used according to the link:https://neo4j.com/developer/java/[Neo4j documentation].
== Configuration
include::{rootdir}/config/io_helidon_integrations_neo4j_Neo4j.adoc[leveloffset=+1,tag=config]
== Examples
This example implements a simple Neo4j REST service using MicroProfile. For this example a working Neo4j database is required. The Neo4j Movie database is used for this example.
Bring up a Neo4j instance via Docker
[source, bash]
----
docker run --publish=7474:7474 --publish=7687:7687 -e 'NEO4J_AUTH=neo4j/secret' neo4j:latest
----
Go to the Neo4j browser and play the first step of the movies graph: link:http://localhost:7474/browser/?cmd=play&arg=movies[`:play movies`]
Now go to the `pom.xml` and add the following dependencies:
[source,xml]
----
io.helidon.integrations.neo4j
helidon-integrations-neo4j
io.helidon.integrations.neo4j
helidon-integrations-neo4j-metrics
io.helidon.integrations.neo4j
helidon-integrations-neo4j-health
----
Next add the connection configuration properties for Neo4j:
[source,yaml]
----
neo4j:
uri: bolt://localhost:7687
authentication:
username: neo4j
password: secret
pool:
metricsEnabled: true
----
This includes both connection information and enables Neo4j metrics propagation.
Finally, we are able to use the `Neo4j` driver.
[source,java]
----
include::{sourcedir}/se/integrations/Neo4jSnippets.java[tag=snippet_2, indent=0]
----
<1> Constructor with `Neo4j` driver parameter
<2> Use `Neo4j` driver to extract all Movies
Movies can now be returned as JSON objects:
[source,java]
----
include::{sourcedir}/se/integrations/Neo4jSnippets.java[tag=snippet_3, indent=0]
----
To use the service, as well as to add metrics and health support the following routing should be created:
[source,java]
----
include::{sourcedir}/se/integrations/Neo4jSnippets.java[tag=snippet_4, indent=0]
----
<1> Use of `Neo4j` support object to initialise and configure the driver.
<2> Use of `Neo4jMetricsSupport` to add _Neo4j_ metrics to `/metrics` output.
<3> Use of `Neo4jHealthCheck` to add _Neo4j_ health support.
<4> Register `MovieService` in _Routing_.
Now build and run.
[source,bash]
----
mvn package
java -jar target/helidon-examples-integration-neo4j.jar
----
Exercise the application:
[source,bash]
----
curl -X GET http://localhost:8080/movies
# Try health
curl -s -X GET http://localhost:8080/health
# Try metrics in Prometheus Format
curl -s -X GET http://localhost:8080/metrics
# Try metrics in JSON Format
curl -H 'Accept: application/json' -X GET http://localhost:8080/metrics
----
Full example code is available in link:{helidon-github-examples-url}/integrations/neo4j[Helidon Examples Repository].
== Additional Information
=== Neo4j Metrics propagation
Neo4j's metrics can be propagated to the user as `MicroProfile` metrics. This is implemented in a separate Maven module. Just add:
[source,xml]
----
io.helidon.integrations.neo4j
helidon-integrations-neo4j-metrics
----
NOTE: Works with _Neo4j Integration_ main dependency described in <>.
To enable metrics in Neo4j, add the following property to `application.yaml`:
[source,yaml]
----
pool:
metricsEnabled: true
----
Finally, to initialize metrics run:
[source,java]
----
include::{sourcedir}/se/integrations/Neo4jSnippets.java[tag=snippet_5, indent=0]
----
Neo4j's metrics will be automatically added to the output of the `/metrics` endpoint.
=== Neo4j Health Checks
If your application is highly dependent on Neo4j database, health and liveness checks are essential for this application to work correctly.
`MicroProfile` Health checks for Neo4j are implemented in a separate Maven module:
[source, xml]
----
io.helidon.integrations.neo4j
helidon-integrations-neo4j-health
----
NOTE: Works with _Neo4j Integration_ main dependency described in <>.
To enable health checks run the following code:
[source,java]
----
include::{sourcedir}/se/integrations/Neo4jSnippets.java[tag=snippet_6, indent=0]
----
Health checks for Neo4j will be included in `/health` endpoint output.
== References
* link:https://neo4j.com/[Neo4j official website]
* link:https://neo4j.com/developer/java/[Neo4j Java developer guide]