001package net.kreatious.pianoleopard.history;
002
003import javax.sound.midi.InvalidMidiDataException;
004
005/**
006 * Visits the events performed historically by the user.
007 * <p>
008 * Methods are called from various threads, but are guaranteed to not be called
009 * concurrently.
010 *
011 * @author Jay-R Studer
012 */
013public abstract class HistoryVisitor {
014    /**
015     * Called when the user begins a practice session. The file being practiced
016     * will be given by a previous call to {@link #onFile(byte[], long)}.
017     *
018     * @param time
019     *            the epoch time in milliseconds the sequence was started at
020     */
021    public void onStart(long time) {
022    }
023
024    /**
025     * Called when the user has opened a file.
026     *
027     * @param hash
028     *            the SHA-256 hash code of the file that was opened
029     * @param time
030     *            the epoch time in milliseconds the event was played at
031     */
032    public void onFile(byte[] hash, long time) {
033    }
034
035    /**
036     * Called when the user has pressed a key in the past.
037     *
038     * @param status
039     *            the status byte of the message the user played
040     * @param data1
041     *            the first data byte of the message
042     * @param data2
043     *            the second data byte of the message
044     * @param currentTime
045     *            the current song time in microseconds the message was played
046     *            at
047     * @param time
048     *            the epoch time in milliseconds the event was played at
049     * @throws InvalidMidiDataException
050     *             if the message was invalid
051     */
052    public void onKey(byte status, byte data1, byte data2, long currentTime, long time) throws InvalidMidiDataException {
053    }
054
055    /**
056     * Called after parsing is complete.
057     * <p>
058     * This method may be called multiple times, and is guaranteed to be called
059     * at least once if the log file is accessible. If notifications are no
060     * longer desired, then the visitor needs to be unregistered.
061     * <p>
062     * If the {@link History} class was unable to initialize logging, this
063     * method is never called.
064     */
065    public abstract void onParsingComplete();
066}