= !EventBenchConsole =

[[TracNav(TOC|nocollapse)]]
[[TOC(inline)]]

== Recent Changes ==

[[ChangeLog(/trunk/EventBenchConsole, 3)]]

== Requirements ==
 * Java 6
 * [wiki:/Software/EventBenchCore EventBenchCore]
 * [wiki:/Software/JavaHelperLib JavaHelperLib]
 * [wiki:/Software/JavaCommons JavaCommons]

== Description ==

A console application that uses the [wiki:Software/EventBenchCore EventBenchCore]. It provides three translation layers:
 1. Windows MFC applications logged with the [wiki:Software/userlog MFCUsageMonitor] and for replaying with [wiki:Software/MFCReplay MFCReplay]. How sequences of Windows messages are translated into events is explained [wiki:Software/EventBenchConsole/MFCTranslationLayer here]
 1. PHP based web applications logged with [wiki:Software/PHPMonitor PHPMonitor] and replaying with [http://curl.haxx.se/ curl]
 1. To the [http://guitar.cs.umd.edu/ GUITAR] project.

== Exemplary Work-flows ==

Creating a based on monitored sessions:
{{{
convertToXml logfile.txt log.xml
parseXML log.xml
generateReplayfile replay.xml
}}}

Creating a randomly generated replay session based on a first-order Markov model:
{{{
convertToXml logfile.txt log.xml
parseXML log.xml
trainMarkovModel markovModel
generateRandomReplay markovModel replay.xml
}}}

== Commands ==
 * {{{calcCoverage <modelname> <observedSequences> [sequenceNames] <minCovLength> <maxCovLength>}}}
  - Calculates the coverage criteria.
  - Examples:
   - {{{calcCoverage markovModel trainingSequences [generatedSequences_1 generatedSequences_2] 2 3}}}
 * {{{calcEntropy <modelname>}}}
  - Calculates the entropy of a first-order Markov model.
  - Examples:
   - {{{calcEntropy markovModel}}}
 * {{{deleteObject <objectname>}}}
  - Deletes an object from the storage.
  - Examples:
   - {{{deleteObject markovModel}}}
   - {{{deleteObject sequences}}}
 * {{{generateFixedLengthSequences <modelname> <sequencesName> <minlenght> <maxlength> {<all>} {<numSequences>}}}}
  - Generates sequences of a predefined length. This command first generates all possible sequences of the defined lengths. In case {{{<all>}}} is {{{true}}}, all generated sequences are then stored. In case {{{<all>}}} is false {{{<numSequences>}}} sequences will be randomly drawn from all the sequences, based on their probability according to {{{<modelname>}}}. The default value for {{{<all>}}} is true.
  - Examples:
   - {{{generateFixedLengthSequences markovModel generatedSequences 3 5}}}
   - {{{generateFixedLengthSequences markovModel generatedSequences 3 5 true}}}
   - {{{generateFixedLengthSequences markovModel generatedSequences 3 5 false 1000}}}
 * {{{generateRandomReplay <modelname> <filename> {<numSessions>}}}}
  - Generates a randomly generated replay from a previously learned usage model. The default number of sessions generate is 1. With this command, is it not possible to configure the length of the generated sequences. 
  - Examples:
   - {{{generateRandomReplay markovModel replay.xml}}}
   - {{{generateRandomReplay markovModel replay.xml 5}}}
 * {{{generateRandomSequenecs <modelName> <sequencesName> <numSessions> <minLength> <maxLength> {<maxIter>}}}}
  - Generates sequences of a predefined length. This command randomly generates sequences from the usage profile. In case the length of a generated session has the desired length, it is added to the set of sequences. The maximum number of randomly generated sequences is defined by {{{<maxIter>}}}, which is by default {{{<numSessions>}}}*10. 
 * {{{generateReplayfile <filename> <sequences>}}}
  - Generates a replay file from a set of sequences.
  - Examples:
   - {{{generateReplayfile d:/data/replay.xml sequences}}}
 * {{{listStates <modelName> {<sort>}}}}
  - Lists all states of a stochastic process. If {{{<sort>}}} is true, the states will be sorted alphabetically.
  - Examples:
   - {{{listStates markovModel}}}
   - {{{listStates markovModel true}}}
 * {{{load <filename>}}}
  - Loads a data container from a file. All currently stored data is discarded.
  - Examples:
   - {{{load d:/data.dat}}}
 * {{{loadObject <filename> <objectName>}}}
  - Loads an object from a file to the storage.
  - Examples:
   - {{{loadObject d:/markovModel.obj markovModel}}}
 * {{{modelSize <modelname>}}}
  - Prints information about the size of a usage profile.
  - Examples:
   - {{{modelSize markovModel>}}}
 * {{{printDot <modelname>}}}
  - Prints the [http://en.wikipedia.org/wiki/DOT_language Dot] graph representation of a model to the console.
  - Examples:
   - {{{printDot markovModel}}}
 * {{{printTrieDot <modelname>}}}
  - Prints the [http://en.wikipedia.org/wiki/DOT_language Dot] graph representation of a trie used by a model to the console.
  - Examples:
   - {{{printTrieDot markovModel}}}
   - {{{printTrieDot predictionByPartialMatch}}}
 * {{{save <filename>}}}
  - Saves all currently stored data to a file.
  - Examples:
   - {{{save d:/data.dat}}}
 * {{{saveObject <filename> <objectname>}}}
  - Saves a single object from the storage to a file.
  - Examples:
   - {{{saveObject d:/markovModel.obj markovModel}}}
 * {{{sequenceStatistics <sequencesName>}}}
  - Prints statistics about a collection of sequences.
  - Examples:
   - {{{sequenceStatistics sequences}}}
 * {{{showMarkovModel <modelname> {<showNodeNames>}}}}
  - Opens a window that displays a first-order Markov model as a directed graph. Per default, the node names are not shown, as the graph gets very ugly and has overlapping nodes if they are shown.
  - Examples:
   - {{{showMarkovModel markovModel}}}
   - {{{showMarkovModel markovModel true}}}
 * {{{showSequences <sequencesName>}}}
  - Opens a dialog that display a list of all sequences that are part of the current sequence set, including their sizes. The sequences can be edited using this dialog.
 * {{{showTimer <timerName>}}}
  - Prints how many milliseconds elapsed since the start of the time.
  - Examples:
   - {{{showTimer timer}}}
 * {{{showTrie <modelname>}}}
  - Opens a window that displays a trie underlying a stochastic process.
  - Examples:
   - {{{showTrie markovModel}}}
   - {{{showTrie predictionByPartialMatch}}}
 * {{{startFileListener <filename>}}}
  - Starts a !FileOutputListener, i.e., pipes all output into the specified file. In case {{{stopFileListener}}} is not called, it is not guaranteed that all output will actually be written!
  - Examples:
   - {{{startFileListener d:/output.log}}}
 * {{{startTimer <timerName>}}}
  - Starts a timer.
  - Examples:
   - {{{startTimer timer}}}
 * {{{stopFileListener <filename>}}}
  - Stops a !FileOutputListener and guarantees that all captured output is written to a file.
  - Examples:
   - {{{stopFileListener d:/output.log}}}
 * {{{trainDFA <modelname> <sequencesName>}}}
  - Trains a Deterministic Finite Automaton (DFA) from a collection of sequences.
  - Examples:
   - {{{trainDFA dfa trainingSequences}}}
 * {{{trainMarkovModel <modelName> <sequencesName> {<order>}}}}
  - Trains a Markov model based from a collection of seqeuences. The default {{{<order>}}} of the model is 1.
  - Examples:
   - {{{trainMarkovModel markovModel trainingSequences}}}
   - {{{trainMarkovModel markovModel trainingSequences 3}}}
 * {{{trainPPM <modelName> <sequencesName> <probEscape> <maxOrder> {<minOrder>}}}}
  - Trains a Prediction by Partial Match (PPM) model based from a collection of sequences. The default {{{<minOrder>}}} is 0, i.e., random selection.
  - Examples:
   - {{{trainPPM PPMModel trainingSequences 0.01 3}}}
   - {{{trainPPM PPMModel trainingSequences 0.01 3 1}}}
 * {{{updateModel <modelname> <sequencesName>}}}
  - Updates a usage profile with a collection of sequences. This reinforces the model, i.e., it is not completly retrained, but the probabilities are merely updated using the new information.
  - Examples:
   - {{{updateModel markovModel newTrainingSequences}}}

=== Commands for handling data generated by [wiki:Software/userlog MFCUsageMonitor] ===
 * {{{convertToXml <filenameSource> <filenameTarget> {<base64>}}}}
  - Converts a logfile with prefixes created by the [wiki:Software/userlog MFCUsageMonitor] into an XML file containing the logged sessions.
  - Examples: 
   - {{{convertToXml d:/logfile.txt d:/log.xml}}}
   - {{{convertToXml d:/logfile.txt d:/log.xml true}}}
 * {{{convertDirToXml <directoryNames> <filenameTarget> {<base64>}}}}
  - Converts all files in a directory into one XML file containing all sessions, the same way {{{convertToXml}}} works. 
  - Examples:
   - {{{convertDirToXml d:/logdir d:/log.xml}}}
   - {{{convertDirToXml d:/logdir d:/log.xml true}}}
 * {{{parseXML <filename> {<countMessageOccurences>}}}}
  - Parses an XML file containing users sessions. If {{{countMessageOccurences}}} is true, a statistic containing how often each message occurred in the log is printed. 
  - Examples:
   - {{{parseXML d:/log.xml}}}
   - {{{parseXML d:/log.xml true}}}

=== Commands for handling data generated by [wiki:Software/PHPMonitor PHPMonitor] ===
 * {{{loadWebSequences <filename> <sequencesName> {<serverUrl>} {<timeout> <minSessionLength> <maxSessionLength>} {<frequentUserThreshold>}}}}
  - Parses a logfile generated by [wiki:Software/PHPMonitor PHPMonitor] and creates a collection of sequences from it. The default {{{<timeout>}}} is 3600000 milliseconds, the default {{{<minSessionLength>}}} is 2, the default {{{<maxSessionLength>}}} is 100. In case a {{{<frequenceUserThreshold>}}} is defined, additional collection of sequences will be defined for all users that have more sessions than this threshold, that fulfill the session length requirements.
  - Examples:
   - {{{loadWebSequences d:/websessions.log web-sequences}}}
   - {{{loadWebSequences d:/websessions.log web-seqeunces http://www.swe.informatik.uni-goettingen.de}}}
   - {{{loadWebSequences d:/websessions.log web-seqeunces http://www.swe.informatik.uni-goettingen.de 7200000 4 50}}}
   - {{{loadWebSequences d:/websessions.log web-seqeunces http://www.swe.informatik.uni-goettingen.de 7200000 4 50 20}}}

=== Commands for working with [http://guitar.cs.umd.edu/ GUITAR] ===
 * {{{efgTestCasesToSequences <folder> <sequencesName> {<efgFileName>}}}}
  - Generates a collection of sequences from GUITAR test cases. If an Event-Flow Graph (EFG) file is defined, it will be used to resolve the widget IDs associated with the events in the test cases. The widget IDs are used as target for the events.
  - Examples:
   - {{{efgTestCasesToSequences d:/efg-testcases testSequences}}}
   - {{{efgTestCasesToSequences d:/efg-testcases testSequences d:/application.efg}}}
 * {{{efgToDFA <filename> <modelname>}}}
  - Creates a Deterministic Finite Automaton (DFA) from an Event-Flow Graph (EFG).
  - Examples:
   - {{{efgToDFA d:/application.efg dfa}}}
 * {{{efgToMM <filename> <modelname>}}}}
  - Creates a first-order Markov model from an Event-Flow Graph (EFG). The model is such that all possible following events are equally likely. To change that, the {{{updateModel}}} command with a collection of sequences obtained using {{{<efgTestCaseToSequences}}} command can be used.
  - Examples:
   - {{{efgToMM d:/application.efg markovModel}}}