Moved Bookmark into public API and then provided a string conversion method to convert string bookmarks to Bookmark

Author: Zhen Li

driver/src/main/java/org/neo4j/driver/internal/Bookmark.java renamed to driver/src/main/java/org/neo4j/driver/Bookmark.java

@@ -16,7 +16,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.neo4j.driver.internal;
+package org.neo4j.driver;
 
 import java.io.Serializable;
 

driver/src/main/java/org/neo4j/driver/Session.java

@@ -21,7 +21,6 @@
 import java.util.Map;
 
 import org.neo4j.driver.async.AsyncSession;
-import org.neo4j.driver.internal.Bookmark;
 import org.neo4j.driver.util.Resource;
 
 /**

driver/src/main/java/org/neo4j/driver/SessionConfig.java

@@ -23,7 +23,6 @@
 import java.util.Optional;
 
 import org.neo4j.driver.async.AsyncSession;
-import org.neo4j.driver.internal.Bookmark;
 import org.neo4j.driver.reactive.RxSession;
 
 import static java.util.Objects.requireNonNull;

driver/src/main/java/org/neo4j/driver/async/AsyncSession.java

@@ -29,7 +29,7 @@
 import org.neo4j.driver.Transaction;
 import org.neo4j.driver.TransactionConfig;
 import org.neo4j.driver.Values;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 
 /**
  * Provides a context of work for database interactions.

driver/src/main/java/org/neo4j/driver/internal/InternalBookmark.java

@@ -25,6 +25,8 @@
 import java.util.Objects;
 import java.util.Set;
 
+import org.neo4j.driver.Bookmark;
+
 import static java.util.Objects.requireNonNull;
 
 public final class InternalBookmark implements Bookmark
@@ -97,7 +99,7 @@ private static void assertInternalBookmark( Bookmark bookmark )
     {
         if ( !(bookmark instanceof InternalBookmark) )
         {
-            throw new IllegalArgumentException( String.format( "Received bookmark '%s' is not generated by driver sessions.", bookmark ) );
+            throw new IllegalArgumentException( String.format( "Received bookmark '%s' is not generated by a driver session.", bookmark ) );
         }
     }
 

driver/src/main/java/org/neo4j/driver/internal/InternalSession.java

@@ -21,6 +21,7 @@
 import java.util.Map;
 
 import org.neo4j.driver.AccessMode;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.Session;
 import org.neo4j.driver.Statement;
 import org.neo4j.driver.StatementResult;

driver/src/main/java/org/neo4j/driver/internal/async/InternalAsyncSession.java

@@ -29,7 +29,7 @@
 import org.neo4j.driver.async.AsyncTransaction;
 import org.neo4j.driver.async.AsyncTransactionWork;
 import org.neo4j.driver.async.StatementResultCursor;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.util.Futures;
 
 import static java.util.Collections.emptyMap;

driver/src/main/java/org/neo4j/driver/internal/async/NetworkSession.java

@@ -29,7 +29,7 @@
 import org.neo4j.driver.TransactionConfig;
 import org.neo4j.driver.async.StatementResultCursor;
 import org.neo4j.driver.exceptions.ClientException;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.BookmarkHolder;
 import org.neo4j.driver.internal.FailableCursor;
 import org.neo4j.driver.internal.InternalBookmark;

driver/src/main/java/org/neo4j/driver/internal/reactive/InternalRxSession.java

@@ -27,7 +27,7 @@
 import org.neo4j.driver.AccessMode;
 import org.neo4j.driver.Statement;
 import org.neo4j.driver.TransactionConfig;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.async.NetworkSession;
 import org.neo4j.driver.internal.cursor.RxStatementResultCursor;
 import org.neo4j.driver.internal.util.Futures;

driver/src/main/java/org/neo4j/driver/reactive/RxSession.java

@@ -28,7 +28,7 @@
 import org.neo4j.driver.Statement;
 import org.neo4j.driver.TransactionConfig;
 import org.neo4j.driver.Values;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 
 /**
  * A reactive session is the same as {@link Session} except it provides a reactive API.

driver/src/main/java/org/neo4j/driver/util/BookmarkUtil.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2002-2019 "Neo4j,"
+ * Neo4j Sweden AB [http://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
+ *
+ *     http://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.driver.util;
+
+import java.io.Serializable;
+import java.util.Collection;
+
+import org.neo4j.driver.Bookmark;
+import org.neo4j.driver.internal.InternalBookmark;
+
+/**
+ * Utils for {@link Bookmark}. This class is deprecated and will be removed from public API in future versions.
+ */
+@Deprecated
+public final class BookmarkUtil
+{
+    /**
+     * Parse {@link Bookmark} from a string value. The bookmark string has to be a single bookmark string such as "aBookmarkString".
+     * Use {@link BookmarkUtil#parse(Collection)} instead to parse multiple bookmark strings into one {@link Bookmark}.
+     * @param value a bookmark string.
+     * @return A {@link Bookmark bookmark}
+     * @deprecated This method is deprecated and will be removed in future versions.
+     * This method provides back-compatibility to convert string bookmarks used in previous driver versions to {@link Bookmark} which is used in this new driver version.
+     * This method shall not be used to convert a bookmark string from {@link Bookmark} back to {@link Bookmark}.
+     * A bookmark shall only be obtained via the driver and passed directly to the driver.
+     * The content of the bookmark shall not be inspected or altered by any client application.
+     */
+    @Deprecated
+    public static Bookmark parse( String value )
+    {
+        return InternalBookmark.parse( value );
+    }
+
+    /**
+     * Parse {@link Bookmark} from a collection of bookmark strings. Each bookmark string in the collection has to be a single bookmark string such as "aBookmarkString".
+     * Use {@link BookmarkUtil#parse(String)} instead to parse a single bookmark string into one {@link Bookmark}.
+     * @param values a collections of bookmark string. The collection has to implement {@link Serializable}.
+     * @return A {@link Bookmark bookmark}
+     * @throws IllegalArgumentException if the collection of bookmark strings does not implement {@link Serializable}.
+     * @deprecated This method is deprecated and will be removed in future versions.
+     * This method provides back-compatibility to convert string bookmarks used in previous driver versions to {@link Bookmark} which is used in this new driver version.
+     * This method shall not be used to convert a bookmark string from {@link Bookmark} back to {@link Bookmark}.
+     * A bookmark shall only be obtained via the driver and passed directly to the driver.
+     * The content of the bookmark shall not be inspected or altered by any client application.
+     */
+    @Deprecated
+    public static Bookmark parse( Collection<String> values )
+    {
+        return InternalBookmark.parse( values );
+    }
+}

