DATAGRAPH-977 - Add bookmark management for causal clustering.

Author: frant-hartm

.editorconfig

@@ -0,0 +1,6 @@
+root=true
+
+[*.java]
+indent_style = tab
+indent_size = 4
+continuation_indent_size = 8

spring-data-neo4j/pom.xml

@@ -133,6 +133,14 @@
             <scope>test</scope>
         </dependency>
 
+        <!-- Cache -->
+        <dependency>
+            <groupId>com.github.ben-manes.caffeine</groupId>
+            <artifactId>caffeine</artifactId>
+            <version>2.5.2</version>
+            <optional>true</optional>
+        </dependency>
+
         <!-- Neo4j OGM -->
         <dependency>
             <groupId>org.neo4j</groupId>

spring-data-neo4j/src/main/java/org/springframework/data/neo4j/annotation/EnableBookmarkManagement.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c)  [2011-2017] "Pivotal Software, Inc." / "Neo Technology" / "Graph Aware Ltd."
+ *
+ * This product is licensed to you under the Apache License, Version 2.0 (the "License").
+ * You may not use this product except in compliance with the License.
+ *
+ * This product may include a number of subcomponents with
+ * separate copyright notices and license terms. Your use of the source
+ * code for these subcomponents is subject to the terms and
+ * conditions of the subcomponent's license, as noted in the LICENSE file.
+ *
+ */
+
+package org.springframework.data.neo4j.annotation;
+
+import org.springframework.context.annotation.Import;
+import org.springframework.data.neo4j.bookmark.BookmarkManagementConfiguration;
+
+import java.lang.annotation.*;
+
+/**
+ * Enables bookmark management
+ * <p>
+ * Bean implementing {@link org.springframework.data.neo4j.bookmark.BookmarkManager} interface needs to exist in the
+ * context. Default implementation {@link org.springframework.data.neo4j.bookmark.CaffeineBookmarkManager} exists.
+ * Use scope of the bean to control how bookmarks are managed.
+ * singleton - suitable for application wide bookmarks, e.g. fat clients
+ * request,session - suitable for web applications
+ * <p>
+ * NOTE: Only usable with OGM Bolt driver.
+ *
+ * @author Frantisek Hartman
+ * @see UseBookmark
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = ElementType.TYPE)
+@Documented
+@Import(BookmarkManagementConfiguration.class)
+public @interface EnableBookmarkManagement {
+}

spring-data-neo4j/src/main/java/org/springframework/data/neo4j/annotation/UseBookmark.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c)  [2011-2017] "Pivotal Software, Inc." / "Neo Technology" / "Graph Aware Ltd."
+ *
+ * This product is licensed to you under the Apache License, Version 2.0 (the "License").
+ * You may not use this product except in compliance with the License.
+ *
+ * This product may include a number of subcomponents with
+ * separate copyright notices and license terms. Your use of the source
+ * code for these subcomponents is subject to the terms and
+ * conditions of the subcomponent's license, as noted in the LICENSE file.
+ *
+ */
+
+package org.springframework.data.neo4j.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * Indicates that a transactional operation will use bookmarks that are currently stored in BookmarkManager when
+ * creating Neo4j session.
+ * Must be used on a method with @Transactional annotation.
+ * May be used on class - applies to all methods or on specific methods.
+ * <p>
+ *
+ * @author Frantisek Hartman
+ * @see EnableBookmarkManagement
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Documented
+public @interface UseBookmark {
+
+	/**
+	 * If the annotated method should set bookmark
+	 */
+	boolean value() default true;
+}

spring-data-neo4j/src/main/java/org/springframework/data/neo4j/bookmark/BeanFactoryBookmarkOperationAdvisor.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c)  [2011-2017] "Pivotal Software, Inc." / "Neo Technology" / "Graph Aware Ltd."
+ *
+ * This product is licensed to you under the Apache License, Version 2.0 (the "License").
+ * You may not use this product except in compliance with the License.
+ *
+ * This product may include a number of subcomponents with
+ * separate copyright notices and license terms. Your use of the source
+ * code for these subcomponents is subject to the terms and
+ * conditions of the subcomponent's license, as noted in the LICENSE file.
+ *
+ */
+
+package org.springframework.data.neo4j.bookmark;
+
+import org.springframework.aop.Pointcut;
+import org.springframework.aop.support.AbstractBeanFactoryPointcutAdvisor;
+
+/**
+ * Advisor for BookmarkManagement
+ * <p>
+ * Used to setup BookmarkInfo for methods marked with @{@link org.springframework.data.neo4j.annotation.UseBookmark}
+ *
+ * @author Frantisek Hartman
+ */
+public class BeanFactoryBookmarkOperationAdvisor extends AbstractBeanFactoryPointcutAdvisor {
+
+	private Pointcut pointcut = new BookmarkOperationPointcut();
+
+	@Override
+	public Pointcut getPointcut() {
+		return pointcut;
+	}
+}

