/*******************************************************************************
- * Copyright (c) 2009, 2013 Ericsson, École Polytechnique de Montréal
+ * Copyright (c) 2009, 2014 Ericsson, École Polytechnique de Montréal
*
* All rights reserved. This program and the accompanying materials are
* made available under the terms of the Eclipse Public License v1.0 which
* Francois Chouinard - Updated as per TMF Trace Model 1.0
* Geneviève Bastien - Added timestamp transforms and timestamp
* creation functions
+ * Patrick Tasse - Add support for folder elements
*******************************************************************************/
package org.eclipse.linuxtools.tmf.core.trace;
-import java.util.Collections;
-import java.util.Map;
-
import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IStatus;
-import org.eclipse.linuxtools.tmf.core.component.ITmfDataProvider;
+import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
+import org.eclipse.linuxtools.tmf.core.analysis.IAnalysisModule;
+import org.eclipse.linuxtools.tmf.core.component.ITmfEventProvider;
import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
-import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
-import org.eclipse.linuxtools.tmf.core.statistics.ITmfStatistics;
import org.eclipse.linuxtools.tmf.core.synchronization.ITmfTimestampTransform;
import org.eclipse.linuxtools.tmf.core.timestamp.ITmfTimestamp;
import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimeRange;
* @see ITmfTraceIndexer
* @see ITmfEventParser
*/
-public interface ITmfTrace extends ITmfDataProvider {
+public interface ITmfTrace extends ITmfEventProvider {
// ------------------------------------------------------------------------
// Constants
* @param resource
* the trace resource
* @param path
- * the trace path
+ * the trace path. The path should suitable for passing to
+ * <code>java.io.File(String)</code> and should use the
+ * platform-dependent path separator.
* @param type
* the trace event type
* @throws TmfTraceException
void initTrace(IResource resource, String path, Class<? extends ITmfEvent> type) throws TmfTraceException;
/**
- * Validate that the trace is of the correct type.
+ * Initialize a newly instantiated "empty" trace object. This is used to
+ * properly parameterize an ITmfTrace instantiated with its parameterless
+ * constructor.
+ * <p>
+ * Typically, the parameterless constructor will provide the block size and
+ * its associated parser and indexer.
+ *
+ * @param resource
+ * the trace resource
+ * @param path
+ * the trace path
+ * @param type
+ * the trace event type
+ * @param name
+ * the trace name
+ * @throws TmfTraceException
+ * If we couldn't open the trace
+ */
+ void initTrace(IResource resource, String path, Class<? extends ITmfEvent> type, String name) throws TmfTraceException;
+
+ /**
+ * Validate that the trace is of the correct type. The implementation should
+ * return a TraceValidationStatus to indicate success with a certain level
+ * of confidence.
*
* @param project
* the eclipse project
* @param path
- * the trace path
+ * the trace path. The path should suitable for passing to
+ * <code>java.io.File(String)</code> and should use the
+ * platform-dependent path separator.
+ *
* @return an IStatus object with validation result. Use severity OK to
* indicate success.
+ * @see TraceValidationStatus
* @since 2.0
*/
IStatus validate(IProject project, String path);
int getCacheSize();
/**
- * @return The statistics provider for this trace
+ * Index the trace. Depending on the trace type, this could be done at the
+ * constructor or initTrace phase too, so this could be implemented as a
+ * no-op.
+ *
+ * @param waitForCompletion
+ * Should we block the caller until indexing is finished, or not.
* @since 2.0
*/
- ITmfStatistics getStatistics();
+ void indexTrace(boolean waitForCompletion);
+
+ // ------------------------------------------------------------------------
+ // Analysis getters
+ // ------------------------------------------------------------------------
/**
- * Return the map of state systems associated with this trace.
+ * Returns an analysis module with the given ID.
*
- * This view should be read-only (implementations should use
- * {@link Collections#unmodifiableMap}).
+ * @param id
+ * The analysis module ID
+ * @return The {@link IAnalysisModule} object, or null if an analysis with
+ * the given ID does no exist.
+ * @since 3.0
+ */
+ @Nullable
+ IAnalysisModule getAnalysisModule(String id);
+
+ /**
+ * Get a list of all analysis modules currently available for this trace.
*
- * @return The map of state systems
- * @since 2.0
+ * @return An iterable view of the analysis modules
+ * @since 3.0
*/
- Map<String, ITmfStateSystem> getStateSystems();
+ @NonNull
+ Iterable<IAnalysisModule> getAnalysisModules();
/**
- * If a state system is not build by the trace itself, it's possible to
- * register it if it comes from another source. It will then be accessible
- * with {@link #getStateSystems} normally.
+ * Get an analysis module belonging to this trace, with the specified ID and
+ * class.
*
+ * @param moduleClass
+ * Returned modules must extend this class
* @param id
- * The unique ID to assign to this state system. In case of
- * conflicting ID's, the new one will overwrite the previous one
- * (default Map behavior).
- * @param ss
- * The already-built state system
- * @since 2.0
+ * The ID of the analysis module
+ * @return The analysis module with specified class and ID, or null if no
+ * such module exists.
+ * @since 3.0
*/
- void registerStateSystem(String id, ITmfStateSystem ss);
+ @Nullable
+ <T extends IAnalysisModule> T getAnalysisModuleOfClass(Class<T> moduleClass, String id);
/**
- * Index the trace. Depending on the trace type, this could be done at the
- * constructor or initTrace phase too, so this could be implemented as a
- * no-op.
+ * Return the analysis modules that are of a given class. Module are already
+ * casted to the requested class.
*
- * @param waitForCompletion
- * Should we block the caller until indexing is finished, or not.
- * @since 2.0
+ * @param moduleClass
+ * Returned modules must extend this class
+ * @return List of modules of class moduleClass
+ * @since 3.0
*/
- void indexTrace(boolean waitForCompletion);
+ @NonNull
+ <T> Iterable<T> getAnalysisModulesOfClass(Class<T> moduleClass);
// ------------------------------------------------------------------------
// Trace characteristics getters
* Creates a timestamp for this trace, using the transformation formula
*
* @param ts
- * The time in long with which to create the timestamp
+ * The time in nanoseconds with which to create the timestamp
* @return The new timestamp
* @since 3.0
*/