/*******************************************************************************
- * 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.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.statesystem.ITmfStateSystemAnalysisModule;
-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;
* @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
- * @since 2.0
- */
- ITmfStatistics getStatistics();
-
- /**
- * Return the map of state systems associated with this trace.
- *
- * This view should be read-only (implementations should use
- * {@link Collections#unmodifiableMap}).
- *
- * @return The map of state systems
- * @since 2.0
- * @deprecated State systems now should be provided by analysis and use
- * {@link ITmfStateSystemAnalysisModule} and retrieve the modules
- * with {@link TmfTrace#getAnalysisModules(Class)} with Class
- * being TmfStateSystemAnalysisModule.class
- */
- @Deprecated
- Map<String, ITmfStateSystem> getStateSystems();
-
- /**
- * 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.
- *
- * @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
- * @deprecated State systems now should be provided by analysis and use
- * {@link ITmfStateSystemAnalysisModule}
- */
- @Deprecated
- void registerStateSystem(String id, ITmfStateSystem ss);
-
/**
* 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
*/
void indexTrace(boolean waitForCompletion);
+ // ------------------------------------------------------------------------
+ // Analysis getters
+ // ------------------------------------------------------------------------
+
/**
- * Returns an analysis module with the given id
+ * Returns an analysis module with the given ID.
*
- * @param analysisId
- * The analysis module id
- * @return The {@link IAnalysisModule} object
+ * @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
*/
- IAnalysisModule getAnalysisModule(String analysisId);
+ @Nullable
+ IAnalysisModule getAnalysisModule(String id);
/**
- * Return a map of analysis modules that are of a given class. Module are
- * already casted to the requested class
+ * Get a list of all analysis modules currently available for this trace.
*
- * @param moduleclass
- * Class returned module must extend
- * @return List of modules of class moduleclass
+ * @return An iterable view of the analysis modules
+ * @since 3.0
*/
- <T> Map<String, T> getAnalysisModules(Class<T> moduleclass);
+ @NonNull
+ Iterable<IAnalysisModule> getAnalysisModules();
/**
- * Returns a map of analysis modules applicable to this trace. The key is
- * the analysis id.
+ * Get an analysis module belonging to this trace, with the specified ID and
+ * class.
*
- * This view should be read-only (implementations should use
- * {@link Collections#unmodifiableMap}).
+ * @param moduleClass
+ * Returned modules must extend this class
+ * @param id
+ * 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
+ */
+ @Nullable
+ <T extends IAnalysisModule> T getAnalysisModuleOfClass(Class<T> moduleClass, String id);
+
+ /**
+ * Return the analysis modules that are of a given class. Module are already
+ * casted to the requested class.
*
- * @return The map of analysis modules
+ * @param moduleClass
+ * Returned modules must extend this class
+ * @return List of modules of class moduleClass
+ * @since 3.0
*/
- Map<String, IAnalysisModule> getAnalysisModules();
+ @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
*/