io microsphere reflect FieldUtils

FieldUtils

Type: Class | Module: microsphere-java-core | Package: io.microsphere.reflect | Since: 1.0.0

Source: microsphere-java-core/src/main/java/io/microsphere/reflect/FieldUtils.java

Overview

The Java Reflection Field Utility class

Declaration

public abstract class FieldUtils implements Utils

Author: Mercy

Version Information

• Introduced in: 1.0.0
• Current Project Version: 0.3.16-SNAPSHOT

Version Compatibility

This component is tested and compatible with the following Java versions:

Java Version	Status
Java 8	✅ Compatible
Java 11	✅ Compatible
Java 17	✅ Compatible
Java 21	✅ Compatible
Java 25	✅ Compatible

Examples

Method Examples

findField

class Example {
    private String testField;
}

Example instance = new Example();
Field field = FieldUtils.findField(instance, "testField");
if (field != null) {
    System.out.println("Field found: " + field.getName());
} else {
    System.out.println("Field not found.");
}

findField

class Example {
    private String testField;
}

Field field = FieldUtils.findField(Example.class, "testField");
if (field != null) {
    System.out.println("Field found: " + field.getName());
} else {
    System.out.println("Field not found.");
}

findField

class Example {
    private String testField;
}

Field field = FieldUtils.findField(Example.class, "testField", String.class);
if (field != null) {
    System.out.println("Field found: " + field.getName());
} else {
    System.out.println("Field not found.");
}

findField

class Example {
    private String testField;
}

// Find field and ensure it's private
Field field = FieldUtils.findField(Example.class, "testField", f -> Modifier.isPrivate(f.getModifiers()));
if (field != null) {
    System.out.println("Field found and passed all filters.");
} else {
    System.out.println("Field not found or did not pass filters.");
}

getStaticFieldValue

class Example {
    private static String testField = "Hello, World!";

    void someMethod() {
       String value = FieldUtils.getStaticFieldValue(Example.class, "testField");
       System.out.println("Field value: " + value);  // Output: Field value: Hello, World!
    }
}

String value = FieldUtils.getStaticFieldValue(Example.class, "testField");
System.out.println("Field value: " + value);  // Output: Field value: Hello, World!

getStaticFieldValue

class Example {
    private static String SECRET = "Hidden";
}

String value = FieldUtils.getStaticFieldValue(true, Example.class, "SECRET");
System.out.println(value);  // Output: Hidden

getStaticFieldValue

class Example {
    private static String testField = "Static Value";
}

Field field = FieldUtils.findField(Example.class, "testField");
String value = FieldUtils.getStaticFieldValue(field);
System.out.println("Field value: " + value);  // Output: Field value: Static Value

getStaticFieldValue

class Example {
    private static int PORT = 8080;
}

Field portField = FieldUtils.findField(Example.class, "PORT");
Integer port = FieldUtils.getStaticFieldValue(true, portField);
System.out.println(port);  // Output: 8080

setStaticFieldValue

class Example {
    private static String testField = "Original Value";
}

// Set the static field's value
FieldUtils.setStaticFieldValue(Example.class, "testField", "New Value");

// Verify the change
String value = FieldUtils.getStaticFieldValue(Example.class, "testField");
System.out.println("Updated field value: " + value);  // Output: Updated field value: New Value

setStaticFieldValue

class Example {
    private static String MODE = "DEV";
}

String previous = FieldUtils.setStaticFieldValue(true, Example.class, "MODE", "PROD");
System.out.println(previous); // Output: DEV
System.out.println(FieldUtils.getStaticFieldValue(true, Example.class, "MODE")); // Output: PROD

findAllFields

class Example {
    public int publicField;
}

Set<Field> fields = FieldUtils.findAllFields(Example.class);
for (Field field : fields) {
    System.out.println("Found field: " + field.getName());
}

Set<Field> stringFields = FieldUtils.findAllFields(Example.class,
    field -> field.getType().equals(String.class));

findAllDeclaredFields

class Example {
    private String privateField;
    public int publicField;
}

Set<Field> fields = FieldUtils.findAllDeclaredFields(Example.class);
for (Field field : fields) {
    System.out.println("Found field: " + field.getName());
}

