org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/StateSystemManager.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012 Ericsson
   3  * Copyright (c) 2010, 2011 École Polytechnique de Montréal
   4  * Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
   5  *
   6  * All rights reserved. This program and the accompanying materials are
   7  * made available under the terms of the Eclipse Public License v1.0 which
   8  * accompanies this distribution, and is available at
   9  * http://www.eclipse.org/legal/epl-v10.html
  10  *
  11  *******************************************************************************/
  12
  13 package org.eclipse.linuxtools.tmf.core.statesystem;
  14
  15 import java.io.File;
  16 import java.io.IOException;
  17
  18 import org.eclipse.linuxtools.internal.tmf.core.statesystem.HistoryBuilder;
  19 import org.eclipse.linuxtools.internal.tmf.core.statesystem.backends.IStateHistoryBackend;
  20 import org.eclipse.linuxtools.internal.tmf.core.statesystem.backends.InMemoryBackend;
  21 import org.eclipse.linuxtools.internal.tmf.core.statesystem.backends.NullBackend;
  22 import org.eclipse.linuxtools.internal.tmf.core.statesystem.backends.historytree.HistoryTreeBackend;
  23 import org.eclipse.linuxtools.internal.tmf.core.statesystem.backends.historytree.ThreadedHistoryTreeBackend;
  24 import org.eclipse.linuxtools.tmf.core.component.TmfComponent;
  25 import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
  26
  27 /**
  28  * This abstract manager class handles loading or creating state history files
  29  * for use in TMF's generic state system.
  30  *
  31  * @version 1.0
  32  * @author Alexandre Montplaisir
  33  */
  34 public abstract class StateSystemManager extends TmfComponent {
  35
  36     /** Size of the blocking queue to use when building a state history */
  37     private final static int QUEUE_SIZE = 10000;
  38
  39     /**
  40      * Load the history file matching the target trace. If the file already
  41      * exists, it will be opened directly. If not, it will be created from
  42      * scratch. In the case the history has to be built, it's possible to block
  43      * the calling thread until construction is complete.
  44      *
  45      * @param htFile
  46      *            The target name of the history file we want to use. If it
  47      *            exists it will be opened. If it doesn't, a new file will be
  48      *            created with this name/path.
  49      * @param htInput
  50      *            The IStateChangeInput to use for building the history file. It
  51      *            may be required even if we are opening an already-existing
  52      *            history (ie, for partial histories).
  53      * @param buildManually
  54      *            If false, the construction will wait for a signal before
  55      *            starting. If true, it will build everything right now and
  56      *            block the caller. It has no effect if the file already exists.
  57      * @return A IStateSystemQuerier handler to the state system, with which you
  58      *         can then run queries on the history.
  59      * @throws TmfTraceException
  60      *             If there was a problem reading or writing one of the files.
  61      *             See the contents of this exception for more info.
  62      * @since 2.0
  63      */
  64     public static ITmfStateSystem loadStateHistory(File htFile,
  65             IStateChangeInput htInput, boolean buildManually)
  66             throws TmfTraceException {
  67         ITmfStateSystem ss;
  68         IStateHistoryBackend htBackend;
  69
  70         /* If the target file already exists, do not rebuild it uselessly */
  71         // TODO for now we assume it's complete. Might be a good idea to check
  72         // at least if its range matches the trace's range.
  73         if (htFile.exists()) {
  74             /* Load an existing history */
  75             try {
  76                 htBackend = new HistoryTreeBackend(htFile);
  77                 ss = HistoryBuilder.openExistingHistory(htBackend);
  78                 return ss;
  79             } catch (IOException e) {
  80                 /*
  81                  * There was an error opening the existing file. Perhaps it was
  82                  * corrupted, perhaps it's an old version? We'll just
  83                  * fall-through and try to build a new one from scratch instead.
  84                  */
  85             }
  86         }
  87
  88         /* Create a new state history from scratch */
  89         HistoryBuilder builder;
  90
  91         if (htInput == null) {
  92             return null;
  93         }
  94         try {
  95             htBackend = new ThreadedHistoryTreeBackend(htFile,
  96                     htInput.getStartTime(), QUEUE_SIZE);
  97             builder = new HistoryBuilder(htInput, htBackend, buildManually);
  98         } catch (IOException e) {
  99             /*
 100              * If it fails here however, it means there was a problem writing to
 101              * the disk, so throw a real exception this time.
 102              */
 103             throw new TmfTraceException(e.toString(), e);
 104         }
 105         return builder.getStateSystemQuerier();
 106     }
 107
 108     /**
 109      * Create a new state system using a null history back-end. This means that
 110      * no history intervals will be saved anywhere, and as such only
 111      * {@link ITmfStateSystem#queryOngoingState} will be available.
 112      *
 113      * This has to be built "manually" (which means you should call
 114      * input.processEvent() to update the ongoing state of the state system).
 115      *
 116      * @param input
 117      *            The input plugin to build the history
 118      * @return Reference to the history-less state system that got built
 119      * @since 2.0
 120      */
 121     public static ITmfStateSystem newNullHistory(IStateChangeInput input) {
 122         IStateHistoryBackend backend = new NullBackend();
 123         HistoryBuilder builder = new HistoryBuilder(input, backend, true);
 124         ITmfStateSystem ss = builder.getStateSystemQuerier();
 125         return ss;
 126     }
 127
 128     /**
 129      * Create a new state system using in-memory interval storage. This should
 130      * only be done for very small state system, and will be naturally limited
 131      * to 2^31 intervals.
 132      *
 133      * This will block the caller while the construction is ongoing.
 134      *
 135      * @param input
 136      *            The state change input to use
 137      * @param buildManually
 138      *            Set to true to block the caller and build without using TMF
 139      *            signals (for test programs most of the time). Use false if you
 140      *            are using the TMF facilities (experiments, etc.)
 141      * @return Reference to the state system that just got built
 142      * @since 2.0
 143      */
 144     public static ITmfStateSystem newInMemHistory(IStateChangeInput input,
 145             boolean buildManually) {
 146         IStateHistoryBackend backend = new InMemoryBackend(input.getStartTime());
 147         HistoryBuilder builder = new HistoryBuilder(input, backend, buildManually);
 148         return builder.getStateSystemQuerier();
 149     }
 150 }