Javadoc polish & pruning dead code

org.springframework.config.java/src/main/java/org/springframework/config/java/Bean.java

@@ -17,137 +17,83 @@ package org.springframework.config.java;
 
 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;
 
+import org.springframework.context.annotation.Scope;
+
 
 /**
- * Annotation to be applied to methods that create beans in a Spring context. The name of
- * the bean is the method name. (It is also possible to specify aliases using the aliases
- * array on this annotation.)
+ * Indicates that a method produces a bean to be managed by the Spring container. The
+ * 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>
- * Contains information similar to that held in Spring's internal BeanDefinition metadata.
- * </p>
+ * <p>The Bean annotation does not provide attributes for scope, primary or lazy. Rather,
+ * it should be used in conjunction with {@link Scope}, {@link Primary} and {@link Lazy}
+ * annotations to acheive the same semantics.
  * 
- * <p>
- * Bean creation methods must be non-private (default, public or protected). Bean creation
- * methods may throw any exception, which will be caught and handled by the Spring container
- * on processing of the configuration class.<br>
- * Bean creation methods must return an object type. The decision to return a class or an
- * interface will be significant in the event of proxying. Bean methods that return
- * interfaces will be proxied using dynamic proxies; those that return a class will require
- * CGLIB or other subclass-based proxying. It is recommended to return an interface where
- * possible, as this is also consistent with best practice around loose coupling.
- * </p>
+ * <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 (aka aliases) for a single bean.
  * 
- * <p>
- * Bean creation methods may reference other bean creation methods by calling them directly,
- * as follows. This ensures that references between beans are strongly typed:
- * </p>
+ * <h3>Constraints</h3>
+ * <ul>
+ *     <li>Bean methods are valid only when declared within a {@link 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 may throw any exception, which will be caught and handled
+ *  by the Spring container on processing of the declaring {@link 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.
  * 
- * @see Configuration
  * 
  * @author Rod Johnson
  * @author Costin Leau
  * @author Chris Beams
  * @since 3.0
+ * @see Configuration
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
-@Inherited
 @Documented
 public @interface Bean {
 
-	// TODO: 
-//	/**
-//	 * Role this bean plays in the overall application configuration.
-//	 * 
-//	 * @see BeanDefinition#ROLE_APPLICATION
-//	 * @see BeanDefinition#ROLE_INFRASTRUCTURE
-//	 * @see BeanDefinition#ROLE_SUPPORT
-//	 * 
-//	 * @see AbstractBeanDefinition the 'role' field is assigned by default to
-//	 *      ROLE_APPLICATION
-//	 */
-//	int role() default BeanDefinition.ROLE_APPLICATION;
-	
+	/**
+	 * The name of this bean, or if plural, aliases for this bean. If left unspecified
+	 * the name of the bean is the name of the annotated method. If specified, the method
+	 * name is ignored.
+	 */
 	String[] name() default {};
 
-	// TODO: Prune aliases, favor name[]
-//	/**
-//	 * Bean aliases.
-//	 */
-//	String[] aliases() default {};
-
-	// TODO: favor @Scope
-//	/**
-//	 * Scope: whether the bean is a singleton, prototype or custom scope. Default is
-//	 * singleton.
-//	 */
-//	String scope() default StandardScopes.SINGLETON;
-
-	// TODO: prune autowiring?
-//	/**
-//	 * Bean autowire strategy.
-//	 */
-//	Autowire autowire() default Autowire.INHERITED;
-
-	// /**
-	// * Bean lazy strategy.
-	// */
-	// Lazy lazy() default Lazy.UNSPECIFIED;
-	//
-	// /**
-	// * A bean may be marked as primary, useful for disambiguation when looking
-	// * up beans by type.
-	// *
-	// * @see
-	// org.springframework.config.java.context.JavaConfigApplicationContext#getBean(Class);
-	// */
-	// Primary primary() default Primary.UNSPECIFIED;
-
 	/**
-	 * Bean init method name. Normally this is not needed, as the initialization (with
-	 * parameterization) can be done directly through java code.
+	 * The optional name of a method to call on the bean instance during initialization.
+	 * Not commonly used, given that the method may be called programmatically directly
+	 * within the Bean method.
 	 */
 	String initMethod() default "";
 
 	/**
-	 * Bean destroy method name.
+	 * The optional name of a method to call on the bean instance during upon closing
+	 * the application context, for example a {@literal close()}
+	 * method on a {@literal DataSource}.
 	 */
 	String destroyMethod() default "";
 
