Avoid changing the db.awaitIndex and db.resampleIndex behaviours,…

… and instead add a new `db.index.fulltext.awaitIndex` procedure for awaiting indexes by name.

The reason for this is that fears were expressed about the change to the `db.awaitIndex` procedure being an incompatible change.

community/community-it/index-it/src/test/java/org/neo4j/kernel/api/impl/fulltext/FulltextProceduresTest.java

@@ -100,7 +100,7 @@ public class FulltextProceduresTest
     private static final String DB_INDEXES = "CALL db.indexes";
     private static final String DROP = "CALL db.index.fulltext.drop(\"%s\")";
     private static final String LIST_AVAILABLE_ANALYZERS = "CALL db.index.fulltext.listAvailableAnalyzers()";
-    private static final String DB_AWAIT_INDEX = "CALL db.awaitIndex(\"%s\")";
+    private static final String DB_AWAIT_INDEX = "CALL db.index.fulltext.awaitIndex(\"%s\")";
     static final String QUERY_NODES = "CALL db.index.fulltext.queryNodes(\"%s\", \"%s\")";
     static final String QUERY_RELS = "CALL db.index.fulltext.queryRelationships(\"%s\", \"%s\")";
     static final String AWAIT_REFRESH = "CALL db.index.fulltext.awaitEventuallyConsistentIndexRefresh()";

community/community-it/kernel-it/src/test/java/org/neo4j/kernel/impl/api/integrationtest/BuiltInProceduresIT.java

@@ -137,13 +137,11 @@ public void listProcedures() throws Throwable
                                 "failureMessage :: STRING?)",
                         "List all indexes in the database.", "READ" ),
                 proc( "db.awaitIndex", "(index :: STRING?, timeOutSeconds = 300 :: INTEGER?) :: VOID",
-                        "Wait for an index to come online (for example: CALL db.awaitIndex(\":Person(name)\"), " +
-                                "or CALL db.awaitIndex(\"index_name\")).", "READ" ),
+                        "Wait for an index to come online (for example: CALL db.awaitIndex(\":Person(name)\")).", "READ" ),
                 proc( "db.awaitIndexes", "(timeOutSeconds = 300 :: INTEGER?) :: VOID",
                         "Wait for all indexes to come online (for example: CALL db.awaitIndexes(\"500\")).", "READ" ),
                 proc( "db.resampleIndex", "(index :: STRING?) :: VOID",
-                        "Schedule resampling of an index (for example: CALL db.resampleIndex(\":Person(name)\"), " +
-                                "or CALL db.resampleIndex(\"index_name\")).", "READ" ),
+                        "Schedule resampling of an index (for example: CALL db.resampleIndex(\":Person(name)\")).", "READ" ),
                 proc( "db.resampleOutdatedIndexes", "() :: VOID", "Schedule resampling of all outdated indexes.", "READ" ),
                 proc( "db.propertyKeys", "() :: (propertyKey :: STRING?)", "List all property keys in the database.", "READ" ),
                 proc( "db.labels", "() :: (label :: STRING?)", "List all labels in the database.", "READ" ),
@@ -229,6 +227,9 @@ public void listProcedures() throws Throwable
                                 "YIELD index, providerName, status", "SCHEMA" ),
                 proc( "db.index.fulltext.awaitEventuallyConsistentIndexRefresh", "() :: VOID",
                         "Wait for the updates from recently committed transactions to be applied to any eventually-consistent fulltext indexes.", "READ" ),
