From 06aa35b9da1d4624060f21c9648bf0ef4a940ba7 Mon Sep 17 00:00:00 2001
From: Stephane Nicoll <snicoll@pivotal.io>
Date: Mon, 20 Jun 2016 15:29:38 +0200
Subject: [PATCH] Clarify usage of EnvironmentPostProcessor

Closes gh-6101
---
 spring-boot-docs/src/main/asciidoc/howto.adoc        |  9 +++++++++
 .../boot/env/EnvironmentPostProcessor.java           | 12 +++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-docs/src/main/asciidoc/howto.adoc
index 35febac3980..b22aadb2c55 100644
--- a/spring-boot-docs/src/main/asciidoc/howto.adoc
+++ b/spring-boot-docs/src/main/asciidoc/howto.adoc
@@ -82,6 +82,15 @@ by the `ApplicationContext` as well. See
 _<<spring-boot-features.adoc#boot-features-application-events-and-listeners>>_ in the
 '`Spring Boot features`' section for a complete list.
 
+It is also possible to customize the `Environment` before the application context is
+refreshed using `EnvironmentPostProcessor`. Each implementation should be registered in
+`META-INF/spring.factories`:
+
+[source,properties,indent=0]
+----
+	org.springframework.boot.env.EnvironmentPostProcessor=com.example.YourEnvironmentPostProcessor
+----
+
 
 
 [[howto-build-an-application-context-hierarchy]]
diff --git a/spring-boot/src/main/java/org/springframework/boot/env/EnvironmentPostProcessor.java b/spring-boot/src/main/java/org/springframework/boot/env/EnvironmentPostProcessor.java
index bacc87655e2..030995ffa3d 100644
--- a/spring-boot/src/main/java/org/springframework/boot/env/EnvironmentPostProcessor.java
+++ b/spring-boot/src/main/java/org/springframework/boot/env/EnvironmentPostProcessor.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2015 the original author or authors.
+ * Copyright 2012-2016 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,17 @@ import org.springframework.core.env.Environment;
  * Allows for customization of the application's {@link Environment} prior to the
  * application context being refreshed.
  *
+ * <p>EnvironmentPostProcessor implementations have to be registered in
+ * {@code META-INF/spring.factories}, using the fully qualified name of this
+ * class as the key.
+ *
+ * <p>{@code EnvironmentPostProcessor} processors are encouraged to detect
+ * whether Spring's {@link org.springframework.core.Ordered Ordered} interface has been
+ * implemented or if the @{@link org.springframework.core.annotation.Order Order}
+ * annotation is present and to sort instances accordingly if so prior to invocation.
+ *
  * @author Andy Wilkinson
+ * @author Stephane Nicoll
  * @since 1.3.0
  */
 public interface EnvironmentPostProcessor {