From 063f0d27815a0660075d3c114cc3175704dd72b4 Mon Sep 17 00:00:00 2001 From: Alexandre Montplaisir Date: Mon, 16 Jul 2012 14:46:23 -0400 Subject: [PATCH] tmf: Fix some javadoc warnings in tmf.core Change-Id: I580d39a0eb71dc4cc81fd0c7cdd9626504aefcba Signed-off-by: Alexandre Montplaisir Reviewed-on: https://git.eclipse.org/r/6866 --- .../tmf/core/statesystem/HistoryBuilder.java | 3 - .../tmf/core/trace/TmfExperimentContext.java | 28 ++++++++ .../tmf/core/trace/TmfLocationArray.java | 6 +- .../tmf/core/component/ITmfDataProvider.java | 13 ++++ .../tmf/core/component/TmfDataProvider.java | 60 +++++++++++++++-- .../tmf/core/component/TmfEventProvider.java | 29 ++++++++- .../tmf/core/ctfadaptor/CtfTmfEvent.java | 13 ++-- .../tmf/core/ctfadaptor/CtfTmfEventType.java | 18 ++++-- .../tmf/core/ctfadaptor/CtfTmfTrace.java | 13 +++- .../tmf/core/event/ITmfEventField.java | 9 ++- .../AttributeNotFoundException.java | 18 ++++-- .../exceptions/StateValueTypeException.java | 21 ++++-- .../tmf/core/io/BufferedRandomAccessFile.java | 64 +++++++++++++++++++ .../tmf/core/request/TmfDataRequest.java | 11 ++-- .../tmf/core/signal/TmfSignalManager.java | 3 +- .../linuxtools/tmf/core/trace/ITmfTrace.java | 2 +- .../tmf/core/trace/ITmfTraceIndexer.java | 24 +++++-- .../tmf/core/trace/TmfCheckpoint.java | 2 +- .../tmf/core/trace/TmfExperiment.java | 8 +-- .../linuxtools/tmf/core/trace/TmfTrace.java | 1 + .../tmf/core/util/TmfFixedArray.java | 4 -- .../tmf/core/util/TmfSortedArrayList.java | 14 ++-- 22 files changed, 295 insertions(+), 69 deletions(-) diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/HistoryBuilder.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/HistoryBuilder.java index da2e4e2d48..725709c4bf 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/HistoryBuilder.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/HistoryBuilder.java @@ -127,7 +127,6 @@ public class HistoryBuilder extends TmfComponent { /** * Build the state history without waiting for signals or anything */ - @SuppressWarnings("unchecked") private void buildManually() { StateSystemBuildRequest request = new StateSystemBuildRequest(this); @@ -155,7 +154,6 @@ public class HistoryBuilder extends TmfComponent { * signal will coalesce this request with the one from the * indexer and histogram. */ - @SuppressWarnings("unchecked") @TmfSignalHandler public void experimentRangeUpdated(final TmfExperimentRangeUpdatedSignal signal) { StateSystemBuildRequest request; @@ -208,7 +206,6 @@ class StateSystemBuildRequest extends TmfEventRequest { private final IStateChangeInput sci; private final ITmfTrace trace; - @SuppressWarnings("unchecked") StateSystemBuildRequest(HistoryBuilder builder) { super((Class) builder.getInputPlugin().getExpectedEventType().getClass(), TmfTimeRange.ETERNITY, diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/trace/TmfExperimentContext.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/trace/TmfExperimentContext.java index be7377efb0..2ea22050bf 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/trace/TmfExperimentContext.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/trace/TmfExperimentContext.java @@ -56,7 +56,10 @@ public class TmfExperimentContext extends TmfContext { // ------------------------------------------------------------------------ /** + * Standard constructor + * * @param contexts + * The matching context for each trace in the experiment */ public TmfExperimentContext(final ITmfContext[] contexts) { super(); @@ -82,7 +85,10 @@ public class TmfExperimentContext extends TmfContext { } /** + * Copy constructor + * * @param other + * The experiment context to copy */ public TmfExperimentContext(final TmfExperimentContext other) { this(other.cloneContexts()); @@ -127,18 +133,40 @@ public class TmfExperimentContext extends TmfContext { // Accessors // ------------------------------------------------------------------------ + /** + * Get the trace contexts composing this experiment context. + * + * @return The array of trace contexts + */ public ITmfContext[] getContexts() { return fContexts; } + /** + * Get the trace events located at this experiment context's location. + * + * @return The array of trace events + */ public ITmfEvent[] getEvents() { return fEvents; } + /** + * Get the index of the trace that was last read (so the trace whose + * current context will match this experiment's). + * + * @return The index of the trace + */ public int getLastTrace() { return fLastTraceRead; } + /** + * Set the last trace read index + * + * @param newIndex + * The new value to assign + */ public void setLastTrace(final int newIndex) { fLastTraceRead = newIndex; } diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/trace/TmfLocationArray.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/trace/TmfLocationArray.java index 49445d8eb0..c28ea8a1b0 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/trace/TmfLocationArray.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/trace/TmfLocationArray.java @@ -50,9 +50,9 @@ public class TmfLocationArray implements Comparable, Cloneable // ------------------------------------------------------------------------ /** - * The standard constructor + * Get the locations inside this array * - * @param locations the locations + * @return the locations */ public ITmfLocation>[] getLocations() { return fLocations; @@ -80,7 +80,7 @@ public class TmfLocationArray implements Comparable, Cloneable // ------------------------------------------------------------------------ @Override - @SuppressWarnings({ "unchecked", "rawtypes" }) + @SuppressWarnings("rawtypes") public int compareTo(TmfLocationArray o) { for (int i = 0; i < fLocations.length; i++) { ITmfLocation l1 = (ITmfLocation) fLocations[i].getLocation(); diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/ITmfDataProvider.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/ITmfDataProvider.java index 84e581fd77..107643255b 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/ITmfDataProvider.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/ITmfDataProvider.java @@ -35,7 +35,20 @@ public interface ITmfDataProvider extends ITmfComponent { */ public void sendRequest(ITmfDataRequest request); + /** + * Queue the coalesced requests. + */ public void fireRequest(); + + /** + * Increments/decrements the pending requests counters and fires the request + * if necessary (counter == 0). Used for coalescing requests across multiple + * TmfDataProvider's. + * + * @param isIncrement + * Should we increment (true) or decrement (false) the pending + * counter + */ public void notifyPendingRequest(boolean isIncrement); /** diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/TmfDataProvider.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/TmfDataProvider.java index a2bb826c66..30895457d0 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/TmfDataProvider.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/TmfDataProvider.java @@ -51,7 +51,10 @@ public abstract class TmfDataProvider extends TmfComponent // Constants // ------------------------------------------------------------------------ + /** Default amount of events per request "chunk" */ public static final int DEFAULT_BLOCK_SIZE = 50000; + + /** Default size of the queue */ public static final int DEFAULT_QUEUE_SIZE = 1000; // ------------------------------------------------------------------------ @@ -75,6 +78,9 @@ public abstract class TmfDataProvider extends TmfComponent // Constructors // ------------------------------------------------------------------------ + /** + * Default constructor + */ public TmfDataProvider() { super(); fQueueSize = DEFAULT_QUEUE_SIZE; @@ -82,6 +88,14 @@ public abstract class TmfDataProvider extends TmfComponent fExecutor = new TmfRequestExecutor(); } + /** + * Initialize this data provider + * + * @param name + * Name of the provider + * @param type + * The type of events that will be handled + */ public void init(String name, Class type) { super.init(name); fType = type; @@ -102,11 +116,25 @@ public abstract class TmfDataProvider extends TmfComponent init(name, type); } + /** + * Copy constructor + * + * @param other + * The other object to copy + */ public TmfDataProvider(TmfDataProvider other) { this(); init(other.getName(), other.fType); } + /** + * Standard constructor. Instantiate and initialize at the same time. + * + * @param name + * Name of the provider + * @param type + * The type of events that will be handled + */ public TmfDataProvider(String name, Class type) { this(name, type, DEFAULT_QUEUE_SIZE); } @@ -123,10 +151,20 @@ public abstract class TmfDataProvider extends TmfComponent // Accessors // ------------------------------------------------------------------------ + /** + * Get the queue size of this provider + * + * @return The size of the queue + */ public int getQueueSize() { return fQueueSize; } + /** + * Get the event type this provider handles + * + * @return The type of ITmfEvent + */ public Class getType() { return fType; } @@ -146,9 +184,6 @@ public abstract class TmfDataProvider extends TmfComponent } } - /** - * This method queues the coalesced requests. - */ @Override public void fireRequest() { synchronized (fLock) { @@ -165,9 +200,10 @@ public abstract class TmfDataProvider extends TmfComponent } /** - * Increments/decrements the pending requests counters and fires the request if necessary (counter == 0). Used for - * coalescing requests accross multiple TmfDataProvider. - * + * Increments/decrements the pending requests counters and fires the request + * if necessary (counter == 0). Used for coalescing requests accross + * multiple TmfDataProvider. + * * @param isIncrement */ @Override @@ -432,6 +468,12 @@ public abstract class TmfDataProvider extends TmfComponent // Signal handlers // ------------------------------------------------------------------------ + /** + * Handler for the start synch signal + * + * @param signal + * Incoming signal + */ @TmfSignalHandler public void startSynch(TmfStartSynchSignal signal) { synchronized (fLock) { @@ -439,6 +481,12 @@ public abstract class TmfDataProvider extends TmfComponent } } + /** + * Handler for the end synch signal + * + * @param signal + * Incoming signal + */ @TmfSignalHandler public void endSynch(TmfEndSynchSignal signal) { synchronized (fLock) { diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/TmfEventProvider.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/TmfEventProvider.java index c876893fc0..012e72e68c 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/TmfEventProvider.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/component/TmfEventProvider.java @@ -33,6 +33,9 @@ public abstract class TmfEventProvider extends TmfDataProvi // Constructors // ------------------------------------------------------------------------ + /** + * Default constructor + */ public TmfEventProvider() { super(); } @@ -42,14 +45,38 @@ public abstract class TmfEventProvider extends TmfDataProvi super.init(name, type); } - public TmfEventProvider(String name, Class type) { + /** + * Standard constructor + * + * @param name + * The name of the provider + * @param type + * The type of handled events + */ + public TmfEventProvider(String name, Class type) { super(name, type); } + /** + * Standard constructor which also sets the queue size + * + * @param name + * The name of the provider + * @param type + * The type of handled events + * @param queueSize + * The size of the queue + */ public TmfEventProvider(String name, Class type, int queueSize) { super(name, type, queueSize); } + /** + * Copy constructor + * + * @param other + * The other TmfEventProvider to copy + */ public TmfEventProvider(TmfEventProvider other) { super(other); } diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfEvent.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfEvent.java index 9f14796228..9de76d1eb4 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfEvent.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/ctfadaptor/CtfTmfEvent.java @@ -64,9 +64,11 @@ public final class CtfTmfEvent implements ITmfEvent, Cloneable { * the StreamInputReader). * * @param eventDef - - * @param fileName String - * @param originTrace CtfTmfTrace + * CTF EventDefinition object corresponding to this trace event + * @param fileName + * The path to the trace file + * @param originTrace + * The trace from which this event originates */ public CtfTmfEvent(EventDefinition eventDef, String fileName, CtfTmfTrace originTrace) { @@ -100,8 +102,8 @@ public final class CtfTmfEvent implements ITmfEvent, Cloneable { * mess, and put them into something ITmfEventField can cope with. * * @param eventDef - - * @return CtfTmfEventField[] + * CTF EventDefinition to read + * @return CtfTmfEventField[] The array of fields that were read */ public static CtfTmfEventField[] parseFields(EventDefinition eventDef) { List fields = new ArrayList(); @@ -127,6 +129,7 @@ public final class CtfTmfEvent implements ITmfEvent, Cloneable { * Copy constructor * * @param other + * CtfTmfEvent to copy */ public CtfTmfEvent(CtfTmfEvent other) { this.fTrace = other.getTrace(); 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 560bfcb745..585d30b3f9 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 @@ -16,19 +16,22 @@ import org.eclipse.linuxtools.tmf.core.event.TmfEventType; import org.eclipse.linuxtools.tmf.core.event.TmfEventTypeManager; /** - * The CTF extension of the TMF event type - * + * The CTF extension of the TMF event type + * * @version 1.0 * @author Matthew khouzam */ public class CtfTmfEventType extends TmfEventType { private static final String CONTEXT_ID = "Ctf Event"; //$NON-NLS-1$ + /** * Constructor for CtfTmfEventType. - * @param contextId String - * @param eventName String - * @param content ITmfEventField + * + * @param eventName + * String + * @param content + * ITmfEventField */ public CtfTmfEventType(String eventName, ITmfEventField content) { super(CONTEXT_ID, eventName, content); @@ -36,6 +39,7 @@ public class CtfTmfEventType extends TmfEventType { /** * Method toString. + * * @return String */ @Override @@ -45,7 +49,9 @@ public class CtfTmfEventType extends TmfEventType { /** * gets the event type for an event name - * @param eventName the event name + * + * @param eventName + * the event name * @return the event type */ public static CtfTmfEventType get(String eventName){ 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 1fd7524908..8c1dd89258 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 @@ -60,10 +60,15 @@ public class CtfTmfTrace extends TmfTrace implements ITmfEventParse //------------------------------------------- /** * Method initTrace. - * @param resource IResource - * @param path String - * @param eventType Class + * + * @param resource + * The resource associated with this trace + * @param path + * The path to the trace file + * @param eventType + * The type of events that will be read from this trace * @throws TmfTraceException + * If something when wrong while reading the trace */ @Override public void initTrace(final IResource resource, final String path, final Class eventType) @@ -251,8 +256,10 @@ public class CtfTmfTrace extends TmfTrace implements ITmfEventParse /** * Suppressing the warning, because the 'throws' will usually happen in * sub-classes. + * * @throws TmfTraceException */ + @SuppressWarnings("unused") protected void buildStateSystem() throws TmfTraceException { /* * Nothing is done in the basic implementation, please specify diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/event/ITmfEventField.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/event/ITmfEventField.java index 7efb44dfaf..7782b672c7 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/event/ITmfEventField.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/event/ITmfEventField.java @@ -1,11 +1,11 @@ /******************************************************************************* * Copyright (c) 2012 Ericsson - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * * Contributors: * Francois Chouinard - Initial API and implementation *******************************************************************************/ @@ -15,7 +15,7 @@ package org.eclipse.linuxtools.tmf.core.event; /** * The generic event payload in TMF. Each field can be either a terminal or * further decomposed into subfields. - * + * * @version 1.0 * @author Francois Chouinard * @@ -53,6 +53,7 @@ public interface ITmfEventField { public String[] getFieldNames(); /** + * @param index The index of the field * @return the nth field name (null if absent or inexistent) */ public String getFieldName(int index); @@ -63,11 +64,13 @@ public interface ITmfEventField { public ITmfEventField[] getFields(); /** + * @param name The name of the field * @return a specific subfield by name (null if absent or inexistent) */ public ITmfEventField getField(String name); /** + * @param index The index of the field to return * @return a specific subfield by index (null if absent or inexistent) */ public ITmfEventField getField(int index); diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/exceptions/AttributeNotFoundException.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/exceptions/AttributeNotFoundException.java index ef39d0843e..2b1b0b4ddc 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/exceptions/AttributeNotFoundException.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/exceptions/AttributeNotFoundException.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * *******************************************************************************/ package org.eclipse.linuxtools.tmf.core.exceptions; @@ -15,18 +15,26 @@ package org.eclipse.linuxtools.tmf.core.exceptions; /** * This exception gets thrown when the user tries to access an attribute which * doesn't exist in the system, of if the quark is simply invalid (ie, < 0). - * - * @author alexmont - * + * + * @author Alexandre Montplaisir */ public class AttributeNotFoundException extends Exception { private static final long serialVersionUID = 7964275803369706145L; + /** + * Default constructor + */ public AttributeNotFoundException() { super(); } + /** + * Constructor with a message + * + * @param message + * Message to attach to this exception + */ public AttributeNotFoundException(String message) { super(message); } diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/exceptions/StateValueTypeException.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/exceptions/StateValueTypeException.java index e0d3a0590b..2aa04d32ab 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/exceptions/StateValueTypeException.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/exceptions/StateValueTypeException.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * *******************************************************************************/ package org.eclipse.linuxtools.tmf.core.exceptions; @@ -16,21 +16,30 @@ package org.eclipse.linuxtools.tmf.core.exceptions; * The StateValue is a wrapper around the different type of values that can be * used and stored in the state system and history. "Unboxing" the value means * retrieving the base type (int, String, etc.) inside it. - * + * * This exception is thrown if the user tries to unbox a StateValue with an * incorrect type (for example, tries to read a String value as an Int). - * - * @author alexmont - * + * + * @author Alexandre Montplaisir + * */ public class StateValueTypeException extends Exception { private static final long serialVersionUID = -4548793451746144513L; + /** + * Default constructor + */ public StateValueTypeException() { super(); } + /** + * Constructor with a message + * + * @param message + * Message to attach to this exception + */ public StateValueTypeException(String message) { super(message); } diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/io/BufferedRandomAccessFile.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/io/BufferedRandomAccessFile.java index 1e41dcac1a..cc70b168e0 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/io/BufferedRandomAccessFile.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/io/BufferedRandomAccessFile.java @@ -36,14 +36,55 @@ public class BufferedRandomAccessFile extends RandomAccessFile { long real_pos = 0; StringBuilder sb = new StringBuilder(); + /** + * Constructor using the default buffer size + * + * @param name + * File path. This is passed as-is to the RandomeAccessFile's + * constructor. + * @param mode + * File open mode ("r", "rw", etc.). This is passed as-is to + * RandomAccessFile's constructor. + * @throws IOException + * If the file was not found or couldn't be opened with the + * request permissions + */ public BufferedRandomAccessFile(String name, String mode) throws IOException { this(name, mode, DEFAULT_BUF_SIZE); } + /** + * Constructor using the default buffer size + * + * @param file + * File object. This is passed as-is to the RandomeAccessFile's + * constructor. + * @param mode + * File open mode ("r", "rw", etc.). This is passed as-is to + * RandomAccessFile's constructor. + * @throws IOException + * If the file was not found or couldn't be opened with the + * request permissions + */ public BufferedRandomAccessFile(File file, String mode) throws IOException { this(file, mode, DEFAULT_BUF_SIZE); } + /** + * Standard constructor. + * + * @param name + * File path. This is passed as-is to the RandomeAccessFile's + * constructor. + * @param mode + * File open mode ("r", "rw", etc.). This is passed as-is to + * RandomAccessFile's constructor. + * @param bufsize + * Buffer size to use, in bytes + * @throws IOException + * If the file was not found or couldn't be opened with the + * request permissions + */ public BufferedRandomAccessFile(String name, String mode, int bufsize) throws IOException { super(name, mode); invalidate(); @@ -51,6 +92,21 @@ public class BufferedRandomAccessFile extends RandomAccessFile { buffer = new byte[BUF_SIZE]; } + /** + * Standard constructor. + * + * @param file + * File object. This is passed as-is to the RandomeAccessFile's + * constructor. + * @param mode + * File open mode ("r", "rw", etc.). This is passed as-is to + * RandomAccessFile's constructor. + * @param bufsize + * Buffer size to use, in bytes + * @throws IOException + * If the file was not found or couldn't be opened with the + * request permissions + */ public BufferedRandomAccessFile(File file, String mode, int bufsize) throws IOException { super(file, mode); invalidate(); @@ -107,6 +163,14 @@ public class BufferedRandomAccessFile extends RandomAccessFile { } } + /** + * Read the next line from the buffer (ie, until the next '\n'). The bytes + * are interpreted as UTF-8 characters. + * + * @return The String that was read + * @throws IOException + * If we failed reading the file + */ public final String getNextLine() throws IOException { String str = null; if (buf_end - buf_pos <= 0) { diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/request/TmfDataRequest.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/request/TmfDataRequest.java index ec314411bc..e8418f1fe3 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/request/TmfDataRequest.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/request/TmfDataRequest.java @@ -76,10 +76,10 @@ public abstract class TmfDataRequest implements ITmfDataReq // Constants // ------------------------------------------------------------------------ - // The default maximum number of events per chunk + /** The default maximum number of events per chunk */ public static final int DEFAULT_BLOCK_SIZE = 1000; - // The request count for all the events + /** The request count for all the events */ public static final int ALL_DATA = Integer.MAX_VALUE; private static int fRequestNumber = 0; @@ -430,6 +430,7 @@ public abstract class TmfDataRequest implements ITmfDataReq * To suspend the client thread until the request starts (or is canceled). * * @throws InterruptedException + * If the thread was interrupted while waiting */ public void waitForStart() throws InterruptedException { while (!fRequestRunning) { @@ -438,9 +439,11 @@ public abstract class TmfDataRequest implements ITmfDataReq } /** - * To suspend the client thread until the request completes (or is canceled). - * + * To suspend the client thread until the request completes (or is + * canceled). + * * @throws InterruptedException + * If the thread was interrupted while waiting */ @Override public void waitForCompletion() throws InterruptedException { diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/signal/TmfSignalManager.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/signal/TmfSignalManager.java index 80cd3429a7..4d78b40439 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/signal/TmfSignalManager.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/signal/TmfSignalManager.java @@ -85,6 +85,8 @@ public class TmfSignalManager { return handlers.toArray(new Method[handlers.size()]); } + static int fSignalId = 0; + /** * Invokes the handling methods that listens to signals of a given type. * @@ -97,7 +99,6 @@ public class TmfSignalManager { * * @param signal the signal to dispatch */ - static int fSignalId = 0; static public synchronized void dispatchSignal(TmfSignal signal) { int signalId = fSignalId++; sendSignal(new TmfStartSynchSignal(signalId)); diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTrace.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTrace.java index 79dcf55a6a..5d2e1ca953 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTrace.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTrace.java @@ -133,7 +133,7 @@ public interface ITmfTrace extends ITmfDataProvider { * @param resource the trace resource * @param path the trace path * @param type the trace event type - * @throws TmfTraceException + * @throws TmfTraceException If we couldn't open the trace */ public void initTrace(IResource resource, String path, Class type) throws TmfTraceException; diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java index 7876c83a12..bdad22ec17 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java @@ -33,27 +33,39 @@ public interface ITmfTraceIndexer> { * intervals to indicate its progress. *

