Package 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, initializes, or cleans up a database using SQL scripts defined in external resources.

- Call `addScript(org.springframework.core.io.Resource)` to add a single SQL script location.
- Call `addScripts(org.springframework.core.io.Resource...)` to add multiple SQL script locations.
- Consult the setter methods in this class for further configuration options.
- Call `populate(java.sql.Connection)` or `execute(javax.sql.DataSource)` to initialize or clean up the database using the configured scripts.

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

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`void`
`addScript(org.springframework.core.io.Resource script)`
Add a script to execute to initialize or clean up the database.
`void`
`addScripts(org.springframework.core.io.Resource... scripts)`
Add multiple scripts to execute to initialize or clean up the database.
`void`
`execute(DataSource dataSource)`
Execute this `ResourceDatabasePopulator` against the given `DataSource`.
`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 single-line comments within the SQL scripts.
`void`
`setCommentPrefixes(String... commentPrefixes)`
Set the prefixes that identify single-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(org.springframework.core.io.Resource... scripts)`
Set the scripts to execute to initialize or clean up 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 the configured 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 Details

### ResourceDatabasePopulator

public ResourceDatabasePopulator()
Construct a new `ResourceDatabasePopulator` with default settings.

Since:
  4.0.3

### ResourceDatabasePopulator

public ResourceDatabasePopulator(org.springframework.core.io.Resource... scripts)
Construct a new `ResourceDatabasePopulator` with default settings for the supplied scripts.

Parameters:
  `scripts` - the scripts to execute to initialize or clean up the database (never `null`)
Since:
  4.0.3

### ResourceDatabasePopulator

public ResourceDatabasePopulator(boolean continueOnError, boolean ignoreFailedDrops, @Nullable String sqlScriptEncoding, org.springframework.core.io.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 (may be `null` or empty to indicate platform encoding)
  `scripts` - the scripts to execute to initialize or clean up the database (never `null`)
Since:
  4.0.3

## Method Details

### addScript

public void addScript(org.springframework.core.io.Resource script)
Add a script to execute to initialize or clean up the database.

Parameters:
  `script` - the path to an SQL script (never `null`)

### addScripts

public void addScripts(org.springframework.core.io.Resource... scripts)
Add multiple scripts to execute to initialize or clean up the database.

Parameters:
  `scripts` - the scripts to execute (never `null`)

### setScripts

public void setScripts(org.springframework.core.io.Resource... scripts)
Set the scripts to execute to initialize or clean up the database, replacing any previously added scripts.

Parameters:
  `scripts` - the scripts to execute (never `null`)

### setSqlScriptEncoding

public void setSqlScriptEncoding(@Nullable String sqlScriptEncoding)
Specify the encoding for the configured SQL scripts, if different from the platform encoding.

Parameters:
  `sqlScriptEncoding` - the encoding used in scripts (may be `null` or empty to indicate platform encoding)
See Also:
  - `addScript(Resource)`

### setSeparator

public void setSeparator(String separator)
Specify the statement separator, if a custom one.

Defaults to `";"` if not specified and falls back to `"\n"` as a last resort; may be set to `ScriptUtils.EOF_STATEMENT_SEPARATOR` to signal that each script contains a single statement without a separator.

Parameters:
  `separator` - the script statement separator

### setCommentPrefix

public void setCommentPrefix(String commentPrefix)
Set the prefix that identifies single-line comments within the SQL scripts.

Defaults to `"--"`.

Parameters:
  `commentPrefix` - the prefix for single-line comments
See Also:
  - `setCommentPrefixes(String...)`

### setCommentPrefixes

public void setCommentPrefixes(String... commentPrefixes)
Set the prefixes that identify single-line comments within the SQL scripts.

Defaults to `["--"]`.

Parameters:
  `commentPrefixes` - the prefixes for single-line comments
Since:
  5.2

### setBlockCommentStartDelimiter

public void setBlockCommentStartDelimiter(String blockCommentStartDelimiter)
Set the start delimiter that identifies block comments within the SQL scripts.

Defaults to `"/*"`.

Parameters:
  `blockCommentStartDelimiter` - the start delimiter for block comments (never `null` or empty)
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.

Defaults to `"*/"`.

Parameters:
  `blockCommentEndDelimiter` - the end delimiter for block comments (never `null` or empty)
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 a non-embedded database 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 a 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.

Warning: Concrete implementations should not close the provided `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; already configured and ready to use; never `null`
Throws:
  `ScriptException` - in all other error cases
See Also:
  - `execute(DataSource)`

### execute

public void execute(DataSource dataSource) throws ScriptException
Execute this `ResourceDatabasePopulator` against the given `DataSource`.

Delegates to `DatabasePopulatorUtils.execute(org.springframework.jdbc.datasource.init.DatabasePopulator, javax.sql.DataSource)`.

Parameters:
  `dataSource` - the `DataSource` to execute against (never `null`)
Throws:
  `ScriptException` - if an error occurs
Since:
  4.1
See Also:
  - `populate(Connection)`