Overhaul Javadoc for embedded database support

Author: sbrannen

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -25,7 +25,7 @@
 
 /**
  * {@link EmbeddedDatabaseConfigurer} for the Apache Derby database 10.6+.
- * Call {@link #getInstance()} to get the singleton instance of this class.
+ * <p>Call {@link #getInstance()} to get the singleton instance of this class.
  *
  * @author Oliver Gierke
  * @author Juergen Hoeller

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabase.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,11 +19,14 @@
 import javax.sql.DataSource;
 
 /**
- * A handle to an EmbeddedDatabase instance.
- * Is a {@link DataSource}.
- * Adds a shutdown operation so the embedded database instance can be shutdown.
+ * {@code EmbeddedDatabase} serves as a handle to an embedded database instance.
+ *
+ * <p>An {@code EmbeddedDatabase} is also a {@link DataSource} and adds a
+ * {@link #shutdown} operation so that the embedded database instance can be
+ * shutdown.
  *
  * @author Keith Donald
+ * @author Sam Brannen
  * @since 3.0
  */
 public interface EmbeddedDatabase extends DataSource {

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

@@ -23,7 +23,7 @@
 /**
  * A builder that provides a convenient API for constructing an embedded database.
  *
- * <p>Usage example:
+ * <h3>Usage Example</h3>
  * <pre class="code">
  * EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
  * EmbeddedDatabase db = builder.setType(H2).addScript("schema.sql").addScript("data.sql").build();
@@ -66,9 +66,10 @@ public EmbeddedDatabaseBuilder(ResourceLoader resourceLoader) {
 
 	/**
 	 * Set the name of the embedded database.
-	 * <p>Defaults to "testdb" if not called.
+	 * <p>Defaults to {@link EmbeddedDatabaseFactory#DEFAULT_DATABASE_NAME} if
+	 * not called.
 	 * @param databaseName the database name
-	 * @return this, to facilitate method chaining
+	 * @return {@code this}, to facilitate method chaining
 	 */
 	public EmbeddedDatabaseBuilder setName(String databaseName) {
 		this.databaseFactory.setDatabaseName(databaseName);
@@ -79,17 +80,17 @@ public EmbeddedDatabaseBuilder setName(String databaseName) {
 	 * Set the type of embedded database.
 	 * <p>Defaults to HSQL if not called.
 	 * @param databaseType the database type
-	 * @return this, to facilitate method chaining
+	 * @return {@code this}, to facilitate method chaining
 	 */
 	public EmbeddedDatabaseBuilder setType(EmbeddedDatabaseType databaseType) {
 		this.databaseFactory.setDatabaseType(databaseType);
 		return this;
 	}
 
 	/**
-	 * Add a SQL script to execute to populate the database.
+	 * Add an SQL script to execute to initialize or populate the database.
 	 * @param sqlResource the sql resource location
-	 * @return this, to facilitate method chaining
+	 * @return {@code this}, to facilitate method chaining
 	 */
 	public EmbeddedDatabaseBuilder addScript(String sqlResource) {
 		this.databasePopulator.addScript(this.resourceLoader.getResource(sqlResource));
@@ -98,9 +99,9 @@ public EmbeddedDatabaseBuilder addScript(String sqlResource) {
 
 	/**
 	 * Add default scripts to execute to populate the database.
-	 * <p>The default scripts are {@code schema.sql} to create the db
-	 * schema and {@code data.sql} to populate the db with data.
-	 * @return this, to facilitate method chaining
+	 * <p>The default scripts are {@code "schema.sql"} to create the database
+	 * schema and {@code "data.sql"} to populate the database with data.
+	 * @return {@code this}, to facilitate method chaining
 	 */
 	public EmbeddedDatabaseBuilder addDefaultScripts() {
 		addScript("schema.sql");

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseConfigurerFactory.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,11 +19,12 @@
 import org.springframework.util.Assert;
 
 /**
- * Maps well-known {@link EmbeddedDatabaseType embedded database types} to
+ * Maps well-known {@linkplain EmbeddedDatabaseType embedded database types} to
  * {@link EmbeddedDatabaseConfigurer} strategies.
  *
  * @author Keith Donald
  * @author Oliver Gierke
+ * @author Sam Brannen
  * @since 3.0
  */
 final class EmbeddedDatabaseConfigurerFactory {
@@ -39,7 +40,7 @@ public static EmbeddedDatabaseConfigurer getConfigurer(EmbeddedDatabaseType type
 				case DERBY:
 					return DerbyEmbeddedDatabaseConfigurer.getInstance();
 				default:
-					throw new UnsupportedOperationException("Other embedded database types not yet supported");
+					throw new UnsupportedOperationException("Embedded database type [" + type + "] is not supported");
 			}
 		}
 		catch (ClassNotFoundException ex) {
@@ -49,6 +50,7 @@ public static EmbeddedDatabaseConfigurer getConfigurer(EmbeddedDatabaseType type
 	}
 
 	private EmbeddedDatabaseConfigurerFactory() {
+		/* no-op */
 	}
 
 }

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

@@ -20,6 +20,7 @@
 import java.sql.Connection;
 import java.sql.SQLException;
 import java.util.logging.Logger;
+
 import javax.sql.DataSource;
 
 import org.apache.commons.logging.Log;
@@ -30,8 +31,10 @@
 import org.springframework.util.Assert;
 
 /**
- * Creates an {@link EmbeddedDatabase} instance. Callers are guaranteed that
- * the returned database has been fully initialized and populated.
+ * Factory for creating {@link EmbeddedDatabase} instances.
+ *
+ * <p>Callers are guaranteed that a returned database has been fully initialized
+ * and populated.
  *
  * <p>Can be configured:
  * <ul>
@@ -43,19 +46,26 @@
  * <li>Call {@link #setDatabasePopulator(DatabasePopulator)} to change the
  * algorithm used to populate the database.
  * <li>Call {@link #setDataSourceFactory(DataSourceFactory)} to change the type
- * of DataSource used to connect to the database.
- * <li>Call {@link #getDatabase()} to get the {@link EmbeddedDatabase} instance.
+ * of {@link DataSource} used to connect to the database.
  * </ul>
  *
+ * <p>Call {@link #getDatabase()} to get the {@link EmbeddedDatabase} instance.
+ *
  * @author Keith Donald
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 3.0
  */
 public class EmbeddedDatabaseFactory {
 
+	/**
+	 * Default name for an embedded database: &quot;testdb&quot;.
+	 */
+	public static final String DEFAULT_DATABASE_NAME = "testdb";
+
 	private static Log logger = LogFactory.getLog(EmbeddedDatabaseFactory.class);
 
-	private String databaseName = "testdb";
+	private String databaseName = DEFAULT_DATABASE_NAME;
 
 	private DataSourceFactory dataSourceFactory = new SimpleDriverDataSourceFactory();
 
@@ -67,16 +77,18 @@ public class EmbeddedDatabaseFactory {
 
 
 	/**
-	 * Set the name of the database. Defaults to "testdb".
-	 * @param databaseName name of the test database
+	 * Set the name of the database.
+	 * <p>Defaults to {@value #DEFAULT_DATABASE_NAME}.
+	 * @param databaseName name of the embedded database
 	 */
 	public void setDatabaseName(String databaseName) {
-		Assert.notNull(databaseName, "Database name is required");
+		Assert.hasText(databaseName, "Database name is required");
 		this.databaseName = databaseName;
 	}
 
 	/**
-	 * Set the factory to use to create the DataSource instance that connects to the embedded database.
+	 * Set the factory to use to create the {@link DataSource} instance that
+	 * connects to the embedded database.
 	 * <p>Defaults to {@link SimpleDriverDataSourceFactory}.
 	 */
 	public void setDataSourceFactory(DataSourceFactory dataSourceFactory) {
@@ -85,9 +97,10 @@ public void setDataSourceFactory(DataSourceFactory dataSourceFactory) {
 	}
 
 	/**
-	 * Set the type of embedded database to use. Call this when you wish to configure
-	 * one of the pre-supported types. Defaults to HSQL.
-	 * @param type the test database type
+	 * Set the type of embedded database to use.
+	 * <p>Call this when you wish to configure one of the pre-supported types.
+	 * <p>Defaults to HSQL.
+	 * @param type the database type
 	 */
 	public void setDatabaseType(EmbeddedDatabaseType type) {
 		this.databaseConfigurer = EmbeddedDatabaseConfigurerFactory.getConfigurer(type);
@@ -102,7 +115,9 @@ public void setDatabaseConfigurer(EmbeddedDatabaseConfigurer configurer) {
 	}
 
 	/**
-	 * Set the strategy that will be used to populate the embedded database. Defaults to null.
+	 * 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) {
@@ -121,8 +136,10 @@ public EmbeddedDatabase getDatabase() {
 
 
 	/**
-	 * Hook to initialize the embedded database. Subclasses may call to force initialization. After calling this method,
-	 * {@link #getDataSource()} returns the DataSource providing connectivity to the db.
+	 * Hook to initialize the embedded database. Subclasses may call this method
+	 * to force initialization.
+	 * <p>After calling this method, {@link #getDataSource()} returns the
+	 * {@link DataSource} providing connectivity to the database.
 	 */
 	protected void initDatabase() {
 		// Create the embedded database source first
@@ -150,9 +167,10 @@ protected void initDatabase() {
 	}
 
 	/**
-	 * Hook to shutdown the embedded database. Subclasses may call to force shutdown.
+	 * Hook to shutdown the embedded database. Subclasses may call this method
+	 * to force shutdown.
 	 * <p>After calling, {@link #getDataSource()} returns {@code null}.
-	 * Does nothing if no embedded database has been initialized.
+	 * <p>Does nothing if no embedded database has been initialized.
 	 */
 	protected void shutdownDatabase() {
 		if (this.dataSource != null) {
@@ -162,9 +180,11 @@ protected void shutdownDatabase() {
 	}
 
 	/**
-	 * Hook that gets the DataSource that provides the connectivity to the embedded database.
-	 * <p>Returns {@code null} if the DataSource has not been initialized or the database
-	 * has been shut down. Subclasses may call to access the DataSource instance directly.
+	 * Hook that gets the {@link DataSource} that provides the connectivity to the
+	 * embedded database.
+	 * <p>Returns {@code null} if the {@code DataSource} has not been initialized
+	 * or if the database has been shut down. Subclasses may call this method to
+	 * access the {@code DataSource} instance directly.
 	 */
 	protected final DataSource getDataSource() {
 		return this.dataSource;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -21,8 +21,8 @@
 import org.springframework.util.ClassUtils;
 
 /**
- * Initializes an H2 embedded database instance.
- * Call {@link #getInstance()} to get the singleton instance of this class.
+ * {@link EmbeddedDatabaseConfigurer} for an H2 embedded database instance.
+ * <p>Call {@link #getInstance()} to get the singleton instance of this class.
  *
  * @author Oliver Gierke
  * @author Juergen Hoeller

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -21,8 +21,8 @@
 import org.springframework.util.ClassUtils;
 
 /**
- * Initializes an HSQL embedded database instance.
- * Call {@link #getInstance()} to get the singleton instance of this class.
+ * {@link EmbeddedDatabaseConfigurer} for an HSQL embedded database instance.
+ * <p>Call {@link #getInstance()} to get the singleton instance of this class.
  *
  * @author Keith Donald
  * @author Oliver Gierke