-	// TODO: Prune DependencyCheck
-	// /**
-	// * Bean dependency check strategy.
-	// */
-	// DependencyCheck dependencyCheck() default DependencyCheck.UNSPECIFIED;
-
 	/**
-	 * Beans on which the current bean depends on.
+	 * Beans on which the current bean depends. Any beans specified are guaranteed to be
+	 * created by the container before this bean. Used infrequently in cases where a bean
+	 * does not explicitly depend on another through properties or constructor arguments,
+	 * but rather depends on the side effects of another bean's initialization.
 	 */
 	String[] dependsOn() default {};
 
-	// TODO: Prune @Meta
-	// /**
-	// * Metadata for the current bean.
-	// */
-	// Meta[] meta() default { };
-
-	// TODO: Prune allowOverriding
-//	/**
-//	 * Allow the bean to be overridden in another JavaConfig, XML or other non-Java
-//	 * configuration. This is consistent with DefaultListableBeanFactory's
-//	 * allowBeanDefinitionOverriding property, which defaults to true.
-//	 * 
-//	 * @return whether overriding of this bean is allowed
-//	 */
-//	boolean allowOverriding() default true;
-//
-	//String name() default "";
-
 }
 

org.springframework.config.java/src/main/java/org/springframework/config/java/Configuration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * 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.
@@ -22,33 +22,42 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.springframework.beans.factory.annotation.Autowire;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.config.java.support.ConfigurationClassPostProcessor;
 import org.springframework.stereotype.Component;
 
 
 /**
- * Annotation indicating that a class is a "Java Configuration" class, meaning that it
- * exposes one or more {@link Bean} methods. Holds similar information to that held in the
- * default values of a bean factory; can generally be thought of as the JavaConfig
- * equivalent of XML's 'beans' root element.
+ * 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>
- * Note however that the information here is not used to populate the defaults of the owning
- * bean factory, which would affect other configurations. In the style of the Java
- * configuration mechanism generally, each Java configuration class is kept isolated.
- * </p>
+ * <p>Configuration is itself annotated as a {@link Component}, therefore Configuration
+ * classes are candidates for component-scanning and may also take advantage of
+ * {@link Autowire} at the field and method and constructor level.
  * 
- * <p>
- * Configuration-annotated classes are also candidates for component scanning thanks to the
- * fact that this annotation is meta-annotated with {@link Component @Component}.
- * </p>
+ * <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.
  * 
- * May be used in conjunction with {@link Lazy}
+ * <h3>Constraints</h3>
+ * <ul>
+ *    <li>Configuration classes must be non-final
+ *    <li>Configuration classes must be non-local (may not be declared within a method)
+ *    <li>Configuration classes must have a default/no-arg constructor or an
+ *        {@link Autowired} constructor
+ * </ul>
+ * 
+ * TODO: test constructor autowiring<br>
+ * TODO: test private Configuration classes<br>
+ * TODO: test @Lazy @Configuration<br>
  * 
  * @author Rod Johnson
  * @author Chris Beams
  * @since 3.0
- * @see Lazy
+ * @see ConfigurationClassPostProcessor
  * @see Bean
+ * @see Lazy
  */
 @Component
 @Target( { ElementType.TYPE })
