- * Contains information similar to that held in Spring's internal BeanDefinition metadata. - *
+ *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. * - *
- * 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.
- * 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.
- *
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. * - *
- * Bean creation methods may reference other bean creation methods by calling them directly, - * as follows. This ensures that references between beans are strongly typed: - *
+ *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 ""; - } diff --git a/org.springframework.config.java/src/main/java/org/springframework/config/java/Configuration.java b/org.springframework.config.java/src/main/java/org/springframework/config/java/Configuration.java index d07c689d62..f37775ba53 100644 --- a/org.springframework.config.java/src/main/java/org/springframework/config/java/Configuration.java +++ b/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. * - *
- * 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. - *
+ *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. * - *
- * Configuration-annotated classes are also candidates for component scanning thanks to the - * fact that this annotation is meta-annotated with {@link Component @Component}. - *
+ *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} + *
This class was originally adapted from examples the ASM 3.0 documentation. * * @author Chris Beams */ diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/Scope.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/Scope.java index 4342dda130..a52e0092eb 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/Scope.java +++ b/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. + * + *
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. * *
In this context, scope means the lifecycle of an instance, such as
- * 'singleton', 'prototype', 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 {
*
Defaults to {@link ScopedProxyMode#NO}, indicating no scoped proxy * should be created. * - *
Analogous to {@literal
Analogous to {@literal