diff --git a/docs-source/src/en/index.md b/docs-source/src/en/index.md index a9e0ad4..178d5bc 100644 --- a/docs-source/src/en/index.md +++ b/docs-source/src/en/index.md @@ -31,8 +31,10 @@ public class World { ``` ```kotlin -World().resolve().firstMethod { +val myWorld = World() + +World::class.resolve().firstMethod { name = "sayHello" parameters(String::class) -}.invoke("KavaRef") +}.of(myWorld).invoke("KavaRef") ``` \ No newline at end of file diff --git a/docs-source/src/en/library/kavaref-core.md b/docs-source/src/en/library/kavaref-core.md index 08d2710..e65eed6 100644 --- a/docs-source/src/en/library/kavaref-core.md +++ b/docs-source/src/en/library/kavaref-core.md @@ -70,7 +70,7 @@ The relationship diagram is as follows. ``` :no-line-numbers KavaRef -└── KClass/Class/Any.resolve() +└── KClass/Class.resolve() ├── method() ├── constructor() └── field() @@ -199,7 +199,7 @@ you can use this instance to create KavaRef reflections directly. ```kotlin // Here, the test instance test will be passed to // KavaRef and get test::class.java. -test.resolve() +test.asResolver() .firstMethod { name = "doTask" parameters(String::class) @@ -215,7 +215,7 @@ Next, we need to get the `isTaskRunning` variable, which can be written in the f // Suppose this is an example of this Class. val test: Test // Call and execute with KavaRef. -val isTaskRunning = test.resolve() +val isTaskRunning = test.asResolver() .firstField { name = "isTaskRunning" type = Boolean::class @@ -258,6 +258,12 @@ To set the current instance, if the reflection is static (static) member, you do ::: +::: warning + +The `Any.resolve()` function has been deprecated in `1.0.1` version because it pollutes the namespace (for example `File.resolve("/path/to/file")`), and now use `Any.asResolver()` instead. + +::: + ::: danger In `MemberResolver` inherited from `InstanceAwareResolver`, the type of `of(instance)` requires the same type as the currently reflected `Class` instance generic type. @@ -295,7 +301,7 @@ At this point, you can use the `parameters(...)` condition to use `VagueType` to // Suppose this is an example of this Class. val test: Test // Call and execute with KavaRef. -test.resolve() +Test::class.resolve() .firstMethod { name = "release" // Use VagueType to fill in the types you don't want to fill in, @@ -325,7 +331,7 @@ Suppose we want to get the `doTask` method in `Test`, we can use the following i // Suppose this is an example of this Class. val test: Test // Call and execute with KavaRef. -test.resolve() +Test::class.resolve() .firstMethod { // Use lambda to set the method name. name { @@ -334,7 +340,7 @@ test.resolve() } // Set parameter type. parameters(String::class) - }.invoke("task_name") + }.of(test).invoke("task_name") ``` ### Generic Conditions @@ -349,7 +355,7 @@ Suppose we need to filter the `print` method in `Box`. // Suppose this is an example of this Class. val box: Box // Call and execute with KavaRef. -box.resolve() +box.asResolver() .firstMethod { name = "print" // Set generic parameter conditions. @@ -374,13 +380,13 @@ Without knowing the superclass name, we only need to add `superclass()` to the f // Suppose this is an example of this Class. val test: Test // Call and execute with KavaRef. -test.resolve() +Test::class.resolve() .firstMethod { name = "doBaseTask" parameters(String::class) // Just add this condition. superclass() - }.invoke("task_name") + }.of(test).invoke("task_name") ``` At this time, we can get this method in the superclass. @@ -432,12 +438,12 @@ You can also use string types to pass in full class names in conditions such as // Suppose this is an example of this Class. val test: Test // Call and execute with KavaRef. -test.resolve() +Test::class.resolve() .firstMethod { name = "doTask" // Pass the full class name using string type. parameters("java.lang.String") - }.invoke("task_name") + }.of(test).invoke("task_name") ``` ### Exception Handling @@ -568,12 +574,13 @@ If you don't like the Kotlin lambda writing, you can create chained calls manual // Suppose this is an example of this Class. val test: Test // Call and execute with KavaRef. -test.resolve() +Test::class.resolve() .method() // Conditions begin. .name("doTask") .parameters(String::class) .build() // Conditions ends (executes) .first() + .of(test) // Setting up instance. .invoke("task_name") ``` @@ -705,13 +712,13 @@ val myResolver = MyMemberProcessorResolver() // Suppose this is an instance of this Class. val test: Test // Call and execute using KavaRef. -test.resolve() +Test::class.resolve() // Set custom resolver. .processor(myResolver) .firstMethod { name = "doTask" parameters(String::class) - }.invoke("task_name") + }.of(test).invoke("task_name") ``` ::: tip diff --git a/docs-source/src/zh-cn/index.md b/docs-source/src/zh-cn/index.md index 257b435..180a0b9 100644 --- a/docs-source/src/zh-cn/index.md +++ b/docs-source/src/zh-cn/index.md @@ -31,8 +31,10 @@ public class World { ``` ```kotlin -World().resolve().firstMethod { +val myWorld = World() + +World::class.resolve().firstMethod { name = "sayHello" parameters(String::class) -}.invoke("KavaRef") +}.of(myWorld).invoke("KavaRef") ``` \ No newline at end of file diff --git a/docs-source/src/zh-cn/library/kavaref-core.md b/docs-source/src/zh-cn/library/kavaref-core.md index 90381f2..c469791 100644 --- a/docs-source/src/zh-cn/library/kavaref-core.md +++ b/docs-source/src/zh-cn/library/kavaref-core.md @@ -69,7 +69,7 @@ KavaRef 采用链式调用的设计方案，它对可用的 Java 反射 API (例 ``` :no-line-numbers KavaRef -└── KClass/Class/Any.resolve() +└── KClass/Class.resolve() ├── method() ├── constructor() └── field() @@ -192,7 +192,7 @@ Test::class ```kotlin // 在这里，Test 的实例 test 会被传给 KavaRef 并获取 test::class.java -test.resolve() +test.asResolver() .firstMethod { name = "doTask" parameters(String::class) @@ -208,7 +208,7 @@ test.resolve() // 假设这就是这个 Class 的实例 val test: Test // 使用 KavaRef 调用并执行 -val isTaskRunning = test.resolve() +val isTaskRunning = test.asResolver() .firstField { name = "isTaskRunning" type = Boolean::class @@ -250,6 +250,12 @@ val test = Test::class.resolve() ::: +::: warning + +`Any.resolve()` 方法已在 `1.0.1` 版本被弃用，因为它会污染命名空间 (例如 `File.resolve("/path/to/file")`)，现在请使用 `Any.asResolver()` 来代替。 + +::: + ::: danger 在继承于 `InstanceAwareResolver` 的 `MemberResolver` 中，`of(instance)` 的类型要求与当前反射的 `Class` 实例泛型类型相同， @@ -286,7 +292,7 @@ myClass.resolve() // 假设这就是这个 Class 的实例 val test: Test // 使用 KavaRef 调用并执行 -test.resolve() +Test::class.resolve() .firstMethod { name = "release" // 使用 VagueType 来填充不想填写的类型，同时保证其它类型能够匹配 @@ -314,7 +320,7 @@ test.resolve() // 假设这就是这个 Class 的实例 val test: Test // 使用 KavaRef 调用并执行 -test.resolve() +Test::class.resolve() .firstMethod { // 使用 lambda 来设置方法名 name { @@ -323,7 +329,7 @@ test.resolve() } // 设置参数类型 parameters(String::class) - }.invoke("task_name") + }.of(test).invoke("task_name") ``` ### 泛型条件 @@ -338,7 +344,7 @@ KavaRef 支持添加泛型过滤条件，你可以使用 `TypeMatcher` 提供的 // 假设这就是这个 Class 的实例 val box: Box // 使用 KavaRef 调用并执行 -box.resolve() +box.asResolver() .firstMethod { name = "print" // 设置泛型参数条件 @@ -363,13 +369,13 @@ box.resolve() // 假设这就是这个 Class 的实例 val test: Test // 使用 KavaRef 调用并执行 -test.resolve() +Test::class.resolve() .firstMethod { name = "doBaseTask" parameters(String::class) // 只需要添加这个条件 superclass() - }.invoke("task_name") + }.of(test).invoke("task_name") ``` 这个时候我们就可以在超类中获取到这个方法了。 @@ -419,12 +425,12 @@ val tag = Test::class.resolve() // 假设这就是这个 Class 的实例 val test: Test // 使用 KavaRef 调用并执行 -test.resolve() +Test::class.resolve() .firstMethod { name = "doTask" // 使用字符串类型传入完整类名 parameters("java.lang.String") - }.invoke("task_name") + }.of(test).invoke("task_name") ``` ### 异常处理 @@ -548,12 +554,13 @@ KavaRef.setLogger(MyLogger()) // 假设这就是这个 Class 的实例 val test: Test // 使用 KavaRef 调用并执行 -test.resolve() +Test::class.resolve() .method() // 条件开始 .name("doTask") .parameters(String::class) .build() // 条件结束 (执行) .first() + .of(test) // 设置实例 .invoke("task_name") ``` @@ -684,13 +691,13 @@ val myResolver = MyMemberProcessorResolver() // 假设这就是这个 Class 的实例 val test: Test // 使用 KavaRef 调用并执行 -test.resolve() +Test::class.resolve() // 设置自定义解析器 .processor(myResolver) .firstMethod { name = "doTask" parameters(String::class) - }.invoke("task_name") + }.of(test).invoke("task_name") ``` ::: tip diff --git a/kavaref-core/src/main/kotlin/com/highcapable/kavaref/KavaRef.kt b/kavaref-core/src/main/kotlin/com/highcapable/kavaref/KavaRef.kt index dac05cf..79521cb 100644 --- a/kavaref-core/src/main/kotlin/com/highcapable/kavaref/KavaRef.kt +++ b/kavaref-core/src/main/kotlin/com/highcapable/kavaref/KavaRef.kt @@ -83,6 +83,15 @@ class KavaRef private constructor() { @JvmName("resolveClass") fun Class.resolve() = MemberScope(createConfiguration()) + /** + * Create a [MemberScope] instance to start a new reflection. + * + * This function has been deprecated due to naming pollution, use [asResolver] instead. + * @return [MemberScope] + */ + @Deprecated(message = "Use asResolver() instead.", replaceWith = ReplaceWith("this.asResolver()")) + fun T.resolve() = asResolver() + /** * Create a [MemberScope] instance to start a new reflection. * @see KClass.resolve @@ -91,44 +100,72 @@ class KavaRef private constructor() { */ @JvmStatic @JvmName("resolveObject") - fun T.resolve() = when (this) { + fun T.asResolver() = when (this) { is KClass<*> -> MemberScope((this as KClass).java.createConfiguration(memberInstance = this)) is Class<*> -> MemberScope((this as Class).createConfiguration(memberInstance = this)) else -> MemberScope(javaClass.createConfiguration(memberInstance = this)) } - // Below are deprecated functions to prevent recursive calls. + // Below are deprecated functions to prevent internal calls. - private const val RECURSIVELY_CALL_DEPRECATED_MESSAGE = "You are calling resolve() recursively, it's an error and should delete it." - private const val RECURSIVELY_CALL_EXCEPTION_MESSAGE = "Not allowed to call resolve() recursively, please delete it." + private const val DEPRECATED_MESSAGE = "You are calling asResolver() in KavaRef internal component, it's an error and should delete it." + private const val EXCEPTION_MESSAGE = "Not allowed to call asResolver() in KavaRef internal component, please delete it." /** - * This is a fake function call chains to avoid recursive calls to themselves. + * This is a fake function call chains to avoid internal calls to themselves. */ - @Deprecated(message = RECURSIVELY_CALL_DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) + @Deprecated(message = DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) @JvmSynthetic - fun MemberScope<*>.resolve(): MemberScope<*> = error(RECURSIVELY_CALL_EXCEPTION_MESSAGE) + fun MemberScope<*>.asResolver(): MemberScope<*> = error(EXCEPTION_MESSAGE) /** - * This is a fake function call chains to avoid recursive calls to themselves. + * This is a fake function call chains to avoid internal calls to themselves. */ - @Deprecated(message = RECURSIVELY_CALL_DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) + @Deprecated(message = DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) @JvmSynthetic - fun MemberCondition<*, *, *>.resolve(): MemberCondition<*, *, *> = error(RECURSIVELY_CALL_EXCEPTION_MESSAGE) + fun MemberScope<*>.resolve(): MemberScope<*> = error(EXCEPTION_MESSAGE) /** - * This is a fake function call chains to avoid recursive calls to themselves. + * This is a fake function call chains to avoid internal calls to themselves. */ - @Deprecated(message = RECURSIVELY_CALL_DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) + @Deprecated(message = DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) @JvmSynthetic - fun MemberResolver<*, *>.resolve(): MemberResolver<*, *> = error(RECURSIVELY_CALL_EXCEPTION_MESSAGE) + fun MemberCondition<*, *, *>.asResolver(): MemberCondition<*, *, *> = error(EXCEPTION_MESSAGE) /** - * This is a fake function call chains to avoid recursive calls to themselves. + * This is a fake function call chains to avoid internal calls to themselves. */ - @Deprecated(message = RECURSIVELY_CALL_DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) + @Deprecated(message = DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) @JvmSynthetic - fun List>.resolve(): List> = error(RECURSIVELY_CALL_EXCEPTION_MESSAGE) + fun MemberCondition<*, *, *>.resolve(): MemberCondition<*, *, *> = error(EXCEPTION_MESSAGE) + + /** + * This is a fake function call chains to avoid internal calls to themselves. + */ + @Deprecated(message = DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) + @JvmSynthetic + fun MemberResolver<*, *>.asResolver(): MemberResolver<*, *> = error(EXCEPTION_MESSAGE) + + /** + * This is a fake function call chains to avoid internal calls to themselves. + */ + @Deprecated(message = DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) + @JvmSynthetic + fun MemberResolver<*, *>.resolve(): MemberResolver<*, *> = error(EXCEPTION_MESSAGE) + + /** + * This is a fake function call chains to avoid internal calls to themselves. + */ + @Deprecated(message = DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) + @JvmSynthetic + fun List>.asResolver(): List> = error(EXCEPTION_MESSAGE) + + /** + * This is a fake function call chains to avoid internal calls to themselves. + */ + @Deprecated(message = DEPRECATED_MESSAGE, level = DeprecationLevel.ERROR) + @JvmSynthetic + fun List>.resolve(): List> = error(EXCEPTION_MESSAGE) } /**