Spring JavaConfig参考文档

Spring JavaConfig参考文档
Spring JavaConfig Reference Documentation
Rod Johnson
Costin Leau
version 1.0-m2
Copies of this document may be made for your own use and for distribution to others, provided that you do not
charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether
distributed in print or electronically.
2007.05.08


目录
1. 介绍
2. 组件
  2.1 @Configuration
  2.2 @Bean
  2.3 @ExternalBean
  2.4 @ScopedProxy
3. Bean可见度
4. 装配依赖
5. 命名策略
6. 混合XM和annotations
7. 使用Java Configuration
8. Roadmap


第一章、介绍
在IoC中提到，Spring IoC核心为一个称为bean的概念。
这个概念定义了一个对象被Spring容器初始化、装配和管理的方式。
虽然Spring本身可以从任何metadata读取内容并装换成Java代码，但是XML是描述beans配置最流行的方式。
JDK5+中引入的Annotations允许源代码组件提供额外的metadata，这些metadata可以影响运行时语义。
这让annotations成为一个很好的配置选项。

第二章、组件
Java Configuration使用annotations来让开发人员不离开Java世界就可以创建和配置beans。
简短来说，开发人员使用Java代码来初始化和配置beans，然后指示容器使用它们。
在继续之前，请注意，Spring仍保持相同的语义，而不管采用何种配置方式: Java或者XML。
让我们看看JavaConfig依赖的最重要的annotations:

2.1 @Configuration
@Configuration标记指示配置类:

@Configuration
public class WebConfiguration {
  // bean definitions follow
}

@Configuration是一个class级别的annotation，它指示了配置里定义的bean的一些默认值。

@Configuration(defaultAutowire = Autowire.BY_TYPE, defaultLazy = Lazy.FALSE)
public classDataSourceConfiguration extends ConfigurationSupport {}

它可以认为是<beans/>标签的替代品。
用@Configuration标注的类继承ConfigurationSupport是明智的，因为该类提供了一些辅助方法。

2.2 @Bean
@Bean的名字暗示了一个bean定义(<bean/>标签)，让我们以一个简单的例子开始:

@Bean (scope = DefaultScopes.SESSION)
public ExampleBean exampleBean() {
  return new ExampleBean();
}

上面的代码指示Spring容器使用方法名(作为bean的名字)和返回值(实际的bean实例)来创建一个bean。
该bean拥有session作用域，这意味着调用exampleBean()方法将为每个HTTP会话创建一个新的bean实例。
由于使用纯Java，我们在处理静态方法时没有必要使用factory-method:

@Bean
public ExampleBean exampleBean() {
  return ExampleFactory.createBean();
}

或者使用FactoryBean/MethodInvokingFactoryBean来创建复杂对象:

@Bean(aliases = {"anniversaries"})
public List<Date> birthdays() {
  List<Date> dates = new ArrayList<Date>();
  Calendar calendar = Calendar.getInstance();
  calendar.set(1977, 05, 28);
  dates.add(calendar.getTime());
  dates.add(computeMotherInLawBirthday());
  return dates;
}

@Bean是一个method级别的annotation并指示用来创建和配置一个bean实例的Java代码。
该标记支持XML bean定义的大部分选项，如autowiring，lazy-init，dependency-check，depends-on和scoping。
并且，lifecycle方法和*Aware接口完全支持:

public class AwareBean implements BeanFactoryAware {
  private BeanFactory factory;
  // BeanFactoryAware setter
  public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
    this.factory - beanFactory;
  }
  public void close() {
    // do clean-up
  }
}

@Bean(destroyMethodName = "close", lazy = Lazy.TRUE)
public AwareBean createBeanFactoryAwareBean() {
  return new AwareBean();
}

除了destroyMethodName，@Bean标记也支持initMethodName。

2.3 @ExternalBean
@ExternalBean是一个简单的markup标记，它用来注入在父application context中定义的"外部"beans，让我们看看例子:

@Configuration
public abstract class ExternalBeanConfiguration {
  @Bean
  public TestBean james() {
    TestBean james = new TestBean();
    // inject dependency from ann()
    james.setSpouse(ann());
    return james;
  }

  // Will be taken from the parent context
  @ExternalBean
  public abstract TestBean ann();
}

当JavaConfig遇到@ExternalBean时，它将覆盖该方法，这样任何时候该方法被调用时，将在父application context里查找该方法名的bean。
这样，你的配置保持纯Java和重构友好性。
注意@ExternalBean也在普通方法上工作；上面的例子使用抽象方法来避免写入无法执行的dummy code:

@Configuration
public class ExternalBeanOnNormalMethod {
  @ExternalBean
  public TestBean ann() {
    System.out.println("this code will not execute as the method " +
      "will be overriden with a bean look up at runtime");
  }
}

2.4 @ScopedProxy
Spring通过使用scoped proxies来提供方便的方式与scoped dependencies工作。
当使用XML配置时创建这样的proxy最简单的方式为<aop:scoped-proxy/>元素。
JavaConfig提供@ScopedProxy标记作为替换品，它提供相同的语义和配置选项。
参考文档里XML scoped proxy的例子在JavaConfig里看起来像这样:

// a HTTP Session-scoped bean exposed as a proxy
@Bean(scope = DefaultScopes.SESSION)
@ScopedProxy
public UserPreferences userPreferences() {
  return new UserPreferences();
}

@Bean
public Service userService() {
  UserService service = new SimpleUserService();
  // a reference to the proxied 'userPreferences' bean
  service.setUserPreferences(userPreferences());
  return service;
}

第三章、Bean可见度
JavaConfig的一个很好的特性是bean可见度。
JavaConfig使用方法可见度修饰符来决定从该方法得到的bean是否可以通过owning application context/bean factory来访问。
考虑如下配置:

@Configuration
public abstract class VisibilityConfiguration {
  @Bean
  public Bean publicBean() {
    Bean bean = new Bean();
    bean.setDependency(hiddenBean());
    return bean;
  }

  @Bean
  protected HiddenBean hiddenBean() {
    return new Bean("protected bean");
  }

  @Bean
  private HiddenBean secretBean() {
    Bean bean = new Bean("private bean");
    // hidden beans can access beans defined in the 'owning' context
    bean.setDependency(outsideBean());
  }

  @ExternalBean
  public abstract Bean outsideBean()
}

和如下XML配置一起使用:

<beans>
  <!-- the configuration above -->
  <bean class="my.java.config.VisibilityConfiguration"/>

  <!-- Java Configuration post processor -->
  <bean class="org.springframework.config.java.process.ConfigurationPostProcessor"/>

  <bean id="mainBean" class="my.company.Bean">
    <!-- this will work -->
    <property name="dependency" ref="publicBean"/>
    <!-- this will *not* work -->
    <property name="anotherDependency" ref="hiddenBean"/>
  </bean>
</beans>

JavaConfig遇到如上的配置时，它将创建3个beans: publicBean， hiddenBean和secretBean。
它们是互相可见的，但是在'owning' application context(启动JavaConfig的application context)里创建的beans将只能看到publicBean。
hiddenBean和secretBean只能被在VisibilityConfiguration里创建的beans访问。
任何被@Bean标注的非public方法(protected, private和default)将创建一个'hidden' bean。
在上面的例子里，mainBean使用publicBean和hiddenBean配置。
但是，由于后者是hidden的，在运行时Spring将抛出异常:
org.springframework.beans.factory.NoSuchBeanDefinitionException: No bean named 'hiddenBean' is defined
...
为了提供可见度功能，JavaConfig利用Spring提供的application context hierarchy，将所有的hidden beans放在一个子application context里一个
特殊的配置类里。这样，hidden beans可以访问在父(或owning)context里定义的beans，但是相反不行。

四、装配依赖
为了装配一个bean，通常需要简单的使用Java提供的constructs:

@Bean(scope = DefaultScopes.SINGLETON)
public Person rod() {
  return new Person("Rod Johnson");
}

@Bean(scope = DefaultScopes.PROTOTYPE)
public Book book() {
  Book book = new Book("Expert one-on-one J2EE Design and Development");
  book.setAuthor(rod()); // rod() method is actually a bean reference !
  return book;
}

上面的例子中，book的author使用rod方法的返回值。
但是，由于book和rod方法都被@Bean标记，结果得到的Spring管理的beans将遵循容器语义: rod bean将是singleton而book bean将是prototype。
当创建配置时，Spring知道annotation context并且将用名为"rod"的bean的引用来代替rod()方法。
每次book bean被请求时容器将返回一个新的Book实例(prototype)，但是对rod bean则将返回同一实例(singleton)。
上面的代码等同于:

<bean id="rod" class="Person" scope="singleton">
  <constructor-arg>Rod Johnson</constructor-arg>
</bean>

<bean id="book" class="Book" scope="prototype">
  <constructor-arg>Expert One-on-On J2EE Design and Development</constructor-arg>
  <property name="author" ref="rod" />
</bean>

注意上面的例子使用两个常见的scopes类型，而任何类型的scoping都可以被指定:

@Bean (scope = "customer")
public Bag shopingBag() {
  return new Basket();
}

@Bean (scope = "shift")
public Manager shopManager() {
  ...
}

五、命名策略
到目前为止，上面所有的例子里，bean的名字都来自于方法名:

@Configuration
public class ColorsConfiguration {
  // create a bean with name 'blue'
  @Bean
  public Color blue() {
    ...
  }
  ...
}

// dependency lookup for the blue color
applicationContext.getBean("blue");

在某些情况下，以方法名作为同样的bean名字并不合适，不同的类将覆盖定义。
为了定制该行为，我们可以实现BeanNamingStrategy接口来提供自己的名字生成策略。
但是，在写你自己的代码之前，看看默认实现MethodNameStrategy提供的选项:

