Class ReflectionUtils

java.lang.Object
io.fluxzero.common.reflection.ReflectionUtils
public class ReflectionUtils extends Object
Utility class for high-performance reflection-based operations across the Fluxzero Runtime.

This class is intended for internal use only. It provides a wide range of methods for accessing and manipulating object members via reflection, including:

  • Resolving annotated fields and methods (with support for meta-annotations)
  • Accessing nested property paths via getters and setters (e.g., "user/address/street")
  • Efficient member access using DefaultMemberInvoker, which leverages LambdaMetafactory for near-native invocation performance
  • Generic type resolution, including collection element types and supertype inference
  • Annotation hierarchy traversal and support for Kotlin nullability reflection (if available)
  • Utilities for determining override relationships, class hierarchies, and bean property metadata
  • Robust handling of Class loading and safe access to field/method/property values

Performance Considerations

This class uses extensive caching and memoization to avoid redundant reflective operations at runtime. All public methods are safe to use in high-performance contexts such as annotation scanning, handler dispatching, and JSON schema validation.

Modular Use

If Fluxzero adopts JPMS (Project Jigsaw) in the future, this utility would likely be placed in an internal module and not exported to consumers, to preserve encapsulation and forward compatibility.
See Also:

  • Constructor Details

    • ReflectionUtils

      public ReflectionUtils()

  • Method Details

    • getMethodOverrideHierarchy

      public static Stream<Method> getMethodOverrideHierarchy(Method method)

    • getParameterOverrideHierarchy

      public static Stream<Parameter> getParameterOverrideHierarchy(Parameter parameter)

    • isKotlinReflectionSupported

      public static boolean isKotlinReflectionSupported()

    • ifClass

      public static Class<?> ifClass(Object value)
      Determines and returns the Class of the provided object if it is either an instance of Class or a Kotlin class that can be converted using Kotlin reflection utilities. If the object does not satisfy these conditions or Kotlin reflection is not supported, returns null.
      Parameters:
      value - The object to check and convert to Class, if possible.
      Returns:
      The Class of the provided object, or null if the object is not a class or cannot be converted.

    • isClass

      public static boolean isClass(Object value)

    • asClass

      public static Class<?> asClass(@NonNull @NonNull Object value)

    • getTypeMetadata

      public static ReflectionUtils.TypeMetadata getTypeMetadata(@NonNull @NonNull Class<?> type)

    • getAllMethods

      public static List<Method> getAllMethods(Class<?> type)

    • getDefaultConstructor

      public static Optional<Constructor<?>> getDefaultConstructor(Class<?> type)
      Returns the default constructor declared by the supplied type, if present.

    • getAllInterfaces

      public static List<Class<?>> getAllInterfaces(Class<?> type)
      Returns all interfaces implemented by the supplied type, including interfaces inherited through superclasses and parent interfaces.
      Parameters:
      type - the type to inspect, or null
      Returns:
      interfaces in deterministic discovery order

    • box

      public static Class<?> box(Class<?> type)
      Converts a primitive type to its wrapper class and leaves non-primitive types unchanged.
      Parameters:
      type - the type to box
      Returns:
      the wrapper type for primitives, otherwise type

    • unbox

      public static Class<?> unbox(Class<?> type)
      Converts a primitive wrapper type to its primitive class and leaves other types unchanged.
      Parameters:
      type - the type to unbox
      Returns:
      the primitive type for wrappers, otherwise type

    • rawClass

      public static Class<?> rawClass(Type type)
      Resolves a reflective Type to the best raw Class representation available.
      Parameters:
      type - the reflective type to resolve
      Returns:
      the raw class, or Object when no more specific class can be resolved

    • getMethod

      public static Optional<Method> getMethod(Class<?> type, String name)

    • getAnnotatedProperties

      public static List<? extends AccessibleObject> getAnnotatedProperties(Class<?> target, Class<? extends Annotation> annotation)

    • getAnnotatedProperty

      public static Optional<? extends AccessibleObject> getAnnotatedProperty(Object target, Class<? extends Annotation> annotation)

    • getAnnotatedProperty

      public static Optional<? extends AccessibleObject> getAnnotatedProperty(Class<?> target, Class<? extends Annotation> annotation)

    • getAnnotatedPropertyInvoker

      public static Optional<MemberInvoker> getAnnotatedPropertyInvoker(Class<?> target, Class<? extends Annotation> annotation)

    • getPropertyPathMetadata

      public static ReflectionUtils.TypeMetadata.PropertyPathMetadata getPropertyPathMetadata(Class<?> target, String propertyPath)

    • getAnnotatedPropertyValue

      public static Optional<Object> getAnnotatedPropertyValue(Object target, Class<? extends Annotation> annotation)

    • getAnnotatedPropertyValues

      public static Collection<Object> getAnnotatedPropertyValues(Object target, Class<? extends Annotation> annotation)

    • getAnnotatedPropertyName

      public static Optional<String> getAnnotatedPropertyName(Object target, Class<? extends Annotation> annotation)

    • getPropertyName

      public static String getPropertyName(AccessibleObject property)

    • getAnnotatedMethods

      public static List<Method> getAnnotatedMethods(Class<?> target, Class<? extends Annotation> annotation)

    • getAnnotatedMethods

      public static List<Method> getAnnotatedMethods(Object target, Class<? extends Annotation> annotation)

    • isMethodAnnotationPresent

      public static boolean isMethodAnnotationPresent(Executable method, Class<? extends Annotation> annotation)

    • getAnnotatedFields

      public static List<Field> getAnnotatedFields(Class<?> target, Class<? extends Annotation> annotation)

    • getAnnotatedFields

      public static List<Field> getAnnotatedFields(Object target, Class<? extends Annotation> annotation)

    • isAnnotationPresent

      public static boolean isAnnotationPresent(Class<?> type, Class<? extends Annotation> annotationType)

    • getTypeAnnotation

      public static <A extends Annotation> A getTypeAnnotation(Class<?> type, Class<? extends Annotation> annotationType)

    • getTypeAnnotations

      public static Collection<? extends Annotation> getTypeAnnotations(Class<?> type)

    • getAnnotations

      public static List<Annotation> getAnnotations(AnnotatedElement element)
      Returns the direct annotations present on an annotated element.

      For type, field, method, constructor, and parameter elements, the result is cached in the declaring ReflectionUtils.TypeMetadata. Use getTypeAnnotations(Class) when inherited Fluxzero type annotation semantics are needed, and getPackageAnnotations(Package) for recursive package annotation lookup.

      Parameters:
      element - the annotated element to inspect
      Returns:
      annotations present on the element, or an empty list when element is null

    • getPackageAnnotation

      public static <A extends Annotation> Optional<A> getPackageAnnotation(Package p, Class<A> annotationType)

    • getPackageAnnotations

      public static Collection<? extends Annotation> getPackageAnnotations(Package p)

    • getPackageAnnotations

      public static Collection<? extends Annotation> getPackageAnnotations(Package p, boolean recursive)

    • readProperty

      public static <T> Optional<T> readProperty(String propertyPath, Object target)

    • getTypeArguments

      public static List<Type> getTypeArguments(Type genericType)

    • getFirstTypeArgument

      public static <T extends Type> T getFirstTypeArgument(Type genericType)

    • getTypeArgument

      public static <T extends Type> T getTypeArgument(Type genericType, int index)

    • getPropertyAnnotation

      public static <T> Optional<T> getPropertyAnnotation(String propertyPath, Object target)

    • hasProperty

      public static boolean hasProperty(String propertyPath, Object target)

    • hasReturnType

      public static boolean hasReturnType(Executable executable)

    • getFieldValue

      public static <T> Optional<T> getFieldValue(String fieldName, Object target)

    • getValue

      public static Object getValue(AccessibleObject fieldOrMethod, Object target, boolean forceAccess)

    • getValue

      public static Object getValue(AccessibleObject fieldOrMethod, Object target)

    • getName

      public static String getName(AccessibleObject fieldOrMethod)

    • getEnclosingClass

      public static Class<?> getEnclosingClass(AccessibleObject fieldOrMethod)

    • getPropertyType

      public static Class<?> getPropertyType(AccessibleObject fieldOrMethod)

    • getGenericPropertyType

      public static Type getGenericPropertyType(AccessibleObject fieldOrMethod)

    • writeProperty

      public static void writeProperty(String propertyPath, Object target, Object value)

    • isOrHas

      public static boolean isOrHas(Annotation annotation, Class<? extends Annotation> annotationType)

    • isOrHas

      public static boolean isOrHas(Class<?> type, Class<? extends Annotation> annotationType)

    • getField

      public static Optional<Field> getField(Class<?> owner, String name)

    • getCallerClass

      public static Class<?> getCallerClass()

    • isNullable

      public static boolean isNullable(Parameter parameter)

    • asInstance

      public static <T> T asInstance(Object classOrInstance)

    • getParameterIndex

      public static int getParameterIndex(Parameter parameter)

    • determineCommonAncestors

      public static List<Class<?>> determineCommonAncestors(Collection<?> elements)

    • getPackageAndParentPackages

      public static List<Package> getPackageAndParentPackages(Package p)

    • getMemberAnnotation

      public static <A extends Annotation> Optional<A> getMemberAnnotation(Class<?> type, String memberName, Class<? extends Annotation> a)

    • isStatic

      public static boolean isStatic(Executable method)

    • isLeafValue

      public static boolean isLeafValue(Object value)
      Returns whether the given value should be treated as a terminal scalar during reflective traversal.

      Leaf values are not recursively inspected for nested annotated properties. This is used by infrastructure such as search indexing and data protection to decide whether a value should be processed as a whole or traversed further.

      A value is considered a leaf when it is:

      • null
      • one of the built-in scalar types known to Fluxzero, such as strings, numbers, booleans, temporal values, URIs, locales, and similar primitives/value objects
      • an enum
      • an instance of a type implementing Leaf
      Parameters:
      value - the value to inspect
      Returns:
      true if the value should be treated as a leaf, false otherwise

    • isAnnotationPresent

      public static boolean isAnnotationPresent(Parameter parameter, Class<? extends Annotation> annotationType)

    • getGenericType

      public static Type getGenericType(Class<?> candidate, Class<?> wantedClass)

    • getCollectionElementType

      public static Optional<Class<?>> getCollectionElementType(AccessibleObject fieldOrMethod)

    • getCollectionElementType

      public static Optional<Class<?>> getCollectionElementType(Type parameterizedType)

    • declaresField

      public static boolean declaresField(Class<?> target, String fieldName)

    • setField

      public static void setField(Field field, Object target, Object value)

    • setField

      public static void setField(String fieldName, Object target, Object value)

    • ensureAccessible

      public static <T extends AccessibleObject> T ensureAccessible(T member)

    • getAnnotationAttributes

      public static Map<String,Object> getAnnotationAttributes(Annotation annotation)
      Returns all no-argument attributes declared by an annotation instance.
      Parameters:
      annotation - the annotation to inspect
      Returns:
      annotation attribute values keyed by attribute name

    • getAnnotationAttribute

      public static <T> Optional<T> getAnnotationAttribute(Annotation annotation, String name, Class<T> expectedType)
      Returns a single annotation attribute value when it exists and matches the requested type.
      Type Parameters:
      T - attribute value type
      Parameters:
      annotation - the annotation to inspect
      name - the attribute name
      expectedType - the expected attribute value type
      Returns:
      the attribute value, or empty if the attribute is absent or has another type

    • hasNonDefaultAnnotationAttribute

      public static boolean hasNonDefaultAnnotationAttribute(Annotation annotation, String name)
      Returns whether an annotation attribute has a value that differs from its declared default.
      Parameters:
      annotation - the annotation to inspect
      name - the attribute name
      Returns:
      true if the attribute has a default and the actual value differs from it

    • getAnnotation

      public static <A extends Annotation> Optional<A> getAnnotation(AnnotatedElement m, Class<A> a)

    • getAnnotationAs

      public static <T> Optional<T> getAnnotationAs(Class<?> target, Class<? extends Annotation> annotationType, Class<T> returnType)

    • getAnnotationAs

      public static <T> Optional<T> getAnnotationAs(AnnotatedElement member, Class<? extends Annotation> annotationType, Class<? extends T> returnType)

    • getAnnotationAs

      public static <T> Optional<T> getAnnotationAs(Annotation annotation, Class<? extends Annotation> targetAnnotation, Class<? extends T> returnType)

    • convertAnnotation

      public static <T> T convertAnnotation(Annotation annotation, Class<? extends T> returnType)

    • has

      public static boolean has(Class<? extends Annotation> annotationClass, Method method)

    • has

      public static boolean has(Class<? extends Annotation> annotationClass, Parameter parameter)

    • getFieldAnnotation

      public static <A extends Annotation> Optional<A> getFieldAnnotation(Field f, Class<? extends Annotation> a)

    • getMethodAnnotation

      public static <A extends Annotation> Optional<A> getMethodAnnotation(Executable m, Class<? extends Annotation> a)

    • getMethodAnnotations

      public static <A extends Annotation> List<A> getMethodAnnotations(Executable m, Class<? extends Annotation> a)

    • copyFields

      public static <V> V copyFields(V source, V target)

    • classForName

      public static Class<?> classForName(String type)

    • classForName

      public static Class<?> classForName(String type, Class<?> defaultClass)

    • classExists

      public static boolean classExists(String className)

    • getSimpleName

      public static String getSimpleName(Class<?> c)

    • getSimpleName

      public static String getSimpleName(Package p)

    • getSimpleName

      public static String getSimpleName(String fullyQualifiedName)