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:
  - `PropertySources`
  - `Configuration`
  - `PropertySource`
  - `ConfigurableEnvironment.getPropertySources()`
  - `MutablePropertySources`

## Required Element Summary

Required Elements
Modifier and Type
Required Element
Description
`String[]`
`value`
Indicate the resource locations of the properties files to be loaded.

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
Description
`String`
`encoding`
A specific character encoding for the given resources, for example, "UTF-8".
`Class<? extends org.springframework.core.io.support.PropertySourceFactory>`
`factory`
Specify a custom `PropertySourceFactory`, if any.
`boolean`
`ignoreResourceNotFound`
Indicate if a failure to find a `property resource` should be ignored.
`String`
`name`
Indicate the unique name of this property source.

## 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:
  - `PropertySource.getName()`
  - `Resource.getDescription()`

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, for example, "UTF-8".

Since:
  4.3

Default:
  ""

### factory

Class<? extends org.springframework.core.io.support.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:
  - `DefaultPropertySourceFactory`
  - `ResourcePropertySource`

Default:
  org.springframework.core.io.support.PropertySourceFactory.class