Improve documentation on EnvironmentPostProcessor

Closes gh-9617

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

@@ -0,0 +1,64 @@
+/*
+ * 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[]