PropertySource (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.context.annotation

## Annotation Type PropertySource

-     @Target(value=TYPE)
      @Retention(value=RUNTIME)
      @Documented
      public @interface PropertySource

  Annotation providing a convenient and declarative mechanism for adding a `PropertySource` to Spring's `Environment`. To be used in conjunction with @`Configuration` classes.

  ### Example usage

  Given a file `app.properties` containing the key/value pair `testbean.name=myTestBean`, the following `@Configuration` class uses `@PropertySource` to contribute `app.properties` to the `Environment`'s set of `PropertySources`.

       @Configuration
       @PropertySource("classpath:/com/myco/app.properties")
       public class AppConfig {
           @Autowired
           Environment env;

           @Bean
           public TestBean testBean() {
               TestBean testBean = new TestBean();
               testBean.setName(env.getProperty("testbean.name"));
               return testBean;
           }
       }

  Notice that the `Environment` object is @`Autowired` into the configuration class and then used when populating the `TestBean` object. Given the configuration above, a call to `testBean.getName()` will return "myTestBean".

  ### Resolving ${...} placeholders in `<bean>` and `@Value` annotations

  In order to resolve ${...} placeholders in `<bean>` definitions or `@Value` annotations using properties from a `PropertySource`, one must register a `PropertySourcesPlaceholderConfigurer`. This happens automatically when using `<context:property-placeholder>` in XML, but must be explicitly registered using a `static` `@Bean` method when using `@Configuration` classes. See the "Working with externalized values" section of @`Configuration` Javadoc and "a note on BeanFactoryPostProcessor-returning @Bean methods" of @`Bean` Javadoc for details and examples.

  ### Resolving ${...} placeholders within `@PropertySource` resource locations

  Any ${...} placeholders present in a `@PropertySource` resource location will be resolved against the set of property sources already registered against the environment. For example:

       @Configuration
       @PropertySource("classpath:/com/${my.placeholder:default/path}/app.properties")
       public class AppConfig {
           @Autowired
           Environment env;

           @Bean
           public TestBean testBean() {
               TestBean testBean = new TestBean();
               testBean.setName(env.getProperty("testbean.name"));
               return testBean;
           }
       }

  Assuming that "my.placeholder" is present in one of the property sources already registered, e.g. system properties or environment variables, the placeholder will be resolved to the corresponding value. If not, then "default/path" will be used as a default. Expressing a default value (delimited by colon ":") is optional. If no default is specified and a property cannot be resolved, an `IllegalArgumentException` will be thrown.

  ### A note on property overriding with @PropertySource

  In cases where a given property key exists in more than one `.properties` file, the last `@PropertySource` annotation processed will 'win' and override. For example, given two properties files `a.properties` and `b.properties`, consider the following two configuration classes that reference them with `@PropertySource` annotations:

       @Configuration
       @PropertySource("classpath:/com/myco/a.properties")
       public class ConfigA { }

       @Configuration
       @PropertySource("classpath:/com/myco/b.properties")
       public class ConfigB { }

  The override ordering depends on the order in which these classes are registered with the application context.

       AnnotationConfigApplicationContext ctx =
           new AnnotationConfigApplicationContext();
       ctx.register(ConfigA.class);
       ctx.register(ConfigB.class);
       ctx.refresh();

  In the scenario above, the properties in `b.properties` will override any duplicates that exist in `a.properties`, because `ConfigB` was registered last.

  In certain situations, it may not be possible or practical to tightly control property source ordering when using `@ProperySource` annotations. For example, if the `@Configuration` classes above were registered via component-scanning, the ordering is difficult to predict. In such cases - and if overriding is important - it is recommended that the user fall back to using the programmatic PropertySource API. See `ConfigurableEnvironment` and `MutablePropertySources` Javadoc for details.

  Since:
    3.1
  Author:
    Chris Beams
  See Also:
    `Configuration`, `PropertySource`, `ConfigurableEnvironment.getPropertySources()`, `MutablePropertySources`

- - ### Required Element Summary

    Required Elements
    Modifier and Type | Required Element and Description
    --- | ---
    `String[]` | `value` Indicate the resource location(s) of the properties file to be loaded.

  - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `String` | `name` Indicate the name of this property source.

- - ### Element Detail

    - #### value

          public abstract String[] value

      Indicate the resource location(s) of the properties file to be loaded. For example, `"classpath:/com/myco/app.properties"` or `"file:/path/to/file"`.

      Resource location wildcards (e.g. **/*.properties) are not permitted; each location must evaluate to exactly one `.properties` resource.

      ${...} placeholders will be resolved against any/all property sources already registered with the `Environment`. See above for examples.

      Each location will be added to the enclosing `Environment` as its own property source, and in the order declared.

    - #### name

          public abstract String name

      Indicate the name of this property source. If omitted, a name will be generated based on the description of the underlying resource.
      See Also:
        `PropertySource.getName()`, `Resource.getDescription()`
      Default:
        ""