001package Torello.HTML.Tools.NewsSite;
002
003import Torello.Java.*;
004import Torello.Java.Additional.Ret4;
005
006import java.io.*;
007import java.util.Vector;
008
009/**
010 * When the main iteration-loop for downloading news-articles is running, the loop-variables are
011 * kept current to this class; so if (while watching the downloader), the programmer has decided
012 * to go take a break (and presses {@code Control-^C}), 'download progress' won't be lost and
013 * starting over with articles that have already been saved won't be necessary.
014 * 
015 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=PAUSE>
016 */
017public interface Pause extends Serializable
018{
019    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
020    public static final long serialVersionUID = 1;
021
022    /**
023     * This method needs to save the current download state.  The three integers provided are all
024     * that the download logic needs in order to identify which newspaper article {@code URL's}
025     * have already downloaded - <I>and, therefore, where to begin the download process after a
026     * pause or break.</I>  The instance of {@code Vector} that is required by this method's 
027     * parameter list contain the "Download Results" for each news-{@code Article} in the
028     * {@code URL} list.
029     * 
030     * @param results  This is the two dimensional {@code Vector} that contains instances of
031     * {@code 'DownloadResult'}.  Each news-{@code Article} in each section of a newspaper
032     * website has a specific location in this two dimensional {@code Vector}.  As the downloader
033     * retrieves (or fails) to scrape news-{@code Article's}, the result of the scrape (or 
034     * scrape-attempt) are inserted into this 2-D {@code Vector}.
035     * 
036     * @param outerCounter This is the outer-{@code Vector} index of the last {@code URL}
037     * downloaded.
038     * 
039     * @param innerCounter This is the inner-{@code Vector} index of the last {@code URL}
040     * downloaded.
041     * 
042     * @param successCounter This is how many of the {@code URL's} that were downloaded without
043     * throwing any exceptions.
044     */
045    public void saveState(
046            Vector<Vector<DownloadResult>> results,
047            int outerCounter, int innerCounter, int successCounter
048        ) throws PauseException;
049
050    /**
051     * This method loads the state of the downloader.  This can be helpful if the user wishes to 
052     * "pause" the download when long-lists of article {@code URL's} are being retrieved.  Also, if
053     * the downloader exits due to an exception, the state of download is maintained.
054     * @return An instance of {@code Ret4<Vector<Vector<DownloadResult>>, Integer, Integer, Integer>}
055     * <BR /><BR /><UL CLASS=JDUL>
056     * <LI>{@code Ret4.a} - The current state of the "Return {@code Vector}".  This two dimensional
057     *                      {@code Vector} fills up with instances of enumerated-type
058     *                      {@code DownloadResult}.
059     * </LI>
060     * <LI>{@code Ret2.b} - The outer-{@code Vector} index of the last attempted newspaper article
061     *                      {@code URL} download.
062     * </LI>
063     * <LI>{@code Ret2.c} - The inner-{@code Vector} index of the last attempted newspaper article
064     *                      {@code URL} download.
065     * </LI>
066     * <LI>{@code Ret2.d} - The number of article {@code URL's} that have successfully downloaded.
067     * </LI>
068     * </UL>
069     */
070    public Ret4<Vector<Vector<DownloadResult>>, Integer, Integer, Integer> loadState()
071        throws PauseException;
072
073    /**
074     * If the {@code Pause} implementation needs initialization, it ought to implement this method.
075     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</B></SPAN>
076     * The initialize process should ensure that a call to {@code loadState()} will return a
077     * {@code Ret4} data-structure whose integer fields are all equal to zero.  These fields are
078     * counters, and when download begins, if they are not-zero, then many news-articles will not
079     * be scraped.
080     * <BR /><BR /><B><SPAN STYLE="color: red;">ALSO:</B></SPAN>
081     * On initialization, the value for the 2-D {@code Vector} in the {@code Ret4} data-structure
082     * need only be present - <B><I>it does not matter what values have been inserted into it, nor
083     * the sizes of the sub-{@code Vector's}.</I></B>  Do note that it's values will be clobbered by
084     * the downloader if / when the downloader determines that the download process is starting at
085     * the beginning.
086     * @throws PauseException This exception is thrown if the implementation of this {@code interface}
087     * fails to init or load.
088     */
089    public void initialize() throws PauseException;
090
091    /**
092     * This method is a {@code static}-factory method that returns an instance of this
093     * {@code interface Pause} that uses the file-system for saving the state to a user-specified
094     * file-name.
095     * @param saveFileName This is just the name of the data-file where state shall be saved.
096     * This state contains only two integers, and is, therefore, an extremely small data-file.
097     * @return A functioning instance of this interface - one that uses a flat file for saving state.
098     */
099    public static Pause getFSInstance(String saveFileName)
100        throws PauseException
101    { return new PauseFS(saveFileName); }
102}