Polishing

Author: jhoeller

spring-context/src/main/java/org/springframework/context/weaving/AspectJWeavingEnabler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2016 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.
@@ -16,7 +16,6 @@
 
 package org.springframework.context.weaving;
 
-
 import java.lang.instrument.ClassFileTransformer;
 import java.lang.instrument.IllegalClassFormatException;
 import java.security.ProtectionDomain;
@@ -44,12 +43,13 @@
 public class AspectJWeavingEnabler
 		implements BeanFactoryPostProcessor, BeanClassLoaderAware, LoadTimeWeaverAware, Ordered {
 
+	public static final String ASPECTJ_AOP_XML_RESOURCE = "META-INF/aop.xml";
+
+
 	private ClassLoader beanClassLoader;
 
 	private LoadTimeWeaver loadTimeWeaver;
 
-	public static final String ASPECTJ_AOP_XML_RESOURCE = "META-INF/aop.xml";
-
 
 	@Override
 	public void setBeanClassLoader(ClassLoader classLoader) {
@@ -71,6 +71,12 @@ public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory)
 		enableAspectJWeaving(this.loadTimeWeaver, this.beanClassLoader);
 	}
 
+
+	/**
+	 * Enable AspectJ weaving with the given {@link LoadTimeWeaver}.
+	 * @param weaverToUse the LoadTimeWeaver to apply to (or {@code null} for a default weaver)
+	 * @param beanClassLoader the class loader to create a default weaver for (if necessary)
+	 */
 	public static void enableAspectJWeaving(LoadTimeWeaver weaverToUse, ClassLoader beanClassLoader) {
 		if (weaverToUse == null) {
 			if (InstrumentationLoadTimeWeaver.isInstrumentationAvailable()) {
@@ -80,8 +86,8 @@ public static void enableAspectJWeaving(LoadTimeWeaver weaverToUse, ClassLoader
 				throw new IllegalStateException("No LoadTimeWeaver available");
 			}
 		}
-		weaverToUse.addTransformer(new AspectJClassBypassingClassFileTransformer(
-					new ClassPreProcessorAgentAdapter()));
+		weaverToUse.addTransformer(
+				new AspectJClassBypassingClassFileTransformer(new ClassPreProcessorAgentAdapter()));
 	}
 
 
@@ -108,4 +114,5 @@ public byte[] transform(ClassLoader loader, String className, Class<?> classBein
 			return this.delegate.transform(loader, className, classBeingRedefined, protectionDomain, classfileBuffer);
 		}
 	}
