This is the core dependency of KavaRef, and you need to introduce this module to use the basic features of KavaRef.
You can add this module to your project using the following method.
Add dependency in your project's SweetDependency configuration file.
libraries:
com.highcapable.kavaref:
kavaref-core:
version: +
Configure dependency in your project's build.gradle.kts.
implementation(com.highcapable.kavaref.kavaref.core)
Add dependency in your project's gradle/libs.versions.toml.
[versions]
kavaref-core = "<version>"
[libraries]
kavaref-core = { module = "com.highcapable.kavaref:kavaref-core", version.ref = "kavaref-core" }
Configure dependency in your project's build.gradle.kts.
implementation(libs.kavaref.core)
Please change <version> to the version displayed at the top of this document.
Configure dependency in your project's build.gradle.kts.
implementation("com.highcapable.kavaref:kavaref-core:<version>")
Please change <version> to the version displayed at the top of this document.
KavaRef adopts a chained call design, which creates extension methods for available Java reflection APIs (such as Class). You only need to call resolve() to these contents to enter the world of KavaRef.
The relationship diagram is as follows.
KavaRef
└── KClass/Class.resolve()
├── method()
├── constructor()
└── field()
Next, we will give multiple examples of Java Class, which will be explained based on them in the future.
package com.demo;
public class BaseTest {
public BaseTest() {
// ...
}
private void doBaseTask(String taskName) {
// ...
}
}
package com.demo;
public class Test extends BaseTest {
private Test() {
// ...
}
private static TAG = "Test";
private boolean isTaskRunning = false;
private void doTask(String taskName) {
// ...
}
private void release(String taskName, Function<boolean, String> task, boolean isFinish) {
// ...
}
private void stop() {
// ...
}
private String getName() {
// ...
}
}
public class Box<T> {
public void print(T item, String str) {
// ...
}
}
Suppose we want to get the doTask method of Test and execute it. In KavaRef, you can do it in the following way.
The following example
// Suppose this is an instance of this Class.
val test: Test
// Reflect it by instantiating Class.
// In KavaRef you don't need to convert it to \`java.lang.Class\`,
// it will automatically call KClass.java.
Test::class
// Create KavaRef reflections.
.resolve()
// Create method condition.
.method {
// Set method name.
name = "doTask"
// Set method parameter type.
parameters(String::class)
}
// After the condition is executed, the matching List<MethodResolver>
// instance will be returned.
// Here we get the first filtering result.
.first()
// Set an instance of Test on MethodResolver.
.of(test)
// Call the method and pass in parameters.
.invoke("task_name")
In the above writing method, we use Test::class.resolve() to get the KavaRef reflection instance of the current Class. Then create a method filtering condition MethodCondition using method { ... }, which sets the method name and parameter type, and returns the List<MethodResolver> instance after execution. Then we use first() to get the first matched MethodResolver instance, then use of(test) to set the current instance of Class, and finally use invoke("task_name") to execute the method and pass in the parameters.
In this, MethodCondition is inherited from MemberCondition, which allows you to conditionally filter the Method, containing a conditional image of the Java-core reflection API. You can view the corresponding comments to understand the native usage of each API.
Similarly, MethodResolver is inherited from MemberResolver, which allows you to make reflection calls to Method in the filtered result.
Since the reflection requirement here is to obtain an available method result, the call chain of method { ... }.first() may be more cumbersome, so there is the following simplified solution.
The following example
Test::class
.resolve()
// Use firstMethod directly to get the first matching
// MethodResolver instance.
.firstMethod {
name = "doTask"
parameters(String::class)
}
.of(test)
.invoke("task_name")
Since we can now get an instance of Test, there is also a simplified way to write this: you can use this instance to create KavaRef reflections directly.
The following example
// Here, the test instance test will be passed to
// KavaRef and get test::class.java.
test.asResolver()
.firstMethod {
name = "doTask"
parameters(String::class)
} // Since you set up an instance, of(test) is no longer needed here.
.invoke("task_name")
Next, we need to get the isTaskRunning variable, which can be written in the following form.
The following example
// Suppose this is an instance of this Class.
val test: Test
// Call and execute with KavaRef.
val isTaskRunning = test.asResolver()
.firstField {
name = "isTaskRunning"
type = Boolean::class
}.get<Boolean>()
The constructor in Test is private, and now we can create an instance of it using the following method.
The following example
val test = Test::class.resolve()
.firstConstructor {
// For the zero parameter constructor,
// the following condition can be used to filter.
// It is equivalent to parameterCount = 0.
emptyParameters()
}.create() // Create a new Test instance.
You can also use createAsType<T>() to specify its superclass type BaseTest for the actual object Test.
The following example
val test = Test::class.resolve()
.firstConstructor {
emptyParameters()
}.createAsType<BaseTest>() // Create a new BaseTest instance.
Tips
In addition to methods such as firstMethod, you can also use methods such as lastMethod to get the last matching MethodResolver instance, which is equivalent to method { ... }.last().
After you get the MemberResolver instance, you can use self to get the Member original instance of the current MemberResolver to do some of your own operations.
In MemberResolver inherited from InstanceAwareResolver (for example MethodResolver and FieldResolver), you can use of(instance) to set the current instance. If the reflection is a static member, you do not need to set the instance.
Notice
The Any.resolve() function has been deprecated in version 1.0.1 because it pollutes the namespace (for example File.resolve("/path/to/file")), and now use Any.asResolver() instead.
Pay Attention
In MemberResolver inherited from InstanceAwareResolver, the type of of(instance) requires the same type as the currently reflected Class instance generic type. Unless the Class generic type is not specified, or the Class generic type is set to Any.
If of(instance) shows a Required: Nothing? error (this is usually due to Class created via Class.forName(...) or ClassLoader.loadClass(...)), then your Class is Class<*> (in Java it is Class<?>). At this time, if you do not want to specify the type, please set or convert it to Class<Any>, as follows.
The following example
val myClass = Class.forName("com.xxx.MyClass") as Class<Any>
// Suppose this is an instance of this Class.
val myClassInstance: Any
myClass.resolve()
.firstMethod {
// ...
}.of(myClassInstance).invoke(...)
You will notice that there is a release method in Test, but its method parameters are very long and some types may not be directly obtainable.
At this point, you can use the parameters(...) condition with VagueType to fill in the method parameter types you don't want to specify.
The following example
// Suppose this is an example of this Class.
val test: Test
// Call and execute with KavaRef.
Test::class.resolve()
.firstMethod {
name = "release"
// Use VagueType to fill in the types you don't want to fill in,
// and ensure that other types can match.
parameters(String::class, VagueType, Boolean::class)
} // Get this method.
Notice
VagueType can only be used when there are filter conditions with multiple parameters, it cannot be used in filter conditions with only a single parameter, such as type.
You can create it using VagueType, VagueType::class or VagueType::class.java, all of which are correctly recognized as fuzzy filtering conditions.
In MemberCondition, name, type, parameterCount and other conditions can all use the Kotlin lambda feature to create free filtering conditions.
Suppose we want to get the doTask method in Test, we can use the following implementation.
The following example
// Suppose this is an example of this Class.
val test: Test
// Call and execute with KavaRef.
Test::class.resolve()
.firstMethod {
// Use lambda to set the method name.
name {
// Set the name not case sensitive.
it.equals("dotask", ignoreCase = true)
}
// Set parameter type.
parameters(String::class)
}.of(test).invoke("task_name")
KavaRef supports adding generic filtering conditions, which you can use the relevant functions provided by TypeMatcher.
Suppose we need to filter the print method in Box<String>.
The following example
// Suppose this is an example of this Class.
val box: Box<String>
// Call and execute with KavaRef.
box.asResolver()
.firstMethod {
name = "print"
// Set generic parameter conditions.
genericParametes(
// Filter generic name "T".
typeVar("T"),
// Create TypeMatcher through Class.
String::class.toTypeMatcher()
)
}.invoke("item", "str")
You will notice that Test inherits from BaseTest, and now we want to get the doBaseTask method of BaseTest.
Without knowing the superclass name, we only need to add superclass() to the filter condition to achieve this function.
The following example
// Suppose this is an example of this Class.
val test: Test
// Call and execute with KavaRef.
Test::class.resolve()
.firstMethod {
name = "doBaseTask"
parameters(String::class)
// Just add this condition.
superclass()
}.of(test).invoke("task_name")
At this time, we can get this method in the superclass.
Tips
superclass() once set it,it will automatically loop backwards whether there is this method in all inherited superclasses until the target has no superclass (the inheritance relationship is java.lang.Object).
Pay Attention
The current filtering method can only filter to the current Class method unless the superclass() condition is specified, which is the default behavior of the Java reflection API. KavaRef will call Class.getDeclaredMethods() to get the current Class method instead of Class.getMethods().
KavaRef provides some filtering conditions to assist in the use of the Java reflection API.
Suppose we want to get the contents of the static variable TAG in Test.
In order to reflect that the filtering conditions include static descriptors, we can implement them using the following methods.
The following example
val tag = Test::class.resolve()
.firstField {
name = "TAG"
type = String::class
// Create descriptor filtering.
modifiers(Modifiers.STATIC)
// Or.
modifiers {
it.contains(Modifiers.STATIC)
}
}.get<String>() // Get field content.
You can also use string types to pass in full class names in conditions such as type, parameters, etc.
The following example
// Suppose this is an example of this Class.
val test: Test
// Call and execute with KavaRef.
Test::class.resolve()
.firstMethod {
name = "doTask"
// Pass the full class name using string type.
parameters("java.lang.String")
}.of(test).invoke("task_name")
By default, KavaRef throws an exception when a member is not found during a reflection call.
The following example
Test::class.resolve()
.method {
name = "doNonExistentMethod"
} // NoSuchMethodException will be thrown here.
If you do not want an exception to be thrown, you can set the optional condition optional().
The following example
Test::class.resolve()
// Set optional conditions.
.optional()
.method {
name = "doNonExistentMethod"
} // Return empty List<MethodResolver>.
KavaRef prints the complete exception content for debugging, and when using optional(), the exception is printed as a WARN level log.
The following example
No method found matching the condition for current class.
+------------------------------------------------+
| class com.demo |
+------------+-----------------------------------+
| name | doNonExistentMethod |
| parameters | [class java.lang.String, boolean] |
+------------+-----------------------------------+
If you don't want KavaRef to throw or print anything, you can use optional(silent = true) to silently handle it, but we do not recommend this, which will mask the problem unless it is necessary.
Pay Attention
If you set optional(), please do not use firstMethod, firstConstructor and other methods to get a single result. Because they throw an exception with empty list when there is no result, you can use the method with the suffix OrNull to get a single result.
But one thing you need to pay attention to here is that if you do not set optional(), then methods such as firstMethodOrNull will still throw exceptions when there is no result**, which is the expected behavior because method { ... } This is the "build" operation of the filter. Exceptions are handled here. Methods such as firstMethodOrNull are just an encapsulation. It is an exception handling of Kotlin's own standard library whether the result List is empty. It does not participate in exception handling of KavaRef filters.
So you must do it like the following.
The following example
Test::class.resolve()
// Set optional conditions.
.optional()
.firstMethodOrNull {
name = "doNonExistentMethod"
} // Return MethodResolver or null.
KavaRef provides its own log management function, you can set the log level through KavaRef.logLevel.
You can set KavaRef.logLevel = KavaRefRuntime.LogLevel.DEBUG to enable DEBUG level logs so that KavaRef prints more detailed step-by-step filtering condition logs to the console during the filtering process.
If you want to turn off all log printing of KavaRef, you can set KavaRef.logLevel = KavaRefRuntime.LogLevel.OFF.
If you have more advanced requirements, you can implement KavaRefRuntime.Logger to customize your own log printing method.
The following example
class MyLogger : KavaRefRuntime.Logger {
// Here you can specify the tag for log printing.
override val tag = "MyLogger"
override fun debug(msg: Any?, throwable: Throwable?) {
// Implement your log printing logic here.
}
override fun info(msg: Any?, throwable: Throwable?) {
// Implement your log printing logic here.
}
override fun warn(msg: Any?, throwable: Throwable?) {
// Implement your log printing logic here.
}
override fun error(msg: Any?, throwable: Throwable?) {
// Implement your log printing logic here.
}
}
Then, set it to KavaRef.
The following example
KavaRef.setLogger(MyLogger())
The above content explains all the usage methods in standard scenarios. If you have a more fine-grained usage scenario, you can manually create related components of KavaRef.
If you don't like the Kotlin lambda writing, you can create chained calls manually.
The following example
// Suppose this is an example of this Class.
val test: Test
// Call and execute with KavaRef.
Test::class.resolve()
.method() // Conditions begin.
.name("doTask")
.parameters(String::class)
.build() // Conditions ends (executes)
.first()
.of(test) // Setting up instance.
.invoke("task_name")
You can also manually create any filtering conditions to achieve multiplexing it in any reflection.
The following example
// Suppose this is an example of this Class.
val test: Test
// Create MethodCondition manually.
val condition = MethodCondition<Test>()
condition.name = "doTask"
condition.parameters(String::class)
// Apply condition to reflection object.
Test::class.resolve()
.firstMethod(condition)
.of(test) // Setting up instance.
.invoke("task_name")
Alternatively, you can also manually and completely implement the entire reflection process.
The following example
// Suppose this is an example of this Class.
val test: Test
// Create MethodCondition manually.
val condition = MethodCondition<Test>()
condition.name = "doTask"
condition.parameters(String::class)
// Create MemberCondition.Configuration manually.
val configuration = Test::class.java.createConfiguration(
memberInstance = test, // Setting up instance.
processorResolver = null, // Use the default resolver, refer to the "Custom Resolver" below.
superclass = false, // Whether to filter in superclass.
optional = MemberCondition.Configuration.Optional.NO // Configure optional conditions.
)
// Create and start filtering.
val resolvers = condition.build(configuration)
// Get the first result.
val resolver = resolvers.first()
// Execute the method.
resolver.invoke("task_name")
If you have more advanced requirements for business layer logic, you can also use mergeWith to merge multiple filter conditions.
The following example
// Suppose this is an instance of this Class.
val test: Test
// Create MethodCondition manually.
// Create the first condition.
val condition1 = MethodCondition<Test>()
condition1.name = "doTask"
// Create a second condition.
val condition2 = MethodCondition<Test>()
condition2.parameters(String::class)
// Merge condition2 into condition1.
// At this time, the condition of condition1 will contain the condition that condition2 is not null.
// The duplicated conditions in condition1 will be overwritten by the condition2 condition.
condition1.mergeWith(condition2)
// You can also use the infix syntax.
condition1 mergeWith condition2
// Call and execute with KavaRef.
Test::class.resolve()
.firstMethod(condition1)
.of(test)
.invoke("task_name")
Pay Attention
Reused use of build(...) will no longer be allowed for creation when MemberCondition.Configuration is set. At this point you need to use copy() to copy and create a new MemberCondition.
Similarly, InstanceAwareResolver is not allowed to duplicately set up new instances after setting the instance via MemberCondition.Configuration.memberInstance or of(instance). At this time, you also need to use copy() to copy and create a new InstanceAwareResolver.
KavaRef uses the default Member resolver for filtering. If you want to implement your own resolver, you can customize the global and the resolver used for each reflection process.
You can inherit from MemberProccessor.Resolver to implement your own resolver.
The following example
class MyMemberProcessorResolver : MemberProcessor.Resolver() {
override fun <T : Any> getDeclaredConstructors(declaringClass: Class<T>): List<Constructor<T>> {
// Intercept and implement your constructor filtering logic here.
return super.getDeclaredConstructors(declaringClass)
}
override fun <T : Any> getDeclaredMethods(declaringClass: Class<T>): List<Method> {
// Intercept and implement your method filtering logic here.
return super.getDeclaredMethods(declaringClass)
}
override fun <T : Any> getDeclaredFields(declaringClass: Class<T>): List<Field> {
// Intercept and implement your field filtering logic here.
return super.getDeclaredFields(declaringClass)
}
}
You can then set it to the global configuration.
The following example
MemberProcessor.globalResolver = MyMemberProcessorResolver()
Alternatively, during each reflection, you can set up a custom resolver using MemberCondition.Configuration or use a chain call to set up a resolver.
The following example
// Create resolver.
val myResolver = MyMemberProcessorResolver()
// Suppose this is an instance of this Class.
val test: Test
// Call and execute using KavaRef.
Test::class.resolve()
// Set custom resolver.
.processor(myResolver)
.firstMethod {
name = "doTask"
parameters(String::class)
}.of(test).invoke("task_name")
Due to the diversity of filtering conditions, KavaRef does not directly provide caching function, and the implementation method of caching will also vary depending on the implementation method of each developer.
We recommend manually implementing caches of MemberResolver created with filter results for improved performance and refer to Create Manually to split filter conditions to optimize code reuse.
Pay Attention
If you use val myResolver by lazy { ... } to implement the cache, for example, do so below.
The following example
val myResolver by lazy {
Test::class.resolve()
.firstMethod {
name = "doTask"
parameters(String::class)
}
}
You may do this when calling.
The following example
// Suppose this is an instance of this Class.
val test: Test
// Call and execute using KavaRef.
myResolver.of(test).invoke("task_name")
Please note that since MemberResolver is cached, the same instance is called every time you reference it, and the instance object of MemberResolver is not allowed to be set duplicately (see the "Pay Attention" below Create Manually).
So calling this directly will throw an exception, you need to change it to the following form.
The following example
// Suppose this is an instance of this Class.
val test: Test
// Call and execute using KavaRef.
myResolver.copy().of(test).invoke("task_name")
This allows you to copy a new MemberResolver instance every time you call without repeating the reflection process and throwing an exception.
KavaRef is not recommended to be used directly in Java because its API design is based on Kotlin's features and syntax sugar.
If you need to use KavaRef in Java, you can do it in the following ways.
The following example
public class Main {
public static void main(String[] args) {
// Suppose this is an example of this Class.
Test test;
// Call and execute with KavaRef.
KavaRef.resolveClass(Test.class)
.method()
.name("doTask")
.parameters(String.class)
.build()
.get(0)
.of(test)
.invoke("task_name");
// Or create KavaRef reflections using an instance.
KavaRef.resolveObject(test)
.method()
.name("doTask")
.parameters(String.class)
.build()
.get(0)
.invoke("task_name");
}
}