DATAGRAPH-1390 - Provide attribute specific conversions.

This introduces the idea of a `Neo4jPersistentPropertyConverter`, a `Neo4jPersistentPropertyConverterFactory` and an annotation `@ConvertWith`.

The annotation can be applied to fields and other annotations.
It is used to indicate that a given `Neo4jPersistentProperty` needs a custom conversion for reads and writes and overwrides all existing converters.

The annotation allows to specifiy the converter through `converter()` and an optional factory.
The default `Neo4jPersistentPropertyConverterFactory` will just try to instantiate the given converter class.
More sophisticated solutions need dedicated factories.

To make the factories work possible, the whole persistent property is passed as a construction parameter, so that the `@ConvertWith` annotation
or any other meta-annotated annotations can be retrieved.

In the progress of implementing this, the `Neo4jEntityConverter` has been stripped of its duties to convert single values.
Instead, a `Neo4jConversionService` has been introduced that orchestrates the underlying spring service and possible overrides.

The conversion will applied at all places where a persistent property can be deduced, either from the model or from parameters targeting the properties.
It will not be applied to parameters of string based queries or SpEL.

Author: michael-simons

etc/jqassistant/structure.adoc

@@ -21,8 +21,17 @@ RETURN p1,p2
 .The public support packages must not depend directly on the mapping package
 ----
 MATCH (a:Main:Artifact)
-MATCH (a) -[:CONTAINS]-> (p1:Package) -[:DEPENDS_ON]-> (p2:Package) <-[:CONTAINS]- (a)
-WHERE p1.fqn in ['org.springframework.data.neo4j.core.convert', 'org.springframework.data.neo4j.core.schema', 'org.springframework.data.neo4j.core.support', 'org.springframework.data.neo4j.core.transaction']
+MATCH (a) -[:CONTAINS]-> (p1:Package)
+WHERE p1.fqn in [
+        'org.springframework.data.neo4j.core.convert',
+        'org.springframework.data.neo4j.core.schema',
+        'org.springframework.data.neo4j.core.support',
+        'org.springframework.data.neo4j.core.transaction'
+      ]
+WITH p1, a
+MATCH (p1) - [:CONTAINS] -> (t:Type)
+MATCH (t) - [:DEPENDS_ON] -> (t2:Type) <- [:CONTAINS] - (p2:Package) <-[:CONTAINS]- (a)
+WHERE t2.fqn <> 'org.springframework.data.neo4j.core.mapping.Neo4jPersistentProperty'
   AND p2.fqn = 'org.springframework.data.neo4j.core.mapping'
-RETURN p1, p2
+RETURN t
 ----

src/main/asciidoc/appendix/conversions.adoc

@@ -177,6 +177,8 @@ If you require the time zone, use a type that supports it (i.e. `ZoneDateTime`)
 
 == Custom conversions
 
+=== For attributes of a given type
+
 If you prefer to work with your own types in the entities or as parameters for `@Query` annotated methods, you can define and provide a custom converter implementation.
 First you have to implement a `GenericConverter` and register the types your converter should handle.
 For entity property type converters you need to take care of converting your type to *and* from a Neo4j Java Driver `Value`.
@@ -199,3 +201,12 @@ include::../../../../src/test/java/org/springframework/data/neo4j/documentation/
 ----
 
 If you need multiple converters in your application, you can add as many as you need in the `Neo4jConversions` constructor.
+
+=== For specific attributes only
+
+If you need conversions only for some specific attributes, we provide `@ConvertWith`.
+This is an annotation that can be put on attributes carrying a `Neo4jPersistentPropertyConverter` on it's `converter` attribute
+and an optional `Neo4jPersistentPropertyConverterFactory` to construct the former.
+With an implementation of `Neo4jPersistentPropertyConverter` all specific conversions for a given type can be addressed.
+
+We provide `@DateLong` and `@DateString` as meta-annotated annotations for backward compatibility with Neo4j-OGM schemes not using native types.

src/main/java/org/springframework/data/neo4j/core/Neo4jTemplate.java