driver/src/test/java/org/neo4j/driver/SessionConfigTest.java

@@ -29,8 +29,6 @@
 import java.util.List;
 import java.util.stream.Stream;
 
-import org.neo4j.driver.internal.Bookmark;
-
 import static java.util.Collections.emptyList;
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.junit.Assert.assertEquals;

driver/src/test/java/org/neo4j/driver/integration/BookmarkIT.java

@@ -26,7 +26,7 @@
 import org.neo4j.driver.Session;
 import org.neo4j.driver.Transaction;
 import org.neo4j.driver.exceptions.ClientException;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.util.DisabledOnNeo4jWith;
 import org.neo4j.driver.internal.util.EnabledOnNeo4jWith;
 import org.neo4j.driver.internal.util.Neo4jFeature;
@@ -39,9 +39,9 @@
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.neo4j.driver.SessionConfig.builder;
 import static org.neo4j.driver.internal.InternalBookmark.parse;
-import static org.neo4j.driver.internal.util.BookmarkUtils.assertBookmarkContainsSingleValue;
-import static org.neo4j.driver.internal.util.BookmarkUtils.assertBookmarkIsEmpty;
-import static org.neo4j.driver.internal.util.BookmarkUtils.assertBookmarksContainsSingleUniqueValues;
+import static org.neo4j.driver.internal.util.BookmarkUtil.assertBookmarkContainsSingleValue;
+import static org.neo4j.driver.internal.util.BookmarkUtil.assertBookmarkIsEmpty;
+import static org.neo4j.driver.internal.util.BookmarkUtil.assertBookmarksContainsSingleUniqueValues;
 
 @ParallelizableIT
 class BookmarkIT

