/******************************************************************************
* Copyright (C) 2016 Yevgeny Krasik *
* *
* Licensed under the Apache License, Version 2.0 (the "License"); *
* you may not use this file except in compliance with the License. *
* You may obtain a copy of the License at *
* *
* http://www.apache.org/licenses/LICENSE-2.0 *
* *
* Unless required by applicable law or agreed to in writing, software *
* distributed under the License is distributed on an "AS IS" BASIS, *
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
* See the License for the specific language governing permissions and *
* limitations under the License. *
******************************************************************************/
package com.github.ykrasik.jaci.reflection;
import java.lang.annotation.Annotation;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.util.List;
/**
* Reflection information about a method.
* Used due to lack of support for java.lang.reflect classes in GWT.
*
* @author Yevgeny Krasik
*/
public interface ReflectionMethod {
/**
* Invokes the underlying method represented by this {@code Method}
* object, on the specified object with the specified parameters.
* Individual parameters are automatically unwrapped to match
* primitive formal parameters, and both primitive and reference
* parameters are subject to method invocation conversions as
* necessary.
*
* <p>If the underlying method is static, then the specified {@code obj}
* argument is ignored. It may be null.
*
* <p>If the number of formal parameters required by the underlying method is
* 0, the supplied {@code args} array may be of length 0 or null.
*
* <p>If the underlying method is an instance method, it is invoked
* using dynamic method lookup as documented in The Java Language
* Specification, Second Edition, section 15.12.4.4; in particular,
* overriding based on the runtime type of the target object will occur.
*
* <p>If the underlying method is static, the class that declared
* the method is initialized if it has not already been initialized.
*
* <p>If the method completes normally, the value it returns is
* returned to the caller of invoke; if the value has a primitive
* type, it is first appropriately wrapped in an object. However,
* if the value has the type of an array of a primitive type, the
* elements of the array are <i>not</i> wrapped in objects; in
* other words, an array of primitive type is returned. If the
* underlying method return type is void, the invocation returns
* null.
*
* @param obj the object the underlying method is invoked from
* @param args the arguments used for the method call
* @return the result of dispatching the method represented by
* this object on {@code obj} with parameters
* {@code args}
*
* @exception IllegalAccessException if this {@code Method} object
* is enforcing Java language access control and the underlying
* method is inaccessible.
* @exception IllegalArgumentException if the method is an
* instance method and the specified object argument
* is not an instance of the class or interface
* declaring the underlying method (or of a subclass
* or implementor thereof); if the number of actual
* and formal parameters differ; if an unwrapping
* conversion for primitive arguments fails; or if,
* after possible unwrapping, a parameter value
* cannot be converted to the corresponding formal
* parameter type by a method invocation conversion.
* @exception InvocationTargetException if the underlying method
* throws an exception.
* @exception NullPointerException if the specified object is null
* and the method is an instance method.
* @exception ExceptionInInitializerError if the initialization
* provoked by this method fails.
*/
Object invoke(Object obj, Object... args) throws Exception;
/**
* Set the {@code accessible} flag for this object to
* the indicated boolean value. A value of {@code true} indicates that
* the reflected object should suppress Java language access
* checking when it is used. A value of {@code false} indicates
* that the reflected object should enforce Java language access checks.
*
* <p>First, if there is a security manager, its
* {@code checkPermission} method is called with a
* {@code ReflectPermission("suppressAccessChecks")} permission.
*
* <p>A {@code SecurityException} is raised if {@code flag} is
* {@code true} but accessibility of this object may not be changed
* (for example, if this element object is a {@link Constructor} object for
* the class {@link java.lang.Class}).
*
* <p>A {@code SecurityException} is raised if this object is a {@link
* java.lang.reflect.Constructor} object for the class
* {@code java.lang.Class}, and {@code flag} is true.
*
* @param flag the new value for the {@code accessible} flag
* @throws SecurityException if the request is denied.
* @see SecurityManager#checkPermission
* @see java.lang.RuntimePermission
*/
void setAccessible(boolean flag) throws SecurityException;
/**
* @return the {@code Class} object representing the class or interface
* that declares the executable represented by this object.
*/
Class<?> getDeclaringClass();
/**
* @return the name of the method represented by this {@code ReflectionMethod} object, as a {@code String}.
*/
String getName();
/**
* Returns this element's annotation for the specified type if
* such an annotation is <em>present</em>, else null.
*
* @param <A> the type of the annotation to query for and return if present
* @param annotationClass the Class object corresponding to the
* annotation type
* @return this element's annotation for the specified annotation type if
* present on this element, else null
* @throws NullPointerException if the given annotation class is null
* @since 1.5
*/
<A extends Annotation> A getAnnotation(Class<A> annotationClass);
/**
* @return The method's parameter information obtained via reflection.
*/
List<ReflectionParameter> getParameters();
/**
* Returns a {@code Class} object that represents the formal return type
* of the method represented by this {@code Method} object.
*
* @return the return type for the method this object represents
*/
Class<?> getReturnType();
}