Polish Javadoc for embedded database support

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/ConnectionProperties.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2009 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,35 +19,38 @@ package org.springframework.jdbc.datasource.embedded;
 import java.sql.Driver;
 
 /**
- * DataSourceFactory helper that allows essential JDBC connection properties to be configured consistently,
- * independent of the actual DataSource implementation.
+ * {@code ConnectionProperties} serves as a simple data container that allows
+ * essential JDBC connection properties to be configured consistently,
+ * independent of the actual {@link javax.sql.DataSource DataSource}
+ * implementation.
  *
  * @author Keith Donald
+ * @author Sam Brannen
  * @since 3.0
  * @see DataSourceFactory
  */
 public interface ConnectionProperties {
 
 	/**
-	 * Set the JDBC driver to use to connect to the database.
+	 * Set the JDBC driver class to use to connect to the database.
 	 * @param driverClass the jdbc driver class
 	 */
 	void setDriverClass(Class<? extends Driver> driverClass);
 
 	/**
-	 * Sets the JDBC connection URL of the database.
+	 * Set the JDBC connection URL for the database.
 	 * @param url the connection url
 	 */
 	void setUrl(String url);
 
 	/**
-	 * Sets the username to use to connect to the database.
+	 * Set the username to use to connect to the database.
 	 * @param username the username
 	 */
 	void setUsername(String username);
 
 	/**
-	 * Sets the password to use to connect to the database.
+	 * Set the password to use to connect to the database.
 	 * @param password the password
 	 */
 	void setPassword(String password);

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/DataSourceFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2009 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,27 +18,31 @@ package org.springframework.jdbc.datasource.embedded;
 
 import javax.sql.DataSource;
 
-import org.springframework.jdbc.datasource.SimpleDriverDataSource;
-
 /**
- * Encapsulates the creation of a particular DataSource implementation, such as a
- * {@link SimpleDriverDataSource} or connection pool such as Apache DBCP or C3P0.
+ * {@code DataSourceFactory} encapsulates the creation of a particular
+ * {@link DataSource} implementation such as a
+ * {@link org.springframework.jdbc.datasource.SimpleDriverDataSource
+ * SimpleDriverDataSource} or a connection pool such as Apache DBCP or C3P0.
  *
- * <p>Call {@link #getConnectionProperties()} to configure normalized DataSource properties
- * before calling {@link #getDataSource()} to actually get the configured DataSource instance.
+ * <p>Call {@link #getConnectionProperties()} to configure normalized
+ * {@code DataSource} properties before calling {@link #getDataSource()} to
+ * actually get the configured {@code DataSource} instance.
  *
  * @author Keith Donald
+ * @author Sam Brannen
  * @since 3.0
  */
 public interface DataSourceFactory {
 
 	/**
-	 * Allows properties of the DataSource to be configured.
+	 * Get the {@linkplain ConnectionProperties connection properties} of the
+	 * {@link #getDataSource DataSource} to be configured.
 	 */
 	ConnectionProperties getConnectionProperties();
 
 	/**
-	 * Returns the DataSource with the connection properties applied.
+	 * Get the {@link DataSource} with the {@linkplain #getConnectionProperties
+	 * connection properties} applied.
 	 */
 	DataSource getDataSource();
 

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseConfigurer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,23 +19,28 @@ package org.springframework.jdbc.datasource.embedded;
 import javax.sql.DataSource;
 
 /**
- * Encapsulates the configuration required to create, connect to, and shutdown a specific type of embedded database such as HSQL or H2.
- * Create a implementation for each database type you wish to support; for example HSQL, H2, or some other type.
+ * {@code EmbeddedDatabaseConfigurer} encapsulates the configuration required to
+ * create, connect to, and shutdown a specific type of embedded database such as
+ * HSQL or H2.
+ * <p>Create an implementation for each database type you wish to support; for
+ * example HSQL, H2, or some other type.
  *
  * @author Keith Donald
+ * @author Sam Brannen
  * @since 3.0
  */
 public interface EmbeddedDatabaseConfigurer {
 
 	/**
-	 * Configure the properties required to create and connect to the embedded database instance.
+	 * Configure the properties required to create and connect to the embedded
+	 * database instance.
 	 * @param properties connection properties to configure
-	 * @param databaseName the name of the test database
+	 * @param databaseName the name of the embedded database
 	 */
 	void configureConnectionProperties(ConnectionProperties properties, String databaseName);
 
 	/**
-	 * Shutdown the embedded database instance that backs dataSource.
+	 * Shutdown the embedded database instance that backs the supplied {@link DataSource}.
 	 * @param dataSource the data source
 	 * @param databaseName the name of the database being shutdown
 	 */

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseFactory.java

@@ -118,14 +118,14 @@ public class EmbeddedDatabaseFactory {
 	 * Set the strategy that will be used to initialize or populate the embedded
 	 * database.
 	 * <p>Defaults to {@code null}.
-	 * @see org.springframework.jdbc.datasource.init.DataSourceInitializer#setDatabasePopulator
 	 */
 	public void setDatabasePopulator(DatabasePopulator populator) {
 		this.databasePopulator = populator;
 	}
 
 	/**
-	 * Factory method that returns the embedded database instance.
+	 * Factory method that returns the {@link EmbeddedDatabase embedded database}
+	 * instance, which is also a {@link DataSource}.
 	 */
 	public EmbeddedDatabase getDatabase() {
 		if (this.dataSource == null) {

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/init/ResourceDatabasePopulator.java

@@ -25,10 +25,13 @@ import org.springframework.core.io.Resource;
 import org.springframework.core.io.support.EncodedResource;
 
 /**
- * Populates a database from SQL scripts defined in external resources.
+ * Populates or initializes a database from SQL scripts defined in external
+ * resources.
  *
- * <p>Call {@link #addScript(Resource)} to add a SQL script location.
- * Call {@link #setSqlScriptEncoding(String)} to set the encoding for all added scripts.
+ * <p>Call {@link #addScript(Resource)} to add a single SQL script location.
+ * Call {@link #addScripts(Resource...)} to add multiple SQL script locations.
+ * Call {@link #setSqlScriptEncoding(String)} to set the encoding for all added
+ * scripts.
  *
  * @author Keith Donald
  * @author Dave Syer
@@ -70,7 +73,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	/**
 	 * Construct a new {@code ResourceDatabasePopulator} with default settings
 	 * for the supplied scripts.
-	 * @param scripts the scripts to execute to populate the database
+	 * @param scripts the scripts to execute to initialize or populate the database
 	 * @since 4.0.3
 	 */
 	public ResourceDatabasePopulator(Resource... scripts) {
@@ -86,7 +89,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	 * statement can be ignored
 	 * @param sqlScriptEncoding the encoding for the supplied SQL scripts, if
 	 * different from the platform encoding; may be {@code null}
-	 * @param scripts the scripts to execute to populate the database
+	 * @param scripts the scripts to execute to initialize or populate the database
 	 * @since 4.0.3
 	 */
 	public ResourceDatabasePopulator(boolean continueOnError, boolean ignoreFailedDrops, String sqlScriptEncoding,
@@ -98,7 +101,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	}
 
 	/**
-	 * Add a script to execute to populate the database.
+	 * Add a script to execute to initialize or populate the database.
 	 * @param script the path to an SQL script
 	 */
 	public void addScript(Resource script) {
@@ -106,7 +109,16 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	}
 
 	/**
-	 * Set the scripts to execute to populate the database.
+	 * Add multiple scripts to execute to initialize or populate the database.
+	 * @param scripts the scripts to execute
+	 */
+	public void addScripts(Resource... scripts) {
+		this.scripts.addAll(Arrays.asList(scripts));
+	}
+
+	/**
+	 * Set the scripts to execute to initialize or populate the database,
+	 * replacing any previously added scripts.
 	 * @param scripts the scripts to execute
 	 */
 	public void setScripts(Resource... scripts) {
@@ -115,6 +127,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 
 	/**
 	 * Specify the encoding for SQL scripts, if different from the platform encoding.
+	 * @param sqlScriptEncoding the encoding used in scripts
 	 * @see #addScript(Resource)
 	 */
 	public void setSqlScriptEncoding(String sqlScriptEncoding) {
@@ -124,6 +137,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	/**
 	 * Specify the statement separator, if a custom one.
 	 * <p>Default is ";".
+	 * @param separator the statement separator
 	 */
 	public void setSeparator(String separator) {
 		this.separator = separator;
@@ -132,6 +146,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	/**
 	 * Set the prefix that identifies line comments within the SQL scripts.
 	 * <p>Default is "--".
+	 * @param commentPrefix the prefix for single-line comments
 	 */
 	public void setCommentPrefix(String commentPrefix) {
 		this.commentPrefix = commentPrefix;
@@ -141,6 +156,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	 * Set the start delimiter that identifies block comments within the SQL
 	 * scripts.
 	 * <p>Default is "/*".
+	 * @param blockCommentStartDelimiter the start delimiter for block comments
 	 * @since 4.0.3
 	 * @see #setBlockCommentEndDelimiter
 	 */
@@ -152,6 +168,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	 * Set the end delimiter that identifies block comments within the SQL
 	 * scripts.
 	 * <p>Default is "*&#47;".
+	 * @param blockCommentEndDelimiter the end delimiter for block comments
 	 * @since 4.0.3
 	 * @see #setBlockCommentStartDelimiter
 	 */
@@ -162,6 +179,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	/**
 	 * Flag to indicate that all failures in SQL should be logged but not cause a failure.
 	 * <p>Defaults to {@code false}.
+	 * @param continueOnError {@code true} if script execution should continue on error
 	 */
 	public void setContinueOnError(boolean continueOnError) {
 		this.continueOnError = continueOnError;
@@ -173,6 +191,7 @@ public class ResourceDatabasePopulator implements DatabasePopulator {
 	 * {@code IF EXISTS} clause in a {@code DROP} statement.
 	 * <p>The default is {@code false} so that if the populator runs accidentally, it will
 	 * fail fast if the script starts with a {@code DROP} statement.
+	 * @param ignoreFailedDrops {@code true} if failed drop statements should be ignored
 	 */
 	public void setIgnoreFailedDrops(boolean ignoreFailedDrops) {
 		this.ignoreFailedDrops = ignoreFailedDrops;