net.sf.mmm.util.reflect.api

Interface ReflectionUtil

All Superinterfaces:

GenericTypeFactory, ReflectionUtilLimited

All Known Implementing Classes:

ReflectionUtilImpl

@ComponentSpecification
public interface ReflectionUtil
extends ReflectionUtilLimited

This is the interface for a collection of utility functions to deal with reflection.
Note:
If you are looking for a method called visitObjectRecursive see PojoUtil instead.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

AnnotationUtil, ReflectionUtilImpl

Field Summary

Fields

Modifier and Type	Field and Description
static Annotation[]	NO_ANNOTATIONS An empty Annotation-array.
static Type[]	NO_TYPES an empty Type-array

Fields inherited from interface net.sf.mmm.util.reflect.api.ReflectionUtilLimited

NO_ARGUMENTS, NO_PARAMETERS

Method Summary

Modifier and Type	Method and Description
int	compare(Class<?> class1, Class<?> class2) This method compares the given classes.
Set<String>	findClassNames(String packageName, boolean includeSubPackages) This method finds all classes that are located in the package identified by the given packageName.
Set<String>	findClassNames(String packageName, boolean includeSubPackages, Filter<? super String> filter) This method finds all classes that are located in the package identified by the given packageName.
Set<String>	findClassNames(String packageName, boolean includeSubPackages, Filter<? super String> filter, ClassLoader classLoader) This method finds all classes that are located in the package identified by the given packageName.
void	findClassNames(String packageName, boolean includeSubPackages, Set<String> classSet) This method finds all classes that are located in the package identified by the given packageName.
Set<String>	findResourceNames(String packageName, boolean includeSubPackages, Filter<? super String> filter) This method finds all resources that are located in the package identified by the given packageName.
Set<String>	findResourceNames(String packageName, boolean includeSubPackages, Filter<? super String> filter, ClassLoader classLoader) This method finds all resources that are located in the package identified by the given packageName.
Set<DataResource>	findResources(String absoluteClasspath) This method finds all resources that match to the given absoluteClasspath.
Set<DataResource>	findResources(String packageName, boolean includeSubPackages, Filter<? super String> filter) This method finds all resources that are located in the package identified by the given packageName.
Set<DataResource>	findResources(String packageName, boolean includeSubPackages, Filter<? super String> filter, ClassLoader classLoader) This method finds all resources that are located in the package identified by the given packageName.
Class<?>	getArrayClass(Class<?> componentType) This method creates the Class reflecting an array of the given componentType.
Class<?>[]	getClasses(Object[] objects) This method gets the classes of the given objects.
Method	getParentMethod(Class<?> inheritingClass, String methodName, Class<?>[] parameterTypes) This method gets the method identified by methodName and parameterTypes that is NOT declared but inherited by the given declaringClass.
Method	getParentMethod(Method method) This method gets the parent method of the given method.
<T> T	getStaticField(Class<?> type, String fieldName, Class<T> fieldType, boolean exactTypeMatch, boolean mustBeFinal, boolean inherit) This method gets the value of a static field .
<T> T	getStaticFieldOrNull(Class<?> type, String fieldName, Class<T> fieldType, boolean exactTypeMatch, boolean mustBeFinal, boolean inherit)
boolean	isMarkerInterface(Class<?> interfaceClass) This method determines if the given interfaceClass is a marker-interface (e.g.
Set<Class<?>>	loadClasses(Collection<String> qualifiedClassNames) This method loads the classes given as Collection of fully qualified names by qualifiedClassNames and returns them as Set.
Set<Class<?>>	loadClasses(Collection<String> classNames, ClassResolver classResolver, Filter<? super Class<?>> filter) This method loads the classes given as Collection of names by classNames using the given classResolver.
Set<Class<?>>	loadClasses(Collection<String> qualifiedClassNames, Filter<? super Class<?>> filter) This method loads the classes given as Collection of fully qualified names by qualifiedClassNames.
String	toString(Type type) This method gets the string representation of a Type.
void	toString(Type type, Appendable appendable, Visitor<Class<?>> classFormatter) This method gets the string representation of a Type.
String	toStringSimple(Type type) This method gets a compact string representation of a Type.
Type	toType(String type) This method is the analogy to Class.forName(String) for creating a Type instance from String.
Type	toType(String type, ClassResolver resolver) This method is the analogy to Class.forName(String) for creating a Type instance from String.

Methods inherited from interface net.sf.mmm.util.reflect.api.ReflectionUtilLimited

getNonPrimitiveType

Methods inherited from interface net.sf.mmm.util.reflect.api.GenericTypeFactory

createGenericType, createGenericType, createGenericType, createGenericType, createGenericTypeOfList, createGenericTypeOfMap, createGenericTypeOfSet

Field Detail

NO_TYPES

static final Type[] NO_TYPES

an empty Type-array

NO_ANNOTATIONS

static final Annotation[] NO_ANNOTATIONS

An empty Annotation-array.

Since:

4.0.0

Method Detail

getClasses

Class<?>[] getClasses(Object[] objects)

This method gets the classes of the given objects.

Parameters:

objects - is an array containing the objects for that the classes are requested.

Returns:

an array of the same length as the given array. At each position the returned array contains the class of the object from the given array at the same position or null, if that object is null.

getArrayClass

Class<?> getArrayClass(Class<?> componentType)

This method creates the Class reflecting an array of the given componentType.

Parameters:

componentType - is the component type .

Returns:

the according array-class.

toType

Type toType(String type)
     throws TypeNotFoundException,
            NlsIllegalArgumentException

This method is the analogy to Class.forName(String) for creating a Type instance from String.

Parameters:

type - is the string representation of the requested type.

Returns:

the requested type.

Throws:

TypeNotFoundException - if a class could NOT be found (e.g. in java.util.Map<java.long.String> - what should be lang instead of long).

NlsIllegalArgumentException - if the given type could NOT be parsed (e.g. java.util.Map<<String>).

See Also:

toType(String, ClassResolver)

toType

Type toType(String type,
            ClassResolver resolver)
     throws TypeNotFoundException,
            NlsIllegalArgumentException

This method is the analogy to Class.forName(String) for creating a Type instance from String.

Parameters:

type - is the string representation of the requested type.

resolver - is used to resolve classes.

Returns:

the requested type.

Throws:

TypeNotFoundException - if a class could NOT be found (e.g. in java.util.Map<java.long.String> - what should be lang instead of long).

NlsIllegalArgumentException - if the given type could NOT be parsed (e.g. java.util.Map<<String>).

toString

String toString(Type type)

This method gets the string representation of a Type. Instead of Type.toString() it returns Class.getName() if the type is a Class.

Parameters:

type - is the type to get as string.

Returns:

the string representation of the given type.

toStringSimple

String toStringSimple(Type type)

This method gets a compact string representation of a Type. Instead of toString(Type) this method will write simple names of Classes.

Parameters:

type - is the type to get as string.

Returns:

the compact string representation of the given type.

toString

void toString(Type type,
              Appendable appendable,
              Visitor<Class<?>> classFormatter)
       throws RuntimeIoException

This method gets the string representation of a Type. Instead of Type.toString() it returns Class.getName() if the type is a Class.

Parameters:

type - is the type to get as string.

appendable - is where to append the string representation to.

classFormatter - is a Visitor that gets called for each Class and has to append as string-representation of the visited Class to the appendable.

Throws:

RuntimeIoException - if the Appendable caused an IOException

Since:

2.0.0

compare

int compare(Class<?> class1,
            Class<?> class2)

This method compares the given classes.

Parameters:

class1 - is the first class.

class2 - is the second class.

Returns:

• 0 if both classes are equal to each other.
• 1 if class1 inherits from class2.
• -1 if class2 inherits from class1.
• Integer.MIN_VALUE otherwise.

isMarkerInterface

boolean isMarkerInterface(Class<?> interfaceClass)

This method determines if the given interfaceClass is a marker-interface (e.g. Serializable or Cloneable). A marker-interface is also called a tagging-interface.

Parameters:

interfaceClass - is the Class reflecting the interface to check.

Returns:

true if the given interfaceClass is a marker-interface, false otherwise (if regular interface or no interface at all).

getStaticField

<T> T getStaticField(Class<?> type,
                     String fieldName,
                     Class<T> fieldType,
                     boolean exactTypeMatch,
                     boolean mustBeFinal,
                     boolean inherit)
              throws NoSuchFieldException,
                     IllegalAccessException,
                     IllegalArgumentException

This method gets the value of a static field .

Type Parameters:

T - the templated type the requested field is assigned to.

Parameters:

type - is the class or interface containing the requested field.

fieldName - is the name of the requested field.

fieldType - is the type the requested field is assigned to. Therefore the field declaration (!) must be assignable to this type.

exactTypeMatch - - if true, the fieldType must match exactly the type of the static field, else if false the type of the field may be a sub-type of fieldType or one of the types may be primitive while the other is the according object-type.

mustBeFinal - - if true, an IllegalArgumentException is thrown if the specified static field exists but is NOT final, false otherwise.

inherit - if true the field may be inherited from a super-class or super-interface of type, else if false the field is only accepted if it is declared in type.

Returns:

the value of the field with the given type.

Throws:

NoSuchFieldException - if the given type has no field with the given fieldName.

IllegalAccessException - if you do not have permission to read the field (e.g. field is private).

IllegalArgumentException - if the field is NOT static (or final) or has the wrong type.

getStaticFieldOrNull

<T> T getStaticFieldOrNull(Class<?> type,
                           String fieldName,
                           Class<T> fieldType,
                           boolean exactTypeMatch,
                           boolean mustBeFinal,
                           boolean inherit)
                    throws IllegalArgumentException

Type Parameters:

T - the templated type the requested field is assigned to.

Parameters:

type - is the class or interface containing the requested field.

fieldName - is the name of the requested field.

fieldType - is the type the requested field is assigned to. Therefore the field declaration (!) must be assignable to this type.

exactTypeMatch - - if true, the fieldType must match exactly the type of the static field, else if false the type of the field may be a sub-type of fieldType or one of the types may be primitive while the other is the according object-type.

mustBeFinal - - if true, an IllegalArgumentException is thrown if the specified static field exists but is NOT final, false otherwise.

inherit - if true the field may be inherited from a super-class or super-interface of type, else if false the field is only accepted if it is declared in type.

Returns:

the value of the field with the given type or null if the field does NOT exist or is NOT accessible.

Throws:

IllegalArgumentException - if the field is NOT static (or final) or has the wrong type.

getParentMethod

Method getParentMethod(Method method)
                throws SecurityException

This method gets the parent method of the given method. The parent method is the method overridden (is the sense of Override) by the given method or directly inherited from an interface.

Parameters:

method - is the method.

Returns:

the parent method or null if no such method exists.

Throws:

SecurityException - if access has been denied by the SecurityManager.

getParentMethod

Method getParentMethod(Class<?> inheritingClass,
                       String methodName,
                       Class<?>[] parameterTypes)
                throws SecurityException

This method gets the method identified by methodName and parameterTypes that is NOT declared but inherited by the given declaringClass.

Parameters:

inheritingClass - is the class inheriting the requested method.

methodName - is the name of the requested method.

parameterTypes - is the signature of the requested method.

Returns:

the inherited method or null if no such method exists.

Throws:

SecurityException - if access has been denied by the SecurityManager.

See Also:

getParentMethod(Class, String, Class[])

findClassNames

Set<String> findClassNames(String packageName,
                           boolean includeSubPackages)
                    throws RuntimeIoException

This method finds all classes that are located in the package identified by the given packageName.
ATTENTION:
This is a relative expensive operation. Depending on your classpath multiple directories, JAR-, and WAR-files may need to be scanned.

Parameters:

packageName - is the name of the Package to scan.

includeSubPackages - - if true all sub-packages of the specified Package will be included in the search.

Returns:

a Set with the fully qualified names of all requested classes.

Throws:

RuntimeIoException - if the operation failed with an I/O error.

findClassNames

Set<String> findClassNames(String packageName,
                           boolean includeSubPackages,
                           Filter<? super String> filter)
                    throws RuntimeIoException

This method finds all classes that are located in the package identified by the given packageName.
ATTENTION:
This is a relative expensive operation. Depending on your classpath multiple directories, JAR-, and WAR-files may need to be scanned.

Parameters:

packageName - is the name of the Package to scan.

includeSubPackages - - if true all sub-packages of the specified Package will be included in the search.

filter - is used to filter the Class-names to be added to the resulting Set. The Filter will receive fully qualified class-names as argument (e.g. "net.sf.mmm.reflect.api.ReflectionUtil").

Returns:

a Set with the fully qualified names of all requested classes.

Throws:

RuntimeIoException - if the operation failed with an I/O error.

Since:

1.1.0

findClassNames

Set<String> findClassNames(String packageName,
                           boolean includeSubPackages,
                           Filter<? super String> filter,
                           ClassLoader classLoader)
                    throws RuntimeIoException

This method finds all classes that are located in the package identified by the given packageName.
ATTENTION:
This is a relative expensive operation. Depending on your classpath multiple directories, JAR-, and WAR-files may need to be scanned.

Parameters:

packageName - is the name of the Package to scan.

includeSubPackages - - if true all sub-packages of the specified Package will be included in the search.

filter - is used to filter the Class-names to be added to the resulting Set. The Filter will receive fully qualified class-names as argument (e.g. "net.sf.mmm.reflect.api.ReflectionUtil").

classLoader - is the explicit ClassLoader to use.

Returns:

a Set with the fully qualified names of all requested classes.

Throws:

RuntimeIoException - if the operation failed with an I/O error.

Since:

1.1.0

findClassNames

void findClassNames(String packageName,
                    boolean includeSubPackages,
                    Set<String> classSet)
             throws RuntimeIoException

This method finds all classes that are located in the package identified by the given packageName.
ATTENTION:
This is a relative expensive operation. Depending on your classpath multiple directories, JAR-, and WAR-files may need to be scanned.

Parameters:

packageName - is the name of the Package to scan.

includeSubPackages - - if true all sub-packages of the specified Package will be included in the search.

classSet - is where to add the classes.

Throws:

RuntimeIoException - if the operation failed with an I/O error.

loadClasses

Set<Class<?>> loadClasses(Collection<String> qualifiedClassNames)
                   throws TypeNotFoundException

This method loads the classes given as Collection of fully qualified names by qualifiedClassNames and returns them as Set.

Parameters:

qualifiedClassNames - is a collection containing the qualified names of the classes to load.

Returns:

a Set with all loaded classes.

Throws:

TypeNotFoundException - if one of the classes could NOT be loaded.

loadClasses

Set<Class<?>> loadClasses(Collection<String> qualifiedClassNames,
                          Filter<? super Class<?>> filter)
                   throws TypeNotFoundException

This method loads the classes given as Collection of fully qualified names by qualifiedClassNames. It returns a Set containing only those loaded classes that are accepted by the given filter.

Parameters:

qualifiedClassNames - is a collection containing the qualified names of the classes to load.

filter - is used to filter the loaded classes.

Returns:

a Set with all loaded classes that are accepted by the given filter.

Throws:

TypeNotFoundException - if one of the classes could NOT be loaded.

loadClasses

Set<Class<?>> loadClasses(Collection<String> classNames,
                          ClassResolver classResolver,
                          Filter<? super Class<?>> filter)
                   throws TypeNotFoundException

This method loads the classes given as Collection of names by classNames using the given classResolver. It returns a Set containing only those loaded classes that are accepted by the given filter.

Parameters:

classNames - is a collection containing the names of the classes to load. The class names should typically be the qualified names of the classes to load. But this may differ depending on the classResolver.

classResolver - is used to load/resolve the classes by their names.

filter - is used to filter the loaded classes.

Returns:

a Set with all loaded classes that are accepted by the given filter.

Throws:

TypeNotFoundException - if one of the classes could NOT be loaded.

findResourceNames

Set<String> findResourceNames(String packageName,
                              boolean includeSubPackages,
                              Filter<? super String> filter)
                       throws RuntimeIoException

This method finds all resources that are located in the package identified by the given packageName.
ATTENTION:
This is a relative expensive operation. Depending on your classpath multiple directories, JAR-, and WAR-files may need to be scanned.

Parameters:

packageName - is the name of the Package to scan. Both "." and "/" are accepted as separator (e.g. "net.sf.mmm.util.reflect).

includeSubPackages - - if true all sub-packages of the specified Package will be included in the search.

filter - is used to filter the resources. The Filter will receive fully qualified classpath entries as argument (e.g. "net/sf/mmm/util/reflect/beans-util-reflect.xml"). Typically you will exclude resources that end with ".class" or only accept resources that end with ".xml".

Returns:

a Set with the fully qualified names of all requested resources (e.g. "net/sf/mmm/util/reflect/beans-util-reflect.xml").

Throws:

RuntimeIoException - if the operation failed with an I/O error.

Since:

1.1.0

findResourceNames

Set<String> findResourceNames(String packageName,
                              boolean includeSubPackages,
                              Filter<? super String> filter,
                              ClassLoader classLoader)
                       throws RuntimeIoException

This method finds all resources that are located in the package identified by the given packageName.
ATTENTION:
This is a relative expensive operation. Depending on your classpath multiple directories, JAR-, and WAR-files may need to be scanned.

Parameters:

packageName - is the name of the Package to scan. Both "." and "/" are accepted as separator (e.g. "net.sf.mmm.util.reflect).

includeSubPackages - - if true all sub-packages of the specified Package will be included in the search.

filter - is used to filter the resources. The Filter will receive fully qualified classpath entries as argument (e.g. "net/sf/mmm/util/reflect/beans-util-reflect.xml"). Typically you will exclude resources that end with ".class" or only accept resources that end with ".xml".

classLoader - is the explicit ClassLoader to use.

Returns:

a Set with the fully qualified names of all requested resources (e.g. "net/sf/mmm/util/reflect/beans-util-reflect.xml").

Throws:

RuntimeIoException - if the operation failed with an I/O error.

Since:

1.1.0

findResources

Set<DataResource> findResources(String packageName,
                                boolean includeSubPackages,
                                Filter<? super String> filter)
                         throws RuntimeIoException

This method finds all resources that are located in the package identified by the given packageName.
ATTENTION:
This is a relative expensive operation. Depending on your classpath multiple directories, JAR-, and WAR-files may need to be scanned.

Parameters:

packageName - is the name of the Package to scan. Both "." and "/" are accepted as separator (e.g. "net.sf.mmm.util.reflect).

includeSubPackages - - if true all sub-packages of the specified Package will be included in the search.

filter - is used to filter the resources. Typically you will exclude resources that end with ".class" or only accept resources that end with ".xml".

Returns:

a Set with all requested resources.

Throws:

RuntimeIoException - if the operation failed with an I/O error.

Since:

1.1.0

findResources

Set<DataResource> findResources(String absoluteClasspath)
                         throws RuntimeIoException

This method finds all resources that match to the given absoluteClasspath. Unlike ClasspathResource.ClasspathResource(String) this method will return all resources that with the given classpath (e.g. out of multiple JAR-files).

Parameters:

absoluteClasspath - is the absolute path to the resource. E.g. "net/sf/mmm/util/resource/ClasspathResource.txt".

Returns:

a Set with all requested resources.

Throws:

RuntimeIoException - if the operation failed with an I/O error.

Since:

1.1.0

findResources

Set<DataResource> findResources(String packageName,
                                boolean includeSubPackages,
                                Filter<? super String> filter,
                                ClassLoader classLoader)
                         throws RuntimeIoException

This method finds all resources that are located in the package identified by the given packageName.
ATTENTION:
This is a relative expensive operation. Depending on your classpath multiple directories, JAR-, and WAR-files may need to be scanned.

Parameters:

packageName - is the name of the Package to scan. Both "." and "/" are accepted as separator (e.g. "net.sf.mmm.util.reflect).

includeSubPackages - - if true all sub-packages of the specified Package will be included in the search.

filter - is used to filter the resources. Typically you will exclude resources that end with ".class" or only accept resources that end with ".xml".

classLoader - is the explicit ClassLoader to use.

Returns:

a Set with all requested resources.

Throws:

RuntimeIoException - if the operation failed with an I/O error.

Since:

1.1.0