diff --git a/spring-core/src/main/java/org/springframework/core/OrderComparator.java b/spring-core/src/main/java/org/springframework/core/OrderComparator.java index 2a9970b9d9c..0a121dd2278 100644 --- a/spring-core/src/main/java/org/springframework/core/OrderComparator.java +++ b/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 java.util.List; 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. * - *

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). + *

Same Order Objects

+ *

Objects that have the same order value will be sorted with arbitrary + * ordering with respect to other objects with the same order value. + * + *

Non-ordered Objects

+ *

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 { /** - * Shared default instance of OrderComparator. + * Shared default instance of {@code OrderComparator}. */ public static final OrderComparator INSTANCE = new OrderComparator(); diff --git a/spring-core/src/main/java/org/springframework/core/Ordered.java b/spring-core/src/main/java/org/springframework/core/Ordered.java index fcabe86a243..2a328ea2ee0 100644 --- a/spring-core/src/main/java/org/springframework/core/Ordered.java +++ b/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 orderable, for example in a {@code Collection}. * - *

The actual order can be interpreted as prioritization, with - * the first object (with the lowest order value) having the highest + *

The actual {@link #getOrder() order} can be interpreted as prioritization, + * with the first object (with the lowest order value) having the highest * priority. * - *

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. + *

Note that there is also a priority marker for this interface: + * {@link PriorityOrdered}. Order values expressed by {@code PriorityOrdered} + * objects always apply before same order values expressed by plain + * {@link Ordered} objects. + * + *

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. - *

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. - *

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. + *

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). + *

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(); 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 1ab51087450..c8fc54b5333 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-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 priority + * ordering: order values expressed by {@code PriorityOrdered} objects + * always apply before same order values expressed by plain + * {@link Ordered} objects. * - *

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 + *

This is primarily a special-purpose interface, used for objects where + * it is particularly important to recognize prioritized objects + * first, without even obtaining the remaining objects. A typical example: + * prioritized post-processors in a Spring * {@link org.springframework.context.ApplicationContext}. * - *

Note: PriorityOrdered post-processor beans are initialized in + *

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 diff --git a/spring-core/src/main/java/org/springframework/core/annotation/AnnotationAwareOrderComparator.java b/spring-core/src/main/java/org/springframework/core/annotation/AnnotationAwareOrderComparator.java index d2295bb7dd5..beecd919dec 100644 --- a/spring-core/src/main/java/org/springframework/core/annotation/AnnotationAwareOrderComparator.java +++ b/spring-core/src/main/java/org/springframework/core/annotation/AnnotationAwareOrderComparator.java @@ -25,12 +25,16 @@ import java.util.List; 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). * + *

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 @@ import org.springframework.core.OrderComparator; 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 @@ public class AnnotationAwareOrderComparator extends OrderComparator { 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); } diff --git a/spring-core/src/main/java/org/springframework/core/annotation/Order.java b/spring-core/src/main/java/org/springframework/core/annotation/Order.java index 36af2ff7a77..2f0612ef8dc 100644 --- a/spring-core/src/main/java/org/springframework/core/annotation/Order.java +++ b/spring-core/src/main/java/org/springframework/core/annotation/Order.java @@ -25,18 +25,24 @@ import java.lang.annotation.Target; 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. + * + *

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). * - *

Since Spring 4.1, the standard {@link javax.annotation.Priority} can be used as - * a drop-in replacement of this annotation. + *

Since Spring 4.1, the standard {@link javax.annotation.Priority} + * annotation can be used as a drop-in replacement for this annotation. * - *

NOTE: 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 instance. + *

NOTE: Annotation-based ordering is supported for specific kinds + * of components only — 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 instance. + * + *

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 @@ import org.springframework.core.Ordered; public @interface Order { /** - * The order value. Default is {@link Ordered#LOWEST_PRECEDENCE}. + * The order value. + *

Default is {@link Ordered#LOWEST_PRECEDENCE}. * @see Ordered#getOrder() */ int value() default Ordered.LOWEST_PRECEDENCE;