tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/event/aspect/ITmfEventAspect.java

   1 /*******************************************************************************
   2  * Copyright (c) 2014, 2015 Ericsson
   3  *
   4  * All rights reserved. This program and the accompanying materials are made
   5  * 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  *   Alexandre Montplaisir - Initial API and implementation
  11  *   Patrick Tasse - Added base aspect list
  12  *******************************************************************************/
  13
  14 package org.eclipse.tracecompass.tmf.core.event.aspect;
  15
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
  18
  19 /**
  20  * An aspect is a piece of information that can be extracted, directly or
  21  * indirectly, from a trace event.
  22  *
  23  * Simple examples could be timestamp, or event fields. But it could also be
  24  * something like a state system request, at the timestamp of the given event.
  25  *
  26  * The aspect can then be used to populate event table columns, to filter
  27  * on to only keep certain events, to plot XY charts, etc.
  28  *
  29  * @author Alexandre Montplaisir
  30  * @param <T> Type of the return value of the {@link #resolve} method
  31  */
  32 public interface ITmfEventAspect<T> {
  33
  34     /**
  35      * Static definition of an empty string. You can use this instead of 'null'!
  36      */
  37     String EMPTY_STRING = ""; //$NON-NLS-1$
  38
  39     /**
  40      * Get the name of this aspect. This name will be user-visible and, as such,
  41      * should be localized.
  42      *
  43      * @return The name of this aspect.
  44      */
  45     String getName();
  46
  47     /**
  48      * Return a descriptive help text of what this aspect does. This could then
  49      * be shown in tooltip or in option dialogs for instance. It should also be
  50      * localized.
  51      *
  52      * You can return {@link #EMPTY_STRING} if you judge that the aspect name
  53      * makes it obvious.
  54      *
  55      * @return The help text of this aspect
  56      */
  57     String getHelpText();
  58
  59     /**
  60      * The "functor" representing this aspect. Basically, what to do for an
  61      * event that is passed in parameter.
  62      *
  63      * Note to implementers:
  64      *
  65      * The parameter type here is {@link ITmfEvent}. This is because you could
  66      * receive any type of event here. Do not assume you will only receive
  67      * events of your own trace type. It is perfectly fine to return
  68      * {@link #EMPTY_STRING} for event types you don't support.
  69      *
  70      * You also can (and should) provide a more specific return type than
  71      * Object.
  72      *
  73      * @param event
  74      *            The event to process
  75      * @return The resulting tidbit of information for this event.
  76      */
  77     @Nullable T resolve(ITmfEvent event);
  78 }