Improve Javadoc for Ordered/@order regarding sort semantics

Author: sbrannen

spring-core/src/main/java/org/springframework/core/OrderComparator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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,23 +24,31 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * {@link Comparator} implementation for {@link Ordered} objects,
- * sorting by order value ascending (resp. by priority descending).
+ * {@link Comparator} implementation for {@link Ordered} objects, sorting
+ * by order value ascending, respectively by priority descending.
  *
- * <p>Non-{@code Ordered} objects are treated as greatest order
- * values, thus ending up at the end of the list, in arbitrary order
- * (just like same order values of {@code Ordered} objects).
+ * <h3>Same Order Objects</h3>
+ * <p>Objects that have the same order value will be sorted with arbitrary
+ * ordering with respect to other objects with the same order value.
+ *
+ * <h3>Non-ordered Objects</h3>
+ * <p>Any object that does not provide its own order value is implicitly
+ * assigned a value of {@link Ordered#LOWEST_PRECEDENCE}, thus ending up
+ * at the end of a sorted collection in arbitrary order with respect to
+ * other objects with the same order value.
  *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 07.04.2003
  * @see Ordered
+ * @see org.springframework.core.annotation.AnnotationAwareOrderComparator
  * @see java.util.Collections#sort(java.util.List, java.util.Comparator)
  * @see java.util.Arrays#sort(Object[], java.util.Comparator)
  */
 public class OrderComparator implements Comparator<Object> {
 
 	/**
-	 * Shared default instance of OrderComparator.
+	 * Shared default instance of {@code OrderComparator}.
 	 */
 	public static final OrderComparator INSTANCE = new OrderComparator();
 

spring-core/src/main/java/org/springframework/core/Ordered.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -17,21 +17,28 @@
 package org.springframework.core;
 
 /**
- * Interface that can be implemented by objects that should be
- * orderable, for example in a Collection.
+ * {@code Ordered} is an interface that can be implemented by objects that
+ * should be <em>orderable</em>, for example in a {@code Collection}.
  *
- * <p>The actual order can be interpreted as prioritization, with
- * the first object (with the lowest order value) having the highest
+ * <p>The actual {@link #getOrder() order} can be interpreted as prioritization,
+ * with the first object (with the lowest order value) having the highest
  * priority.
  *
- * <p>Note that there is a 'priority' marker for this interface:
- * {@link PriorityOrdered}. Order values expressed by PriorityOrdered
- * objects always apply before order values of 'plain' Ordered values.
+ * <p>Note that there is also a <em>priority</em> marker for this interface:
+ * {@link PriorityOrdered}. Order values expressed by {@code PriorityOrdered}
+ * objects always apply before same order values expressed by <em>plain</em>
+ * {@link Ordered} objects.
+ *
+ * <p>Consult the Javadoc for {@link OrderComparator} for details on the
+ * sort semantics for non-ordered objects.
  *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 07.04.2003
+ * @see PriorityOrdered
  * @see OrderComparator
  * @see org.springframework.core.annotation.Order
+ * @see org.springframework.core.annotation.AnnotationAwareOrderComparator
  */
 public interface Ordered {
 
@@ -49,15 +56,15 @@ public interface Ordered {
 
 
 	/**
-	 * Return the order value of this object, with a
-	 * higher value meaning greater in terms of sorting.
-	 * <p>Normally starting with 0, with {@code Integer.MAX_VALUE}
-	 * indicating the greatest value. Same order values will result
-	 * in arbitrary positions for the affected objects.
-	 * <p>Higher values can be interpreted as lower priority. As a
-	 * consequence, the object with the lowest value has highest priority
-	 * (somewhat analogous to Servlet "load-on-startup" values).
+	 * Get the order value of this object.
+	 * <p>Higher values are interpreted as lower priority. As a consequence,
+	 * the object with the lowest value has the highest priority (somewhat
+	 * analogous to Servlet {@code load-on-startup} values).
+	 * <p>Same order values will result in arbitrary sort positions for the
+	 * affected objects.
 	 * @return the order value
+	 * @see #HIGHEST_PRECEDENCE
+	 * @see #LOWEST_PRECEDENCE
 	 */
 	int getOrder();
 

spring-core/src/main/java/org/springframework/core/PriorityOrdered.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2009 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -17,19 +17,20 @@
 package org.springframework.core;
 
 /**
- * Extension of the {@link Ordered} interface, expressing a 'priority'
- * ordering: Order values expressed by PriorityOrdered objects always
- * apply before order values of 'plain' Ordered values.
+ * 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.
  *
- * <p>This is primarily a special-purpose interface, used for objects
- * where it is particularly important to determine 'prioritized'
- * objects first, without even obtaining the remaining objects.
- * A typical example: Prioritized post-processors in a Spring
+ * <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
  * {@link org.springframework.context.ApplicationContext}.
  *
- * <p>Note: PriorityOrdered post-processor beans are initialized in
+ * <p>Note: {@code PriorityOrdered} post-processor beans are initialized in
  * a special phase, ahead of other post-processor beans. This subtly
- * affects their autowiring behavior: They will only be autowired against
+ * affects their autowiring behavior: they will only be autowired against
  * beans which do not require eager initialization for type matching.
  *
  * @author Juergen Hoeller

spring-core/src/main/java/org/springframework/core/annotation/AnnotationAwareOrderComparator.java

@@ -25,12 +25,16 @@
 import org.springframework.core.OrderComparator;
 
 /**
- * {@link java.util.Comparator} implementation that checks Spring's
+ * {@code AnnotationAwareOrderComparator} is an extension of
+ * {@link OrderComparator} that supports Spring's
  * {@link org.springframework.core.Ordered} interface as well as the
  * {@link Order @Order} and {@link javax.annotation.Priority @Priority}
  * annotations, with an order value provided by an {@code Ordered}
  * instance overriding a statically defined annotation value (if any).
  *
+ * <p>Consult the Javadoc for {@link OrderComparator} for details on the
+ * sort semantics for non-ordered objects.
+ *
  * @author Juergen Hoeller
  * @author Oliver Gierke
  * @author Stephane Nicoll
@@ -42,15 +46,16 @@
 public class AnnotationAwareOrderComparator extends OrderComparator {
 
 	/**
-	 * Shared default instance of AnnotationAwareOrderComparator.
+	 * Shared default instance of {@code AnnotationAwareOrderComparator}.
 	 */
 	public static final AnnotationAwareOrderComparator INSTANCE = new AnnotationAwareOrderComparator();
 
 
 	/**
-	 * This implementation checks for the {@link Order} annotation
-	 * on various kinds of elements, in addition to the
-	 * {@link org.springframework.core.Ordered} check in the superclass.
+	 * This implementation checks for {@link Order @Order} or
+	 * {@link javax.annotation.Priority @Priority} on various kinds of
+	 * elements, in addition to the {@link org.springframework.core.Ordered}
+	 * check in the superclass.
 	 */
 	protected Integer findOrder(Object obj) {
 		// Check for regular Ordered interface
@@ -59,7 +64,7 @@ protected Integer findOrder(Object obj) {
 			return order;
 		}
 
-		// Check for @Order annotation on various kinds of elements
+		// Check for @Order and @Priority on various kinds of elements
 		if (obj instanceof Class) {
 			return OrderUtils.getOrder((Class<?>) obj);
 		}

spring-core/src/main/java/org/springframework/core/annotation/Order.java

@@ -25,18 +25,24 @@
 import org.springframework.core.Ordered;
 
 /**
- * Annotation that defines ordering. The value is optional, and represents order value
- * as defined in the {@link Ordered} interface. Lower values have higher priority.
- * The default value is {@code Ordered.LOWEST_PRECEDENCE}, indicating
+ * {@code @Order} defines the sort order for an annotated component.
+ *
+ * <p>The {@link #value} is optional and represents an order value as defined
+ * in the {@link Ordered} interface. Lower values have higher priority. The
+ * default value is {@code Ordered.LOWEST_PRECEDENCE}, indicating
  * lowest priority (losing to any other specified order value).
  *
- * <p>Since Spring 4.1, the standard {@link javax.annotation.Priority} can be used as
- * a drop-in replacement of this annotation.
+ * <p>Since Spring 4.1, the standard {@link javax.annotation.Priority}
+ * annotation can be used as a drop-in replacement for this annotation.
+ *
+ * <p><b>NOTE</b>: Annotation-based ordering is supported for specific kinds
+ * of components only &mdash; for example, for annotation-based AspectJ
+ * aspects. Ordering strategies within the Spring container, on the other
+ * hand, are typically based on the {@link Ordered} interface in order to
+ * allow for programmatically configurable ordering of each <i>instance</i>.
  *
- * <p><b>NOTE:</b> Annotation-based ordering is supported for specific kinds of
- * components only, e.g. for annotation-based AspectJ aspects. Spring container
- * strategies, on the other hand, are typically based on the {@link Ordered}
- * interface in order to allow for configurable ordering of each <i>instance</i>.
+ * <p>Consult the Javadoc for {@link org.springframework.core.OrderComparator
+ * OrderComparator} for details on the sort semantics for non-ordered objects.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller
@@ -52,7 +58,8 @@
 public @interface Order {
 
 	/**
-	 * The order value. Default is {@link Ordered#LOWEST_PRECEDENCE}.
+	 * The order value.
+	 * <p>Default is {@link Ordered#LOWEST_PRECEDENCE}.
 	 * @see Ordered#getOrder()
 	 */
 	int value() default Ordered.LOWEST_PRECEDENCE;