driver/src/test/java/org/neo4j/driver/integration/RoutingDriverBoltKitTest.java

@@ -46,7 +46,7 @@
 import org.neo4j.driver.exceptions.ServiceUnavailableException;
 import org.neo4j.driver.exceptions.SessionExpiredException;
 import org.neo4j.driver.exceptions.TransientException;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.DriverFactory;
 import org.neo4j.driver.internal.cluster.RoutingSettings;
 import org.neo4j.driver.internal.retry.RetrySettings;

driver/src/test/java/org/neo4j/driver/integration/RoutingDriverMultidatabaseBoltKitTest.java

@@ -35,7 +35,7 @@
 import org.neo4j.driver.exceptions.FatalDiscoveryException;
 import org.neo4j.driver.exceptions.ServiceUnavailableException;
 import org.neo4j.driver.integration.RoutingDriverBoltKitTest.PortBasedServerAddressComparator;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.net.ServerAddress;
 import org.neo4j.driver.net.ServerAddressResolver;
 import org.neo4j.driver.util.StubServer;

driver/src/test/java/org/neo4j/driver/integration/SessionBoltV3IT.java

@@ -38,7 +38,7 @@
 import org.neo4j.driver.async.AsyncSession;
 import org.neo4j.driver.async.StatementResultCursor;
 import org.neo4j.driver.exceptions.TransientException;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.cluster.RoutingSettings;
 import org.neo4j.driver.internal.messaging.Message;
 import org.neo4j.driver.internal.messaging.request.GoodbyeMessage;

driver/src/test/java/org/neo4j/driver/integration/SessionIT.java

@@ -91,9 +91,9 @@
 import static org.neo4j.driver.SessionConfig.forDatabase;
 import static org.neo4j.driver.Values.parameters;
 import static org.neo4j.driver.internal.logging.DevNullLogging.DEV_NULL_LOGGING;
-import static org.neo4j.driver.internal.util.BookmarkUtils.assertBookmarkContainsSingleValue;
-import static org.neo4j.driver.internal.util.BookmarkUtils.assertBookmarkIsEmpty;
-import static org.neo4j.driver.internal.util.BookmarkUtils.assertBookmarkIsNotEmpty;
+import static org.neo4j.driver.internal.util.BookmarkUtil.assertBookmarkContainsSingleValue;
+import static org.neo4j.driver.internal.util.BookmarkUtil.assertBookmarkIsEmpty;
+import static org.neo4j.driver.internal.util.BookmarkUtil.assertBookmarkIsNotEmpty;
 import static org.neo4j.driver.internal.util.Matchers.arithmeticError;
 import static org.neo4j.driver.internal.util.Matchers.connectionAcquisitionTimeoutError;
 import static org.neo4j.driver.internal.util.Neo4jFeature.BOLT_V4;

driver/src/test/java/org/neo4j/driver/integration/async/AsyncTransactionIT.java

@@ -42,7 +42,7 @@
 import org.neo4j.driver.exceptions.ClientException;
 import org.neo4j.driver.exceptions.NoSuchRecordException;
 import org.neo4j.driver.exceptions.ServiceUnavailableException;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.summary.ResultSummary;
 import org.neo4j.driver.summary.StatementType;
 import org.neo4j.driver.types.Node;

driver/src/test/java/org/neo4j/driver/integration/reactive/RxTransactionIT.java

@@ -42,7 +42,7 @@
 import org.neo4j.driver.Value;
 import org.neo4j.driver.exceptions.ClientException;
 import org.neo4j.driver.exceptions.ServiceUnavailableException;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.util.EnabledOnNeo4jWith;
 import org.neo4j.driver.reactive.RxSession;
 import org.neo4j.driver.reactive.RxStatementResult;

driver/src/test/java/org/neo4j/driver/internal/DirectDriverBoltKitTest.java

