From 529125898a7f1cba23d3bbbc4cd7d7e994c00fb1 Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Sat, 20 Jul 2019 17:34:16 +0200 Subject: [PATCH] Polishing --- .../TransactionAwareCacheDecorator.java | 17 ++++--- .../springframework/cache/CacheManager.java | 15 ++++--- .../cache/support/AbstractCacheManager.java | 18 ++++---- .../context/MessageSource.java | 44 ++++++++++++------- .../springframework/core/PriorityOrdered.java | 23 ++++++---- .../support/ReflectivePropertyAccessor.java | 29 ++++++------ 6 files changed, 85 insertions(+), 61 deletions(-) diff --git a/spring-context-support/src/main/java/org/springframework/cache/transaction/TransactionAwareCacheDecorator.java b/spring-context-support/src/main/java/org/springframework/cache/transaction/TransactionAwareCacheDecorator.java index 9038156aac..223812c8dc 100644 --- a/spring-context-support/src/main/java/org/springframework/cache/transaction/TransactionAwareCacheDecorator.java +++ b/spring-context-support/src/main/java/org/springframework/cache/transaction/TransactionAwareCacheDecorator.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2017 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. @@ -25,14 +25,16 @@ import org.springframework.transaction.support.TransactionSynchronizationManager import org.springframework.util.Assert; /** - * Cache decorator which synchronizes its {@link #put}, {@link #evict} and {@link #clear} - * operations with Spring-managed transactions (through Spring's {@link TransactionSynchronizationManager}, - * performing the actual cache put/evict/clear operation only in the after-commit phase of a - * successful transaction. If no transaction is active, {@link #put}, {@link #evict} and + * Cache decorator which synchronizes its {@link #put}, {@link #evict} and + * {@link #clear} operations with Spring-managed transactions (through Spring's + * {@link TransactionSynchronizationManager}, performing the actual cache + * put/evict/clear operation only in the after-commit phase of a successful + * transaction. If no transaction is active, {@link #put}, {@link #evict} and * {@link #clear} operations will be performed immediately, as usual. * - *

Use of more aggressive operations such as {@link #putIfAbsent} cannot be deferred - * to the after-commit phase of a running transaction. Use these with care. + *

Note: Use of immediate operations such as {@link #putIfAbsent} + * cannot be deferred to the after-commit phase of a running transaction. + * Use these with care in a transactional environment. * * @author Juergen Hoeller * @author Stephane Nicoll @@ -54,6 +56,7 @@ public class TransactionAwareCacheDecorator implements Cache { this.targetCache = targetCache; } + /** * Return the target Cache that this Cache should delegate to. */ diff --git a/spring-context/src/main/java/org/springframework/cache/CacheManager.java b/spring-context/src/main/java/org/springframework/cache/CacheManager.java index d3ca7090bf..833715c63c 100644 --- a/spring-context/src/main/java/org/springframework/cache/CacheManager.java +++ b/spring-context/src/main/java/org/springframework/cache/CacheManager.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2014 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. @@ -22,23 +22,28 @@ import org.springframework.lang.Nullable; /** * Spring's central cache manager SPI. - * Allows for retrieving named {@link Cache} regions. + * + *

Allows for retrieving named {@link Cache} regions. * * @author Costin Leau + * @author Sam Brannen * @since 3.1 */ public interface CacheManager { /** - * Return the cache associated with the given name. + * Get the cache associated with the given name. + *

Note that the cache may be lazily created at runtime if the + * native provider supports it. * @param name the cache identifier (must not be {@code null}) - * @return the associated cache, or {@code null} if none found + * @return the associated cache, or {@code null} if such a cache + * does not exist or could be not created */ @Nullable Cache getCache(String name); /** - * Return a collection of the cache names known by this manager. + * Get a collection of the cache names known by this manager. * @return the names of all caches known by the cache manager */ Collection getCacheNames(); diff --git a/spring-context/src/main/java/org/springframework/cache/support/AbstractCacheManager.java b/spring-context/src/main/java/org/springframework/cache/support/AbstractCacheManager.java index a767d476b2..50ab5ccb31 100644 --- a/spring-context/src/main/java/org/springframework/cache/support/AbstractCacheManager.java +++ b/spring-context/src/main/java/org/springframework/cache/support/AbstractCacheManager.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2016 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. @@ -174,15 +174,15 @@ public abstract class AbstractCacheManager implements CacheManager, Initializing } /** - * Return a missing cache with the specified {@code name} or {@code null} if - * such cache does not exist or could not be created on the fly. - *

Some caches may be created at runtime if the native provider supports - * it. If a lookup by name does not yield any result, a subclass gets a chance - * to register such a cache at runtime. The returned cache will be automatically - * added to this instance. + * Return a missing cache with the specified {@code name}, or {@code null} if + * such a cache does not exist or could not be created on demand. + *

Caches may be lazily created at runtime if the native provider supports it. + * If a lookup by name does not yield any result, an {@code AbstractCacheManager} + * subclass gets a chance to register such a cache at runtime. The returned cache + * will be automatically added to this cache manager. * @param name the name of the cache to retrieve - * @return the missing cache or {@code null} if no such cache exists or could be - * created + * @return the missing cache, or {@code null} if no such cache exists or could be + * created on demand * @since 4.1 * @see #getCache(String) */ diff --git a/spring-context/src/main/java/org/springframework/context/MessageSource.java b/spring-context/src/main/java/org/springframework/context/MessageSource.java index 6396a016bb..54f5ea88ed 100644 --- a/spring-context/src/main/java/org/springframework/context/MessageSource.java +++ b/spring-context/src/main/java/org/springframework/context/MessageSource.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2017 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. @@ -26,10 +26,10 @@ import org.springframework.lang.Nullable; * *