+                proc( "db.index.fulltext.awaitIndex", "(index :: STRING?, timeOutSeconds = 300 :: INTEGER?) :: VOID",
+                        "Similar to db.awaitIndex(index, timeout), except instead of an index pattern, the index is specified by name. " +
+                                "The name can be quoted by backticks, if necessary.", "READ" ),
                 proc( "db.index.fulltext.createNodeIndex", "(indexName :: STRING?, labels :: LIST? OF STRING?, propertyNames :: LIST? OF STRING?, " +
                         "config = {} :: MAP?) :: VOID", startsWith( "Create a node fulltext index for the given labels and properties." ), "SCHEMA" ),
                 proc( "db.index.fulltext.createRelationshipIndex",

community/fulltext-index/src/main/java/org/neo4j/kernel/api/impl/fulltext/FulltextProcedures.java

@@ -31,6 +31,7 @@
 import java.util.concurrent.TimeUnit;
 import java.util.stream.Stream;
 
+import org.neo4j.graphdb.DependencyResolver;
 import org.neo4j.graphdb.GraphDatabaseService;
 import org.neo4j.graphdb.Node;
 import org.neo4j.graphdb.NotFoundException;
@@ -39,11 +40,14 @@
 import org.neo4j.graphdb.schema.Schema;
 import org.neo4j.internal.kernel.api.IndexReference;
 import org.neo4j.internal.kernel.api.exceptions.InvalidTransactionTypeKernelException;
+import org.neo4j.internal.kernel.api.exceptions.ProcedureException;
 import org.neo4j.internal.kernel.api.exceptions.schema.IndexNotFoundKernelException;
 import org.neo4j.internal.kernel.api.exceptions.schema.SchemaKernelException;
 import org.neo4j.internal.kernel.api.schema.SchemaDescriptor;
 import org.neo4j.kernel.api.KernelTransaction;
+import org.neo4j.kernel.builtinprocs.IndexProcedures;
 import org.neo4j.kernel.impl.api.KernelTransactionImplementation;
+import org.neo4j.kernel.impl.api.index.IndexingService;
 import org.neo4j.procedure.Context;
 import org.neo4j.procedure.Description;
 import org.neo4j.procedure.Name;
@@ -73,6 +77,9 @@ public class FulltextProcedures
     @Context
     public GraphDatabaseService db;
 
+    @Context
+    public DependencyResolver resolver;
+
     @Context
     public FulltextAdapter accessor;
 
@@ -90,6 +97,22 @@ public void awaitRefresh()
         accessor.awaitRefresh();
     }
 
+    @Description( "Similar to db.awaitIndex(index, timeout), except instead of an index pattern, the index is specified by name. " +
+            "The name can be quoted by backticks, if necessary." )
+    @Procedure( name = "db.index.fulltext.awaitIndex", mode = READ )
+    public void awaitIndex( @Name( "index" ) String index, @Name( value = "timeOutSeconds", defaultValue = "300" ) long timeout ) throws ProcedureException
+    {
+        try ( IndexProcedures indexProcedures = indexProcedures() )
+        {
+            indexProcedures.awaitIndexByName( index, timeout, TimeUnit.SECONDS );
+        }
+    }
+
+    private IndexProcedures indexProcedures()
+    {
+        return new IndexProcedures( tx, resolver.resolveDependency( IndexingService.class ) );
+    }
+
     @Description( "Create a node fulltext index for the given labels and properties. " +
                   "The optional 'config' map parameter can be used to supply settings to the index. " +
                   "Note: index specific settings are currently experimental, and might not replicated correctly in a cluster, or during backup. " +

community/kernel/src/main/java/org/neo4j/kernel/builtinprocs/BuiltInProcedures.java

@@ -169,15 +169,15 @@ public Stream<IndexResult> listIndexes() throws ProcedureException
         }
     }
 
-    @Description( "Wait for an index to come online (for example: CALL db.awaitIndex(\":Person(name)\"), or CALL db.awaitIndex(\"index_name\"))." )
+    @Description( "Wait for an index to come online (for example: CALL db.awaitIndex(\":Person(name)\"))." )
     @Procedure( name = "db.awaitIndex", mode = READ )
     public void awaitIndex( @Name( "index" ) String index,
             @Name( value = "timeOutSeconds", defaultValue = "300" ) long timeout )
             throws ProcedureException
     {
         try ( IndexProcedures indexProcedures = indexProcedures() )
         {
-            indexProcedures.awaitIndex( index, timeout, TimeUnit.SECONDS );
+            indexProcedures.awaitIndexByPattern( index, timeout, TimeUnit.SECONDS );
         }
     }
 