Set<Field> privateFields = FieldUtils.findAllDeclaredFields(Example.class,
    field -> Modifier.isPrivate(field.getModifiers()));

getDeclaredField

class Example {
    private String exampleField;
}

Field field = FieldUtils.getDeclaredField(Example.class, "exampleField");
if (field != null) {
    System.out.println("Field found: " + field.getName());
} else {
    System.out.println("Field not found.");
}

getFieldValue

class Example {
    private String message = "Hello";
}

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, "message");
System.out.println(value); // May require forceAccess=true for private fields

getFieldValue

class Example {
    private String secret = "Hidden";
}

Example instance = new Example();
String value = FieldUtils.getFieldValue(true, instance, "secret");
System.out.println(value);  // Output: Hidden

getFieldValue

class Example {
    private String label;
}

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, "label", "N/A");
System.out.println(value);  // Output: N/A

class Example {
    private String label = "Microsphere";
}

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, "label", "N/A");
System.out.println(value);  // Output: Microsphere

getFieldValue

class Example {
    private String name;
}

Example instance = new Example();
String value = FieldUtils.getFieldValue(true, instance, "name", "Unknown");
System.out.println(value);  // Output: Unknown

class Example {
    private String name = "Microsphere";
}

Example instance = new Example();
String value = FieldUtils.getFieldValue(true, instance, "name", "Unknown");
System.out.println(value);  // Output: Microsphere

getFieldValue

class Example {
    public String name = "Microsphere";
}

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, "name", String.class);
System.out.println(value);  // Output: Microsphere

class Example {
    public String name = "Microsphere";
}

Example instance = new Example();
Integer value = FieldUtils.getFieldValue(instance, "name", Integer.class);
System.out.println(value);  // Output: null (field type does not match)

getFieldValue

class Example {
    private String secret = "typed";
}

Example instance = new Example();
String value = FieldUtils.getFieldValue(true, instance, "secret", String.class);
System.out.println(value);  // Output: typed

getFieldValue

class Example {
    public String name = "Microsphere";
}

Example instance = new Example();
Field field = FieldUtils.findField(instance, "name");
String value = FieldUtils.getFieldValue(instance, field);
System.out.println(value);  // Output: Microsphere

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, (Field) null);
System.out.println(value);  // Output: null

Usage

Maven Dependency

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-java-core</artifactId>
    <version>${microsphere-java.version}</version>
</dependency>

Tip: Use the BOM (microsphere-java-dependencies) for consistent version management. See the Getting Started guide.

Import

import io.microsphere.reflect.FieldUtils;

API Reference

Public Methods

Method	Description
findField	Find the specified object's declared Field by its name.
findField	Finds a Field in the specified class by its name.
findField	Find the declared Field by its name and type.
findField	Find the declared Field by its name and apply additional filtering conditions.
getStaticFieldValue	Retrieves the value of a static field from the specified class.
getStaticFieldValue	Retrieves the value of a static field from the specified class, optionally forcing accessibility.
getStaticFieldValue	Retrieves the value of a static field.
getStaticFieldValue	Retrieves the value of a static field, optionally forcing accessibility.
setStaticFieldValue	Sets the value of a static field in the specified class.
setStaticFieldValue	Sets the value of a static field in the specified class, optionally forcing accessibility.
findAllFields	Find and return all accessible fields in the class hierarchy, optionally filtered by one or more predicates.
findAllDeclaredFields	Find and return all declared fields in the class hierarchy, optionally filtered by one or more predicates.
getDeclaredField	Retrieves the declared field with the specified name from the given class.
getFieldValue	Retrieves the value of a field by name from the given object instance.
getFieldValue	Retrieves the value of a field by name from the given object instance, with optional forced accessibility.
getFieldValue	Retrieves the value of a field by name and returns a fallback when the field value is null.
getFieldValue	Retrieves the value of a field by name and returns a fallback when the resolved value is null,
getFieldValue	Retrieves the value of a field by name and expected type from the given object instance.
getFieldValue	Retrieves the value of a field with the specified name and type from the given object instance,
getFieldValue	Retrieves the value of the specified Field from the given object instance.

