org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFStream.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.linuxtools.ctf.core.trace;
  14
  15 import java.util.ArrayList;
  16 import java.util.Collection;
  17 import java.util.Collections;
  18 import java.util.HashSet;
  19 import java.util.List;
  20 import java.util.Map;
  21 import java.util.Set;
  22
  23 import org.eclipse.jdt.annotation.NonNull;
  24 import org.eclipse.jdt.annotation.Nullable;
  25 import org.eclipse.linuxtools.ctf.core.event.IEventDeclaration;
  26 import org.eclipse.linuxtools.ctf.core.event.types.IDeclaration;
  27 import org.eclipse.linuxtools.ctf.core.event.types.IEventHeaderDeclaration;
  28 import org.eclipse.linuxtools.ctf.core.event.types.StructDeclaration;
  29 import org.eclipse.linuxtools.internal.ctf.core.event.EventDeclaration;
  30 import org.eclipse.linuxtools.internal.ctf.core.event.metadata.exceptions.ParseException;
  31
  32 /**
  33  * <b><u>Stream</u></b>
  34  * <p>
  35  * Represents a stream in a trace.
  36  *
  37  * @since 3.0
  38  */
  39 public class CTFStream {
  40
  41     // ------------------------------------------------------------------------
  42     // Attributes
  43     // ------------------------------------------------------------------------
  44
  45     /**
  46      * The numerical ID of the stream
  47      */
  48     private Long fId = null;
  49
  50     /**
  51      * Declarations of the stream-specific structures
  52      */
  53     private StructDeclaration fPacketContextDecl = null;
  54     private IDeclaration fEventHeaderDecl = null;
  55     private StructDeclaration fEventContextDecl = null;
  56
  57     /**
  58      * The trace to which the stream belongs
  59      */
  60     private CTFTrace fTrace = null;
  61
  62     /**
  63      * Maps event ids to events
  64      */
  65     private final ArrayList<IEventDeclaration> fEvents = new ArrayList<>();
  66
  67     private boolean fEventUnsetId = false;
  68
  69     /**
  70      * The inputs associated to this stream
  71      */
  72     private final Set<CTFStreamInput> fInputs = new HashSet<>();
  73
  74     // ------------------------------------------------------------------------
  75     // Constructors
  76     // ------------------------------------------------------------------------
  77
  78     /**
  79      * Constructs a Stream that belongs to a Trace
  80      *
  81      * @param trace
  82      *            The trace to which belongs this stream.
  83      */
  84     public CTFStream(CTFTrace trace) {
  85         fTrace = trace;
  86     }
  87
  88     // ------------------------------------------------------------------------
  89     // Getters/Setters/Predicates
  90     // ------------------------------------------------------------------------
  91
  92     /**
  93      * Sets the id of a stream
  94      *
  95      * @param id
  96      *            the id of a stream
  97      */
  98     public void setId(long id) {
  99         fId = id;
 100     }
 101
 102     /**
 103      * Gets the id of a stream
 104      *
 105      * @return id the id of a stream
 106      */
 107     public Long getId() {
 108         return fId;
 109     }
 110
 111     /**
 112      * Is the id of a stream set
 113      *
 114      * @return If the ID is set or not
 115      */
 116     public boolean isIdSet() {
 117         return fId != null;
 118     }
 119
 120     /**
 121      *
 122      * @return is the event header set (timestamp and stuff) (see Ctf Spec)
 123      */
 124     public boolean isEventHeaderSet() {
 125         return fEventHeaderDecl != null;
 126     }
 127
 128     /**
 129      *
 130      * @return is the event context set (pid and stuff) (see Ctf Spec)
 131      */
 132     public boolean isEventContextSet() {
 133         return fEventContextDecl != null;
 134     }
 135
 136     /**
 137      *
 138      * @return Is the packet context set (see Ctf Spec)
 139      */
 140     public boolean isPacketContextSet() {
 141         return fPacketContextDecl != null;
 142     }
 143
 144     /**
 145      * Sets the event header
 146      *
 147      * @param eventHeader
 148      *            the current event header for all events in this stream
 149      */
 150     public void setEventHeader(StructDeclaration eventHeader) {
 151         fEventHeaderDecl = eventHeader;
 152     }
 153
 154     /**
 155      * Sets the event header, this typically has the id and the timestamp
 156      *
 157      * @param eventHeader
 158      *            the current event header for all events in this stream
 159      * @since 3.1
 160      */
 161     public void setEventHeader(IEventHeaderDeclaration eventHeader) {
 162         fEventHeaderDecl = eventHeader;
 163     }
 164
 165     /**
 166      *
 167      * @param eventContext
 168      *            the context for all events in this stream
 169      */
 170     public void setEventContext(StructDeclaration eventContext) {
 171         fEventContextDecl = eventContext;
 172     }
 173
 174     /**
 175      *
 176      * @param packetContext
 177      *            the packet context for all packets in this stream
 178      */
 179     public void setPacketContext(StructDeclaration packetContext) {
 180         fPacketContextDecl = packetContext;
 181     }
 182
 183     /**
 184      *
 185      * @return the event header declaration in structdeclaration form
 186      * @deprecated use {@link CTFStream#getEventHeaderDeclaration()}
 187      */
 188     @Deprecated
 189     public StructDeclaration getEventHeaderDecl() {
 190         return (StructDeclaration) ((fEventHeaderDecl instanceof StructDeclaration) ? fEventHeaderDecl : null);
 191     }
 192
 193     /**
 194      * Gets the event header declaration
 195      *
 196      * @return the event header declaration in declaration form
 197      * @since 3.1
 198      */
 199     public IDeclaration getEventHeaderDeclaration() {
 200         return fEventHeaderDecl;
 201     }
 202
 203     /**
 204      *
 205      * @return the event context declaration in structdeclaration form
 206      */
 207     public StructDeclaration getEventContextDecl() {
 208         return fEventContextDecl;
 209     }
 210
 211     /**
 212      *
 213      * @return the packet context declaration in structdeclaration form
 214      */
 215     public StructDeclaration getPacketContextDecl() {
 216         return fPacketContextDecl;
 217     }
 218
 219     /**
 220      *
 221      * @return the set of all stream inputs for this stream
 222      */
 223     public Set<CTFStreamInput> getStreamInputs() {
 224         return fInputs;
 225     }
 226
 227     /**
 228      *
 229      * @return the parent trace
 230      */
 231     public CTFTrace getTrace() {
 232         return fTrace;
 233     }
 234
 235     /**
 236      *
 237      * @return all the event declarations for this stream, using the id as a key
 238      *         for the hashmap.
 239      * @deprecated use {@link CTFStream#getEventDeclarations()}
 240      */
 241     @Deprecated
 242     public Map<Long, IEventDeclaration> getEvents() {
 243         throw new UnsupportedOperationException();
 244     }
 245
 246     /**
 247      * Get all the event declarations in this stream.
 248      *
 249      * @return The event declarations for this stream
 250      * @since 3.2
 251      */
 252     public @NonNull Collection<IEventDeclaration> getEventDeclarations() {
 253         List<IEventDeclaration> retVal = new ArrayList<>(fEvents);
 254         retVal.removeAll(Collections.<IEventDeclaration> singletonList(null));
 255         return retVal;
 256     }
 257
 258     /**
 259      * Get the event declaration for a given ID.
 260      *
 261      * @param eventId
 262      *            The ID, can be {@link EventDeclaration#UNSET_EVENT_ID}, or any
 263      *            positive value
 264      * @return The event declaration with the given ID for this stream, or
 265      *         'null' if there are no declaration with this ID
 266      * @throws IllegalArgumentException
 267      *             If the passed ID is invalid
 268      * @since 3.2
 269      */
 270     public @Nullable IEventDeclaration getEventDeclaration(int eventId) {
 271         int eventIndex = (eventId == EventDeclaration.UNSET_EVENT_ID) ? 0 : eventId;
 272         if (eventIndex < 0) {
 273             /* Any negative value other than UNSET_EVENT_ID is invalid */
 274             throw new IllegalArgumentException("Event ID cannot be negative."); //$NON-NLS-1$
 275         }
 276         if (eventIndex >= fEvents.size()) {
 277             /* This ID could be valid, but there are no declarations with it */
 278             return null;
 279         }
 280         return fEvents.get(eventIndex);
 281     }
 282
 283     // ------------------------------------------------------------------------
 284     // Operations
 285     // ------------------------------------------------------------------------
 286
 287     /**
 288      * Adds an event to the event list.
 289      *
 290      * An event in a stream can omit its id if it is the only event in this
 291      * stream. An event for which no id has been specified has a null id. It is
 292      * thus not possible to add an event with the null key if the map is not
 293      * empty. It is also not possible to add an event to the map if the null key
 294      * is present in the map.
 295      *
 296      * @param event
 297      *            The event to add
 298      * @throws ParseException
 299      *             If there was a problem reading the event or adding it to the
 300      *             stream
 301      */
 302     public void addEvent(IEventDeclaration event) throws ParseException {
 303         if (fEventUnsetId) {
 304             throw new ParseException("Event without id with multiple events in a stream"); //$NON-NLS-1$
 305         }
 306         int id = ((EventDeclaration) event).id();
 307
 308         /*
 309          * If there is an event without id (the null key), it must be the only
 310          * one
 311          */
 312         if (id == EventDeclaration.UNSET_EVENT_ID) {
 313             if (!fEvents.isEmpty()) {
 314                 throw new ParseException("Event without id with multiple events in a stream"); //$NON-NLS-1$
 315             }
 316             fEventUnsetId = true;
 317             fEvents.add(event);
 318         } else {
 319             /* Check if an event with the same ID already exists */
 320             if (fEvents.size() > id && fEvents.get(id) != null) {
 321                 throw new ParseException("Event id already exists"); //$NON-NLS-1$
 322             }
 323             ensureSize(fEvents, id);
 324             /* Put the event in the list */
 325             fEvents.set(id, event);
 326         }
 327     }
 328
 329     /**
 330      * Add a list of event declarations to this stream. There must be no overlap
 331      * between the two lists of event declarations. This will merge the two
 332      * lists and preserve the indexes of both lists.
 333      *
 334      * @param events
 335      *            list of the events to add
 336      * @throws CTFReaderException
 337      *             if the list already contains data
 338      * @since 3.2
 339      */
 340     public void addEvents(Collection<IEventDeclaration> events) throws CTFReaderException {
 341         if (fEventUnsetId) {
 342             throw new CTFReaderException("Cannot add to a stream with an unidentified event"); //$NON-NLS-1$
 343         }
 344         if (fEvents.isEmpty()) {
 345             fEvents.addAll(events);
 346             return;
 347         }
 348         for (IEventDeclaration event : events) {
 349             if (event != null) {
 350                 int index = event.getId().intValue();
 351                 ensureSize(fEvents, index);
 352                 if (fEvents.get(index) != null) {
 353                     throw new CTFReaderException("Both lists have an event defined at position " + index); //$NON-NLS-1$
 354                 }
 355                 fEvents.set(index, event);
 356             }
 357         }
 358     }
 359
 360     private static void ensureSize(ArrayList<? extends Object> list, int index) {
 361         list.ensureCapacity(index);
 362         while (list.size() <= index) {
 363             list.add(null);
 364         }
 365     }
 366
 367     /**
 368      * Add an input to this Stream
 369      *
 370      * @param input
 371      *            The StreamInput to add.
 372      */
 373     public void addInput(CTFStreamInput input) {
 374         fInputs.add(input);
 375     }
 376
 377     @Override
 378     public String toString() {
 379         return "Stream [id=" + fId + ", packetContextDecl=" + fPacketContextDecl //$NON-NLS-1$ //$NON-NLS-2$
 380                 + ", eventHeaderDecl=" + fEventHeaderDecl //$NON-NLS-1$
 381                 + ", eventContextDecl=" + fEventContextDecl + ", trace=" + fTrace //$NON-NLS-1$ //$NON-NLS-2$
 382                 + ", events=" + fEvents + ", inputs=" + fInputs + "]"; //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
 383     }
 384 }