Package edu.gvsu.kurmasz.warszawa.io

Class InputHelper

java.lang.Object
edu.gvsu.kurmasz.warszawa.io.InputHelper
public class InputHelper
extends java.lang.Object
Shortcuts for opening InputStreams. In particular, this class contains shortcuts for:
  • opening an InputStream attached to the standard input using common names like "-" and "stdin"
  • opening and reading from a compressed file
  • attempting to open an InputStream and quitting on failure

More generally, there are two types of shortcuts: stream maps and filter maps:

Stream Maps
Stream Maps map filenames onto existing InputStreams. This feature is designed primarily map the names "-" and "stdin" to System.in (thereby allowing users to enter these names at the command line). However, programmers can use any any Map<String, InputStream>. This feature (1) allows users to specify custom names for System.in, and (2) allows the various open methods to easily re-reference existing open InputStreams.
Filter Maps
Filter maps map file suffixes onto filter-like InputStreams that pre-process the file being opened. (For example, the default filter map maps the suffix 'bz2' onto CBZip2InputStream.) Filters are designed primarily to automate the process of opening and decompressing compressed files (bzip2, gzip, etc.). However, they can be used to automate the pre-processing of any InputStream based on file suffix.

Note that the open methods that take File objects as parameters do not use stream maps. File objects are designed to describe specific files. There was little apparent benefit to allowing File objects to refer to "virtual" files like "-" and "stdin". In addition, the practice seemed to seemed to have high potential for confusion. Users who want to use both stream maps and filter maps can simply call the "filename" version of the method in quesiton and pass it file.getAbsolutePath().

Yes, I did go a little overboard with the convenience methods. (Once I added the few I use most, it was trivial to add the rest.)

