Improve documentation on EnvironmentPostProcessor

Closes gh-9617

spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -115,6 +115,26 @@ refreshed using `EnvironmentPostProcessor`. Each implementation should be regist
 	org.springframework.boot.env.EnvironmentPostProcessor=com.example.YourEnvironmentPostProcessor
 ----
 
+The implementation can load arbitrary files and add them to the `Environment`. For
+instance, this example loads a YAML configuration file from the classpath:
+
+
+[source,java,indent=0]
+----
+include::{code-examples}/context/EnvironmentPostProcessorExample.java[tag=example]
+----
+
+TIP: The `Environment` will already have been prepared with all the usual property sources
+that Spring Boot loads by default. It is therefore possible to get the location of the
+file from the environment. This example adds the `custom-resource` property source at the
+end of the list so that a key defined in any of the usual other locations takes
+precedence. A custom implementation may obviously defines another order.
+
+NOTE: While using `@PropertySource` on your `@SpringBootApplication` seems convenient and
+easy enough to load a custom resource in the `Environment`, we do not recommend it as
+Spring Boot prepares the `Environment` before the `ApplicationContext` is refreshed. Any
+key defined via `@PropertySource` will be loaded too late to have any effect on
+auto-configuration.
 
 
 [[howto-build-an-application-context-hierarchy]]

spring-boot-docs/src/main/java/org/springframework/boot/context/EnvironmentPostProcessorExample.java

+/*
+ * Copyright 2012-2017 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.context;
+
+import java.io.IOException;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.env.EnvironmentPostProcessor;
+import org.springframework.boot.env.YamlPropertySourceLoader;
+import org.springframework.core.env.ConfigurableEnvironment;
+import org.springframework.core.env.PropertySource;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.core.io.Resource;
+
+/**
+ * An {@link EnvironmentPostProcessor} example that loads a YAML file.
+ *
+ * @author Stephane Nicoll
+ */
+// tag::example[]
+public class EnvironmentPostProcessorExample
+		implements EnvironmentPostProcessor {
+
+	private final YamlPropertySourceLoader loader
+			= new YamlPropertySourceLoader();
+
+	@Override
+	public void postProcessEnvironment(ConfigurableEnvironment environment,
+			SpringApplication application) {
+		Resource path = new ClassPathResource("com/example/myapp/config.yml");
+		PropertySource<?> propertySource = loadYaml(path);
+		environment.getPropertySources().addLast(propertySource);
+	}
+
+	private PropertySource<?> loadYaml(Resource path) {
+		if (!path.exists()) {
+			throw new IllegalArgumentException("Resource " + path
+					+ " does not exist");
+		}
+		try {
+			return this.loader.load("custom-resource", path, null);
+		}
+		catch (IOException ex) {
+			throw new IllegalStateException("Failed to load yaml configuration "
+					+ "from " + path, ex);
+		}
+	}
+
+}
+// end::example[]

spring-boot-docs/src/test/java/org/springframework/boot/context/EnvironmentPostProcessorExampleTests.java

+/*
+ * Copyright 2012-2017 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.context;
+
+import org.junit.Test;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.core.env.StandardEnvironment;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link EnvironmentPostProcessorExample}.
+ *
+ * @author Stephane Nicoll
+ */
+public class EnvironmentPostProcessorExampleTests {
+
+	private final StandardEnvironment environment = new StandardEnvironment();
+
+	@Test
+	public void applyEnvironmentPostProcessor() {
+		assertThat(this.environment.containsProperty("test.foo.bar")).isFalse();
+		new EnvironmentPostProcessorExample().postProcessEnvironment(
+				this.environment, new SpringApplication());
+		assertThat(this.environment.containsProperty("test.foo.bar")).isTrue();
+		assertThat(this.environment.getProperty("test.foo.bar")).isEqualTo("value");
+	}
+
+}

spring-boot-docs/src/test/resources/com/example/myapp/config.yml

+test:
+  foo:
+    bar: value
\ No newline at end of file