Method Details

findField

public static Field findField(@Nonnull Object object, @Nonnull String fieldName)

Find the specified object's declared Field by its name.

Example Usage

`class Example {
    private String testField;
`

Example instance = new Example();
Field field = FieldUtils.findField(instance, "testField");
if (field != null) {
    System.out.println("Field found: " + field.getName());
} else {
    System.out.println("Field not found.");
}
}

findField

public static Field findField(@Nonnull Class<?> klass, @Nonnull String fieldName)

Finds a Field in the specified class by its name.

This method recursively searches for the field in the given class and its superclasses until it finds the field or reaches the top of the class hierarchy (i.e., the Object class).

Example Usage

`class Example {
    private String testField;
`

Field field = FieldUtils.findField(Example.class, "testField");
if (field != null) {
    System.out.println("Field found: " + field.getName());
} else {
    System.out.println("Field not found.");
}
}

findField

public static Field findField(@Nonnull Class<?> klass, @Nonnull String fieldName, @Nonnull Class<?> fieldType)

Find the declared Field by its name and type.

This method searches for a field with the specified name and type in the given class. If the field is not found, it recursively checks the superclasses until it finds a matching field or reaches the top of the class hierarchy.

Example Usage

`class Example {
    private String testField;
`

Field field = FieldUtils.findField(Example.class, "testField", String.class);
if (field != null) {
    System.out.println("Field found: " + field.getName());
} else {
    System.out.println("Field not found.");
}
}

findField

public static Field findField(@Nonnull Class<?> klass, @Nonnull String fieldName, @Nonnull Predicate<? super Field>... predicates)

Find the declared Field by its name and apply additional filtering conditions.

This method searches for a field with the specified name in the given class. If the field is found, it applies the provided predicates to further filter the field. If any predicate evaluates to false, this method returns null.

Example Usage

`class Example {
    private String testField;
`

// Find field and ensure it's private
Field field = FieldUtils.findField(Example.class, "testField", f -> Modifier.isPrivate(f.getModifiers()));
if (field != null) {
    System.out.println("Field found and passed all filters.");
} else {
    System.out.println("Field not found or did not pass filters.");
}
}

getStaticFieldValue

public static <T> T getStaticFieldValue(@Nonnull Class<?> klass, @Nonnull String fieldName)

Retrieves the value of a static field from the specified class.

This method attempts to find the declared field by name in the given class and then retrieves its value. If the field is not found or is not accessible, an appropriate exception may be thrown.

Example Usage

`class Example {
    private static String testField = "Hello, World!";

    void someMethod() {
       String value = FieldUtils.getStaticFieldValue(Example.class, "testField");
       System.out.println("Field value: " + value);  // Output: Field value: Hello, World!
    `
}

String value = FieldUtils.getStaticFieldValue(Example.class, "testField");
System.out.println("Field value: " + value);  // Output: Field value: Hello, World!
}

getStaticFieldValue

public static <T> T getStaticFieldValue(boolean forceAccess, @Nonnull Class<?> klass, @Nonnull String fieldName)

Retrieves the value of a static field from the specified class, optionally forcing accessibility.

When forceAccess is true, this method attempts to make the field accessible before reading its value. This is useful for private or protected static fields.

Example Usage

`class Example {
    private static String SECRET = "Hidden";
`

String value = FieldUtils.getStaticFieldValue(true, Example.class, "SECRET");
System.out.println(value);  // Output: Hidden
}

getStaticFieldValue

public static <T> T getStaticFieldValue(@Nullable Field field)

Retrieves the value of a static field.

This method gets the value of the specified static field. If the field is not accessible, an attempt will be made to make it accessible.

Example Usage

`class Example {
    private static String testField = "Static Value";
`

Field field = FieldUtils.findField(Example.class, "testField");
String value = FieldUtils.getStaticFieldValue(field);
System.out.println("Field value: " + value);  // Output: Field value: Static Value
}

getStaticFieldValue

public static <T> T getStaticFieldValue(boolean forceAccess, @Nullable Field field)

Retrieves the value of a static field, optionally forcing accessibility.

