package JavaLinkedListDemo;

import java.io.* ;  // required to use the BufferedReader class

public class jmhUtilities {

  /** Default constructor to create a new instance of <code>jmhUtilities</code>.
   *  This constructor is not called because the <code>jmhUtilities</code> class
   *  contains only <code>static</code> methods.
   */
  jmhUtilities() {
  }

  /** Get a line of text entered by the user from the console.  The need for all
   *    this code is one thing that many people don&rsquo;t like about Java!  8-(
   *  <p>Here's how this method works:</p>
   *  <ul>
   *    <li>We want to read an entire line at once, and the only method
   *      available to do that in the Java API is the <code>ReadLine</code> method of the
   *      <code>BufferedReader</code> class</li>
   *    <li>Unfortunately, there is no constructor for a <code>BufferedReader</code> object
   *      that takes the only input object we have, <code>System.in</code>, which is an
   *      instance of the <code>InputStream</code> class. <code>BufferedReader</code>
   *      constructors only take objects of the <code>Reader</code> class.</li>
   *    <li>Therefore, we need to find some way to construct a <code>Reader</code> class (or
   *      a class derived from a <code>Reader</code> class from an <code>InputStream</code>
   *      object. Looking through the API, we find the &ldquo;bridge&rdquo; we need: the
   *      <code>InputStreamReader</code> class.</li>
   *    <li>So first we construct an instance of the <code>InputStreamReader</code> class
   *      from the system-supplied <code>System.in</code> object (of type
   *      <code>Inputstream</code>).</li>
   *    <li>Then we use that object to construct a <code>BufferedReader</code> object.</li>
   *  </ul>
   *  <p>As noted above, this complexity is definitely a turn-off to many
   *    people, but it is a nice demonstration of OOP and &ldquo;building bridges&rdquo;
   *    between objects, a common requirement of all OO languages and
   *    systems.</p>
   *  @return  <code>String</code> entered by the user
   */
  public static String ReadLine() {
    String strUserEntry = "" ;    // string entered by the user

    InputStreamReader isrConsole = new InputStreamReader( System.in ) ;
    BufferedReader brConsole = new BufferedReader( isrConsole ) ;

    try {
      System.out.flush() ;                    // ensure that prompt is visible
      strUserEntry = brConsole.readLine() ;   // read the user's input
    } catch ( IOException ioe ) {
      System.err.println( "An IOException has occurred in method ReadLine." ) ;
      System.err.println( "The system reported:" ) ;
      System.err.println( ioe.toString() ) ;
          // the toString() method is not really needed above, but I have
          //    included it for clarity to show what the system actually does
          //    automatically
      System.exit( 1 ) ;   // terminate program execution with an error flag
    }

    return strUserEntry ;
  }

}