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 db51713944..2f7f8b45f5 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. @@ -24,14 +24,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 @@ -53,6 +55,7 @@ public class TransactionAwareCacheDecorator implements Cache { this.targetCache = targetCache; } + /** * Return the target Cache that this Cache should delegate to. */ @@ -101,7 +104,7 @@ public class TransactionAwareCacheDecorator implements Cache { } @Override - public ValueWrapper putIfAbsent(final Object key, final Object value) { + public ValueWrapper putIfAbsent(Object key, Object value) { return this.targetCache.putIfAbsent(key, value); } 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 861f78fffd..c2b795badd 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. @@ -20,22 +20,27 @@ import java.util.Collection; /** * 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 */ 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 01c19806d5..8138c4cccc 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-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. @@ -171,15 +171,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 5a6a4ac92c..028c078b62 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. @@ -24,10 +24,10 @@ import java.util.Locale; * *

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

* * @author Rod Johnson @@ -39,29 +39,33 @@ 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 */ String getMessage(String code, Object[] args, String defaultMessage, Locale locale); /** * 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, Object[] args, Locale locale) throws NoSuchMessageException; @@ -73,9 +77,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 0aa90270b3..bba34b60c1 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. @@ -330,6 +330,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 @@ -385,10 +386,10 @@ public class ReflectivePropertyAccessor implements PropertyAccessor { */ 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; } @@ -418,19 +419,6 @@ public class ReflectivePropertyAccessor implements PropertyAccessor { return null; } - /** - * Determine whether the given {@code Method} is a candidate for property access - * on an instance of the given target class. - *

The default implementation considers any method as a candidate, even for - * non-user-declared properties on the {@link Object} base class. - * @param method the Method to evaluate - * @param targetClass the concrete target class that is being introspected - * @since 4.3.15 - */ - protected boolean isCandidateForProperty(Method method, Class targetClass) { - return true; - } - /** * Return class methods ordered with non-bridge methods appearing higher. */ @@ -449,6 +437,19 @@ public class ReflectivePropertyAccessor implements PropertyAccessor { return methods; } + /** + * Determine whether the given {@code Method} is a candidate for property access + * on an instance of the given target class. + *

The default implementation considers any method as a candidate, even for + * non-user-declared properties on the {@link Object} base class. + * @param method the Method to evaluate + * @param targetClass the concrete target class that is being introspected + * @since 4.3.15 + */ + protected boolean isCandidateForProperty(Method method, Class targetClass) { + return true; + } + /** * Return the method suffixes for a given property name. The default implementation * uses JavaBean conventions with additional support for properties of the form 'xY'