* Example 1: Index a whole trace asynchronously + * * 

      * trace.getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, false);
      *
+ * * Example 2: Index a whole trace synchronously + * * 
      * trace.getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, true);
      *
+ * * Example 3: Index a trace asynchronously, starting at rank 100 + * * 
      * trace.getIndexer().buildIndex(100, TmfTimeRange.ETERNITY, false);
      *
- * Example 4: Index a trace asynchronously, starting at rank 100 for events between - * T1 and T2 (inclusive). This is used for incremental indexing. + * + * Example 4: Index a trace asynchronously, starting at rank 100 for + * events between T1 and T2 (inclusive). This is used for incremental + * indexing. + * * 
      * TmfTimeRange range = new TmfTimeRange(T1, T2);
      * trace.getIndexer().buildIndex(100, range, false);
      *
* - * @param offset The offset of the first event to consider - * @param range The time range to consider + * @param offset + * The offset of the first event to consider + * @param range + * The time range to consider * @param waitForCompletion + * Should we block the calling thread until the build is + * complete? */ public void buildIndex(long offset, TmfTimeRange range, boolean waitForCompletion); @@ -68,8 +80,8 @@ public interface ITmfTraceIndexer> { /** * Adds an entry to the trace index. * - * @param context - * @param timestamp + * @param context The trace context to save + * @param timestamp The timestamp matching this context */ public void updateIndex(ITmfContext context, ITmfTimestamp timestamp); diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfCheckpoint.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfCheckpoint.java index 21f5901a10..9cabf4eecd 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfCheckpoint.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfCheckpoint.java @@ -52,7 +52,7 @@ public class TmfCheckpoint implements ITmfCheckpoint, Cloneable { * Full constructor * * @param timestamp the checkpoint timestamp - * @param location the corresponding trace location + * @param context the corresponding trace location */ public TmfCheckpoint(final ITmfTimestamp timestamp, final ITmfContext context) { fTimestamp = timestamp; diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfExperiment.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfExperiment.java index 5c13ebf55a..7f9576cbda 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfExperiment.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfExperiment.java @@ -523,7 +523,7 @@ public class TmfExperiment extends TmfTrace implements I /** * Signal handler for the TmfExperimentSelectedSignal signal * - * @param signal + * @param signal The incoming signal */ @TmfSignalHandler public void experimentSelected(final TmfExperimentSelectedSignal signal) { @@ -537,7 +537,7 @@ public class TmfExperiment extends TmfTrace implements I /** * Signal handler for the TmfEndSynchSignal signal * - * @param signal + * @param signal The incoming signal */ @TmfSignalHandler public void endSync(final TmfEndSynchSignal signal) { @@ -550,7 +550,7 @@ public class TmfExperiment extends TmfTrace implements I /** * Signal handler for the TmfTraceUpdatedSignal signal * - * @param signal + * @param signal The incoming signal */ @TmfSignalHandler public void traceUpdated(final TmfTraceUpdatedSignal signal) { @@ -562,7 +562,7 @@ public class TmfExperiment extends TmfTrace implements I /** * Signal handler for the TmfExperimentRangeUpdatedSignal signal * - * @param signal + * @param signal The incoming signal */ @TmfSignalHandler public void experimentRangeUpdated(final TmfExperimentRangeUpdatedSignal signal) { diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfTrace.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfTrace.java index 7699fe4372..82421f5d62 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfTrace.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/TmfTrace.java @@ -166,6 +166,7 @@ public abstract class TmfTrace extends TmfEventProvider * Copy constructor * * @param trace the original trace + * @throws TmfTraceException Should not happen usually */ @SuppressWarnings({ "unchecked", "rawtypes" }) public TmfTrace(final TmfTrace trace) throws TmfTraceException { diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/util/TmfFixedArray.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/util/TmfFixedArray.java index 23134cd8b0..f38fd5f0ef 100755 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/util/TmfFixedArray.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/util/TmfFixedArray.java @@ -41,7 +41,6 @@ public final class TmfFixedArray extends AbstractList implements RandomAcc * @param newLength Length of the copy to be returned. * @return A new array consisting of the elements specified. */ - @SuppressWarnings("unchecked") private static E[] copyOf(final E[] array, int newLength) { E[] result = (E[])Array.newInstance(array.getClass().getComponentType(), newLength); // Is it useful to use newInstance? System.arraycopy(array, 0, result, 0, Math.min(array.length, newLength)); @@ -55,7 +54,6 @@ public final class TmfFixedArray extends AbstractList implements RandomAcc * @param newType Type of the array to be returned. * @return A new array consisting of the elements specified. */ - @SuppressWarnings("unchecked") private static E[] copyOf(final U[] array, int newLength, Class newType) { E[] result = (E[])Array.newInstance(newType.getComponentType(), newLength); System.arraycopy(array, 0, result, 0, Math.min(array.length, newLength)); @@ -69,7 +67,6 @@ public final class TmfFixedArray extends AbstractList implements RandomAcc * @param end Ending position of the range, exclusive. * @return A new array consisting of the elements specified. The length of the new array is equal to end-start */ - @SuppressWarnings("unchecked") private static E[] copyOfRange(final E[] array, int start, int end) { E[] result = (E[])Array.newInstance(array.getClass().getComponentType(), end - start); System.arraycopy(array, start, result, 0, end - start); @@ -238,7 +235,6 @@ public final class TmfFixedArray extends AbstractList implements RandomAcc * @see java.util.AbstractCollection#toArray(T[]) */ @Override - @SuppressWarnings("unchecked") public E[] toArray(E[] array) { if(array.length < fArray.length) { diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/util/TmfSortedArrayList.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/util/TmfSortedArrayList.java index 56a623d287..184b8868a2 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/util/TmfSortedArrayList.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/util/TmfSortedArrayList.java @@ -1,11 +1,11 @@ /******************************************************************************* * Copyright (c) 2011, 2012 Ericsson - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * * Contributors: * Francois Chouinard - Initial API and implementation *******************************************************************************/ @@ -16,18 +16,18 @@ import java.util.ArrayList; /** * Implementation of a sorted array list. - * + * * @version 1.0 - * @Francois Chouinard + * @author Francois Chouinard */ public class TmfSortedArrayList extends ArrayList { private static final long serialVersionUID = 1L; /** - * Inserts a new value in the list according to its sorted position. - * - * @param value A value to insert + * Inserts a new value in the list according to its sorted position. + * + * @param value A value to insert */ @SuppressWarnings("unchecked") public void insertSorted(T value) { -- 2.34.1