tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/event/ITmfEventField.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 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  *   Alexandre Montplaisir - Removed arrays from the API
  12  *   Patrick Tasse - Use ellipsis for getField and remove getSubField
  13  *******************************************************************************/
  14
  15 package org.eclipse.tracecompass.tmf.core.event;
  16
  17 import java.util.Collection;
  18
  19 import org.eclipse.jdt.annotation.NonNull;
  20
  21 /**
  22  * The generic event payload in TMF. Each field can be either a terminal or
  23  * further decomposed into subfields.
  24  *
  25  * @version 1.0
  26  * @author Francois Chouinard
  27  *
  28  * @see ITmfEvent
  29  * @see ITmfEventType
  30  */
  31 public interface ITmfEventField {
  32
  33     // ------------------------------------------------------------------------
  34     // Constants
  35     // ------------------------------------------------------------------------
  36
  37     /**
  38      * The root field id (the main container)
  39      */
  40     public static final @NonNull String ROOT_FIELD_ID = ":root:"; //$NON-NLS-1$
  41
  42     // ------------------------------------------------------------------------
  43     // Getters
  44     // ------------------------------------------------------------------------
  45
  46     /**
  47      * @return the field name
  48      */
  49     @NonNull String getName();
  50
  51     /**
  52      * @return the field value
  53      */
  54     Object getValue();
  55
  56     /**
  57      * @return the value formatted as string
  58      */
  59     String getFormattedValue();
  60
  61     /**
  62      * Return the subfield names. The iteration order is the same as
  63      * {@link #getFields()}. The returned Collection is immutable.
  64      *
  65      * @return The subfield names (empty Collection if none)
  66      */
  67     @NonNull Collection<@NonNull String> getFieldNames();
  68
  69     /**
  70      * Return the subfields. The iteration order is the same as
  71      * {@link #getFieldNames()}. The returned Collection is immutable.
  72      *
  73      * @return The subfields (empty Collection if none)
  74      */
  75     @NonNull Collection<? extends ITmfEventField> getFields();
  76
  77     /**
  78      * Return a subfield by its path relative to this field.
  79      * If the path is empty, this field is returned.
  80      * @param path The path to the subfield
  81      * @return a specific subfield by path (null if inexistent)
  82      */
  83     ITmfEventField getField(String @NonNull ... path);
  84
  85 }