Annotation Interface PropertySource
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:
-
Required Element Summary
-
Optional Element Summary
Modifier and TypeOptional ElementDescriptionA specific character encoding for the given resources, for example, "UTF-8".Class<? extends PropertySourceFactory>
Specify a customPropertySourceFactory
, if any.boolean
Indicate if a failure to find aproperty resource
should be ignored.Indicate the unique name of this property source.
-
Element Details
-
value
String[] valueIndicate 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 theEnvironment
. 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 nameIndicate the unique name of this property source.If omitted, the
factory()
will generate a name based on the underlying resource (in the case ofDefaultPropertySourceFactory
: derived from the resource description through a corresponding name-lessResourcePropertySource
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 (seeaddBefore()
andaddAfter()
).
- Default:
- ""
- Diagnostics: to determine the source of the properties in logging and
debugging — for example, in a Spring Boot application via Spring
Boot's
-
ignoreResourceNotFound
boolean ignoreResourceNotFoundIndicate if a failure to find aproperty resource
should be ignored.true
is appropriate if the properties file is completely optional.Default is
false
.- Since:
- 4.0
- Default:
- false
-
encoding
String encodingA specific character encoding for the given resources, for example, "UTF-8".- Since:
- 4.3
- Default:
- ""
-
factory
Class<? extends PropertySourceFactory> factorySpecify a customPropertySourceFactory
, if any.By default, a default factory for standard resource files will be used which supports
*.properties
and*.xml
file formats forProperties
.- Since:
- 4.3
- See Also:
- Default:
- org.springframework.core.io.support.PropertySourceFactory.class
-