Add convert methods with result data

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 4.2.0
 **Library changes:**
 - Improved support for [auto-store setting](https://uploadcare.com/docs/uploads/storage/#defaults).
+- Added convert methods with result data
 
 ## 4.1.0
 **Library changes:**

documentation/LIBRARY.md

@@ -869,6 +869,99 @@ DocumentConverter converter = new DocumentConverter(uploadcare, conversionJobs);
 List<UploadcareFile> result = converter.convert();
 ```
 
+##### Asynchronous documents convert with result data.
+
+Kotlin
+```kotlin
+// Create conversion job
+val conversionJob = DocumentConversionJob("YOUR_FILE_UUID").apply {
+    setFormat(DocumentFormat.JPG)
+    // other conversion parameters...
+}
+
+// Create document converter, multiple DocumentConversionJob are supported.
+val converter = DocumentConverter(uploadcare, listOf(conversionJob))
+
+// Convert with result data
+converter.convertWithResultDataAsync(object : ConversionResultDataCallback {
+    override fun onFailure(e: UploadcareApiException) {
+        // Handle errors.
+    }
+
+    override fun onSuccess(result: ConvertResultData) {
+        /* Handle an object containing the problems related to your processing job
+           and the result for each requested path.
+        */
+    }
+})
+```
+
+Java
+```java
+// Create conversion job
+DocumentConversionJob conversionJob = new DocumentConversionJob("YOUR_FILE_UUID")
+    .setFormat(DocumentFormat.JPG);
+    // other conversion parameters...
+
+// Multiple DocumentConversionJob are supported.
+List<DocumentConversionJob> conversionJobs = new ArrayList();
+conversionJobs.add(conversionJob);
+
+// Create document converter
+DocumentConverter converter = new DocumentConverter(uploadcare, conversionJobs);
+
+// Convert with result data
+converter.convertWithResultDataAsync(
+        new ConversionResultDataCallback() {
+            @Override
+            public void onFailure(@NotNull UploadcareApiException e) {
+                // Handle errors.
+            }
+
+            @Override
+            public void onSuccess(@NonNull ConvertResultData result) {
+                /* Handle an object containing the problems related to your processing job
+                   and the result for each requested path.
+                */
+            }
+        });
+```
+
+##### Synchronous documents convert with result data.
+
+Kotlin
+```kotlin
+// Create conversion job
+val conversionJob = DocumentConversionJob("YOUR_FILE_UUID").apply {
+    setFormat(DocumentFormat.JPG)
+    // other conversion parameters...
+}
+
+// Create document converter, multiple DocumentConversionJob are supported.
+val converter = DocumentConverter(uploadcare, listOf(conversionJob))
+
+// Convert with result data
+val result: ConvertResultData = converter.convertWithResultData()
+```
+
+Java
+```java
+// Create conversion job
+DocumentConversionJob conversionJob = new DocumentConversionJob("YOUR_FILE_UUID")
+    .setFormat(DocumentFormat.JPG);
+    // other conversion parameters...
+
+// Multiple DocumentConversionJob are supported.
+List<DocumentConversionJob> conversionJobs = new ArrayList();
+conversionJobs.add(conversionJob);
+
+// Create document converter
+DocumentConverter converter = new DocumentConverter(uploadcare, conversionJobs);
+
+// Convert with result data
+ConvertResultData result = converter.convertWithResultData();
+```
+
 ## Check document conversion status ([API Reference](https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Conversion/operation/documentConvertStatus)) ##
 
 ##### Asynchronous check document conversion status.
@@ -1013,6 +1106,103 @@ VideoConverter converter = new VideoConverter(uploadcare, conversionJobs);
 List<UploadcareFile> result = converter.convert();
 ```
 
+##### Asynchronous videos convert with result data.
+
+Kotlin
+```kotlin
+// Create conversion job
+val conversionJob = VideoConversionJob("YOUR_FILE_UUID").apply {
+    setFormat(VideoFormat.MP4)
+    quality(VideoQuality.NORMAL)
+    thumbnails(2)
+    // other conversion parameters...
+}
+
+// Create video converter, multiple VideoConversionJob are supported.
+val converter = VideoConverter(uploadcare, listOf(conversionJob))
+
+// Convert with result data
+converter.convertWithResultDataAsync(object : ConversionResultDataCallback {
+    override fun onFailure(e: UploadcareApiException) {
+        // Handle errors.
+    }
+
+    override fun onSuccess(result: ConvertResultData) {
+        /* Handle an object containing the problems related to your processing job
+           and the result for each requested path.
+        */
+    }
+})
+```
+
+Java
+```java
+// Create conversion job
+VideoConversionJob conversionJob = new VideoConversionJob("YOUR_FILE_UUID")
+    .setFormat(DocumentFormat.JPG);
+    // other conversion parameters...
+
+// Multiple VideoConversionJob are supported.
+List<VideoConversionJob> conversionJobs = new ArrayList();
+conversionJobs.add(conversionJob);
+
+// Create document converter
+VideoConverter converter = new VideoConverter(uploadcare, conversionJobs);
+
+// Convert with result data
+converter.convertAsync(
+        new ConversionResultDataCallback() {
+            @Override
+            public void onFailure(@NotNull UploadcareApiException e) {
+                // Handle errors.
+            }
+
+            @Override
+            public void onSuccess(@NonNull ConvertResultData result) {
+                /* Handle an object containing the problems related to your processing job
+                   and the result for each requested path.
+                */
+            }
+        });
+```
+
+##### Synchronous videos convert with result data.
+
+Kotlin
+```kotlin
+// Create conversion job
+val conversionJob = VideoConversionJob("YOUR_FILE_UUID").apply {
+    setFormat(VideoFormat.MP4)
+    quality(VideoQuality.NORMAL)
+    thumbnails(2)
+    // other conversion parameters...
+}
+
+// Create video converter, multiple VideoConversionJob are supported.
+val converter = VideoConverter(uploadcare, listOf(conversionJob))
+
+// Convert with result data
+val result: ConvertResultData = converter.convertWithResultData()
+```
+
+Java
+```java
+// Create conversion job
+VideoConversionJob conversionJob = new VideoConversionJob("YOUR_FILE_UUID")
+    .setFormat(DocumentFormat.JPG);
+    // other conversion parameters...
+
+// Multiple VideoConversionJob are supported.
+List<VideoConversionJob> conversionJobs = new ArrayList();
+conversionJobs.add(conversionJob);
+
+// Create document converter
+VideoConverter converter = new VideoConverter(uploadcare, conversionJobs);
+
+// Convert with result data
+ConvertResultData result = converter.convertWithResultData();
+```
+
 ## Check video conversion status ([API Reference](https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Conversion/operation/videoConvertStatus)) ##
 
 ##### Asynchronous check video conversion status.

library/src/main/java/com/uploadcare/android/library/callbacks/Callbacks.kt

@@ -2,6 +2,7 @@ package com.uploadcare.android.library.callbacks
 
 import androidx.annotation.NonNull
 import com.uploadcare.android.library.api.*
+import com.uploadcare.android.library.data.ConvertResultData
 import com.uploadcare.android.library.data.ConvertStatusData
 import com.uploadcare.android.library.data.UploadFromUrlStatusData
 import com.uploadcare.android.library.exceptions.UploadcareApiException
@@ -63,3 +64,5 @@ interface UploadcareMetadataKeyValueCallback : BaseCallback<String>
 interface UploadFromUrlStatusCallback : BaseCallback<UploadFromUrlStatusData>
 
 interface ConversionStatusCallback : BaseCallback<ConvertStatusData>
+
+interface ConversionResultDataCallback : BaseCallback<ConvertResultData>

library/src/main/java/com/uploadcare/android/library/conversion/Converter.kt

@@ -5,6 +5,7 @@ import com.uploadcare.android.library.api.RequestHelper.Companion.md5
 import com.uploadcare.android.library.api.UploadcareClient
 import com.uploadcare.android.library.api.UploadcareFile
 import com.uploadcare.android.library.callbacks.ConversionFilesCallback
+import com.uploadcare.android.library.callbacks.ConversionResultDataCallback
 import com.uploadcare.android.library.data.ConvertData
 import com.uploadcare.android.library.data.ConvertResultData
 import com.uploadcare.android.library.data.ConvertStatusData
@@ -26,7 +27,7 @@ abstract class Converter(private val client: UploadcareClient,
     private var store: String? = null
     private var saveInGroup: String? = null
 
-    private var job: Job? = null
+    private val scope = MainScope()
 
     private var isCanceled: Boolean = false
 
@@ -46,7 +47,7 @@ abstract class Converter(private val client: UploadcareClient,
      * @param ConversionFilesCallback that will be called when finished, or when error occurred.
      */
     fun convertAsync(callback: ConversionFilesCallback) {
-        job = GlobalScope.launch(Dispatchers.IO) {
+        scope.launch(Dispatchers.IO) {
             try {
                 val uploadedFiles = convert(UrlUploader.DEFAULT_POLLING_INTERVAL)
                 withContext(Dispatchers.Main) {
@@ -62,8 +63,8 @@ abstract class Converter(private val client: UploadcareClient,
 
     fun cancel() {
         isCanceled = true
-        job?.cancel("canceled", UploadcareApiException("Canceled"))
-        job = null
+        val cause = CancellationException("canceled", UploadcareApiException("Canceled"))
+        scope.coroutineContext.cancelChildren(cause)
     }
 
     /**
@@ -92,19 +93,7 @@ abstract class Converter(private val client: UploadcareClient,
     @Throws(UploadcareApiException::class)
     fun convert(pollingInterval: Long): List<UploadcareFile> {
         val results = ArrayList<UploadcareFile>()
-
-        val convertData = ConvertData(getPaths(), store, saveInGroup)
-        val requestBodyContent = client.objectMapper.toJson(convertData, ConvertData::class.java)
-        val body = requestBodyContent.encodeUtf8().toRequestBody(RequestHelper.JSON)
-        val url = getConversionUri()
-
-        val jobTokens = client.requestHelper.executeQuery(
-                RequestHelper.REQUEST_POST,
-                url.toString(),
-                true,
-                ConvertResultData::class.java,
-                body,
-                requestBodyContent.md5())
+        val jobTokens = convertWithResultData()
 
         if (jobTokens.result.isEmpty()) {
             throw UploadcareApiException("Convert Error: " + jobTokens.problems.toString())
@@ -168,6 +157,48 @@ abstract class Converter(private val client: UploadcareClient,
         return results
     }
 
+    /**
+     * Start conversion process synchronously.
+     *
+     * @return An object containing the problems related to your processing job
+     * and the result for each requested path.
+     */
+    fun convertWithResultData(): ConvertResultData {
+        val convertData = ConvertData(getPaths(), store, saveInGroup)
+        val requestBodyContent = client.objectMapper.toJson(convertData, ConvertData::class.java)
+        val body = requestBodyContent.encodeUtf8().toRequestBody(RequestHelper.JSON)
+        val url = getConversionUri()
+
+        return client.requestHelper.executeQuery(
+            RequestHelper.REQUEST_POST,
+            url.toString(),
+            true,
+            ConvertResultData::class.java,
+            body,
+            requestBodyContent.md5()
+        )
+    }
+
+    /**
+     * Start conversion process asynchronously.
+     *
+     * @param ConversionResultDataCallback that will be called when finished, or when error occurred.
+     */
+    fun convertWithResultDataAsync(callback: ConversionResultDataCallback) {
+        scope.launch(Dispatchers.IO) {
+            try {
+                val file = convertWithResultData()
+                withContext(Dispatchers.Main) {
+                    callback.onSuccess(file)
+                }
+            } catch (e: Exception) {
+                withContext(Dispatchers.Main) {
+                    callback.onFailure(UploadcareApiException(e.message))
+                }
+            }
+        }
+    }
+
     protected abstract fun getConversionUri(): URI
 
     protected abstract fun getConversionStatusUri(token: Int): URI

library/src/main/java/com/uploadcare/android/library/data/ConvertData.kt

@@ -8,11 +8,11 @@ internal data class ConvertData(
         @Json(name = "save_in_group") val saveInGroup: String?
 )
 
-internal data class ConvertResultData(
+data class ConvertResultData(
         val problems: Map<String, String>,
         val result: List<ConvertResult>)
 
-internal data class ConvertResult(
+data class ConvertResult(
         val originalSource: String? = null,
         val uuid: String,
         val token: Int)