@@ -49,11 +49,11 @@
 import org.springframework.data.neo4j.core.mapping.NestedRelationshipContext;
 import org.springframework.data.neo4j.core.mapping.NestedRelationshipProcessingStateMachine;
 import org.springframework.data.neo4j.core.mapping.NestedRelationshipProcessingStateMachine.ProcessState;
+import org.springframework.data.neo4j.core.mapping.Constants;
+import org.springframework.data.neo4j.core.mapping.CypherGenerator;
 import org.springframework.data.neo4j.core.mapping.Neo4jMappingContext;
 import org.springframework.data.neo4j.core.mapping.Neo4jPersistentEntity;
 import org.springframework.data.neo4j.core.mapping.Neo4jPersistentProperty;
-import org.springframework.data.neo4j.core.mapping.Constants;
-import org.springframework.data.neo4j.core.mapping.CypherGenerator;
 import org.springframework.data.neo4j.core.mapping.NodeDescription;
 import org.springframework.data.neo4j.core.mapping.RelationshipDescription;
 import org.springframework.data.neo4j.core.mapping.CreateRelationshipStatementHolder;
@@ -187,31 +187,31 @@ public <T> Optional<T> findOne(String cypherQuery, Map<String, Object> parameter
 
 	@Override
 	public <T> Optional<T> findById(Object id, Class<T> domainType) {
-		Neo4jPersistentEntity entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
+		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
 		Statement statement = cypherGenerator
 				.prepareMatchOf(entityMetaData, entityMetaData.getIdExpression().isEqualTo(parameter(Constants.NAME_OF_ID)))
 				.returning(cypherGenerator.createReturnStatementForMatch(entityMetaData)).build();
 		return createExecutableQuery(domainType, statement, Collections
-				.singletonMap(Constants.NAME_OF_ID, convertIdValues(id)))
+				.singletonMap(Constants.NAME_OF_ID, convertIdValues(entityMetaData.getRequiredIdProperty(), id)))
 				.getSingleResult();
 	}
 
 	@Override
 	public <T> List<T> findAllById(Iterable<?> ids, Class<T> domainType) {
-		Neo4jPersistentEntity entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
+		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
 		Statement statement = cypherGenerator
 				.prepareMatchOf(entityMetaData, entityMetaData.getIdExpression().in((parameter(Constants.NAME_OF_IDS))))
 				.returning(cypherGenerator.createReturnStatementForMatch(entityMetaData)).build();
 
 		return createExecutableQuery(domainType, statement, Collections
-				.singletonMap(Constants.NAME_OF_IDS, convertIdValues(ids)))
+				.singletonMap(Constants.NAME_OF_IDS, convertIdValues(entityMetaData.getRequiredIdProperty(), ids)))
 				.getResults();
 	}
 