spring-data-neo4j/src/main/java/org/springframework/data/neo4j/bookmark/BookmarkInfo.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c)  [2011-2017] "Pivotal Software, Inc." / "Neo Technology" / "Graph Aware Ltd."
+ *
+ * This product is licensed to you under the Apache License, Version 2.0 (the "License").
+ * You may not use this product except in compliance with the License.
+ *
+ * This product may include a number of subcomponents with
+ * separate copyright notices and license terms. Your use of the source
+ * code for these subcomponents is subject to the terms and
+ * conditions of the subcomponent's license, as noted in the LICENSE file.
+ *
+ */
+
+package org.springframework.data.neo4j.bookmark;
+
+import java.io.Serializable;
+import java.util.Collection;
+
+/**
+ * Bookmark info stored as thread local
+ *
+ * @author Frantisek Hartman
+ */
+public class BookmarkInfo implements Serializable {
+
+	private boolean useBookmark;
+	private Collection<String> bookmarks;
+
+	public BookmarkInfo() {
+	}
+
+	public BookmarkInfo(boolean useBookmark) {
+		this.useBookmark = true;
+	}
+
+	public boolean shouldUseBookmark() {
+		return useBookmark;
+	}
+
+	public void setUseBookmark(boolean useBookmark) {
+		this.useBookmark = useBookmark;
+	}
+
+	public Collection<String> getBookmarks() {
+		return bookmarks;
+	}
+
+	public void setBookmarks(Collection<String> bookmarks) {
+		this.bookmarks = bookmarks;
+	}
+}

spring-data-neo4j/src/main/java/org/springframework/data/neo4j/bookmark/BookmarkInterceptor.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c)  [2011-2017] "Pivotal Software, Inc." / "Neo Technology" / "Graph Aware Ltd."
+ *
+ * This product is licensed to you under the Apache License, Version 2.0 (the "License").
+ * You may not use this product except in compliance with the License.
+ *
+ * This product may include a number of subcomponents with
+ * separate copyright notices and license terms. Your use of the source
+ * code for these subcomponents is subject to the terms and
+ * conditions of the subcomponent's license, as noted in the LICENSE file.
+ *
+ */
+
+package org.springframework.data.neo4j.bookmark;
+
+import org.aopalliance.intercept.MethodInterceptor;
+import org.aopalliance.intercept.MethodInvocation;
+
+/**
+ * Interceptor that sets {@link BookmarkInfo} as a ThreadLocal
+ *
+ * @author Frantisek Hartman
+ */
+public class BookmarkInterceptor extends BookmarkSupport implements MethodInterceptor {
+
+	@Override
+	public Object invoke(MethodInvocation invocation) throws Throwable {
+		BookmarkInfo previousValue;
+
+		if (bookmarkInfoHolder.get() == null) {
+			previousValue = null;
+		} else {
+			previousValue = bookmarkInfoHolder.get();
+		}
+		bookmarkInfoHolder.set(new BookmarkInfo(true));
+
+		try {
+			return invocation.proceed();
+		} finally {
+			bookmarkInfoHolder.set(previousValue);
+		}
+	}
+}

