Commit | Line | Data |
---|---|---|
3a081e85 GB |
1 | /******************************************************************************* |
2 | * Copyright (c) 2010, 2016 Ericsson, École Polytechnique de Montréal, and others | |
3 | * | |
4 | * All rights reserved. This program and the accompanying materials are | |
5 | * made available under the terms of the Eclipse Public License v1.0 which | |
6 | * accompanies this distribution, and is available at | |
7 | * http://www.eclipse.org/legal/epl-v10.html | |
8 | *******************************************************************************/ | |
9 | ||
10 | package org.eclipse.tracecompass.internal.statesystem.core.backend.historytree; | |
11 | ||
12 | import java.io.File; | |
13 | import java.io.FileInputStream; | |
f4baf640 | 14 | import java.io.IOException; |
3a081e85 | 15 | import java.nio.channels.ClosedChannelException; |
3a081e85 GB |
16 | import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException; |
17 | ||
18 | /** | |
19 | * Meta-container for the History Tree. This structure contains all the | |
20 | * high-level data relevant to the tree. | |
21 | * | |
22 | * @author Alexandre Montplaisir | |
f4baf640 | 23 | * @author Geneviève Bastien |
3a081e85 GB |
24 | */ |
25 | public interface IHistoryTree { | |
26 | ||
f4baf640 GB |
27 | /** |
28 | * Interface for history to create the various HTNodes | |
29 | */ | |
30 | interface IHTNodeFactory { | |
31 | ||
32 | /** | |
33 | * Creates a new core node for the specific history tree | |
34 | * | |
35 | * @param config | |
36 | * Configuration of the History Tree | |
37 | * @param seqNumber | |
38 | * The (unique) sequence number assigned to this particular | |
39 | * node | |
40 | * @param parentSeqNumber | |
41 | * The sequence number of this node's parent node | |
42 | * @param start | |
43 | * The earliest timestamp stored in this node | |
44 | * @return The new core node | |
45 | * @throws IOException | |
46 | * any exception occurring while trying to read/create the | |
47 | * node | |
48 | */ | |
49 | HTNode createCoreNode(HTConfig config, int seqNumber, int parentSeqNumber, long start) throws IOException; | |
50 | ||
51 | /** | |
52 | * Creates a new core node for the specific history tree | |
53 | * | |
54 | * @param config | |
55 | * Configuration of the History Tree | |
56 | * @param seqNumber | |
57 | * The (unique) sequence number assigned to this particular | |
58 | * node | |
59 | * @param parentSeqNumber | |
60 | * The sequence number of this node's parent node | |
61 | * @param start | |
62 | * The earliest timestamp stored in this node | |
63 | * @return The new core node | |
64 | * @throws IOException | |
65 | * any exception occurring while trying to read/create the | |
66 | * node | |
67 | */ | |
68 | HTNode createLeafNode(HTConfig config, int seqNumber, int parentSeqNumber, long start) throws IOException; | |
69 | } | |
70 | ||
3a081e85 GB |
71 | /** |
72 | * Size of the "tree header" in the tree-file The nodes will use this offset | |
73 | * to know where they should be in the file. This should always be a | |
74 | * multiple of 4K. | |
75 | */ | |
76 | int TREE_HEADER_SIZE = 4096; | |
77 | ||
78 | /** | |
79 | * "Save" the tree to disk. This method will cause the treeIO object to | |
80 | * commit all nodes to disk and then return the RandomAccessFile descriptor | |
81 | * so the Tree object can save its configuration into the header of the | |
82 | * file. | |
83 | * | |
84 | * @param requestedEndTime | |
85 | * The greatest timestamp present in the history tree | |
86 | */ | |
87 | void closeTree(long requestedEndTime); | |
88 | ||
89 | // ------------------------------------------------------------------------ | |
90 | // Accessors | |
91 | // ------------------------------------------------------------------------ | |
92 | ||
93 | /** | |
94 | * Get the start time of this tree. | |
95 | * | |
96 | * @return The start time | |
97 | */ | |
98 | long getTreeStart(); | |
99 | ||
100 | /** | |
101 | * Get the current end time of this tree. | |
102 | * | |
103 | * @return The end time | |
104 | */ | |
105 | long getTreeEnd(); | |
106 | ||
107 | /** | |
108 | * Get the number of nodes in this tree. | |
109 | * | |
110 | * @return The number of nodes | |
111 | */ | |
112 | int getNodeCount(); | |
113 | ||
114 | /** | |
115 | * Get the current root node of this tree | |
116 | * | |
117 | * @return The root node | |
118 | */ | |
119 | HTNode getRootNode(); | |
120 | ||
121 | // ------------------------------------------------------------------------ | |
122 | // HT_IO interface | |
123 | // ------------------------------------------------------------------------ | |
124 | ||
125 | /** | |
126 | * Return the FileInputStream reader with which we will read an attribute | |
127 | * tree (it will be sought to the correct position). | |
128 | * | |
129 | * @return The FileInputStream indicating the file and position from which | |
130 | * the attribute tree can be read. | |
131 | */ | |
132 | FileInputStream supplyATReader(); | |
133 | ||
134 | /** | |
135 | * Return the file to which we will write the attribute tree. | |
136 | * | |
137 | * @return The file to which we will write the attribute tree | |
138 | */ | |
139 | File supplyATWriterFile(); | |
140 | ||
141 | /** | |
142 | * Return the position in the file (given by {@link #supplyATWriterFile}) | |
143 | * where to start writing the attribute tree. | |
144 | * | |
145 | * @return The position in the file where to start writing | |
146 | */ | |
147 | long supplyATWriterFilePos(); | |
148 | ||
149 | /** | |
150 | * Read a node from the tree. | |
151 | * | |
152 | * @param seqNumber | |
153 | * The sequence number of the node to read | |
154 | * @return The node | |
155 | * @throws ClosedChannelException | |
156 | * If the tree IO is unavailable | |
157 | */ | |
158 | HTNode readNode(int seqNumber) throws ClosedChannelException; | |
159 | ||
160 | /** | |
161 | * Write a node object to the history file. | |
162 | * | |
163 | * @param node | |
164 | * The node to write to disk | |
165 | */ | |
166 | void writeNode(HTNode node); | |
167 | ||
168 | /** | |
169 | * Close the history file. | |
170 | */ | |
171 | void closeFile(); | |
172 | ||
173 | /** | |
174 | * Delete the history file. | |
175 | */ | |
176 | void deleteFile(); | |
177 | ||
178 | // ------------------------------------------------------------------------ | |
179 | // Operations | |
180 | // ------------------------------------------------------------------------ | |
181 | ||
182 | /** | |
183 | * Insert an interval in the tree. | |
184 | * | |
185 | * @param interval | |
186 | * The interval to be inserted | |
187 | * @throws TimeRangeException | |
188 | * If the start of end time of the interval are invalid | |
189 | */ | |
190 | void insertInterval(HTInterval interval) throws TimeRangeException; | |
191 | ||
3a081e85 GB |
192 | /** |
193 | * Get the current size of the history file. | |
194 | * | |
195 | * @return The history file size | |
196 | */ | |
197 | long getFileSize(); | |
198 | ||
3a081e85 | 199 | } |