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

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2014 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  *******************************************************************************/
  13
  14 package org.eclipse.linuxtools.tmf.core.event;
  15
  16 import java.util.Collection;
  17
  18 import org.eclipse.jdt.annotation.NonNull;
  19
  20 /**
  21  * The generic event payload in TMF. Each field can be either a terminal or
  22  * further decomposed into subfields.
  23  *
  24  * @version 1.0
  25  * @author Francois Chouinard
  26  *
  27  * @see ITmfEvent
  28  * @see ITmfEventType
  29  */
  30 public interface ITmfEventField {
  31
  32     // ------------------------------------------------------------------------
  33     // Constants
  34     // ------------------------------------------------------------------------
  35
  36     /**
  37      * The root field id (the main container)
  38      */
  39     public static final @NonNull String ROOT_FIELD_ID = ":root:"; //$NON-NLS-1$
  40
  41     // ------------------------------------------------------------------------
  42     // Getters
  43     // ------------------------------------------------------------------------
  44
  45     /**
  46      * @return the field name
  47      */
  48     String getName();
  49
  50     /**
  51      * @return the field value
  52      */
  53     Object getValue();
  54
  55     /**
  56      * @return the value formatted as string
  57      * @since 2.0
  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      * @since 3.0
  67      */
  68     Collection<String> getFieldNames();
  69
  70     /**
  71      * Return the subfield. The iteration order is the same as
  72      * {@link #getFieldNames()}. The returned Collection is immutable.
  73      *
  74      * @return The subfields (empty Collection if none)
  75      * @since 3.0
  76      */
  77     Collection<? extends ITmfEventField> getFields();
  78
  79     /**
  80      * @param name The name of the field
  81      * @return a specific subfield by name (null if absent or inexistent)
  82      */
  83     ITmfEventField getField(String name);
  84
  85     /**
  86      * Gets the a sub-field of this field, which may be multiple levels down.
  87      *
  88      * @param path
  89      *            Array of field names to recursively go through
  90      * @return The field at the end, or null if a field in the path cannot be
  91      *         found
  92      * @since 3.0
  93      */
  94     ITmfEventField getSubField(String... path);
  95
  96 }