polish

Author: Keith Donald

org.springframework.jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/CannotReadScriptException.java

@@ -1,9 +1,33 @@
+/*
+ * Copyright 2002-2009 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.springframework.jdbc.datasource.embedded;
 
 import org.springframework.core.io.support.EncodedResource;
 
+/**
+ * Thrown by {@link ResourceDatabasePopulator} if one of its SQL scripts could not be read during population.
+ * @author Keith Donald
+ */
 public class CannotReadScriptException extends RuntimeException {
 
+	/**
+	 * Creates a new cannot read script exception.
+	 * @param resource the resource that could not be read from
+	 * @param cause the underlying cause of the resource access failure
+	 */
 	public CannotReadScriptException(EncodedResource resource, Throwable cause) {
 		super("Cannot read SQL script from " + resource, cause);
 	}

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

@@ -20,7 +20,7 @@
 import org.springframework.jdbc.datasource.SimpleDriverDataSource;
 
 /**
- * A factory for a kind of DataSource, such as a {@link SimpleDriverDataSource} or connection pool such as Apache DBCP or c3p0.
+ * A factory for DataSource implementation, such as a {@link SimpleDriverDataSource} or connection pool such as Apache DBCP or c3p0.
  * Call {@link #getConnectionProperties()} to configure normalized DataSource properties before calling {@link #getDataSource()} to actually get the configured DataSource instance.
  * @author Keith Donald 
  */

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

@@ -19,7 +19,7 @@
 
 /**
  * Encapsulates the configuration required to create, connect to, and shutdown a specific type of embedded database such as HSQLdb or H2.
- * Create a implementation for each database type we wish to support.
+ * Create a implementation for each database type you wish to support; for example HSQL, H2, or some other type.
  * @author Keith Donald
  */
 public interface EmbeddedDatabaseConfigurer {

org.springframework.jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseConfigurerFactory.java

@@ -18,22 +18,27 @@
 import org.springframework.util.Assert;
 
 /**
- * Package private factory for mapping well-known embedded database types to database configurer strategies.
+ * Package private factory for mapping well-known {@link EmbeddedDatabaseType embedded database types} to
+ * {@link EmbeddedDatabaseConfigurer} strategies.
  * @author Keith Donald
  */
-class EmbeddedDatabaseConfigurerFactory {
+final class EmbeddedDatabaseConfigurerFactory {
 
+	private EmbeddedDatabaseConfigurerFactory() {		
+	}
+	
 	public static EmbeddedDatabaseConfigurer getConfigurer(EmbeddedDatabaseType type) throws IllegalStateException {
 		Assert.notNull(type, "The EmbeddedDatabaseType is required");
 		try {
 			if (type == EmbeddedDatabaseType.HSQL) {
 				return HsqlEmbeddedDatabaseConfigurer.getInstance();
 			} else {
-				throw new UnsupportedOperationException("Other types not yet supported");
+				throw new UnsupportedOperationException("Other embedded database types not yet supported");
 			}
 		} catch (ClassNotFoundException e) {
-			throw new IllegalStateException("Drivers for test database type [" + type + "] are not available in the classpath", e);
+			throw new IllegalStateException("Drivers for test database type [" + type
+					+ "] are not available in the classpath", e);
 		}
 	}
-	
+
 }

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

@@ -116,14 +116,19 @@ public void setDataSourceFactory(DataSourceFactory dataSourceFactory) {
 	 */
 	public EmbeddedDatabase getDatabase() {
 		if (dataSource == null) {
-			initDataSource();
+			initDatabase();
 		}
 		return new EmbeddedDataSourceProxy(dataSource);
 	}
 
 	// subclassing hooks
 
-	protected void initDataSource() {
+	/**
+	 * 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.
+	 */
+	protected void initDatabase() {
 		// create the embedded database source first
 		if (logger.isInfoEnabled()) {
 			logger.info("Created embedded database '" + databaseName + "'");
@@ -136,11 +141,23 @@ protected void initDataSource() {
 		}
 	}
 
+	/**
+	 * Hook that gets the datasource that provides the connectivity to the embedded database.
+	 * Returns null if the datasource has not been initialized or the database has been shutdown.
+	 * Subclasses may call to access the datasource instance directly.
+	 * @return the datasource
+	 */
 	protected DataSource getDataSource() {
 		return dataSource;
 	}
 
-	protected void shutdownDataSource() {
+	/**
+	 * Hook to shutdown the embedded database.
+	 * Subclasses may call to force shutdown.
+	 * After calling, {@link #getDataSource()} returns null.
+	 * Does nothing if no embedded database has been initialized.
+	 */
+	protected void shutdownDatabase() {
 		if (dataSource != null) {
 			databaseConfigurer.shutdown(dataSource);
 			dataSource = null;
@@ -200,7 +217,7 @@ public <T> T unwrap(Class<T> iface) throws SQLException {
 		}
 
 		public void shutdown() {
-			shutdownDataSource();
+			shutdownDatabase();
 		}
 
 	}

org.springframework.jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseFactoryBean.java

@@ -32,7 +32,7 @@
 public class EmbeddedDatabaseFactoryBean extends EmbeddedDatabaseFactory implements FactoryBean<DataSource>, InitializingBean, DisposableBean {
 
 	public void afterPropertiesSet() throws Exception {
-		initDataSource();
+		initDatabase();
 	}
 
 	public DataSource getObject() throws Exception {
@@ -48,7 +48,7 @@ public boolean isSingleton() {
 	}
 
 	public void destroy() throws Exception {
-		shutdownDataSource();
+		shutdownDatabase();
 	}	
 
 }

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

@@ -25,12 +25,26 @@
 import org.apache.commons.logging.LogFactory;
 import org.springframework.util.ClassUtils;
 
-public class HsqlEmbeddedDatabaseConfigurer implements EmbeddedDatabaseConfigurer {
+/**
+ * Initializes a HSQL embedded database instance.
+ * Call {@link #getInstance()} to get the singleton instance of this class.
+ * 
+ * @author Keith Donald
+ */
+final class HsqlEmbeddedDatabaseConfigurer implements EmbeddedDatabaseConfigurer {
 
 	private static final Log logger = LogFactory.getLog(HsqlEmbeddedDatabaseConfigurer.class);
 
 	private static HsqlEmbeddedDatabaseConfigurer INSTANCE;
 
+	private HsqlEmbeddedDatabaseConfigurer() {	
+	}
+	
+	/**
+	 * Get the singleton {@link HsqlEmbeddedDatabaseConfigurer} instance.
+	 * @return the configurer
+	 * @throws ClassNotFoundException if HSQL is not on the classpath
+	 */
 	public static synchronized HsqlEmbeddedDatabaseConfigurer getInstance() throws ClassNotFoundException {
 		if (INSTANCE == null) {
 			ClassUtils.forName("org.hsqldb.jdbcDriver", HsqlEmbeddedDatabaseConfigurer.class.getClassLoader());

org.springframework.jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/SimpleDriverDataSourceFactory.java

@@ -4,13 +4,12 @@
 
 import org.springframework.jdbc.datasource.SimpleDriverDataSource;
 
-public class SimpleDriverDataSourceFactory implements DataSourceFactory {
+final class SimpleDriverDataSourceFactory implements DataSourceFactory {
 
 	private SimpleDriverDataSource dataSource = new SimpleDriverDataSource();
 
 	public ConnectionProperties getConnectionProperties() {
 		return new ConnectionProperties() {
-
 			public void setDriverClass(Class<?> driverClass) {
 				dataSource.setDriverClass(driverClass);
 			}
@@ -26,13 +25,11 @@ public void setUsername(String username) {
 			public void setPassword(String password) {
 				dataSource.setPassword(password);
 			}
-
 		};
 	}
 
 	public DataSource getDataSource() {
 		return dataSource;
 	}
-
 
 }