diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java index ad45ce9ed89..bd58f61592d 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java +++ b/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 } element in the Spring XML schema. Deviations are * as follows: - * + * *

The Bean annotation does not provide attributes for scope, primary or lazy. Rather, * it should be used in conjunction with {@link Scope @Scope}, * {@link Primary @Primary}, and {@link Lazy @Lazy} annotations to achieve the * same semantics. - * + * *

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. - * + * *

Constraints

* - * + * *

Usage

*

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 diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java index 0cd221faef0..08ea04ebeee 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java +++ b/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. - * + * *

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. - * + * *

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. - * + * *

Constraints

* - * + * * @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. - * + * *

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 ""; - + } diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClass.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClass.java index 34b14c000cb..eb25db05977 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClass.java +++ b/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 importedResources = new LinkedHashMap(); private final Set methods = new LinkedHashSet(); private final Map overloadedMethodMap = new LinkedHashMap(); + private String beanName; + public ConfigurationClass(MetadataReader metadataReader, String beanName) { this.metadata = metadataReader.getAnnotationMetadata(); @@ -102,11 +102,11 @@ final class ConfigurationClass { } return this; } - + public Set getMethods() { return this.methods; } - + public void addImportedResource(String importedResource, Class readerClass) { this.importedResources.put(importedResource, readerClass); } diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassBeanDefinitionReader.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassBeanDefinitionReader.java index ca3c5b78968..e0578224af4 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassBeanDefinitionReader.java +++ b/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. diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassParser.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassParser.java index 684e13e3f46..5cdfade8394 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassParser.java +++ b/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). - * + * *

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 importStack = new ImportStack(); - + private final Set configurationClasses = new LinkedHashSet(); diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/Import.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/Import.java index 51b6f01fc86..61c14a9a6c5 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/Import.java +++ b/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. + * *

Provides functionality equivalent to the {@literal } element in Spring XML. - * Only supported for actual {@link Configuration} classes. + * Only supported for actual {@literal @Configuration}-annotated classes. + * + *

{@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. + * + *

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 { diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/ImportResource.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/ImportResource.java index f5300bf1cd8..9aa10b99f5a 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/ImportResource.java +++ b/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. + * + *

Like {@link Import @Import}, this annotation provides functionality similar to the + * {@literal } 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. + * + *

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 } 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 reader() default XmlBeanDefinitionReader.class; } diff --git a/org.springframework.samples.petclinic/src/main/java/org/springframework/samples/petclinic/config/DbcpDataSourceFactory.java b/org.springframework.samples.petclinic/src/main/java/org/springframework/samples/petclinic/config/DbcpDataSourceFactory.java index 16fe9214838..0454161e65f 100644 --- a/org.springframework.samples.petclinic/src/main/java/org/springframework/samples/petclinic/config/DbcpDataSourceFactory.java +++ b/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, DisposableBean { - // configurable properties + // configurable properties - private String driverClassName; - - private String url; - - private String username; - - private String password; - - private boolean populate; + private String driverClassName; - private Resource schemaLocation; + private String url; - private Resource dataLocation; + private String username; - private Resource dropLocation; + private String password; - /** - * The object created by this factory. - */ - private BasicDataSource dataSource; + private boolean populate; - public void setDriverClassName(String driverClassName) { - this.driverClassName = driverClassName; - } + private Resource schemaLocation; - /** - * The data source connection URL - */ - public void setUrl(String url) { - this.url = url; - } + private Resource dataLocation; - /** - * The data source username - */ - public void setUsername(String username) { - this.username = username; - } + private Resource dropLocation; - /** - *The data source password - */ - public void setPassword(String password) { - this.password = password; - } + /** + * The object created by this factory. + */ + private BasicDataSource dataSource; - /** - * Indicates that the data base should be populated from the schema and data locations - */ - public void setPopulate(boolean populate) { - this.populate = populate; - } + public void setDriverClassName(String driverClassName) { + this.driverClassName = driverClassName; + } - /** - * 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; - } + /** + * The data source connection URL + */ + public void setUrl(String url) { + this.url = url; + } - /** - * 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; - } + /** + * The data source username + */ + public void setUsername(String username) { + this.username = username; + } - /** - * 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; - } + /** + *The data source password + */ + public void setPassword(String password) { + this.password = password; + } - // implementing FactoryBean + /** + * Indicates that the data base should be populated from the schema and data locations + */ + public void setPopulate(boolean populate) { + this.populate = populate; + } - // this method is called by Spring to expose the DataSource as a bean - public DataSource getObject() throws Exception { - if (dataSource == null) { - initDataSource(); - } - return dataSource; - } + /** + * 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; + } - public Class getObjectType() { - return DataSource.class; - } + /** + * 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; + } - public boolean isSingleton() { - return true; - } + /** + * 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 DisposableBean + // implementing FactoryBean - public void destroy() throws Exception { - dataSource.close(); - } + // this method is called by Spring to expose the DataSource as a bean + public DataSource getObject() throws Exception { + if (dataSource == null) { + initDataSource(); + } + return dataSource; + } - // internal helper methods + public Class getObjectType() { + return DataSource.class; + } - // 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(); + public boolean isSingleton() { + return true; + } - if (this.populate) { - // now populate the database by loading the schema and data - populateDataSource(); - } - } + // implementing DisposableBean - 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; - } + public void destroy() throws Exception { + dataSource.close(); + } - 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); - } + // internal helper methods - /** - * Populates a in memory data source with data. - */ - private class DatabasePopulator { + // 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(); - private DataSource dataSource; + if (this.populate) { + // now populate the database by loading the schema and data + populateDataSource(); + } + } - /** - * Creates a new database populator. - * @param dataSource the data source that will be populated. - */ - public DatabasePopulator(DataSource dataSource) { - this.dataSource = dataSource; - } + 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; + } - /** - * 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) { - } - } - } - } + 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); + } - // 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)); + /** + * Populates a in memory data source with data. + */ + private class DatabasePopulator { - StringWriter sw = new StringWriter(); - BufferedWriter writer = new BufferedWriter(sw); + private DataSource dataSource; - for (int c=reader.read(); c != -1; c=reader.read()) { - writer.write(c); - } - writer.flush(); - return sw.toString(); + /** + * Creates a new database populator. + * @param dataSource the data source that will be populated. + */ + public DatabasePopulator(DataSource dataSource) { + this.dataSource = dataSource; + } - } finally { - if (is != null) { - is.close(); - } - } - } + /** + * 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 run the parsed sql - private void executeSql(String sql, Connection connection) throws SQLException { - Statement statement = connection.createStatement(); - statement.execute(sql); - } - } + // 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); + } + } }