Added javadocs to new classes

community/lucene-index/src/main/java/org/neo4j/kernel/api/impl/index/AbstractLuceneIndex.java

@@ -45,10 +45,17 @@
 
 import static java.util.stream.Collectors.toList;
 
+/**
+ * Abstract implementation of a partitioned index.
+ * Such index may consist of one or multiple separate Lucene indexes that are represented as independent
+ * {@link IndexPartition partitions}.
+ */
 public abstract class AbstractLuceneIndex implements Closeable
 {
+    // lock used to guard commits and close of lucene indexes from separate threads
     protected final ReentrantLock commitCloseLock = new ReentrantLock();
-    protected final ReentrantLock readWriteLock = new ReentrantLock();
+    // lock guard concurrent creation of new partitions
+    protected final ReentrantLock partitionsLock = new ReentrantLock();
 
     protected final PartitionedIndexStorage indexStorage;
     private List<IndexPartition> partitions = new CopyOnWriteArrayList<>();
@@ -63,8 +70,9 @@ public AbstractLuceneIndex( PartitionedIndexStorage indexStorage )
      * Creates new index.
      * As part of creation process index will allocate all required folders, index failure storage
      * and will create its first partition.
-     * <p></p>
+     * <p>
      * <b>Index creation do not automatically open it. To be able to use index please open it first.</b>
+     *
      * @throws IOException
      */
     public void create() throws IOException
@@ -77,6 +85,7 @@ public void create() throws IOException
 
     /**
      * Open index with all allocated partitions.
+     *
      * @throws IOException
      */
     public void open() throws IOException
@@ -96,6 +105,7 @@ boolean isOpen()
 
     /**
      * Check lucene index existence within all allocated partitions.
+     *
      * @return true if index exist in all partitions, false when index is empty or does not exist
      * @throws IOException
      */
@@ -120,6 +130,7 @@ public boolean exists() throws IOException
      * Verify state of the index.
      * If index is already open and in use method assume that index is valid since lucene already operating with it,
      * otherwise necessary checks perform.
+     *
      * @return true if lucene confirm that index is in valid clean state or index is already open.
      */
     public boolean isValid()
@@ -160,12 +171,22 @@ public boolean isValid()
         return true;
     }
 
+    /**
+     * Close index and deletes all it's partitions.
+     *
+     * @throws IOException
+     */
     public void drop() throws IOException
     {
         close();
         indexStorage.cleanupFolder( indexStorage.getIndexFolder() );
     }
 
+    /**
+     * Commits all index partitions.
+     *
+     * @throws IOException
+     */
     public void flush() throws IOException
     {
         commitCloseLock.lock();
@@ -199,10 +220,15 @@ public void close() throws IOException
         }
     }
 
+    /**
+     * Creates an iterable over all {@link org.apache.lucene.document.Document document}s in all partitions.
+     *
+     * @return LuceneAllDocumentsReader over all documents
+     */
     public LuceneAllDocumentsReader allDocumentsReader()
     {
         ensureOpen();
-        readWriteLock.lock();
+        partitionsLock.lock();
         try
         {
             List<PartitionSearcher> searchers = new ArrayList<>( partitions.size() );
@@ -227,10 +253,17 @@ public LuceneAllDocumentsReader allDocumentsReader()
         }
         finally
         {
-            readWriteLock.unlock();
+            partitionsLock.unlock();
         }
     }
 
+    /**
+     * Snapshot of all file in all index partitions.
+     *
+     * @return iterator over all index files.
+     * @throws IOException
+     * @see org.neo4j.kernel.api.impl.index.backup.LuceneIndexSnapshotFileIterator
+     */
     public ResourceIterator<File> snapshot() throws IOException
     {
         ensureOpen();
@@ -267,9 +300,14 @@ public ResourceIterator<File> snapshot() throws IOException
         }
     }
 
+    /**
+     * Refresh all partitions to make newly inserted data visible for readers.
+     *
+     * @throws IOException
+     */
     public void maybeRefreshBlocking() throws IOException
     {
-        readWriteLock.lock();
+        partitionsLock.lock();
         try
         {
             for ( IndexPartition partition : getPartitions() )
@@ -279,7 +317,7 @@ public void maybeRefreshBlocking() throws IOException
         }
         finally
         {
-            readWriteLock.unlock();
+            partitionsLock.unlock();
         }
     }
 
@@ -289,10 +327,16 @@ List<IndexPartition> getPartitions()
         return partitions;
     }
 
+    /**
+     * Add new partition to the index.
+     *
+     * @return newly created partition
+     * @throws IOException
+     */
     IndexPartition addNewPartition() throws IOException
     {
         ensureOpen();
-        readWriteLock.lock();
+        partitionsLock.lock();
         try
         {
             File partitionFolder = createNewPartitionFolder();
@@ -303,7 +347,7 @@ IndexPartition addNewPartition() throws IOException
         }
         finally
         {
-            readWriteLock.unlock();
+            partitionsLock.unlock();
         }
     }
 

community/lucene-index/src/main/java/org/neo4j/kernel/api/impl/index/IndexWriterConfigs.java

