tmf: Update Javadoc throughout tmf.ui

[deliverable/tracecompass.git] / org.eclipse.linuxtools.tmf.ui / src / org / eclipse / linuxtools / tmf / ui / viewers / events / TmfEventsCache.java

diff --git a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/viewers/events/TmfEventsCache.java b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/viewers/events/TmfEventsCache.java
index 0bf74dc300bbcaa87f7c82c0c7c38ed62bbe55d8..bb8c6a540fec7ba528f135de9fbc1f73370117f0 100644 (file)
--- a/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/viewers/events/TmfEventsCache.java
+++ b/org.eclipse.linuxtools.tmf.ui/src/org/eclipse/linuxtools/tmf/ui/viewers/events/TmfEventsCache.java
@@ -28,7 +28,10 @@ import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
 \r
 /**\r
  * The generic TMF Events table events cache\r
- * \r
+ *\r
+ * This can help avoid re-reading the trace when the user scrolls a window,\r
+ * for example.\r
+ *\r
  * @version 1.0\r
  * @author Patrick Tasse\r
  */\r
@@ -36,7 +39,7 @@ public class TmfEventsCache {
 \r
     /**\r
      * The generic TMF Events table cached event\r
-     * \r
+     *\r
      * @version 1.0\r
      * @author Patrick Tasse\r
      */\r
@@ -44,6 +47,14 @@ public class TmfEventsCache {
         ITmfEvent event;\r
         long rank;\r
 \r
+        /**\r
+         * Constructor for new cached events.\r
+         *\r
+         * @param iTmfEvent\r
+         *            The original trace event\r
+         * @param rank\r
+         *            The rank of this event in the trace\r
+         */\r
         public CachedEvent (ITmfEvent iTmfEvent, long rank) {\r
             this.event = iTmfEvent;\r
             this.rank = rank;\r
@@ -59,32 +70,70 @@ public class TmfEventsCache {
     private ITmfFilter fFilter;\r
     private final List<Integer> fFilterIndex = new ArrayList<Integer>(); // contains the event rank at each 'cache size' filtered events\r
 \r
+    /**\r
+     * Constructor for the event cache\r
+     *\r
+     * @param cacheSize\r
+     *            The size of the cache, in number of events\r
+     * @param table\r
+     *            The Events table this cache will cover\r
+     */\r
     public TmfEventsCache(int cacheSize, TmfEventsTable table) {\r
         fCache = new CachedEvent[cacheSize];\r
         fTable = table;\r
     }\r
 \r
+    /**\r
+     * Assign a new trace to this events cache. This clears the current\r
+     * contents.\r
+     *\r
+     * @param trace\r
+     *            The trace to assign.\r
+     */\r
     public void setTrace(ITmfTrace<?> trace) {\r
         fTrace = trace;\r
         clear();\r
     }\r
 \r
+    /**\r
+     * Clear the current contents of this cache.\r
+     */\r
     public synchronized void clear() {\r
         fCacheStartIndex = 0;\r
         fCacheEndIndex = 0;\r
         fFilterIndex.clear();\r
     }\r
 \r
+    /**\r
+     * Apply a filter on this event cache. This clears the current cache\r
+     * contents.\r
+     *\r
+     * @param filter\r
+     *            The ITmfFilter to apply.\r
+     */\r
     public void applyFilter(ITmfFilter filter) {\r
         fFilter = filter;\r
         clear();\r
     }\r
 \r
+    /**\r
+     * Clear the current filter on this cache. This also clears the current\r
+     * cache contents.\r
+     */\r
     public void clearFilter() {\r
         fFilter = null;\r
         clear();\r
     }\r
 \r
+    /**\r
+     * Get an event from the cache. This will remove the event from the cache.\r
+     *\r
+     * FIXME this does not currently remove the event!\r
+     *\r
+     * @param index\r
+     *            The index of this event in the cache\r
+     * @return The cached event, or 'null' if there is no event at that index\r
+     */\r
     public synchronized CachedEvent getEvent(int index) {\r
         if ((index >= fCacheStartIndex) && (index < fCacheEndIndex)) {\r
             int i = index - fCacheStartIndex;\r
@@ -94,6 +143,14 @@ public class TmfEventsCache {
         return null;\r
     }\r
 \r
+    /**\r
+     * Read an event, but without removing it from the cache.\r
+     *\r
+     * @param index\r
+     *            Index of the event to peek\r
+     * @return A reference to the event, or 'null' if there is no event at this\r
+     *         index\r
+     */\r
     public synchronized CachedEvent peekEvent(int index) {\r
         if ((index >= fCacheStartIndex) && (index < fCacheEndIndex)) {\r
             int i = index - fCacheStartIndex;\r
@@ -102,6 +159,16 @@ public class TmfEventsCache {
         return null;\r
     }\r
 \r
+    /**\r
+     * Add a trace event to the cache.\r
+     *\r
+     * @param event\r
+     *            The original trace event to be cached\r
+     * @param rank\r
+     *            The rank of this event in the trace\r
+     * @param index\r
+     *            The index this event will occupy in the cache\r
+     */\r
     public synchronized void storeEvent(ITmfEvent event, long rank, int index) {\r
         if (index == fCacheEndIndex) {\r
             int i = index - fCacheStartIndex;\r
@@ -116,6 +183,14 @@ public class TmfEventsCache {
         }\r
     }\r
 \r
+    /**\r
+     * Get the cache index of an event from his rank in the trace. This will\r
+     * take in consideration any filter that might be applied.\r
+     *\r
+     * @param rank\r
+     *            The rank of the event in the trace\r
+     * @return The position (index) this event should use once cached\r
+     */\r
     @SuppressWarnings("unchecked")\r
     public int getFilteredEventIndex(final long rank) {\r
         int current;\r
@@ -294,9 +369,8 @@ public class TmfEventsCache {
                 // Flag the UI thread that the cache is ready\r
                 if (monitor.isCanceled()) {\r
                     return Status.CANCEL_STATUS;\r
-                } else {\r
-                    return Status.OK_STATUS;\r
                 }\r
+                return Status.OK_STATUS;\r
             }\r
         };\r
         //job.setSystem(true);\r