up

src/Sdk/StellaOps.Sdk.Generator/java/README.md

@@ -0,0 +1,45 @@
+# Java SDK (SDKGEN-63-004)
+
+Deterministic generator settings for the Java SDK with OkHttp client and builder pattern.
+
+## Prereqs
+- `STELLA_OAS_FILE` pointing to the frozen OpenAPI spec.
+- OpenAPI Generator CLI 7.4.0 jar at `tools/openapi-generator-cli-7.4.0.jar` (override with `STELLA_OPENAPI_GENERATOR_JAR`).
+- JDK 21 available on PATH (vendored at `../tools/jdk-21.0.1+12`; set `JAVA_HOME` if needed).
+
+## Generate
+```bash
+cd src/Sdk/StellaOps.Sdk.Generator
+STELLA_OAS_FILE=ts/fixtures/ping.yaml \
+STELLA_SDK_OUT=$(mktemp -d) \
+java/generate-java.sh
+```
+
+Outputs land in `out/java/` and are post-processed to normalize whitespace, inject the banner, and copy shared helpers (`Hooks.java`).
+Override `STELLA_SDK_OUT` to keep the repo clean during local runs.
+
+## Design Principles
+
+- **Builder pattern**: API clients follow idiomatic Java builder patterns for configuration.
+- **OkHttp abstraction**: Uses OkHttp as the HTTP client with interceptor-based hooks.
+- **Jakarta EE**: Uses `jakarta.*` packages for enterprise compatibility.
+- **Deterministic**: Generation is reproducible given the same spec and toolchain lock.
+
+## Helpers
+
+The post-process step copies `Hooks.java` into the output directory providing:
+- `Hooks.withAll()`: Composes auth, telemetry, and retry interceptors onto an OkHttpClient
+- `AuthProvider`: Interface for token-based authentication
+- `RetryOptions`: Configurable retry with exponential backoff
+- `TelemetryOptions`: Client/trace header injection
+- `StellaAuthInterceptor`, `StellaTelemetryInterceptor`, `StellaRetryInterceptor`: OkHttp interceptors
+
+## Maven Coordinates
+
+```xml
+<dependency>
+  <groupId>com.stellaops</groupId>
+  <artifactId>stellaops-sdk</artifactId>
+  <version>0.0.0-alpha</version>
+</dependency>
+```