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