Class ReflectiveAccess

java.lang.Object
dev.ua.theroer.magicutils.reflect.ReflectiveAccess
public final class ReflectiveAccess extends Object
Lightweight helpers for optional runtime integrations via reflection.

All operations are safe-by-default and return Optional values instead of throwing reflective exceptions.

  • Method Details

    • registerNameResolver

      public static void registerNameResolver(ReflectiveAccess.NameResolver resolver)
      Registers a runtime name resolver used by mapped lookup helpers.
      Parameters:
      resolver - resolver to add

    • loadClass

      public static Optional<Class<?>> loadClass(String className)
      Attempts to load a class by its fully qualified name.
      Parameters:
      className - the name of the class to load
      Returns:
      an Optional containing the class if found, otherwise empty

    • loadMappedClass

      public static Optional<Class<?>> loadMappedClass(String className)
      Attempts to load a class directly and then through registered name resolvers.
      Parameters:
      className - class name to load
      Returns:
      an Optional containing the class if found, otherwise empty

    • loadMappedClass

      public static Optional<Class<?>> loadMappedClass(String namespace, String className)
      Attempts to load a class directly and then through registered name resolvers.
      Parameters:
      namespace - source namespace for mapped lookup
      className - class name to load
      Returns:
      an Optional containing the class if found, otherwise empty

    • loadFirstAvailable

      public static Optional<Class<?>> loadFirstAvailable(String... classNames)
      Attempts to load the first available class from a list of names. Useful for handling different environment-specific class names (e.g., Yarn vs Mojang mappings).
      Parameters:
      classNames - list of class names to try
      Returns:
      an Optional containing the first successfully loaded class, otherwise empty

    • publicMethod

      public static Optional<Method> publicMethod(Class<?> type, String name, Class<?>... parameterTypes)
      Attempts to find a public method in the given type. The method is automatically made accessible.
      Parameters:
      type - the class to search in
      name - the name of the method
      parameterTypes - the parameter types of the method
      Returns:
      an Optional containing the method if found, otherwise empty

    • publicMappedMethod

      public static Optional<Method> publicMappedMethod(Class<?> type, String name, Class<?>... parameterTypes)
      Attempts to find a public method directly and then through registered name resolvers.
      Parameters:
      type - the class to search in
      name - method name to find
      parameterTypes - the parameter types of the method
      Returns:
      an Optional containing the method if found, otherwise empty

    • publicMappedMethod

      public static Optional<Method> publicMappedMethod(Class<?> type, String namespace, String ownerClassName, String methodName, String descriptor, Class<?>... parameterTypes)
      Attempts to find a public method directly and then through registered name resolvers.
      Parameters:
      type - the class to search in
      namespace - source namespace for mapped lookup
      ownerClassName - fully qualified source owner class name
      methodName - method name to find
      descriptor - JVM method descriptor in the source namespace, when available
      parameterTypes - runtime parameter types of the method
      Returns:
      an Optional containing the method if found, otherwise empty

    • firstMethod

      public static Optional<Method> firstMethod(Class<?> type, Predicate<Method> predicate)
      Finds the first public method in the given type that matches the predicate.
      Parameters:
      type - the class to search in
      predicate - the condition to match
      Returns:
      an Optional containing the first matching method, otherwise empty

    • publicField

      public static Optional<Field> publicField(Class<?> type, String name)
      Attempts to find a public field in the given type by its name. The field is automatically made accessible.
      Parameters:
      type - the class to search in
      name - the name of the field
      Returns:
      an Optional containing the field if found, otherwise empty

    • publicMappedField

      public static Optional<Field> publicMappedField(Class<?> type, String name)
      Attempts to find a public field directly and then through registered name resolvers.
      Parameters:
      type - the class to search in
      name - field name to find
      Returns:
      an Optional containing the field if found, otherwise empty

    • publicMappedField

      public static Optional<Field> publicMappedField(Class<?> type, String namespace, String ownerClassName, String fieldName, String descriptor)
      Attempts to find a public field directly and then through registered name resolvers.
      Parameters:
      type - the class to search in
      namespace - source namespace for mapped lookup
      ownerClassName - fully qualified source owner class name
      fieldName - field name to find
      descriptor - JVM field descriptor in the source namespace, when available
      Returns:
      an Optional containing the field if found, otherwise empty

    • firstPublicStaticField

      public static Optional<Field> firstPublicStaticField(Class<?> type, Predicate<Field> predicate)
      Finds the first public static field in the given type that matches the predicate.
      Parameters:
      type - the class to search in
      predicate - the condition to match
      Returns:
      an Optional containing the first matching field, otherwise empty

    • readField

      public static Optional<Object> readField(Field field, Object target)
      Reads the value of a field from a target object.
      Parameters:
      field - the field to read
      target - the object instance (null for static fields)
      Returns:
      an Optional containing the field value if read successfully, otherwise empty

    • invoke

      public static Optional<Object> invoke(Method method, Object target, Object... args)
      Invokes a method on a target object with the given arguments.
      Parameters:
      method - the method to invoke
      target - the object instance (null for static methods)
      args - the arguments for the invocation
      Returns:
      an Optional containing the invocation result if successful, otherwise empty

    • cast

      public static <T> Optional<T> cast(Object value, Class<T> expectedType)
      Casts an object to the expected type safely. Handles primitive-to-wrapper conversions.
      Type Parameters:
      T - the target type
      Parameters:
      value - the object to cast
      expectedType - the class to cast to
      Returns:
      an Optional containing the casted value if successful, otherwise empty

    • signature

      public static Predicate<Method> signature(String name, Class<?> returnType, Class<?>... params)
      Creates a predicate to match a method signature.
      Parameters:
      name - the method name (null to ignore)
      returnType - the return type (null to ignore)
      params - the parameter types
      Returns:
      a predicate for method matching