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)
```

Class SqlFile

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LS

Constructor Detail

SqlFile

SqlFile

SqlFile

SqlFile

SqlFile

SqlFile

SqlFile

SqlFile

SqlFile

Method Detail

setConnection

getConnection

setContinueOnError

setMaxHistoryLength

addMacros

addUserVars

getUserVars

getMacros

setAutoClose

execute

closeReader

getCurrentSchema

streamToString

streamToBytes

loadBinary

loadBinary

canDisplayType

sqlTypeToString

dsvSafe

convertEscapes

importDsv

hexCharOctetsToBytes

bitCharsToBytes

getBanner

escapeHtml

toPaddedString