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

Added Javadoc where necessary; polishing.

This commit is contained in:
Chris Beams 2009-11-12 07:29:52 +00:00
parent 2e12907fe4
commit 9f07b15185
8 changed files with 246 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java
View File

@ -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

18
org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java
View File

@ -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 "";
}

8
org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClass.java
View File

@ -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);
}

2
org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassBeanDefinitionReader.java
View File

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

6
org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassParser.java
View File

@ -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>();

19
org.springframework.context/src/main/java/org/springframework/context/annotation/Import.java
View File

@ -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 {

30
org.springframework.context/src/main/java/org/springframework/context/annotation/ImportResource.java
View File

@ -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;
}

358
org.springframework.samples.petclinic/src/main/java/org/springframework/samples/petclinic/config/DbcpDataSourceFactory.java
View File

@ -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
// 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<DataSource> 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<DataSource> 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);
}
}
}