feat: Allow direct rendering of Visitable objects. (#554)

This adds a generalised version of the `org.neo4j.cypherdsl.core.renderer.Renderer` that can be retrieved via `org.neo4j.cypherdsl.core.renderer.Renderer#getRenderer(org.neo4j.cypherdsl.core.renderer.Configuration, java.lang.Class<T>)`. This generalised version adds an overload of `render` that accepts any `Visitable` so that an intermediate representation can be retrieved.

Changing the interface to accept `Visitable` in general would have broken binary compatibility, an overload on the current interface has been discarded to avoid ambiguity.

Reluctant use is suggested, as the intermediate representation won't be cached in the renderer.

In addition, an overload of `toString` has been added to many `Visitable` types. While I would liked to have added this to the `Visitable` interface as suggested by @lukaseder, this is not possible as specified in the JLS 9.4.1.2. "Requirements in Overriding" (https://docs.oracle.com/javase/specs/jls/se17/html/jls-9.html#jls-9.4.1.2) (more background here https://mail.openjdk.org/pipermail/lambda-dev/2013-March/008435.html)

Closes #552.

Author: michael-simons

README.adoc

@@ -6,7 +6,7 @@
 :artifactId: neo4j-cypher-dsl
 
 // This will be next version and also the one that will be put into the manual for the main branch
-:neo4j-cypher-dsl-version: 2023.0.1-SNAPSHOT
+:neo4j-cypher-dsl-version: 2023.1.0-SNAPSHOT
 // This is the latest released version, used only in the readme
 :neo4j-cypher-dsl-version-latest: 2023.0.0
 

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/AbstractCase.java

@@ -48,16 +48,17 @@ public static Case create(@Nullable Expression expression) {
 		return expression == null ? new GenericCaseImpl() : new SimpleCaseImpl(expression);
 	}
 
-	AbstractCase() {
-		this(Collections.emptyList());
-	}
-
 	AbstractCase(List<CaseWhenThen> caseWhenThens) {
 		this.caseWhenThens = new ArrayList<>(caseWhenThens);
 	}
 
 	abstract Expression getCaseExpression();
 
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
+
 	void setCaseElse(CaseElse caseElse) {
 		this.caseElse = caseElse;
 	}

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/AbstractClause.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2019-2023 "Neo4j,"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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.neo4j.cypherdsl.core;
+
+abstract class AbstractClause implements Clause {
+
+	@Override
+	public final String toString() {
+		return RendererBridge.render(this);
+	}
+}

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/AbstractNode.java

@@ -120,4 +120,9 @@ public final Relationship relationshipFrom(Node other, String... types) {
 	public final Relationship relationshipBetween(Node other, String... types) {
 		return new InternalRelationshipImpl(null, this, Relationship.Direction.UNI, other, types);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/AliasedExpression.java

@@ -81,4 +81,9 @@ Expression getDelegate() {
 	public Expression asExpression() {
 		return this;
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Arguments.java

@@ -55,4 +55,9 @@ public Optional<String> getPrefix() {
 	public Optional<String> getSuffix() {
 		return Optional.of(")");
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Comparison.java

@@ -99,5 +99,10 @@ public Condition not() {
 		}
 		return Condition.super.not();
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }
 

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Create.java

@@ -31,7 +31,7 @@
  * @since 1.0
  */
 @API(status = STABLE, since = "1.0")
-public final class Create implements UpdatingClause {
+public final class Create extends AbstractClause implements UpdatingClause {
 
 	private final Pattern pattern;
 

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/DecoratedQuery.java

@@ -36,7 +36,12 @@ sealed class DecoratedQuery extends AbstractStatement implements UseStatement {
 
 	private enum Decoration implements Visitable {
 
-		EXPLAIN, PROFILE
+		EXPLAIN, PROFILE;
+
+		@Override
+		public String toString() {
+			return RendererBridge.render(this);
+		}
 	}
 
 	private final Visitable decoration;

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Delete.java

@@ -31,7 +31,7 @@
  * @since 1.0
  */
 @API(status = STABLE, since = "1.0")
-public final class Delete implements UpdatingClause {
+public final class Delete extends AbstractClause implements UpdatingClause {
 
 	private final ExpressionList deleteItems;
 

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/ExpressionList.java

@@ -50,4 +50,9 @@ protected Visitable prepareVisit(Expression child) {
 	boolean isEmpty() {
 		return super.children.isEmpty();
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Foreach.java

@@ -32,7 +32,7 @@
  * @since 2021.3.0
  */
 @API(status = STABLE, since = "2021.3.0")
-public final class Foreach implements UpdatingClause {
+public final class Foreach extends AbstractClause implements UpdatingClause {
 
 	private final SymbolicName variable;
 

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/FunctionInvocation.java

@@ -181,9 +181,8 @@ public void accept(Visitor visitor) {
 		visitor.leave(this);
 	}
 
-	@Override public String toString() {
-		return "FunctionInvocation{" +
-			"functionName='" + functionName + '\'' +
-			'}';
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
 	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Hint.java

@@ -40,9 +40,19 @@
  */
 public final class Hint implements Visitable {
 
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
+
 	private enum Type implements Visitable {
 
-		INDEX, INDEX_SEEK, SCAN, JOIN_ON
+		INDEX, INDEX_SEEK, SCAN, JOIN_ON;
+
+		@Override
+		public String toString() {
+			return RendererBridge.render(this);
+		}
 	}
 
 	private static final class IndexReference implements Visitable {
@@ -71,6 +81,11 @@ public void accept(Visitor visitor) {
 			Visitable.visitIfNotNull(this.optionalLabel, visitor);
 			visitor.leave(this);
 		}
+
+		@Override
+		public String toString() {
+			return RendererBridge.render(this);
+		}
 	}
 
 	private static final class IndexReferences extends TypedSubtree<IndexReference> {

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/InTransactions.java

@@ -62,4 +62,9 @@ public void accept(Visitor visitor) {
 		subquery.accept(visitor);
 		visitor.leave(this);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/InternalPropertyImpl.java

@@ -165,4 +165,9 @@ private static SymbolicName extractRequiredSymbolicName(Named parentContainer) {
 	public Expression asExpression() {
 		return this;
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/KeyValueMapEntry.java

@@ -79,4 +79,9 @@ public void accept(Visitor visitor) {
 		value.accept(visitor);
 		visitor.leave(this);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Limit.java

@@ -52,4 +52,9 @@ public void accept(Visitor visitor) {
 		limitExpression.accept(visitor);
 		visitor.leave(this);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/ListExpression.java

@@ -64,4 +64,9 @@ public void accept(Visitor visitor) {
 		this.content.accept(visitor);
 		visitor.leave(this);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/ListOperator.java

@@ -37,7 +37,7 @@
  * @since 2020.1.0
  */
 @API(status = API.Status.EXPERIMENTAL, since = "2020.1.0")
-public final class ListOperator implements Expression {
+public final class ListOperator implements Expression, Visitable {
 
 	/**
 	 * A literal for the dots.
@@ -93,6 +93,11 @@ public Optional<String> getPrefix() {
 		public Optional<String> getSuffix() {
 			return Optional.of("]");
 		}
+
+		@Override
+		public String toString() {
+			return RendererBridge.render(this);
+		}
 	}
 
 	/**

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/ListPredicate.java

@@ -65,4 +65,9 @@ public void accept(Visitor visitor) {
 		this.where.accept(visitor);
 		visitor.leave(this);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/LiteralBase.java

@@ -51,5 +51,10 @@ protected LiteralBase(T content) {
 	public final T getContent() {
 		return content;
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }
 

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/MapExpression.java

@@ -106,4 +106,9 @@ MapExpression addEntries(List<Expression> entries) {
 	protected Visitable prepareVisit(Expression child) {
 		return Expressions.nameOrExpression(child);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/MapProjection.java

@@ -130,14 +130,13 @@ private static List<Expression> createNewContent(Object... content) {
 				knownKeys.add(lastKey);
 			} else if (lastExpression instanceof SymbolicName || lastExpression instanceof PropertyLookup) {
 				newContent.add(lastExpression);
-			} else if (lastExpression instanceof Property) {
-				List<PropertyLookup> names = ((Property) lastExpression).getNames();
+			} else if (lastExpression instanceof Property property) {
+				List<PropertyLookup> names = property.getNames();
 				if (names.size() > 1) {
 					throw new IllegalArgumentException("Cannot project nested properties!");
 				}
 				newContent.addAll(names);
-			} else if (lastExpression instanceof AliasedExpression) {
-				AliasedExpression aliasedExpression = (AliasedExpression) lastExpression;
+			} else if (lastExpression instanceof AliasedExpression aliasedExpression) {
 				newContent.add(KeyValueMapEntry.create(aliasedExpression.getAlias(), aliasedExpression));
 			} else if (lastExpression instanceof KeyValueMapEntry) {
 				newContent.add(lastExpression);
@@ -153,4 +152,9 @@ private static List<Expression> createNewContent(Object... content) {
 		}
 		return newContent;
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Match.java

@@ -37,7 +37,7 @@
  * @since 1.0
  */
 @API(status = STABLE, since = "1.0")
-public final class Match implements ReadingClause {
+public final class Match extends AbstractClause implements ReadingClause {
 
 	private final boolean optional;
 

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/Merge.java

@@ -37,7 +37,7 @@
  * @since 1.0
  */
 @API(status = STABLE, since = "1.0")
-public final class Merge implements UpdatingClause {
+public final class Merge extends AbstractClause implements UpdatingClause {
 
 	/**
 	 * A literal for the blank.
@@ -81,4 +81,3 @@ public void accept(Visitor visitor) {
 		visitor.leave(this);
 	}
 }
-

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/MergeAction.java

@@ -41,6 +41,11 @@
 @API(status = STABLE, since = "2020.1.2")
 public final class MergeAction implements Visitable {
 
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
+
 	/**
 	 * The type of the action.
 	 */

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/MultiPartElement.java

@@ -54,4 +54,9 @@ public void accept(Visitor visitor) {
 		with.accept(visitor);
 		visitor.leave(this);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/NestedExpression.java

@@ -43,4 +43,9 @@ public void accept(Visitor visitor) {
 		Expressions.nameOrExpression(this.delegate).accept(visitor);
 		visitor.leave(this);
 	}
+
+	@Override
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }

neo4j-cypher-dsl/src/main/java/org/neo4j/cypherdsl/core/NodeLabels.java

@@ -47,4 +47,8 @@ public void accept(Visitor visitor) {
 		values.forEach(value -> value.accept(visitor));
 		visitor.leave(this);
 	}
+
+	public String toString() {
+		return RendererBridge.render(this);
+	}
 }