Stream Map
nonedefaultexplicit
Filter Mapnonenot providedopenMappedInputStream(String)openUnfilteredInputStream(String, java.util.Map)
defaultopenFilteredInputStream(String)openMappedAndFilteredInputStream(String)openFilteredInputStream(String, java.util.Map)
explicitopenUnmappedInputStream(String, java.util.Map)openMappedInputStream(String, java.util.Map)openInputStream(java.io.File, java.util.Map)
Author:
Zachary Kurmas

  • Field Details

  • Method Details

    • makeDefaultInputStreamMap

      public static java.util.Map<java.lang.String,​java.io.InputStream> makeDefaultInputStreamMap()
      Generates a map of common names for the standard input to System.in.
      Returns:
      the map

    • makeDefaultFilterFactoryMap

      public static java.util.Map<java.lang.String,​InputHelper.FilterFactory> makeDefaultFilterFactoryMap()
      Generates a map of common file suffixes to appropriate InputHelper.FilterFactory objects. For example, the default map maps "bz2" to a FilterFactory that builds a CBZip2InputStream.
      Returns:
      a map of common suffixes to appropriate InputHelper.FilterFactory objects.

    • openInputStream

      public static java.io.InputStream openInputStream​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap) throws java.io.FileNotFoundException
      Opens an InputStream attached to the specified file, using streamMap and filterMap. Specifically,
      • If filename appears in streamMap, then return that InputSteam.
      • If filename's suffix appears in filterMap, then apply that FilterFactory.
      • If neither condition above applies, then return a new InputStream attached to the specified file .

      Note: InputStreams found in streamMap are not affected by the filterMap — even if there is an entry in filterMap for filename's suffix. It is assumed that the InputStreams in the streamMap will already be configured with any desired filtering/pre-processing.

      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      filterMap - a map of file suffixes to filters that will pre-process the file.
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the requested file does not exist.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openMappedAndFilteredInputStream

      public static java.io.InputStream openMappedAndFilteredInputStream​(java.lang.String filename) throws java.io.FileNotFoundException
      Calls openInputStream(String, java.util.Map, java.util.Map) with DEFAULT_INPUT_STREAM_MAP and DEFAULT_FILTER_FACTORY_MAP.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the requested file does not exist.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openFilteredInputStream

      public static java.io.InputStream openFilteredInputStream​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap) throws java.io.FileNotFoundException
      Calls openInputStream(String, java.util.Map, java.util.Map) with DEFAULT_FILTER_FACTORY_MAP.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the requested file does not exist.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openFilteredInputStream

      public static java.io.InputStream openFilteredInputStream​(java.lang.String filename) throws java.io.FileNotFoundException
      Calls openInputStream(String, java.util.Map, java.util.Map) with null and DEFAULT_FILTER_FACTORY_MAP.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the requested file does not exist.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openUnfilteredInputStream

      public static java.io.InputStream openUnfilteredInputStream​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap) throws java.io.FileNotFoundException
      Calls openInputStream(String, java.util.Map, java.util.Map) with null.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      Returns:
      either the InputStream in streamMap, or a new InputStream.
      Throws:
      java.io.FileNotFoundException - if the requested file does not exist.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openMappedInputStream

      public static java.io.InputStream openMappedInputStream​(java.lang.String filename, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap) throws java.io.FileNotFoundException
      Calls openInputStream(String, java.util.Map, java.util.Map) with DEFAULT_INPUT_STREAM_MAP.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      filterMap - a map of file suffixes to filters that will pre-process the file.
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the requested file does not exist.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openMappedInputStream

      public static java.io.InputStream openMappedInputStream​(java.lang.String filename) throws java.io.FileNotFoundException
      Calls openInputStream(String, java.util.Map, java.util.Map) with DEFAULT_INPUT_STREAM_MAP and null.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the requested file does not exist.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openUnmappedInputStream

      public static java.io.InputStream openUnmappedInputStream​(java.lang.String filename, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap) throws java.io.FileNotFoundException
      Calls openInputStream(String, java.util.Map, java.util.Map) with null.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      filterMap - a map of file suffixes to filters that will pre-process the file.
      Returns:
      a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the requested file does not exist.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openInputStream

      public static java.io.InputStream openInputStream​(java.io.File file, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap) throws java.io.FileNotFoundException
      Opens an InputStream attached to the specified file using the filterMap. Specifically, if the file's suffix appears in filterMap, then apply that FilterFactory, otherwise, return a new InputStream attached to the specified file
      Parameters:
      file - the name of the file to open
      filterMap - a map of file suffixes to filters that will pre-process the file.
      Returns:
      a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the file cannot be opened.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openFilteredInputStream

      public static java.io.InputStream openFilteredInputStream​(java.io.File file) throws java.io.FileNotFoundException
      Calls openInputStream(java.io.File, java.util.Map) with DEFAULT_FILTER_FACTORY_MAP
      Parameters:
      file - the file to open
      Returns:
      a new, possibly filtered, InputStream.
      Throws:
      java.io.FileNotFoundException - if the file cannot be opened.
      InputHelper.FilterFactory.FilterFactoryException - if the specified filter cannot handle the given file.

    • openInputStreamOrQuit

      public static java.io.InputStream openInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap, java.io.PrintStream error, int exitValue)
      Calls openInputStream(String, java.util.Map, java.util.Map) and exits if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      filterMap - a map of file suffixes to filters that will pre-process the file.
      error - the PrintStream to which to write any errors.
      exitValue - the value to pass to System.exit in the event of an error
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openInputStreamOrQuit

      public static java.io.InputStream openInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap)
      Calls openInputStream(String, java.util.Map, java.util.Map) and exits if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      filterMap - a map of file suffixes to filters that will pre-process the file.
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openMappedAndFilteredInputStreamOrQuit

      public static java.io.InputStream openMappedAndFilteredInputStreamOrQuit​(java.lang.String filename, java.io.PrintStream error, int exitValue)
      Calls openInputStream(String, java.util.Map, java.util.Map) with DEFAULT_INPUT_STREAM_MAP and DEFAULT_FILTER_FACTORY_MAP and exists if the file can't be opened.
      Parameters:
      error - the PrintStream to which to write any errors.
      exitValue - the value to pass to System.exit in the event of an error
      filename - the name of the file to open (or one of the keys in streamMap).
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openMappedAndFilteredInputStreamOrQuit

      public static java.io.InputStream openMappedAndFilteredInputStreamOrQuit​(java.lang.String filename)
      Calls openInputStream(String, java.util.Map, java.util.Map) with DEFAULT_INPUT_STREAM_MAP and DEFAULT_FILTER_FACTORY_MAP and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openFilteredInputStreamOrQuit

      public static java.io.InputStream openFilteredInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap, java.io.PrintStream error, int exitValue)
      Calls openFilteredInputStream(String, java.util.Map) and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      error - the PrintStream to which to write any errors.
      exitValue - the value to pass to System.exit in the event of an error
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openFilteredInputStreamOrQuit

      public static java.io.InputStream openFilteredInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap)
      Calls openFilteredInputStream(String, java.util.Map) and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openUnfilteredInputStreamOrQuit

      public static java.io.InputStream openUnfilteredInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap, java.io.PrintStream error, int exitValue)
      Calls openUnfilteredInputStream(String, java.util.Map) and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      error - the PrintStream to which to write any errors.
      exitValue - the value to pass to System.exit in the event of an error
      Returns:
      either the InputStream in streamMap, or a new InputStream.

    • openUnfilteredInputStreamOrQuit

      public static java.io.InputStream openUnfilteredInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​java.io.InputStream> streamMap)
      Calls openUnfilteredInputStream(String, java.util.Map) and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      streamMap - a map of file names to existing InputStreams
      Returns:
      either the InputStream in streamMap, or a new InputStream.

    • openMappedInputStreamOrQuit

      public static java.io.InputStream openMappedInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap, java.io.PrintStream error, int exitValue)
      Calls openMappedInputStream(String, java.util.Map) and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      filterMap - a map of file suffixes to filters that will pre-process the file.
      error - the PrintStream to which to write any errors.
      exitValue - the value to pass to System.exit in the event of an error
      Returns:
      either the InputStream in the default stream map or a new, possibly filtered, InputStream.

    • openMappedInputStreamOrQuit

      public static java.io.InputStream openMappedInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap)
      Calls openMappedInputStream(String, java.util.Map) and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      filterMap - a map of file suffixes to filters that will pre-process the file.
      Returns:
      either the InputStream in the default stream map or a new, possibly filtered, InputStream.

    • openUnmappedInputStreamOrQuit

      public static java.io.InputStream openUnmappedInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap, java.io.PrintStream error, int exitValue)
      Calls openUnmappedInputStream(String, java.util.Map) and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      filterMap - a map of file suffixes to filters that will pre-process the file.
      error - the PrintStream to which to write any errors.
      exitValue - the value to pass to System.exit in the event of an error
      Returns:
      a new, possibly filtered, InputStream.

    • openUnmappedInputStreamOrQuit

      public static java.io.InputStream openUnmappedInputStreamOrQuit​(java.lang.String filename, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap)
      Calls openUnmappedInputStream(String, java.util.Map) and exists if the file can't be opened.
      Parameters:
      filename - the name of the file to open (or one of the keys in streamMap).
      filterMap - a map of file suffixes to filters that will pre-process the file.
      Returns:
      a new, possibly filtered, InputStream.

    • openInputStreamOrQuit

      public static java.io.InputStream openInputStreamOrQuit​(java.io.File file, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap, java.io.PrintStream error, int exitValue)
      Calls openInputStream(java.io.File, java.util.Map) and exits if the file can't be opened.
      Parameters:
      file - the file to open (or one of the keys in streamMap).
      filterMap - a map of file suffixes to filters that will pre-process the file.
      error - the PrintStream to which to write any errors.
      exitValue - the value to pass to System.exit in the event of an error
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openInputStreamOrQuit

      public static java.io.InputStream openInputStreamOrQuit​(java.io.File file, java.util.Map<java.lang.String,​InputHelper.FilterFactory> filterMap)
      Calls openInputStream(java.io.File, java.util.Map) and exits if the file can't be opened.
      Parameters:
      file - the file to open (or one of the keys in streamMap).
      filterMap - a map of file suffixes to filters that will pre-process the file.
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openFilteredInputStreamOrQuit

      public static java.io.InputStream openFilteredInputStreamOrQuit​(java.io.File file, java.io.PrintStream error, int exitValue)
      Calls openFilteredInputStream(java.io.File) and exits if the file can't be opened.
      Parameters:
      file - the file to open (or one of the keys in streamMap).
      error - the PrintStream to which to write any errors.
      exitValue - the value to pass to System.exit in the event of an error
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.

    • openFilteredInputStreamOrQuit

      public static java.io.InputStream openFilteredInputStreamOrQuit​(java.io.File file)
      Calls openFilteredInputStream(java.io.File) and exits if the file can't be opened.
      Parameters:
      file - the file to open (or one of the keys in streamMap).
      Returns:
      either the InputStream in streamMap, or a new, possibly filtered, InputStream.