fix(java-sdk): ensure headers can be set and overriden

config/clients/java/config.overrides.json

@@ -565,52 +565,48 @@
       "destinationFilename": "docs/OpenTelemetry.md",
       "templateType": "SupportingFiles"
     },
-    "example/Makefile": {
-      "destinationFilename": "example/Makefile",
-      "templateType": "SupportingFiles"
-    },
     "example/README.md": {
-      "destinationFilename": "example/README.md",
+      "destinationFilename": "examples/README.md",
       "templateType": "SupportingFiles"
     },
     "example/example1/README.md": {
-      "destinationFilename": "example/example1/README.md",
+      "destinationFilename": "examples/basic-examples/README.md",
       "templateType": "SupportingFiles"
     },
     "example/example1/gradle/wrapper/gradle-wrapper.jar": {
-      "destinationFilename": "example/example1/gradle/wrapper/gradle-wrapper.jar",
+      "destinationFilename": "examples/basic-examples/gradle/wrapper/gradle-wrapper.jar",
       "templateType": "SupportingFiles"
     },
     "example/example1/gradle/wrapper/gradle-wrapper.properties": {
-      "destinationFilename": "example/example1/gradle/wrapper/gradle-wrapper.properties",
+      "destinationFilename": "examples/basic-examples/gradle/wrapper/gradle-wrapper.properties",
       "templateType": "SupportingFiles"
     },
     "example/example1/gradlew": {
-      "destinationFilename": "example/example1/gradlew",
+      "destinationFilename": "examples/basic-examples/gradlew",
       "templateType": "SupportingFiles"
     },
     "example/example1/build.gradle.mustache": {
-      "destinationFilename": "example/example1/build.gradle",
+      "destinationFilename": "examples/basic-examples/build.gradle",
       "templateType": "SupportingFiles"
     },
     "example/example1/gradle.properties": {
-      "destinationFilename": "example/example1/gradle.properties",
+      "destinationFilename": "examples/basic-examples/gradle.properties",
       "templateType": "SupportingFiles"
     },
     "example/example1/settings.gradle": {
-      "destinationFilename": "example/example1/settings.gradle",
+      "destinationFilename": "examples/basic-examples/settings.gradle",
       "templateType": "SupportingFiles"
     },
     "example/example1/src/main/resources/example1-auth-model.json": {
-      "destinationFilename": "example/example1/src/main/resources/example1-auth-model.json",
+      "destinationFilename": "examples/basic-examples/src/main/resources/example1-auth-model.json",
       "templateType": "SupportingFiles"
     },
     "example/example1/src/main/java/dev/openfga/sdk/example/Example1.java": {
-      "destinationFilename": "example/example1/src/main/java/dev/openfga/sdk/example/Example1.java",
+      "destinationFilename": "examples/basic-examples/src/main/java/dev/openfga/sdk/example/Example1.java",
       "templateType": "SupportingFiles"
     },
     "example/example1/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt": {
-      "destinationFilename": "example/example1/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt",
+      "destinationFilename": "examples/basic-examples/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt",
       "templateType": "SupportingFiles"
     },
     "ExampleTest.java.mustache": {

config/clients/java/template/README_initializing.mustache

@@ -108,3 +108,66 @@ public class Example {
     }
 }
 ```
+
+### Custom Headers
+
+#### Default Headers
+
+You can set default headers to be sent with every request by using the `defaultHeaders` property of the `ClientConfiguration` class.
+
+```java
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.openfga.sdk.api.client.OpenFgaClient;
+import dev.openfga.sdk.api.configuration.ClientConfiguration;
+
+import java.net.http.HttpClient;
+import java.util.Map;
+
+public class Example {
+    public static void main(String[] args) throws Exception {
+        var config = new ClientConfiguration()
+                .apiUrl(System.getenv("FGA_API_URL"))
+                .storeId(System.getenv("FGA_STORE_ID"))
+                .authorizationModelId(System.getenv("FGA_MODEL_ID"))
+                .defaultHeaders(Map.of(
+                        "X-Custom-Header", "default-value",
+                        "X-Request-Source", "my-app"
+                ));
+
+        var fgaClient = new OpenFgaClient(config);
+    }
+}
+```
+
+#### Per-request Headers
+
+You can set custom headers to be sent with a specific request by using the `additionalHeaders` property of the options classes (e.g. `ClientReadOptions`, `ClientWriteOptions`, etc.).
+
+```java
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.openfga.sdk.api.client.OpenFgaClient;
+import dev.openfga.sdk.api.configuration.ClientConfiguration;
+import java.net.http.HttpClient;
+
+public class Example {
+    public static void main(String[] args) throws Exception {
+        var config = new ClientConfiguration()
+                .apiUrl(System.getenv("FGA_API_URL"))
+                .storeId(System.getenv("FGA_STORE_ID"))
+                .authorizationModelId(System.getenv("FGA_MODEL_ID"))
+                .defaultHeaders(Map.of(
+                        "X-Custom-Header", "default-value",
+                        "X-Request-Source", "my-app"
+                ));
+
+        var fgaClient = new OpenFgaClient(config);
+        var options = new ClientReadOptions()
+                    .additionalHeaders(Map.of(
+                            "X-Request-Id", "123e4567-e89b-12d3-a456-426614174000",
+                            "X-Custom-Header", "overridden-value" // this will override the default value for this request only
+                    )
+                );
+        var response = fgaClient.read(request, options).get();
+    }
+}
+```

config/clients/java/template/build.gradle.mustache

@@ -61,7 +61,7 @@ ext {
     {{#swagger2AnnotationLibrary}}
     swagger_annotations_version = "2.2.9"
     {{/swagger2AnnotationLibrary}}
-    jackson_version = "2.19.2"
+    jackson_version = "2.20.0"
     {{#hasFormParamsInSpec}}
     httpmime_version = "4.5.13"
     {{/hasFormParamsInSpec}}
@@ -75,12 +75,17 @@ dependencies {
     implementation "io.swagger.core.v3:swagger-annotations:$swagger_annotations_version"
     {{/swagger2AnnotationLibrary}}
     implementation "com.google.code.findbugs:jsr305:3.0.2"
-    implementation "com.fasterxml.jackson.core:jackson-core:$jackson_version"
-    implementation "com.fasterxml.jackson.core:jackson-annotations:$jackson_version"
-    implementation "com.fasterxml.jackson.core:jackson-databind:$jackson_version"
-    implementation "com.fasterxml.jackson.datatype:jackson-datatype-jsr310:$jackson_version"
-    implementation "org.openapitools:jackson-databind-nullable:0.2.6"
-    implementation platform("io.opentelemetry:opentelemetry-bom:1.53.0")
+
+    // ---- Jackson ----
+    implementation platform("com.fasterxml.jackson:jackson-bom:$jackson_version")
+    implementation "com.fasterxml.jackson.core:jackson-core"
+    implementation "com.fasterxml.jackson.core:jackson-annotations"
+    implementation "com.fasterxml.jackson.core:jackson-databind"
+    implementation "com.fasterxml.jackson.datatype:jackson-datatype-jsr310"
+    implementation "org.openapitools:jackson-databind-nullable:0.2.7"
+
+    // ---- OpenTelemetry ----
+    implementation platform("io.opentelemetry:opentelemetry-bom:1.54.1")
     implementation "io.opentelemetry:opentelemetry-api"
     {{#hasFormParamsInSpec}}
     implementation "org.apache.httpcomponents:httpmime:$httpmime_version"
@@ -92,9 +97,9 @@ testing {
         test {
             useJUnitJupiter()
             dependencies {
-                implementation 'org.assertj:assertj-core:3.27.4'
-                implementation 'org.mockito:mockito-core:5.18.0'
-                implementation 'org.junit.jupiter:junit-jupiter:5.13.4'
+                implementation 'org.assertj:assertj-core:3.27.6'
+                implementation 'org.mockito:mockito-core:5.20.0'
+                implementation 'org.junit.jupiter:junit-jupiter:5.14.0'
                 implementation 'org.wiremock:wiremock:3.13.1'
 
                 runtimeOnly 'org.junit.platform:junit-platform-launcher'
@@ -122,8 +127,11 @@ testing {
             useJUnitJupiter()
 
             dependencies {
-                implementation "com.fasterxml.jackson.core:jackson-core:$jackson_version"
-                implementation "com.fasterxml.jackson.core:jackson-databind:$jackson_version"
+                // --- Jackson ---
+                implementation platform("com.fasterxml.jackson:jackson-bom:$jackson_version")
+                implementation "com.fasterxml.jackson.core:jackson-core"
+                implementation "com.fasterxml.jackson.core:jackson-databind"
+
                 implementation "org.testcontainers:junit-jupiter:1.21.3"
                 implementation "org.testcontainers:openfga:1.21.3"
                 implementation project()

config/clients/java/template/example/README.md

@@ -1,49 +1,11 @@
 ## Examples of using the OpenFGA Java SDK
 
-A set of Examples on how to call the OpenFGA Java SDK
+A collection of examples demonstrating how to use the OpenFGA Java SDK in different scenarios.
 
-### Examples
-Example 1:
-A bare-bones example. It creates a store, and runs a set of calls against it including creating a model, writing tuples and checking for access.
-This example is implemented in both Java and Kotlin.
+### Available Examples
 
+#### Basic Examples (`basic-examples/`)
+A simple example that creates a store, runs a set of calls against it including creating a model, writing tuples and checking for access. This example is implemented in both Java and Kotlin.
 
-### Running the Examples
-
-Prerequisites:
-- `docker`
-- `make`
-- A Java Runtime Environment (JRE)
-
-#### Run using a published SDK
-
-Steps
-1. Clone/Copy the example folder
-2. Run `make` to build the project
-3. If you have an OpenFGA server running, you can use it, otherwise run `make run-openfga` to spin up an instance (you'll need to switch to a different terminal after - don't forget to close it when done)
-4. Run `make run` to run the example
-
-#### Run using a local unpublished SDK build
-
-Steps
-1. Build the SDK
-2. In the Example project file (e.g. `build.gradle`), comment out the part that specifies the remote SDK, e.g.
-```groovy
-dependencies {
-    implementation("dev.openfga:openfga-sdk:0.4.+")
-
-    // ...etc
-}
-```
-and replace it with one pointing to the local gradle project, e.g.
-```groovy
-dependencies {
-    // implementation("dev.openfga:openfga-sdk:0.4.+")
-    implementation project(path: ':')
-
-    // ...etc
-}
-```
-3. Run `make` to build the project
-4. If you have an OpenFGA server running, you can use it, otherwise run `make run-openfga` to spin up an instance (you'll need to switch to a different terminal after - don't forget to close it when done)
-5. Run `make run` to run the example
+#### OpenTelemetry Examples
+- `opentelemetry/` - Demonstrates OpenTelemetry integration both via manual code configuration, as well as no-code instrumentation using the OpenTelemetry java agent

config/clients/java/template/example/example1/build.gradle.mustache

@@ -1,7 +1,7 @@
 plugins {
     id 'application'
-    id 'com.diffplug.spotless' version '7.2.1'
-    id 'org.jetbrains.kotlin.jvm' version '2.2.10'
+    id 'com.diffplug.spotless' version '8.0.0'
+    id 'org.jetbrains.kotlin.jvm' version '2.2.20'
 }
 
 application {
@@ -19,7 +19,7 @@ repositories {
 }
 
 ext {
-    jacksonVersion = "2.19.2"
+    jacksonVersion = "2.20.0"
 }
 
 dependencies {
@@ -30,7 +30,7 @@ dependencies {
     implementation("com.fasterxml.jackson.core:jackson-annotations:$jacksonVersion")
     implementation("com.fasterxml.jackson.core:jackson-databind:$jacksonVersion")
     implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:$jacksonVersion")
-    implementation("org.openapitools:jackson-databind-nullable:0.2.6")
+    implementation("org.openapitools:jackson-databind-nullable:0.2.7")
 
     // Kotlin
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"

config/clients/java/template/example/example1/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.2.1-all.zip
 networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

config/clients/java/template/example/example1/src/main/java/dev/openfga/sdk/example/Example1.java

@@ -28,8 +28,7 @@ public void run(String apiUrl) throws Exception {
         var configuration = new ClientConfiguration()
                 .apiUrl(apiUrl) // required, e.g. https://api.fga.example
                 .storeId(System.getenv("FGA_STORE_ID")) // not needed when calling `CreateStore` or `ListStores`
-                .authorizationModelId(
-                        System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request
+                .authorizationModelId(System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request
                 .credentials(credentials);
         var fgaClient = new OpenFgaClient(configuration);
 
@@ -114,8 +113,9 @@ public void run(String apiUrl) throws Exception {
                                         new ClientTupleKey()
                                                 .user("user:anne")
                                                 .relation("owner")
-                                                ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a") // different relation
-                                )),
+                                                ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a") // different
+                                        // relation
+                                        )),
                         new ClientWriteOptions()
                                 .disableTransactions(true)
                                 .authorizationModelId(authorizationModel.getAuthorizationModelId()))

config/clients/java/template/gitignore.mustache

@@ -30,3 +30,9 @@ VERSION.txt
 
 # VSCode IDE
 /.vscode
+
+# env files
+.env
+
+# mac
+.DS_Store