org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/component/ITmfEventProvider.java

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2015 Ericsson
   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  * Contributors:
  10  *   Francois Chouinard - Initial API and implementation
  11  *   Bernd Hufmann - Added APIs for composite event providers
  12  *******************************************************************************/
  13
  14 package org.eclipse.tracecompass.tmf.core.component;
  15
  16 import java.util.List;
  17
  18 import org.eclipse.jdt.annotation.NonNull;
  19 import org.eclipse.jdt.annotation.Nullable;
  20 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
  21 import org.eclipse.tracecompass.tmf.core.request.ITmfEventRequest;
  22 import org.eclipse.tracecompass.tmf.core.trace.ITmfContext;
  23
  24 /**
  25  * This is the interface of the data providers in TMF. Data providers have the
  26  * capability of handling data requests.
  27  *
  28  * @author Francois Chouinard
  29  *
  30  * @see TmfEventProvider
  31  * @since 3.0
  32  */
  33 public interface ITmfEventProvider extends ITmfComponent {
  34
  35     /**
  36      * Queue the request for processing.
  37      *
  38      * @param request The request to process
  39      */
  40     void sendRequest(ITmfEventRequest request);
  41
  42     /**
  43      * Increments/decrements the pending requests counters and fires the request
  44      * if necessary (counter == 0). Used for coalescing requests across multiple
  45      * TmfDataProvider's.
  46      *
  47      * @param isIncrement
  48      *            Should we increment (true) or decrement (false) the pending
  49      *            counter
  50      */
  51     void notifyPendingRequest(boolean isIncrement);
  52
  53     /**
  54      * Return the next event based on the context supplied. The context
  55      * will be updated for the subsequent read.
  56      *
  57      * @param context the trace read context (updated)
  58      * @return the event referred to by context
  59      */
  60     ITmfEvent getNext(ITmfContext context);
  61
  62     /**
  63      * Gets the parent event provider.
  64      *
  65      * @return the parent event provider or null if no parent.
  66      */
  67     @Nullable
  68     ITmfEventProvider getParent();
  69
  70     /**
  71      * Sets the parent event provider.
  72      *
  73      * @param parent
  74      *            the parent to set.
  75      */
  76     void setParent(@Nullable ITmfEventProvider parent);
  77
  78     /**
  79      * Adds a child event provider.
  80      *
  81      * @param child
  82      *            a child to add, cannot be null.
  83      */
  84     void addChild(@NonNull ITmfEventProvider child);
  85
  86     /**
  87      * Gets the children event providers.
  88      *
  89      * @return a list of children event providers or an empty list if no
  90      *         children (return value cannot be null).
  91      */
  92     @NonNull
  93     List<ITmfEventProvider> getChildren();
  94
  95     /**
  96      * Returns the child event provider with given name.
  97      *
  98      * @param name
  99      *            name of child to find.
 100      * @return child event provider or null.
 101      */
 102     @Nullable
 103     ITmfEventProvider getChild(String name);
 104
 105     /**
 106      * Returns the child event provider for a given index
 107      *
 108      * @param index
 109      *            index of child to get. Prior calling this method the index has
 110      *            to be verified so that it is within the bounds.
 111      * @return child event provider (cannot be null)
 112      */
 113     @NonNull
 114     ITmfEventProvider getChild(int index);
 115
 116     /**
 117      * Gets children for given class type.
 118      *
 119      * @param clazz
 120      *            a class type to get
 121      * @return a list of children event providers matching a given class type or
 122      *         an empty list if no children (return value cannot be null).
 123      */
 124     @NonNull
 125     <T extends ITmfEventProvider> List<T> getChildren(Class<T> clazz);
 126
 127     /**
 128      * Gets the number of children
 129      *
 130      * @return number of children
 131      */
 132     int getNbChildren();
 133 }