org.springframework.jdbc.datasource.init

## Class ResourceDatabasePopulator

- java.lang.Object
- - org.springframework.jdbc.datasource.init.ResourceDatabasePopulator

- All Implemented Interfaces:
    DatabasePopulator

      public class ResourceDatabasePopulator
      extends Object
      implements DatabasePopulator

  Populates or initializes a database from SQL scripts defined in external resources.

  Call `addScript(Resource)` to add a single SQL script location. Call `addScripts(Resource...)` to add multiple SQL script locations. Call `setSqlScriptEncoding(String)` to set the encoding for all added scripts.

  Since:
    3.0
  Author:
    Keith Donald, Dave Syer, Juergen Hoeller, Chris Beams, Oliver Gierke, Sam Brannen, Chris Baldwin
  See Also:
    `DatabasePopulatorUtils`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResourceDatabasePopulator()` Construct a new `ResourceDatabasePopulator` with default settings.
    `ResourceDatabasePopulator(boolean continueOnError, boolean ignoreFailedDrops, String sqlScriptEncoding, Resource... scripts)` Construct a new `ResourceDatabasePopulator` with the supplied values.
    `ResourceDatabasePopulator(Resource... scripts)` Construct a new `ResourceDatabasePopulator` with default settings for the supplied scripts.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addScript(Resource script)` Add a script to execute to initialize or populate the database.
    `void` | `addScripts(Resource... scripts)` Add multiple scripts to execute to initialize or populate the database.
    `void` | `populate(Connection connection)` Populate, initialize, or clean up the database using the provided JDBC connection.
    `void` | `setBlockCommentEndDelimiter(String blockCommentEndDelimiter)` Set the end delimiter that identifies block comments within the SQL scripts.
    `void` | `setBlockCommentStartDelimiter(String blockCommentStartDelimiter)` Set the start delimiter that identifies block comments within the SQL scripts.
    `void` | `setCommentPrefix(String commentPrefix)` Set the prefix that identifies line comments within the SQL scripts.
    `void` | `setContinueOnError(boolean continueOnError)` Flag to indicate that all failures in SQL should be logged but not cause a failure.
    `void` | `setIgnoreFailedDrops(boolean ignoreFailedDrops)` Flag to indicate that a failed SQL `DROP` statement can be ignored.
    `void` | `setScripts(Resource... scripts)` Set the scripts to execute to initialize or populate the database, replacing any previously added scripts.
    `void` | `setSeparator(String separator)` Specify the statement separator, if a custom one.
    `void` | `setSqlScriptEncoding(String sqlScriptEncoding)` Specify the encoding for SQL scripts, if different from the platform encoding.

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

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

- - ### Constructor Detail

    - #### ResourceDatabasePopulator

          public ResourceDatabasePopulator()

      Construct a new `ResourceDatabasePopulator` with default settings.
      Since:
        4.0.3

    - #### ResourceDatabasePopulator

          public ResourceDatabasePopulator(Resource... scripts)

      Construct a new `ResourceDatabasePopulator` with default settings for the supplied scripts.
      Parameters:
        `scripts` - the scripts to execute to initialize or populate the database
      Since:
        4.0.3

    - #### ResourceDatabasePopulator

          public ResourceDatabasePopulator(boolean continueOnError,
                                           boolean ignoreFailedDrops,
                                           String sqlScriptEncoding,
                                           Resource... scripts)

      Construct a new `ResourceDatabasePopulator` with the supplied values.
      Parameters:
        `continueOnError` - flag to indicate that all failures in SQL should be logged but not cause a failure
        `ignoreFailedDrops` - flag to indicate that a failed SQL `DROP` statement can be ignored
        `sqlScriptEncoding` - the encoding for the supplied SQL scripts, if different from the platform encoding; may be `null`
        `scripts` - the scripts to execute to initialize or populate the database
      Since:
        4.0.3

  - ### Method Detail

    - #### addScript

          public void addScript(Resource script)

      Add a script to execute to initialize or populate the database.
      Parameters:
        `script` - the path to an SQL script

    - #### addScripts

          public void addScripts(Resource... scripts)

      Add multiple scripts to execute to initialize or populate the database.
      Parameters:
        `scripts` - the scripts to execute

    - #### setScripts

          public void setScripts(Resource... scripts)

      Set the scripts to execute to initialize or populate the database, replacing any previously added scripts.
      Parameters:
        `scripts` - the scripts to execute

    - #### setSqlScriptEncoding

          public void setSqlScriptEncoding(String sqlScriptEncoding)

      Specify the encoding for SQL scripts, if different from the platform encoding.
      Parameters:
        `sqlScriptEncoding` - the encoding used in scripts
      See Also:
        `addScript(Resource)`

    - #### setSeparator

          public void setSeparator(String separator)

      Specify the statement separator, if a custom one.

      Default is ";".

      Parameters:
        `separator` - the statement separator

    - #### setCommentPrefix

          public void setCommentPrefix(String commentPrefix)

      Set the prefix that identifies line comments within the SQL scripts.

      Default is "--".

      Parameters:
        `commentPrefix` - the prefix for single-line comments

    - #### setBlockCommentStartDelimiter

          public void setBlockCommentStartDelimiter(String blockCommentStartDelimiter)

      Set the start delimiter that identifies block comments within the SQL scripts.

      Default is "/*".

      Parameters:
        `blockCommentStartDelimiter` - the start delimiter for block comments
      Since:
        4.0.3
      See Also:
        `setBlockCommentEndDelimiter(java.lang.String)`

    - #### setBlockCommentEndDelimiter

          public void setBlockCommentEndDelimiter(String blockCommentEndDelimiter)

      Set the end delimiter that identifies block comments within the SQL scripts.

      Default is "*/".

      Parameters:
        `blockCommentEndDelimiter` - the end delimiter for block comments
      Since:
        4.0.3
      See Also:
        `setBlockCommentStartDelimiter(java.lang.String)`

    - #### setContinueOnError

          public void setContinueOnError(boolean continueOnError)

      Flag to indicate that all failures in SQL should be logged but not cause a failure.

      Defaults to `false`.

      Parameters:
        `continueOnError` - `true` if script execution should continue on error

    - #### setIgnoreFailedDrops

          public void setIgnoreFailedDrops(boolean ignoreFailedDrops)

      Flag to indicate that a failed SQL `DROP` statement can be ignored.

      This is useful for non-embedded databases whose SQL dialect does not support an `IF EXISTS` clause in a `DROP` statement.

      The default is `false` so that if the populator runs accidentally, it will fail fast if the script starts with a `DROP` statement.

      Parameters:
        `ignoreFailedDrops` - `true` if failed drop statements should be ignored

    - #### populate

          public void populate(Connection connection)
                        throws ScriptException

      Populate, initialize, or clean up the database using the provided JDBC connection.

      Concrete implementations may throw an `SQLException` if an error is encountered but are strongly encouraged to throw a specific `ScriptException` instead. For example, Spring's `ResourceDatabasePopulator` and `DatabasePopulatorUtils` wrap all `SQLExceptions` in `ScriptExceptions`.

      Specified by:
        `populate` in interface `DatabasePopulator`
      Parameters:
        `connection` - the JDBC connection to use to populate the db; already configured and ready to use
      Throws:
        `ScriptException` - in all other error cases
      See Also:
        `DatabasePopulatorUtils.execute(org.springframework.jdbc.datasource.init.DatabasePopulator, javax.sql.DataSource)`