From 9ac2eb62ce40169e4da395b9128c511e1ec8dbca Mon Sep 17 00:00:00 2001 From: Matthew Khouzam Date: Wed, 6 Jun 2012 18:29:38 -0400 Subject: [PATCH] Improve javadoc for ctfAdapter in Tmf.Core Improve javadoc for Ctf.Core Signed-off-by: Matthew Khouzam --- .../ctf/core/tests/trace/StreamTest.java | 8 +- .../ctf/core/tests/types/DefinitionTest.java | 11 +- .../core/tests/types/EnumDeclarationTest.java | 11 -- .../ctf/core/event/EventDeclaration.java | 70 +++++++++- .../ctf/core/event/EventDefinition.java | 45 ++++++- .../core/event/types/ArrayDeclaration.java | 13 ++ .../ctf/core/event/types/ArrayDefinition.java | 12 ++ .../ctf/core/event/types/Definition.java | 31 ++++- .../ctf/core/event/types/Encoding.java | 7 +- .../ctf/core/event/types/EnumDeclaration.java | 46 ++++--- .../ctf/core/event/types/EnumDefinition.java | 23 ++++ .../core/event/types/FloatDeclaration.java | 14 +- .../ctf/core/event/types/FloatDefinition.java | 28 ++++ .../ctf/core/event/types/IDeclaration.java | 16 +++ .../core/event/types/IDefinitionScope.java | 4 + .../core/event/types/IntegerDeclaration.java | 38 ++++++ .../core/event/types/IntegerDefinition.java | 15 +++ .../core/event/types/SequenceDeclaration.java | 20 ++- .../core/event/types/SequenceDefinition.java | 54 ++++++-- .../core/event/types/StringDeclaration.java | 27 ++-- .../core/event/types/StringDefinition.java | 23 ++++ .../core/event/types/StructDeclaration.java | 44 +++++- .../core/event/types/StructDefinition.java | 76 ++++++++++- .../core/event/types/VariantDeclaration.java | 28 ++++ .../core/event/types/VariantDefinition.java | 125 ++++++++++++++++-- .../linuxtools/ctf/core/trace/CTFTrace.java | 43 ++++++ .../ctf/core/trace/CTFTraceReader.java | 22 ++- .../core/trace/StreamInputPacketReader.java | 64 ++++++++- .../ctf/core/trace/StreamInputReader.java | 48 ++++++- .../linuxtools/ctf/core/trace/Utils.java | 4 +- .../internal/ctf/core/Activator.java | 29 +++- .../internal/ctf/core/event/io/BitBuffer.java | 89 ++++++++++++- .../ctf/core/event/metadata/CTFStrings.java | 51 ++++++- .../ctf/core/event/metadata/IOStructGen.java | 19 ++- .../metadata/exceptions/ParseException.java | 5 +- .../internal/ctf/core/trace/Stream.java | 68 +++++++++- .../internal/ctf/core/trace/StreamInput.java | 34 +++++ .../core/trace/StreamInputPacketIndex.java | 13 ++ .../trace/StreamInputPacketIndexEntry.java | 1 - .../tmf/core/ctfadaptor/CtfIterator.java | 4 +- .../tmf/core/ctfadaptor/CtfLocation.java | 3 + .../tmf/core/ctfadaptor/CtfTmfEventType.java | 5 + .../tmf/core/ctfadaptor/CtfTmfTimestamp.java | 17 ++- .../tmf/core/ctfadaptor/CtfTmfTrace.java | 10 +- 44 files changed, 1207 insertions(+), 111 deletions(-) diff --git a/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/trace/StreamTest.java b/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/trace/StreamTest.java index 8b1cec41b0..8f11bf7a0c 100644 --- a/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/trace/StreamTest.java +++ b/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/trace/StreamTest.java @@ -92,7 +92,7 @@ public class StreamTest { */ @Test public void testEventContextIsSet() { - assertTrue(fixture.eventContextIsSet()); + assertTrue(fixture.isEventContextSet()); } /** * Run the boolean eventContextIsSet() method test. @@ -107,7 +107,7 @@ public class StreamTest { */ @Test public void testEventHeaderIsSet() { - assertTrue(fixture.eventHeaderIsSet()); + assertTrue(fixture.isEventHeaderSet()); } /** @@ -176,7 +176,7 @@ public class StreamTest { */ @Test public void testIdIsSet() { - boolean result = fixture.idIsSet(); + boolean result = fixture.isIdSet(); assertTrue(result); } @@ -185,7 +185,7 @@ public class StreamTest { */ @Test public void testPacketContextIsSet() { - boolean result = fixture.packetContextIsSet(); + boolean result = fixture.isPacketContextSet(); assertTrue(result); } diff --git a/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/types/DefinitionTest.java b/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/types/DefinitionTest.java index b49eb82f76..f2789bc664 100644 --- a/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/types/DefinitionTest.java +++ b/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/types/DefinitionTest.java @@ -3,6 +3,7 @@ package org.eclipse.linuxtools.ctf.core.tests.types; import static org.junit.Assert.assertNotNull; import org.eclipse.linuxtools.ctf.core.event.types.Definition; +import org.eclipse.linuxtools.ctf.core.event.types.IDeclaration; import org.eclipse.linuxtools.ctf.core.event.types.IDefinitionScope; import org.eclipse.linuxtools.internal.ctf.core.event.io.BitBuffer; import org.junit.After; @@ -12,7 +13,7 @@ import org.junit.Test; /** * The class DefinitionTest contains tests for the class * {@link Definition}. - * + * * @author ematkho * @version $Revision: 1.0 $ */ @@ -20,7 +21,7 @@ public class DefinitionTest { /** * Launch the test. - * + * * @param args * the command line arguments */ @@ -59,6 +60,12 @@ public class DefinitionTest { /* Just a test, no need to implement anything */ } + @Override + public IDeclaration getDeclaration() { + // TODO Auto-generated method stub + return null; + } + } @Test diff --git a/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/types/EnumDeclarationTest.java b/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/types/EnumDeclarationTest.java index 89ab4edf6f..dbfc406e7b 100644 --- a/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/types/EnumDeclarationTest.java +++ b/org.eclipse.linuxtools.ctf.core.tests/src/org/eclipse/linuxtools/ctf/core/tests/types/EnumDeclarationTest.java @@ -98,17 +98,6 @@ public class EnumDeclarationTest { assertNotNull(result); } - /** - * Run the String getLabel(long) method test. - */ - @Test - public void testGetLabel() { - long i = 0; - String result = fixture.getLabel(i); - - assertNull(result); - } - /** * Run the String query(long) method test. */ diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/EventDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/EventDeclaration.java index 8a118a464f..3f45e0c3eb 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/EventDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/EventDeclaration.java @@ -85,7 +85,7 @@ public class EventDeclaration { /** * Creates a "lost" event. This is a synthetic event that is there to show * that there should be something there. - * @return + * @return the lost event */ public synchronized static EventDeclaration getLostEventDeclaration(){ EventDeclaration lostEvent = new EventDeclaration(); @@ -99,70 +99,138 @@ public class EventDeclaration { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Sets a name for an event Declaration + * @param name the name + */ public void setName(String name) { this.name = name; } + /** + * Gets the name of en event declaration + * @return the name + */ public String getName() { return name; } + /** + * Sets the context for an event declaration (see CTF specification) + * @param context the context in structdeclaration format + */ public void setContext(StructDeclaration context) { this.context = context; } + /** + * Sets the fields of an event declaration + * @param fields the fields in structdeclaration format + */ public void setFields(StructDeclaration fields) { this.fields = fields; } + /** + * Gets the fields of an event declaration + * @return fields the fields in structdeclaration format + */ public StructDeclaration getFields() { return fields; } + /** + * Gets the context of an event declaration + * @return context the fields in structdeclaration format + */ public StructDeclaration getContext() { return context; } + /** + * Sets the id of am event declaration + * @param id the id + */ public void setId(long id) { this.id = id; } + /** + * Gets the id of am event declaration + * return id the id + */ public Long getId() { return id; } + /** + * Sets the stream of am event declaration + * @param stream the stream + */ public void setStream(Stream stream) { this.stream = stream; } + /** + * Gets the stream of am event declaration + * @return stream the stream + */ public Stream getStream() { return stream; } + /** + * Is the name of the event declaration set + * @return is the name set? + */ public boolean nameIsSet() { return name != null; } + /** + * Is the context set + * @return is the context set + */ public boolean contextIsSet() { return context != null; } + /** + * Is a field set? + * @return Is the field set? + */ public boolean fieldsIsSet() { return fields != null; } + /** + * Is the id set? + * @return is the id set? + */ public boolean idIsSet() { return id != null; } + /** + * Is the stream set? + * @return is the stream set? + */ public boolean streamIsSet() { return stream != null; } + /** + * What is the log level of this event + * @return the log level. + */ public long getLogLevel() { return logLevel; } + /** + * Sets the log level + * @param level the log level + */ public void setLogLevel( long level){ logLevel = level; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/EventDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/EventDefinition.java index 455d6a8495..9ca6fee758 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/EventDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/EventDefinition.java @@ -81,26 +81,56 @@ public class EventDefinition implements IDefinitionScope { return "event"; //$NON-NLS-1$ } + /** + * Gets the declaration (the form) of the data + * + * @return the event declaration + */ public EventDeclaration getDeclaration() { return declaration; } + /** + * Gets the fields of a definition + * + * @return the fields of a definition in struct form. Can be null. + */ public StructDefinition getFields() { return fields; } + /** + * Gets the context of this event + * + * @return the context in struct form + */ public StructDefinition getContext() { return context; } + /** + * Gets the stream input reader that this event was made by + * + * @return the parent + */ public StreamInputReader getStreamInputReader() { return streamInputReader; } + /** + * Gets the context of packet the event is in. + * + * @return the packet context + */ public StructDefinition getPacketContext() { return streamInputReader.getCurrentPacketContext(); } + /** + * gets the CPU the event was generated by. Slightly LTTng specific + * + * @return The CPU the event was generated by + */ public int getCPU() { return streamInputReader.getCPU(); } @@ -113,21 +143,24 @@ public class EventDefinition implements IDefinitionScope { } /** - * @param timestamp the timestamp to set + * @param timestamp + * the timestamp to set */ public void setTimestamp(long timestamp) { this.timestamp = timestamp; } /** - * @param context the context to set + * @param context + * the context to set */ public void setContext(StructDefinition context) { this.context = context; } /** - * @param fields the fields to set + * @param fields + * the fields to set */ public void setFields(StructDefinition fields) { this.fields = fields; @@ -163,7 +196,8 @@ public class EventDefinition implements IDefinitionScope { list = context.getDeclaration().getFieldsList(); for (String field : list) { - retString.append(field + " : " + definitions.get(field).toString() + cr); //$NON-NLS-1$ + retString.append(field + + " : " + definitions.get(field).toString() + cr); //$NON-NLS-1$ } } @@ -172,7 +206,8 @@ public class EventDefinition implements IDefinitionScope { list = fields.getDeclaration().getFieldsList(); for (String field : list) { - retString.append(field + " : " + definitions.get(field).toString() + cr); //$NON-NLS-1$ + retString.append(field + + " : " + definitions.get(field).toString() + cr); //$NON-NLS-1$ } } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/ArrayDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/ArrayDeclaration.java index 84c5f599ec..c7ee915ff5 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/ArrayDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/ArrayDeclaration.java @@ -28,6 +28,11 @@ public class ArrayDeclaration implements IDeclaration { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * @param length how many elements in the array + * @param elemType what type of element is in the array + */ public ArrayDeclaration(int length, IDeclaration elemType) { this.length = length; this.elemType = elemType; @@ -37,10 +42,18 @@ public class ArrayDeclaration implements IDeclaration { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * + * @return the type of element in the array + */ public IDeclaration getElementType() { return elemType; } + /** + * + * @return how many elements in the array + */ public int getLength() { return length; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/ArrayDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/ArrayDefinition.java index da5cef3475..7f1f6e353b 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/ArrayDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/ArrayDefinition.java @@ -30,6 +30,12 @@ public class ArrayDefinition extends Definition { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * @param declaration the parent declaration + * @param definitionScope the parent scope + * @param fieldName the field name + */ public ArrayDefinition(ArrayDeclaration declaration, IDefinitionScope definitionScope, String fieldName) { super(definitionScope, fieldName); @@ -63,6 +69,11 @@ public class ArrayDefinition extends Definition { this.definitions = definitions; } + /** + * Get the element at i + * @param i the index (cannot be negative) + * @return The element at I, if I > length, null, if I < 0, the method throws an out of bounds exception + */ public Definition getElem(int i) { if (i > definitions.length) { return null; @@ -71,6 +82,7 @@ public class ArrayDefinition extends Definition { return definitions[i]; } + @Override public ArrayDeclaration getDeclaration() { return declaration; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/Definition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/Definition.java index a196611607..45351aa113 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/Definition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/Definition.java @@ -15,7 +15,14 @@ package org.eclipse.linuxtools.ctf.core.event.types; import org.eclipse.linuxtools.internal.ctf.core.event.io.BitBuffer; /** - * Definition + * Definition
+ * A definition is like an object of a declaration class. It fills the declaration with values.
+ * An example:
+ * int i = 0;
+ * int is the declaration.
+ * i is the definition.
+ * 0 is the value assigned to the definition, not the declaration.
+ * */ public abstract class Definition { @@ -41,6 +48,15 @@ public abstract class Definition { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * + * @param definitionScope + * the definition is in a scope, (normally a struct) what is it? + * @param fieldName + * the name of the definition. (it is a field in the parent + * scope) + */ public Definition(IDefinitionScope definitionScope, String fieldName) { this.definitionScope = definitionScope; this.fieldName = fieldName; @@ -65,6 +81,19 @@ public abstract class Definition { // Operations // ------------------------------------------------------------------------ + /** + * + * @return gets the declaration of a datatype + * + */ + public abstract IDeclaration getDeclaration(); + + /** + * Read the definition from a bitbuffer + * + * @param input + * the bitbuffer containing the data to read. + */ public abstract void read(BitBuffer input); @Override diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/Encoding.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/Encoding.java index 922c4ad9fe..a3de0160ba 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/Encoding.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/Encoding.java @@ -18,5 +18,10 @@ package org.eclipse.linuxtools.ctf.core.event.types; * Encoding types */ public enum Encoding { - UTF8, ASCII, NONE + /** UTF-8 encoding */ + UTF8, + /** Ascii encoding */ + ASCII, + /** No encoding, maybe not even text */ + NONE } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/EnumDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/EnumDeclaration.java index f1fa82cb44..6cd0bdbe5f 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/EnumDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/EnumDeclaration.java @@ -31,6 +31,15 @@ public class EnumDeclaration implements IDeclaration { // Constructors // ------------------------------------------------------------------------ + /** + * constructor + * + * @param containerType + * the enum is an int, this is the type that the data is + * contained in. If you have 1000 possible values, you need at + * least a 10 bit enum. If you store 2 values in a 128 bit int, + * you are wasting space. + */ public EnumDeclaration(IntegerDeclaration containerType) { this.containerType = containerType; } @@ -39,6 +48,10 @@ public class EnumDeclaration implements IDeclaration { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * + * @return The container type + */ public IntegerDeclaration getContainerType() { return containerType; } @@ -47,6 +60,7 @@ public class EnumDeclaration implements IDeclaration { public long getAlignment() { return this.getContainerType().getAlignment(); } + // ------------------------------------------------------------------------ // Operations // ------------------------------------------------------------------------ @@ -57,18 +71,26 @@ public class EnumDeclaration implements IDeclaration { return new EnumDefinition(this, definitionScope, fieldName); } + /** + * Add a value. Do not overlap, this is not an interval tree. + * @param low lowest value that this int can be to have label as a return string + * @param high highest value that this int can be to have label as a return string + * @param label the name of the value. + * @return was the value be added? true == success + */ public boolean add(long low, long high, String label) { return table.add(low, high, label); } + /** + * check if the label for a value (enum a{day=0,night=1} would return "day" for query(0) + * @param value the value to lookup + * @return the label of that value, can be null + */ public String query(long value) { return table.query(value); } - public String getLabel(long i) { - return table.getLabel(i); - } - /* * Maps integer range -> string. A simple list for now, but feel free to * optimize it. Babeltrace suggests an interval tree. @@ -80,15 +102,6 @@ public class EnumDeclaration implements IDeclaration { public EnumTable() { } - public String getLabel(long i) { - for (Range r : ranges) { - if (r.intersects(i)) { - return r.str; - } - } - return null; - } - public boolean add(long low, long high, String label) { Range newRange = new Range(low, high, label); @@ -103,13 +116,17 @@ public class EnumDeclaration implements IDeclaration { return true; } + /** + * return the first label that matches a value + * @param value the value to query + * @return the label corresponding to that value + */ public String query(long value) { for (Range r : ranges) { if (r.intersects(value)) { return r.str; } } - return null; } @@ -141,5 +158,4 @@ public class EnumDeclaration implements IDeclaration { return "[declaration] enum[" + Integer.toHexString(hashCode()) + ']'; //$NON-NLS-1$ } - } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/EnumDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/EnumDefinition.java index 308b05a4c2..e1565f92ad 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/EnumDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/EnumDefinition.java @@ -33,6 +33,12 @@ public class EnumDefinition extends Definition { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * @param declaration the parent declaration + * @param definitionScope the parent scope + * @param fieldName the field name + */ public EnumDefinition(EnumDeclaration declaration, IDefinitionScope definitionScope, String fieldName) { super(definitionScope, fieldName); @@ -48,19 +54,36 @@ public class EnumDefinition extends Definition { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Gets the value of the enum in string format so "Enum a{DAY="0", NIGHT="1"}; will return "DAY" + * @return the value of the enum. + */ public String getValue() { return value; } + /** + * Gets the value of the enum in string format so "Enum a{DAY="0", NIGHT="1"}; will return 0 + * @return the value of the enum. + */ public long getIntegerValue() { return integerValue.getValue(); } + /** + * Sets the value of the enum in string format so "Enum a{DAY="0", NIGHT="1"}; will set 0 + * @param Value The value of the enum. + */ public void setIntegerValue(long Value) { integerValue.setValue(Value); value = ((Long) integerValue.getValue()).toString(); } + @Override + public EnumDeclaration getDeclaration() { + return declaration; + } + // ------------------------------------------------------------------------ // Operations // ------------------------------------------------------------------------ diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/FloatDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/FloatDeclaration.java index 293528f276..3d97dd4601 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/FloatDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/FloatDeclaration.java @@ -13,7 +13,12 @@ package org.eclipse.linuxtools.ctf.core.event.types; import java.nio.ByteOrder; - +/** + * Float declaration + * + * @author Matthew Khouzam + * + */ public class FloatDeclaration implements IDeclaration { // ------------------------------------------------------------------------ @@ -29,6 +34,13 @@ public class FloatDeclaration implements IDeclaration { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * @param exponent the exponent size in bits + * @param mantissa the mantissa size in bits (+1 for sign) (see ctf spec) + * @param byteOrder the byte order + * @param alignment the alignment + */ public FloatDeclaration(int exponent, int mantissa, ByteOrder byteOrder, long alignment) { mant = mantissa; diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/FloatDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/FloatDefinition.java index 397be25d7e..07bd50cd39 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/FloatDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/FloatDefinition.java @@ -13,6 +13,11 @@ package org.eclipse.linuxtools.ctf.core.event.types; import org.eclipse.linuxtools.internal.ctf.core.event.io.BitBuffer; +/** + * Float definition + * @author Matthew Khouzam + * + */ public class FloatDefinition extends Definition { // ------------------------------------------------------------------------ // Attributes @@ -25,6 +30,16 @@ public class FloatDefinition extends Definition { // Contructors // ------------------------------------------------------------------------ + /** + * Constructor + * + * @param declaration + * the parent declaration + * @param definitionScope + * the parent scope + * @param fieldName + * the field name + */ public FloatDefinition(FloatDeclaration declaration, IDefinitionScope definitionScope, String fieldName) { super(definitionScope, fieldName); @@ -35,14 +50,27 @@ public class FloatDefinition extends Definition { // Gettters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * THe value of a float stored, fit into a double. This should be extended + * for exotic floats if this is necessary. + * + * @return the value of the float field fit into a double. + */ public double getValue() { return value; } + /** + * Sets the value of the float + * + * @param val + * the value of the float + */ public void setValue(double val) { value = val; } + @Override public FloatDeclaration getDeclaration() { return declaration; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IDeclaration.java index 171bad33ef..1aba10e3c9 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IDeclaration.java @@ -17,8 +17,24 @@ package org.eclipse.linuxtools.ctf.core.event.types; */ public interface IDeclaration { + /** + * Create a definition from this declaration + * + * @param definitionScope + * the definition scope, the parent where the definition will be + * placed + * @param fieldName + * the name of the definition + * @return a reference to the definition + */ public Definition createDefinition(IDefinitionScope definitionScope, String fieldName); + /** + * The minimum alignment. if the field is 32 bits, the definition will pad + * all the data up to (position%32==0) + * + * @return the alignment in bits + */ public long getAlignment(); } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IDefinitionScope.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IDefinitionScope.java index b802251516..1d20b2d48b 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IDefinitionScope.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IDefinitionScope.java @@ -17,6 +17,10 @@ package org.eclipse.linuxtools.ctf.core.event.types; */ public interface IDefinitionScope { + /** + * Gets the path in a C style for the scope. + * @return the path + */ public String getPath(); /** diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IntegerDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IntegerDeclaration.java index 92283535ff..b8803786bf 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IntegerDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IntegerDeclaration.java @@ -35,6 +35,16 @@ public class IntegerDeclaration implements IDeclaration { // Constructors // ------------------------------------------------------------------------ + /** + * Contructor + * @param len the length in bits + * @param signed is the integer signed? false == unsigned + * @param base the base (10-16 are most common) + * @param byteOrder Big endian little endian or other + * @param encoding ascii, utf8 or none. + * @param clock the clock path, can be null + * @param alignment the minimum alignment + */ public IntegerDeclaration(int len, boolean signed, int base, ByteOrder byteOrder, Encoding encoding, String clock, long alignment) { this.length = len; @@ -50,26 +60,50 @@ public class IntegerDeclaration implements IDeclaration { // Gettters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Is the integer signed? + * @return the is the integer signed + */ public boolean isSigned() { return signed; } + /** + * get the integer base commonly decimal or hex + * @return the integer base + */ public int getBase() { return base; } + /** + * gets the byte order + * @return the byte order + */ public ByteOrder getByteOrder() { return byteOrder; } + /** + * get encoding, chars are 8 bit ints + * @return the encoding + */ public Encoding getEncoding() { return encoding; } + /** + * is the integer a character (8 bits and encoded?) + * @return is the integer a char + */ public boolean isCharacter() { return (length == 8) && (encoding != Encoding.NONE); } + /** + * How many bits is this int + * @return the length of the int + */ public int getLength() { return length; } @@ -79,6 +113,10 @@ public class IntegerDeclaration implements IDeclaration { return alignment; } + /** + * The integer's clock, since timestamps are stored in ints + * @return the integer's clock, can be null. (most often it is) + */ public String getClock(){ return clock; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IntegerDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IntegerDefinition.java index 499c7fd38d..312489775e 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IntegerDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/IntegerDefinition.java @@ -33,6 +33,12 @@ public class IntegerDefinition extends Definition { // Contructors // ------------------------------------------------------------------------ + /** + * Constructor + * @param declaration the parent declaration + * @param definitionScope the parent scope + * @param fieldName the field name + */ public IntegerDefinition(IntegerDeclaration declaration, IDefinitionScope definitionScope, String fieldName) { super(definitionScope, fieldName); @@ -43,14 +49,23 @@ public class IntegerDefinition extends Definition { // Gettters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Gets the value of the integer + * @return the value of the integer (in long) + */ public long getValue() { return value; } + /** + * Sets the value of an integer + * @param val the value + */ public void setValue(long val) { value = val; } + @Override public IntegerDeclaration getDeclaration() { return declaration; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/SequenceDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/SequenceDeclaration.java index 2ea5081bcb..3ee5bb4b54 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/SequenceDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/SequenceDeclaration.java @@ -15,7 +15,9 @@ package org.eclipse.linuxtools.ctf.core.event.types; import org.eclipse.linuxtools.ctf.core.trace.CTFReaderException; /** - * SequenceDeclaration + * SequenceDeclaration
+ * An array where the size is fixed but declared in the trace, unlike array + * where it is declared with a literal */ public class SequenceDeclaration implements IDeclaration { @@ -30,6 +32,13 @@ public class SequenceDeclaration implements IDeclaration { // Constructors // ------------------------------------------------------------------------ + /** + * Constuctor + * + * @param lengthName + * the name of the field describing the lenght + * @param elemType + */ public SequenceDeclaration(String lengthName, IDeclaration elemType) { this.elemType = elemType; this.lengthName = lengthName; @@ -39,10 +48,18 @@ public class SequenceDeclaration implements IDeclaration { // Gettters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Gets the element type + * @return the element type + */ public IDeclaration getElementType() { return elemType; } + /** + * Gets the name of the length field + * @return the name of the length field + */ public String getLengthName() { return lengthName; } @@ -51,6 +68,7 @@ public class SequenceDeclaration implements IDeclaration { public long getAlignment() { return getElementType().getAlignment(); } + // ------------------------------------------------------------------------ // Operations // ------------------------------------------------------------------------ diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/SequenceDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/SequenceDefinition.java index 1abe32784e..3ddb77eed2 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/SequenceDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/SequenceDefinition.java @@ -33,26 +33,38 @@ public class SequenceDefinition extends Definition { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * + * @param declaration + * the parent declaration + * @param definitionScope + * the parent scope + * @param fieldName + * the field name + */ public SequenceDefinition(SequenceDeclaration declaration, - IDefinitionScope definitionScope, String fieldName) throws CTFReaderException { + IDefinitionScope definitionScope, String fieldName) + throws CTFReaderException { super(definitionScope, fieldName); Definition lenDef = null; this.declaration = declaration; if (definitionScope != null) { - lenDef = definitionScope.lookupDefinition(declaration.getLengthName()); + lenDef = definitionScope.lookupDefinition(declaration + .getLengthName()); } - if (lenDef == null) { - throw new CTFReaderException("Sequence length field not found"); //$NON-NLS-1$ - } + if (lenDef == null) { + throw new CTFReaderException("Sequence length field not found"); //$NON-NLS-1$ + } - if (!(lenDef instanceof IntegerDefinition)) { - throw new CTFReaderException("Sequence length field not integer"); //$NON-NLS-1$ - } + if (!(lenDef instanceof IntegerDefinition)) { + throw new CTFReaderException("Sequence length field not integer"); //$NON-NLS-1$ + } - lengthDefinition = (IntegerDefinition) lenDef; + lengthDefinition = (IntegerDefinition) lenDef; if (this.lengthDefinition.getDeclaration().isSigned()) { throw new CTFReaderException("Sequence length must not be signed"); //$NON-NLS-1$ @@ -63,14 +75,29 @@ public class SequenceDefinition extends Definition { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + @Override public SequenceDeclaration getDeclaration() { return declaration; } + /** + * The length of the sequence in number of elements so a sequence of 5 + * GIANT_rediculous_long_ints is the same as a sequence of 5 bits. (5) + * + * @return the length of the sequence + */ public int getLength() { return currentLength; } + /** + * Get the element at i + * + * @param i + * the index (cannot be negative) + * @return The element at I, if I > length, null, if I < 0, the method + * throws an out of bounds exception + */ public Definition getElem(int i) { if (i > definitions.length) { return null; @@ -79,6 +106,10 @@ public class SequenceDefinition extends Definition { return definitions[i]; } + /** + * Is the sequence a null terminated string? + * @return true == is a string, false == is not a string + */ public boolean isString() { IntegerDeclaration elemInt; @@ -111,8 +142,9 @@ public class SequenceDefinition extends Definition { } for (; i < currentLength; i++) { - newDefinitions[i] = declaration.getElementType().createDefinition( - definitionScope, fieldName + "[" + i + "]"); //$NON-NLS-1$ //$NON-NLS-2$ + newDefinitions[i] = declaration.getElementType() + .createDefinition(definitionScope, + fieldName + "[" + i + "]"); //$NON-NLS-1$ //$NON-NLS-2$ } definitions = newDefinitions; diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StringDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StringDeclaration.java index 0f62d91732..d57229fca0 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StringDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StringDeclaration.java @@ -27,17 +27,16 @@ public class StringDeclaration implements IDeclaration { // Constructors // ------------------------------------------------------------------------ - public Encoding getEncoding() { - return encoding; - } - - // ------------------------------------------------------------------------ - // Constructors - // ------------------------------------------------------------------------ - + /** + * Generate a UTF8 string declaration + */ public StringDeclaration() { } + /** + * generate an encoded string declaration + * @param encoding the encoding, utf8 or ascii + */ public StringDeclaration(Encoding encoding) { this.encoding = encoding; } @@ -46,6 +45,18 @@ public class StringDeclaration implements IDeclaration { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * + * @return the character encoding. + */ + public Encoding getEncoding() { + return encoding; + } + + /** + * + * @param encoding the character encoding to set + */ public void setEncoding(Encoding encoding) { this.encoding = encoding; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StringDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StringDefinition.java index 8a4eb8733a..2661f31253 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StringDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StringDefinition.java @@ -31,6 +31,12 @@ public class StringDefinition extends Definition { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * @param declaration the parent declaration + * @param definitionScope the parent scope + * @param fieldName the field name + */ public StringDefinition(StringDeclaration declaration, IDefinitionScope definitionScope, String fieldName) { super(definitionScope, fieldName); @@ -44,22 +50,39 @@ public class StringDefinition extends Definition { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + @Override public StringDeclaration getDeclaration() { return declaration; } + /** + * Sets the string declaration + * @param declaration the declaration + */ public void setDeclaration(StringDeclaration declaration) { this.declaration = declaration; } + /** + * Gets the string + * @return the stringbuilder + */ public StringBuilder getString() { return string; } + /** + * Sets a stringbuilder for the definition + * @param string the stringbuilder + */ public void setString(StringBuilder string) { this.string = string; } + /** + * Gets the string (value) + * @return the string + */ public String getValue() { return string.toString(); } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StructDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StructDeclaration.java index 1772c9076b..9bc93a3f6a 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StructDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StructDeclaration.java @@ -33,6 +33,14 @@ public class StructDeclaration implements IDeclaration { // Constructors // ------------------------------------------------------------------------ + /** + * The struct declaration, add fields later + * + * @param align + * the minimum alignment of the struct. (if a struct is 8bit + * aligned and has a 32 bit aligned field, the struct becomes 32 + * bit aligned. + */ public StructDeclaration(long align) { this.maxAlign = Math.max(align, 1); } @@ -41,18 +49,35 @@ public class StructDeclaration implements IDeclaration { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Get current alignment + * @return the alignment of the struct and all its fields + */ public long getMaxAlign() { return maxAlign; } + /** + * Query if the struct has a given field + * @param name the name of the field, scopeless please + * @return does the field exist? + */ public boolean hasField(String name) { return this.fields.containsKey(name); } + /** + * get the fields of the struct in a map. Faster access time than a list. + * @return a HashMap of the fields (key is the name) + */ public HashMap getFields() { return this.fields; } + /** + * Gets the field list. Very important since the map of fields does not retain the order of the fields. + * @return the field list. + */ public List getFieldsList() { return this.fieldsList; } @@ -61,6 +86,7 @@ public class StructDeclaration implements IDeclaration { public long getAlignment() { return this.maxAlign; } + // ------------------------------------------------------------------------ // Operations // ------------------------------------------------------------------------ @@ -71,13 +97,17 @@ public class StructDeclaration implements IDeclaration { return new StructDefinition(this, definitionScope, fieldName); } + /** + * Add a field to the struct + * @param name the name of the field, scopeless + * @param declaration the declaration of the field + */ public void addField(String name, IDeclaration declaration) { this.fields.put(name, declaration); this.fieldsList.add(name); maxAlign = Math.max(maxAlign, declaration.getAlignment()); - if( maxAlign == 1 ) - { - maxAlign =1; + if (maxAlign == 1) { + maxAlign = 1; } } @@ -87,7 +117,9 @@ public class StructDeclaration implements IDeclaration { return "[declaration] struct[" + Integer.toHexString(hashCode()) + ']'; //$NON-NLS-1$ } - /* (non-Javadoc) + /* + * (non-Javadoc) + * * @see java.lang.Object#hashCode() */ @Override @@ -100,7 +132,9 @@ public class StructDeclaration implements IDeclaration { return result; } - /* (non-Javadoc) + /* + * (non-Javadoc) + * * @see java.lang.Object#equals(java.lang.Object) */ @Override diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StructDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StructDefinition.java index b5d8210514..2fb915e371 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StructDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/StructDefinition.java @@ -34,6 +34,16 @@ public class StructDefinition extends Definition implements IDefinitionScope { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * + * @param declaration + * the parent declaration + * @param definitionScope + * the parent scope + * @param fieldName + * the field name + */ public StructDefinition(StructDeclaration declaration, IDefinitionScope definitionScope, String structFieldName) { super(definitionScope, structFieldName); @@ -58,10 +68,14 @@ public class StructDefinition extends Definition implements IDefinitionScope { return path; } + /** + * @return The definitions of all the fields + */ public HashMap getDefinitions() { return definitions; } + @Override public StructDeclaration getDeclaration() { return declaration; } @@ -73,7 +87,8 @@ public class StructDefinition extends Definition implements IDefinitionScope { @Override public void read(BitBuffer input) { final int align = (int) declaration.getAlignment(); - int pos = input.position() + ((align-(input.position() % align))%align); + int pos = input.position() + + ((align - (input.position() % align)) % align); input.position(pos); final List fieldList = declaration.getFieldsList(); for (String fName : fieldList) { @@ -97,40 +112,96 @@ public class StructDefinition extends Definition implements IDefinitionScope { return retVal; } + /** + * Lookup an array in a struct. if the name returns a non-array (like an + * int) than the method returns null + * + * @param name + * the name of the array + * @return the array or null. + */ public ArrayDefinition lookupArray(String name) { Definition def = lookupDefinition(name); return (ArrayDefinition) ((def instanceof ArrayDefinition) ? def : null); } + /** + * Lookup an enum in a struct. if the name returns a non-enum (like an int) + * than the method returns null + * + * @param name + * the name of the enum + * @return the enum or null. + */ public EnumDefinition lookupEnum(String name) { Definition def = lookupDefinition(name); return (EnumDefinition) ((def instanceof EnumDefinition) ? def : null); } + /** + * Lookup an integer in a struct. if the name returns a non-integer (like an + * float) than the method returns null + * + * @param name + * the name of the integer + * @return the integer or null. + */ public IntegerDefinition lookupInteger(String name) { Definition def = lookupDefinition(name); return (IntegerDefinition) ((def instanceof IntegerDefinition) ? def : null); } + /** + * Lookup a sequence in a struct. if the name returns a non-sequence (like + * an int) than the method returns null + * + * @param name + * the name of the sequence + * @return the sequence or null. + */ public SequenceDefinition lookupSequence(String name) { Definition def = lookupDefinition(name); return (SequenceDefinition) ((def instanceof SequenceDefinition) ? def : null); } + /** + * Lookup a string in a struct. if the name returns a non-string (like + * an int) than the method returns null + * + * @param name + * the name of the string + * @return the string or null. + */ public StringDefinition lookupString(String name) { Definition def = lookupDefinition(name); return (StringDefinition) ((def instanceof StringDefinition) ? def : null); } + /** + * Lookup a struct in a struct. if the name returns a non-struct (like + * an int) than the method returns null + * + * @param name + * the name of the struct + * @return the struct or null. + */ public StructDefinition lookupStruct(String name) { Definition def = lookupDefinition(name); return (StructDefinition) ((def instanceof StructDefinition) ? def : null); } + /** + * Lookup a variant in a struct. if the name returns a non-variant (like + * an int) than the method returns null + * + * @param name + * the name of the variant + * @return the variant or null. + */ public VariantDefinition lookupVariant(String name) { Definition def = lookupDefinition(name); return (VariantDefinition) ((def instanceof VariantDefinition) ? def @@ -148,7 +219,8 @@ public class StructDefinition extends Definition implements IDefinitionScope { builder.append("{ "); //$NON-NLS-1$ } - ListIterator listIterator = this.declaration.getFieldsList().listIterator(); + ListIterator listIterator = this.declaration.getFieldsList() + .listIterator(); while (listIterator.hasNext()) { String field = listIterator.next(); diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/VariantDeclaration.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/VariantDeclaration.java index 87f4325d89..6d456c8dd5 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/VariantDeclaration.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/VariantDeclaration.java @@ -31,6 +31,9 @@ public class VariantDeclaration implements IDeclaration { // Constructors // ------------------------------------------------------------------------ + /** + * constructor + */ public VariantDeclaration() { } @@ -39,22 +42,42 @@ public class VariantDeclaration implements IDeclaration { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * @return Does the variant have a tag + */ public boolean isTagged() { return tag != null; } + /** + * Lookup if a field exists in the variant + * @param fieldTag the field tag name + * @return true = field tag exists + */ public boolean hasField(String fieldTag) { return fields.containsKey(fieldTag); } + /** + * Sets the tag in a variant + * @param tag the tag + */ public void setTag(String tag) { this.tag = tag; } + /** + * gets current variant tag + * @return the variant tag. + */ public String getTag() { return this.tag; } + /** + * Gets the fields of the variant + * @return the fields of the variant + */ public HashMap getFields() { return this.fields; } @@ -73,6 +96,11 @@ public class VariantDeclaration implements IDeclaration { return new VariantDefinition(this, definitionScope, fieldName); } + /** + * + * @param fieldTag + * @param declaration + */ public void addField(String fieldTag, IDeclaration declaration) { fields.put(fieldTag, declaration); } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/VariantDefinition.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/VariantDefinition.java index 55011eae9f..4c249440b3 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/VariantDefinition.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/event/types/VariantDefinition.java @@ -36,6 +36,12 @@ public class VariantDefinition extends Definition implements IDefinitionScope { // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + * @param declaration the parent declaration + * @param definitionScope the parent scope + * @param fieldName the field name + */ public VariantDefinition(VariantDeclaration declaration, IDefinitionScope definitionScope, String fieldName) { super(definitionScope, fieldName); @@ -63,30 +69,55 @@ public class VariantDefinition extends Definition implements IDefinitionScope { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + @Override public VariantDeclaration getDeclaration() { return declaration; } + /** + * Sets the variant declaration + * @param declaration the variant declaration + */ public void setDeclaration(VariantDeclaration declaration) { this.declaration = declaration; } + /** + * Gets the tag + * @return the tag definition + */ public EnumDefinition getTagDefinition() { return tagDefinition; } + /** + * Sets the tag + * @param tagDefinition the tag + */ public void setTagDefinition(EnumDefinition tagDefinition) { this.tagDefinition = tagDefinition; } + /** + * Get the definitions in the variant + * @return the definitions + */ public HashMap getDefinitions() { return definitions; } + /** + * Set the definitions in a variant + * @param definitions the definitions + */ public void setDefinitions(HashMap definitions) { this.definitions = definitions; } + /** + * Set the current field + * @param currentField the current field + */ public void setCurrentField(String currentField) { this.currentField = currentField; } @@ -96,6 +127,23 @@ public class VariantDefinition extends Definition implements IDefinitionScope { return path; } + /** + * Get the current field name + * @return the current field name + */ + public String getCurrentFieldName() { + return currentField; + } + + /** + * Get the current field + * @return the current field + */ + public Definition getCurrentField() { + return definitions.get(currentField); + } + + // ------------------------------------------------------------------------ // Operations // ------------------------------------------------------------------------ @@ -114,50 +162,99 @@ public class VariantDefinition extends Definition implements IDefinitionScope { return definitions.get(lookupPath); } - public String getCurrentFieldName() { - return currentField; - } - - public Definition getCurrentField() { - return definitions.get(currentField); - } + /** + * Lookup an array in a struct. if the name returns a non-array (like an + * int) than the method returns null + * + * @param name + * the name of the array + * @return the array or null. + */ public ArrayDefinition lookupArray(String name) { - Definition def = definitions.get(name); + Definition def = lookupDefinition(name); return (ArrayDefinition) ((def instanceof ArrayDefinition) ? def : null); } + /** + * Lookup an enum in a struct. if the name returns a non-enum (like an int) + * than the method returns null + * + * @param name + * the name of the enum + * @return the enum or null. + */ public EnumDefinition lookupEnum(String name) { - Definition def = definitions.get(name); + Definition def = lookupDefinition(name); return (EnumDefinition) ((def instanceof EnumDefinition) ? def : null); } + /** + * Lookup an integer in a struct. if the name returns a non-integer (like an + * float) than the method returns null + * + * @param name + * the name of the integer + * @return the integer or null. + */ public IntegerDefinition lookupInteger(String name) { - Definition def = definitions.get(name); + Definition def = lookupDefinition(name); return (IntegerDefinition) ((def instanceof IntegerDefinition) ? def : null); } + /** + * Lookup a sequence in a struct. if the name returns a non-sequence (like + * an int) than the method returns null + * + * @param name + * the name of the sequence + * @return the sequence or null. + */ public SequenceDefinition lookupSequence(String name) { - Definition def = definitions.get(name); + Definition def = lookupDefinition(name); return (SequenceDefinition) ((def instanceof SequenceDefinition) ? def : null); } + /** + * Lookup a string in a struct. if the name returns a non-string (like + * an int) than the method returns null + * + * @param name + * the name of the string + * @return the string or null. + */ public StringDefinition lookupString(String name) { - Definition def = definitions.get(name); + Definition def = lookupDefinition(name); return (StringDefinition) ((def instanceof StringDefinition) ? def : null); } + /** + * Lookup a struct in a struct. if the name returns a non-struct (like + * an int) than the method returns null + * + * @param name + * the name of the struct + * @return the struct or null. + */ public StructDefinition lookupStruct(String name) { - Definition def = definitions.get(name); + Definition def = lookupDefinition(name); return (StructDefinition) ((def instanceof StructDefinition) ? def : null); } + /** + * Lookup a variant in a struct. if the name returns a non-variant (like + * an int) than the method returns null + * + * @param name + * the name of the variant + * @return the variant or null. + */ public VariantDefinition lookupVariant(String name) { - Definition def = definitions.get(name); + Definition def = lookupDefinition(name); return (VariantDefinition) ((def instanceof VariantDefinition) ? def : null); } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFTrace.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFTrace.java index af60e736f8..4f29e0cfa5 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFTrace.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFTrace.java @@ -639,22 +639,46 @@ public class CTFTrace implements IDefinitionScope { eventDecs.put(stream.getId(), new HashMap()); } + /** + * gets the Environment variables from the trace metadata (See CTF spec) + * @return the environment variables in a hashmap form (key value) + */ public HashMap getEnvironment() { return environment; } + /** + * Look up a specific environment variable + * @param key the key to look for + * @return the value of the variable, can be null. + */ public String lookupEnvironment(String key) { return environment.get(key); } + /** + * Add a variable to the environment variables + * @param varName the name of the variable + * @param varValue the value of the variable + */ public void addEnvironmentVar(String varName, String varValue) { environment.put(varName, varValue); } + /** + * Add a clock to the clock list + * @param nameValue the name of the clock (full name with scope) + * @param ctfClock the clock + */ public void addClock(String nameValue, CTFClock ctfClock) { clocks.put(nameValue, ctfClock); } + /** + * gets the clock with a specific name + * @param name the name of the clock. + * @return the clock + */ public CTFClock getClock(String name) { return clocks.get(name); } @@ -662,6 +686,10 @@ public class CTFTrace implements IDefinitionScope { private CTFClock singleClock; private long singleOffset; + /** + * gets the clock if there is only one. (this is 100% of the use cases as of June 2012) + * @return the clock + */ public final CTFClock getClock() { if (clocks.size() == 1) { if (singleClock == null) { @@ -673,6 +701,10 @@ public class CTFTrace implements IDefinitionScope { return null; } + /** + * gets the time offset of a clock with respect to UTC in nanoseconds + * @return the time offset of a clock with respect to UTC in nanoseconds + */ public final long getOffset() { if (getClock() == null) { return 0; @@ -680,9 +712,20 @@ public class CTFTrace implements IDefinitionScope { return singleOffset; } + /** + * Does a given stream contain any events? + * @param id the stream ID + * @return true if the stream has events. + */ public boolean hasEvents(Long id){ return eventDecs.containsKey(id); } + + /** + * Add an event declaration map to the events map. + * @param id the id of a stream + * @return the hashmap containing events. + */ public HashMap createEvents(Long id){ HashMap value = eventDecs.get(id); if( value == null ) { diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFTraceReader.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFTraceReader.java index 3fbd66cce1..c4e98ceb74 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFTraceReader.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/CTFTraceReader.java @@ -63,7 +63,6 @@ public class CTFTraceReader { */ private long endTime; - protected void setEndTime(long endTime) { this.endTime = endTime; } @@ -241,8 +240,9 @@ public class CTFTraceReader { * Add it back in the queue. */ this.prio.add(top); - final long topEnd = top.getCurrentEvent().getTimestamp() + this.getTrace().getOffset(); - this.setEndTime( Math.max(topEnd, this.getEndTime())); + final long topEnd = top.getCurrentEvent().getTimestamp() + + this.getTrace().getOffset(); + this.setEndTime(Math.max(topEnd, this.getEndTime())); this.eventCountPerTraceFile[top.getName()]++; if (top.getCurrentEvent() != null) { @@ -322,6 +322,11 @@ public class CTFTraceReader { return tempIndex; } + /** + * gets the stream with the oldest event + * + * @return the stream with the oldest event + */ public StreamInputReader getTopStream() { return this.prio.peek(); } @@ -379,6 +384,12 @@ public class CTFTraceReader { } } + /** + * gets the last event timestamp that was read. This is NOT necessarily the + * last event in a trace, just the last one read so far. + * + * @return the last event + */ public long getEndTime() { return this.endTime; } @@ -435,6 +446,11 @@ public class CTFTraceReader { return "CTFTraceReader [trace=" + trace + ']'; //$NON-NLS-1$ } + /** + * Gets the parent trace + * + * @return the parent trace + */ public CTFTrace getTrace() { return trace; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/StreamInputPacketReader.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/StreamInputPacketReader.java index 02b86226dc..abefa7ada3 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/StreamInputPacketReader.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/StreamInputPacketReader.java @@ -138,16 +138,29 @@ public class StreamInputPacketReader implements IDefinitionScope { // Getters/Setters/Predicates // ------------------------------------------------------------------------ - /* Getters, setters and stuff. */ - + /** + * Gets the current packet + * + * @return the current packet + */ public StreamInputPacketIndexEntry getCurrentPacket() { return this.currentPacket; } + /** + * Gets the steamPacketContext Definition + * + * @return steamPacketContext Definition + */ public StructDefinition getStreamPacketContextDef() { return this.streamPacketContextDef; } + /** + * Gets the CPU (core) number + * + * @return the CPU (core) number + */ public int getCPU() { return this.currentCpu; } @@ -485,39 +498,86 @@ public class StreamInputPacketReader implements IDefinitionScope { return null; } + /** + * Gets the stream event context definition (see CTF specs) + * + * @return the definition of the stream event context (the form not the + * content) + */ public StructDefinition getStreamEventContextDef() { return this.streamEventContextDef; } + /** + * Sets the stream event context definition + * + * @param streamEventContextDef + * The stream event context definition + */ public void setStreamEventContextDef(StructDefinition streamEventContextDef) { this.streamEventContextDef = streamEventContextDef; } + /** + * Gets the stream event header definition + * + * @return the stream event header definition + */ public StructDefinition getStreamEventHeaderDef() { return this.streamEventHeaderDef; } + /** + * Sets the stream event header definition + * + * @param streamEventHeaderDef + * the stream event header definition + */ public void setStreamEventHeaderDef(StructDefinition streamEventHeaderDef) { this.streamEventHeaderDef = streamEventHeaderDef; } + /** + * Sets the stream packet context definition + * + * @param streamPacketContextDef + * the stream packet context definition + */ public void setStreamPacketContextDef( StructDefinition streamPacketContextDef) { this.streamPacketContextDef = streamPacketContextDef; } + /** + * Gets the trace packet header definition + * + * @return the trace packet header definition + */ public StructDefinition getTracePacketHeaderDef() { return this.tracePacketHeaderDef; } + /** + * Sets the trace packet header definition + * + * @param tracePacketHeaderDef + * the trace packet header definition + */ public void setTracePacketHeaderDef(StructDefinition tracePacketHeaderDef) { this.tracePacketHeaderDef = tracePacketHeaderDef; } + /** + * @return the parent stream input reader + */ public StreamInputReader getStreamInputReader() { return this.streamInputReader; } + /** + * + * @return THe bit buffer that reads the file. + */ public BitBuffer getBitBuffer() { return bitBuffer; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/StreamInputReader.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/StreamInputReader.java index 2bb89c9340..d04a8089cd 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/StreamInputReader.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/StreamInputReader.java @@ -86,30 +86,67 @@ public class StreamInputReader { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Gets the current event in this stream + * + * @return the current event in the stream, null if the stream is + * finished/empty/malformed + */ public EventDefinition getCurrentEvent() { return this.currentEvent; } + /** + * gets the current packet context + * + * @return the current packet context (size, lost events and such) + */ public StructDefinition getCurrentPacketContext() { return this.packetReader.getStreamPacketContextDef(); } + /** + * Gets the byte order for a trace + * + * @return the trace byte order + */ public ByteOrder getByteOrder() { return streamInput.getStream().getTrace().getByteOrder(); } + /** + * Gets the name of the stream (it's an id and a number) + * + * @return gets the stream name (it's a number) + */ public int getName() { return this.name; } + /** + * Sets the name of the stream + * + * @param name + * the name of the stream, (it's a number) + */ public void setName(int name) { this.name = name; } + /** + * Gets the CPU of a stream. It's the same as the one in /proc or running + * the asm CPUID instruction + * + * @return The CPU id (a number) + */ public int getCPU() { return this.packetReader.getCPU(); } + /** + * Gets the filename of the stream being read + * @return The filename of the stream being read + */ public String getFilename() { return streamInput.getFilename(); } @@ -144,7 +181,7 @@ public class StreamInputReader { } } - /* + /*autogenerate javadoc getter setter * If an event is available, read it. */ if (this.packetReader.hasMoreEvents()) { @@ -217,7 +254,7 @@ public class StreamInputReader { // do nothing here } } - if( this.packetReader.getCurrentPacket() == null){ + if (this.packetReader.getCurrentPacket() == null) { gotoPacket(timestamp); } @@ -248,6 +285,9 @@ public class StreamInputReader { goToNextPacket(); } + /** + * Seeks the last event of a stream and returns it. + */ public void goToLastEvent() { /* * Search in the index for the packet to search in. @@ -308,6 +348,10 @@ public class StreamInputReader { this.parent = parent; } + /** + * Sets the current event in a stream input reader + * @param currentEvent the event to set + */ public void setCurrentEvent(EventDefinition currentEvent) { this.currentEvent = currentEvent; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/Utils.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/Utils.java index 171db4827b..552dc5b2f1 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/Utils.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/ctf/core/trace/Utils.java @@ -26,12 +26,12 @@ public class Utils { // ------------------------------------------------------------------------ /** - * CTF magic number. + * CTF magic number. (sort of looks like CTF CTF CT) */ public final static int CTF_MAGIC = 0xC1FC1FC1; /** - * TSDL magic number. + * TSDL magic number. (sort of looks like TSDL LSDT) */ public final static int TSDL_MAGIC = 0x75D11D57; diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/Activator.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/Activator.java index f1315e4c86..707529d2bb 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/Activator.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/Activator.java @@ -28,16 +28,23 @@ public class Activator extends Plugin { // Attributes // ------------------------------------------------------------------------ - // The plug-in ID + /** + * The plug-in ID + */ public static final String PLUGIN_ID = "org.eclipse.linuxtools.ctf"; //$NON-NLS-1$ - // The shared instance + /** + * The shared instance + */ private static Activator fPlugin; // ------------------------------------------------------------------------ // Constructors // ------------------------------------------------------------------------ + /** + * Constructor + */ public Activator() { setDefault(this); } @@ -46,10 +53,19 @@ public class Activator extends Plugin { // Accessors // ------------------------------------------------------------------------ + /** + * Get the default activator + * @return the default activator + */ public static Activator getDefault() { return fPlugin; } + /** + * Sets the default activator + * + * @param plugin the default activator + */ private static void setDefault(Activator plugin) { fPlugin = plugin; } @@ -74,10 +90,19 @@ public class Activator extends Plugin { // Logging // ------------------------------------------------------------------------ + /** + * Log a message + * @param msg the message to log + */ public void log(String msg) { log(msg, null); } + /** + * Log a message with an exception + * @param msg the message + * @param e the exception + */ public void log(String msg, Exception e) { getLog().log(new Status(IStatus.INFO, PLUGIN_ID, IStatus.OK, msg, e)); } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/io/BitBuffer.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/io/BitBuffer.java index 04e54908b3..2559fe5df3 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/io/BitBuffer.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/io/BitBuffer.java @@ -19,7 +19,7 @@ import java.nio.ByteOrder; /** * BitBuffer *

- * TODO Implement me. Please. + * A bitwise buffer capable of accessing fields with bit offsets. */ public class BitBuffer { @@ -28,10 +28,15 @@ public class BitBuffer { // ------------------------------------------------------------------------ /* default bit width */ + /** 8 bits to a char */ public static final int BIT_CHAR = 8; + /** 16 bits to a short */ public static final int BIT_SHORT = 16; + /** 32 bits to an int */ public static final int BIT_INT = 32; + /** 32 bits to a float */ public static final int BIT_FLOAT = 32; + /** 64 bits to a long */ public static final int BIT_LONG = 64; // ------------------------------------------------------------------------ @@ -45,15 +50,31 @@ public class BitBuffer { // ------------------------------------------------------------------------ // Constructors // ------------------------------------------------------------------------ - + /** + * Default constructor, makes a bigendian buffer + */ public BitBuffer() { this(null, ByteOrder.BIG_ENDIAN); } + /** + * Constructor, makes a bigendian buffer + * + * @param buf + * the bytebuffer to read + */ public BitBuffer(ByteBuffer buf) { this(buf, ByteOrder.BIG_ENDIAN); } + /** + * Constructor that is fully parametrisable + * + * @param buf + * the buffer to read + * @param order + * the byte order (big endian, little endian, network?) + */ public BitBuffer(ByteBuffer buf, ByteOrder order) { setByteBuffer(buf); order(order); @@ -444,10 +465,26 @@ public class BitBuffer { // Buffer attributes handling // ------------------------------------------------------------------------ + /** + * Can this buffer be read for thus amount of bits? + * + * @param length + * the length in bits to read + * @return does the buffer have enough room to read the next "length" + */ public boolean canRead(int length) { return canRead(pos, length); } + /** + * Can this buffer be read for thus amount of bits? + * + * @param index + * the position in the buffer to read + * @param length + * the length in bits to read + * @return does the buffer have enough room to read the next "length" + */ public boolean canRead(int index, int length) { if (buf == null) { return false; @@ -459,6 +496,12 @@ public class BitBuffer { return true; } + /** + * Sets the order of the buffer. + * + * @param order + * The order of the buffer. + */ public void order(ByteOrder order) { this.byteOrder = order; if (buf != null) { @@ -466,18 +509,41 @@ public class BitBuffer { } } + /** + * Sets the order of the buffer. + * + * @return The order of the buffer. + */ public ByteOrder order() { return byteOrder; } + /** + * Sets the position in the buffer. + * + * @param order + * The position of the buffer. + */ public void position(int newPosition) { this.pos = newPosition; } + /** + * + * Sets the position in the buffer. + * + * @return order The position of the buffer. + */ public int position() { return pos; } + /** + * Sets the byte buffer + * + * @param buf + * the byte buffer + */ public void setByteBuffer(ByteBuffer buf) { this.buf = buf; if (buf != null) { @@ -486,18 +552,37 @@ public class BitBuffer { clear(); } + /** + * Gets the byte buffer + * + * @return The byte buffer + */ public ByteBuffer getByteBuffer() { return buf; } + /** + * Sets the byte order + * + * @param byteOrder + * The byte order + */ public void setByteOrder(ByteOrder byteOrder) { this.byteOrder = byteOrder; } + /** + * Gets the byte order + * + * @return The byte order + */ public ByteOrder getByteOrder() { return byteOrder; } + /** + * resets the bitbuffer. + */ public void clear() { position(0); diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/CTFStrings.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/CTFStrings.java index 52e0d17833..11dc2e65e1 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/CTFStrings.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/CTFStrings.java @@ -11,51 +11,100 @@ package org.eclipse.linuxtools.internal.ctf.core.event.metadata; +/** + * Strings generated from the TSDL grammar. Note that they are static final so + * they get quarked. See CTF specs for more details + * + * @author Matthew Khouzam and All + * + */ public interface CTFStrings { + /** None */ public static final String NONE = "none"; //$NON-NLS-1$ + /** Ascii */ public static final String ASCII = "ASCII"; //$NON-NLS-1$ + /** UTF8 */ public static final String UTF8 = "UTF8"; //$NON-NLS-1$ + /** b (for binary like b11010010 */ public static final String BIN = "b"; //$NON-NLS-1$ + /** Binary */ public static final String BINARY = "binary"; //$NON-NLS-1$ + /** Octal like o177 */ public static final String OCTAL_CTE = "o"; //$NON-NLS-1$ + /** Octal like oct177 */ public static final String OCT = "oct"; //$NON-NLS-1$ + /** Octal like octal177 */ public static final String OCTAL = "octal"; //$NON-NLS-1$ + /** Pointer (memory address for all the hardcore Java gurus out there)*/ public static final String POINTER = "p"; //$NON-NLS-1$ + /** X for hex */ public static final String X2 = "X"; //$NON-NLS-1$ + /** x for hex */ public static final String X = "x"; //$NON-NLS-1$ + /** hex */ public static final String HEX = "hex"; //$NON-NLS-1$ + /** Hexadecimal */ public static final String HEXADECIMAL = "hexadecimal"; //$NON-NLS-1$ + /** unsigned like in 10000ul */ public static final String UNSIGNED_CTE = "u"; //$NON-NLS-1$ + /** Decimal */ public static final String DEC_CTE = "d"; //$NON-NLS-1$ + /** Integer like 1000i */ public static final String INT_MOD = "i"; //$NON-NLS-1$ + /** Decimal */ public static final String DEC = "dec"; //$NON-NLS-1$ + /** Decimal */ public static final String DECIMAL = "decimal"; //$NON-NLS-1$ + /** native for byteorders*/ public static final String NATIVE = "native"; //$NON-NLS-1$ + /** network for byteorders*/ public static final String NETWORK = "network"; //$NON-NLS-1$ + /** Big endian */ public static final String BE = "be"; //$NON-NLS-1$ + /** Little endian */ public static final String LE = "le"; //$NON-NLS-1$ + /** Alignment of a field */ public static final String ALIGN = "align"; //$NON-NLS-1$ + /** Mantissa digits */ public static final String MANT_DIG = "mant_dig"; //$NON-NLS-1$ + /** Exponent digits */ public static final String EXP_DIG = "exp_dig"; //$NON-NLS-1$ + /** Loglevel */ public static final String LOGLEVEL2 = "loglevel"; //$NON-NLS-1$ + /** Name */ public static final String NAME2 = "name"; //$NON-NLS-1$ + /** Event context */ public static final String EVENT_CONTEXT = "event.context"; //$NON-NLS-1$ + /** Fields */ public static final String FIELDS_STRING = "fields"; //$NON-NLS-1$ + /** context */ public static final String CONTEXT = "context"; //$NON-NLS-1$ + /** Stream ID */ public static final String STREAM_ID = "stream_id"; //$NON-NLS-1$ + /** Packet context */ public static final String PACKET_CONTEXT = "packet.context"; //$NON-NLS-1$ + /** ID */ public static final String ID = "id"; //$NON-NLS-1$ + /** Packet Header */ public static final String PACKET_HEADER = "packet.header"; //$NON-NLS-1$ + /** Event Header */ public static final String EVENT_HEADER = "event.header"; //$NON-NLS-1$ + /** Byte order */ public static final String BYTE_ORDER = "byte_order"; //$NON-NLS-1$ + /** UUID */ public static final String UUID_STRING = "uuid"; //$NON-NLS-1$ + /** False */ public static final String FALSE2 = "FALSE"; //$NON-NLS-1$ + /** False */ public static final String FALSE = "false"; //$NON-NLS-1$ + /** True */ public static final String TRUE2 = "TRUE"; //$NON-NLS-1$ + /** True */ public static final String TRUE = "true"; //$NON-NLS-1$ + /** Minor (Vresion)*/ public static final String MINOR = "minor"; //$NON-NLS-1$ + /** Major (Vresion)*/ public static final String MAJOR = "major"; //$NON-NLS-1$ - } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/IOStructGen.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/IOStructGen.java index 5039efbcd0..b9533b2299 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/IOStructGen.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/IOStructGen.java @@ -79,11 +79,20 @@ public class IOStructGen { // Constructor // ------------------------------------------------------------------------ + /** + * Constuctor + * @param tree the tree (antlr generated) with the parsed TSDL data. + * @param trace the trace containing the places to put all the read metadata + */ public IOStructGen(CommonTree tree, CTFTrace trace) { this.trace = trace; this.tree = tree; } + /** + * Parse the tree and populate the trace defined in the constructor. + * @throws ParseException + */ public void generate() throws ParseException { parseRoot(tree); } @@ -445,7 +454,7 @@ public class IOStructGen { } } - if (stream.idIsSet()) { + if (stream.isIdSet()) { if (!trace.packetHeaderIsSet() || !trace.getPacketHeader().hasField(CTFStrings.STREAM_ID)) { throw new ParseException( @@ -482,7 +491,7 @@ public class IOStructGen { String left = concatenateUnaryStrings(leftStrings); if (left.equals(CTFStrings.ID)) { - if (stream.idIsSet()) { + if (stream.isIdSet()) { throw new ParseException("stream id already defined"); //$NON-NLS-1$ } @@ -490,7 +499,7 @@ public class IOStructGen { stream.setId(streamID); } else if (left.equals(CTFStrings.EVENT_HEADER)) { - if (stream.eventHeaderIsSet()) { + if (stream.isEventHeaderSet()) { throw new ParseException("event.header already defined"); //$NON-NLS-1$ } @@ -510,7 +519,7 @@ public class IOStructGen { stream.setEventHeader((StructDeclaration) eventHeaderDecl); } else if (left.equals(CTFStrings.EVENT_CONTEXT)) { - if (stream.eventContextIsSet()) { + if (stream.isEventContextSet()) { throw new ParseException("event.context already defined"); //$NON-NLS-1$ } @@ -530,7 +539,7 @@ public class IOStructGen { stream.setEventContext((StructDeclaration) eventContextDecl); } else if (left.equals(CTFStrings.PACKET_CONTEXT)) { - if (stream.packetContextIsSet()) { + if (stream.isPacketContextSet()) { throw new ParseException("packet.context already defined"); //$NON-NLS-1$ } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/exceptions/ParseException.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/exceptions/ParseException.java index 48055d96aa..242f015143 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/exceptions/ParseException.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/event/metadata/exceptions/ParseException.java @@ -19,6 +19,9 @@ public class ParseException extends Exception { private static final long serialVersionUID = 7901917601459652080L; + /** + * Enoty constructor + */ public ParseException() { super(); } @@ -26,7 +29,7 @@ public class ParseException extends Exception { /** * Constructor * - * @param message + * @param message (to be sent to logs */ public ParseException(String message) { super(message); diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/Stream.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/Stream.java index 1434fa781b..83f252e27d 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/Stream.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/Stream.java @@ -78,63 +78,123 @@ public class Stream { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Sets the id of a stream + * @param id the id of a stream + */ public void setId(long id) { this.id = id; this.events = trace.createEvents(this.id); } + /** + * Gets the id of a stream + * @return id the id of a stream + */ public Long getId() { return id; } - public boolean idIsSet() { + /** + * Is the id of a stream set + * @param Is id the id of a stream set + */ + public boolean isIdSet() { return id != null; } - public boolean eventHeaderIsSet() { + /** + * + * @return is the event header set (timestamp and stuff) (see Ctf Spec) + */ + public boolean isEventHeaderSet() { return eventHeaderDecl != null; } - public boolean eventContextIsSet() { + /** + * + * @return is the event context set (pid and stuff) (see Ctf Spec) + */ + public boolean isEventContextSet() { return eventContextDecl != null; } - public boolean packetContextIsSet() { + /** + * + * @return Is the packet context set (see Ctf Spec) + */ + public boolean isPacketContextSet() { return packetContextDecl != null; } + /** + * + * @param eventHeader the current event header for all events in this stream + */ public void setEventHeader(StructDeclaration eventHeader) { this.eventHeaderDecl = eventHeader; } + /** + * + * @param eventContext the context for all events in this stream + */ public void setEventContext(StructDeclaration eventContext) { this.eventContextDecl = eventContext; } + /** + * + * @param packetContext the packet context for all packets in this stream + */ public void setPacketContext(StructDeclaration packetContext) { this.packetContextDecl = packetContext; } + /** + * + * @return the event header declaration in structdeclaration form + */ public StructDeclaration getEventHeaderDecl() { return eventHeaderDecl; } + /** + * + * @return the event context declaration in structdeclaration form + */ public StructDeclaration getEventContextDecl() { return eventContextDecl; } + /** + * + * @return the packet context declaration in structdeclaration form + */ public StructDeclaration getPacketContextDecl() { return packetContextDecl; } + /** + * + * @return the set of all stream inputs for this stream + */ public Set getStreamInputs() { return inputs; } + /** + * + * @return the parent trace + */ public CTFTrace getTrace() { return trace; } + /** + * + * @return all the event declarations for this stream, using the id as a key for the hashmap. + */ public HashMap getEvents() { return events; } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInput.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInput.java index b90bb12837..685c61efcb 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInput.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInput.java @@ -96,30 +96,57 @@ public class StreamInput implements IDefinitionScope { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Gets the stream the streamInput wrapper is wrapping + * @return the stream the streamInput wrapper is wrapping + */ public Stream getStream() { return stream; } + /** + * the common streamInput Index + * @return the stream input Index + */ public StreamInputPacketIndex getIndex() { return index; } + /** + * Gets the filechannel of the streamInput. This is a limited Java ressource. + * @return the filechannel + */ public FileChannel getFileChannel() { return fileChannel; } + /** + * Gets the filename of the streamInput file. + * @return the filename of the streaminput file. + */ public String getFilename() { return file.getName(); } + /** + * gets the last read timestamp of a stream. (this is not necessarily the last time in the stream.) + * @return the last read timestamp + */ public long getTimestampEnd() { return timestampEnd; } + /** + * Sets the last read timestamp of a stream. (this is not necessarily the last time in the stream.) + * @param timestampEnd the last read timestamp + */ public void setTimestampEnd(long timestampEnd) { this.timestampEnd = timestampEnd; } + /** + * useless for streaminputs + */ @Override public String getPath() { return ""; //$NON-NLS-1$ @@ -162,6 +189,13 @@ public class StreamInput implements IDefinitionScope { } + /** + * Adds the next packet header index entry to the index of a stream input. + * @warning slow + * @warning can corrupt data if not used properly + * @return true if there are more packets to add + * @throws CTFReaderException + */ public boolean addPacketHeaderIndex() throws CTFReaderException { long currentPos = 0L; if (!index.getEntries().isEmpty()) { diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInputPacketIndex.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInputPacketIndex.java index b295342b7f..b04165f460 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInputPacketIndex.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInputPacketIndex.java @@ -38,14 +38,27 @@ public class StreamInputPacketIndex { // Getters/Setters/Predicates // ------------------------------------------------------------------------ + /** + * Gets the entries + * @return the entries + */ public Vector getEntries() { return this.entries; } + /** + * Gets an iterator to the entries + * @return an iterator to the entries + */ public ListIterator listIterator() { return this.entries.listIterator(); } + /** + * Gets an iterator to the entries at a given position + * @param n the position to get + * @return the iterator + */ public ListIterator listIterator(int n) { return this.entries.listIterator(n); } diff --git a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInputPacketIndexEntry.java b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInputPacketIndexEntry.java index ee44da2136..aa1baf2ac1 100644 --- a/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInputPacketIndexEntry.java +++ b/org.eclipse.linuxtools.ctf.core/src/org/eclipse/linuxtools/internal/ctf/core/trace/StreamInputPacketIndexEntry.java @@ -23,7 +23,6 @@ public class StreamInputPacketIndexEntry { // Attributes // ------------------------------------------------------------------------ - public static final long INVALID_INDEX = Long.MAX_VALUE; /** * Offset of the packet in the file, in bytes diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfIterator.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfIterator.java index be7bd1447a..f79e2f4ed8 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfIterator.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfIterator.java @@ -24,6 +24,9 @@ public class CtfIterator extends CTFTraceReader implements ITmfContext, Comparab private final CtfTmfTrace ctfTmfTrace; + /** + * An invalid location + */ final public static CtfLocation NULL_LOCATION = new CtfLocation( CtfLocation.INVALID_LOCATION); private CtfLocation curLocation; @@ -169,7 +172,6 @@ public class CtfIterator extends CTFTraceReader implements ITmfContext, Comparab /** * Method setLocation. * @param location ITmfLocation - * @see org.eclipse.linuxtools.tmf.core.trace.ITmfContext#setLocation(ITmfLocation) */ @Override public void setLocation(final ITmfLocation location) { diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfLocation.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfLocation.java index d87c413f59..f8b969be46 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfLocation.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfLocation.java @@ -19,6 +19,9 @@ import org.eclipse.linuxtools.tmf.core.trace.ITmfLocation; */ public class CtfLocation implements ITmfLocation, Cloneable { + /** + * An invalid location + */ public static final Long INVALID_LOCATION = -1L; /** diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfEventType.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfEventType.java index ee72e09ce3..c9ac13f471 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfEventType.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfEventType.java @@ -39,6 +39,11 @@ public class CtfTmfEventType extends TmfEventType { return this.getName(); } + /** + * gets the event type for an event name + * @param eventName the event name + * @return the event type + */ public static CtfTmfEventType get(String eventName){ return (CtfTmfEventType) TmfEventTypeManager.getInstance().getType(CONTEXT_ID, eventName); } diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfTimestamp.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfTimestamp.java index 9e1deddc46..4ba31785e1 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfTimestamp.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfTimestamp.java @@ -25,7 +25,22 @@ public class CtfTmfTimestamp extends TmfTimestamp { /** */ public enum TimestampType { - FULL_DATE, DAY, NANOS, SECONDS + /** + * yyyy/mm/dd hh:mm:ss.nnnnnnnnnn + */ + FULL_DATE, + /** + * hh:mm:ss.nnnnnnnnnn + */ + DAY, + /** + * nnnnnnnnnnnnnnnnnnnnn ns + */ + NANOS, + /** + * ssssssssss.nnnnnnnnnn s + */ + SECONDS } private TimestampType type; diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfTrace.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfTrace.java index 9e0adaf868..33f0ba457d 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfTrace.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfTrace.java @@ -30,6 +30,10 @@ import org.eclipse.linuxtools.tmf.core.trace.ITmfEventParser; import org.eclipse.linuxtools.tmf.core.trace.ITmfLocation; import org.eclipse.linuxtools.tmf.core.trace.TmfTrace; +/** + * @author Matthew Khouzam + * A trace type that reads CTF. + */ public class CtfTmfTrace extends TmfTrace implements ITmfEventParser{ @@ -71,7 +75,6 @@ public class CtfTmfTrace extends TmfTrace implements ITmfEventParse * @param path String * @param eventType Class * @throws TmfTraceException - * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(IResource, String, Class) */ @Override public void initTrace(final IResource resource, final String path, final Class eventType) @@ -195,7 +198,6 @@ public class CtfTmfTrace extends TmfTrace implements ITmfEventParse * Method seekEvent. * @param location ITmfLocation * @return ITmfContext - * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(ITmfLocation) */ @Override public ITmfContext seekEvent(final ITmfLocation location) { @@ -322,6 +324,10 @@ public class CtfTmfTrace extends TmfTrace implements ITmfEventParse // Clocks //------------------------------------------- + /** + * gets the clock offset + * @return the clock offset in ns + */ public long getOffset(){ if( fTrace != null ) { return fTrace.getOffset(); -- 2.34.1