@@ -29,6 +29,7 @@
 
 import org.neo4j.driver.AccessMode;
 import org.neo4j.driver.AuthTokens;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.Config;
 import org.neo4j.driver.Driver;
 import org.neo4j.driver.GraphDatabase;

driver/src/test/java/org/neo4j/driver/internal/InternalBookmarkTest.java

@@ -27,6 +27,7 @@
 import java.util.Arrays;
 import java.util.List;
 
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.util.Iterables;
 
 import static java.util.Arrays.asList;

driver/src/test/java/org/neo4j/driver/internal/async/NetworkSessionTest.java

@@ -30,7 +30,7 @@
 import org.neo4j.driver.TransactionConfig;
 import org.neo4j.driver.async.StatementResultCursor;
 import org.neo4j.driver.exceptions.ClientException;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.InternalBookmark;
 import org.neo4j.driver.internal.messaging.BoltProtocol;
 import org.neo4j.driver.internal.messaging.request.PullMessage;

driver/src/test/java/org/neo4j/driver/internal/util/BookmarkUtils.java renamed to driver/src/test/java/org/neo4j/driver/internal/util/BookmarkUtil.java

@@ -23,7 +23,7 @@
 import java.util.HashSet;
 import java.util.List;
 
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.InternalBookmark;
 
 import static org.hamcrest.Matchers.equalTo;
@@ -36,7 +36,7 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.neo4j.driver.internal.util.Iterables.asList;
 
-public class BookmarkUtils
+public class BookmarkUtil
 {
     /**
      * Bookmark is empty.
@@ -79,6 +79,18 @@ public static void assertBookmarkContainsSingleValue( Bookmark bookmark, Matcher
         assertThat( values.get( 0 ), matcher );
     }
 
+    /**
+     * Bookmark contains values matching the requirement set by matcher.
+     */
+    public static void assertBookmarkContainsValues( Bookmark bookmark, Matcher<Iterable<String>> matcher )
+    {
+        assertNotNull( bookmark );
+        assertThat( bookmark, instanceOf( InternalBookmark.class ) );
+
+        List<String> values = asList( ((InternalBookmark) bookmark).values() );
+        assertThat( values, matcher );
+    }
+
     /**
      * Each bookmark contains one single value and the values are all different from each other.
      */

driver/src/test/java/org/neo4j/driver/internal/util/MetadataExtractorTest.java

@@ -30,7 +30,7 @@
 import org.neo4j.driver.exceptions.UntrustedServerException;
 import org.neo4j.driver.exceptions.value.Uncoercible;
 import org.neo4j.driver.internal.BoltServerAddress;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.InternalBookmark;
 import org.neo4j.driver.internal.spi.Connection;
 import org.neo4j.driver.internal.summary.InternalInputPosition;

driver/src/test/java/org/neo4j/driver/stress/AbstractContext.java

@@ -21,7 +21,7 @@
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicLong;
 
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.summary.ResultSummary;
 
 public abstract class AbstractContext

driver/src/test/java/org/neo4j/driver/stress/AbstractStressTestBase.java

@@ -63,7 +63,7 @@
 import org.neo4j.driver.async.AsyncSession;
 import org.neo4j.driver.async.AsyncTransaction;
 import org.neo4j.driver.async.StatementResultCursor;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.InternalDriver;
 import org.neo4j.driver.internal.logging.DevNullLogger;
 import org.neo4j.driver.internal.util.EnabledOnNeo4jWith;

driver/src/test/java/org/neo4j/driver/stress/CausalClusteringIT.java

@@ -59,7 +59,7 @@
 import org.neo4j.driver.exceptions.SessionExpiredException;
 import org.neo4j.driver.integration.NestedQueries;
 import org.neo4j.driver.internal.BoltServerAddress;
-import org.neo4j.driver.internal.Bookmark;
+import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.internal.cluster.RoutingSettings;
 import org.neo4j.driver.internal.retry.RetrySettings;
 import org.neo4j.driver.internal.util.DisabledOnNeo4jWith;