Module org.hsqldb.sqltool
Package org.hsqldb.cmdline

## Class SqlFile

- java.lang.Object
- - org.hsqldb.cmdline.SqlFile

-     public class SqlFile
      extends java.lang.Object

  Encapsulation of SQL text and the environment under which it will be executed with a JDBC Connection. 'SqlInputStream' would be a more precise name, but the content we are talking about here is what is colloqially known as the contents of "SQL file"s.

  The file `src/org/hsqldb/sample/SqlFileEmbedder.java` in the HSQLDB distribution provides an example for using SqlFile to execute SQL files directly from your own Java classes.

  The complexities of passing userVars and macros maps are to facilitate strong scoping (among blocks and nested scripts).

  Some implementation comments and variable names use keywords based on the following definitions.

  - COMMAND = Statement || SpecialCommand || BufferCommand
  - Statement = SQL statement like "SQL Statement;"
  - SpecialCommand = Special Command like "\x arg..."
  - BufferCommand = Editing/buffer command like ":s/this/that/"

  When entering SQL statements, you are always "appending" to the "immediate" command (not the "buffer", which is a different thing). All you can do to the immediate command is append new lines to it, execute it, or save it to buffer. When you are entering a buffer edit command like ":s/this/that/", your immediate command is the buffer-edit-command. The buffer is the command string that you are editing. The buffer usually contains either an exact copy of the last command executed or sent to buffer by entering a blank line, but BUFFER commands can change the contents of the buffer.

  In general, the special commands mirror those of Postgresql's psql, but SqlFile handles command editing very differently than Postgresql does, in part because of Java's lack of support for raw tty I/O. The \p special command, in particular, is very different from psql's.

  Buffer commands are unique to SQLFile. The ":" commands allow you to edit the buffer and to execute the buffer.

  \d commands are very poorly supported for Mysql because (a) Mysql lacks most of the most basic JDBC support elements, and the most basic role and schema features, and (b) to access the Mysql data dictionary, one must change the database instance (to do that would require work to restore the original state and could have disastrous effects upon transactions).

  The process*() methods, other than processBuffHist() ALWAYS execute on "buffer", and expect it to contain the method specific prefix (if any).

  The input/output Reader/Stream are generally managed by the caller. An exception is that the input reader may be closed automatically or on demand by the user, since in some cases this class builds the Reader. There is no corresponding functionality for output since the user always has control over that object (which may be null or System.out).

  Author:
    Blaine Simpson (blaine dot simpson at admc dot com)
  See Also:
    The SqlTool chapter of the HyperSQL Utilities Guide

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `SqlFile.BadSpecial` | Utility nested Exception class for internal use only.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `LS` | Platform-specific line separator

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SqlFile​(java.io.File inputFile)` | Convenience wrapper for the SqlFile(File, String) constructor
    `SqlFile​(java.io.File inputFile, java.lang.String encoding)` | Convenience wrapper for the SqlFile(File, String, boolean) constructor
    `SqlFile​(java.io.File inputFile, java.lang.String encoding, boolean interactive)` | Constructor for non-interactive usage with a SQL file, using the specified encoding and sending normal output to stdout.
    `SqlFile​(java.io.Reader reader, java.lang.String inputStreamLabel, java.io.PrintStream psStd, java.lang.String encoding, boolean interactive, java.io.File atBaseFile)` | Legacy constructor.
    `SqlFile​(java.io.Reader reader, java.lang.String inputStreamLabel, java.io.PrintStream psStd, java.lang.String encoding, boolean interactive, java.net.URL atBase)` | Instantiate a SqlFile instance for SQL input from 'reader'.
    `SqlFile​(java.lang.String encoding, boolean interactive)` | Constructor for interactive usage with stdin/stdout
    `SqlFile​(java.net.URL inputUrl)` |
    `SqlFile​(java.net.URL inputUrl, java.lang.String encoding)` |
    `SqlFile​(java.net.URL inputUrl, java.lang.String encoding, boolean interactive)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addMacros​(java.util.Map<java.lang.String,​org.hsqldb.cmdline.sqltool.Token> newMacros)` |
    `void` | `addUserVars​(java.util.Map<java.lang.String,​java.lang.String> newUserVars)` |
    `static byte[]` | `bitCharsToBytes​(java.lang.String hexChars)` | Just a stub for now.
    `static boolean` | `canDisplayType​(int i)` | This method is used to tell SqlFile whether this Sql Type must ALWAYS be loaded to the binary buffer without displaying.
    `void` | `closeReader()` | Close the reader.
    `static java.lang.String` | `convertEscapes​(java.lang.String inString)` | Translates user-supplied escapes into the traditionaly corresponding binary characters.
    `void` | `dsvSafe​(java.lang.String s)` | Validate that String is safe to write TO DSV file.
    `static java.lang.String` | `escapeHtml​(java.lang.String s)` | Escaping rules taken from 'Reserved Characters in HTML table at http://www.w3schools.com/tags/ref_entities.asp
    `void` | `execute()` | Process all the commands from the file or Reader associated with "this" object.
    `static java.lang.String` | `getBanner​(java.sql.Connection c)` | Returns a String report for the specified JDBC Connection.
    `java.sql.Connection` | `getConnection()` |
    `java.lang.String` | `getCurrentSchema()` |
    `java.util.Map<java.lang.String,​org.hsqldb.cmdline.sqltool.Token>` | `getMacros()` |
    `java.util.Map<java.lang.String,​java.lang.String>` | `getUserVars()` | Get a reference to the user variable map.
    `static byte[]` | `hexCharOctetsToBytes​(java.lang.String hexChars)` | Convert a String to a byte array by interpreting every 2 characters as an octal byte value.
    `void` | `importDsv​(java.net.URL fileUrl, java.lang.String skipPrefix)` | Name is self-explanatory.
    `static byte[]` | `loadBinary​(java.io.File binFile)` | Legacy function.
    `static byte[]` | `loadBinary​(java.net.URL binUrl)` | Binary file load
    `void` | `setAutoClose​(boolean autoClose)` | Specify whether the supplied or generated input Reader should automatically be closed by the execute() method.
    `void` | `setConnection​(java.sql.Connection jdbcConn)` |
    `void` | `setContinueOnError​(boolean continueOnError)` |
    `void` | `setMaxHistoryLength​(int maxHistoryLength)` |
    `static java.lang.String` | `sqlTypeToString​(int i)` | Return a String representation of the specified java.sql.Types type.
    `static byte[]` | `streamToBytes​(java.io.InputStream is)` | As the name says...
    `java.lang.String` | `streamToString​(java.io.InputStream is, java.lang.String cs)` | As the name says...
    `static java.lang.String` | `toPaddedString​(java.lang.String source, int length, char pad, boolean trailing)` |

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### LS

          public static final java.lang.String LS

      Platform-specific line separator

  - ### Constructor Detail

    - #### SqlFile

          public SqlFile​(java.io.File inputFile)
                  throws java.io.IOException

      Convenience wrapper for the SqlFile(File, String) constructor
      Parameters:
        `inputFile` - input file
      Throws:
        `java.io.IOException` - on read errors
      See Also:
        `SqlFile(File, String)`

    - #### SqlFile

          public SqlFile​(java.net.URL inputUrl)
                  throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### SqlFile

          public SqlFile​(java.io.File inputFile,
                         java.lang.String encoding)
                  throws java.io.IOException

      Convenience wrapper for the SqlFile(File, String, boolean) constructor
      Parameters:
        `inputFile` - the input File
        `encoding` - is applied to both the given File and other files read in or written out. Null will use your env+JVM settings.
      Throws:
        `java.io.IOException` - on read errors
      See Also:
        `SqlFile(File, String, boolean)`

    - #### SqlFile

          public SqlFile​(java.net.URL inputUrl,
                         java.lang.String encoding)
                  throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### SqlFile

          public SqlFile​(java.io.File inputFile,
                         java.lang.String encoding,
                         boolean interactive)
                  throws java.io.IOException

      Constructor for non-interactive usage with a SQL file, using the specified encoding and sending normal output to stdout.
      Parameters:
        `inputFile` - the input File
        `encoding` - is applied to the given File and other files read in or written out. Null will use your env+JVM settings.
        `interactive` - If true, prompts are printed, the interactive Special commands are enabled, and continueOnError defaults to true.
      Throws:
        `java.io.IOException` - on read errors
      See Also:
        `SqlFile(Reader, String, PrintStream, String, boolean, File)`

    - #### SqlFile

          public SqlFile​(java.net.URL inputUrl,
                         java.lang.String encoding,
                         boolean interactive)
                  throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### SqlFile

          public SqlFile​(java.lang.String encoding,
                         boolean interactive)
                  throws java.io.IOException

      Constructor for interactive usage with stdin/stdout
      Parameters:
        `encoding` - is applied to other files read in or written out (but not to stdin or stdout). Null will use your env+JVM settings.
        `interactive` - If true, prompts are printed, the interactive Special commands are enabled, and continueOnError defaults to true.
      Throws:
        `java.io.IOException` - on read errors
      See Also:
        `SqlFile(Reader, String, PrintStream, String, boolean, File)`

    - #### SqlFile

          public SqlFile​(java.io.Reader reader,
                         java.lang.String inputStreamLabel,
                         java.io.PrintStream psStd,
                         java.lang.String encoding,
                         boolean interactive,
                         java.io.File atBaseFile)
                  throws java.io.IOException

      Legacy constructor. See following constructor for documentation.
      Throws:
        `java.io.IOException`

    - #### SqlFile

          public SqlFile​(java.io.Reader reader,
                         java.lang.String inputStreamLabel,
                         java.io.PrintStream psStd,
                         java.lang.String encoding,
                         boolean interactive,
                         java.net.URL atBase)
                  throws java.io.IOException

      Instantiate a SqlFile instance for SQL input from 'reader'. After any needed customization, the SQL can be executed by the execute method.

      Most Special Commands and many Buffer commands are only for interactive use.

      This program never writes to an error stream (stderr or alternative). All meta messages and error messages are written using the logging facility.

      Parameters:
        `reader` - Source for the SQL to be executed. Caller is responsible for setting up encoding. (the 'encoding' parameter will NOT be applied to this reader).
        `inputStreamLabel` - the lable
        `psStd` - PrintStream for normal output. If null, normal output will be discarded. Caller is responsible for settingup encoding (the 'encoding' parameter will NOT be applied to this stream).
        `encoding` - the encoding
        `interactive` - If true, prompts are printed, the interactive Special commands are enabled, and continueOnError defaults to true.
        `atBase` - the base dir
      Throws:
        `java.io.IOException` - on read errors
      See Also:
        `execute()`

  - ### Method Detail

    - #### setConnection

          public void setConnection​(java.sql.Connection jdbcConn)

    - #### getConnection

          public java.sql.Connection getConnection()

    - #### setContinueOnError

          public void setContinueOnError​(boolean continueOnError)

    - #### setMaxHistoryLength

          public void setMaxHistoryLength​(int maxHistoryLength)

    - #### addMacros

          public void addMacros​(java.util.Map<java.lang.String,​org.hsqldb.cmdline.sqltool.Token> newMacros)

    - #### addUserVars

          public void addUserVars​(java.util.Map<java.lang.String,​java.lang.String> newUserVars)

    - #### getUserVars

          public java.util.Map<java.lang.String,​java.lang.String> getUserVars()

      Get a reference to the user variable map. Since you are getting a reference to the private map used inside this class, update this map with great caution and attention to lifecycle handling of the variable map.
      Returns:
        user variable map

    - #### getMacros

          public java.util.Map<java.lang.String,​org.hsqldb.cmdline.sqltool.Token> getMacros()

    - #### setAutoClose

          public void setAutoClose​(boolean autoClose)

      Specify whether the supplied or generated input Reader should automatically be closed by the execute() method.

      execute() will close the Reader by default (i.e. 'autoClose' defaults to true). You may want to set this to false if you want to stop execution with \q or similar, then continue using the Reader or underlying Stream.

      The caller is always responsible for closing the output object (if any) used by SqlFile.

      Parameters:
        `autoClose` - boolean

    - #### execute

          public void execute()
                       throws SqlToolError,
                              java.sql.SQLException

      Process all the commands from the file or Reader associated with "this" object. SQL commands in the content get executed against the current JDBC data source connection.
      Throws:
        `java.sql.SQLException` - thrown by JDBC driver. Only possible if in "\c false" mode.
        `SqlToolError` - all other errors. This includes QuitNow, BreakException, ContinueException for recursive calls only.

    - #### closeReader

          public void closeReader()

      Close the reader. The execute method will run this automatically, by default.

    - #### getCurrentSchema

          public java.lang.String getCurrentSchema()
                                            throws SqlFile.BadSpecial,
                                                   SqlToolError

      Throws:
        `SqlFile.BadSpecial`
        `SqlToolError`

    - #### streamToString

          public java.lang.String streamToString​(java.io.InputStream is,
                                                 java.lang.String cs)
                                          throws java.io.IOException

      As the name says... This method always closes the input stream.
      Parameters:
        `is` - InputStream
        `cs` - String
      Returns:
        String
      Throws:
        `java.io.IOException` - on read errors

    - #### streamToBytes

          public static byte[] streamToBytes​(java.io.InputStream is)
                                      throws java.io.IOException

      As the name says...
      Parameters:
        `is` - input
      Returns:
        byte[]
      Throws:
        `java.io.IOException` - on read errors

    - #### loadBinary

          public static byte[] loadBinary​(java.io.File binFile)
                                   throws java.io.IOException

      Legacy function. See following function for documentation.
      Throws:
        `java.io.IOException`

    - #### loadBinary

          public static byte[] loadBinary​(java.net.URL binUrl)
                                   throws java.io.IOException

      Binary file load
      Parameters:
        `binUrl` - url
      Returns:
        The bytes which are the content of the file
      Throws:
        `java.io.IOException` - on read errors

    - #### canDisplayType

          public static boolean canDisplayType​(int i)

      This method is used to tell SqlFile whether this Sql Type must ALWAYS be loaded to the binary buffer without displaying.

      N.b.: If this returns "true" for a type, then the user can never "see" values for these columns. Therefore, if a type may-or-may-not-be displayable, better to return false here and let the user choose. In general, if there is a toString() operator for this Sql Type then return false, since the JDBC driver should know how to make the value displayable.

      Parameters:
        `i` - JDBC type number
      Returns:
        boolean
      See Also:
        http://java.sun.com/docs/books/tutorial/jdbc/basics/retrieving.html The table on this page lists the most common SqlTypes, all of which must implement toString(), `Types`

    - #### sqlTypeToString

          public static java.lang.String sqlTypeToString​(int i)

      Return a String representation of the specified java.sql.Types type.
      Parameters:
        `i` - int
      Returns:
        String

    - #### dsvSafe

          public void dsvSafe​(java.lang.String s)
                       throws SqlToolError

      Validate that String is safe to write TO DSV file.
      Parameters:
        `s` - String
      Throws:
        `SqlToolError` - if validation fails.

    - #### convertEscapes

          public static java.lang.String convertEscapes​(java.lang.String inString)

      Translates user-supplied escapes into the traditionaly corresponding binary characters. Allowed sequences:
      - \0\d+ (an octal digit)
      - \[0-9]\d* (a decimal digit)
      - \[Xx][0-9]{2} (a hex digit)
      - \n Newline (Ctrl-J)
      - \r Carriage return (Ctrl-M)
      - \t Horizontal tab (Ctrl-I)
      - \f Form feed (Ctrl-L)
      Java 1.4 String methods will make this into a 1 or 2 line task.
      Parameters:
        `inString` - input string
      Returns:
        converted string

    - #### importDsv

          public void importDsv​(java.net.URL fileUrl,
                                java.lang.String skipPrefix)
                         throws SqlToolError

      Name is self-explanatory.
      Parameters:
        `fileUrl` - String
        `skipPrefix` - String
      Throws:
        `SqlToolError` - Would prefer to throw an internal exception, but we want this method to have external visibility.

    - #### hexCharOctetsToBytes

          public static byte[] hexCharOctetsToBytes​(java.lang.String hexChars)

      Convert a String to a byte array by interpreting every 2 characters as an octal byte value.
      Parameters:
        `hexChars` - String
      Returns:
        byte[]

    - #### bitCharsToBytes

          public static byte[] bitCharsToBytes​(java.lang.String hexChars)

      Just a stub for now.
      Parameters:
        `hexChars` - String
      Returns:
        byte[]

    - #### getBanner

          public static java.lang.String getBanner​(java.sql.Connection c)

      Returns a String report for the specified JDBC Connection. For databases with poor JDBC support, you won't get much detail.
      Parameters:
        `c` - Connection
      Returns:
        String

    - #### escapeHtml

          public static java.lang.String escapeHtml​(java.lang.String s)

      Escaping rules taken from 'Reserved Characters in HTML table at http://www.w3schools.com/tags/ref_entities.asp
      Parameters:
        `s` - String
      Returns:
        String

    - #### toPaddedString

          public static java.lang.String toPaddedString​(java.lang.String source,
                                                        int length,
                                                        char pad,
                                                        boolean trailing)