explain suppressed warnings

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/proxy/trunk@1582544 13f79535-47bb-0310-9956-ffa450edef68

asm/src/main/java/org/apache/commons/proxy2/asm/ASMProxyFactory.java

@@ -70,7 +70,7 @@ private <T> T createProxy(final ClassLoader classLoader, final AbstractInvoker i
         final Class<?> proxyClass = PROXY_CLASS_CACHE.getProxyClass(classLoader, proxyClasses);
         try
         {
-            @SuppressWarnings("unchecked")
+            @SuppressWarnings("unchecked") // type inference
             final T result = (T) proxyClass.getConstructor(Invoker.class).newInstance(invoker);
             return result;
         }

cglib/src/main/java/org/apache/commons/proxy2/cglib/CglibProxyFactory.java

@@ -55,7 +55,6 @@ public class CglibProxyFactory extends AbstractSubclassingProxyFactory
      * {@inheritDoc}
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createDelegatorProxy(ClassLoader classLoader, ObjectProvider<?> targetProvider,
             Class<?>... proxyClasses)
     {
@@ -66,14 +65,15 @@ public <T> T createDelegatorProxy(ClassLoader classLoader, ObjectProvider<?> tar
         enhancer.setCallbackFilter(CALLBACKFILTER);
         enhancer.setCallbacks(new Callback[] { new ObjectProviderDispatcher(targetProvider), new EqualsHandler(),
                 new HashCodeHandler() });
-        return (T) enhancer.create();
+        @SuppressWarnings("unchecked") // type inference
+        final T result = (T) enhancer.create();
+        return result;
     }
 
     /**
      * {@inheritDoc}
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Interceptor interceptor,
             Class<?>... proxyClasses)
     {
@@ -84,14 +84,15 @@ public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Inte
         enhancer.setCallbackFilter(CALLBACKFILTER);
         enhancer.setCallbacks(new Callback[] { new InterceptorBridge(target, interceptor), new EqualsHandler(),
                 new HashCodeHandler() });
-        return (T) enhancer.create();
+        @SuppressWarnings("unchecked") // type inference
+        final T result = (T) enhancer.create();
+        return result;
     }
 
     /**
      * {@inheritDoc}
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createInvokerProxy(ClassLoader classLoader, Invoker invoker, Class<?>... proxyClasses)
     {
         final Enhancer enhancer = new Enhancer();
@@ -101,7 +102,9 @@ public <T> T createInvokerProxy(ClassLoader classLoader, Invoker invoker, Class<
         enhancer.setCallbackFilter(CALLBACKFILTER);
         enhancer.setCallbacks(
                 new Callback[] { new InvokerBridge(invoker), new EqualsHandler(), new HashCodeHandler() });
-        return (T) enhancer.create();
+        @SuppressWarnings("unchecked") // type inference
+        final T result = (T) enhancer.create();
+        return result;
     }
 
     //******************************************************************************************************************

core/src/main/java/org/apache/commons/proxy2/DefaultProxyFactory.java

@@ -22,8 +22,6 @@
 /**
  * {@link ProxyFactory} implementation that delegates to the first discovered {@link ProxyFactory} service provider that
  * {@link #canProxy(Class...)}.
- * 
- * @author Matt Benson
  */
 class DefaultProxyFactory implements ProxyFactory
 {
@@ -54,7 +52,7 @@ public boolean canProxy(Class<?>... proxyClasses)
     @Override
     public <T> T createDelegatorProxy(ObjectProvider<?> delegateProvider, Class<?>... proxyClasses)
     {
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // type inference
         final T result = (T) getCapableProxyFactory(proxyClasses).createDelegatorProxy(delegateProvider, proxyClasses);
         return result;
     }
@@ -66,7 +64,7 @@ public <T> T createDelegatorProxy(ObjectProvider<?> delegateProvider, Class<?>..
     public <T> T createDelegatorProxy(ClassLoader classLoader, ObjectProvider<?> delegateProvider,
             Class<?>... proxyClasses)
     {
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // type inference
         final T result = (T) getCapableProxyFactory(proxyClasses).createDelegatorProxy(classLoader, delegateProvider,
                 proxyClasses);
         return result;
@@ -78,7 +76,7 @@ public <T> T createDelegatorProxy(ClassLoader classLoader, ObjectProvider<?> del
     @Override
     public <T> T createInterceptorProxy(Object target, Interceptor interceptor, Class<?>... proxyClasses)
     {
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // type inference
         final T result = (T) getCapableProxyFactory(proxyClasses).createInterceptorProxy(target, interceptor,
                 proxyClasses);
         return result;
@@ -91,7 +89,7 @@ public <T> T createInterceptorProxy(Object target, Interceptor interceptor, Clas
     public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Interceptor interceptor,
             Class<?>... proxyClasses)
     {
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // type inference
         final T result = (T) getCapableProxyFactory(proxyClasses).createInterceptorProxy(classLoader, target,
                 interceptor, proxyClasses);
         return result;
@@ -103,7 +101,7 @@ public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Inte
     @Override
     public <T> T createInvokerProxy(Invoker invoker, Class<?>... proxyClasses)
     {
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // type inference
         final T result = (T) getCapableProxyFactory(proxyClasses).createInvokerProxy(invoker, proxyClasses);
         return result;
     }
@@ -114,7 +112,7 @@ public <T> T createInvokerProxy(Invoker invoker, Class<?>... proxyClasses)
     @Override
     public <T> T createInvokerProxy(ClassLoader classLoader, Invoker invoker, Class<?>... proxyClasses)
     {
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // type inference
         final T result = (T) getCapableProxyFactory(proxyClasses)
                 .createInvokerProxy(classLoader, invoker, proxyClasses);
         return result;

core/src/main/java/org/apache/commons/proxy2/ProxyUtils.java

@@ -165,10 +165,11 @@ public static Class<?> getWrapperClass(Class<?> primitiveType)
      *            the type
      * @return the null value
      */
-    @SuppressWarnings("unchecked")
     public static <T> T nullValue(Class<T> type)
     {
-        return (T) NULL_VALUE_MAP.get(type);
+        @SuppressWarnings("unchecked") // map only contains matching type/value entries
+        final T result = (T) NULL_VALUE_MAP.get(type);
+        return result;
     }
 
     /**

core/src/main/java/org/apache/commons/proxy2/stub/AnnotationBuilder.java

@@ -130,34 +130,36 @@ public Object proceed() throws Throwable
     private static final ProxyFactory PROXY_FACTORY = new AbstractProxyFactory()
     {
         @Override
-        @SuppressWarnings("unchecked")
         public <T> T createInvokerProxy(ClassLoader classLoader, final Invoker invoker, Class<?>... proxyClasses)
         {
-            return (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InvocationHandler()
+            @SuppressWarnings("unchecked") // type inference
+            final T result = (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InvocationHandler()
             {
                 @Override
                 public Object invoke(Object proxy, Method method, Object[] args) throws Throwable
                 {
                     return invoker.invoke(proxy, method, args);
                 }
             });
+            return result;
         }
 
         @Override
-        @SuppressWarnings("unchecked")
         public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Interceptor interceptor,
                 Class<?>... proxyClasses)
         {
-            return (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InterceptorInvocationHandler(
+            @SuppressWarnings("unchecked") // type inference
+            final T result = (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InterceptorInvocationHandler(
                     ObjectProviderUtils.constant(target), interceptor));
+            return result;
         }
 
         @Override
-        @SuppressWarnings("unchecked")
         public <T> T createDelegatorProxy(ClassLoader classLoader, final ObjectProvider<?> delegateProvider,
                 Class<?>... proxyClasses)
         {
-            return (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InterceptorInvocationHandler(
+            @SuppressWarnings("unchecked") // type inference
+            final T result = (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InterceptorInvocationHandler(
                     delegateProvider, new Interceptor()
                     {
                         private static final long serialVersionUID = 1L;
@@ -168,6 +170,7 @@ public Object intercept(Invocation invocation) throws Throwable
                             return invocation.proceed();
                         }
                     }));
+            return result;
         }
     };
 

core/src/main/java/org/apache/commons/proxy2/stub/BaseAnnotationTrainer.java

@@ -74,9 +74,15 @@ public StubAnnotationArrayBuilder<R> thenBuildArray()
         private <N extends Annotation> StubAnnotationArrayBuilder(final Class<? extends R> componentType)
         {
             super(componentType);
+
+            /*
+             * We know the only type of array method that can be hosted on an annotation is an annotation array.
+             * Therefore we declare a bogus annotation type parameter on this method which we use to create
+             * our AnnotationTypeTrainer, whose type parameter requires an annotation type. N == R
+             */
             @SuppressWarnings("unchecked")
             final Class<N> annotationType = (Class<N>) componentType;
-            @SuppressWarnings("unchecked")
+            @SuppressWarnings("unchecked") // and cast it back
             final BaseTrainer<?, R> trainer = (BaseTrainer<?, R>) new AnnotationTypeTrainer<N>(
                     annotationType);
             this.annotationTypeTrainer = trainer;
@@ -104,7 +110,7 @@ public <R> WhenAnnotation<R> when(R expression)
     @Override
     public <R> WhenAnnotationArray<R> when(R[] expression)
     {
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // we can reasonably say that the component type of an R[] is Class<? extends R>:
         final Class<? extends R> componentType = (Class<? extends R>) expression.getClass().getComponentType();
         return new WhenAnnotationArray<R>(componentType);
     }

core/src/main/java/org/apache/commons/proxy2/stub/BaseTrainer.java

@@ -58,7 +58,7 @@ protected BaseTrainer(Class<T> traineeType)
             this.traineeType = traineeType;
             return;
         }
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // T is this class's second type parameter; thus the raw type is Class<T>
         final Class<T> resolvedVariable = (Class<T>) TypeUtils.getRawType(BaseTrainer.class.getTypeParameters()[1],
                 getClass());
         Validate.isTrue(resolvedVariable != null, "Trainee type was not specified and could not be calculated for %s",
@@ -159,7 +159,7 @@ public WhenDoubleArray when(double[] expression)
 
     public <R> WhenObjectArray<R> when(R[] expression)
     {
-        @SuppressWarnings("unchecked")
+        @SuppressWarnings("unchecked") // we can reasonably say that the component type of an R[] is Class<? extends R>:
         final Class<? extends R> componentType = (Class<? extends R>) expression.getClass().getComponentType();
         return new WhenObjectArray<R>(componentType);
     }
@@ -169,10 +169,11 @@ public WhenCharArray when(char[] expression)
         return new WhenCharArray();
     }
 
-    @SuppressWarnings("unchecked")
     protected S self()
     {
-        return (S) this;
+        @SuppressWarnings("unchecked") // S is our "self" type parameter
+        final S self = (S) this;
+        return self;
     }
 
     //******************************************************************************************************************
@@ -337,7 +338,7 @@ public StubArrayBuilder<R> addElement(BaseTrainer<?, R> trainer)
 
         public S build()
         {
-            @SuppressWarnings("unchecked")
+            @SuppressWarnings("unchecked") // an array of component type ? extends R is assignable to R[]:
             final R[] array = elements.toArray((R[]) Array.newInstance(componentType, elements.size()));
             trainingContext().then(InterceptorUtils.constant(array));
             return self();

core/src/main/java/org/apache/commons/proxy2/stub/TrainingContext.java

@@ -179,7 +179,7 @@ private boolean allArgumentsMatch(Object[] arguments)
             for (int i = 0; i < arguments.length; i++)
             {
                 Object argument = arguments[i];
-                @SuppressWarnings({ "rawtypes", "unchecked" })
+                @SuppressWarnings({ "rawtypes", "unchecked"}) // we can't know generic argument types
                 final boolean matches = ((ArgumentMatcher) matchers[i]).matches(argument);
                 if (!matches)
                 {

javassist/src/main/java/org/apache/commons/proxy2/javassist/JavassistProxyFactory.java

@@ -69,12 +69,12 @@ private static void addGetMethodMethod(CtClass proxyClass) throws CannotCompileE
      * {@inheritDoc}
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createDelegatorProxy(ClassLoader classLoader, ObjectProvider<?> targetProvider,
             Class<?>... proxyClasses)
     {
         try
         {
+            @SuppressWarnings("unchecked") // type inference
             final Class<? extends T> clazz = (Class<? extends T>) DELEGATING_PROXY_CACHE.getProxyClass(classLoader,
                     proxyClasses);
             return clazz.getConstructor(ObjectProvider.class).newInstance(targetProvider);
@@ -89,12 +89,12 @@ public <T> T createDelegatorProxy(ClassLoader classLoader, ObjectProvider<?> tar
      * {@inheritDoc}
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Interceptor interceptor,
             Class<?>... proxyClasses)
     {
         try
         {
+            @SuppressWarnings("unchecked") // type inference
             final Class<? extends T> clazz = (Class<? extends T>) INTERCEPTOR_PROXY_CACHE.getProxyClass(classLoader,
                     proxyClasses);
             return clazz.getConstructor(Object.class, Interceptor.class).newInstance(target, interceptor);
@@ -109,11 +109,11 @@ public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Inte
      * {@inheritDoc}
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createInvokerProxy(ClassLoader classLoader, Invoker invoker, Class<?>... proxyClasses)
     {
         try
         {
+            @SuppressWarnings("unchecked") // type inference
             final Class<? extends T> clazz = (Class<? extends T>) INVOKER_PROXY_CACHE.getProxyClass(classLoader,
                     proxyClasses);
             return clazz.getConstructor(Invoker.class).newInstance(invoker);

jdk/src/main/java/org/apache/commons/proxy2/jdk/JdkProxyFactory.java

@@ -53,11 +53,13 @@ public class JdkProxyFactory extends AbstractProxyFactory
      * @return a proxy2 which delegates to the object provided by the target <code>delegateProvider>
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createDelegatorProxy(ClassLoader classLoader, ObjectProvider<?> delegateProvider,
             Class<?>... proxyClasses)
     {
-        return (T) Proxy.newProxyInstance(classLoader, proxyClasses, new DelegatorInvocationHandler(delegateProvider));
+        @SuppressWarnings("unchecked") // type inference
+        final T result = (T) Proxy.newProxyInstance(classLoader, proxyClasses, new DelegatorInvocationHandler(
+                delegateProvider));
+        return result;
     }
 
     /**
@@ -76,12 +78,13 @@ public <T> T createDelegatorProxy(ClassLoader classLoader, ObjectProvider<?> del
      *         <code>target</code> object.
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Interceptor interceptor,
             Class<?>... proxyClasses)
     {
-        return (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InterceptorInvocationHandler(target,
+        @SuppressWarnings("unchecked") // type inference
+        final T result = (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InterceptorInvocationHandler(target,
                 interceptor));
+        return result;
     }
 
     /**
@@ -96,10 +99,11 @@ public <T> T createInterceptorProxy(ClassLoader classLoader, Object target, Inte
      * @return a proxy2 which uses the provided {@link Invoker} to handle all method invocations
      */
     @Override
-    @SuppressWarnings("unchecked")
     public <T> T createInvokerProxy(ClassLoader classLoader, Invoker invoker, Class<?>... proxyClasses)
     {
-        return (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InvokerInvocationHandler(invoker));
+        @SuppressWarnings("unchecked") // type inference
+        final T result = (T) Proxy.newProxyInstance(classLoader, proxyClasses, new InvokerInvocationHandler(invoker));
+        return result;
     }
 
     //******************************************************************************************************************