From c8b37c011deba12158aa5e550a01acdb161bd59a Mon Sep 17 00:00:00 2001 From: rafael <36054+rferreira@users.noreply.github.com> Date: Tue, 5 May 2026 13:05:13 -0400 Subject: [PATCH 1/2] deprecate-auto-endpoint: deprecate ScaniiTarget.AUTO Marks ScaniiTarget.AUTO and the no-target createDefault(key, secret) overload as @Deprecated(since="8.2.0"). Building a client without an explicit .target() now emits a runtime System.err warning pointing to the regional constants (US1, EU1, etc.) for data residency compliance. Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 13 +++++++++++++ src/main/java/com/scanii/ScaniiClientBuilder.java | 14 +++++++++++++- src/main/java/com/scanii/ScaniiClients.java | 6 +++++- src/main/java/com/scanii/ScaniiTarget.java | 13 +++++++++++-- src/test/java/com/scanii/ScaniiClientsTest.java | 1 + src/test/java/com/scanii/ScaniiTargetTest.java | 1 + 6 files changed, 44 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db6d4bf..c93c14e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## [8.2.0] — 2026-05-05 + +### Deprecated + +- `ScaniiTarget.AUTO` — latency-based routing (`https://api.scanii.com`) does not guarantee + regional data placement. Use an explicit regional constant (`ScaniiTarget.US1`, + `ScaniiTarget.EU1`, etc.) instead. Will be removed in a future major version. +- `ScaniiClients.createDefault(String key, String secret)` — defaults to `ScaniiTarget.AUTO`. + Use `createDefault(ScaniiTarget, String, String)` with an explicit target instead. + Will be removed in a future major version. +- Constructing a client via the builder without calling `.target(...)` now logs a deprecation + warning to `System.err` at runtime. + ## [8.1.0] — 2026-05-01 ### Added diff --git a/src/main/java/com/scanii/ScaniiClientBuilder.java b/src/main/java/com/scanii/ScaniiClientBuilder.java index 7d80f9f..6afb9ac 100644 --- a/src/main/java/com/scanii/ScaniiClientBuilder.java +++ b/src/main/java/com/scanii/ScaniiClientBuilder.java @@ -22,6 +22,7 @@ * } */ public class ScaniiClientBuilder { + @SuppressWarnings("deprecation") private ScaniiTarget target = ScaniiTarget.AUTO; private String key; private String secret; @@ -35,7 +36,11 @@ public class ScaniiClientBuilder { /** * Sets the target region. * - * @param target the target region {@link ScaniiTarget}. Defaults to {@link ScaniiTarget#AUTO}. + *