@@ -26,6 +26,9 @@
 import org.neo4j.index.impl.lucene.legacy.MultipleBackupDeletionPolicy;
 import org.neo4j.unsafe.impl.internal.dragons.FeatureToggles;
 
+/**
+ * Helper factory for standard lucene index writer configuration.
+ */
 public final class IndexWriterConfigs
 {
     private static final int MAX_BUFFERED_DOCS =
@@ -46,11 +49,10 @@ public static IndexWriterConfig standardConfig()
     {
         IndexWriterConfig writerConfig = new IndexWriterConfig( LuceneDataSource.KEYWORD_ANALYZER );
 
-        writerConfig.setMaxBufferedDocs( MAX_BUFFERED_DOCS ); // TODO figure out depending on environment?
+        writerConfig.setMaxBufferedDocs( MAX_BUFFERED_DOCS );
         writerConfig.setIndexDeletionPolicy( new MultipleBackupDeletionPolicy() );
         writerConfig.setUseCompoundFile( true );
 
-        // TODO: TieredMergePolicy & possibly SortingMergePolicy
         LogByteSizeMergePolicy mergePolicy = new LogByteSizeMergePolicy();
         mergePolicy.setNoCFSRatio( MERGE_POLICY_NO_CFS_RATIO );
         mergePolicy.setMinMergeMB( MERGE_POLICY_MIN_MERGE_MB );

community/lucene-index/src/main/java/org/neo4j/kernel/api/impl/index/LuceneDocumentRetrievalException.java

@@ -32,13 +32,13 @@ public class LuceneDocumentRetrievalException extends RuntimeException
 
     public LuceneDocumentRetrievalException( String message, long documentId, Throwable cause )
     {
-        this(message, cause);
+        this( message, cause );
         this.documentId = documentId;
     }
 
     public LuceneDocumentRetrievalException( String message, Throwable cause )
     {
-        super(message, cause);
+        super( message, cause );
     }
 
     public long getDocumentId()

community/lucene-index/src/main/java/org/neo4j/kernel/api/impl/index/LuceneIndexAccessor.java

@@ -93,7 +93,7 @@ public IndexReader newReader()
         }
         catch ( IOException e )
         {
-            throw new LuceneIndexAcquisitionException("Can't acquire index reader");
+            throw new LuceneIndexReaderAcquisitionException( "Can't acquire index reader", e );
         }
     }
 

community/lucene-index/src/main/java/org/neo4j/kernel/api/impl/index/LuceneIndexAcquisitionException.java → community/lucene-index/src/main/java/org/neo4j/kernel/api/impl/index/LuceneIndexReaderAcquisitionException.java

@@ -19,15 +19,17 @@
  */
 package org.neo4j.kernel.api.impl.index;
 
+import java.io.IOException;
+
 /**
  * Exception that will be thrown in case if encounter IOException during Lucene reader acquisition.
  *
  * @see org.apache.lucene.search.IndexSearcher
  */
-public class LuceneIndexAcquisitionException extends RuntimeException
+public class LuceneIndexReaderAcquisitionException extends RuntimeException
 {
-    public LuceneIndexAcquisitionException( String message )
+    public LuceneIndexReaderAcquisitionException( String message, IOException e )
     {
-        super( message );
+        super( message, e );
     }
 }

community/lucene-index/src/main/java/org/neo4j/kernel/api/impl/index/LuceneLabelScanIndex.java

@@ -32,6 +32,12 @@
 import org.neo4j.kernel.api.labelscan.NodeLabelRange;
 import org.neo4j.storageengine.api.schema.LabelScanReader;
 
+/**
+ * Implementation of Lucene label scan store index that support multiple partitions.
+ * <p>
+ * Each partition stores {@link org.apache.lucene.document.Document documents} according to the given
+ * {@link BitmapDocumentFormat} and {@link LabelScanStorageStrategy}.
+ */
 public class LuceneLabelScanIndex extends AbstractLuceneIndex
 {
     private final BitmapDocumentFormat format;
@@ -44,10 +50,11 @@ public LuceneLabelScanIndex( BitmapDocumentFormat format, PartitionedIndexStorag
         this.storageStrategy = new NodeRangeDocumentLabelScanStorageStrategy( format );
     }
 
+
     public LabelScanReader getLabelScanReader()
     {
         ensureOpen();
-        readWriteLock.lock();
+        partitionsLock.lock();
         try
         {
             List<IndexPartition> partitions = getPartitions();
@@ -63,7 +70,7 @@ public LabelScanReader getLabelScanReader()
         }
         finally
         {
-            readWriteLock.unlock();
+            partitionsLock.unlock();
         }
     }
 

community/lucene-index/src/main/java/org/neo4j/kernel/api/impl/index/LucenePartitionAllDocumentsReader.java

@@ -34,6 +34,9 @@
 import org.neo4j.helpers.collection.PrefetchingIterator;
 import org.neo4j.kernel.api.impl.index.partition.PartitionSearcher;
 
+/**
+ * Provides a view of all {@link Document}s in a single partition.
+ */
 public class LucenePartitionAllDocumentsReader implements BoundedIterable<Document>
 {
     private final PartitionSearcher partitionSearcher;