root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 4 Packages Projects Releases Wiki Activity

Overhaul Javadoc for embedded database support

This commit is contained in:
Sam Brannen 2014-03-18 12:54:40 +01:00
parent c61d62ef4b
commit 42690a9a9e
7 changed files with 70 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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 @@ import org.apache.derby.jdbc.EmbeddedDriver;
/**
* {@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

11
spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabase.java
View File

@ -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 @@ package org.springframework.jdbc.datasource.embedded;
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 {

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

@ -23,7 +23,7 @@ import org.springframework.jdbc.datasource.init.ResourceDatabasePopulator;
/**
* 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 class EmbeddedDatabaseBuilder {
/**
* 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,7 +80,7 @@ public class EmbeddedDatabaseBuilder {
* 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);
@ -87,9 +88,9 @@ public class EmbeddedDatabaseBuilder {
}
/**
* 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 class EmbeddedDatabaseBuilder {
/**
* 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");

8
spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseConfigurerFactory.java
View File

@ -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 @@ package org.springframework.jdbc.datasource.embedded;
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 @@ final class EmbeddedDatabaseConfigurerFactory {
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 @@ final class EmbeddedDatabaseConfigurerFactory {
}
private EmbeddedDatabaseConfigurerFactory() {
/* no-op */
}
}

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

@ -20,6 +20,7 @@ import java.io.PrintWriter;
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.jdbc.datasource.init.DatabasePopulatorUtils;
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 @@ import org.springframework.util.Assert;
* <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 class EmbeddedDatabaseFactory {
}
/**
* 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 class EmbeddedDatabaseFactory {
}
/**
* 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 class EmbeddedDatabaseFactory {
/**
* 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 @@ public class EmbeddedDatabaseFactory {
}
/**
* 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 @@ public class EmbeddedDatabaseFactory {
}
/**
* 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;

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

@ -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 java.sql.Driver;
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

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

@ -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 java.sql.Driver;
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