Package com.aim2be.platform.schema

Class DualSchemaRegistryClient

java.lang.Object

com.aim2be.platform.schema.DualSchemaRegistryClient

All Implemented Interfaces:

SchemaRegistryClient

public class DualSchemaRegistryClient
extends Object
implements SchemaRegistryClient

Wire-format hedge coordinator (ADR-0011 §B optional hedge).

Important — design clarification (R2 MAJOR fix): the "primary" and "fallback" delegates wrap the SAME underlying Apicurio registry. The dual client is NOT an HA hedge against registry outages; it's a wire-format coexistence layer. Both producers + consumers in a deployment may choose Apicurio 8-byte OR Confluent 4-byte wire prefixes, and the dual client makes both interpretations available against one Apicurio backend.

Behaviour:

• register(String, byte[], SchemaType) — calls primary only. Any error from the primary (5xx / IOException / 4xx) propagates to the caller; the fallback is NEVER invoked at this method because it wraps the same underlying registry and retrying cannot recover from an outage there.
• fetchByGlobalId(long) — primary only. Apicurio globalIds (long) and Confluent schemaIds (int) are NOT interchangeable; a caller that has only a wire-prefix-derived id must pre-decide which method to invoke based on the wire format. Falling back here would silently mis-map ids.
• fetchLatestBySubject(String) — primary only; outages propagate (same rationale as register).
• kind() — SchemaRegistryClient.Kind.DUAL.
• wireFormat() — returns the primary's wireFormat (Apicurio 8-byte by default).

The fallback delegate is retained on this class so the wire- format-hedging consumers may explicitly access it via getFallback(); routine register/fetch operations only ever consult the primary.

Activated when im2be.schema-registry.mode=dual.

Nested Class Summary

Nested classes/interfaces inherited from interface com.aim2be.platform.schema.SchemaRegistryClient

SchemaRegistryClient.Kind, SchemaRegistryClient.Schema, SchemaRegistryClient.SchemaType

Constructor Summary

Constructors

Constructor	Description
DualSchemaRegistryClient(SchemaRegistryClient primary, SchemaRegistryClient fallback, io.opentelemetry.api.OpenTelemetry openTelemetry)

Method Summary

Modifier and Type	Method	Description
SchemaRegistryClient.Schema	fetchByGlobalId(long globalId)	Fetches a schema by registry global ID.
SchemaRegistryClient.Schema	fetchLatestBySubject(String subject)	Fetches the latest schema body registered under subject.
SchemaRegistryClient	getFallback()
SchemaRegistryClient	getPrimary()
SchemaRegistryClient.Kind	kind()	Returns the implementation kind.
long	register(String subject, byte[] schemaBytes, SchemaRegistryClient.SchemaType type)	Registers schemaBytes under subject, returning the registry-assigned global ID.
WireFormat	wireFormat()	Returns the wire format this client emits / parses.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DualSchemaRegistryClient

public DualSchemaRegistryClient(SchemaRegistryClient primary,
 SchemaRegistryClient fallback,
 io.opentelemetry.api.OpenTelemetry openTelemetry)

Parameters:

primary - the primary path (typically Apicurio 8-byte); not null

fallback - the fallback path (typically Confluent 4-byte); not null

openTelemetry - the OpenTelemetry instance for tracer acquisition; not null

Method Details

register

public long register(String subject,
 byte[] schemaBytes,
 SchemaRegistryClient.SchemaType type)

Description copied from interface: SchemaRegistryClient

Registers schemaBytes under subject, returning the registry-assigned global ID.

Idempotent: a re-registration of identical bytes returns the same global ID (Apicurio's IfExists=RETURN_OR_UPDATE semantics).

Specified by:

register in interface SchemaRegistryClient

Parameters:

subject - the subject name (typically <topic>-value or <topic>-key per ADR-0011 §B)

schemaBytes - the schema body bytes; UTF-8 JSON for Avro/JSON, binary for Protobuf; must be non-null

type - the schema type (AVRO / PROTOBUF / JSON)

Returns:

the registry-assigned global ID

fetchByGlobalId

public SchemaRegistryClient.Schema fetchByGlobalId(long globalId)

Description copied from interface: SchemaRegistryClient

Fetches a schema by registry global ID.

Specified by:

fetchByGlobalId in interface SchemaRegistryClient

Parameters:

globalId - the global ID returned by a prior SchemaRegistryClient.register(java.lang.String, byte[], com.aim2be.platform.schema.SchemaRegistryClient.SchemaType) call

Returns:

the schema record, or null if no such globalId. Sentinel-field contract: the Apicurio v2 REST API has no direct globalId → (subject, version) lookup, so impls that hydrate via the content-by-globalId endpoint return a SchemaRegistryClient.Schema with subject="" and version=0 as sentinels. Callers that need subject/version coordinates must use SchemaRegistryClient.fetchLatestBySubject(String) instead.

fetchLatestBySubject

public SchemaRegistryClient.Schema fetchLatestBySubject(String subject)

Description copied from interface: SchemaRegistryClient

Fetches the latest schema body registered under subject.

Specified by:

fetchLatestBySubject in interface SchemaRegistryClient

Parameters:

subject - the subject name

Returns:

the schema record, or null if no such subject

kind

public SchemaRegistryClient.Kind kind()

Description copied from interface: SchemaRegistryClient

Returns the implementation kind. Used for observability tagging (the kind shows up as schema.registry on every OTel span this client emits) and for callers that need to choose between Apicurio globalId semantics and Confluent schemaId semantics in their producer code path.

Specified by:

kind in interface SchemaRegistryClient

Returns:

the implementation kind; never null

wireFormat

public WireFormat wireFormat()

Description copied from interface: SchemaRegistryClient

Returns the wire format this client emits / parses. Defaults to WireFormat.APICURIO_8_BYTE — the Apicurio native prefix. ConfluentWireCompatSchemaRegistryClient overrides this to WireFormat.CONFLUENT_4_BYTE.

Specified by:

wireFormat in interface SchemaRegistryClient

Returns:

the wire format; never null

getPrimary

public SchemaRegistryClient getPrimary()

Returns:

the primary delegate. Useful for diagnostic introspection.

getFallback

public SchemaRegistryClient getFallback()

Returns:

the fallback delegate. Useful for diagnostic introspection.