If forceAccess is enabled, this method tries to make the field accessible before reading the value. Passing null for field returns null.

Example Usage

`class Example {
    private static int PORT = 8080;
`

Field portField = FieldUtils.findField(Example.class, "PORT");
Integer port = FieldUtils.getStaticFieldValue(true, portField);
System.out.println(port);  // Output: 8080
}

setStaticFieldValue

public static <V> V setStaticFieldValue(@Nonnull Class<?> klass, @Nonnull String fieldName, @Nullable V fieldValue)

Sets the value of a static field in the specified class.

This method finds the declared field by name in the given class and sets its value to the provided value. If the field is not found or cannot be accessed, an appropriate exception may be thrown.

Example Usage

`class Example {
    private static String testField = "Original Value";
`

// Set the static field's value
FieldUtils.setStaticFieldValue(Example.class, "testField", "New Value");

// Verify the change
String value = FieldUtils.getStaticFieldValue(Example.class, "testField");
System.out.println("Updated field value: " + value);  // Output: Updated field value: New Value
}

setStaticFieldValue

public static <V> V setStaticFieldValue(boolean forceAccess, @Nonnull Class<?> klass, @Nonnull String fieldName, @Nullable V fieldValue)

Sets the value of a static field in the specified class, optionally forcing accessibility.

When forceAccess is true, this method attempts to make the field accessible before reading and updating it. The previous field value is returned.

Example Usage

`class Example {
    private static String MODE = "DEV";
`

String previous = FieldUtils.setStaticFieldValue(true, Example.class, "MODE", "PROD");
System.out.println(previous); // Output: DEV
System.out.println(FieldUtils.getStaticFieldValue(true, Example.class, "MODE")); // Output: PROD
}

findAllFields

public static Set<Field> findAllFields(@Nonnull Class<?> declaredClass, @Nonnull Predicate<? super Field>... fieldFilters)

Find and return all accessible fields in the class hierarchy, optionally filtered by one or more predicates.

This method collects all public fields from the specified class and its superclasses (including interfaces), and applies optional filtering conditions to select only the desired fields.

Example Usage

`class Example {
    public int publicField;
`

Set fields = FieldUtils.findAllFields(Example.class);
for (Field field : fields) {
    System.out.println("Found field: " + field.getName());
}
}

Filtering Fields

`Set stringFields = FieldUtils.findAllFields(Example.class,
    field -> field.getType().equals(String.class));
`

findAllDeclaredFields

public static Set<Field> findAllDeclaredFields(@Nonnull Class<?> declaredClass, @Nonnull Predicate<? super Field>... fieldFilters)

Find and return all declared fields in the class hierarchy, optionally filtered by one or more predicates.

This method collects all declared fields from the specified class and its superclasses (including interfaces), and applies optional filtering conditions to select only the desired fields.

Example Usage

`class Example {
    private String privateField;
    public int publicField;
`

Set fields = FieldUtils.findAllDeclaredFields(Example.class);
for (Field field : fields) {
    System.out.println("Found field: " + field.getName());
}
}

Filtering Fields

`Set privateFields = FieldUtils.findAllDeclaredFields(Example.class,
    field -> Modifier.isPrivate(field.getModifiers()));
`

getDeclaredField

public static Field getDeclaredField(@Nonnull Class<?> declaredClass, @Nonnull String fieldName)

Retrieves the declared field with the specified name from the given class.

This method uses reflection to find the field and wraps any exceptions thrown during execution in an unchecked exception.

Example Usage

`class Example {
    private String exampleField;
`

Field field = FieldUtils.getDeclaredField(Example.class, "exampleField");
if (field != null) {
    System.out.println("Field found: " + field.getName());
} else {
    System.out.println("Field not found.");
}
}

getFieldValue

public static <V> V getFieldValue(@Nonnull Object instance, @Nonnull String fieldName)

Retrieves the value of a field by name from the given object instance.

This is a convenience overload of #getFieldValue(boolean, Object, String) with forceAccess=false. It will read public fields directly and may throw an access-related exception for non-public fields.

Example Usage

