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.ArrayList;
  16 import java.util.Collection;
  17 import java.util.Comparator;
  18 import java.util.List;
  19
  20 import org.eclipse.jdt.annotation.Nullable;
  21
  22 import com.google.common.collect.Lists;
  23
  24 /**
  25  * Interface for segment-storing backends.
  26  *
  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  *
  34  * @param <E>
  35  *            The type of {@link ISegment} element that will be stored in this
  36  *            database.
  37  *
  38  * @author Alexandre Montplaisir
  39  */
  40 public interface ISegmentStore<E extends ISegment> extends Collection<E> {
  41
  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){
  51         return getIntersectingElements(0, Long.MAX_VALUE, order);
  52     }
  53
  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      */
  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     }
  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      */
  99     Iterable<E> getIntersectingElements(long start, long end);
 100
 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      */
 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;
 129     }
 130
 131     /**
 132      * Dispose the data structure and release any system resources associated
 133      * with it.
 134      */
 135     void dispose();
 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     }
 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     }
 164 }