Javadoc polish & pruning dead code
This commit is contained in:
Chris Beams
parent
3231f458c8
commit
faffd98621
|
|
@ -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 "";
|
||||
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
}
|
||||
}
|
||||
|
|
@ -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
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue