com.github.ykrasik.jaci.reflection.ReflectionAccessor Maven / Gradle / Ivy
Show all versions of jaci-reflection-api Show documentation
/******************************************************************************
* 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;
/**
* Encapsulates all possible interactions with the Java reflection API - required for GWT, which doesn't support
* anything under java.lang.reflect
*
* @author Yevgeny Krasik
*/
public interface ReflectionAccessor {
/**
* Returns a {@code ReflectionMethod} object that reflects the specified
* declared method of the class or interface represented by this
* {@code Class} object. The {@code name} parameter is a
* {@code String} that specifies the simple name of the desired
* method, and the {@code parameterTypes} parameter is an array of
* {@code Class} objects that identify the method's formal parameter
* types, in declared order. If more than one method with the same
* parameter types is declared in a class, and one of these methods has a
* return type that is more specific than any of the others, that method is
* returned; otherwise one of the methods is chosen arbitrarily. If the
* name is "<init>"or "<clinit>" a {@code NoSuchMethodException}
* is raised.
*
* If this {@code Class} object represents an array type, then this
* method does not find the {@code clone()} method.
*
* @param clazz class to get declared method from
* @param name the name of the method
* @param parameterTypes the parameter array
* @return the {@code ReflectionMethod} object for the method of this class
* matching the specified name and parameters
* @throws NoSuchMethodException if a matching method is not found.
* @throws NullPointerException if {@code name} is {@code null}
* @throws SecurityException
* If a security manager, s, is present and any of the
* following conditions is met:
*
*
*
* - the caller's class loader is not the same as the
* class loader of this class and invocation of
* {@link SecurityManager#checkPermission
* s.checkPermission} method with
* {@code RuntimePermission("accessDeclaredMembers")}
* denies access to the declared method
*
*
- the caller's class loader is not the same as or an
* ancestor of the class loader for the current class and
* invocation of {@link SecurityManager#checkPackageAccess
* s.checkPackageAccess()} denies access to the package
* of this class
*
*
*
* @since JDK1.1
*/
ReflectionMethod getDeclaredMethod(Class clazz, String name, Class... parameterTypes) throws Exception;
/**
* Returns an array containing {@code ReflectionMethod} objects reflecting all the
* public methods of the class or interface represented by this {@code
* Class} object, including those declared by the class or interface and
* those inherited from superclasses and superinterfaces.
*
* If this {@code Class} object represents a type that has multiple
* public methods with the same name and parameter types, but different
* return types, then the returned array has a {@code ReflectionMethod} object for
* each such method.
*
*
If this {@code Class} object represents a type with a class
* initialization method {@code }, then the returned array does
* not have a corresponding {@code ReflectionMethod} object.
*
* If this {@code Class} object represents an array type, then the
* returned array has a {@code ReflectionMethod} object for each of the public
* methods inherited by the array type from {@code Object}. It does not
* contain a {@code ReflectionMethod} object for {@code clone()}.
*
*
If this {@code Class} object represents an interface then the
* returned array does not contain any implicitly declared methods from
* {@code Object}. Therefore, if no methods are explicitly declared in
* this interface or any of its superinterfaces then the returned array
* has length 0. (Note that a {@code Class} object which represents a class
* always has public methods, inherited from {@code Object}.)
*
*
If this {@code Class} object represents a primitive type or void,
* then the returned array has length 0.
*
*
Static methods declared in superinterfaces of the class or interface
* represented by this {@code Class} object are not considered members of
* the class or interface.
*
*
The elements in the returned array are not sorted and are not in any
* particular order.
*
* @param clazz Class to get methods from
* @return the array of {@code ReflectionMethod} objects representing the
* public methods of this class
* @throws SecurityException
* If a security manager, s, is present and
* the caller's class loader is not the same as or an
* ancestor of the class loader for the current class and
* invocation of {@link SecurityManager#checkPackageAccess
* s.checkPackageAccess()} denies access to the package
* of this class.
*
* @since JDK1.1
*/
ReflectionMethod[] getMethods(Class clazz) throws SecurityException;
/**
* Returns an array of {@code Field} objects reflecting all the fields
* declared by the class or interface represented by this
* {@code Class} object. This includes public, protected, default
* (package) access, and private fields, but excludes inherited fields.
*
*
If this {@code Class} object represents a class or interface with no
* declared fields, then this method returns an array of length 0.
*
*
If this {@code Class} object represents an array type, a primitive
* type, or void, then this method returns an array of length 0.
*
*
The elements in the returned array are not sorted and are not in any
* particular order.
*
* @param clazz Class to get fields from
* @return the array of {@code Field} objects representing all the
* declared fields of this class
* @throws SecurityException
* If a security manager, s, is present and any of the
* following conditions is met:
*
*
*
* - the caller's class loader is not the same as the
* class loader of this class and invocation of
* {@link SecurityManager#checkPermission
* s.checkPermission} method with
* {@code RuntimePermission("accessDeclaredMembers")}
* denies access to the declared fields within this class
*
*
- the caller's class loader is not the same as or an
* ancestor of the class loader for the current class and
* invocation of {@link SecurityManager#checkPackageAccess
* s.checkPackageAccess()} denies access to the package
* of this class
*
*
*
* @since JDK1.1
*/
ReflectionField[] getDeclaredFields(Class clazz) throws SecurityException;
/**
* Returns this element's annotation for the specified type if
* such an annotation is present, else null.
*
* @param the type of the annotation to query for and return if present
* @param clazz Class to get annotation from
* @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
*/
T getAnnotation(Class clazz, Class annotationClass);
/**
* Creates a new instance of the class represented by this {@code Class}
* object. The class is instantiated as if by a {@code new}
* expression with an empty argument list. The class is initialized if it
* has not already been initialized.
*
* Note that this method propagates any exception thrown by the
* nullary constructor, including a checked exception. Use of
* this method effectively bypasses the compile-time exception
* checking that would otherwise be performed by the compiler.
* The {@link
* java.lang.reflect.Constructor#newInstance(java.lang.Object...)
* Constructor.newInstance} method avoids this problem by wrapping
* any exception thrown by the constructor in a (checked) {@link
* java.lang.reflect.InvocationTargetException}.
*
* @param class type
* @param clazz Class to instantiate
* @return a newly allocated instance of the class represented by this
* object.
* @throws IllegalAccessException if the class or its nullary
* constructor is not accessible.
* @throws InstantiationException
* if this {@code Class} represents an abstract class,
* an interface, an array class, a primitive type, or void;
* or if the class has no nullary constructor;
* or if the instantiation fails for some other reason.
* @throws ExceptionInInitializerError if the initialization
* provoked by this method fails.
* @throws SecurityException
* If a security manager, s, is present and
* the caller's class loader is not the same as or an
* ancestor of the class loader for the current class and
* invocation of {@link SecurityManager#checkPackageAccess
* s.checkPackageAccess()} denies access to the package
* of this class.
*/
T newInstance(Class clazz) throws Exception;
}