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      * Get the event type this provider handles
  54      *
  55      * @return The type of ITmfEvent
  56      * @since 2.0
  57      */
  58     Class<? extends ITmfEvent> getEventType();
  59
  60     /**
  61      * Return the next event based on the context supplied. The context
  62      * will be updated for the subsequent read.
  63      *
  64      * @param context the trace read context (updated)
  65      * @return the event referred to by context
  66      */
  67     ITmfEvent getNext(ITmfContext context);
  68
  69     /**
  70      * Gets the parent event provider.
  71      *
  72      * @return the parent event provider or null if no parent.
  73      */
  74     @Nullable
  75     ITmfEventProvider getParent();
  76
  77     /**
  78      * Sets the parent event provider.
  79      *
  80      * @param parent
  81      *            the parent to set.
  82      */
  83     void setParent(@Nullable ITmfEventProvider parent);
  84
  85     /**
  86      * Adds a child event provider.
  87      *
  88      * @param child
  89      *            a child to add, cannot be null.
  90      */
  91     void addChild(@NonNull ITmfEventProvider child);
  92
  93     /**
  94      * Gets the children event providers.
  95      *
  96      * @return a list of children event providers or an empty list if no
  97      *         children (return value cannot be null).
  98      */
  99     @NonNull
 100     List<ITmfEventProvider> getChildren();
 101
 102     /**
 103      * Returns the child event provider with given name.
 104      *
 105      * @param name
 106      *            name of child to find.
 107      * @return child event provider or null.
 108      */
 109     @Nullable
 110     ITmfEventProvider getChild(String name);
 111
 112     /**
 113      * Returns the child event provider for a given index
 114      *
 115      * @param index
 116      *            index of child to get. Prior calling this method the index has
 117      *            to be verified so that it is within the bounds.
 118      * @return child event provider (cannot be null)
 119      */
 120     @NonNull
 121     ITmfEventProvider getChild(int index);
 122
 123     /**
 124      * Gets children for given class type.
 125      *
 126      * @param clazz
 127      *            a class type to get
 128      * @return a list of children event providers matching a given class type or
 129      *         an empty list if no children (return value cannot be null).
 130      */
 131     @NonNull
 132     <T extends ITmfEventProvider> List<T> getChildren(Class<T> clazz);
 133
 134     /**
 135      * Gets the number of children
 136      *
 137      * @return number of children
 138      */
 139     int getNbChildren();
 140 }