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