Spring provides two out-of-the-box implementations for production: *

* * @author Rod Johnson @@ -41,16 +41,17 @@ public interface MessageSource { /** * Try to resolve the message. Return default message if no message was found. - * @param code the code to lookup up, such as 'calculator.noRateSet'. Users of - * this class are encouraged to base message names on the relevant fully - * qualified class name, thus avoiding conflict and ensuring maximum clarity. + * @param code the message code to look up, e.g. 'calculator.noRateSet'. + * MessageSource users are encouraged to base message names on qualified class + * or package names, avoiding potential conflicts and ensuring maximum clarity. * @param args an array of arguments that will be filled in for params within * the message (params look like "{0}", "{1,date}", "{2,time}" within a message), - * or {@code null} if none. + * or {@code null} if none * @param defaultMessage a default message to return if the lookup fails * @param locale the locale in which to do the lookup - * @return the resolved message if the lookup was successful; - * otherwise the default message passed as a parameter + * @return the resolved message if the lookup was successful, otherwise + * the default message passed as a parameter (which may be {@code null}) + * @see #getMessage(MessageSourceResolvable, Locale) * @see java.text.MessageFormat */ @Nullable @@ -58,13 +59,16 @@ public interface MessageSource { /** * Try to resolve the message. Treat as an error if the message can't be found. - * @param code the code to lookup up, such as 'calculator.noRateSet' + * @param code the message code to look up, e.g. 'calculator.noRateSet'. + * MessageSource users are encouraged to base message names on qualified class + * or package names, avoiding potential conflicts and ensuring maximum clarity. * @param args an array of arguments that will be filled in for params within * the message (params look like "{0}", "{1,date}", "{2,time}" within a message), - * or {@code null} if none. + * or {@code null} if none * @param locale the locale in which to do the lookup - * @return the resolved message - * @throws NoSuchMessageException if the message wasn't found + * @return the resolved message (never {@code null}) + * @throws NoSuchMessageException if no corresponding message was found + * @see #getMessage(MessageSourceResolvable, Locale) * @see java.text.MessageFormat */ String getMessage(String code, @Nullable Object[] args, Locale locale) throws NoSuchMessageException; @@ -76,9 +80,15 @@ public interface MessageSource { * since at the time of calling this method we aren't able to determine if the * {@code defaultMessage} property of the resolvable is {@code null} or not. * @param resolvable the value object storing attributes required to resolve a message + * (may include a default message) * @param locale the locale in which to do the lookup - * @return the resolved message - * @throws NoSuchMessageException if the message wasn't found + * @return the resolved message (never {@code null} since even a + * {@code MessageSourceResolvable}-provided default message needs to be non-null) + * @throws NoSuchMessageException if no corresponding message was found + * (and no default message was provided by the {@code MessageSourceResolvable}) + * @see MessageSourceResolvable#getCodes() + * @see MessageSourceResolvable#getArguments() + * @see MessageSourceResolvable#getDefaultMessage() * @see java.text.MessageFormat */ String getMessage(MessageSourceResolvable resolvable, Locale locale) throws NoSuchMessageException; 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 priority - * ordering: order values expressed by {@code PriorityOrdered} objects - * always apply before same order values expressed by plain - * {@link Ordered} objects. + * ordering: {@code PriorityOrdered} objects are always applied before + * plain {@link Ordered} objects regardless of their order values. * - *

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

When sorting a set of {@code Ordered} objects, {@code PriorityOrdered} + * objects and plain {@code Ordered} objects are effectively treated as + * two separate subsets, with the set of {@code PriorityOrdered} objects preceding + * the set of plain {@code Ordered} objects and with relative + * ordering applied within those subsets. + * + *

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

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 { - } diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/support/ReflectivePropertyAccessor.java b/spring-expression/src/main/java/org/springframework/expression/spel/support/ReflectivePropertyAccessor.java index 7d1ed62794..cd9d3157df 100644 --- a/spring-expression/src/main/java/org/springframework/expression/spel/support/ReflectivePropertyAccessor.java +++ b/spring-expression/src/main/java/org/springframework/expression/spel/support/ReflectivePropertyAccessor.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2018 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. @@ -327,6 +327,7 @@ public class ReflectivePropertyAccessor implements PropertyAccessor { } /** + * Get the last read invoker pair. * @deprecated as of 4.3.15 since it is not used within the framework anymore */ @Deprecated @@ -384,10 +385,10 @@ public class ReflectivePropertyAccessor implements PropertyAccessor { @Nullable protected Method findGetterForProperty(String propertyName, Class clazz, boolean mustBeStatic) { Method method = findMethodForProperty(getPropertyMethodSuffixes(propertyName), - "get", clazz, mustBeStatic, 0, ANY_TYPES); + "get", clazz, mustBeStatic, 0, ANY_TYPES); if (method == null) { method = findMethodForProperty(getPropertyMethodSuffixes(propertyName), - "is", clazz, mustBeStatic, 0, BOOLEAN_TYPES); + "is", clazz, mustBeStatic, 0, BOOLEAN_TYPES); } return method; } @@ -419,6 +420,17 @@ public class ReflectivePropertyAccessor implements PropertyAccessor { return null; } + /** + * Return class methods ordered with non-bridge methods appearing higher. + */ + private Method[] getSortedMethods(Class clazz) { + return this.sortedMethodsCache.computeIfAbsent(clazz, key -> { + Method[] methods = key.getMethods(); + Arrays.sort(methods, (o1, o2) -> (o1.isBridge() == o2.isBridge() ? 0 : (o1.isBridge() ? 1 : -1))); + return methods; + }); + } + /** * Determine whether the given {@code Method} is a candidate for property access * on an instance of the given target class. @@ -432,17 +444,6 @@ public class ReflectivePropertyAccessor implements PropertyAccessor { return true; } - /** - * Return class methods ordered with non-bridge methods appearing higher. - */ - private Method[] getSortedMethods(Class clazz) { - return this.sortedMethodsCache.computeIfAbsent(clazz, key -> { - Method[] methods = key.getMethods(); - Arrays.sort(methods, (o1, o2) -> (o1.isBridge() == o2.isBridge() ? 0 : (o1.isBridge() ? 1 : -1))); - return methods; - }); - } - /** * Return the method suffixes for a given property name. The default implementation * uses JavaBean conventions with additional support for properties of the form 'xY'