Class KrabkaSchemaRegistryClient

java.lang.Object
io.krabka.streams.schema.KrabkaSchemaRegistryClient
public final class KrabkaSchemaRegistryClient extends Object
A nonblocking client for the Confluent Schema Registry REST API.

Every operation returns a CompletableFuture and no method blocks the calling thread; requests run on the HttpClient's executor. Transport errors, HTTP 429, and 5xx responses are retried up to the configured retry count. Failed futures complete with SchemaRegistryException (usually wrapped in a CompletionException).

Applications rarely call this client directly for serialization; they hand it to a SchemaCache, which layers caching and prewarming on top. Direct use suits tooling: registering schemas from a pipeline, checking compatibility levels, or cleaning up subjects.

Example

var client = new KrabkaSchemaRegistryClient(URI.create("http://localhost:8081"));

int id = client.register("orders-value", SchemaKind.AVRO, orderSchema, null).join();
var latest = client.latest("orders-value").join();
List<String> subjects = client.subjects().join();

  • Constructor Details

    • KrabkaSchemaRegistryClient

      public KrabkaSchemaRegistryClient(URI baseUri)
      Creates a client with a default HTTP client, default mapper, and two retries.
      Parameters:
      baseUri - the registry base URI, for example http://localhost:8081

    • KrabkaSchemaRegistryClient

      public KrabkaSchemaRegistryClient(URI baseUri, HttpClient httpClient, com.fasterxml.jackson.databind.ObjectMapper objectMapper)
      Creates a client with caller-supplied HTTP client and mapper and two retries.
      Parameters:
      baseUri - the registry base URI
      httpClient - the HTTP client that executes requests
      objectMapper - the mapper for request and response JSON

    • KrabkaSchemaRegistryClient

      public KrabkaSchemaRegistryClient(URI baseUri, HttpClient httpClient, com.fasterxml.jackson.databind.ObjectMapper objectMapper, int maxRetries)
      Creates a client with an explicit retry budget.
      Parameters:
      baseUri - the registry base URI
      httpClient - the HTTP client that executes requests
      objectMapper - the mapper for request and response JSON
      maxRetries - how many times a failed request is retried; zero disables retries
      Throws:
      IllegalArgumentException - if maxRetries is negative

    • KrabkaSchemaRegistryClient

      public KrabkaSchemaRegistryClient(URI baseUri, String username, String password)
      Creates a client that sends HTTP basic authentication with every request.
      Parameters:
      baseUri - the registry base URI
      username - the basic-auth user name
      password - the basic-auth password

  • Method Details

    • register

      public CompletableFuture<Integer> register(String subject, SchemaKind kind, String schema, String messageType)
      Registers a schema under a subject without references.

      Registration is idempotent: registering a schema the subject already has returns the existing ID.

      Parameters:
      subject - the registry subject name
      kind - the schema format
      schema - the schema text
      messageType - the Protobuf message full name, or null for other formats
      Returns:
      a future with the registered schema's ID

    • register

      public CompletableFuture<Integer> register(String subject, SchemaKind kind, String schema, String messageType, List<KrabkaSchemaRegistryClient.SchemaReference> references)
      Registers a schema under a subject with schema references.
      Parameters:
      subject - the registry subject name
      kind - the schema format
      schema - the schema text
      messageType - the Protobuf message full name, or null for other formats
      references - the schemas this schema refers to
      Returns:
      a future with the registered schema's ID

    • lookup

      public CompletableFuture<Integer> lookup(String subject, SchemaKind kind, String schema, String messageType)
      Looks up the ID of an already registered schema without references.
      Parameters:
      subject - the registry subject name
      kind - the schema format
      schema - the schema text to look up
      messageType - the Protobuf message full name, or null for other formats
      Returns:
      a future with the schema's ID; fails with HTTP 404 when unregistered

    • lookup

      public CompletableFuture<Integer> lookup(String subject, SchemaKind kind, String schema, String messageType, List<KrabkaSchemaRegistryClient.SchemaReference> references)
      Looks up the ID of an already registered schema with schema references.
      Parameters:
      subject - the registry subject name
      kind - the schema format
      schema - the schema text to look up
      messageType - the Protobuf message full name, or null for other formats
      references - the schemas this schema refers to
      Returns:
      a future with the schema's ID; fails with HTTP 404 when unregistered

    • latest

      public CompletableFuture<KrabkaSchemaRegistryClient.RegisteredSchema> latest(String subject)
      Fetches the latest registered version of a subject.
      Parameters:
      subject - the registry subject name
      Returns:
      a future with the latest version's metadata and schema text

    • latestId

      public CompletableFuture<Integer> latestId(String subject)
      Fetches the schema ID of a subject's latest version.
      Parameters:
      subject - the registry subject name
      Returns:
      a future with the latest version's schema ID

    • schemaById

      public CompletableFuture<KrabkaSchemaRegistryClient.FetchedSchema> schemaById(int schemaId)
      Fetches a schema by its global ID.
      Parameters:
      schemaId - the registry schema ID
      Returns:
      a future with the schema text and reference list; references are not resolved to their own schema texts

    • resolvedSchemaById

      public CompletableFuture<KrabkaSchemaRegistryClient.ResolvedSchema> resolvedSchemaById(int schemaId)
      Fetches a schema by ID and recursively resolves its references.

      Each referenced subject version is fetched, and its own references are resolved transitively. Reference cycles are tolerated: a subject version already being resolved on the current path is skipped.

      Parameters:
      schemaId - the registry schema ID
      Returns:
      a future with the schema text and every transitive reference's text

    • subjects

      public CompletableFuture<List<String>> subjects()
      Lists all subject names.
      Returns:
      a future with every subject known to the registry

    • versions

      public CompletableFuture<List<Integer>> versions(String subject)
      Lists a subject's version numbers.
      Parameters:
      subject - the registry subject name
      Returns:
      a future with the subject's version numbers in registry order

    • version

      public CompletableFuture<KrabkaSchemaRegistryClient.RegisteredSchema> version(String subject, int version)
      Fetches one specific version of a subject.
      Parameters:
      subject - the registry subject name
      version - the version number to fetch
      Returns:
      a future with the version's metadata and schema text

    • compatibility

      public CompletableFuture<String> compatibility(String subject)
      Reads a subject's compatibility level.
      Parameters:
      subject - the registry subject name
      Returns:
      a future with the compatibility level, for example BACKWARD

    • compatibility

      public CompletableFuture<String> compatibility()
      Reads the registry's global compatibility level.
      Returns:
      a future with the global compatibility level

    • setCompatibility

      public CompletableFuture<String> setCompatibility(String subject, String level)
      Sets a subject's compatibility level.
      Parameters:
      subject - the registry subject name
      level - the level to set, for example BACKWARD or FULL
      Returns:
      a future with the level the registry acknowledged

    • setCompatibility

      public CompletableFuture<String> setCompatibility(String level)
      Sets the registry's global compatibility level.
      Parameters:
      level - the level to set, for example BACKWARD or FULL
      Returns:
      a future with the level the registry acknowledged

    • deleteSubject

      public CompletableFuture<List<Integer>> deleteSubject(String subject, boolean permanent)
      Deletes a subject and all of its versions.
      Parameters:
      subject - the registry subject name
      permanent - whether to hard-delete instead of soft-delete
      Returns:
      a future with the deleted version numbers

    • deleteVersion

      public CompletableFuture<Integer> deleteVersion(String subject, int version, boolean permanent)
      Deletes one version of a subject.
      Parameters:
      subject - the registry subject name
      version - the version number to delete
      permanent - whether to hard-delete instead of soft-delete
      Returns:
      a future with the deleted version number