Deprecate remnants of two-phase visiting APIs and usage

This has not been relevant since "orderdoc" was a thing, and it
was never really a thing in the first place.

Unfortunately, due to an oversight in how the backend propagates visitor
statistics, the internal usage of 2nd pass statistics cannot be fully
removed before Vespa 8 (where the backend is known to not set the
deprecated statistics fields).

7 files changed, 57 insertions, 8 deletions

diff --git a/documentapi/src/main/java/com/yahoo/documentapi/VisitorParameters.java b/documentapi/src/main/java/com/yahoo/documentapi/VisitorParameters.java
index 44675d8d2ac..605bb95ba24 100644
--- a/documentapi/src/main/java/com/yahoo/documentapi/VisitorParameters.java
+++ b/documentapi/src/main/java/com/yahoo/documentapi/VisitorParameters.java
@@ -286,10 +286,18 @@ public class VisitorParameters extends Parameters {
     // TODO: Document: Where is the default - does this ever return null, or does it return "storage" if input is null?
     public Route getRoute() { return visitRoute; }
 
-    /** Set the maximum number of documents to visit (max documents returned by the visitor) */
+    /** Set the maximum number of documents to visit (max documents returned by the visitor)
+     *
+     * @deprecated use setMaxTotalHits instead
+     */
+    @Deprecated(since = "7", forRemoval = true) // TODO: Vespa 8: remove
     public void setMaxFirstPassHits(long max) { maxFirstPassHits = max; }
 
-    /** @return Returns the maximum number of documents to visit (max documents returned by the visitor) */
+    /** @return Returns the maximum number of documents to visit (max documents returned by the visitor)
+     *
+     * @deprecated Use getMaxTotalHits() instead
+     */
+    @Deprecated(since = "7", forRemoval = true) // TODO: Vespa 8: remove
     public long getMaxFirstPassHits() { return maxFirstPassHits; }
 
     /** Set the maximum number of documents to visit (max documents returned by the visitor) */
@@ -349,7 +357,10 @@ public class VisitorParameters extends Parameters {
      * the desired amount of documents
      *
      * @param dynamicallyIncreaseMaxBucketsPerVisitor whether or not to increase
+     *
+     * @deprecated deprecated feature, will be removed on Vespa 8
      */
+    @Deprecated(since = "7", forRemoval = true) // TODO: Vespa 8: remove
     public void setDynamicallyIncreaseMaxBucketsPerVisitor(boolean dynamicallyIncreaseMaxBucketsPerVisitor) {
         this.dynamicallyIncreaseMaxBucketsPerVisitor = dynamicallyIncreaseMaxBucketsPerVisitor;
     }
diff --git a/documentapi/src/main/java/com/yahoo/documentapi/messagebus/MessageBusVisitorSession.java b/documentapi/src/main/java/com/yahoo/documentapi/messagebus/MessageBusVisitorSession.java
index e99028684c7..1c473a196f3 100755
--- a/documentapi/src/main/java/com/yahoo/documentapi/messagebus/MessageBusVisitorSession.java
+++ b/documentapi/src/main/java/com/yahoo/documentapi/messagebus/MessageBusVisitorSession.java
@@ -933,7 +933,9 @@ public class MessageBusVisitorSession implements VisitorSession {
         progress.getIterator().update(bucket, ProgressToken.FINISHED_BUCKET);
     }
 
+    @SuppressWarnings("removal") // TODO: Vespa 8: remove
     private boolean enoughHitsReceived() {
+        // TODO: Vespa 8: remove "Nth pass" concept entirely from API and internals
         if (params.getMaxFirstPassHits() != -1
                 && statistics.getDocumentsReturned() >= params.getMaxFirstPassHits())
         {
@@ -941,7 +943,7 @@ public class MessageBusVisitorSession implements VisitorSession {
         }
         if (params.getMaxTotalHits() != -1
                 && ((statistics.getDocumentsReturned()
-                     + statistics.getSecondPassDocumentsReturned())
+                     + statistics.getSecondPassDocumentsReturned()) // TODO: Vespa 8: remove
                     >= params.getMaxTotalHits()))
         {
             return true;
@@ -1021,6 +1023,7 @@ public class MessageBusVisitorSession implements VisitorSession {
         return scheduleSendCreateVisitorsIfApplicable(0, TimeUnit.MILLISECONDS);
     }
 
+    @SuppressWarnings("removal")// TODO: Vespa 8: remove
     private void handleCreateVisitorReply(CreateVisitorReply reply) {
         CreateVisitorMessage msg = (CreateVisitorMessage)reply.getMessage();
 
@@ -1040,6 +1043,7 @@ public class MessageBusVisitorSession implements VisitorSession {
             trace.getRoot().addChild(reply.getTrace().getRoot());
         }
 
+        // TODO: Vespa 8 remove this unused functionality
         if (params.getDynamicallyIncreaseMaxBucketsPerVisitor()
                 && (reply.getVisitorStatistics().getDocumentsReturned()
                     < params.getMaxFirstPassHits() / 2.0))
diff --git a/documentapi/src/main/java/com/yahoo/documentapi/messagebus/protocol/RoutableFactories60.java b/documentapi/src/main/java/com/yahoo/documentapi/messagebus/protocol/RoutableFactories60.java
index b6c87e0a27e..c022af0cf07 100644
--- a/documentapi/src/main/java/com/yahoo/documentapi/messagebus/protocol/RoutableFactories60.java
+++ b/documentapi/src/main/java/com/yahoo/documentapi/messagebus/protocol/RoutableFactories60.java
@@ -237,6 +237,7 @@ public abstract class RoutableFactories60 {
     public static class CreateVisitorReplyFactory extends DocumentReplyFactory {
 
         @Override
+        @SuppressWarnings("removal")// TODO: Vespa 8: remove
         protected DocumentReply doDecode(DocumentDeserializer buf) {
             CreateVisitorReply reply = new CreateVisitorReply(DocumentProtocol.REPLY_CREATEVISITOR);
             reply.setLastBucket(new BucketId(buf.getLong(null)));
@@ -247,13 +248,14 @@ public abstract class RoutableFactories60 {
             vs.setBytesVisited(buf.getLong(null));
             vs.setDocumentsReturned(buf.getLong(null));
             vs.setBytesReturned(buf.getLong(null));
-            vs.setSecondPassDocumentsReturned(buf.getLong(null));
-            vs.setSecondPassBytesReturned(buf.getLong(null));
+            vs.setSecondPassDocumentsReturned(buf.getLong(null)); // TODO: on Vespa 8 remove setter (_not_ getLong())
+            vs.setSecondPassBytesReturned(buf.getLong(null)); // TODO: on Vespa 8 remove setter (_not_ getLong())
             reply.setVisitorStatistics(vs);
             return reply;
         }
 
         @Override
+        @SuppressWarnings("removal")// TODO: Vespa 8: remove
         protected boolean doEncode(DocumentReply obj, DocumentSerializer buf) {
             CreateVisitorReply reply = (CreateVisitorReply)obj;
             buf.putLong(null, reply.getLastBucket().getRawId());
@@ -262,8 +264,8 @@ public abstract class RoutableFactories60 {
             buf.putLong(null, reply.getVisitorStatistics().getBytesVisited());
             buf.putLong(null, reply.getVisitorStatistics().getDocumentsReturned());
             buf.putLong(null, reply.getVisitorStatistics().getBytesReturned());
-            buf.putLong(null, reply.getVisitorStatistics().getSecondPassDocumentsReturned());
-            buf.putLong(null, reply.getVisitorStatistics().getSecondPassBytesReturned());
+            buf.putLong(null, reply.getVisitorStatistics().getSecondPassDocumentsReturned()); // TODO: on Vespa 8 remove getter (_not_ putLong())
+            buf.putLong(null, reply.getVisitorStatistics().getSecondPassBytesReturned()); // TODO: on Vespa 8 remove getter (_not_ putLong())
             return true;
         }
     }
diff --git a/documentapi/src/test/java/com/yahoo/documentapi/VisitorParametersTestCase.java b/documentapi/src/test/java/com/yahoo/documentapi/VisitorParametersTestCase.java
index 88e87a632d2..caed3867d99 100644
--- a/documentapi/src/test/java/com/yahoo/documentapi/VisitorParametersTestCase.java
+++ b/documentapi/src/test/java/com/yahoo/documentapi/VisitorParametersTestCase.java
@@ -10,6 +10,7 @@ import static org.junit.Assert.*;
 public class VisitorParametersTestCase {
     private LoadType loadType = new LoadType(3, "samnmax", DocumentProtocol.Priority.HIGH_3);
 
+    @SuppressWarnings("removal")// TODO: Vespa 8: remove
     private VisitorParameters createVisitorParameters() {
         VisitorParameters params = new VisitorParameters("");
         params.setDocumentSelection("id.user==5678");
@@ -42,6 +43,7 @@ public class VisitorParametersTestCase {
         return params;
     }
 
+    @SuppressWarnings("removal")// TODO: Vespa 8: remove
     @Test
     public void testCopyConstructor() {
         VisitorParameters params = createVisitorParameters();
diff --git a/documentapi/src/test/java/com/yahoo/documentapi/messagebus/protocol/test/Messages60TestCase.java b/documentapi/src/test/java/com/yahoo/documentapi/messagebus/protocol/test/Messages60TestCase.java
index 51fef9ac557..5250a6b1db7 100644
--- a/documentapi/src/test/java/com/yahoo/documentapi/messagebus/protocol/test/Messages60TestCase.java
+++ b/documentapi/src/test/java/com/yahoo/documentapi/messagebus/protocol/test/Messages60TestCase.java
@@ -274,6 +274,7 @@ public class Messages60TestCase extends MessagesTestBase {
     public class testCreateVisitorReply implements RunnableTest {
 
         @Override
+        @SuppressWarnings("removal")
         public void run() {
             CreateVisitorReply reply = new CreateVisitorReply(DocumentProtocol.REPLY_CREATEVISITOR);
             reply.setLastBucket(new BucketId(16, 123));
@@ -296,7 +297,7 @@ public class Messages60TestCase extends MessagesTestBase {
                 assertEquals(1024000, reply.getVisitorStatistics().getBytesVisited());
                 assertEquals(123, reply.getVisitorStatistics().getDocumentsReturned());
                 assertEquals(512000, reply.getVisitorStatistics().getBytesReturned());
-                assertEquals(456, reply.getVisitorStatistics().getSecondPassDocumentsReturned());
+                assertEquals(456, reply.getVisitorStatistics().getSecondPassDocumentsReturned()); // TODO remove on Vespa 8
                 assertEquals(789100, reply.getVisitorStatistics().getSecondPassBytesReturned());
             }
         }
diff --git a/documentapi/src/test/java/com/yahoo/documentapi/messagebus/test/MessageBusVisitorSessionTestCase.java b/documentapi/src/test/java/com/yahoo/documentapi/messagebus/test/MessageBusVisitorSessionTestCase.java
index f55e6433cd0..01c4383b16a 100755
--- a/documentapi/src/test/java/com/yahoo/documentapi/messagebus/test/MessageBusVisitorSessionTestCase.java
+++ b/documentapi/src/test/java/com/yahoo/documentapi/messagebus/test/MessageBusVisitorSessionTestCase.java
@@ -942,6 +942,7 @@ public class MessageBusVisitorSessionTestCase {
         }
 
         @Override
+        @SuppressWarnings("removal") // TODO: Vespa 8: remove
         public void onVisitorStatistics(VisitorStatistics vs) {
             super.onVisitorStatistics(vs);
             builder.append("onVisitorStatistics : ");
@@ -1411,6 +1412,7 @@ public class MessageBusVisitorSessionTestCase {
         doTestEarlyCompletion(visitorParameters, replyModifier1, replyModifier2);
     }
 
+    @SuppressWarnings("removal")// TODO: Vespa 8: remove
     @Test
     public void testVisitingCompletedFromSufficientFirstPassHits() {
         VisitorParameters visitorParameters = createVisitorParameters("id.user==1234");
@@ -1432,6 +1434,7 @@ public class MessageBusVisitorSessionTestCase {
         doTestEarlyCompletion(visitorParameters, replyModifier1, replyModifier2);
     }
 
+    @SuppressWarnings("removal")// TODO: Vespa 8: remove test
     @Test
     public void testVisitingCompletedFromSecondPassHits() {
         VisitorParameters visitorParameters = createVisitorParameters("id.user==1234");
@@ -2312,6 +2315,7 @@ public class MessageBusVisitorSessionTestCase {
                 mc.controlHandler.toString());
     }
 
+    @SuppressWarnings("removal")// TODO: Vespa 8: remove test
     @Test
     public void testDynamicallyIncreaseMaxBucketsPerVisitorOption() {
         VisitorParameters visitorParameters = createVisitorParameters("id.user==1234");
diff --git a/vdslib/src/main/java/com/yahoo/vdslib/VisitorStatistics.java b/vdslib/src/main/java/com/yahoo/vdslib/VisitorStatistics.java
index f3bf6f4ed38..a79f3d5fb6d 100644
--- a/vdslib/src/main/java/com/yahoo/vdslib/VisitorStatistics.java
+++ b/vdslib/src/main/java/com/yahoo/vdslib/VisitorStatistics.java
@@ -23,22 +23,47 @@ public class VisitorStatistics {
     public int getBucketsVisited() { return bucketsVisited; }
     public void setBucketsVisited(int bucketsVisited) { this.bucketsVisited = bucketsVisited; }
 
+    /**
+     * @return the number of documents matching the document selection in the backend and that
+     *   has been passed to the client-specified visitor instance (dumpvisitor, searchvisitor etc).
+     */
     public long getDocumentsVisited() { return documentsVisited; }
     public void setDocumentsVisited(long documentsVisited) { this.documentsVisited = documentsVisited; }
 
     public long getBytesVisited() { return bytesVisited; }
     public void setBytesVisited(long bytesVisited) { this.bytesVisited = bytesVisited; }
 
+    /**
+     * @return Number of documents returned to the visitor client by the backend. This number may
+     *   be lower than that returned by getDocumentsVisited() since the client-specified visitor
+     *   instance may further have filtered the set of documents returned by the backend.
+     */
     public long getDocumentsReturned() { return documentsReturned; }
     public void setDocumentsReturned(long documentsReturned) { this.documentsReturned = documentsReturned; }
 
     public long getBytesReturned() { return bytesReturned; }
     public void setBytesReturned(long bytesReturned) { this.bytesReturned = bytesReturned; }
 
+    /**
+     * @deprecated Use getDocumentsReturned() instead
+     */
+    @Deprecated(since = "7", forRemoval = true) // TODO: Vespa 8: remove
     public long getSecondPassDocumentsReturned() { return secondPassDocumentsReturned; }
+    /**
+     * @deprecated only applies for deprecated "orderdoc" ID scheme
+     */
+    @Deprecated(since = "7", forRemoval = true)// TODO: Vespa 8: remove
     public void setSecondPassDocumentsReturned(long secondPassDocumentsReturned) { this.secondPassDocumentsReturned = secondPassDocumentsReturned; }
 
+    /**
+     * @deprecated Use getBytesReturned() instead
+     */
+    @Deprecated(since = "7", forRemoval = true) // TODO: Vespa 8: remove
     public long getSecondPassBytesReturned() { return secondPassBytesReturned; }
+    /**
+     * @deprecated only applies for deprecated "orderdoc" ID scheme
+     */
+    @Deprecated(since = "7", forRemoval = true) // TODO: Vespa 8: remove
     public void setSecondPassBytesReturned(long secondPassBytesReturned) { this.secondPassBytesReturned = secondPassBytesReturned; }
 
     public String toString() {