One {@code MarketDataClient} per application. Holds a single shared {@link HttpClient} - * (HTTP/2, 2 s connect timeout) for connection pooling (ADR-004) and a 50-permit semaphore that - * gates the global concurrency pool required by SDK requirements §12. + * (HTTP/2, 2 s connect timeout) for connection pooling and a 50-permit semaphore that gates the + * global concurrency pool required by SDK requirements §12. * - *
Construction follows the configuration cascade in §4: explicit builder values → {@code - * MARKETDATA_*} environment variables → values in a {@code .env} file in the working directory → - * built-in defaults. Pass no token to enter demo mode (authenticated endpoints will fail; - * the {@code Authorization} header is omitted). + *
Two constructors: + * + *
Instances are immutable: every field is {@code final} and assigned in the constructor. */ public final class MarketDataClient implements AutoCloseable { @@ -48,18 +57,46 @@ public final class MarketDataClient implements AutoCloseable { private final boolean demoMode; private final boolean validateOnStartup; - private MarketDataClient(Builder builder) { + /** + * Production constructor. Resolves all settings from the configuration cascade in SDK + * requirements §4 (env var → {@code .env} → built-in default) and enables startup validation. + * + *
Equivalent to {@link #MarketDataClient(String, String, String, boolean) new + * MarketDataClient(null, null, null, true)}. + */ + public MarketDataClient() { + this(null, null, null, true); + } + + /** + * Explicit-control constructor for tests and short-lived runtimes. Each of {@code apiKey}, {@code + * baseUrl}, and {@code apiVersion} may be {@code null} to defer to the cascade in §4 for that + * single value. + * + * @param apiKey explicit API token, or {@code null} to resolve from {@code MARKETDATA_TOKEN} → + * {@code .env} → demo mode + * @param baseUrl override the API base URL, or {@code null} to resolve to {@link + * Configuration#DEFAULT_BASE_URL} + * @param apiVersion override the API version segment, or {@code null} to resolve to {@link + * Configuration#DEFAULT_API_VERSION} + * @param validateOnStartup whether to validate the token on construction by calling {@code + * /user/} (SDK requirements §5). Pass {@code false} for short-lived runtimes where the + * startup hit is undesirable. + */ + public MarketDataClient( + @Nullable String apiKey, + @Nullable String baseUrl, + @Nullable String apiVersion, + boolean validateOnStartup) { Configuration config = Configuration.loadFromProcess(); - this.token = config.resolve(builder.apiKey, EnvVars.TOKEN); + this.token = config.resolve(apiKey, EnvVars.TOKEN); this.baseUrl = trimTrailingSlash( - config.resolveOrDefault( - builder.baseUrl, EnvVars.BASE_URL, Configuration.DEFAULT_BASE_URL)); + config.resolveOrDefault(baseUrl, EnvVars.BASE_URL, Configuration.DEFAULT_BASE_URL)); this.apiVersion = - config.resolveOrDefault( - builder.apiVersion, EnvVars.API_VERSION, Configuration.DEFAULT_API_VERSION); + config.resolveOrDefault(apiVersion, EnvVars.API_VERSION, Configuration.DEFAULT_API_VERSION); this.demoMode = this.token == null; - this.validateOnStartup = builder.validateOnStartup; + this.validateOnStartup = validateOnStartup; this.userAgent = "marketdata-sdk-java/" + Version.current(); this.httpClient = @@ -73,23 +110,19 @@ private MarketDataClient(Builder builder) { LOG.log( Level.INFO, "Initialized Market Data SDK {0} (baseUrl={1}, apiVersion={2}, demoMode={3})", - new Object[] {Version.current(), baseUrl, apiVersion, demoMode}); - if (demoMode) { + new Object[] {Version.current(), this.baseUrl, this.apiVersion, this.demoMode}); + if (this.demoMode) { LOG.warning( "No API token provided — running in demo mode. Authenticated endpoints will" + " fail; rate-limit initialization is skipped."); } else if (LOG.isLoggable(Level.FINE)) { - LOG.log(Level.FINE, "Token: {0}", Tokens.redact(token)); + LOG.log(Level.FINE, "Token: {0}", Tokens.redact(this.token)); } // SDK requirements §5: validate on startup by default. The actual // /user/ call lands with the request layer; this flag is the seam. } - public static Builder builder() { - return new Builder(); - } - public String getBaseUrl() { return baseUrl; } @@ -118,53 +151,12 @@ public boolean isValidateOnStartup() { @Override public void close() { // java.net.http.HttpClient gained explicit close() in JDK 21. - // While the minimum target is JDK 17 (ADR-002), this method is a - // no-op: the JVM releases the executor and connection pool on - // process exit. Revisit if/when the minimum bumps to 21+. + // While the minimum target is JDK 17, this method is a no-op: + // the JVM releases the executor and connection pool on process + // exit. Revisit if/when the minimum bumps to 21+. } private static String trimTrailingSlash(String url) { return url.endsWith("/") ? url.substring(0, url.length() - 1) : url; } - - public static final class Builder { - private @Nullable String apiKey; - private @Nullable String baseUrl; - private @Nullable String apiVersion; - private boolean validateOnStartup = true; - - private Builder() {} - - /** Override the API token; otherwise resolved from {@code MARKETDATA_TOKEN} or {@code .env}. */ - public Builder apiKey(String apiKey) { - this.apiKey = apiKey; - return this; - } - - /** Override the base URL (default {@value Configuration#DEFAULT_BASE_URL}). */ - public Builder baseUrl(String baseUrl) { - this.baseUrl = baseUrl; - return this; - } - - /** Override the API version (default {@value Configuration#DEFAULT_API_VERSION}). */ - public Builder apiVersion(String apiVersion) { - this.apiVersion = apiVersion; - return this; - } - - /** - * Whether to validate the token at construction by calling {@code /user/} (SDK requirements - * §5). Defaults to {@code true}. Disable for short-lived runtimes where the startup hit is - * undesirable. - */ - public Builder validateOnStartup(boolean validateOnStartup) { - this.validateOnStartup = validateOnStartup; - return this; - } - - public MarketDataClient build() { - return new MarketDataClient(this); - } - } } diff --git a/src/main/java/com/marketdata/sdk/exception/MarketDataException.java b/src/main/java/com/marketdata/sdk/exception/MarketDataException.java index f5b427b..bb16a91 100644 --- a/src/main/java/com/marketdata/sdk/exception/MarketDataException.java +++ b/src/main/java/com/marketdata/sdk/exception/MarketDataException.java @@ -8,9 +8,9 @@ /** * Root of the SDK exception hierarchy. * - *
Sealed (ADR-002) so consumer {@code switch} statements over its subtypes are compile-time - * exhaustive. Every instance carries the support context fields required by SDK requirements §6.2 - * and exposes a {@link #getSupportInfo()} string per §6.3. + *
Sealed so consumer {@code switch} statements over its subtypes are compile-time exhaustive. + * Every instance carries the support context fields required by SDK requirements §6.2 and exposes a + * {@link #getSupportInfo()} string per §6.3. * *
Subtypes use {@link ErrorContext#empty()} for client-side validation errors that occur before * any HTTP request is dispatched. diff --git a/src/main/java/com/marketdata/sdk/exception/package-info.java b/src/main/java/com/marketdata/sdk/exception/package-info.java index 3fb0727..456d22e 100644 --- a/src/main/java/com/marketdata/sdk/exception/package-info.java +++ b/src/main/java/com/marketdata/sdk/exception/package-info.java @@ -1,9 +1,9 @@ /** * Sealed exception hierarchy thrown by the SDK. * - *
The {@link com.marketdata.sdk.exception.MarketDataException} root is sealed (ADR-002) so - * consumer {@code switch} statements over the known subtypes are compiler-checked for - * exhaustiveness. Adding a new subtype is a breaking change. + *
The {@link com.marketdata.sdk.exception.MarketDataException} root is sealed so consumer {@code + * switch} statements over the known subtypes are compiler-checked for exhaustiveness. Adding a new + * subtype is a breaking change. */ @NullMarked package com.marketdata.sdk.exception; diff --git a/src/main/java/com/marketdata/sdk/package-info.java b/src/main/java/com/marketdata/sdk/package-info.java index c8dc2bb..b23a077 100644 --- a/src/main/java/com/marketdata/sdk/package-info.java +++ b/src/main/java/com/marketdata/sdk/package-info.java @@ -1,8 +1,8 @@ /** * Market Data Java SDK — public API entry point. * - *
Per ADR-001 §2.1, the entire public API is {@code @NullMarked}: every type, parameter, return, - * and field is non-null by default. Mark nullable items explicitly with {@link + *
The entire public API is {@code @NullMarked}: every type, parameter, return, and field is + * non-null by default. Mark nullable items explicitly with {@link * org.jspecify.annotations.Nullable}. */ @NullMarked diff --git a/src/test/java/com/marketdata/sdk/MarketDataClientTest.java b/src/test/java/com/marketdata/sdk/MarketDataClientTest.java index 8e9cfc8..24f0ddf 100644 --- a/src/test/java/com/marketdata/sdk/MarketDataClientTest.java +++ b/src/test/java/com/marketdata/sdk/MarketDataClientTest.java @@ -9,7 +9,7 @@ class MarketDataClientTest { @Test void buildsWithExplicitToken() { - try (var client = MarketDataClient.builder().apiKey("test-key").build()) { + try (var client = new MarketDataClient("test-key", null, null, true)) { assertThat(client.isDemoMode()).isFalse(); assertThat(client.getBaseUrl()).isEqualTo(Configuration.DEFAULT_BASE_URL); assertThat(client.getApiVersion()).isEqualTo(Configuration.DEFAULT_API_VERSION); @@ -18,26 +18,41 @@ void buildsWithExplicitToken() { @Test void demoModeWhenNoTokenAvailable() { - // No apiKey set on the builder. Demo mode iff the env/dotenv + // No apiKey passed to the constructor. Demo mode iff the env/dotenv // cascade also yields nothing — true on any CI environment that // doesn't export MARKETDATA_TOKEN. This assertion is conditional // so the test stays valid in both cases. - try (var client = MarketDataClient.builder().build()) { + try (var client = new MarketDataClient()) { String envToken = System.getenv("MARKETDATA_TOKEN"); boolean expectDemo = envToken == null || envToken.isBlank(); assertThat(client.isDemoMode()).isEqualTo(expectDemo); } } + @Test + void noArgConstructorAppliesProductionDefaults() { + // The no-arg constructor must be equivalent to `new MarketDataClient(null, null, null, + // true)` — production path with everything resolved from the cascade and startup + // validation enabled. validateOnStartup and the userAgent format are env-independent, + // so we assert them unconditionally; baseUrl/apiVersion fall back to the documented + // defaults only when the cascade has no override, so we gate those assertions on the + // env vars being unset (mirrors the demo-mode test above). + try (var client = new MarketDataClient()) { + assertThat(client.isValidateOnStartup()).isTrue(); + assertThat(client.getUserAgent()).startsWith("marketdata-sdk-java/"); + + if (System.getenv("MARKETDATA_BASE_URL") == null) { + assertThat(client.getBaseUrl()).isEqualTo(Configuration.DEFAULT_BASE_URL); + } + if (System.getenv("MARKETDATA_API_VERSION") == null) { + assertThat(client.getApiVersion()).isEqualTo(Configuration.DEFAULT_API_VERSION); + } + } + } + @Test void overridesAreHonored() { - try (var client = - MarketDataClient.builder() - .apiKey("KEY") - .baseUrl("https://example.test/") - .apiVersion("v2") - .validateOnStartup(false) - .build()) { + try (var client = new MarketDataClient("KEY", "https://example.test/", "v2", false)) { assertThat(client.getBaseUrl()).isEqualTo("https://example.test"); // trailing slash trimmed assertThat(client.getApiVersion()).isEqualTo("v2"); assertThat(client.isValidateOnStartup()).isFalse(); @@ -46,14 +61,14 @@ void overridesAreHonored() { @Test void userAgentMatchesSpec() { - try (var client = MarketDataClient.builder().apiKey("KEY").build()) { + try (var client = new MarketDataClient("KEY", null, null, true)) { assertThat(client.getUserAgent()).startsWith("marketdata-sdk-java/"); } } @Test void rateLimitsStartUnpopulated() { - try (var client = MarketDataClient.builder().apiKey("KEY").build()) { + try (var client = new MarketDataClient("KEY", null, null, true)) { assertThat(client.getRateLimits()).isNull(); } }