ctf/org.eclipse.tracecompass.ctf.core/src/org/eclipse/tracecompass/ctf/core/trace/ICTFStream.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.trace;
  14
  15 import java.util.List;
  16 import java.util.Set;
  17
  18 import org.eclipse.jdt.annotation.NonNull;
  19 import org.eclipse.jdt.annotation.Nullable;
  20 import org.eclipse.tracecompass.ctf.core.event.IEventDeclaration;
  21 import org.eclipse.tracecompass.ctf.core.event.types.IDeclaration;
  22 import org.eclipse.tracecompass.ctf.core.event.types.StructDeclaration;
  23 import org.eclipse.tracecompass.internal.ctf.core.event.EventDeclaration;
  24
  25 /**
  26  * An _event stream_ can be divided into contiguous event packets of variable
  27  * size. An event packet can contain a certain amount of padding at the end. The
  28  * stream header is repeated at the beginning of each event packet. The
  29  * rationale for the event stream design choices is explained in
  30  * <a href="http://diamon.org/ctf/#specB" >Stream header rationale<a/>.
  31  * <p>
  32  *
  33  * The event stream header will therefore be referred to as the _event packet
  34  * header_ throughout the rest of this document.
  35  *
  36  * @author Matthew Khouzam
  37  * @author Efficios - Javadoc
  38  * @since 2.0
  39  */
  40 public interface ICTFStream {
  41
  42     /**
  43      * Gets the id of a stream
  44      *
  45      * @return id the id of a stream
  46      * @since 1.0
  47      */
  48     long getId();
  49
  50     /**
  51      * Is the id of a stream set
  52      *
  53      * @return If the ID is set or not
  54      */
  55     boolean isIdSet();
  56
  57     /**
  58      *
  59      * @return is the event header set (timestamp and stuff) (see Ctf Spec)
  60      */
  61     boolean isEventHeaderSet();
  62
  63     /**
  64      *
  65      * @return is the event context set (pid and stuff) (see Ctf Spec)
  66      */
  67     boolean isEventContextSet();
  68
  69     /**
  70      *
  71      * @return Is the packet context set (see Ctf Spec)
  72      */
  73     boolean isPacketContextSet();
  74
  75     /**
  76      * Gets the event header declaration
  77      *
  78      * @return the event header declaration in declaration form
  79      */
  80     IDeclaration getEventHeaderDeclaration();
  81
  82     /**
  83      *
  84      * @return the event context declaration in structdeclaration form
  85      */
  86     StructDeclaration getEventContextDecl();
  87
  88     /**
  89      *
  90      * @return the packet context declaration in structdeclaration form
  91      */
  92     StructDeclaration getPacketContextDecl();
  93
  94     /**
  95      *
  96      * @return the set of all stream inputs for this stream
  97      */
  98     Set<CTFStreamInput> getStreamInputs();
  99
 100     /**
 101      *
 102      * @return the parent trace
 103      */
 104     CTFTrace getTrace();
 105
 106     /**
 107      * Get all the event declarations in this stream.
 108      *
 109      * @return The event declarations for this stream
 110      * @since 2.0
 111      */
 112     @NonNull
 113     List<@Nullable IEventDeclaration> getEventDeclarations();
 114
 115     /**
 116      * Get the event declaration for a given ID.
 117      *
 118      * @param eventId
 119      *            The ID, can be {@link EventDeclaration#UNSET_EVENT_ID}, or any
 120      *            positive value
 121      * @return The event declaration with the given ID for this stream, or
 122      *         'null' if there are no declaration with this ID
 123      * @throws IllegalArgumentException
 124      *             If the passed ID is invalid
 125      */
 126     @Nullable
 127     IEventDeclaration getEventDeclaration(int eventId);
 128
 129 }