tmf/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  */
  32 public interface ITmfEventProvider extends ITmfComponent {
  33
  34     /**
  35      * Queue the request for processing.
  36      *
  37      * @param request The request to process
  38      */
  39     void sendRequest(ITmfEventRequest request);
  40
  41     /**
  42      * Increments/decrements the pending requests counters and fires the request
  43      * if necessary (counter == 0). Used for coalescing requests across multiple
  44      * TmfDataProvider's.
  45      *
  46      * @param isIncrement
  47      *            Should we increment (true) or decrement (false) the pending
  48      *            counter
  49      */
  50     void notifyPendingRequest(boolean isIncrement);
  51
  52     /**
  53      * Return the next event based on the context supplied. The context
  54      * will be updated for the subsequent read.
  55      *
  56      * @param context the trace read context (updated)
  57      * @return the event referred to by context
  58      */
  59     ITmfEvent getNext(ITmfContext context);
  60
  61     /**
  62      * Gets the parent event provider.
  63      *
  64      * @return the parent event provider or null if no parent.
  65      */
  66     @Nullable
  67     ITmfEventProvider getParent();
  68
  69     /**
  70      * Sets the parent event provider.
  71      *
  72      * @param parent
  73      *            the parent to set.
  74      */
  75     void setParent(@Nullable ITmfEventProvider parent);
  76
  77     /**
  78      * Adds a child event provider.
  79      *
  80      * @param child
  81      *            a child to add, cannot be null.
  82      */
  83     void addChild(@NonNull ITmfEventProvider child);
  84
  85     /**
  86      * Gets the children event providers.
  87      *
  88      * @return a list of children event providers or an empty list if no
  89      *         children (return value cannot be null).
  90      */
  91     @NonNull
  92     List<ITmfEventProvider> getChildren();
  93
  94     /**
  95      * Returns the child event provider with given name.
  96      *
  97      * @param name
  98      *            name of child to find.
  99      * @return child event provider or null.
 100      */
 101     @Nullable
 102     ITmfEventProvider getChild(String name);
 103
 104     /**
 105      * Returns the child event provider for a given index
 106      *
 107      * @param index
 108      *            index of child to get. Prior calling this method the index has
 109      *            to be verified so that it is within the bounds.
 110      * @return child event provider (cannot be null)
 111      */
 112     @NonNull
 113     ITmfEventProvider getChild(int index);
 114
 115     /**
 116      * Gets children for given class type.
 117      *
 118      * @param clazz
 119      *            a class type to get
 120      * @return a list of children event providers matching a given class type or
 121      *         an empty list if no children (return value cannot be null).
 122      */
 123     @NonNull
 124     <T extends ITmfEventProvider> List<T> getChildren(Class<T> clazz);
 125
 126     /**
 127      * Gets the number of children
 128      *
 129      * @return number of children
 130      */
 131     int getNbChildren();
 132 }