Improve javadoc for ctfAdapter in Tmf.Core

[deliverable/tracecompass.git] / org.eclipse.linuxtools.ctf.core / src / org / eclipse / linuxtools / ctf / core / event / types / SequenceDefinition.java

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 3f29d1f14cef202cf42e2f2a354d251402b70368..3ddb77eed22ab39be150cc6ebfa8a9b935063792 100644 (file)
--- 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
@@ -12,7 +12,8 @@
 
 package org.eclipse.linuxtools.ctf.core.event.types;
 
-import org.eclipse.linuxtools.ctf.core.event.io.BitBuffer;
+import org.eclipse.linuxtools.ctf.core.trace.CTFReaderException;
+import org.eclipse.linuxtools.internal.ctf.core.event.io.BitBuffer;
 
 /**
  * <b><u>SequenceDefinition</u></b>
@@ -24,7 +25,7 @@ public class SequenceDefinition extends Definition {
     // ------------------------------------------------------------------------
 
     private final SequenceDeclaration declaration;
-    private IntegerDefinition lengthDefinition;
+    private final IntegerDefinition lengthDefinition;
     private Definition definitions[];
     private int currentLength;
 
@@ -32,42 +33,71 @@ 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) {
+            IDefinitionScope definitionScope, String fieldName)
+            throws CTFReaderException {
         super(definitionScope, fieldName);
+        Definition lenDef = null;
 
         this.declaration = declaration;
-        // this.definitionScope = definitionScope;
 
         if (definitionScope != null) {
-            Definition lenDef = definitionScope.lookupDefinition(declaration.getLengthName());
-            lengthDefinition = (IntegerDefinition) lenDef;
+            lenDef = definitionScope.lookupDefinition(declaration
+                    .getLengthName());
+        }
+
+        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$
+        }
+
+        lengthDefinition = (IntegerDefinition) lenDef;
+
+        if (this.lengthDefinition.getDeclaration().isSigned()) {
+            throw new CTFReaderException("Sequence length must not be signed"); //$NON-NLS-1$
         }
-        /*
-         * if (lenDef == null) { throw new
-         * Exception("Sequence length field not found"); }
-         *
-         * if (!(lenDef instanceof IntegerDefinition)) { throw new
-         * Exception("Sequence length field not integer"); }
-         */
-        /*
-         * if (this.lengthDefinition.declaration.signed) { throw new
-         * Exception("Sequence length must not be signed"); }
-         */
     }
 
     // ------------------------------------------------------------------------
     // 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;
@@ -76,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;
 
@@ -108,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;