From 1389e6cd6c2ce6e92fa26dab1c6dc4b56107ef48 Mon Sep 17 00:00:00 2001 From: Nicolas Mervaillie Date: Tue, 3 Oct 2017 12:29:31 +0200 Subject: [PATCH] DATAGRAPH-1039 - Improve documentation. Fix broken links. Fix typos and add precisions on the contents of the conf properties file. --- README.adoc | 1 - src/main/asciidoc/migration.adoc | 6 +++--- src/main/asciidoc/preface.adoc | 9 ++++++++- .../asciidoc/reference/getting-started.adoc | 20 ++++++++++++++++--- .../reference/neo4j-repositories.adoc | 5 +++-- src/main/asciidoc/reference/projections.adoc | 2 +- 6 files changed, 32 insertions(+), 11 deletions(-) diff --git a/README.adoc b/README.adoc index 5742dd5d7..a22a0095f 100644 --- a/README.adoc +++ b/README.adoc @@ -110,7 +110,6 @@ Spring Data Neo4j will attempt to auto-configure itself using a file called `ogm [source,java] ---- -driver=org.neo4j.ogm.drivers.http.driver.HttpDriver URI=http://user:password@localhost:7474 ---- diff --git a/src/main/asciidoc/migration.adoc b/src/main/asciidoc/migration.adoc index 66d2c0b46..99b175b73 100644 --- a/src/main/asciidoc/migration.adoc +++ b/src/main/asciidoc/migration.adoc @@ -74,11 +74,11 @@ SDN provides automatic type conversion for the obvious candidates: byte[] and By BigInteger types. In order to define bespoke type conversions for particular entity attribute, you can annotate a field or method with `@Convert` to specify your own implementation of `org.neo4j.ogm.typeconversion.AttributeConverter`. -You can find out more about type conversions here: <> +You can find out more about type conversions here: <> [[migration.4-0.date-format]] === Date Format Changes -The default Date converter is <>. +The default Date converter is <>. SDN 3.x and earlier represented Dates as a String value consisting of the number of milliseconds since January 1, 1970, 00:00:00 GMT. @@ -124,7 +124,7 @@ Some features of the previous annotations have been dropped. Overriding @Property Types:: Support for overriding property types via arguments to @Property has been dropped. If your attribute requires -a non-default conversion to and from a database property, you can use a <> instead. +a non-default conversion to and from a database property, you can use a <> instead. @Relationship enforceTargetType:: In previous versions of Spring Data Neo4j, you would have to add an `enforceTargetType` attribute into every clashing diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index b6d37eb2f..0016354a2 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -17,7 +17,14 @@ It assumes the user is familiar with the Neo4j graph database as well as Spring [[preface.spring-data]] == Spring and Spring Data -Spring Data uses Spring framework's http://docs.spring.io/spring/docs/5.0.x/spring-framework-reference/html/spring-core.html[core] functionality, such as the http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/beans.html[IoC] container, http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/validation.html#core-convert[type conversion system], http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/expressions.html[expression language], http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/jmx.html[JMX integration], and portable http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/dao.html#dao-exceptions[DAO exception hierarchy]. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use. +Spring Data uses Spring framework's https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html[core] functionality, +such as the https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#beans[IoC] container, +https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#core-convert[type conversion system], +https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#expressions[expression language], +https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/integration.html#jmx[JMX integration], +and portable https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/data-access.html#dao-exceptions[DAO exception hierarchy]. +While it is not important to know the Spring APIs, understanding the concepts behind them is. +At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use. The core functionality of the Neo4J support can be used directly, with no need to invoke the IoC services of the Spring Container. This is much like Hibernate `Session` or JPA `EntityManager` which can be used 'standalone' without any other services of the Spring container. To leverage all the features of Spring Data Neo4j, such as the repository support, you will need to configure some parts of the library using Spring. diff --git a/src/main/asciidoc/reference/getting-started.adoc b/src/main/asciidoc/reference/getting-started.adoc index 98701933e..2755a36d3 100644 --- a/src/main/asciidoc/reference/getting-started.adoc +++ b/src/main/asciidoc/reference/getting-started.adoc @@ -61,7 +61,8 @@ For more in depth configuration details please consult the Configuration section By default, SDN will use the BOLT driver to connect to Neo4j and you don't need to declare it as a separate dependency in your pom. If you want to use the embedded or HTTP drivers in your production application, you must add the following dependencies as well. -(This dependency on the embedded driver is not required if you only want to use the embedded driver for testing. See the section on <> below for more information). +(This dependency on the embedded driver is not required if you only want to use the embedded driver for testing. +See the section on <> below for more information). @@ -172,7 +173,7 @@ public class MyConfiguration { @Bean public org.neo4j.ogm.config.Configuration configuration() { ConfigurationSource properties = new ClasspathConfigurationSource("ogm.properties"); - org.neo4j.ogm.config.Configuration configuration = new org.neo4j.ogm.config.Configuration.Builder(properties) + org.neo4j.ogm.config.Configuration configuration = new org.neo4j.ogm.config.Configuration.Builder(properties).build(); return configuration; } @@ -236,9 +237,22 @@ Configuration can also be initialized from an external file like this. @Bean public org.neo4j.ogm.config.Configuration configuration() { ConfigurationSource properties = new ClasspathConfigurationSource("db.properties"); - return new org.neo4j.ogm.config.Configuration.Builder(properties); + return new org.neo4j.ogm.config.Configuration.Builder(properties).build(); } ---- +where `db.properties` looks like +[source,properties] +---- +URI=bolt://localhost +username=user +password=secret +connection.pool.size=... #see java driver doc +encryption.level=... #see java driver doc +trust.strategy=... #see java driver doc +trust.certificate.file=... #see java driver doc +connection.liveness.check.timeout=... #see java driver doc +verify.connection=... #see java driver doc +---- //TODO add configuration option with native driver diff --git a/src/main/asciidoc/reference/neo4j-repositories.adoc b/src/main/asciidoc/reference/neo4j-repositories.adoc index a6dbfc2cb..7d9dcdd2c 100644 --- a/src/main/asciidoc/reference/neo4j-repositories.adoc +++ b/src/main/asciidoc/reference/neo4j-repositories.adoc @@ -466,7 +466,7 @@ determines the actual one used. It is highly recommended that users understand how Spring Transactions work. Below are some excellent resources: * https://docs.spring.io/spring/docs/current/spring-framework-reference/data-access.html#spring-data-tier[Spring Transaction Management] -* http://graphaware.com/neo4j/2016/09/30/upgrading-to-sdn-42.html[Upgrading to Spring Data Neo4j 4.2] +* https://graphaware.com/neo4j/2016/09/30/upgrading-to-sdn-42.html[Upgrading to Spring Data Neo4j 4.2] === Read only Transactions @@ -591,8 +591,9 @@ Spring Data Neo4J allows developers to use JSR-303 annotations like `@NotNull` e While this is provided it's not a best practice. It is highly recommended to create JSR-303 annotations on actual Java Beans, similar to things like Data Transfer Objects (DTOs). +[[reference_programming-model_conversion]] === Conversion Service -It is possible to have Spring Data Neo4j use converters registered with http://docs.spring.io/spring/docs/current/spring-framework-reference/html/validation.html#core-convert[Spring's ConversionService]. +It is possible to have Spring Data Neo4j use converters registered with http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/validation.html#core-convert[Spring's ConversionService]. In order to do this, provide `org.springframework.data.neo4j.conversion.MetaDataDrivenConversionService` as a Spring bean. .Provide MetaDataDrivenConversionService as a Spring bean diff --git a/src/main/asciidoc/reference/projections.adoc b/src/main/asciidoc/reference/projections.adoc index c8fa2fccd..11124dc01 100644 --- a/src/main/asciidoc/reference/projections.adoc +++ b/src/main/asciidoc/reference/projections.adoc @@ -105,7 +105,7 @@ This projection has the following details: ==== The backing domain model does not have these properties so we need to tell Spring Data from where they are obtained. -Virtual properties are the place where `@Value` comes into play. The `cinemaName` getter is annotated with `@Value` to use http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/expressions.html[SpEL expressions] pointing to the backing property `name`. You may have noticed `name` is prefixed with `target` which is the variable name pointing to the backing object. Using `@Value` on methods allows defining where and how the value is obtained. +Virtual properties are the place where `@Value` comes into play. The `cinemaName` getter is annotated with `@Value` to use https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#expressions[SpEL expressions] pointing to the backing property `name`. You may have noticed `name` is prefixed with `target` which is the variable name pointing to the backing object. Using `@Value` on methods allows defining where and how the value is obtained. `@Value` gives full access to the target object and its nested properties. SpEL expressions are extremely powerful as the definition is always applied to the projection method.