@@ -57,55 +66,4 @@ import org.springframework.stereotype.Component;
 @Documented
 public @interface Configuration {
 
-	// TODO: consider pruning @Configuration(name[])
-//	/**
-//	 * Configuration name. Allow different variants, such as test, production etc. Default
-//	 * will always match.
-//	 * 
-//	 * @return
-//	 */
-//	String[] name() default "";
-
-	// TODO: Prune defaultAutowire
-//	/**
-//	 * Specifies the default autowiring strategy.
-//	 * 
-//	 * @see Autowire
-//	 * @return
-//	 */
-//	Autowire defaultAutowire() default Autowire.INHERITED;
-
-	// TODO: Prune DependencyCheck
-	// /**
-	// * Dependency check strategy. By default, the dependency check is
-	// * unspecified, that is the default Spring option will apply. In most cases,
-	// * it means no dependency check will be done.
-	// *
-	// * @see DependencyCheck
-	// * @return
-	// */
-	// DependencyCheck defaultDependencyCheck() default DependencyCheck.UNSPECIFIED;
-	//
-	
-	// TODO: Favor @Lazy at the @Configuration class level.  Should have @Target(TYPE, METHOD)
-	// /**
-	// * Bean instantiation strategy. By default, it is unspecified.
-	// *
-	// * @see Lazy
-	// * @return
-	// */
-	// Lazy defaultLazy() default Lazy.UNSPECIFIED;
-
-	// TODO: prune useFactoryAspects
-//	/**
-//	 * Do we autowire with aspects from the enclosing factory scope?
-//	 */
-//	boolean useFactoryAspects() default false;
-
-	// TODO: this is the default, and needs to be switched off at annotation-config
-//	/**
-//	 * Do we check {@link Required @Required} methods to make sure they've been called?
-//	 */
-//	boolean checkRequired() default false;
-
-}
+}

org.springframework.config.java/src/main/java/org/springframework/config/java/internal/enhancement/AddAnnotationAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * 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.
@@ -29,8 +29,8 @@ import org.objectweb.asm.MethodVisitor;
  * the desired annotation is not already present before adding. Used by
  * {@link ConfigurationEnhancer} to dynamically add an {@link org.aspectj.lang.Aspect}
  * annotation to an enhanced Configuration subclass.
- * <p/>
- * This class was originally adapted from examples the ASM 3.0 documentation.
+ * 
+ * <p>This class was originally adapted from examples the ASM 3.0 documentation.
  * 
  * @author Chris Beams
  */

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

@@ -23,16 +23,26 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.stereotype.Component;
 
 /**
- * Indicates the name of a scope to use for instances of the annotated class.
+ * When used as a type-level annotation in conjunction with the {@link Component}
+ * annotation, indicates the name of a scope to use for instances of the annotated
+ * type.
+ * 
+ * <p>When used as a method-level annotation in conjunction with the
+ * {@link Bean} annotation, indicates the name of a scope to use for
+ * the instance returned from the method.
  *
  * <p>In this context, scope means the lifecycle of an instance, such as
- * '<code>singleton</code>', '<code>prototype</code>', and so forth.
+ * {@literal singleton}, {@literal prototype}, and so forth.
  * 
  * @author Mark Fisher
  * @author Chris Beams
  * @since 2.5
+ * @see Component
+ * @see Bean
+ * @see StandardScopes
  */
 @Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
@@ -40,8 +50,9 @@ import org.springframework.beans.factory.config.BeanDefinition;
 public @interface Scope {
 
 	/**
-	 * Specifies the scope to use for instances of the annotated class.
-	 * @return the desired scope
+	 * Specifies the scope to use for the annotated component/bean.
+	 * @return the specified scope
+	 * @see StandardScopes
 	 */
 	String value() default BeanDefinition.SCOPE_SINGLETON;
 
@@ -52,7 +63,7 @@ public @interface Scope {
 	 * <p>Defaults to {@link ScopedProxyMode#NO}, indicating no scoped proxy
 	 * should be created.
 	 * 
-	 * <p>Analogous to {@literal <aop:scoped-proxy/>} support in XML. Valid
+	 * <p>Analogous to {@literal <aop:scoped-proxy/>} support in Spring XML. Valid
 	 * only in conjunction with a non-singleton, non-prototype {@link #value()}.
 	 */
 	ScopedProxyMode proxyMode() default ScopedProxyMode.NO;