release: 0.7.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.0"
+  ".": "0.7.0"
 }

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.7.0 (2023-11-05)
+
+Full Changelog: [v0.6.0...v0.7.0](https://github.com/Finch-API/finch-api-java/compare/v0.6.0...v0.7.0)
+
+### Features
+
+* **client:** allow binary returns ([#99](https://github.com/Finch-API/finch-api-java/issues/99)) ([6232afc](https://github.com/Finch-API/finch-api-java/commit/6232afc5972c220c5940550147d56ff2699e930f))
+
+
+### Documentation
+
+* **readme:** improve example snippets ([#101](https://github.com/Finch-API/finch-api-java/issues/101)) ([522188f](https://github.com/Finch-API/finch-api-java/commit/522188f904fa5c59c56c67b867aebe66bbab5ef0))
+
 ## 0.6.0 (2023-10-31)
 
 Full Changelog: [v0.5.1...v0.6.0](https://github.com/Finch-API/finch-api-java/compare/v0.5.1...v0.6.0)

README.md

@@ -2,7 +2,7 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.tryfinch.api/finch-java)](https://central.sonatype.com/artifact/com.tryfinch.api/finch-java/0.6.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.tryfinch.api/finch-java)](https://central.sonatype.com/artifact/com.tryfinch.api/finch-java/0.7.0)
 
 <!-- x-release-please-end -->
 
@@ -25,7 +25,7 @@ The API documentation can be found [in the Finch Documentation Center](https://
 <!-- x-release-please-start-version -->
 
 ```kotlin
-implementation("com.tryfinch.api:finch-java:0.6.0")
+implementation("com.tryfinch.api:finch-java:0.7.0")
 ```
 
 #### Maven
@@ -34,7 +34,7 @@ implementation("com.tryfinch.api:finch-java:0.6.0")
 <dependency>
     <groupId>com.tryfinch.api</groupId>
     <artifactId>finch-java</artifactId>
-    <version>0.6.0</version>
+    <version>0.7.0</version>
 </dependency>
 ```
 
@@ -79,7 +79,7 @@ import com.tryfinch.api.models.Page;
 HrisDirectoryListParams params = HrisDirectoryListParams.builder()
     .candidateId("<candidate id>")
     .build();
-HrisDirectoryListPage hrisDirectory = client.directory().list(params);
+HrisDirectoryListPage page = client.hris().directory().list(params);
 ```
 
 ### Example: listing resources
@@ -91,7 +91,7 @@ You can retrieve the first page by:
 import com.tryfinch.api.models.IndividualInDirectory;
 import com.tryfinch.api.models.Page;
 
-HrisDirectoryListPage page = client.directory().list();
+HrisDirectoryListPage page = client.hris().directory().list();
 for (IndividualInDirectory directory : page.individuals()) {
     System.out.println(directory);
 }
@@ -127,7 +127,7 @@ HrisDirectoryListParams params = HrisDirectoryListParams.builder()
 When receiving a response, the Finch Java SDK will deserialize it into instances of the typed model classes. In rare cases, the API may return a response property that doesn't match the expected Java type. If you directly access the mistaken property, the SDK will throw an unchecked `FinchInvalidDataException` at runtime. If you would prefer to check in advance that that response is completely well-typed, call `.validate()` on the returned model.
 
 ```java
-HrisDirectoryListPage hrisDirectory = client.directory().list().validate();
+HrisDirectoryListPage page = client.hris().directory().list().validate();
 ```
 
 ### Response properties as JSON
@@ -157,7 +157,7 @@ if (field.isMissing()) {
 Sometimes, the server response may include additional properties that are not yet available in this library's types. You can access them using the model's `_additionalProperties` method:
 
 ```java
-JsonValue secret = hrisDirectory._additionalProperties().get("secret_field");
+JsonValue secret = page._additionalProperties().get("secret_field");
 ```
 
 ---
@@ -176,13 +176,13 @@ which automatically handles fetching more pages for you:
 
 ```java
 // As an Iterable:
-HrisDirectoryListPage page = client.directory().list(params);
+HrisDirectoryListPage page = client.hris().directory().list(params);
 for (IndividualInDirectory directory : page.autoPager()) {
     System.out.println(directory);
 };
 
 // As a Stream:
-client.directory().list(params).autoPager().stream()
+client.hris().directory().list(params).autoPager().stream()
     .limit(50)
     .forEach(directory -> System.out.println(directory));
 ```
@@ -191,7 +191,7 @@ client.directory().list(params).autoPager().stream()
 
 ```java
 // Using forEach, which returns CompletableFuture<Void>:
-asyncClient.directory().list(params).autoPager()
+asyncClient.hris().directory().list(params).autoPager()
     .forEach(directory -> System.out.println(directory), executor);
 ```
 
@@ -203,7 +203,7 @@ A page of results has a `data()` method to fetch the list of objects, as well as
 `hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination.
 
 ```java
-HrisDirectoryListPage page = client.directory().list(params);
+HrisDirectoryListPage page = client.hris().directory().list(params);
 while (page != null) {
     for (IndividualInDirectory directory : page.individuals()) {
         System.out.println(directory);

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 
 allprojects {
     group = "com.tryfinch.api"
-    version = "0.6.0" // x-release-please-version
+    version = "0.7.0" // x-release-please-version
 }
 
 nexusPublishing {

finch-java-core/src/main/kotlin/com/tryfinch/api/core/http/BinaryResponseContent.kt

@@ -0,0 +1,15 @@
+package com.tryfinch.api.core.http
+
+import java.io.Closeable
+import java.io.IOException
+import java.io.InputStream
+import java.io.OutputStream
+
+interface BinaryResponseContent : Closeable {
+
+    fun contentType(): String?
+
+    fun body(): InputStream
+
+    @Throws(IOException::class) fun writeTo(outputStream: OutputStream)
+}

finch-java-core/src/main/kotlin/com/tryfinch/api/services/Handlers.kt

@@ -4,6 +4,7 @@ package com.tryfinch.api.services
 
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
+import com.tryfinch.api.core.http.BinaryResponseContent
 import com.tryfinch.api.core.http.HttpResponse
 import com.tryfinch.api.core.http.HttpResponse.Handler
 import com.tryfinch.api.errors.BadRequestException
@@ -16,6 +17,8 @@ import com.tryfinch.api.errors.RateLimitException
 import com.tryfinch.api.errors.UnauthorizedException
 import com.tryfinch.api.errors.UnexpectedStatusCodeException
 import com.tryfinch.api.errors.UnprocessableEntityException
+import java.io.InputStream
+import java.io.OutputStream
 
 @JvmSynthetic internal fun emptyHandler(): Handler<Void?> = EmptyHandler
 
@@ -25,12 +28,20 @@ private object EmptyHandler : Handler<Void?> {
 
 @JvmSynthetic internal fun stringHandler(): Handler<String> = StringHandler
 
+@JvmSynthetic internal fun binaryHandler(): Handler<BinaryResponseContent> = BinaryHandler
+
 private object StringHandler : Handler<String> {
     override fun handle(response: HttpResponse): String {
         return response.body().readBytes().toString(Charsets.UTF_8)
     }
 }
 
+private object BinaryHandler : Handler<BinaryResponseContent> {
+    override fun handle(response: HttpResponse): BinaryResponseContent {
+        return BinaryResponseContentImpl(response)
+    }
+}
+
 @JvmSynthetic
 internal inline fun <reified T> jsonHandler(jsonMapper: JsonMapper): Handler<T> {
     return object : Handler<T> {
@@ -96,3 +107,24 @@ internal fun <T> Handler<T>.withErrorHandler(errorHandler: Handler<FinchError>):
         }
     }
 }
+
+class BinaryResponseContentImpl
+constructor(
+    private val response: HttpResponse,
+) : BinaryResponseContent {
+    override fun contentType(): String? {
+        return response.headers().get("Content-Type").firstOrNull()
+    }
+
+    override fun body(): InputStream {
+        return response.body()
+    }
+
+    override fun writeTo(outputStream: OutputStream) {
+        response.body().copyTo(outputStream)
+    }
+
+    override fun close() {
+        response.body().close()
+    }
+}