ctf/org.eclipse.tracecompass.ctf.core/src/org/eclipse/tracecompass/ctf/core/event/IEventDeclaration.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  *******************************************************************************/
  11
  12 package org.eclipse.tracecompass.ctf.core.event;
  13
  14 import java.util.Collections;
  15 import java.util.List;
  16 import java.util.Set;
  17
  18 import org.eclipse.jdt.annotation.NonNull;
  19 import org.eclipse.tracecompass.ctf.core.CTFException;
  20 import org.eclipse.tracecompass.ctf.core.event.io.BitBuffer;
  21 import org.eclipse.tracecompass.ctf.core.event.types.StructDeclaration;
  22 import org.eclipse.tracecompass.ctf.core.trace.CTFStreamInputReader;
  23 import org.eclipse.tracecompass.ctf.core.trace.ICTFStream;
  24 import org.eclipse.tracecompass.internal.ctf.core.trace.CTFStream;
  25
  26 /**
  27  * Representation of one type of event. A bit like "int" or "long" but for trace
  28  * events.
  29  *
  30  * @author Matthew Khouzam
  31  */
  32 public interface IEventDeclaration {
  33
  34     /**
  35      * Id of events when not set
  36      *
  37      * @since 1.0
  38      */
  39     public static final long UNSET_EVENT_ID = -2L;
  40
  41     /**
  42      * Creates an instance of {@link IEventDefinition} corresponding to this
  43      * declaration.
  44      *
  45      * @param streamInputReader
  46      *            The {@link CTFStreamInputReader} for which this definition is
  47      *            created.
  48      * @param input
  49      *            the {@link BitBuffer} input source
  50      * @param timestamp
  51      *            The timestamp when the event was taken
  52      * @return A new {@link IEventDefinition}
  53      * @throws CTFException
  54      *             As a bitbuffer is used to read, it could have wrapped
  55      *             IOExceptions.
  56      * @since 2.0
  57      */
  58     IEventDefinition createDefinition(CTFStreamInputReader streamInputReader, @NonNull BitBuffer input, long timestamp) throws CTFException;
  59
  60     /**
  61      * Gets the name of an event declaration
  62      *
  63      * @return the name
  64      */
  65     String getName();
  66
  67     /**
  68      * Gets the fields of an event declaration
  69      *
  70      * @return fields the fields in {@link StructDeclaration} format
  71      */
  72     StructDeclaration getFields();
  73
  74     /**
  75      * Gets the context of an event declaration
  76      *
  77      * @return context the fields in {@link StructDeclaration} format
  78      */
  79     StructDeclaration getContext();
  80
  81     /**
  82      * Gets the id of an event declaration
  83      *
  84      * @return The EventDeclaration ID
  85      */
  86     Long getId();
  87
  88     /**
  89      * Gets the {@link CTFStream} of an event declaration
  90      *
  91      * @return the stream
  92      * @since 2.0
  93      */
  94     ICTFStream getStream();
  95
  96     /**
  97      * What is the log level of this event?
  98      *
  99      * @return the log level.
 100      */
 101     long getLogLevel();
 102
 103     /**
 104      * Get the {@link Set} of names of the custom CTF attributes.
 105      *
 106      * @return The set of custom attributes
 107      */
 108     @NonNull
 109     Set<@NonNull String> getCustomAttributes();
 110
 111     /**
 112      * Get the value of a given CTF attribute.
 113      *
 114      * @param key
 115      *            The CTF attribute name
 116      * @return the CTF attribute
 117      */
 118     String getCustomAttribute(String key);
 119
 120     /**
 121      * Gets the potential static call sites of an event
 122      *
 123      * @return the collection of call sites of an event
 124      * @since 2.1
 125      */
 126     default @NonNull List<@NonNull CTFCallsite> getCallsites() {
 127         return Collections.emptyList();
 128     }
 129
 130 }