statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/statesystem/core/statevalue/ITmfStateValue.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  *   Alexandre Montplaisir - Initial API
  11  ******************************************************************************/
  12
  13 package org.eclipse.tracecompass.statesystem.core.statevalue;
  14
  15 import org.eclipse.tracecompass.statesystem.core.exceptions.StateValueTypeException;
  16
  17 /**
  18  * This is the interface for using state values and reading their contents.
  19  *
  20  * @author Alexandre Montplaisir
  21  */
  22 public interface ITmfStateValue extends Comparable<ITmfStateValue> {
  23
  24     /**
  25      * The supported types of state values
  26      */
  27     enum Type {
  28
  29         /** Null value, for an interval not carrying any information */
  30         NULL((byte) -1),
  31         /** 32-bit integer value */
  32         INTEGER((byte) 0),
  33         /** 64-bit integer value */
  34         LONG((byte) 1),
  35         /** IEEE 754 double precision number */
  36         DOUBLE((byte) 2),
  37         /** Variable-length string value */
  38         STRING((byte) 3);
  39
  40         private final byte fTypeByte;
  41
  42         private Type(byte type) {
  43             fTypeByte = type;
  44         }
  45
  46         /**
  47          * Get the corresponding Type from its byte representation.
  48          *
  49          * @param type
  50          *            The type byte
  51          * @return The corresponding Type enum element
  52          * @throws IllegalArgumentException
  53          *             If the type byte is not recognized
  54          * @since 2.0
  55          */
  56         public static Type getTypeFromByte(byte type) {
  57             switch (type) {
  58             case -1:
  59                 return NULL;
  60             case 0:
  61                 return INTEGER;
  62             case 1:
  63                 return LONG;
  64             case 2:
  65                 return DOUBLE;
  66             case 3:
  67                 return STRING;
  68             default:
  69                 throw new IllegalArgumentException();
  70             }
  71         }
  72
  73         /**
  74          * Get the byte representation of this type.
  75          *
  76          * @return The type byte
  77          * @since 2.0
  78          */
  79         public byte getByte() {
  80             return fTypeByte;
  81         }
  82     }
  83
  84     /**
  85      * Each implementation has to define which one (among the supported types)
  86      * they implement. There could be more than one implementation of each type,
  87      * depending on the needs of the different users.
  88      *
  89      * @return The ITmfStateValue.Type enum representing the type of this value
  90      */
  91     Type getType();
  92
  93     /**
  94      * Only "null values" should return true here
  95      *
  96      * @return True if this type of SV is considered "null", false if it
  97      *         contains a real value.
  98      */
  99     boolean isNull();
 100
 101     /**
 102      * Read the contained value as an 'int' primitive
 103      *
 104      * @return The integer contained in the state value
 105      * @throws StateValueTypeException
 106      *             If the contained value cannot be read as an integer
 107      */
 108     int unboxInt();
 109
 110     /**
 111      * Read the contained value as a 'long' primitive
 112      *
 113      * @return The long contained in the state value
 114      * @throws StateValueTypeException
 115      *             If the contained value cannot be read as a long
 116      */
 117     long unboxLong();
 118
 119     /**
 120      * Read the contained value as a 'double' primitive
 121      *
 122      * @return The double contained in the state value
 123      * @throws StateValueTypeException
 124      *             If the contained value cannot be read as a double
 125      */
 126     double unboxDouble();
 127
 128     /**
 129      * Read the contained value as a String
 130      *
 131      * @return The String contained in the state value
 132      * @throws StateValueTypeException
 133      *             If the contained value cannot be read as a String
 134      */
 135     String unboxStr();
 136
 137     /**
 138      * Serialize this state value into a byte array.
 139      *
 140      * The format of this array should always be:
 141      *
 142      * <pre>[type byte][payload]</pre>
 143      *
 144      * and the type will determine the layout of [payload].
 145      *
 146      * @return The serialized form of the state value
 147      * @since 2.0
 148      */
 149     byte[] serialize();
 150
 151 }