Added Javadoc where necessary; polishing.

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@2388 50f2f4bb-b051-0410-bef5-90022cba6387

org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java

@@ -29,32 +29,32 @@ import org.springframework.beans.factory.annotation.Autowire;
  * names and semantics of the attributes to this annotation are intentionally similar
  * to those of the {@literal <bean/>} element in the Spring XML schema. Deviations are
  * as follows:
- * 
+ *
  * <p>The Bean annotation does not provide attributes for scope, primary or lazy. Rather,
  * it should be used in conjunction with {@link Scope &#064;Scope},
  * {@link Primary &#064;Primary}, and {@link Lazy &#064;Lazy} annotations to achieve the
  * same semantics.
- * 
+ *
  * <p>While a {@link #name()} attribute is available, the default strategy for determining
  * the name of a bean is to use the name of the Bean method. This is convenient and
  * intuitive, but if explicit naming is desired, the {@link #name()} attribute may be used.
  * Also note that {@link #name()} accepts an array of strings. This is in order to allow
  * for specifying multiple names (i.e., aliases) for a single bean.
- * 
+ *
  * <h3>Constraints</h3>
  * <ul>
  *     <li>Bean methods are valid only when declared within an {@link Configuration &#064;Configuration}-annotated class
- * 	   <li>Bean methods must be non-void, non-final, non-private
- * 	   <li>Bean methods may not accept any arguments
+ *     <li>Bean methods must be non-void, non-final, non-private
+ *     <li>Bean methods may not accept any arguments
  *     <li>Bean methods may throw any exception, which will be caught and handled
  *  by the Spring container on processing of the declaring {@link Configuration &#064;Configuration} class.
  * </ul>
- * 
+ *
  * <h3>Usage</h3>
  * <p>Bean methods may reference other Bean methods by calling them directly. This ensures
  * that references between beans are strongly typed and navigable. So called 'inter-bean
  * references' are guaranteed to respect scoping and AOP semantics.
- * 
+ *
  * @author Rod Johnson
  * @author Costin Leau
  * @author Chris Beams

org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java

@@ -31,16 +31,16 @@ import org.springframework.stereotype.Component;
  * Indicates that a class declares one or more {@link Bean} methods and may be processed
  * by the Spring container to generate bean definitions and service requests for those beans
  * at runtime.
- * 
+ *
  * <p>Configuration is meta-annotated as a {@link Component}, therefore Configuration
  * classes are candidates for component-scanning and may also take advantage of
  * {@link Autowired} at the field and method but not at the constructor level.
  * Externalized values may be wired into Configuration classes using the {@link Value}
  * annotation.
- * 
+ *
  * <p>May be used in conjunction with the {@link Lazy} annotation to indicate that all Bean
  * methods declared within this class are by default lazily initialized.
- * 
+ *
  * <h3>Constraints</h3>
  * <ul>
  *    <li>Configuration classes must be non-final
@@ -48,15 +48,15 @@ import org.springframework.stereotype.Component;
  *    <li>Configuration classes must have a default/no-arg constructor and may not use
  *        {@link Autowired} constructor parameters
  * </ul>
- * 
+ *
  * @author Rod Johnson
  * @author Chris Beams
  * @since 3.0
  * @see Import
  * @see Lazy
  * @see Bean
- * @see ConfigurationClassPostProcessor;
- * @see AnnotationConfigApplicationContext ;
+ * @see ConfigurationClassPostProcessor
+ * @see AnnotationConfigApplicationContext
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
@@ -68,15 +68,15 @@ public @interface Configuration {
 	 * Explicitly specify the name of the Spring bean definition associated
 	 * with this Configuration class.  If left unspecified (the common case),
 	 * a bean name will be automatically generated.
-	 * 
+	 *
 	 * <p>The custom name applies only if the Configuration class is picked up via
 	 * component scanning or supplied directly to a {@link AnnotationConfigApplicationContext}.
 	 * If the Configuration class is registered as a traditional XML bean definition,
 	 * the name/id of the bean element will take precedence.
-	 * 
+	 *
 	 * @return the specified bean name, if any
 	 * @see org.springframework.beans.factory.support.DefaultBeanNameGenerator
 	 */
 	String value() default "";
-	
+
 }

org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClass.java

@@ -48,14 +48,14 @@ final class ConfigurationClass {
 
 	private final Resource resource;
 
-	private String beanName;
-
 	private final Map<String, Class> importedResources = new LinkedHashMap<String, Class>();
 
 	private final Set<ConfigurationClassMethod> methods = new LinkedHashSet<ConfigurationClassMethod>();
 
 	private final Map<String, Integer> overloadedMethodMap = new LinkedHashMap<String, Integer>();
 
+	private String beanName;
+
 
 	public ConfigurationClass(MetadataReader metadataReader, String beanName) {
 		this.metadata = metadataReader.getAnnotationMetadata();
@@ -102,11 +102,11 @@ final class ConfigurationClass {
 		}
 		return this;
 	}
-	
+
 	public Set<ConfigurationClassMethod> getMethods() {
 		return this.methods;
 	}
-	
+
 	public void addImportedResource(String importedResource, Class readerClass) {
 		this.importedResources.put(importedResource, readerClass);
 	}

org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassBeanDefinitionReader.java

@@ -233,7 +233,7 @@ class ConfigurationClassBeanDefinitionReader {
 			reader.loadBeanDefinitions(resource);
 		}
 	}
-	
+
 	/**
 	 * {@link RootBeanDefinition} marker subclass used to signify that a bean definition
 	 * created from a configuration class as opposed to any other configuration source.

org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassParser.java

@@ -37,11 +37,11 @@ import org.springframework.core.type.classreading.MetadataReaderFactory;
 import org.springframework.util.StringUtils;
 
 /**
- * Parses a {@link Configuration} class definition, populating a model (collection) of
+ * Parses a {@link Configuration} class definition, populating a collection of
  * {@link ConfigurationClass} objects (parsing a single Configuration class may result in
  * any number of ConfigurationClass objects because one Configuration class may import
  * another using the {@link Import} annotation).
- * 
+ *
  * <p>This class helps separate the concern of parsing the structure of a Configuration
  * class from the concern of registering {@link BeanDefinition} objects based on the
  * content of that model.
@@ -61,7 +61,7 @@ class ConfigurationClassParser {
 	private final ProblemReporter problemReporter;
 
 	private final Stack<ConfigurationClass> importStack = new ImportStack();
-	
+
 	private final Set<ConfigurationClass> configurationClasses =
 		new LinkedHashSet<ConfigurationClass>();
 

org.springframework.context/src/main/java/org/springframework/context/annotation/Import.java

@@ -18,25 +18,32 @@ package org.springframework.context.annotation;
 
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
-import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation that allows one {@link Configuration} class to import another Configuration,
- * and thereby all its {@link Bean} definitions.
- * 
+ * Indicates one or more {@link Configuration} classes to import.
+ *
  * <p>Provides functionality equivalent to the {@literal <import/>} element in Spring XML.
- * Only supported for actual {@link Configuration} classes.
+ * Only supported for actual {@literal @Configuration}-annotated classes.
+ *
+ * <p>{@literal @Bean} definitions declared in imported {@literal @Configuration} classes
+ * should be accessed by using {@link Autowired @Autowired} injection.  Either the bean
+ * itself can be autowired, or the configuration class instance declaring the bean can be
+ * autowired.  The latter approach allows for explicit, IDE-friendly navigation between
+ * {@literal @Configuration} class methods.
+ *
+ * <p>If XML or other non-{@literal @Configuration} bean definition resources need to be
+ * imported, use {@link ImportResource @ImportResource}
  *
  * @author Chris Beams
  * @since 3.0
  * @see Configuration
+ * @see ImportResource
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
-@Inherited
 @Documented
 public @interface Import {
 

org.springframework.context/src/main/java/org/springframework/context/annotation/ImportResource.java

@@ -25,13 +25,43 @@ import java.lang.annotation.Target;
 import org.springframework.beans.factory.support.BeanDefinitionReader;
 import org.springframework.beans.factory.xml.XmlBeanDefinitionReader;
 
+
+/**
+ * Indicates one or more resources containing bean definitions to import.
+ *
+ * <p>Like {@link Import @Import}, this annotation provides functionality similar to the
+ * {@literal <import/>} element in Spring XML.  It is typically used when
+ * designing {@link Configuration @Configuration} classes to be bootstrapped by
+ * {@link AnnotationConfigApplicationContext}, but where some XML functionality such as
+ * namespaces is still necessary.
+ *
+ * <p>By default, arguments to the {@link #value()} attribute will be processed using
+ * an {@link XmlBeanDefinitionReader}, i.e. it is assumed that resources are Spring
+ * {@literal <beans/>} XML files.  Optionally, the {@link #reader()} attribute may be
+ * supplied, allowing the user to specify a different {@link BeanDefinitionReader}
+ * implementation, such as
+ * {@link org.springframework.beans.factory.support.PropertiesBeanDefinitionReader}.
+ *
+ * @author Chris Beams
+ * @since 3.0
+ * @see Configuration
+ * @see Import
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @Documented
 public @interface ImportResource {
 
+	/**
+	 * Resource paths to import.  Resource-loading prefixes such as {@literal classpath:} and
+	 * {@literal file:}, etc may be used.
+	 */
 	String[] value();
 
+	/**
+	 * {@link BeanDefinitionReader} implementation to use when processing resources specified
+	 * by the {@link #value()} attribute.
+	 */
 	Class<? extends BeanDefinitionReader> reader() default XmlBeanDefinitionReader.class;
 
 }

org.springframework.samples.petclinic/src/main/java/org/springframework/samples/petclinic/config/DbcpDataSourceFactory.java

@@ -40,222 +40,222 @@ import org.springframework.core.io.Resource;
  * guaranteed that the database schema and data will have been loaded by that time.
  *
  * Is a FactoryBean, for exposing the fully-initialized DataSource as a Spring bean. See {@link #getObject()}.
- * 
+ *
  * @author Chris Beams
  * @author Scott Andrews
  */
 public class DbcpDataSourceFactory implements FactoryBean<DataSource>, DisposableBean {
 
-    // configurable properties
-
-    private String driverClassName;
-    
-    private String url;
-    
-    private String username;
-    
-    private String password;
-    
-    private boolean populate;
-
-    private Resource schemaLocation;
-
-    private Resource dataLocation;
-
-    private Resource dropLocation;
-
-    /**
-     * The object created by this factory.
-     */
-    private BasicDataSource dataSource;
-
-    public void setDriverClassName(String driverClassName) {
-        this.driverClassName = driverClassName;
-    }
-
-    /**
-     * The data source connection URL
-     */
-    public void setUrl(String url) {
-        this.url = url;
-    }
-
-    /**
-     * The data source username
-     */
-    public void setUsername(String username) {
-        this.username = username;
-    }
-
-    /**
-     *The data source password
-     */
-    public void setPassword(String password) {
-        this.password = password;
-    }
-
-    /**
-     * Indicates that the data base should be populated from the schema and data locations
-     */
-    public void setPopulate(boolean populate) {
-        this.populate = populate;
-    }
-
-    /**
-     * Sets the location of the file containing the schema DDL to export to the database.
-     * @param schemaLocation the location of the database schema DDL
-     */
-    public void setSchemaLocation(Resource schemaLocation) {
-        this.schemaLocation = schemaLocation;
-    }
-
-    /**
-     * Sets the location of the file containing the data to load into the database.
-     * @param testDataLocation the location of the data file
-     */
-    public void setDataLocation(Resource testDataLocation) {
-        this.dataLocation = testDataLocation;
-    }
-
-    /**
-     * Sets the location of the file containing the drop scripts for the database.
-     * @param testDataLocation the location of the data file
-     */
-    public void setDropLocation(Resource testDropLocation) {
-        this.dropLocation = testDropLocation;
-    }
-
-    // implementing FactoryBean
-
-    // this method is called by Spring to expose the DataSource as a bean
-    public DataSource getObject() throws Exception {
-        if (dataSource == null) {
-            initDataSource();
-        }
-        return dataSource;
-    }
-
-    public Class<DataSource> getObjectType() {
-        return DataSource.class;
-    }
-
-    public boolean isSingleton() {
-        return true;
-    }
-
-    // implementing DisposableBean
-
-    public void destroy() throws Exception {
-    	dataSource.close();
-    }
-
-    // internal helper methods
-
-    // encapsulates the steps involved in initializing the data source: creating it, and populating it
-    private void initDataSource() {
-        // create the database source first
-        this.dataSource = createDataSource();
-
-        if (this.populate) {
-        	// now populate the database by loading the schema and data
-        	populateDataSource();
-        }
-    }
-
-    private BasicDataSource createDataSource() {
-    	BasicDataSource dataSource = new BasicDataSource();
-        dataSource.setDriverClassName(this.driverClassName);
-        dataSource.setUrl(this.url);
-        dataSource.setUsername(this.username);
-        dataSource.setPassword(this.password);
-        return dataSource;
-    }
-
-    private void populateDataSource() {
-        DatabasePopulator populator = new DatabasePopulator(dataSource);
-        if (dropLocation != null) {
-            try {
-        		populator.populate(this.dropLocation);
-            } 
-            catch (Exception e) {
-               	// ignore
-            }
-        }
-        populator.populate(this.schemaLocation);
-        populator.populate(this.dataLocation);
-    }
-
-    /**
-     * Populates a in memory data source with data.
-     */
-    private class DatabasePopulator {
-
-        private DataSource dataSource;
-
-        /**
-         * Creates a new database populator.
-         * @param dataSource the data source that will be populated.
-         */
-        public DatabasePopulator(DataSource dataSource) {
-            this.dataSource = dataSource;
-        }
-
-        /**
-         * Populate the database executing the statements in the provided resource against the database
-         * @param sqlFile spring resource containing SQL to run against the db
-         */
-        public void populate(Resource sqlFile) {
-            Connection connection = null;
-            try {
-                connection = dataSource.getConnection();
-                try {
-                    String sql = parseSqlIn(sqlFile);
-                    executeSql(sql, connection);
-                } catch (IOException e) {
-                    throw new RuntimeException("I/O exception occurred accessing the database schema file", e);
-                } catch (SQLException e) {
-                    throw new RuntimeException("SQL exception occurred exporting database schema", e);
-                }
-            } catch (SQLException e) {
-                throw new RuntimeException("SQL exception occurred acquiring connection", e);
-            } finally {
-                if (connection != null) {
-                    try {
-                        connection.close();
-                    } catch (SQLException e) {
-                    }
-                }
-            }
-        }
-
-        // utility method to read a .sql txt input stream
-        private String parseSqlIn(Resource resource) throws IOException {
-            InputStream is = null;
-            try {
-                is = resource.getInputStream();
-                BufferedReader reader = new BufferedReader(new InputStreamReader(is));
-
-                StringWriter sw = new StringWriter();
-                BufferedWriter writer = new BufferedWriter(sw);
-
-                for (int c=reader.read(); c != -1; c=reader.read()) {
-                    writer.write(c);
-                }
-                writer.flush();
-                return sw.toString();
-
-            } finally {
-                if (is != null) {
-                    is.close();
-                }
-            }
-        }
-
-        // utility method to run the parsed sql
-        private void executeSql(String sql, Connection connection) throws SQLException {
-            Statement statement = connection.createStatement();
-            statement.execute(sql);
-        }
-    }
+	// configurable properties
+
+	private String driverClassName;
+
+	private String url;
+
+	private String username;
+
+	private String password;
+
+	private boolean populate;
+
+	private Resource schemaLocation;
+
+	private Resource dataLocation;
+
+	private Resource dropLocation;
+
+	/**
+	 * The object created by this factory.
+	 */
+	private BasicDataSource dataSource;
+
+	public void setDriverClassName(String driverClassName) {
+		this.driverClassName = driverClassName;
+	}
+
+	/**
+	 * The data source connection URL
+	 */
+	public void setUrl(String url) {
+		this.url = url;
+	}
+
+	/**
+	 * The data source username
+	 */
+	public void setUsername(String username) {
+		this.username = username;
+	}
+
+	/**
+	 *The data source password
+	 */
+	public void setPassword(String password) {
+		this.password = password;
+	}
+
+	/**
+	 * Indicates that the data base should be populated from the schema and data locations
+	 */
+	public void setPopulate(boolean populate) {
+		this.populate = populate;
+	}
+
+	/**
+	 * Sets the location of the file containing the schema DDL to export to the database.
+	 * @param schemaLocation the location of the database schema DDL
+	 */
+	public void setSchemaLocation(Resource schemaLocation) {
+		this.schemaLocation = schemaLocation;
+	}
+
+	/**
+	 * Sets the location of the file containing the data to load into the database.
+	 * @param testDataLocation the location of the data file
+	 */
+	public void setDataLocation(Resource testDataLocation) {
+		this.dataLocation = testDataLocation;
+	}
+
+	/**
+	 * Sets the location of the file containing the drop scripts for the database.
+	 * @param testDataLocation the location of the data file
+	 */
+	public void setDropLocation(Resource testDropLocation) {
+		this.dropLocation = testDropLocation;
+	}
+
+	// implementing FactoryBean
+
+	// this method is called by Spring to expose the DataSource as a bean
+	public DataSource getObject() throws Exception {
+		if (dataSource == null) {
+			initDataSource();
+		}
+		return dataSource;
+	}
+
+	public Class<DataSource> getObjectType() {
+		return DataSource.class;
+	}
+
+	public boolean isSingleton() {
+		return true;
+	}
+
+	// implementing DisposableBean
+
+	public void destroy() throws Exception {
+		dataSource.close();
+	}
+
+	// internal helper methods
+
+	// encapsulates the steps involved in initializing the data source: creating it, and populating it
+	private void initDataSource() {
+		// create the database source first
+		this.dataSource = createDataSource();
+
+		if (this.populate) {
+			// now populate the database by loading the schema and data
+			populateDataSource();
+		}
+	}
+
+	private BasicDataSource createDataSource() {
+		BasicDataSource dataSource = new BasicDataSource();
+		dataSource.setDriverClassName(this.driverClassName);
+		dataSource.setUrl(this.url);
+		dataSource.setUsername(this.username);
+		dataSource.setPassword(this.password);
+		return dataSource;
+	}
+
+	private void populateDataSource() {
+		DatabasePopulator populator = new DatabasePopulator(dataSource);
+		if (dropLocation != null) {
+			try {
+				populator.populate(this.dropLocation);
+			} 
+			catch (Exception e) {
+			   	// ignore
+			}
+		}
+		populator.populate(this.schemaLocation);
+		populator.populate(this.dataLocation);
+	}
+
+	/**
+	 * Populates a in memory data source with data.
+	 */
+	private class DatabasePopulator {
+
+		private DataSource dataSource;
+
+		/**
+		 * Creates a new database populator.
+		 * @param dataSource the data source that will be populated.
+		 */
+		public DatabasePopulator(DataSource dataSource) {
+			this.dataSource = dataSource;
+		}
+
+		/**
+		 * Populate the database executing the statements in the provided resource against the database
+		 * @param sqlFile spring resource containing SQL to run against the db
+		 */
+		public void populate(Resource sqlFile) {
+			Connection connection = null;
+			try {
+				connection = dataSource.getConnection();
+				try {
+					String sql = parseSqlIn(sqlFile);
+					executeSql(sql, connection);
+				} catch (IOException e) {
+					throw new RuntimeException("I/O exception occurred accessing the database schema file", e);
+				} catch (SQLException e) {
+					throw new RuntimeException("SQL exception occurred exporting database schema", e);
+				}
+			} catch (SQLException e) {
+				throw new RuntimeException("SQL exception occurred acquiring connection", e);
+			} finally {
+				if (connection != null) {
+					try {
+						connection.close();
+					} catch (SQLException e) {
+					}
+				}
+			}
+		}
+
+		// utility method to read a .sql txt input stream
+		private String parseSqlIn(Resource resource) throws IOException {
+			InputStream is = null;
+			try {
+				is = resource.getInputStream();
+				BufferedReader reader = new BufferedReader(new InputStreamReader(is));
+
+				StringWriter sw = new StringWriter();
+				BufferedWriter writer = new BufferedWriter(sw);
+
+				for (int c=reader.read(); c != -1; c=reader.read()) {
+					writer.write(c);
+				}
+				writer.flush();
+				return sw.toString();
+
+			} finally {
+				if (is != null) {
+					is.close();
+				}
+			}
+		}
+
+		// utility method to run the parsed sql
+		private void executeSql(String sql, Connection connection) throws SQLException {
+			Statement statement = connection.createStatement();
+			statement.execute(sql);
+		}
+	}
 
 }