ctf/org.eclipse.tracecompass.ctf.core/src/org/eclipse/tracecompass/ctf/core/event/types/IDeclaration.java

   1 /*******************************************************************************
   2  * Copyright (c) 2011, 2014 Ericsson, Ecole Polytechnique de Montreal and others
   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: Matthew Khouzam - Initial API and implementation
  10  * Contributors: Simon Marchi - Initial API and implementation
  11  *******************************************************************************/
  12
  13 package org.eclipse.tracecompass.ctf.core.event.types;
  14
  15 import org.eclipse.jdt.annotation.NonNull;
  16 import org.eclipse.tracecompass.ctf.core.CTFException;
  17 import org.eclipse.tracecompass.ctf.core.event.io.BitBuffer;
  18 import org.eclipse.tracecompass.ctf.core.event.scope.IDefinitionScope;
  19 import org.eclipse.tracecompass.ctf.core.event.scope.ILexicalScope;
  20
  21 /**
  22  * A CTF data type declaration.
  23  *
  24  * An example: <br>
  25  * int i = 0; <br>
  26  * <b>int</b> is the declaration.<br>
  27  * <b>i</b> is the definition.<br>
  28  * <b>0</b> is the value assigned to the definition, not the declaration.<br>
  29  *
  30  * @version 1.0
  31  * @author Matthew Khouzam
  32  * @author Simon Marchi
  33  */
  34 public interface IDeclaration {
  35
  36     /**
  37      * Create a definition from this declaration
  38      *
  39      * @param definitionScope
  40      *            the definition scope, the parent where the definition will be
  41      *            placed
  42      * @param fieldName
  43      *            the name of the definition
  44      * @param input
  45      *            a bitbuffer to read from
  46      * @return a reference to the definition
  47      * @throws CTFException
  48      *             error in reading
  49      */
  50     @NonNull Definition createDefinition(IDefinitionScope definitionScope, @NonNull String fieldName, @NonNull BitBuffer input) throws CTFException;
  51
  52     /**
  53      * Get the path of a definition
  54      *
  55      * @param definitionScope
  56      *            the scope of the definition
  57      * @param fieldName
  58      *            the name of the definition
  59      * @return the path of the definition
  60      * @since 1.0
  61      */
  62     @NonNull ILexicalScope getPath(IDefinitionScope definitionScope, @NonNull String fieldName);
  63
  64     /**
  65      * The minimum alignment. if the field is 32 bits, the definition will pad
  66      * all the data up to (position%32==0)
  67      *
  68      * @return the alignment in bits
  69      */
  70     long getAlignment();
  71
  72     /**
  73      * The MAXIMUM size of this declaration (in bits).
  74      *
  75      * @return the maximum size
  76      */
  77     int getMaximumSize();
  78
  79     @Override
  80     int hashCode();
  81
  82     @Override
  83     boolean equals(Object other);
  84
  85     /**
  86      * Are the two declarations equivalent on a binary level. eg: an 8 bit
  87      * little endian and big endian int.
  88      *
  89      * @param other
  90      *            the other {@link IDeclaration}
  91      * @return true if the binary CTF stream will generate the same value with
  92      *         the two streams
  93      */
  94     boolean isBinaryEquivalent(IDeclaration other);
  95
  96 }