unify the interface and exception handling of index

Author: bianhq

pixels-common/src/main/java/io/pixelsdb/pixels/common/index/IndexService.java

@@ -28,23 +28,25 @@ public interface IndexService
     /**
      * Allocate a batch of continuous row ids for the primary index on a table.
      * These row ids are to be put into the primary index by the client (e.g., retina or sink)
-     * @param tableId the table id of the table
+     *
+     * @param tableId   the table id of the table
      * @param numRowIds the number of row ids to allocate
      * @return the allocated row ids
+     * @throws IndexException if failed to allocate row ids
      */
-    IndexProto.RowIdBatch allocateRowIdBatch(long tableId, int numRowIds);
+    IndexProto.RowIdBatch allocateRowIdBatch(long tableId, int numRowIds) throws IndexException;
 
     /**
      * Lookup a unique index.
      * @param key the index key
-     * @return the row location or null if the index entry is not found.
+     * @return the row location or null if the index entry is not found
      */
     IndexProto.RowLocation lookupUniqueIndex(IndexProto.IndexKey key) throws IndexException;
 
     /**
      * Lookup a non-unique index.
      * @param key the index key
-     * @return the row locations or null if the index entry is not found.
+     * @return the row locations or null if the index entry is not found
      */
     List<IndexProto.RowLocation> lookupNonUniqueIndex(IndexProto.IndexKey key) throws IndexException;
 
@@ -86,13 +88,15 @@ boolean putSecondaryIndexEntries(long tableId, long indexId,
      * Delete an entry from the primary index. The deleted index entry is marked as deleted using a tombstone.
      * @param key the index key
      * @return the row location of the deleted index entry
+     * @throws IndexException if no existing entry to delete
      */
     IndexProto.RowLocation deletePrimaryIndexEntry(IndexProto.IndexKey key) throws IndexException;
 
     /**
      * Delete entry(ies) from the secondary index. Each deleted index entry is marked as deleted using a tombstone.
      * @param key the index key
      * @return the row id(s) of the deleted index entry(ies)
+     * @throws IndexException if no existing entry(ies) to delete
      */
     List<Long> deleteSecondaryIndexEntry(IndexProto.IndexKey key) throws IndexException;
 
@@ -102,6 +106,7 @@ boolean putSecondaryIndexEntries(long tableId, long indexId,
      * @param indexId the index id of the index
      * @param keys the keys of the entries to delete
      * @return the row locations of the deleted index entries
+     * @throws IndexException if no existing entry(ies) to delete
      */
     List<IndexProto.RowLocation> deletePrimaryIndexEntries(long tableId, long indexId,
                                                            List<IndexProto.IndexKey> keys) throws IndexException;
@@ -112,6 +117,7 @@ List<IndexProto.RowLocation> deletePrimaryIndexEntries(long tableId, long indexI
      * @param indexId the index id of the index
      * @param keys the keys of the entries to delete
      * @return the row ids of the deleted index entries
+     * @throws IndexException if no existing entry(ies) to delete
      */
     List<Long> deleteSecondaryIndexEntries(long tableId, long indexId,
                                            List<IndexProto.IndexKey> keys) throws IndexException;
@@ -120,13 +126,15 @@ List<Long> deleteSecondaryIndexEntries(long tableId, long indexId,
      * Update the entry of a primary index.
      * @param indexEntry the index entry to update
      * @return the previous row location of the index entry
+     * @throws IndexException if no existing entry to update
      */
     IndexProto.RowLocation updatePrimaryIndexEntry(IndexProto.PrimaryIndexEntry indexEntry) throws IndexException;
 
     /**
      * Update the entry of a secondary index.
      * @param indexEntry the index entry to update
      * @return the previous row id(s) of the index entry
+     * @throws IndexException if no existing entry(ies) to update
      */
     List<Long> updateSecondaryIndexEntry(IndexProto.SecondaryIndexEntry indexEntry) throws IndexException;
 
@@ -136,6 +144,7 @@ List<Long> deleteSecondaryIndexEntries(long tableId, long indexId,
      * @param indexId the index id of the primary index
      * @param indexEntries the index entries to update
      * @return the previous row locations of the index entries
+     * IndexException if no existing entry(ies) to update
      */
     List<IndexProto.RowLocation> updatePrimaryIndexEntries(long tableId, long indexId,
                                                            List<IndexProto.PrimaryIndexEntry> indexEntries) throws IndexException;
@@ -146,6 +155,7 @@ List<IndexProto.RowLocation> updatePrimaryIndexEntries(long tableId, long indexI
      * @param indexId the index id of the secondary index
      * @param indexEntries the index entries to update
      * @return the previous row ids of the index entries
+     * IndexException if no existing entry(ies) to update
      */
     List<Long> updateSecondaryIndexEntries(long tableId, long indexId,
                                            List<IndexProto.SecondaryIndexEntry> indexEntries) throws IndexException;