`class Example {
    private String message = "Hello";
`

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, "message");
System.out.println(value); // May require forceAccess=true for private fields
}

getFieldValue

public static <V> V getFieldValue(boolean forceAccess, @Nonnull Object instance, @Nonnull String fieldName)

Retrieves the value of a field by name from the given object instance, with optional forced accessibility.

When forceAccess is true, this method attempts to make the target field accessible before reading its value, which is useful for private or protected fields.

Example Usage

`class Example {
    private String secret = "Hidden";
`

Example instance = new Example();
String value = FieldUtils.getFieldValue(true, instance, "secret");
System.out.println(value);  // Output: Hidden
}

getFieldValue

public static <V> V getFieldValue(@Nonnull Object instance, @Nonnull String fieldName, @Nullable V defaultValue)

Retrieves the value of a field by name and returns a fallback when the field value is null.

This method first delegates to #getFieldValue(Object, String). If the resolved field value is null, it returns the provided defaultValue instead.

Example Usage

`class Example {
    private String label;
`

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, "label", "N/A");
System.out.println(value);  // Output: N/A
}

When Field Value Exists

`class Example {
    private String label = "Microsphere";
`

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, "label", "N/A");
System.out.println(value);  // Output: Microsphere
}

getFieldValue

public static <V> V getFieldValue(boolean forceAccess, @Nonnull Object instance, @Nonnull String fieldName, @Nullable V defaultValue)

Retrieves the value of a field by name and returns a fallback when the resolved value is null, optionally forcing accessibility.

This method is useful when the target field may be private or protected and you want a single call that both reads the field and substitutes a default value when the actual field value is null.

Example Usage

`class Example {
    private String name;
`

Example instance = new Example();
String value = FieldUtils.getFieldValue(true, instance, "name", "Unknown");
System.out.println(value);  // Output: Unknown
}

When Field Value Exists

`class Example {
    private String name = "Microsphere";
`

Example instance = new Example();
String value = FieldUtils.getFieldValue(true, instance, "name", "Unknown");
System.out.println(value);  // Output: Microsphere
}

getFieldValue

public static <V> V getFieldValue(@Nonnull Object instance, @Nonnull String fieldName, @Nonnull Class<V> fieldType)

Retrieves the value of a field by name and expected type from the given object instance.

This is a convenience overload of #getFieldValue(boolean, Object, String, Class) with forceAccess=false. Use this method when the target field is accessible and you want a type-safe lookup by field name and declared type.

Example Usage

`class Example {
    public String name = "Microsphere";
`

Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, "name", String.class);
System.out.println(value);  // Output: Microsphere
}

Type Mismatch Example

`class Example {
    public String name = "Microsphere";
`

Example instance = new Example();
Integer value = FieldUtils.getFieldValue(instance, "name", Integer.class);
System.out.println(value);  // Output: null (field type does not match)
}

getFieldValue

public static <V> V getFieldValue(boolean forceAccess, @Nonnull Object instance, @Nonnull String fieldName, @Nonnull Class<V> fieldType)

Retrieves the value of a field with the specified name and type from the given object instance, optionally forcing accessibility.

This variant is useful when the field may be non-public and you want to verify the field type before reading its value.

Example Usage

`class Example {
    private String secret = "typed";
`

Example instance = new Example();
String value = FieldUtils.getFieldValue(true, instance, "secret", String.class);
System.out.println(value);  // Output: typed
}

getFieldValue

public static <V> V getFieldValue(@Nullable Object instance, @Nullable Field field)

Retrieves the value of the specified Field from the given object instance.

This is a convenience overload of #getFieldValue(boolean, Object, Field) with forceAccess=false. Use this method when the field is already accessible, or when you are reading public members.

Example Usage

`class Example {
    public String name = "Microsphere";
`

Example instance = new Example();
Field field = FieldUtils.findField(instance, "name");
String value = FieldUtils.getFieldValue(instance, field);
System.out.println(value);  // Output: Microsphere
}

Null Field Handling

`Example instance = new Example();
String value = FieldUtils.getFieldValue(instance, (Field) null);
System.out.println(value);  // Output: null
`

---

This documentation was auto-generated from the source code of microsphere-java.