Use an explicit regional constant ({@link ScaniiTarget#US1}, {@link ScaniiTarget#EU1}, + * etc.) for production. If not set, the client defaults to {@link ScaniiTarget#AUTO}, which is + * deprecated — a runtime warning will be emitted.

+ * + * @param target the target region {@link ScaniiTarget}. * @return this builder. */ public ScaniiClientBuilder target(ScaniiTarget target) { @@ -108,10 +113,17 @@ public ScaniiClientBuilder header(String name, String value) { * @return the new scanii client. * @throws IllegalStateException if credentials have not been set. */ + @SuppressWarnings("deprecation") public ScaniiClient build() { if (key == null) { throw new IllegalStateException("credentials or authToken must be set"); } + if (target == ScaniiTarget.AUTO) { + System.err.println("[scanii] DEPRECATION: No explicit target set; defaulting to ScaniiTarget.AUTO " + + "(https://api.scanii.com). This does not guarantee regional data placement. " + + "Use ScaniiTarget.US1 (or another regional constant) for explicit data residency control. " + + "ScaniiTarget.AUTO will be removed in a future major version."); + } HttpClient client = httpClient != null ? httpClient : HttpClient.newHttpClient(); return new DefaultScaniiClient(target, key, secret, client, userAgent, Collections.unmodifiableMap(new LinkedHashMap<>(headers))); } diff --git a/src/main/java/com/scanii/ScaniiClients.java b/src/main/java/com/scanii/ScaniiClients.java index 328f886..77de759 100644 --- a/src/main/java/com/scanii/ScaniiClients.java +++ b/src/main/java/com/scanii/ScaniiClients.java @@ -52,12 +52,16 @@ public static ScaniiClient createDefault(ScaniiTarget target, String key, String } /** - * Creates a default client using an API key/secret pair and routing to the nearest processing endpoint. + * Creates a default client using an API key/secret pair, routing to the nearest processing endpoint. * * @param key an API key to be used. * @param secret an API secret to be used. * @return the new scanii client. + * @deprecated Routing to the nearest processing endpoint does not give you control over which + * region processes your data. Use {@link #createDefault(ScaniiTarget, String, String)} with an + * explicit regional target instead. Will be removed in a future major version. */ + @Deprecated(since = "8.2.0") public static ScaniiClient createDefault(String key, String secret) { return builder().credentials(key, secret).build(); } diff --git a/src/main/java/com/scanii/ScaniiTarget.java b/src/main/java/com/scanii/ScaniiTarget.java index 841cb5e..e1ae68c 100644 --- a/src/main/java/com/scanii/ScaniiTarget.java +++ b/src/main/java/com/scanii/ScaniiTarget.java @@ -4,11 +4,20 @@ import java.util.List; /** - * Scanii Resource targets so you can control which api version and endpoint you would like your client to utilize. + * Scanii regional API endpoints. * - * @see http://docs.scanii.com/v2.1/overview.html#endpoints + * @see https://scanii.github.io/openapi/v22/ */ public class ScaniiTarget { + /** + * Latency-routed endpoint ({@code https://api.scanii.com}). Routes to the nearest regional + * endpoint automatically, but does not guarantee which region processes your data. + * + * @deprecated Use an explicit regional target for data residency compliance: + * {@link #US1}, {@link #EU1}, {@link #EU2}, {@link #AP1}, {@link #AP2}, {@link #CA1}. + * Will be removed in a future major version. + */ + @Deprecated(since = "8.2.0") public static final ScaniiTarget AUTO = new ScaniiTarget("https://api.scanii.com"); public static final ScaniiTarget US1 = new ScaniiTarget("https://api-us1.scanii.com"); public static final ScaniiTarget EU1 = new ScaniiTarget("https://api-eu1.scanii.com"); diff --git a/src/test/java/com/scanii/ScaniiClientsTest.java b/src/test/java/com/scanii/ScaniiClientsTest.java index 328043c..0b59b68 100644 --- a/src/test/java/com/scanii/ScaniiClientsTest.java +++ b/src/test/java/com/scanii/ScaniiClientsTest.java @@ -7,6 +7,7 @@ import java.net.http.HttpClient; +@SuppressWarnings("deprecation") class ScaniiClientsTest { @Test diff --git a/src/test/java/com/scanii/ScaniiTargetTest.java b/src/test/java/com/scanii/ScaniiTargetTest.java index 7319843..61037ed 100644 --- a/src/test/java/com/scanii/ScaniiTargetTest.java +++ b/src/test/java/com/scanii/ScaniiTargetTest.java @@ -5,6 +5,7 @@ import java.util.List; +@SuppressWarnings("deprecation") class ScaniiTargetTest { @Test From cf79002a0da1048f908f8c5c56252c0e6d18519b Mon Sep 17 00:00:00 2001 From: rafael <36054+rferreira@users.noreply.github.com> Date: Tue, 5 May 2026 13:29:40 -0400 Subject: [PATCH 2/2] review: remove runtime System.err deprecation warning from build() Per review feedback, the annotation-only approach (@Deprecated on ScaniiTarget.AUTO and createDefault(key, secret)) is sufficient. Runtime stderr noise is too aggressive for a library. Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 2 -- src/main/java/com/scanii/ScaniiClientBuilder.java | 7 ------- 2 files changed, 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c93c14e..5544155 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,8 +10,6 @@ - `ScaniiClients.createDefault(String key, String secret)` — defaults to `ScaniiTarget.AUTO`. Use `createDefault(ScaniiTarget, String, String)` with an explicit target instead. Will be removed in a future major version. -- Constructing a client via the builder without calling `.target(...)` now logs a deprecation - warning to `System.err` at runtime. ## [8.1.0] — 2026-05-01 diff --git a/src/main/java/com/scanii/ScaniiClientBuilder.java b/src/main/java/com/scanii/ScaniiClientBuilder.java index 6afb9ac..3e38769 100644 --- a/src/main/java/com/scanii/ScaniiClientBuilder.java +++ b/src/main/java/com/scanii/ScaniiClientBuilder.java @@ -113,17 +113,10 @@ public ScaniiClientBuilder header(String name, String value) { * @return the new scanii client. * @throws IllegalStateException if credentials have not been set. */ - @SuppressWarnings("deprecation") public ScaniiClient build() { if (key == null) { throw new IllegalStateException("credentials or authToken must be set"); } - if (target == ScaniiTarget.AUTO) { - System.err.println("[scanii] DEPRECATION: No explicit target set; defaulting to ScaniiTarget.AUTO " + - "(https://api.scanii.com). This does not guarantee regional data placement. " + - "Use ScaniiTarget.US1 (or another regional constant) for explicit data residency control. " + - "ScaniiTarget.AUTO will be removed in a future major version."); - } HttpClient client = httpClient != null ? httpClient : HttpClient.newHttpClient(); return new DefaultScaniiClient(target, key, secret, client, userAgent, Collections.unmodifiableMap(new LinkedHashMap<>(headers))); }