Package org.springframework.context.annotation

Annotation Interface PropertySource

@Target(TYPE) @Retention(RUNTIME) @Documented @Repeatable(PropertySources.class) 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, you must ensure that an appropriate embedded value resolver is registered in the BeanFactory used by the ApplicationContext. This happens automatically when using <context:property-placeholder> in XML. When using @Configuration classes this can be achieved by explicitly registering a PropertySourcesPlaceholderConfigurer via a static @Bean method. Note, however, that explicit registration of a PropertySourcesPlaceholderConfigurer via a static @Bean method is typically only required if you need to customize configuration such as the placeholder syntax, etc. See the "Working with externalized values" section of @Configuration's javadocs and "a note on BeanFactoryPostProcessor-returning @Bean methods" of @Bean's javadocs 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 — for example, 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 property resource file, the last @PropertySource annotation processed will 'win' and override any previous key with the same name.

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 @PropertySource 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 javadocs for details.

@PropertySource can be used as a repeatable annotation. @PropertySource may also be used as a meta-annotation to create custom composed annotations with attribute overrides.

Since:
3.1
Author:
Chris Beams, Juergen Hoeller, Phillip Webb, Sam Brannen
See Also:

  • Element Details

    • value

      String[] value
      Indicate the resource locations of the properties files to be loaded.

      The default factory supports both traditional and XML-based properties file formats — for example, "classpath:/com/myco/app.properties" or "file:/path/to/file.xml".

      As of Spring Framework 6.1, resource location wildcards are also supported — for example, "classpath*:/config/*.properties".

      ${...} placeholders will be resolved against 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 (or in the order in which resource locations are resolved when location wildcards are used).

    • name

      String name
      Indicate the unique name of this property source.

      If omitted, the factory() will generate a name based on the underlying resource (in the case of DefaultPropertySourceFactory: derived from the resource description through a corresponding name-less ResourcePropertySource constructor).

      The name of a PropertySource serves two general purposes.

      • Diagnostics: to determine the source of the properties in logging and debugging — for example, in a Spring Boot application via Spring Boot's PropertySourceOrigin.
      • Programmatic interaction with MutablePropertySources: the name can be used to retrieve properties from a particular property source (or to determine if a particular named property source already exists). The name can also be used to add a new property source relative to an existing property source (see addBefore() and addAfter()).
      See Also:
      Default:
      ""

    • ignoreResourceNotFound

      boolean ignoreResourceNotFound
      Indicate if a failure to find a property resource should be ignored.

      true is appropriate if the properties file is completely optional.

      Default is false.

      Since:
      4.0
      Default:
      false

    • encoding

      String encoding
      A specific character encoding for the given resources, e.g. "UTF-8".
      Since:
      4.3
      Default:
      ""

    • factory

      Class<? extends PropertySourceFactory> factory
      Specify a custom PropertySourceFactory, if any.

      By default, a default factory for standard resource files will be used which supports *.properties and *.xml file formats for Properties.

      Since:
      4.3
      See Also:
      Default:
      org.springframework.core.io.support.PropertySourceFactory.class