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

org.springframework.beans.factory.config

## Class PropertyPlaceholderConfigurer

- java.lang.Object
- - org.springframework.core.io.support.PropertiesLoaderSupport
  - - org.springframework.beans.factory.config.PropertyResourceConfigurer
    - - org.springframework.beans.factory.config.PlaceholderConfigurerSupport
      - - org.springframework.beans.factory.config.PropertyPlaceholderConfigurer

- All Implemented Interfaces:
    Aware, BeanFactoryAware, BeanNameAware, BeanFactoryPostProcessor, Ordered, PriorityOrdered
  Direct Known Subclasses:
    PreferencesPlaceholderConfigurer, ServletContextPropertyPlaceholderConfigurer

      public class PropertyPlaceholderConfigurer
      extends PlaceholderConfigurerSupport

  `PlaceholderConfigurerSupport` subclass that resolves ${...} placeholders against `local` `properties` and/or system properties and environment variables.

  As of Spring 3.1, `PropertySourcesPlaceholderConfigurer` should be used preferentially over this implementation; it is more flexible through taking advantage of the `Environment` and `PropertySource` mechanisms also made available in Spring 3.1.

  `PropertyPlaceholderConfigurer` is still appropriate for use when:

  - the `spring-context` module is not available (i.e., one is using Spring's `BeanFactory` API as opposed to `ApplicationContext`).
  - existing configuration makes use of the `"systemPropertiesMode"` and/or `"systemPropertiesModeName"` properties. Users are encouraged to move away from using these settings, and rather configure property source search order through the container's `Environment`; however, exact preservation of functionality may be maintained by continuing to use `PropertyPlaceholderConfigurer`.

  Prior to Spring 3.1, the `<context:property-placeholder/>` namespace element registered an instance of `PropertyPlaceholderConfigurer`. It will still do so if using the `spring-context-3.0.xsd` definition of the namespace. That is, you can preserve registration of `PropertyPlaceholderConfigurer` through the namespace, even if using Spring 3.1; simply do not update your `xsi:schemaLocation` and continue using the 3.0 XSD.

  Since:
    02.10.2003
  Author:
    Juergen Hoeller, Chris Beams
  See Also:
    `setSystemPropertiesModeName(java.lang.String)`, `PlaceholderConfigurerSupport`, `PropertyOverrideConfigurer`, `PropertySourcesPlaceholderConfigurer`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `SYSTEM_PROPERTIES_MODE_FALLBACK` Check system properties if not resolvable in the specified properties.
    `static int` | `SYSTEM_PROPERTIES_MODE_NEVER` Never check system properties.
    `static int` | `SYSTEM_PROPERTIES_MODE_OVERRIDE` Check system properties first, before trying the specified properties.

    - ### Fields inherited from class org.springframework.beans.factory.config.PlaceholderConfigurerSupport

      `DEFAULT_PLACEHOLDER_PREFIX, DEFAULT_PLACEHOLDER_SUFFIX, DEFAULT_VALUE_SEPARATOR, ignoreUnresolvablePlaceholders, nullValue, placeholderPrefix, placeholderSuffix, valueSeparator`

    - ### Fields inherited from class org.springframework.core.io.support.PropertiesLoaderSupport

      `localOverride, localProperties, logger`

    - ### Fields inherited from interface org.springframework.core.Ordered

      `HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PropertyPlaceholderConfigurer()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected String` | `parseStringValue(String strVal, Properties props, Set<?> visitedPlaceholders)` Deprecated. as of Spring 3.0, in favor of using `resolvePlaceholder(java.lang.String, java.util.Properties, int)` with `PropertyPlaceholderHelper`. Only retained for compatibility with Spring 2.5 extensions.
    `protected void` | `processProperties(ConfigurableListableBeanFactory beanFactoryToProcess, Properties props)` Visit each bean definition in the given bean factory and attempt to replace ${...} property placeholders with values from the given properties.
    `protected String` | `resolvePlaceholder(String placeholder, Properties props)` Resolve the given placeholder using the given properties.
    `protected String` | `resolvePlaceholder(String placeholder, Properties props, int systemPropertiesMode)` Resolve the given placeholder using the given properties, performing a system properties check according to the given mode.
    `protected String` | `resolveSystemProperty(String key)` Resolve the given key as JVM system property, and optionally also as system environment variable if no matching system property has been found.
    `void` | `setSearchSystemEnvironment(boolean searchSystemEnvironment)` Set whether to search for a matching system environment variable if no matching system property has been found.
    `void` | `setSystemPropertiesMode(int systemPropertiesMode)` Set how to check system properties: as fallback, as override, or never.
    `void` | `setSystemPropertiesModeName(String constantName)` Set the system property mode by the name of the corresponding constant, e.g.

    - ### Methods inherited from class org.springframework.beans.factory.config.PlaceholderConfigurerSupport

      `doProcessProperties, setBeanFactory, setBeanName, setIgnoreUnresolvablePlaceholders, setNullValue, setPlaceholderPrefix, setPlaceholderSuffix, setValueSeparator`

    - ### Methods inherited from class org.springframework.beans.factory.config.PropertyResourceConfigurer

      `convertProperties, convertProperty, convertPropertyValue, getOrder, postProcessBeanFactory, setOrder`

    - ### Methods inherited from class org.springframework.core.io.support.PropertiesLoaderSupport

      `loadProperties, mergeProperties, setFileEncoding, setIgnoreResourceNotFound, setLocalOverride, setLocation, setLocations, setProperties, setPropertiesArray, setPropertiesPersister`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SYSTEM_PROPERTIES_MODE_NEVER

          public static final int SYSTEM_PROPERTIES_MODE_NEVER

      Never check system properties.
      See Also:
        Constant Field Values

    - #### SYSTEM_PROPERTIES_MODE_FALLBACK

          public static final int SYSTEM_PROPERTIES_MODE_FALLBACK

      Check system properties if not resolvable in the specified properties. This is the default.
      See Also:
        Constant Field Values

    - #### SYSTEM_PROPERTIES_MODE_OVERRIDE

          public static final int SYSTEM_PROPERTIES_MODE_OVERRIDE

      Check system properties first, before trying the specified properties. This allows system properties to override any other property source.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PropertyPlaceholderConfigurer

          public PropertyPlaceholderConfigurer()

  - ### Method Detail

    - #### setSystemPropertiesModeName

          public void setSystemPropertiesModeName(String constantName)
                                           throws IllegalArgumentException

      Set the system property mode by the name of the corresponding constant, e.g. "SYSTEM_PROPERTIES_MODE_OVERRIDE".
      Parameters:
        `constantName` - name of the constant
      Throws:
        `IllegalArgumentException` - if an invalid constant was specified
      See Also:
        `setSystemPropertiesMode(int)`

    - #### setSystemPropertiesMode

          public void setSystemPropertiesMode(int systemPropertiesMode)

      Set how to check system properties: as fallback, as override, or never. For example, will resolve ${user.dir} to the "user.dir" system property.

      The default is "fallback": If not being able to resolve a placeholder with the specified properties, a system property will be tried. "override" will check for a system property first, before trying the specified properties. "never" will not check system properties at all.

      See Also:
        `SYSTEM_PROPERTIES_MODE_NEVER`, `SYSTEM_PROPERTIES_MODE_FALLBACK`, `SYSTEM_PROPERTIES_MODE_OVERRIDE`, `setSystemPropertiesModeName(java.lang.String)`

    - #### setSearchSystemEnvironment

          public void setSearchSystemEnvironment(boolean searchSystemEnvironment)

      Set whether to search for a matching system environment variable if no matching system property has been found. Only applied when "systemPropertyMode" is active (i.e. "fallback" or "override"), right after checking JVM system properties.

      Default is "true". Switch this setting off to never resolve placeholders against system environment variables. Note that it is generally recommended to pass external values in as JVM system properties: This can easily be achieved in a startup script, even for existing environment variables.

      NOTE: Access to environment variables does not work on the Sun VM 1.4, where the corresponding `System.getenv(java.lang.String)` support was disabled - before it eventually got re-enabled for the Sun VM 1.5. Please upgrade to 1.5 (or higher) if you intend to rely on the environment variable support.

      See Also:
        `setSystemPropertiesMode(int)`, `System.getProperty(String)`, `System.getenv(String)`

    - #### resolvePlaceholder

          protected String resolvePlaceholder(String placeholder,
                                  Properties props,
                                  int systemPropertiesMode)

      Resolve the given placeholder using the given properties, performing a system properties check according to the given mode.

      The default implementation delegates to `resolvePlaceholder (placeholder, props)` before/after the system properties check.

      Subclasses can override this for custom resolution strategies, including customized points for the system properties check.

      Parameters:
        `placeholder` - the placeholder to resolve
        `props` - the merged properties of this configurer
        `systemPropertiesMode` - the system properties mode, according to the constants in this class
      Returns:
        the resolved value, of null if none
      See Also:
        `setSystemPropertiesMode(int)`, `System.getProperty(java.lang.String)`, `resolvePlaceholder(String, java.util.Properties)`

    - #### resolvePlaceholder

          protected String resolvePlaceholder(String placeholder,
                                  Properties props)

      Resolve the given placeholder using the given properties. The default implementation simply checks for a corresponding property key.

      Subclasses can override this for customized placeholder-to-key mappings or custom resolution strategies, possibly just using the given properties as fallback.

      Note that system properties will still be checked before respectively after this method is invoked, according to the system properties mode.

      Parameters:
        `placeholder` - the placeholder to resolve
        `props` - the merged properties of this configurer
      Returns:
        the resolved value, of `null` if none
      See Also:
        `setSystemPropertiesMode(int)`

    - #### resolveSystemProperty

          protected String resolveSystemProperty(String key)

      Resolve the given key as JVM system property, and optionally also as system environment variable if no matching system property has been found.
      Parameters:
        `key` - the placeholder to resolve as system property key
      Returns:
        the system property value, or `null` if not found
      See Also:
        `setSearchSystemEnvironment(boolean)`, `System.getProperty(String)`, `System.getenv(String)`

    - #### processProperties

          protected void processProperties(ConfigurableListableBeanFactory beanFactoryToProcess,
                               Properties props)
                                    throws BeansException

      Visit each bean definition in the given bean factory and attempt to replace ${...} property placeholders with values from the given properties.
      Specified by:
        `processProperties` in class `PropertyResourceConfigurer`
      Parameters:
        `beanFactoryToProcess` - the BeanFactory used by the application context
        `props` - the Properties to apply
      Throws:
        `BeansException` - in case of errors

    - #### parseStringValue

          @Deprecated
          protected String parseStringValue(String strVal,
                                           Properties props,
                                           Set<?> visitedPlaceholders)

      Deprecated. as of Spring 3.0, in favor of using `resolvePlaceholder(java.lang.String, java.util.Properties, int)` with `PropertyPlaceholderHelper`. Only retained for compatibility with Spring 2.5 extensions.
      Parse the given String value for placeholder resolution.
      Parameters:
        `strVal` - the String value to parse
        `props` - the Properties to resolve placeholders against
        `visitedPlaceholders` - the placeholders that have already been visited during the current resolution attempt (ignored in this version of the code)