spring-data-neo4j/src/main/java/org/springframework/data/neo4j/bookmark/BookmarkManagementConfiguration.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c)  [2011-2017] "Pivotal Software, Inc." / "Neo Technology" / "Graph Aware Ltd."
+ *
+ * This product is licensed to you under the Apache License, Version 2.0 (the "License").
+ * You may not use this product except in compliance with the License.
+ *
+ * This product may include a number of subcomponents with
+ * separate copyright notices and license terms. Your use of the source
+ * code for these subcomponents is subject to the terms and
+ * conditions of the subcomponent's license, as noted in the LICENSE file.
+ *
+ */
+
+package org.springframework.data.neo4j.bookmark;
+
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Role;
+
+/**
+ * Configuration used by @{@link org.springframework.data.neo4j.annotation.EnableBookmarkManagement}
+ * <p>
+ * Note on bookmark management implementation:
+ * The implementation closely follows implementation of @EnableTransactionManagement or @EnableCaching, with simplified
+ * pointcut.
+ * <p>
+ * The bookmark interceptor will set BookmarkInfo thread local when a methods is annotated with @UseBookmark.
+ * It is executed before transactional advice (see setOrder(0) ).
+ * Neo4j transaction manager then uses {@link BookmarkManager} bean to retrieve currently stored bookmarks and begins
+ * new transaction using these bookmarks.
+ * After commit new bookmark is stored in the BookmarkManager, replacing the bookmarks used to begin the transaction.
+ * The user needs to provide the BookmarkManager bean.
+ *
+ * @author Frantisek Hartman
+ */
+@Configuration
+public class BookmarkManagementConfiguration {
+
+	@Bean
+	@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
+	public BeanFactoryBookmarkOperationAdvisor bookmarkAdvisor() {
+		BeanFactoryBookmarkOperationAdvisor advisor = new BeanFactoryBookmarkOperationAdvisor();
+		advisor.setAdvice(bookmarkInterceptor());
+		advisor.setOrder(0);
+		return advisor;
+	}
+
+
+	@Bean
+	@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
+	public BookmarkInterceptor bookmarkInterceptor() {
+		return new BookmarkInterceptor();
+	}
+
+}

spring-data-neo4j/src/main/java/org/springframework/data/neo4j/bookmark/BookmarkManager.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c)  [2011-2017] "Pivotal Software, Inc." / "Neo Technology" / "Graph Aware Ltd."
+ *
+ * This product is licensed to you under the Apache License, Version 2.0 (the "License").
+ * You may not use this product except in compliance with the License.
+ *
+ * This product may include a number of subcomponents with
+ * separate copyright notices and license terms. Your use of the source
+ * code for these subcomponents is subject to the terms and
+ * conditions of the subcomponent's license, as noted in the LICENSE file.
+ *
+ */
+
+package org.springframework.data.neo4j.bookmark;
+
+import java.util.Collection;
+
+/**
+ * Bookmark manager keeps track of Neo4j transaction bookmarks
+ *
+ * @author Frantisek Hartman
+ * @see org.springframework.data.neo4j.annotation.EnableBookmarkManagement
+ */
+public interface BookmarkManager {
+
+	/**
+	 * Return stored bookmarks
+	 *
+	 * @return bookmarks
+	 */
+	Collection<String> getBookmarks();
+
+	/**
+	 * Stores bookmark to this manager
+	 *
+	 * @param bookmark new bookmark to store
+	 * @param previous previous bookmarks that are to be replaced by new bookmark, may be empty
+	 */
+	void storeBookmark(String bookmark, Collection<String> previous);
+}

spring-data-neo4j/src/main/java/org/springframework/data/neo4j/bookmark/BookmarkOperationPointcut.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c)  [2011-2017] "Pivotal Software, Inc." / "Neo Technology" / "Graph Aware Ltd."
+ *
+ * This product is licensed to you under the Apache License, Version 2.0 (the "License").
+ * You may not use this product except in compliance with the License.
+ *
+ * This product may include a number of subcomponents with
+ * separate copyright notices and license terms. Your use of the source
+ * code for these subcomponents is subject to the terms and
+ * conditions of the subcomponent's license, as noted in the LICENSE file.
+ *
+ */
+
+package org.springframework.data.neo4j.bookmark;
+
+import org.springframework.aop.support.StaticMethodMatcherPointcut;
+import org.springframework.data.neo4j.annotation.UseBookmark;
+
+import java.lang.reflect.Method;
+
+/**
+ * Pointcut for methods marked with @{@link UseBookmark}
+ *
+ * @author Frantisek Hartman
+ */
+public class BookmarkOperationPointcut extends StaticMethodMatcherPointcut {
+
+	@Override
+	public boolean matches(Method method, Class<?> targetClass) {
+		UseBookmark classAnnotation = targetClass.getAnnotation(UseBookmark.class);
+		UseBookmark methodAnnotation = method.getAnnotation(UseBookmark.class);
+
+		// method matches if @UseBookmark is on class, is true and not on method or
+		// @UseBookmark is on method and is true
+		// it is needed to cover @UseBookmark on class and @UseBookmark(false) on method
+		return ((classAnnotation != null) && classAnnotation.value() && methodAnnotation == null) ||
+				((methodAnnotation != null) && methodAnnotation.value());
+	}
+}