Improve Javadoc for Ordered/@Order regarding sort semantics
This commit is contained in:
Sam Brannen
parent
a07ba695b0
commit
1ff3af6da3
|
|
@ -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.
|
||||
*
|
||||
* <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();
|
||||
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
*
|
||||
* <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 @@ 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);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
*
|
||||
* <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, 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><b>NOTE</b>: 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 <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 @@ import org.springframework.core.Ordered;
|
|||
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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue