Merge pull request #569 from permissions-dispatcher/fix_434

OnShowRationale API change with keeping backward compatibilty

Author: hotchemi

doc/java_usage.md

@@ -18,7 +18,7 @@ PermissionsDispatcher introduces only a few annotations, keeping its general API
 |---|---|---|
 |`@RuntimePermissions`|**✓**|Register an `Activity` or `Fragment`(we support both) to handle permissions|
 |`@NeedsPermission`|**✓**|Annotate a method which performs the action that requires one or more permissions|
-|`@OnShowRationale`||Annotate a method which explains why the permission/s is/are needed. It passes in a `PermissionRequest` object which can be used to continue or abort the current permission request upon user input|
+|`@OnShowRationale`||Annotate a method which explains why the permissions are needed. It passes in a `PermissionRequest` object which can be used to continue or abort the current permission request upon user input. If you don't specify any argument for the method compiler will generate `process${NeedsPermissionMethodName}ProcessRequest` and `cancel${NeedsPermissionMethodName}ProcessRequest`. You can use those methods in place of `PermissionRequest`(ex: with `DialogFragment`)|
 |`@OnPermissionDenied`||Annotate a method which is invoked if the user doesn't grant the permissions|
 |`@OnNeverAskAgain`||Annotate a method which is invoked if the user chose to have the device "never ask again" about a permission|
 

doc/kotlin_usage.md

@@ -2,16 +2,26 @@
 
 Here's a minimum example, in which you register a `MainActivity` which requires `Manifest.permission.CAMERA`.
 
-### 0. Preparation
+### 0. Prepare AndroidManifest
 
 Add the following line to `AndroidManifest.xml`:
 
 `<uses-permission android:name="android.permission.CAMERA" />`
 
 ### 1. Attach annotations
 
+PermissionsDispatcher introduces only a few annotations, keeping its general API concise:
+
 > NOTE: Annotated methods must not be `private`.
 
