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 static org.eclipse.tracecompass.common.core.NonNullUtils.checkNotNull;
  17
  18 import java.util.List;
  19
  20 import org.eclipse.jdt.annotation.Nullable;
  21 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
  22 import org.eclipse.tracecompass.tmf.core.event.ITmfEventType;
  23 import org.eclipse.tracecompass.tmf.core.timestamp.ITmfTimestamp;
  24
  25 import com.google.common.collect.ImmutableList;
  26
  27 /**
  28  * An aspect is a piece of information that can be extracted, directly or
  29  * indirectly, from a trace event.
  30  *
  31  * Simple examples could be timestamp, or event fields. But it could also be
  32  * something like a state system request, at the timestamp of the given event.
  33  *
  34  * The aspect can then be used to populate event table columns, to filter
  35  * on to only keep certain events, to plot XY charts, etc.
  36  *
  37  * @author Alexandre Montplaisir
  38  */
  39 public interface ITmfEventAspect {
  40
  41     /**
  42      * Static definition of an empty string. You can use this instead of 'null'!
  43      */
  44     String EMPTY_STRING = ""; //$NON-NLS-1$
  45
  46     /**
  47      * List of all common base aspects
  48      */
  49     public static final List<ITmfEventAspect> BASE_ASPECTS =
  50             checkNotNull(ImmutableList.of(
  51                     BaseAspects.TIMESTAMP,
  52                     BaseAspects.EVENT_TYPE,
  53                     BaseAspects.CONTENTS,
  54                     BaseAspects.TRACE_NAME
  55                     ));
  56     /**
  57      * Some basic aspects that all trace types should be able to use, using
  58      * methods found in {@link ITmfEvent}.
  59      */
  60     interface BaseAspects {
  61
  62         /**
  63          * Aspect for the event timestamp
  64          */
  65         ITmfEventAspect TIMESTAMP = new ITmfEventAspect() {
  66             @Override
  67             public String getName() {
  68                 return Messages.getMessage(Messages.AspectName_Timestamp);
  69             }
  70
  71             @Override
  72             public String getHelpText() {
  73                 return EMPTY_STRING;
  74             }
  75
  76             @Override
  77             public @Nullable ITmfTimestamp resolve(ITmfEvent event) {
  78                 return event.getTimestamp();
  79             }
  80         };
  81
  82         /**
  83          * Aspect for the event type
  84          */
  85         ITmfEventAspect EVENT_TYPE = new ITmfEventAspect() {
  86             @Override
  87             public String getName() {
  88                 return Messages.getMessage(Messages.AspectName_EventType);
  89             }
  90
  91             @Override
  92             public String getHelpText() {
  93                 return Messages.getMessage(Messages.AspectHelpText_EventType);
  94             }
  95
  96             @Override
  97             public @Nullable String resolve(ITmfEvent event) {
  98                 ITmfEventType type = event.getType();
  99                 if (type == null) {
 100                     return null;
 101                 }
 102                 return type.getName();
 103             }
 104         };
 105
 106         /**
 107          * Aspect for the aggregated event contents (fields)
 108          */
 109         ITmfEventAspect CONTENTS = new ITmfEventAspect() {
 110             @Override
 111             public String getName() {
 112                 return Messages.getMessage(Messages.AspectName_Contents);
 113             }
 114
 115             @Override
 116             public String getHelpText() {
 117                 return Messages.getMessage(Messages.AspectHelpText_Contents);
 118             }
 119
 120             @Override
 121             public @Nullable String resolve(ITmfEvent event) {
 122                 return event.getContent().toString();
 123             }
 124         };
 125
 126         /**
 127          * Aspect for the trace's name (for experiments with many traces)
 128          */
 129         ITmfEventAspect TRACE_NAME = new ITmfEventAspect() {
 130             @Override
 131             public String getName() {
 132                 return Messages.getMessage(Messages.AspectName_TraceName);
 133             }
 134
 135             @Override
 136             public String getHelpText() {
 137                 return Messages.getMessage(Messages.AspectHelpText_TraceName);
 138             }
 139
 140             @Override
 141             public @Nullable String resolve(ITmfEvent event) {
 142                 return event.getTrace().getName();
 143             }
 144         };
 145     }
 146
 147     /**
 148      * Get the name of this aspect. This name will be user-visible and, as such,
 149      * should be localized.
 150      *
 151      * @return The name of this aspect.
 152      */
 153     String getName();
 154
 155     /**
 156      * Return a descriptive help text of what this aspect does. This could then
 157      * be shown in tooltip or in option dialogs for instance. It should also be
 158      * localized.
 159      *
 160      * You can return {@link #EMPTY_STRING} if you judge that the aspect name
 161      * makes it obvious.
 162      *
 163      * @return The help text of this aspect
 164      */
 165     String getHelpText();
 166
 167     /**
 168      * The "functor" representing this aspect. Basically, what to do for an
 169      * event that is passed in parameter.
 170      *
 171      * Note to implementers:
 172      *
 173      * The parameter type here is {@link ITmfEvent}. This is because you could
 174      * receive any type of event here. Do not assume you will only receive
 175      * events of your own trace type. It is perfectly fine to return
 176      * {@link #EMPTY_STRING} for event types you don't support.
 177      *
 178      * You also can (and should) provide a more specific return type than
 179      * Object.
 180      *
 181      * @param event
 182      *            The event to process
 183      * @return The resulting tidbit of information for this event.
 184      */
 185     @Nullable Object resolve(ITmfEvent event);
 186 }