Commit | Line | Data |
---|---|---|
26a6a7eb AM |
1 | /******************************************************************************* |
2 | * Copyright (c) 2015 EfficiOS Inc., Alexandre Montplaisir | |
3 | * | |
4 | * All rights reserved. This program and the accompanying materials | |
5 | * are made available under the terms of the Eclipse Public License v1.0 | |
6 | * which accompanies this distribution, and is available at | |
7 | * http://www.eclipse.org/legal/epl-v10.html | |
8 | * | |
9 | * Contributors: | |
10 | * Alexandre Montplaisir - Initial API and implementation | |
11 | *******************************************************************************/ | |
12 | ||
13 | package org.eclipse.tracecompass.segmentstore.core; | |
14 | ||
0ee1e58a | 15 | import java.util.ArrayList; |
1a9cb076 | 16 | import java.util.Collection; |
def1d9d0 | 17 | import java.util.Comparator; |
def1d9d0 LPD |
18 | import java.util.List; |
19 | ||
899df915 MK |
20 | import org.eclipse.jdt.annotation.Nullable; |
21 | ||
fc409c43 GB |
22 | import com.google.common.collect.Lists; |
23 | ||
26a6a7eb AM |
24 | /** |
25 | * Interface for segment-storing backends. | |
26 | * | |
899df915 MK |
27 | * Common contract (what should not be implemented) for a segment store. |
28 | * <ol> | |
29 | * <li>no remove</li> | |
30 | * <li>no removeAll</li> | |
31 | * <li>no retainall</li> | |
32 | * </ol> | |
33 | * | |
1a9cb076 | 34 | * @param <E> |
26a6a7eb AM |
35 | * The type of {@link ISegment} element that will be stored in this |
36 | * database. | |
37 | * | |
38 | * @author Alexandre Montplaisir | |
39 | */ | |
1a9cb076 | 40 | public interface ISegmentStore<E extends ISegment> extends Collection<E> { |
26a6a7eb | 41 | |
def1d9d0 LPD |
42 | /** |
43 | * Sorted Iterator | |
44 | * | |
45 | * @param order | |
46 | * The desired order for the returned iterator | |
47 | * @return An iterator over all the segments in the store in the desired order | |
48 | * @since 1.1 | |
49 | */ | |
50 | default Iterable<E> iterator(Comparator<ISegment> order){ | |
da132663 | 51 | return getIntersectingElements(0, Long.MAX_VALUE, order); |
def1d9d0 LPD |
52 | } |
53 | ||
26a6a7eb AM |
54 | /** |
55 | * Retrieve all elements that inclusively cross the given position. | |
56 | * | |
57 | * @param position | |
58 | * The target position. This would represent a timestamp, if the | |
59 | * tree's X axis represents time. | |
60 | * @return The intervals that cross this position | |
61 | */ | |
def1d9d0 LPD |
62 | default Iterable<E> getIntersectingElements(long position){ |
63 | return getIntersectingElements(position, position); | |
64 | } | |
65 | ||
66 | /** | |
67 | * Retrieve all elements that inclusively cross the given position, sorted | |
68 | * in the specified order. | |
69 | * | |
70 | * @param position | |
71 | * The target position. This would represent a timestamp, if the | |
72 | * tree's X axis represents time. | |
73 | * @param order | |
74 | * The desired order for the returned iterator | |
75 | * @return The intervals that cross this position | |
76 | * @since 1.1 | |
77 | */ | |
78 | default Iterable<E> getIntersectingElements(long position, Comparator<ISegment> order) { | |
79 | return getIntersectingElements(position, position, order); | |
80 | } | |
26a6a7eb AM |
81 | |
82 | /** | |
83 | * Retrieve all elements that inclusively cross another segment. We define | |
84 | * this target segment by its start and end positions. | |
85 | * | |
86 | * This effectively means, all elements that respect *both* conditions: | |
87 | * | |
88 | * <ul> | |
89 | * <li>Their end is after the 'start' parameter</li> | |
90 | * <li>Their start is before the 'end' parameter</li> | |
91 | * </ul> | |
92 | * | |
93 | * @param start | |
94 | * The target start position | |
95 | * @param end | |
96 | * The target end position | |
97 | * @return The elements overlapping with this segment | |
98 | */ | |
1a9cb076 | 99 | Iterable<E> getIntersectingElements(long start, long end); |
26a6a7eb | 100 | |
def1d9d0 LPD |
101 | /** |
102 | * Retrieve all elements that inclusively cross another segment, sorted in | |
103 | * the specified order. We define this target segment by its start and end | |
104 | * positions. | |
105 | * | |
106 | * @param start | |
107 | * The target start position | |
108 | * @param end | |
109 | * The target end position | |
110 | * @param order | |
111 | * The desired order for the returned iterator | |
112 | * @return The intervals that cross this position | |
113 | * @since 1.1 | |
114 | */ | |
0ee1e58a LPD |
115 | default Iterable<E> getIntersectingElements(long start, long end, Comparator<ISegment> order) { |
116 | Iterable<E> ret = getIntersectingElements(start, end); | |
117 | List<E> list; | |
118 | if (ret instanceof ArrayList<?>) { | |
119 | /* | |
120 | * No point in copying the intersecting elements into a new | |
121 | * ArrayList if they are already in a new ArrayList. | |
122 | */ | |
123 | list = (List<E>) ret; | |
124 | } else { | |
125 | list = Lists.newArrayList(ret); | |
126 | } | |
127 | list.sort(order); | |
128 | return list; | |
def1d9d0 LPD |
129 | } |
130 | ||
26a6a7eb AM |
131 | /** |
132 | * Dispose the data structure and release any system resources associated | |
133 | * with it. | |
134 | */ | |
135 | void dispose(); | |
a05d1af8 GB |
136 | |
137 | /** | |
138 | * Method to close off the segment store. This happens for example when we | |
139 | * are done reading an off-line trace. Implementers can use this method to | |
140 | * save the segment store on disk | |
141 | * | |
142 | * @param deleteFiles | |
143 | * Whether to delete any file that was created while building the | |
144 | * segment store | |
145 | */ | |
146 | default void close(boolean deleteFiles) { | |
147 | ||
148 | } | |
899df915 MK |
149 | |
150 | @Override | |
151 | default boolean remove(@Nullable Object o) { | |
152 | throw new UnsupportedOperationException("Segment stores does not support \"remove\""); //$NON-NLS-1$ | |
153 | } | |
154 | ||
155 | @Override | |
156 | default boolean removeAll(@Nullable Collection<?> c) { | |
157 | throw new UnsupportedOperationException("Segment stores does not support \"removeAll\""); //$NON-NLS-1$ | |
158 | } | |
159 | ||
160 | @Override | |
161 | default boolean retainAll(@Nullable Collection<?> c) { | |
162 | throw new UnsupportedOperationException("Segment stores does not support \"retainAll\""); //$NON-NLS-1$ | |
163 | } | |
26a6a7eb | 164 | } |