<!-- Java Configuration post processor -->
<bean class="org.springframework.config.java.process.ConfigurationPostProcessor">
  <property name="namingStrategy">
    <bean class="org.springframework.config.java.naming.MethodNameStrategy">
      <property name="prefix" value="CLASS"/>
    </bean>
  </property>
</bean>

这样配置后，bean的名字将为bean创建方法加上class名前缀:

// dependency lookup for the blue color using the new naming scheme
applicationContext.getBean("ColorsConfiguration.blue");

六、混合XML和annotations
Java和XML配置不是互斥的--它们可以同时在同一Spring程序里使用。为了从一个XML文件得到bean，我们需要使用Spring容器。
前面提到，我们可以使用@ExternalBean标记(推荐方式)。
当这种方式不适用时，可以访问@Configuration类使用的底层beanFactory。
这可以通过继承ConfigurationSupport或实现BeanFactoryAware接口来实现。
考虑下面的XML配置:

<bean id="myBean" class="MyBean"/>

为了引用myBean这个bean，我们可以使用下面的代码片段:

@Configuration
public class MyConfig extends ConfigurationSupport {
  @Bean
  public ExampleBean anotherBean() {
    ExampleBean bean = new ExampleBean("anotherBean");
    bean.setDep(getBean("myBean")); // use utility method to get a hold of 'myBean'
    return bean;
  }
}

@Configuration
public class MyOtherConfig implements BeanFactoryAware {
  private BeanFactory beanFactory;

  public void setBeanFactory(BeanFactory beanFactory) {
    // get access to the owning bean factory
    this.beanFactory = beanFactory;
  }

  @Bean
  public ExampleBean yetAnotherBean() {
    ExampleBean bean = new ExampleBean("yetAnotherBean");
    bean.setDep(beanFactory.getBean("myBean")); // use dependency lookup
    return bean;
  }
}

在使用ConfigurationSupport或BeanFactoryAware之前请三思，因为@ExternalBean以重构更友好的方式提供同样的功能。
JavaConfig发布时包含了一个Petclinic示例，它使用Java和Groovy来替换部分XML配置--请参考示例程序获得更多信息。

七、使用Java Configuration
为了使用annotations来配置我们的程序，我们可以使用:

a, AnnotationApplicationContext
它接收Ant风格模式的类名来搜索annotations:

ApplicationContext config = new AnnotationApplicationContext(SimpleConfiguration.class.getName());
ApplicatonContext aBunchOfConfigs = new AnnotationApplicationContext("**/configuration/*Configuration.class");

这种特有的application context将自动读取classpath下匹配给定模式的类并添加进来作为beans，缺点是这种方式不允许配置实例带参数。

b, Configuration post processor

<beans>
  <!-- Spring configuration -->
  <bean class="org.springframework.samples.petclinic.JdbcConfiguration"/>
  <!-- Java Configuration post processor -->
  <bean class="org.springframework.config.java.process.ConfigurationPostProcessor"/>
</beans>

这种方式允许更多的配置选项，因为它不仅提供对configuration processing(通过ConfigurationPostProcessor)的控制，也提供对配置实例本身。
通过定义configuration为一个bean，Spring容器可以用来配置configuration(设置properties或者使用某个构造方法):

<beans>
<!-- a possible configurable configuration -->
<bean class="org.my.company.cofig.AppConfiguration">
  <property name="env" value="TESTING"/>
  <property name="monitoring" value="true"/>
  <property name="certificates" value="classpath:/META-INF/config/MyCompany.certs"/>
</bean>

<!-- Java Configuration post processor -->
<bean class="org.springframework.config.java.process.ConfigurationPostProcessor"/>
</beans>

第八章、Roadmap
该project相对来说很年轻，可以认为是beta版(hence, the milestone release)。
后继的开发将关注于自动配置发现和简化。
反馈、八哥和建议在Srping forum和Spring issue tracking都是受欢迎的。

译者说:
Spring JavaConfig和Google Guice的区别主要在于它们两者的IoC理念不同:
JavaConfig说IoC配置是必须无侵入的，所以单独弄了个@Configuration
Guice说IoC配置是应用程序模型的一部分，所以配置都扔在领域模型代码中

最后感谢老婆公司领导命令她今天加班，译者今天才有一天的时间来翻译此文档。

Spring JavaConfig和Spring annotation(http://spring-annotation.dev.java.net)区别在哪儿，Spring 2.1采用的是哪种方式，太乱了，，，
感觉是spring还是要使用Annotation配合xml的方式，xml中写Spring中最基本的bean，Annotation用在自己的Bean上，写一个Configuration太不爽了吧。

还好现在Spring项目还没有用到这些东西

JavaConfig和sannotations都以plugins的方式使用，Spring现在还没有集成它们，而JavaConfig是Spring的子项目，Spring要把Annotation配置集成到核心代码的话肯定选择JavaConfig了

你要采用annotation方式配置，就表示接受使用@Configuration