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”.

Maven Coordinates

To enable Neo4j add the following dependency to your project’s pom.xml (see Managing Dependencies).

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

Check Neo4j Metrics Propagation and Neo4j Health Checks 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 microprofile-config.properties file and Neo4j driver will be configured by Helidon and can be injected using CDI.

To implement Neo4j, you must first provide the connection properties as shown below:

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

Then just inject the driver:

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

The driver can be used according to the Neo4j documentation.

Configuration

MicroProfile configuration options:

keytypedefault valuedescription
mp.jwt.verify.publickeystring The property allows the Public Verification Key text itself to be supplied as a string.
authentication.usernamestring Neo4j authentication user name
authentication.passwordstring Neo4j authentication password
authentication.enabledbooleanTRUEIf Neo4j authentication is enabled
encryptedbooleanFALSEIf Neo4j encryption is enabled
pool.metricsEnabledbooleanFALSEIf Neo4J metrics is enabled
pool.logLeakedSessionsboolean Log leaking sessions
pool.maxConnectionPoolSizestring Maximum connection pool size
pool.idleTimeBeforeConnectionTeststring Idle time before connection test
pool.maxConnectionLifetimestring Connection lifetime in seconds
pool.connectionAcquisitionTimeoutstring Connection Acquisition Timeout
trustsettings.trustStrategystring Trust Strategy: Trust All certificates, TRUST_ALL_CERTIFICATES, Trust custom certificates - TRUST_CUSTOM_CA_SIGNED_CERTIFICATES, Trust system CA - TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
trustsettings.certificatestring Path to trusted certificate
trustsettings.hostnameVerificationEnabledstringFALSEIf hostname verification is enabled.

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

docker run --publish=7474:7474 --publish=7687:7687 -e 'NEO4J_AUTH=neo4j/secret'  neo4j:latest
Copied

Go to the Neo4j browser and play the first step of the movies graph: :play movies

Now go to the pom.xml and add the following dependencies:

 <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>
Copied

Next add the connection configuration properties for Neo4j:

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

# Enable the optional MicroProfile Metrics REST.request metrics
metrics.rest-request.enabled=true
Copied

This includes both connection information and enables Neo4j metrics propagation.

Finally, we are able to inject and use the Neo4j driver.

@ApplicationScoped
public class MovieRepository {

    private final Driver driver;

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

    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;
            }));
        }
    }
}
Copied
  • Neo4j driver constructor injection
  • Use of Neo4j driver to extract all Movies

Movies can now be returned as JSON objects:

@GET
@Produces(MediaType.APPLICATION_JSON)
public List<Movie> getAllMovies() {
    return movieRepository.findAll();
}
Copied

Now build and run with JDK17+

mvn package
java -jar target/helidon-examples-integration-neo4j-mp.jar
Copied

Exercise the application:

curl -X GET http://localhost:8080/movies
{. . .}

# Try health and metrics

curl -s -X GET http://localhost:8080/health
{"outcome":"UP",...
. . .

# Prometheus Format
curl -s -X GET http://localhost:8080/metrics
# TYPE base:gc_g1_young_generation_count gauge
. . .

# JSON Format
curl -H 'Accept: application/json' -X GET http://localhost:8080/metrics
{"base":...
. . .
Copied

Full example code is available in Helidon GitHub Repository.

Additional Information

Neo4j Metrics Propagation

Neo4j metrics can be propagated to the user as MicroProfile metrics. This is implemented in a separate Maven module. Just add

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

Works with Neo4j Integration main dependency described in Maven Coordinates.

To enable metrics in Neo4j, add the following property to microprofile-config.properties:

neo4j.pool.metricsEnabled=true
Copied

By applying these two actions, Neo4j metrics will be automatically added to the output of the /metrics endpoint.

Neo4j Health Checks

If your application is highly dependent on the 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:

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

Works with Neo4j Integration main dependency described in Maven Coordinates.

Health checks for Neo4j will be included in /health endpoint output.

References