statesystem/org.eclipse.tracecompass.segmentstore.core/src/org/eclipse/tracecompass/segmentstore/core/ISegmentStore.java

   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
  15 import java.util.Collection;
  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;
  24
  25 /**
  26  * Interface for segment-storing backends.
  27  *
  28  * @param <E>
  29  *            The type of {@link ISegment} element that will be stored in this
  30  *            database.
  31  *
  32  * @author Alexandre Montplaisir
  33  */
  34 public interface ISegmentStore<E extends ISegment> extends Collection<E> {
  35
  36     /**
  37      * Sorted Iterator
  38      *
  39      * @param order
  40      *            The desired order for the returned iterator
  41      * @return An iterator over all the segments in the store in the desired order
  42      * @since 1.1
  43      */
  44     default Iterable<E> iterator(Comparator<ISegment> order){
  45         return getIntersectingElements(Long.MIN_VALUE, Long.MAX_VALUE, order);
  46     }
  47
  48     /**
  49      * Retrieve all elements that inclusively cross the given position.
  50      *
  51      * @param position
  52      *            The target position. This would represent a timestamp, if the
  53      *            tree's X axis represents time.
  54      * @return The intervals that cross this position
  55      */
  56     default Iterable<E> getIntersectingElements(long position){
  57         return getIntersectingElements(position, position);
  58     }
  59
  60     /**
  61      * Retrieve all elements that inclusively cross the given position, sorted
  62      * in the specified order.
  63      *
  64      * @param position
  65      *            The target position. This would represent a timestamp, if the
  66      *            tree's X axis represents time.
  67      * @param order
  68      *            The desired order for the returned iterator
  69      * @return The intervals that cross this position
  70      * @since 1.1
  71      */
  72     default Iterable<E> getIntersectingElements(long position, Comparator<ISegment> order) {
  73         return getIntersectingElements(position, position, order);
  74     }
  75
  76     /**
  77      * Retrieve all elements that inclusively cross another segment. We define
  78      * this target segment by its start and end positions.
  79      *
  80      * This effectively means, all elements that respect *both* conditions:
  81      *
  82      * <ul>
  83      * <li>Their end is after the 'start' parameter</li>
  84      * <li>Their start is before the 'end' parameter</li>
  85      * </ul>
  86      *
  87      * @param start
  88      *            The target start position
  89      * @param end
  90      *            The target end position
  91      * @return The elements overlapping with this segment
  92      */
  93     Iterable<E> getIntersectingElements(long start, long end);
  94
  95     /**
  96      * Retrieve all elements that inclusively cross another segment, sorted in
  97      * the specified order. We define this target segment by its start and end
  98      * positions.
  99      *
 100      * @param start
 101      *            The target start position
 102      * @param end
 103      *            The target end position
 104      * @param order
 105      *            The desired order for the returned iterator
 106      * @return The intervals that cross this position
 107      * @since 1.1
 108      */
 109     default Iterable<E> getIntersectingElements(long start, long end, Comparator<ISegment> order){
 110         List<E> list = Lists.newArrayList(getIntersectingElements(start, end));
 111         return new Iterable<@NonNull E>() {
 112             @Override
 113             public Iterator<@NonNull E> iterator() {
 114                 Collections.sort(list, order);
 115                 return list.iterator();
 116             }
 117         };
 118     }
 119
 120     /**
 121      * Dispose the data structure and release any system resources associated
 122      * with it.
 123      */
 124     void dispose();
 125
 126     /**
 127      * Method to close off the segment store. This happens for example when we
 128      * are done reading an off-line trace. Implementers can use this method to
 129      * save the segment store on disk
 130      *
 131      * @param deleteFiles
 132      *            Whether to delete any file that was created while building the
 133      *            segment store
 134      */
 135     default void close(boolean deleteFiles) {
 136
 137     }
 138 }