+|Annotation|Required|Description|
+|---|---|---|
+|`@RuntimePermissions`|**✓**|Register an `Activity` or `Fragment`(we support both) to handle permissions|
+|`@NeedsPermission`|**✓**|Annotate a method which performs the action that requires one or more permissions|
+|`@OnShowRationale`||Annotate a method which explains why the permissions are needed. It passes in a `PermissionRequest` object which can be used to continue or abort the current permission request upon user input. If you don't specify any argument for the method compiler will generate `process${NeedsPermissionMethodName}ProcessRequest` and `cancel${NeedsPermissionMethodName}ProcessRequest`. You can use those methods in place of `PermissionRequest`(ex: with `DialogFragment`)|
+|`@OnPermissionDenied`||Annotate a method which is invoked if the user doesn't grant the permissions|
+|`@OnNeverAskAgain`||Annotate a method which is invoked if the user chose to have the device "never ask again" about a permission|
+
 ```kotlin
 @RuntimePermissions
 class MainActivity : AppCompatActivity(), View.OnClickListener {

processor/src/main/kotlin/permissions/dispatcher/processor/PermissionsProcessor.kt

@@ -8,7 +8,6 @@ import permissions.dispatcher.processor.util.kotlinMetadataClass
 import java.io.File
 import javax.annotation.processing.AbstractProcessor
 import javax.annotation.processing.Filer
-import javax.annotation.processing.Messager
 import javax.annotation.processing.ProcessingEnvironment
 import javax.annotation.processing.RoundEnvironment
 import javax.lang.model.SourceVersion
@@ -33,12 +32,10 @@ class PermissionsProcessor : AbstractProcessor() {
 
     /* Processing Environment helpers */
     private var filer: Filer by Delegates.notNull()
-    var messager: Messager by Delegates.notNull()
 
     override fun init(processingEnv: ProcessingEnvironment) {
         super.init(processingEnv)
         filer = processingEnv.filer
-        messager = processingEnv.messager
         ELEMENT_UTILS = processingEnv.elementUtils
         TYPE_UTILS = processingEnv.typeUtils
     }
@@ -86,13 +83,13 @@ class PermissionsProcessor : AbstractProcessor() {
             kaptGeneratedDir.parentFile.mkdirs()
         }
 
-        val processorUnit = findAndValidateProcessorUnit(kotlinProcessorUnits(), element)
+        val processorUnit = findAndValidateProcessorUnit(kotlinProcessorUnits, element)
         val kotlinFile = processorUnit.createFile(rpe, requestCodeProvider)
         kotlinFile.writeTo(kaptGeneratedDir)
     }
 
     private fun processJava(element: Element, rpe: RuntimePermissionsElement, requestCodeProvider: RequestCodeProvider) {
-        val processorUnit = findAndValidateProcessorUnit(javaProcessorUnits(), element)
+        val processorUnit = findAndValidateProcessorUnit(javaProcessorUnits, element)
         val javaFile = processorUnit.createFile(rpe, requestCodeProvider)
         javaFile.writeTo(filer)
     }

processor/src/main/kotlin/permissions/dispatcher/processor/ProcessorUnit.kt

@@ -6,6 +6,11 @@ import javax.lang.model.type.TypeMirror
 
 interface ProcessorUnit<out K> {
     fun getTargetType(): TypeMirror
+    /**
+     * Creates the File for the provided @RuntimePermissions element.
+     * <p>
+     * This will delegate to other methods that compose generated code.
+     */
     fun createFile(rpe: RuntimePermissionsElement, requestCodeProvider: RequestCodeProvider): K
 }
 

processor/src/main/kotlin/permissions/dispatcher/processor/RuntimePermissionsElement.kt

@@ -32,8 +32,6 @@ class RuntimePermissionsElement(val e: TypeElement) {
         validateNeverAskMethods()
     }
 
-    /* Begin private */
-
     private fun validateNeedsMethods() {
         checkNotEmpty(needsElements, this, NeedsPermission::class.java)
         checkPrivateMethods(needsElements, NeedsPermission::class.java)
@@ -64,8 +62,6 @@ class RuntimePermissionsElement(val e: TypeElement) {
         checkSpecialPermissionsWithNeverAskAgain(onNeverAskElements)
     }
 
-    /* Begin public */
-
     fun findOnRationaleForNeeds(needsElement: ExecutableElement): ExecutableElement? {
         return findMatchingMethodForNeeds(needsElement, onRationaleElements, OnShowRationale::class.java)
     }

processor/src/main/kotlin/permissions/dispatcher/processor/exception/WrongParametersException.kt

@@ -4,4 +4,4 @@ import permissions.dispatcher.processor.util.simpleString
 import javax.lang.model.element.ExecutableElement
 import javax.lang.model.type.TypeMirror
 
-class WrongParametersException(e: ExecutableElement, requiredType: TypeMirror?) : RuntimeException("Method '${e.simpleString()}()' must declare parameters of type '${requiredType?.simpleString()}'")
+class WrongParametersException(e: ExecutableElement, numParams: Int, requiredType: TypeMirror) : RuntimeException("Method '${e.simpleString()}()' must has less than or equal to $numParams size parameter and type of it is supposed to be '${requiredType.simpleString()}'")

processor/src/main/kotlin/permissions/dispatcher/processor/impl/ProcessorUnits.kt

@@ -5,10 +5,5 @@ import permissions.dispatcher.processor.impl.java.JavaFragmentProcessorUnit
 import permissions.dispatcher.processor.impl.kotlin.KotlinActivityProcessorUnit
 import permissions.dispatcher.processor.impl.kotlin.KotlinFragmentProcessorUnit
 
-fun javaProcessorUnits() = listOf(
-        JavaActivityProcessorUnit(),
-        JavaFragmentProcessorUnit())
-
-fun kotlinProcessorUnits() = listOf(
-        KotlinActivityProcessorUnit(),
-        KotlinFragmentProcessorUnit())
+val javaProcessorUnits = listOf(JavaActivityProcessorUnit(), JavaFragmentProcessorUnit())
+val kotlinProcessorUnits = listOf(KotlinActivityProcessorUnit(), KotlinFragmentProcessorUnit())

processor/src/main/kotlin/permissions/dispatcher/processor/impl/java/JavaActivityProcessorUnit.kt

@@ -6,27 +6,19 @@ import permissions.dispatcher.processor.util.typeMirrorOf
 import javax.lang.model.type.TypeMirror
 
 /**
- * ProcessorUnit implementation for Activity classes.
+ * ProcessorUnit implementation for Activity.
  */
 class JavaActivityProcessorUnit : JavaBaseProcessorUnit() {
 
-    private val ACTIVITY_COMPAT = ClassName.get("androidx.core.app", "ActivityCompat")
+    override fun getTargetType(): TypeMirror = typeMirrorOf("android.app.Activity")
 
-    override fun isDeprecated(): Boolean = false
-
-    override fun getTargetType(): TypeMirror {
-        return typeMirrorOf("android.app.Activity")
-    }
-
-    override fun getActivityName(targetParam: String): String {
-        return targetParam
-    }
+    override fun getActivityName(targetParam: String): String = targetParam
 
     override fun addShouldShowRequestPermissionRationaleCondition(builder: MethodSpec.Builder, targetParam: String, permissionField: String, isPositiveCondition: Boolean) {
         builder.beginControlFlow("if (\$N\$T.shouldShowRequestPermissionRationale(\$N, \$N))", if (isPositiveCondition) "" else "!", PERMISSION_UTILS, targetParam, permissionField)
     }
 
     override fun addRequestPermissionsStatement(builder: MethodSpec.Builder, targetParam: String, permissionField: String, requestCodeField: String) {
-        builder.addStatement("\$T.requestPermissions(\$N, \$N, \$N)", ACTIVITY_COMPAT, targetParam, permissionField, requestCodeField)
+        builder.addStatement("\$T.requestPermissions(\$N, \$N, \$N)", ClassName.get("androidx.core.app", "ActivityCompat"), targetParam, permissionField, requestCodeField)
     }
 }