Interface ScrapedArticleReceiver

  • Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
    @FunctionalInterface
public interface ScrapedArticleReceiver
    A Java function-pointer / lambda-target that provides a means for deciding where to save downloaded article HTML, including a static-builder method for choosing to save articles directly to the file-system.

    This interface is a FunctionalInterface, meaning it has only one method which must be written to satisfy the requirements of implementing the interface.

    The method in this FunctionalInterface is here to receive Article's that have been downloaded by the class ScrapeArticles - allowing the programmer to decide where, how and when to save those Article's.

    Default Instance:
    There is a simple, 'static' Factory-Builder Method in this interface that may be used if the programmer is satisfied with saving downloaded Article classes to a simple directory on the File-System.


    • Field Summary

       
      Serializable ID
      Modifier and Type Field
      static long serialVersionUID

    • Method Summary

       
      @FunctionalInterface: (Lambda) Method
      Modifier and Type Method
      void receive​(Article articleBody, int sectionURLNum, int articleNum)
       
      Methods: Static Factory-Builder
      Modifier and Type Method
      static ScrapedArticleReceiver saveToFS​(String dirNameStr)

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.

        Functional Interfaces are usually not thought of as Data Objects that need to be saved, stored and retrieved; however, having the ability to store intermediate results along with the lambda-functions that helped get those results can make debugging easier.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final long serialVersionUID = 1;

    • Method Detail

      • receive

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        void receive​(Article articleBody,
             int sectionURLNum,
             int articleNum)
      throws ReceiveException
        FUNCTIONAL-INTERFACE METHOD: This is the method that must be fulfilled to meet the requirements of this @FunctionalInterface
        Parameters:
        articleBody - After an article has been downloaded by the ScrapeArticles class, it will build an instance of class Article and pass it to this class. It is the programmer's responsibility to ultimately decide what to do with news articles after they have been successfully scraped and parsed.
        sectionURLNum - This is a convenience parameter that informs the implementing-interface from which URL Section of the News Web-Sites main-page that this article is being downloaded.

        NOTE: Review the class ScrapeURLs to read more about "Section URL's." The number of "Section URL's" for a news web-site scrape is just the length of the Vector<URL> sectionURL's
        articleNum - This parameter informs the implementing-interface which article number is being downloaded. Each section-URL will have a number of different articles in the section. These numbers can be used to create unique file-names, for instance.
        Throws:
        ReceiveException - This exception may be thrown by the lambda-expression or class instance that implements this FunctionalInterface. It is not mandatory that this exception be used.

      • saveToFS

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        static ScrapedArticleReceiver saveToFS​(java.lang.String dirNameStr)
        saveToFS => Save To File-System

        This is a static factory-builder method that will produce a 'ScrapedArticleReceiver' that simply saves downloaded articles to a directory on the file-system.

        The user, here, merely needs to provide a Directory-Name using String parameter 'dirNameStr'. This is the most simple way to create an instance of this class.
        Parameters:
        dirNameStr - This is a directory on the file-system that will be used to save articles that are received directly to the file-system.
        Throws:
        WritableDirectoryException - This method shall check whether it is possible to write to the provided directory name.
        Code:
        Exact Method Body:
         WritableDirectoryException.check(dirNameStr);

 // Make sure that the directory name-string ends with the system File-Separator
 // character.  This '/' for UNIX and '\' for MS-DOS.

 final String finalDirNameStr = dirNameStr.endsWith(File.separator) 
     ? dirNameStr
     : dirNameStr + File.separator;

 // Create an instance of this functional-interface using a lambda-expression.
 // 
 // NOTE: This is literally just saving an object to a file using object-serialization.
 //       The exception catching / throwing is just to produce standardized error messages
 //       back to the user, if an exception occurs when saving files.

 return (Article articleBody, int sectionURLNum, int articleNum) ->
 {
     String outFileName = 
         finalDirNameStr +
         StringParse.zeroPad(sectionURLNum) + '.' +
         StringParse.zeroPad10e4(articleNum) + ".dat";

     try
         { FileRW.writeObjectToFile(articleBody, outFileName, true); }

     catch (Exception ex)
     {
         throw new ReceiveException(
             "A " + ex.getClass().getCanonicalName() + " was thrown while attempting to " +
             "write a downloaded article to the file-system.\n" +
             "Section-URL [" + sectionURLNum + "], Article Number [" + articleNum + "]\n" +
             "Unable to save file:\n" +
             outFileName + "\n" + 
             "Please review this exception's getCause() for more details.",
             ex, sectionURLNum, articleNum
         );
     }
 };