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

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