From dda4dfb44ba0c76ab135a1255f99857c76f1c5ed Mon Sep 17 00:00:00 2001
From: Sam Brannen <sbrannen@pivotal.io>
Date: Tue, 25 Jun 2019 10:40:55 +0300
Subject: [PATCH] Clarify semantics of the PriorityOrdered interface

This commit clarifies the semantics of the PriorityOrdered interface
with respect to sorting sets of objects containing both PriorityOrdered
and plain Ordered objects.

Closes gh-23187
---
 .../springframework/core/PriorityOrdered.java | 23 +++++++++++--------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/spring-core/src/main/java/org/springframework/core/PriorityOrdered.java b/spring-core/src/main/java/org/springframework/core/PriorityOrdered.java
index c50c6ee9f0..2090cd35f9 100644
--- a/spring-core/src/main/java/org/springframework/core/PriorityOrdered.java
+++ b/spring-core/src/main/java/org/springframework/core/PriorityOrdered.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -18,14 +18,19 @@ package org.springframework.core;
 
 /**
  * Extension of the {@link Ordered} interface, expressing a <em>priority</em>
- * ordering: order values expressed by {@code PriorityOrdered} objects
- * always apply before same order values expressed by <em>plain</em>
- * {@link Ordered} objects.
+ * ordering: {@code PriorityOrdered} objects are always applied before
+ * <em>plain</em> {@link Ordered} objects regardless of their order values.
  *
- * <p>This is primarily a special-purpose interface, used for objects where
- * it is particularly important to recognize <em>prioritized</em> objects
- * first, without even obtaining the remaining objects. A typical example:
- * prioritized post-processors in a Spring
+ * <p>When sorting a set of {@code Ordered} objects, {@code PriorityOrdered}
+ * objects and <em>plain</em> {@code Ordered} objects are effectively treated as
+ * two separate subsets, with the set of {@code PriorityOrdered} objects preceding
+ * the set of <em>plain</em> {@code Ordered} objects and with relative
+ * ordering applied within those subsets.
+ *
+ * <p>This is primarily a special-purpose interface, used within the framework
+ * itself for objects where it is particularly important to recognize
+ * <em>prioritized</em> objects first, potentially without even obtaining the
+ * remaining objects. A typical example: prioritized post-processors in a Spring
  * {@link org.springframework.context.ApplicationContext}.
  *
  * <p>Note: {@code PriorityOrdered} post-processor beans are initialized in
@@ -34,10 +39,10 @@ package org.springframework.core;
  * beans which do not require eager initialization for type matching.
  *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 2.5
  * @see org.springframework.beans.factory.config.PropertyOverrideConfigurer
  * @see org.springframework.beans.factory.config.PropertyPlaceholderConfigurer
  */
 public interface PriorityOrdered extends Ordered {
-
 }