@@ -188,7 +188,7 @@ public void awaitIndexes( @Name( value = "timeOutSeconds", defaultValue = "300"
         graphDatabaseAPI.schema().awaitIndexesOnline( timeout, TimeUnit.SECONDS );
     }
 
-    @Description( "Schedule resampling of an index (for example: CALL db.resampleIndex(\":Person(name)\"), or CALL db.resampleIndex(\"index_name\"))." )
+    @Description( "Schedule resampling of an index (for example: CALL db.resampleIndex(\":Person(name)\"))." )
     @Procedure( name = "db.resampleIndex", mode = READ )
     public void resampleIndex( @Name( "index" ) String index ) throws ProcedureException
     {

community/kernel/src/main/java/org/neo4j/kernel/builtinprocs/IndexProcedures.java

@@ -57,16 +57,23 @@ public IndexProcedures( KernelTransaction tx, IndexingService indexingService )
         this.indexingService = indexingService;
     }
 
-    public void awaitIndex( String indexSpecification, long timeout, TimeUnit timeoutUnits )
+    public void awaitIndexByPattern( String indexPattern, long timeout, TimeUnit timeoutUnits )
             throws ProcedureException
     {
-        IndexSpecifier specifier = IndexSpecifier.patternOrName( indexSpecification );
+        IndexSpecifier specifier = IndexSpecifier.byPattern( indexPattern );
+        waitUntilOnline( getIndex( specifier ), specifier, timeout, timeoutUnits );
+    }
+
+    public void awaitIndexByName( String indexName, long timeout, TimeUnit timeoutUnits )
+            throws ProcedureException
+    {
+        IndexSpecifier specifier = IndexSpecifier.byName( indexName );
         waitUntilOnline( getIndex( specifier ), specifier, timeout, timeoutUnits );
     }
 
     public void resampleIndex( String indexSpecification ) throws ProcedureException
     {
-        IndexSpecifier specifier = IndexSpecifier.patternOrName( indexSpecification );
+        IndexSpecifier specifier = IndexSpecifier.byPattern( indexSpecification );
         try
         {
             triggerSampling( getIndex( specifier ) );
@@ -102,7 +109,7 @@ private Stream<BuiltInProcedures.SchemaIndexInfo> createIndex( String indexSpeci
             IndexCreator indexCreator ) throws ProcedureException
     {
         assertProviderNameNotNull( providerName );
-        IndexSpecifier index = IndexSpecifier.pattern( indexSpecification );
+        IndexSpecifier index = IndexSpecifier.byPattern( indexSpecification );
         int labelId = getOrCreateLabelId( index.label() );
         int[] propertyKeyIds = getOrCreatePropertyIds( index.properties() );
         try

community/kernel/src/main/java/org/neo4j/kernel/builtinprocs/IndexSpecifier.java

@@ -59,17 +59,22 @@ public class IndexSpecifier
     private final String[] properties;
     private final String name;
 
-    public static IndexSpecifier patternOrName( String specification )
+    public static IndexSpecifier byPatternOrName( String specification )
     {
-        return parse( specification, true );
+        return parse( specification, true, true );
     }
 
-    public static IndexSpecifier pattern( String specification )
+    public static IndexSpecifier byPattern( String specification )
     {
-        return parse( specification, false );
+        return parse( specification, false, true );
     }
 
-    private static IndexSpecifier parse( String specification, boolean allowIndexNameSpecs )
+    public static IndexSpecifier byName( String specification )
+    {
+        return parse( specification, true, false );
+    }
+
+    private static IndexSpecifier parse( String specification, boolean allowIndexNameSpecs, boolean allowIndexPatternSpecs )
     {
         Matcher matcher = PATTERN_START_INDEX_NAME_OR_LABEL.matcher( specification );
         if ( !matcher.find() )
@@ -93,6 +98,12 @@ private static IndexSpecifier parse( String specification, boolean allowIndexNam
             throw new IllegalArgumentException( "Invalid characters following index name: '" + specification + "'" );
         }
 
+        if ( !allowIndexPatternSpecs )
+        {
+            throw new IllegalArgumentException( "Cannot parse index specification: '" + specification +
+                    "' - it looks like an index pattern, but an index name was expected." );
+        }
+
         String label = either( matcher.group( GROUP_LABEL ), matcher.group( GROUP_QUOTED_LABEL ) );
         if ( label == null )
         {

community/kernel/src/test/java/org/neo4j/kernel/builtinprocs/AwaitIndexProcedureTest.java

@@ -89,7 +89,7 @@ public void shouldThrowAnExceptionIfTheLabelDoesntExist()
 
         try
         {
-            procedure.awaitIndex( ":NonExistentLabel(prop)", TIMEOUT, TIME_UNIT );
+            procedure.awaitIndexByPattern( ":NonExistentLabel(prop)", TIMEOUT, TIME_UNIT );
             fail( "Expected an exception" );
         }
         catch ( ProcedureException e )
@@ -105,7 +105,7 @@ public void shouldThrowAnExceptionIfThePropertyKeyDoesntExist()
 
         try
         {
-            procedure.awaitIndex( ":Label(nonExistentProperty)", TIMEOUT, TIME_UNIT );
+            procedure.awaitIndexByPattern( ":Label(nonExistentProperty)", TIMEOUT, TIME_UNIT );
             fail( "Expected an exception" );
         }
         catch ( ProcedureException e )
@@ -122,7 +122,7 @@ public void shouldLookUpTheIndexByLabelIdAndPropertyKeyId() throws ProcedureExce
         when( schemaRead.index( anyInt(), any() ) ).thenReturn( anyIndex );
         when( schemaRead.indexGetState( any( IndexReference.class ) ) ).thenReturn( ONLINE );
 
-        procedure.awaitIndex( ":Person(name)", TIMEOUT, TIME_UNIT );
+        procedure.awaitIndexByPattern( ":Person(name)", TIMEOUT, TIME_UNIT );
 
         verify( schemaRead ).index( descriptor.getLabelId(), descriptor.getPropertyId() );
     }
@@ -135,7 +135,7 @@ public void shouldLookUpTheIndexByIndexName() throws ProcedureException, IndexNo
         when( schemaRead.indexGetForName( "my index" ) ).thenReturn( anyIndex );
         when( schemaRead.indexGetState( any( IndexReference.class ) ) ).thenReturn( ONLINE );
 
-        procedure.awaitIndex( "`my index`", TIMEOUT, TIME_UNIT );
+        procedure.awaitIndexByName( "`my index`", TIMEOUT, TIME_UNIT );
 
         verify( schemaRead ).indexGetForName( "my index" );
     }
@@ -151,7 +151,7 @@ public void shouldThrowAnExceptionIfTheIndexHasFailed() throws IndexNotFoundKern
 
         try
         {
-            procedure.awaitIndex( ":Person(name)", TIMEOUT, TIME_UNIT );
+            procedure.awaitIndexByPattern( ":Person(name)", TIMEOUT, TIME_UNIT );
             fail( "Expected an exception" );
         }
         catch ( ProcedureException e )
@@ -170,7 +170,7 @@ public void shouldThrowAnExceptionIfTheIndexDoesNotExist()
 
         try
         {
-            procedure.awaitIndex( ":Person(name)", TIMEOUT, TIME_UNIT );
+            procedure.awaitIndexByPattern( ":Person(name)", TIMEOUT, TIME_UNIT );
             fail( "Expected an exception" );
         }
         catch ( ProcedureException e )
@@ -179,6 +179,12 @@ public void shouldThrowAnExceptionIfTheIndexDoesNotExist()
         }
     }
 
+    @Test( expected = IllegalArgumentException.class )
+    public void shouldThrowAnExceptionIfGivenAnIndexName() throws ProcedureException
+    {
+        procedure.awaitIndexByPattern( "`some index`", TIMEOUT, TIME_UNIT );
+    }
+
     @Test
     public void shouldThrowAnExceptionIfTheIndexWithGivenNameDoesNotExist()
     {
@@ -188,7 +194,7 @@ public void shouldThrowAnExceptionIfTheIndexWithGivenNameDoesNotExist()
 
         try
         {
-            procedure.awaitIndex( "`some index`", TIMEOUT, TIME_UNIT );
+            procedure.awaitIndexByName( "`some index`", TIMEOUT, TIME_UNIT );
             fail( "Expected an exception" );
         }
         catch ( ProcedureException e )
@@ -212,7 +218,7 @@ public void shouldBlockUntilTheIndexIsOnline() throws IndexNotFoundKernelExcepti
         {
             try
             {
-                procedure.awaitIndex( ":Person(name)", TIMEOUT, TIME_UNIT );
+                procedure.awaitIndexByPattern( ":Person(name)", TIMEOUT, TIME_UNIT );
             }
             catch ( ProcedureException e )
             {
@@ -242,7 +248,7 @@ public void shouldTimeoutIfTheIndexTakesTooLongToComeOnline() throws Interrupted
             try
             {
                 // We wait here, because we expect timeout
-                procedure.awaitIndex( ":Person(name)", 0, TIME_UNIT );
+                procedure.awaitIndexByPattern( ":Person(name)", 0, TIME_UNIT );
             }
             catch ( ProcedureException e )
             {

community/kernel/src/test/java/org/neo4j/kernel/builtinprocs/BuiltInProceduresTest.java

@@ -265,8 +265,7 @@ public void shouldListCorrectBuiltinProcedures() throws Throwable
                         "dbms.listConfig(searchString =  :: STRING?) :: (name :: STRING?, description :: STRING?, value :: STRING?, dynamic :: BOOLEAN?)",
                         "List the currently active config of Neo4j.", "DBMS" ),
                 record( "db.awaitIndex", "db.awaitIndex(index :: STRING?, timeOutSeconds = 300 :: INTEGER?) :: VOID",
-                        "Wait for an index to come online (for example: CALL db.awaitIndex(\":Person(name)\"), " +
-                                "or CALL db.awaitIndex(\"index_name\")).", "READ" ),
+                        "Wait for an index to come online (for example: CALL db.awaitIndex(\":Person(name)\")).", "READ" ),
                 record( "db.awaitIndexes", "db.awaitIndexes(timeOutSeconds = 300 :: INTEGER?) :: VOID",
                         "Wait for all indexes to come online (for example: CALL db.awaitIndexes(\"500\")).", "READ" ),
                 record( "db.constraints", "db.constraints() :: (description :: STRING?)",
@@ -281,8 +280,7 @@ public void shouldListCorrectBuiltinProcedures() throws Throwable
                 record( "db.relationshipTypes", "db.relationshipTypes() :: (relationshipType :: STRING?)",
                         "List all relationship types in the database.", "READ" ),
                 record( "db.resampleIndex", "db.resampleIndex(index :: STRING?) :: VOID",
-                        "Schedule resampling of an index (for example: CALL db.resampleIndex(\":Person(name)\"), " +
-                                "or CALL db.resampleIndex(\"index_name\")).", "READ" ),
+                        "Schedule resampling of an index (for example: CALL db.resampleIndex(\":Person(name)\")).", "READ" ),
                 record( "db.resampleOutdatedIndexes", "db.resampleOutdatedIndexes() :: VOID",
                         "Schedule resampling of all outdated indexes.", "READ" ),
                 record( "db.schema",