-	private Object convertIdValues(Object idValues) {
+	private Object convertIdValues(@Nullable Neo4jPersistentProperty idProperty, Object idValues) {
 
-		return neo4jMappingContext.getEntityConverter().writeValueFromProperty(idValues,
-				ClassTypeInformation.from(idValues.getClass()));
+		return neo4jMappingContext.getConversionService().writeValue(idValues,
+				ClassTypeInformation.from(idValues.getClass()), idProperty == null ? null : idProperty.getOptionalWritingConverter());
 	}
 
 	@Override
@@ -320,14 +320,15 @@ public <T> List<T> saveAll(Iterable<T> instances) {
 	@Override
 	public <T> void deleteById(Object id, Class<T> domainType) {
 
-		Neo4jPersistentEntity entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
+		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
 		String nameOfParameter = "id";
 		Condition condition = entityMetaData.getIdExpression().isEqualTo(parameter(nameOfParameter));
 
 		log.debug(() -> String.format("Deleting entity with id %s ", id));
 
 		Statement statement = cypherGenerator.prepareDeleteOf(entityMetaData, condition);
-		ResultSummary summary = this.neo4jClient.query(renderer.render(statement)).in(getDatabaseName()).bind(convertIdValues(id))
+		ResultSummary summary = this.neo4jClient.query(renderer.render(statement)).in(getDatabaseName())
+				.bind(convertIdValues(entityMetaData.getRequiredIdProperty(), id))
 				.to(nameOfParameter).run();
 
 		log.debug(() -> String.format("Deleted %d nodes and %d relationships.", summary.counters().nodesDeleted(),
@@ -337,14 +338,15 @@ public <T> void deleteById(Object id, Class<T> domainType) {
 	@Override
 	public <T> void deleteAllById(Iterable<?> ids, Class<T> domainType) {
 
-		Neo4jPersistentEntity entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
+		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
 		String nameOfParameter = "ids";
 		Condition condition = entityMetaData.getIdExpression().in(parameter(nameOfParameter));
 
 		log.debug(() -> String.format("Deleting all entities with the following ids: %s ", ids));
 
 		Statement statement = cypherGenerator.prepareDeleteOf(entityMetaData, condition);
-		ResultSummary summary = this.neo4jClient.query(renderer.render(statement)).in(getDatabaseName()).bind(convertIdValues(ids))
+		ResultSummary summary = this.neo4jClient.query(renderer.render(statement)).in(getDatabaseName()).bind(
+				convertIdValues(entityMetaData.getRequiredIdProperty(), ids))
 				.to(nameOfParameter).run();
 
 		log.debug(() -> String.format("Deleted %d nodes and %d relationships.", summary.counters().nodesDeleted(),
@@ -428,7 +430,8 @@ private void processNestedRelations(Neo4jPersistentEntity<?> neo4jPersistentEnti
 				Statement relationshipRemoveQuery = cypherGenerator.createRelationshipRemoveQuery(neo4jPersistentEntity,
 						relationshipDescription, previouslyRelatedPersistentEntity);
 
-				neo4jClient.query(renderer.render(relationshipRemoveQuery)).in(inDatabase).bind(convertIdValues(fromId))
+				neo4jClient.query(renderer.render(relationshipRemoveQuery)).in(inDatabase)
+						.bind(convertIdValues(previouslyRelatedPersistentEntity.getIdProperty(), fromId))
 						.to(Constants.FROM_ID_PARAMETER_NAME).run();
 			}
 
@@ -455,7 +458,8 @@ private void processNestedRelations(Neo4jPersistentEntity<?> neo4jPersistentEnti
 						neo4jPersistentEntity, relationshipContext, relatedInternalId, relatedValueToStore);
 
 				neo4jClient.query(renderer.render(statementHolder.getStatement())).in(inDatabase)
-						.bind(convertIdValues(fromId)).to(Constants.FROM_ID_PARAMETER_NAME).bindAll(statementHolder.getProperties())
+						.bind(convertIdValues(targetNodeDescription.getRequiredIdProperty(), fromId))
+						.to(Constants.FROM_ID_PARAMETER_NAME).bindAll(statementHolder.getProperties())
 						.run();
 
 				// if an internal id is used this must get set to link this entity in the next iteration

src/main/java/org/springframework/data/neo4j/core/ReactiveNeo4jTemplate.java

@@ -182,33 +182,34 @@ public <T> Mono<T> findOne(String cypherQuery, Map<String, Object> parameters, C
 	@Override
 	public <T> Mono<T> findById(Object id, Class<T> domainType) {
 
-		Neo4jPersistentEntity entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
+		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
 		Statement statement = cypherGenerator
 				.prepareMatchOf(entityMetaData, entityMetaData.getIdExpression().isEqualTo(parameter(Constants.NAME_OF_ID)))
 				.returning(cypherGenerator.createReturnStatementForMatch(entityMetaData)).build();
 
 		return createExecutableQuery(domainType, statement, Collections
-				.singletonMap(Constants.NAME_OF_ID, convertIdValues(id)))
+				.singletonMap(Constants.NAME_OF_ID, convertIdValues(entityMetaData.getRequiredIdProperty(), id)))
 				.flatMap(ExecutableQuery::getSingleResult);
 	}
 
 	@Override
 	public <T> Flux<T> findAllById(Iterable<?> ids, Class<T> domainType) {
 
-		Neo4jPersistentEntity entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
+		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
 		Statement statement = cypherGenerator
 				.prepareMatchOf(entityMetaData, entityMetaData.getIdExpression().in((parameter(Constants.NAME_OF_IDS))))
 				.returning(cypherGenerator.createReturnStatementForMatch(entityMetaData)).build();
 
 		return createExecutableQuery(domainType, statement, Collections
-				.singletonMap(Constants.NAME_OF_IDS, convertIdValues(ids)))
+				.singletonMap(Constants.NAME_OF_IDS,
+						convertIdValues(entityMetaData.getRequiredIdProperty(), ids)))
 				.flatMapMany(ExecutableQuery::getResults);
 	}
 
-	private Object convertIdValues(Object idValues) {
+	private Object convertIdValues(@Nullable Neo4jPersistentProperty idProperty, Object idValues) {
 
-		return neo4jMappingContext.getEntityConverter().writeValueFromProperty(idValues,
-				ClassTypeInformation.from(idValues.getClass()));
+		return neo4jMappingContext.getConversionService().writeValue(idValues,
+				ClassTypeInformation.from(idValues.getClass()), idProperty == null ? null : idProperty.getOptionalWritingConverter());
 	}
 
 	@Override
@@ -328,13 +329,15 @@ public <T> Flux<T> saveAll(Iterable<T> instances) {
 	@Override
 	public <T> Mono<Void> deleteAllById(Iterable<?> ids, Class<T> domainType) {
 
-		Neo4jPersistentEntity entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
+		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
 		String nameOfParameter = "ids";
 		Condition condition = entityMetaData.getIdExpression().in(parameter(nameOfParameter));
 
 		Statement statement = cypherGenerator.prepareDeleteOf(entityMetaData, condition);
 		return getDatabaseName().flatMap(databaseName -> this.neo4jClient.query(() -> renderer.render(statement))
-				.in(databaseName.getValue()).bind(convertIdValues(ids)).to(nameOfParameter).run().then());
+				.in(databaseName.getValue())
+				.bind(convertIdValues(entityMetaData.getRequiredIdProperty(), ids))
+				.to(nameOfParameter).run().then());
 	}
 
 	@Override
@@ -343,12 +346,14 @@ public <T> Mono<Void> deleteById(Object id, Class<T> domainType) {
 		Assert.notNull(id, "The given id must not be null!");
 
 		String nameOfParameter = "id";
-		Neo4jPersistentEntity entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
+		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getPersistentEntity(domainType);
 		Condition condition = entityMetaData.getIdExpression().isEqualTo(parameter(nameOfParameter));
 
 		Statement statement = cypherGenerator.prepareDeleteOf(entityMetaData, condition);
 		return getDatabaseName().flatMap(databaseName -> this.neo4jClient.query(() -> renderer.render(statement))
-				.in(databaseName.getValue()).bind(convertIdValues(id)).to(nameOfParameter).run().then());
+				.in(databaseName.getValue())
+				.bind(convertIdValues(entityMetaData.getRequiredIdProperty(), id))
+				.to(nameOfParameter).run().then());
 	}
 
 	@Override
@@ -426,7 +431,8 @@ private Mono<Void> processNestedRelations(Neo4jPersistentEntity<?> neo4jPersiste
 					Statement relationshipRemoveQuery = cypherGenerator.createRelationshipRemoveQuery(neo4jPersistentEntity,
 							relationshipDescription, previouslyRelatedPersistentEntity);
 					relationshipCreationMonos.add(
-							neo4jClient.query(renderer.render(relationshipRemoveQuery)).in(inDatabase).bind(convertIdValues(fromId))
+							neo4jClient.query(renderer.render(relationshipRemoveQuery)).in(inDatabase)
+									.bind(convertIdValues(previouslyRelatedPersistentEntity.getIdProperty(), fromId))
 									.to(Constants.FROM_ID_PARAMETER_NAME).run().checkpoint("delete relationships").then());
 				}
 
@@ -462,7 +468,8 @@ private Mono<Void> processNestedRelations(Neo4jPersistentEntity<?> neo4jPersiste
 											// in case of no properties the bind will just return an empty map
 											Mono<ResultSummary> relationshipCreationMonoNested = neo4jClient
 													.query(renderer.render(statementHolder.getStatement())).in(inDatabase)
-													.bind(convertIdValues(fromId)).to(Constants.FROM_ID_PARAMETER_NAME)
+													.bind(convertIdValues(targetNodeDescription.getRequiredIdProperty(), fromId))
+													.to(Constants.FROM_ID_PARAMETER_NAME)
 													.bindAll(statementHolder.getProperties()).run();
 
 											if (processState != ProcessState.PROCESSED_ALL_VALUES) {

src/main/java/org/springframework/data/neo4j/core/convert/ConvertWith.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2011-2020 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.
+ */
+package org.springframework.data.neo4j.core.convert;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apiguardian.api.API;
+import org.neo4j.driver.Value;
+
+/**
+ * This annotation can be used to define either custom conversions for single attributes by specifying a custom
+ * {@link Neo4jPersistentPropertyConverter} and if needed, a custom factory to create that converter or the annotation
+ * can be used to build custom meta-annotated annotations like {@code @org.springframework.data.neo4j.core.support.DateLong}.
+ *
+ * <p>Custom conversions are applied to both attributes of entities and parameters of repository methods that map to those
+ * attributes (which does apply to all derived queries and queries by example but not to string based queries).
+ *
+ * <p>Converters that have a default constructor don't need a dedicated factory. A dedicated factory will be provided with
+ * either this annotation and its values or with the meta annotated annotation, including all configuration
+ * available.
+ *
+ * @author Michael J. Simons
+ * @soundtrack Antilopen Gang - Abwasser
+ * @since 6.0
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.ANNOTATION_TYPE, ElementType.FIELD })
+@Inherited
+@Documented
+@API(status = API.Status.STABLE, since = "6.0")
+public @interface ConvertWith {
+
+	Class<? extends Neo4jPersistentPropertyConverter<?>> converter() default UnsetConverter.class;
+
+	Class<? extends Neo4jPersistentPropertyConverterFactory> converterFactory() default DefaultNeo4jPersistentPropertyConverterFactory.class;
+
+	/**
+	 * Indicates an unset converter.
+	 */
+	final class UnsetConverter implements Neo4jPersistentPropertyConverter<Object> {
+
+		@Override public Value write(Object source) {
+			return null;
+		}
+
+		@Override public Object read(Value source) {
+			return null;
+		}
+	}
+}

src/main/java/org/springframework/data/neo4j/core/convert/DefaultNeo4jPersistentPropertyConverterFactory.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2011-2020 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.
+ */
+package org.springframework.data.neo4j.core.convert;
+
+import org.springframework.beans.BeanUtils;
+import org.springframework.data.neo4j.core.mapping.Neo4jPersistentProperty;
+
+/**
+ * @author Michael J. Simons
+ * @soundtrack Metallica - S&M2
+ * @since 6.0
+ */
+final class DefaultNeo4jPersistentPropertyConverterFactory implements Neo4jPersistentPropertyConverterFactory {
+
+	@Override
+	public Neo4jPersistentPropertyConverter getPropertyConverterFor(Neo4jPersistentProperty persistentProperty) {
+
+		ConvertWith config = persistentProperty.findAnnotation(ConvertWith.class);
+		if (config.converter() == ConvertWith.UnsetConverter.class) {
+			throw new IllegalArgumentException(
+					"The default custom conversion factory cannot be used with a placeholder");
+		}
+
+		Neo4jPersistentPropertyConverter<?> converter = BeanUtils.instantiateClass(config.converter());
+		return converter;
+	}
+}