Skip to content

Commit a59e059

Browse files
dalexandrovdalexandrov
authored
[New Doc PR] - 4299 Helidon Integrations documentation Neo4J (helidon-io#4598)
* Initial commit Neo4j documentation for Helidon MP * Neo4j docs added for Helidon SE * Apply Tim's comments * Apply Tim's comments. Part two. * Apply Tim's comments. Part two. * Minor render fix
1 parent 08a1f45 commit a59e059

4 files changed

Lines changed: 674 additions & 0 deletions

File tree

‎docs/config/io_helidon_integrations_neo4j.adoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
///////////////////////////////////////////////////////////////////////////////
2+
3+
Copyright (c) 2022 Oracle and/or its affiliates.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
17+
///////////////////////////////////////////////////////////////////////////////
18+
19+
// MANUALLY CREATED DOC
20+
21+
:description: Configuration of io_helidon_integrations_neo4j
22+
:keywords: helidon, config, io_helidon_integrations_neo4j.adoc
23+
:basic-table-intro: The table below lists the configuration keys that configure io_helidon_integrations_neo4j.adoc
24+
25+
= Neo4j Configuration
26+
27+
// tag::config[]
28+
29+
30+
MicroProfile configuration options:
31+
[cols="3,3,2,5"]
32+
33+
|===
34+
|key |type |default value |description
35+
36+
|`mp.jwt.verify.publickey` |string |{nbsp} |The property allows the Public Verification Key text itself to be supplied as a string.
37+
38+
39+
|`authentication.username`|string |{nbsp} | Neo4j authentication user name
40+
|`authentication.password`|string |{nbsp} | Neo4j authentication password
41+
|`authentication.enabled`|boolean |TRUE | If Neo4j authentication is enabled
42+
|`encrypted`|boolean |FALSE | If Neo4j encryption is enabled
43+
|`pool.metricsEnabled`|boolean |FALSE | If Neo4J metrics is enabled
44+
|`pool.logLeakedSessions`|boolean |{nbsp} | Log leaking sessions
45+
|`pool.maxConnectionPoolSize`|string |{nbsp} | Maximum connection pool size
46+
|`pool.idleTimeBeforeConnectionTest`|string |{nbsp} | Idle time before connection test
47+
|`pool.maxConnectionLifetime`|string |{nbsp} | Connection lifetime in seconds
48+
|`pool.connectionAcquisitionTimeout`|string |{nbsp} | Connection Acquisition Timeout
49+
|`trustsettings.trustStrategy`|string |{nbsp} | Trust Strategy: Trust All certificates, `TRUST_ALL_CERTIFICATES`, Trust custom certificates -
50+
`TRUST_CUSTOM_CA_SIGNED_CERTIFICATES`, Trust system CA - `TRUST_SYSTEM_CA_SIGNED_CERTIFICATES`
51+
|`trustsettings.certificate`|string |{nbsp} | Path to trusted certificate
52+
|`trustsettings.hostnameVerificationEnabled`|string |FALSE | If hostname verification is enabled.
53+
54+
55+
|===
56+
57+
// end::config[]

‎docs/mp/integrations/neo4j.adoc‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
///////////////////////////////////////////////////////////////////////////////
2+
3+
Copyright (c) 2022 Oracle and/or its affiliates.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
17+
///////////////////////////////////////////////////////////////////////////////
18+
19+
= Neo4j
20+
:description: Neo4j integration
21+
:keywords: neo4j
22+
:feature-name: Neo4j
23+
:rootdir: {docdir}/../..
24+
25+
include::{rootdir}/includes/mp.adoc[]
26+
27+
== Contents
28+
29+
- <<Overview, Overview>>
30+
- <<maven-coordinates, Maven Coordinates>>
31+
- <<Usage, Usage>>
32+
- <<Configuration, Configuration>>
33+
- <<Examples, Examples>>
34+
- <<Additional Information, Additional Information>>
35+
- <<References, References>>
36+
37+
== Overview
38+
39+
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”.
40+
41+
include::{rootdir}/includes/dependencies.adoc[]
42+
43+
[source,xml]
44+
----
45+
<dependency>
46+
<groupId>io.helidon.integrations.neo4j</groupId>
47+
<artifactId>helidon-integrations-neo4j</artifactId>
48+
</dependency>
49+
----
50+
NOTE: Check <<Neo4j Metrics propagation, Neo4j Metrics propagation>> and <<Neo4j Health Checks, Neo4j Health Checks>> for additional dependencies for _Neo4j_ `Metrics` and `Health Checks` integration.
51+
52+
== Usage
53+
54+
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.
55+
56+
First describe Neo4j connection properties:
57+
58+
[source,properties]
59+
----
60+
# Neo4j settings
61+
neo4j.uri=bolt://localhost:7687
62+
neo4j.authentication.username=neo4j
63+
neo4j.authentication.password: secret
64+
neo4j.pool.metricsEnabled: true
65+
----
66+
67+
Then just inject the driver:
68+
69+
[source,java]
70+
----
71+
@Inject
72+
public MovieRepository(Driver driver) {
73+
this.driver = driver;
74+
}
75+
----
76+
77+
The driver can be used according to the link:https://neo4j.com/developer/java/[Neo4j documentation].
78+
79+
== Configuration
80+
81+
include::{rootdir}/config/io_helidon_integrations_neo4j.adoc[leveloffset=+1,tag=config]
82+
83+
== Examples
84+
85+
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.
86+
87+
Bring up a Neo4j instance via Docker
88+
89+
```bash
90+
docker run --publish=7474:7474 --publish=7687:7687 -e 'NEO4J_AUTH=neo4j/secret' neo4j:latest
91+
```
92+
93+
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`]
94+
95+
Now go to the `pom.xml` and add the following dependencies:
96+
97+
[source,xml]
98+
----
99+
<dependency>
100+
<groupId>io.helidon.integrations.neo4j</groupId>
101+
<artifactId>helidon-integrations-neo4j</artifactId>
102+
</dependency>
103+
<dependency>
104+
<groupId>io.helidon.integrations.neo4j</groupId>
105+
<artifactId>helidon-integrations-neo4j-metrics</artifactId>
106+
</dependency>
107+
<dependency>
108+
<groupId>io.helidon.integrations.neo4j</groupId>
109+
<artifactId>helidon-integrations-neo4j-health</artifactId>
110+
</dependency>
111+
----
112+
113+
Next add the connection configuration properties for Neo4j:
114+
115+
[source,properties]
116+
----
117+
# Neo4j settings
118+
neo4j.uri=bolt://localhost:7687
119+
neo4j.authentication.username=neo4j
120+
neo4j.authentication.password: secret
121+
neo4j.pool.metricsEnabled: true
122+
123+
# Enable the optional MicroProfile Metrics REST.request metrics
124+
metrics.rest-request.enabled=true
125+
----
126+
127+
This includes both connection information and enables Neo4j metrics propagation.
128+
129+
Finally, we are able to inject and use the `Neo4j` driver.
130+
131+
[source,java]
132+
----
133+
@ApplicationScoped
134+
public class MovieRepository {
135+
136+
private final Driver driver;
137+
138+
@Inject
139+
public MovieRepository(Driver driver) { // <1>
140+
this.driver = driver;
141+
}
142+
143+
public List<Movie> findAll() { // <2>
144+
145+
try (var session = driver.session()) {
146+
147+
var query = ""
148+
+ "match (m:Movie) "
149+
+ "match (m) <- [:DIRECTED] - (d:Person) "
150+
+ "match (m) <- [r:ACTED_IN] - (a:Person) "
151+
+ "return m, collect(d) as directors, collect({name:a.name, roles: r.roles}) as actors";
152+
153+
return session.readTransaction(tx -> tx.run(query).list(r -> {
154+
var movieNode = r.get("m").asNode();
155+
156+
var directors = r.get("directors").asList(v -> {
157+
var personNode = v.asNode();
158+
return new Person(personNode.get("born").asInt(), personNode.get("name").asString());
159+
});
160+
161+
var actors = r.get("actors").asList(v -> {
162+
return new Actor(v.get("name").asString(), v.get("roles").asList(Value::asString));
163+
});
164+
165+
var m = new Movie(movieNode.get("title").asString(), movieNode.get("tagline").asString());
166+
m.setReleased(movieNode.get("released").asInt());
167+
m.setDirectorss(directors);
168+
m.setActors(actors);
169+
return m;
170+
}));
171+
}
172+
}
173+
}
174+
175+
----
176+
<1> `Neo4j` driver constructor injection
177+
<2> Use of `Neo4j` driver to extract all Movies
178+
179+
Movies can now be returned as JSON objects:
180+
181+
[source,java]
182+
----
183+
@GET
184+
@Produces(MediaType.APPLICATION_JSON)
185+
public List<Movie> getAllMovies() {
186+
return movieRepository.findAll();
187+
}
188+
----
189+
190+
Now build and run with JDK17+
191+
[source,bash]
192+
----
193+
mvn package
194+
java -jar target/helidon-examples-integration-neo4j-mp.jar
195+
----
196+
197+
Exercise the application:
198+
199+
[source,bash]
200+
----
201+
curl -X GET http://localhost:8080/movies
202+
{. . .}
203+
204+
# Try health and metrics
205+
206+
curl -s -X GET http://localhost:8080/health
207+
{"outcome":"UP",...
208+
. . .
209+
210+
# Prometheus Format
211+
curl -s -X GET http://localhost:8080/metrics
212+
# TYPE base:gc_g1_young_generation_count gauge
213+
. . .
214+
215+
# JSON Format
216+
curl -H 'Accept: application/json' -X GET http://localhost:8080/metrics
217+
{"base":...
218+
. . .
219+
220+
----
221+
222+
Full example code is available in link:https://github.com/oracle/helidon/tree/master/examples/integrations/neo4j/neo4j-mp[Helidon GitHub Repository].
223+
224+
225+
== Additional Information
226+
227+
=== Neo4j Metrics propagation
228+
229+
Neo4j metrics can be propagated to the user as `MicroProfile` metrics. This is implemented in a separate Maven module. Just add
230+
231+
[source,xml]
232+
----
233+
<dependency>
234+
<groupId>io.helidon.integrations.neo4j</groupId>
235+
<artifactId>helidon-integrations-neo4j-metrics</artifactId>
236+
</dependency>
237+
----
238+
239+
NOTE: Works with _Neo4j Integration_ main dependency described in <<maven-coordinates, Maven Coordinates>>.
240+
241+
To enable metrics in Neo4j, add the following property to `microprofile-config.properties`:
242+
243+
[source,properties]
244+
----
245+
neo4j.pool.metricsEnabled=true
246+
----
247+
248+
By applying these two actions, Neo4j metrics will be automatically added to the output of the `/metrics` endpoint.
249+
250+
=== Neo4j Health Checks
251+
252+
If your application is highly dependent on Neo4j database, health and liveness checks are essential for this application to work correctly.
253+
254+
`MicroProfile` Health checks for Neo4j are implemented in a separate Maven module:
255+
256+
[source, xml]
257+
----
258+
<dependency>
259+
<groupId>io.helidon.integrations.neo4j</groupId>
260+
<artifactId>helidon-integrations-neo4j-health</artifactId>
261+
</dependency>
262+
----
263+
NOTE: Works with _Neo4j Integration_ main dependency described in <<maven-coordinates, Maven Coordinates>>.
264+
265+
Health checks for Neo4j will be included in `/health` endpoint output.
266+
267+
== References
268+
269+
* link:https://neo4j.com/[Neo4j official website]
270+
* link:https://neo4j.com/developer/java/[Neo4j Java developer guide]
271+
272+

0 commit comments

Comments
 (0)