Package me.croabeast.common.reflect

Class Reflector

java.lang.Object
me.croabeast.common.reflect.Reflector
public final class Reflector extends Object
A powerful utility for performing reflection operations in a fluent and concise manner.

The Reflector class encapsulates a target class and provides methods to retrieve its constructors, fields, methods, and inner classes. It also offers helper functions to invoke methods, access and modify fields, and create new instances dynamically.

This tool is particularly useful in plugin development where access to internal server classes (such as NMS or CraftBukkit classes) is needed. It abstracts away the boilerplate associated with reflection and helps in writing more readable and maintainable code.

Example usage: 


 // Create a Reflector for a target class by its fully-qualified name:
 Reflector reflector = Reflector.of("net.minecraft.server.v1_16_R3.EntityPlayer");

 // Retrieve a declared method and invoke it:
 Method method = reflector.getMethod("someInternalMethod", String.class);
 Object result = method.invoke(someEntityPlayerInstance, "argument");

 // Alternatively, invoke a method using the fluent call:
 Object resultFluent = reflector.call("someInternalMethod", "argument");

Additionally, the Reflector supports creating new instances, accessing private fields, and converting return values into new Reflector objects for further chained operations.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    CRAFT_BUKKIT_PACKAGE
    The package path for CraftBukkit classes, derived from the server's implementation.
    static final String
    NMS_PACKAGE
    The package path for NMS (net.minecraft.server) classes, dynamically constructed based on the API version.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Reflector()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T
    call(Object initial, String methodName, Object... objects)
    Invokes a method on the target object (or an object provided by the initial supplier) with the given parameters.
    <T> T
    call(String methodName, Object... objects)
    Invokes a method on the target object using the specified method name and parameters.
    Reflector
    callAsReflector(Object initial, String methodName, Object... objects)
    Invokes a method on the target object and wraps the result in a new Reflector for further reflection.
    Reflector
    callAsReflector(String methodName, Object... objects)
    Invokes a method on the target object and wraps the result in a new Reflector for further reflection.
    <T> T
    create(Object... objects)
    Creates a new instance of the target class using the constructor that matches the provided arguments.
    Reflector
    createAsReflector(Object... objects)
    Creates a new instance of the target class using the provided constructor arguments, and wraps the resulting object in a Reflector for further reflection.
    static Reflector
    from(Supplier<Object> supplier)
    Creates a new Reflector from a supplier that provides an object instance.
    <T> T
    get(Class<?> clazz)
    Retrieves the value of a field (by matching type) from the target object.
    <T> T
    get(Object initial, Class<?> clazz)
    Retrieves the value of a field (by matching type) from the target object.
    <T> T
    get(Object initial, String fieldName)
    Retrieves the value of a field from the target object (or an object provided by the initial supplier).
    <T> T
    get(String fieldName)
    Retrieves the value of a field with the given name from the target object.
    Reflector
    getAsReflector(Class<?> clazz)
    Retrieves a field value (by matching type) and wraps it in a new Reflector for further reflective operations.
    Reflector
    getAsReflector(Object initial, Class<?> clazz)
    Retrieves a field value (by matching type) and wraps it in a new Reflector for further reflective operations.
    Reflector
    getAsReflector(Object initial, String fieldName)
    Retrieves a field value and wraps it in a new Reflector for further reflective operations.
    Reflector
    getAsReflector(String fieldName)
    Retrieves a field value by name and wraps it in a new Reflector for further reflective operations.
    List<Class<?>>
    getClasses()
    Retrieves a list of all declared inner classes of the target class.
    Constructor<?>
    getConstructor(Class<?>... parameters)
    Retrieves a declared constructor with the specified parameter types.
    List<Constructor<?>>
    getConstructors()
    Retrieves a list of all declared constructors of the target class.
    Field
    getField(Class<?> clazz)
    Retrieves a declared field from the specified class that is not of the same type as the class itself.
    Field
    getField(String name)
    Retrieves a declared field by name.
    List<Field>
    getFields()
    Retrieves a list of all declared fields of the target class.
    Method
    getMethod(String name, Class<?>... parameters)
    Retrieves a declared method by name and parameter types.
    List<Method>
    getMethods()
    Retrieves a list of all declared methods of the target class.
    Class<?>
    getType()
    Returns the target class wrapped by this Reflector.
    static Reflector
    of(Class<?> clazz)
    Creates a new Reflector for the specified target class.
    static Reflector
    of(String path)
    Creates a new Reflector for the class with the specified fully-qualified name.
    static Reflector
    ofCraftBukkit(String className)
    Creates a new Reflector for a CraftBukkit class with the given name.
    static Reflector
    ofNms(String className)
    Creates a new Reflector for an NMS (net.minecraft.server) class with the given name.
    void
    set(Object initial, String fieldName, Object value)
    Sets the value of a field with the specified name on the target object (or an object provided by the initial supplier).
    void
    set(String fieldName, Object value)
    Sets the value of a field with the specified name on the target object.
    Reflector
    setInitial(Supplier<Object> supplier)
    Sets the supplier for the initial object instance.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • NMS_PACKAGE

      public static final String NMS_PACKAGE
      The package path for NMS (net.minecraft.server) classes, dynamically constructed based on the API version.

    • CRAFT_BUKKIT_PACKAGE

      public static final String CRAFT_BUKKIT_PACKAGE
      The package path for CraftBukkit classes, derived from the server's implementation.

  • Constructor Details

    • Reflector

      public Reflector()

  • Method Details

    • setInitial

      public Reflector setInitial(Supplier<Object> supplier)
      Sets the supplier for the initial object instance. This can be used to delay the instantiation or to provide dynamic values for non-static method invocations.
      Parameters:
      supplier - the supplier to set (must not be null)
      Returns:
      this Reflector instance for chaining

    • getType

      public Class<?> getType()
      Returns the target class wrapped by this Reflector.
      Returns:
      the target Class<?>

    • getMethods

      public List<Method> getMethods()
      Retrieves a list of all declared methods of the target class.
      Returns:
      a List of Method objects representing the declared methods

    • getFields

      public List<Field> getFields()
      Retrieves a list of all declared fields of the target class.
      Returns:
      a List of Field objects representing the declared fields

    • getConstructors

      public List<Constructor<?>> getConstructors()
      Retrieves a list of all declared constructors of the target class.
      Returns:
      a List of Constructor objects representing the declared constructors

    • getClasses

      public List<Class<?>> getClasses()
      Retrieves a list of all declared inner classes of the target class.
      Returns:
      a List of Class objects representing the declared inner classes

    • getMethod

      public Method getMethod(String name, Class<?>... parameters)
      Retrieves a declared method by name and parameter types.

      If the method is not accessible, its accessibility is set to true.

      Parameters:
      name - the name of the method
      parameters - the parameter types of the method
      Returns:
      the Method matching the given signature
      Throws:
      NullPointerException - if the method is not found

    • getField

      public Field getField(String name)
      Retrieves a declared field by name.

      If the field is not accessible, its accessibility is set to true.

      Parameters:
      name - the name of the field
      Returns:
      the Field with the specified name
      Throws:
      NullPointerException - if the field is not found

    • getField

      public Field getField(Class<?> clazz)
      Retrieves a declared field from the specified class that is not of the same type as the class itself.

      This method is useful when trying to find a field that holds an instance of a different type.

      Parameters:
      clazz - the class in which to search for the field
      Returns:
      the first Field that does not have the same type as the provided class
      Throws:
      NullPointerException - if no such field is found

    • getConstructor

      public Constructor<?> getConstructor(Class<?>... parameters)
      Retrieves a declared constructor with the specified parameter types.

      If the constructor is not accessible, its accessibility is set to true.

      Parameters:
      parameters - the parameter types of the constructor
      Returns:
      the Constructor matching the given signature
      Throws:
      NullPointerException - if the constructor is not found

    • call

      public <T> T call(Object initial, String methodName, Object... objects)
      Invokes a method on the target object (or an object provided by the initial supplier) with the given parameters.

      The method is looked up by name and parameter types inferred from the provided arguments.

      Type Parameters:
      T - the expected return type
      Parameters:
      initial - an optional initial object to invoke the method on; if null, the supplier's value is used
      methodName - the name of the method to invoke
      objects - the arguments to pass to the method
      Returns:
      the result of the method invocation, cast to type T

    • call

      public <T> T call(String methodName, Object... objects)
      Invokes a method on the target object using the specified method name and parameters.

      This is a convenience overload that assumes a null initial object.

      Type Parameters:
      T - the expected return type
      Parameters:
      methodName - the name of the method to invoke
      objects - the arguments to pass to the method
      Returns:
      the result of the method invocation, cast to type T

    • callAsReflector

      public Reflector callAsReflector(Object initial, String methodName, Object... objects)
      Invokes a method on the target object and wraps the result in a new Reflector for further reflection.
      Parameters:
      initial - an optional initial object to invoke the method on
      methodName - the name of the method to invoke
      objects - the arguments to pass to the method
      Returns:
      a new Reflector wrapping the result of the method call

    • callAsReflector

      public Reflector callAsReflector(String methodName, Object... objects)
      Invokes a method on the target object and wraps the result in a new Reflector for further reflection.
      Parameters:
      methodName - the name of the method to invoke
      objects - the arguments to pass to the method
      Returns:
      a new Reflector wrapping the result of the method call

    • get

      public <T> T get(Object initial, String fieldName)
      Retrieves the value of a field from the target object (or an object provided by the initial supplier).
      Type Parameters:
      T - the expected type of the field value
      Parameters:
      initial - an optional initial object from which to retrieve the field value; if null, the supplier's value is used
      fieldName - the name of the field
      Returns:
      the value of the field, cast to type T

    • get

      public <T> T get(String fieldName)
      Retrieves the value of a field with the given name from the target object.
      Type Parameters:
      T - the expected type of the field value
      Parameters:
      fieldName - the name of the field
      Returns:
      the field value, cast to type T

    • get

      public <T> T get(Object initial, Class<?> clazz)
      Retrieves the value of a field (by matching type) from the target object.
      Type Parameters:
      T - the expected type of the field value
      Parameters:
      initial - an optional initial object from which to retrieve the field value; if null, the supplier's value is used
      clazz - the type of the field to retrieve
      Returns:
      the field value, cast to type T

    • get

      public <T> T get(Class<?> clazz)
      Retrieves the value of a field (by matching type) from the target object.
      Type Parameters:
      T - the expected type of the field value
      Parameters:
      clazz - the type of the field to retrieve
      Returns:
      the field value, cast to type T

    • getAsReflector

      public Reflector getAsReflector(Object initial, String fieldName)
      Retrieves a field value and wraps it in a new Reflector for further reflective operations.
      Parameters:
      initial - an optional initial object from which to retrieve the field value
      fieldName - the name of the field
      Returns:
      a new Reflector wrapping the retrieved field value

    • getAsReflector

      public Reflector getAsReflector(String fieldName)
      Retrieves a field value by name and wraps it in a new Reflector for further reflective operations.
      Parameters:
      fieldName - the name of the field
      Returns:
      a new Reflector wrapping the retrieved field value

    • getAsReflector

      public Reflector getAsReflector(Object initial, Class<?> clazz)
      Retrieves a field value (by matching type) and wraps it in a new Reflector for further reflective operations.
      Parameters:
      initial - an optional initial object from which to retrieve the field value
      clazz - the type of the field to retrieve
      Returns:
      a new Reflector wrapping the retrieved field value

    • getAsReflector

      public Reflector getAsReflector(Class<?> clazz)
      Retrieves a field value (by matching type) and wraps it in a new Reflector for further reflective operations.
      Parameters:
      clazz - the type of the field to retrieve
      Returns:
      a new Reflector wrapping the retrieved field value

    • set

      public void set(Object initial, String fieldName, Object value)
      Sets the value of a field with the specified name on the target object (or an object provided by the initial supplier).
      Parameters:
      initial - an optional initial object on which to set the field value; if null, the supplier's value is used
      fieldName - the name of the field
      value - the value to set in the field

    • set

      public void set(String fieldName, Object value)
      Sets the value of a field with the specified name on the target object.
      Parameters:
      fieldName - the name of the field
      value - the value to set in the field

    • create

      public <T> T create(Object... objects)
      Creates a new instance of the target class using the constructor that matches the provided arguments.
      Type Parameters:
      T - the type of the created instance
      Parameters:
      objects - the arguments to pass to the constructor
      Returns:
      a new instance of type T

    • createAsReflector

      public Reflector createAsReflector(Object... objects)
      Creates a new instance of the target class using the provided constructor arguments, and wraps the resulting object in a Reflector for further reflection.
      Parameters:
      objects - the arguments to pass to the constructor
      Returns:
      a new Reflector wrapping the created instance

    • of

      public static Reflector of(Class<?> clazz)
      Creates a new Reflector for the specified target class.
      Parameters:
      clazz - the target class
      Returns:
      a new Reflector wrapping the target class

    • of

      public static Reflector of(String path)
      Creates a new Reflector for the class with the specified fully-qualified name.
      Parameters:
      path - the fully-qualified class name
      Returns:
      a new Reflector wrapping the target class
      Throws:
      IllegalStateException - if the class cannot be found

    • ofNms

      public static Reflector ofNms(String className)
      Creates a new Reflector for an NMS (net.minecraft.server) class with the given name.
      Parameters:
      className - the name of the NMS class
      Returns:
      a new Reflector wrapping the NMS class

    • ofCraftBukkit

      public static Reflector ofCraftBukkit(String className)
      Creates a new Reflector for a CraftBukkit class with the given name.
      Parameters:
      className - the name of the CraftBukkit class
      Returns:
      a new Reflector wrapping the CraftBukkit class

    • from

      public static Reflector from(Supplier<Object> supplier)
      Creates a new Reflector from a supplier that provides an object instance.

      The supplier is stored as the initial supplier for this reflector, allowing future operations to work with the supplied instance.

      Parameters:
      supplier - a supplier that provides an object instance
      Returns:
      a new Reflector wrapping the class of the supplied object