Re-introduce system-properties-mode to spring-context 3.1 XSD

See JIRA issue for complete details.

Issue: SPR-8901

Author: cbeams

org.springframework.context/src/main/java/org/springframework/context/config/PropertyPlaceholderBeanDefinitionParser.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2010 the original author or authors.
+ * Copyright 2002-2011 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@
 import org.springframework.util.StringUtils;
 
 /**
- * Parser for the <context:property-placeholder/> element.
+ * Parser for the {@code <context:property-placeholder/>} element.
  *
  * @author Juergen Hoeller
  * @author Dave Syer
@@ -33,13 +33,22 @@
  */
 class PropertyPlaceholderBeanDefinitionParser extends AbstractPropertyLoadingBeanDefinitionParser {
 
+	private static final String SYSTEM_PROPERTIES_MODE_ATTRIB = "system-properties-mode";
+	private static final String SYSTEM_PROPERTIES_MODE_DEFAULT = "ENVIRONMENT";
+
 	@Override
 	protected Class<?> getBeanClass(Element element) {
-		if (element.hasAttribute("system-properties-mode")) {
-			return PropertyPlaceholderConfigurer.class;
+		// As of Spring 3.1, the default value of system-properties-mode has changed from
+		// 'FALLBACK' to 'ENVIRONMENT'. This latter value indicates that resolution of
+		// placeholders against system properties is a function of the Environment and
+		// its current set of PropertySources
+		if (element.getAttribute(SYSTEM_PROPERTIES_MODE_ATTRIB).equals(SYSTEM_PROPERTIES_MODE_DEFAULT)) {
+			return PropertySourcesPlaceholderConfigurer.class;
 		}
 
-		return PropertySourcesPlaceholderConfigurer.class;
+		// the user has explicitly specified a value for system-properties-mode. Revert
+		// to PropertyPlaceholderConfigurer to ensure backward compatibility.
+		return PropertyPlaceholderConfigurer.class;
 	}
 
 	@Override
@@ -49,8 +58,9 @@ protected void doParse(Element element, BeanDefinitionBuilder builder) {
 		builder.addPropertyValue("ignoreUnresolvablePlaceholders",
 				Boolean.valueOf(element.getAttribute("ignore-unresolvable")));
 
-		String systemPropertiesModeName = element.getAttribute("system-properties-mode");
-		if (StringUtils.hasLength(systemPropertiesModeName)) {
+		String systemPropertiesModeName = element.getAttribute(SYSTEM_PROPERTIES_MODE_ATTRIB);
+		if (StringUtils.hasLength(systemPropertiesModeName) &&
+				!systemPropertiesModeName.equals(SYSTEM_PROPERTIES_MODE_DEFAULT)) {
 			builder.addPropertyValue("systemPropertiesModeName", "SYSTEM_PROPERTIES_MODE_"+systemPropertiesModeName);
 		}
 	}

org.springframework.context/src/main/java/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.java

@@ -34,13 +34,30 @@
 import org.springframework.util.StringValueResolver;
 
 /**
- * Specialization of {@link org.springframework.beans.factory.config.PlaceholderConfigurerSupport}
+ * Specialization of {@link org.springframework.beans.factory.config.PlaceholderConfigurerSupport
+ * PlaceholderConfigurerSupport} that resolves ${...} placeholders within bean definition
+ * property values and {@code @Value} annotations against the current Spring {@link
+ * Environment} and its set of {@link PropertySources}.
  *
- * <p>Local properties are added as a property source in any case. Precedence is based
- * on the value of the {@link #setLocalOverride localOverride} property.
+ * <p>This class is designed as a general replacement for {@code
+ * PropertyPlaceholderConfigurer} in Spring 3.1 applications. It is used by default to
+ * support the {@code property-placeholder} element in working against the
+ * spring-context-3.1 XSD, whereas spring-context versions &lt;= 3.0 default to
+ * {@code PropertyPlaceholderConfigurer} to ensure backward compatibility. See
+ * spring-context XSD documentation for complete details.
+ *
+ * <p>Any local properties (e.g. those added via {@link #setProperties},
+ * {@link #setLocations} et al.) are added as a {@code PropertySource}. Search precedence
+ * of local properties is based on the value of the {@link #setLocalOverride localOverride}
+ * property, which is by default {@code false} meaning that local properties are to be
+ * searched last, after all environment property sources.
+ *
+ * <p>See {@link org.springframework.core.env.ConfigurableEnvironment ConfigurableEnvironment}
+ * and related Javadoc for details on manipulating environment property sources.
  *
  * @author Chris Beams
  * @since 3.1
+ * @see org.springframework.core.env.ConfigurableEnvironment
  * @see org.springframework.beans.factory.config.PlaceholderConfigurerSupport
  * @see org.springframework.beans.factory.config.PropertyPlaceholderConfigurer
  */

org.springframework.context/src/main/resources/org/springframework/context/config/spring-context-3.1.xsd

@@ -89,10 +89,20 @@
 	<xsd:element name="property-placeholder">
 		<xsd:annotation>
 			<xsd:documentation><![CDATA[
-	Activates replacement of ${...} placeholders, resolved against the specified properties file or
-	Properties object (if any). Defines a PropertySourcesPlaceholderConfigurer within the context.
-	For backward compatibility with versions earlier than Spring 3.1, a PropertyPlaceholderConfigurer will be
-	registered if the 'system-properties-mode' attribute has been explicitly assigned a value.
+	Activates replacement of ${...} placeholders by registering a
+	PropertySourcesPlaceholderConfigurer within the application context. Properties will
+	be resolved against the specified properties file or Properties object -- so called
+	"local properties", if any, and against the Spring Environment's current set of
+	PropertySources.
+
+	Note that as of Spring 3.1 the system-properties-mode attribute has been removed in
+	favor of the more flexible PropertySources mechanism. However, Spring 3.1-based
+	applications may continue to use the 3.0 (and older) versions of the spring-context
+	schema in order to preserve system-properties-mode behavior. In this case, the
+	traditional PropertyPlaceholderConfigurer component will be registered instead of the
+	new PropertySourcesPlaceholderConfigurer.
+
+	See ConfigurableEnvironment Javadoc for more information on using.
 			]]></xsd:documentation>
 			<xsd:appinfo>
 				<tool:annotation>
@@ -103,7 +113,39 @@
 		</xsd:annotation>
 		<xsd:complexType>
 			<xsd:complexContent>
-				<xsd:extension base="propertyPlaceholder" />
+				<xsd:extension base="propertyPlaceholder">
+					<xsd:attribute name="system-properties-mode" default="ENVIRONMENT">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+	Controls how to resolve placeholders against system properties. As of Spring 3.1, this
+	attribute value defaults to "ENVIRONMENT", indicating that resolution of placeholders
+	against system properties is handled via PropertySourcesPlaceholderConfigurer and its
+	delegation to the current Spring Environment object.
+
+	For maximum backward compatibility, this attribute is preserved going forward with the
+	3.1 version of the context schema, and any values other than the default "ENVIRONMENT"
+	will cause a traditional PropertyPlaceholderConfigurer to be registered instead of the
+	newer PropertySourcesPlaceholderConfigurer variant. In this case, the Spring Environment
+	and its property sources are not interrogated when resolving placeholders. Users are
+	encouraged to consider this attribute deprecated, and to take advantage of
+	Environment/PropertySource mechanisms. See ConfigurableEnvironment Javadoc for examples.
+
+	"ENVIRONMENT" indicates placeholders should be resolved against the current Environment and against any local properties;
+	"NEVER" indicates placeholders should be resolved only against local properties and never against system properties;
+	"FALLBACK" indicates placeholders should be resolved against any local properties and then against system properties;
+	"OVERRIDE" indicates placeholders should be resolved first against system properties and then against any local properties;
+							]]></xsd:documentation>
+						</xsd:annotation>
+						<xsd:simpleType>
+							<xsd:restriction base="xsd:string">
+								<xsd:enumeration value="ENVIRONMENT"/>
+								<xsd:enumeration value="NEVER"/>
+								<xsd:enumeration value="FALLBACK"/>
+								<xsd:enumeration value="OVERRIDE"/>
+							</xsd:restriction>
+						</xsd:simpleType>
+					</xsd:attribute>
+				</xsd:extension>
 			</xsd:complexContent>
 		</xsd:complexType>
 	</xsd:element>
@@ -360,10 +402,6 @@
 	Signals the current application context to apply dependency injection
 	to non-managed classes that are instantiated outside of the Spring bean
 	factory (typically classes annotated with the @Configurable annotation).
-
-	See Javadoc for org.springframework.context.annotation.EnableSpringConfigured in the
-	spring-aspects module for information on code-based alternatives to bootstrapping
-	this functionality.
 			]]></xsd:documentation>
 		</xsd:annotation>
 		<xsd:simpleType>

org.springframework.context/src/test/resources/org/springframework/context/config/contextNamespaceHandlerTests-system.xml

@@ -3,7 +3,7 @@
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context"
 	xmlns:util="http://www.springframework.org/schema/util"
 	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
-				http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd
+				http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.1.xsd
 				http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.5.xsd">
 
 	<util:properties id="placeholderProps">