Coverage Summary for Class: BlocksIndex (co.rsk.db)
1 /*
2 * This file is part of RskJ
3 * Copyright (C) 2019 RSK Labs Ltd.
4 *
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU Lesser General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19 package co.rsk.db;
20
21 import org.ethereum.db.IndexedBlockStore;
22
23 import java.util.List;
24
25 /**
26 * BlocksIndex handles block accesses by their block number.
27 * <p>
28 * Many different blocks might contain the same block number but only one of the belongs to the main chain.
29 * (The one with the most difficulty)
30 * <p>
31 * The blocks themselves are not stored, only the smallest information required to access them by hash.
32 */
33 //TODO(im): Better public methods, this storage should enforce its own invariants.
34 public interface BlocksIndex {
35
36 /**
37 * @return True iif the index is empty.
38 */
39 boolean isEmpty();
40
41 /**
42 * Retrieves the max block number stored in the index. It might not belong to the main chain.
43 * @return The max block number if it exists.
44 * @throws IllegalStateException if the blockstore is empty.
45 */
46 long getMaxNumber();
47
48 /**
49 * Retrieves the min block number stored in the index. It should always belong to the main chain.
50 * @return The min block number.
51 * @throws IllegalStateException if the blockstore is empty.
52 */
53 long getMinNumber();
54
55 /**
56 * Checks if a block number was stored previously.
57 *
58 * @return True iif there's at least one block stored with that number.
59 */
60 boolean contains(long blockNumber);
61
62 /**
63 * Retrieves a list in no particular order of the stored blocks that go by that number.
64 *
65 * @return A list containing the found blocks.
66 */
67 List<IndexedBlockStore.BlockInfo> getBlocksByNumber(long blockNumber);
68
69 /**
70 * Stores a list of blocks by their number, overwriting the previous existing ones.
71 *
72 * @param blocks A non null, non empty list of blocks.
73 */
74 void putBlocks(long blockNumber, List<IndexedBlockStore.BlockInfo> blocks);
75
76 /**
77 * Removes the blocks with the highest block number from the storage.
78 *
79 * @return The removed blocks.
80 */
81 List<IndexedBlockStore.BlockInfo> removeLast();
82
83 /**
84 * Commits the changes to the underlying permanent storage.
85 */
86 void flush();
87
88 void close();
89 }