+
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2016 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.
@@ -29,15 +29,13 @@
 import org.springframework.util.Assert;
 
 /**
- * Helper class that encapsulates the specification of a method parameter, i.e.
- * a {@link Method} or {@link Constructor} plus a parameter index and a nested
- * type index for a declared generic type. Useful as a specification object to
- * pass along.
+ * Helper class that encapsulates the specification of a method parameter, i.e. a {@link Method}
+ * or {@link Constructor} plus a parameter index and a nested type index for a declared generic
+ * type. Useful as a specification object to pass along.
  *
- * <p>As of 4.2, there is a {@link org.springframework.core.annotation.SynthesizingMethodParameter
- * SynthesizingMethodParameter} subclass available which synthesizes annotations
- * with attribute aliases. That subclass is used for web and message endpoint
- * processing, in particular.
+ * <p>As of 4.2, there is a {@link org.springframework.core.annotation.SynthesizingMethodParameter}
+ * subclass available which synthesizes annotations with attribute aliases. That subclass is used
+ * for web and message endpoint processing, in particular.
  *
  * @author Juergen Hoeller
  * @author Rob Harrop
@@ -167,7 +165,14 @@ public Constructor<?> getConstructor() {
 	}
 
 	/**
-	 * Returns the wrapped member.
+	 * Return the class that declares the underlying Method or Constructor.
+	 */
+	public Class<?> getDeclaringClass() {
+		return getMember().getDeclaringClass();
+	}
+
+	/**
+	 * Return the wrapped member.
 	 * @return the Method or Constructor as Member
 	 */
 	public Member getMember() {
@@ -183,7 +188,9 @@ public Member getMember() {
 	}
 
 	/**
-	 * Returns the wrapped annotated element.
+	 * Return the wrapped annotated element.
+	 * <p>Note: This method exposes the annotations declared on the method/constructor
+	 * itself (i.e. at the method/constructor level, not at the parameter level).
 	 * @return the Method or Constructor as AnnotatedElement
 	 */
 	public AnnotatedElement getAnnotatedElement() {
@@ -198,13 +205,6 @@ public AnnotatedElement getAnnotatedElement() {
 		}
 	}
 
-	/**
-	 * Return the class that declares the underlying Method or Constructor.
-	 */
-	public Class<?> getDeclaringClass() {
-		return getMember().getDeclaringClass();
-	}
-
 	/**
 	 * Return the index of the method/constructor parameter.
 	 * @return the parameter index (-1 in case of the return type)
@@ -338,8 +338,8 @@ public Type getGenericParameterType() {
 	/**
 	 * Return the nested type of the method/constructor parameter.
 	 * @return the parameter type (never {@code null})
-	 * @see #getNestingLevel()
 	 * @since 3.1
+	 * @see #getNestingLevel()
 	 */
 	public Class<?> getNestedParameterType() {
 		if (this.nestingLevel > 1) {
@@ -370,8 +370,8 @@ else if (type instanceof ParameterizedType) {
 	/**
 	 * Return the nested generic type of the method/constructor parameter.
 	 * @return the parameter type (never {@code null})
-	 * @see #getNestingLevel()
 	 * @since 4.2
+	 * @see #getNestingLevel()
 	 */
 	public Type getNestedGenericParameterType() {
 		if (this.nestingLevel > 1) {
@@ -423,33 +423,37 @@ public Annotation[] getParameterAnnotations() {
 		return this.parameterAnnotations;
 	}
 
+	/**
+	 * Return {@code true} if the parameter has at least one annotation,
+	 * {@code false} if it has none.
+	 * @see #getParameterAnnotations()
+	 */
+	public boolean hasParameterAnnotations() {
+		return (getParameterAnnotations().length != 0);
+	}
+
 	/**
 	 * Return the parameter annotation of the given type, if available.
 	 * @param annotationType the annotation type to look for
 	 * @return the annotation object, or {@code null} if not found
 	 */
 	@SuppressWarnings("unchecked")
-	public <T extends Annotation> T getParameterAnnotation(Class<T> annotationType) {
+	public <A extends Annotation> A getParameterAnnotation(Class<A> annotationType) {
 		Annotation[] anns = getParameterAnnotations();
 		for (Annotation ann : anns) {
 			if (annotationType.isInstance(ann)) {
-				return (T) ann;
+				return (A) ann;
 			}
 		}
 		return null;
 	}
 
 	/**
-	 * Return true if the parameter has at least one annotation, false if it has none.
-	 */
-	public boolean hasParameterAnnotations() {
-		return (getParameterAnnotations().length != 0);
-	}
-
-	/**
-	 * Return true if the parameter has the given annotation type, and false if it doesn't.
+	 * Return whether the parameter is declared with the given annotation type.
+	 * @param annotationType the annotation type to look for
+	 * @see #getParameterAnnotation(Class)
 	 */
-	public <T extends Annotation> boolean hasParameterAnnotation(Class<T> annotationType) {
+	public <A extends Annotation> boolean hasParameterAnnotation(Class<A> annotationType) {
 		return (getParameterAnnotation(annotationType) != null);
 	}
 

spring-core/src/main/java/org/springframework/core/convert/ConversionService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2016 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.
@@ -64,19 +64,19 @@ public interface ConversionService {
 
 	/**
 	 * Convert the given {@code source} to the specified {@code targetType}.
-	 * @param source the source object to convert (may be null)
+	 * @param source the source object to convert (may be {@code null})
 	 * @param targetType the target type to convert to (required)
 	 * @return the converted object, an instance of targetType
 	 * @throws ConversionException if a conversion exception occurred
-	 * @throws IllegalArgumentException if targetType is null
+	 * @throws IllegalArgumentException if targetType is {@code null}
 	 */
 	<T> T convert(Object source, Class<T> targetType);
 
 	/**
 	 * Convert the given {@code source} to the specified {@code targetType}.
 	 * The TypeDescriptors provide additional context about the source and target locations
 	 * where conversion will occur, often object fields or property locations.
-	 * @param source the source object to convert (may be null)
+	 * @param source the source object to convert (may be {@code null})
 	 * @param sourceType context about the source type to convert from
 	 * (may be {@code null} if source is {@code null})
 	 * @param targetType context about the target type to convert to (required)

spring-orm-hibernate5/src/main/java/org/springframework/orm/hibernate5/HibernateTransactionManager.java

@@ -69,9 +69,9 @@
  * and services which use plain JDBC (without being aware of Hibernate)!
  * Application code needs to stick to the same simple Connection lookup pattern as
  * with {@link org.springframework.jdbc.datasource.DataSourceTransactionManager}
- * (i.e. {@link DataSourceUtils#getConnection}
+ * (i.e. {@link org.springframework.jdbc.datasource.DataSourceUtils#getConnection}
  * or going through a
- * {@link TransactionAwareDataSourceProxy}).
+ * {@link org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy}).
  *
  * <p>Note: To be able to register a DataSource's Connection for plain JDBC code,
  * this instance needs to be aware of the DataSource ({@link #setDataSource}).
@@ -235,7 +235,6 @@ public void setPrepareConnection(boolean prepareConnection) {
 	 * <p>Default is "false". Turning this flag on enforces over-commit holdability on the
 	 * underlying JDBC Connection (if {@link #prepareConnection "prepareConnection"} is on)
 	 * and skips the disconnect-on-completion step.
-	 * @since 4.2
 	 * @see Connection#setHoldability
 	 * @see ResultSet#HOLD_CURSORS_OVER_COMMIT
 	 * @see #disconnectOnCompletion(Session)
@@ -687,7 +686,6 @@ protected void doCleanupAfterCompletion(Object transaction) {
 	 * <p>The default implementation simply calls {@link Session#disconnect()}.
 	 * Subclasses may override this with a no-op or with fine-tuned disconnection logic.
 	 * @param session the Hibernate Session to disconnect
-	 * @since 4.2
 	 * @see Session#disconnect()
 	 */
 	protected void disconnectOnCompletion(Session session) {

spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2016 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.
@@ -33,8 +33,8 @@
  * or common handler behavior like locale or theme changes. Its main purpose
  * is to allow for factoring out repetitive handler code.
  *
- * <p>In an async processing scenario, the handler may be executed in a separate
- * thread while the main thread exits without rendering or invoking the
+ * <p>In an asynchronous processing scenario, the handler may be executed in a
+ * separate thread while the main thread exits without rendering or invoking the
  * {@code postHandle} and {@code afterCompletion} callbacks. When concurrent
  * handler execution completes, the request is dispatched back in order to
  * proceed with rendering the model and all methods of this contract are invoked
@@ -77,16 +77,13 @@ public interface HandlerInterceptor {
 	/**
 	 * Intercept the execution of a handler. Called after HandlerMapping determined
 	 * an appropriate handler object, but before HandlerAdapter invokes the handler.
-	 *
 	 * <p>DispatcherServlet processes a handler in an execution chain, consisting
 	 * of any number of interceptors, with the handler itself at the end.
 	 * With this method, each interceptor can decide to abort the execution chain,
 	 * typically sending a HTTP error or writing a custom response.
-	 *
 	 * <p><strong>Note:</strong> special considerations apply for asynchronous
 	 * request processing. For more details see
 	 * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}.
-	 *
 	 * @param request current HTTP request
 	 * @param response current HTTP response
 	 * @param handler chosen handler to execute, for type and/or instance evaluation
@@ -102,19 +99,16 @@ boolean preHandle(HttpServletRequest request, HttpServletResponse response, Obje
 	 * Intercept the execution of a handler. Called after HandlerAdapter actually
 	 * invoked the handler, but before the DispatcherServlet renders the view.
 	 * Can expose additional model objects to the view via the given ModelAndView.
-	 *
 	 * <p>DispatcherServlet processes a handler in an execution chain, consisting
 	 * of any number of interceptors, with the handler itself at the end.
 	 * With this method, each interceptor can post-process an execution,
 	 * getting applied in inverse order of the execution chain.
-	 *
 	 * <p><strong>Note:</strong> special considerations apply for asynchronous
 	 * request processing. For more details see
 	 * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}.
-	 *
 	 * @param request current HTTP request
 	 * @param response current HTTP response
-	 * @param handler handler (or {@link HandlerMethod}) that started async
+	 * @param handler handler (or {@link HandlerMethod}) that started asynchronous
 	 * execution, for type and/or instance examination
 	 * @param modelAndView the {@code ModelAndView} that the handler returned
 	 * (can also be {@code null})
@@ -127,21 +121,17 @@ void postHandle(HttpServletRequest request, HttpServletResponse response, Object
 	 * Callback after completion of request processing, that is, after rendering
 	 * the view. Will be called on any outcome of handler execution, thus allows
 	 * for proper resource cleanup.
-	 *
 	 * <p>Note: Will only be called if this interceptor's {@code preHandle}
 	 * method has successfully completed and returned {@code true}!
-	 *
 	 * <p>As with the {@code postHandle} method, the method will be invoked on each
 	 * interceptor in the chain in reverse order, so the first interceptor will be
 	 * the last to be invoked.
-	 *
 	 * <p><strong>Note:</strong> special considerations apply for asynchronous
 	 * request processing. For more details see
 	 * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}.
-	 *
 	 * @param request current HTTP request
 	 * @param response current HTTP response
-	 * @param handler handler (or {@link HandlerMethod}) that started async
+	 * @param handler handler (or {@link HandlerMethod}) that started asynchronous
 	 * execution, for type and/or instance examination
 	 * @param ex exception thrown on handler execution, if any
 	 * @throws Exception in case of errors

spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerMethodExceptionResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2016 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.
@@ -34,7 +34,7 @@ public abstract class AbstractHandlerMethodExceptionResolver extends AbstractHan
 
 	/**
 	 * Checks if the handler is a {@link HandlerMethod} and then delegates to the
-	 * base class implementation of {@link #shouldApplyTo(HttpServletRequest, Object)}
+	 * base class implementation of {@code #shouldApplyTo(HttpServletRequest, Object)}
 	 * passing the bean of the {@code HandlerMethod}. Otherwise returns {@code false}.
 	 */
 	@Override
@@ -54,8 +54,7 @@ else if (handler instanceof HandlerMethod) {
 
 	@Override
 	protected final ModelAndView doResolveException(
-			HttpServletRequest request, HttpServletResponse response,
-			Object handler, Exception ex) {
+			HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
 
 		return doResolveHandlerMethodException(request, response, (HandlerMethod) handler, ex);
 	}
@@ -75,7 +74,6 @@ protected final ModelAndView doResolveException(
 	 * @return a corresponding ModelAndView to forward to, or {@code null} for default processing
 	 */
 	protected abstract ModelAndView doResolveHandlerMethodException(
-			HttpServletRequest request, HttpServletResponse response,
-			HandlerMethod handlerMethod, Exception ex);
+			HttpServletRequest request, HttpServletResponse response, HandlerMethod handlerMethod, Exception ex);
 
 }