Package io.apicurio.registry.client.common

Class RegistryClientOptions

java.lang.Object
io.apicurio.registry.client.common.RegistryClientOptions
public class RegistryClientOptions extends Object
Configuration options for creating a RegistryClient. This class encapsulates all the configuration parameters needed to create different types of registry clients.

The options support the following authentication methods:

  • Anonymous (no authentication)
  • Basic authentication (username/password)
  • OAuth2/OIDC authentication (client credentials)
  • Custom WebClient (for advanced scenarios)

  • Method Details

    • create

      public static RegistryClientOptions create()

      Warning: If you do not provide a Vertx instance, we will try to retrieve it from the current CDI context. If that fails, we will use a default instance managed by

      invalid reference 
      DefaultVertxInstance
      .

      However, using the default Vertx instance is not recommended for production use. Applications should manage their own Vertx instance and provide it via vertx(Vertx) to ensure proper lifecycle management and resource cleanup.

    • create

      public static RegistryClientOptions create(String registryUrl)

      Warning: If you do not provide a Vertx instance, we will try to retrieve it from the current CDI context. If that fails, we will use a default instance managed by

      invalid reference 
      DefaultVertxInstance
      .

      However, using the default Vertx instance is not recommended for production use. Applications should manage their own Vertx instance and provide it via vertx(Vertx) to ensure proper lifecycle management and resource cleanup.

    • create

      public static RegistryClientOptions create(String registryUrl, io.vertx.core.Vertx vertx)

    • getRegistryUrl

      public String getRegistryUrl()

    • getNormalizeRegistryUrl

      public boolean getNormalizeRegistryUrl()

    • getAuthType

      public RegistryClientOptions.AuthType getAuthType()

    • getUsername

      public String getUsername()

    • getPassword

      public String getPassword()

    • getTokenEndpoint

      public String getTokenEndpoint()

    • getClientId

      public String getClientId()

    • getClientSecret

      public String getClientSecret()

    • getScope

      public String getScope()

    • getVertx

      public io.vertx.core.Vertx getVertx()

    • getWebClient

      public io.vertx.ext.web.client.WebClient getWebClient()

    • isRetryEnabled

      public boolean isRetryEnabled()

    • getMaxRetryAttempts

      public int getMaxRetryAttempts()

    • getRetryDelayMs

      public long getRetryDelayMs()

    • getBackoffMultiplier

      public double getBackoffMultiplier()

    • getMaxRetryDelayMs

      public long getMaxRetryDelayMs()

    • getTrustStoreType

      public RegistryClientOptions.TrustStoreType getTrustStoreType()

    • getTrustStorePath

      public String getTrustStorePath()

    • getTrustStorePassword

      public String getTrustStorePassword()

    • getPemCertPaths

      public String[] getPemCertPaths()

    • getPemCertContent

      public String getPemCertContent()

    • isTrustAll

      public boolean isTrustAll()

    • isVerifyHost

      public boolean isVerifyHost()

    • getProxyHost

      public String getProxyHost()

    • getProxyPort

      public int getProxyPort()

    • getProxyUsername

      public String getProxyUsername()

    • getProxyPassword

      public String getProxyPassword()

    • getKeyStoreType

      public RegistryClientOptions.KeyStoreType getKeyStoreType()

    • getKeyStorePath

      public String getKeyStorePath()

    • getKeyStorePassword

      public String getKeyStorePassword()

    • getPemClientCertPath

      public String getPemClientCertPath()

    • getPemClientKeyPath

      public String getPemClientKeyPath()

    • getPemClientCertContent

      public String getPemClientCertContent()

    • getPemClientKeyContent

      public String getPemClientKeyContent()

    • getHttpAdapterType

      public HttpAdapterType getHttpAdapterType()

    • isOtelEnabled

      public boolean isOtelEnabled()

    • registryUrl

      public RegistryClientOptions registryUrl(String registryUrl)
      Sets the registry URL.

      If the protocol or the API path is not provided (e.g., "localhost:8080"), it will be added.

      Parameters:
      registryUrl - the base URL of the registry API (e.g., "http://localhost:8080/apis/registry/v3")
      Returns:
      this builder

    • rawRegistryUrl

      public RegistryClientOptions rawRegistryUrl(String registryUrl)
      Sets the registry URL.

      URL will not be modified, but valid URL is still required.

      Parameters:
      registryUrl - the base URL of the registry API (e.g., "http://localhost:8080/apis/registry/v3")
      Returns:
      this builder

    • basicAuth

      public RegistryClientOptions basicAuth(String username, String password)
      Configures basic authentication.
      Parameters:
      username - the username for basic authentication
      password - the password for basic authentication
      Returns:
      this builder

    • oauth2

      public RegistryClientOptions oauth2(String tokenEndpoint, String clientId, String clientSecret)
      Configures OAuth2/OIDC authentication using client credentials flow.
      Parameters:
      tokenEndpoint - the OAuth2 token endpoint URL
      clientId - the OAuth2 client ID
      clientSecret - the OAuth2 client secret
      Returns:
      this builder

    • oauth2

      public RegistryClientOptions oauth2(String tokenEndpoint, String clientId, String clientSecret, String scope)
      Configures OAuth2/OIDC authentication using client credentials flow with scope.
      Parameters:
      tokenEndpoint - the OAuth2 token endpoint URL
      clientId - the OAuth2 client ID
      clientSecret - the OAuth2 client secret
      scope - the OAuth2 scope (optional, can be null)
      Returns:
      this builder

    • customWebClient

      public RegistryClientOptions customWebClient(io.vertx.ext.web.client.WebClient webClient)
      Configures a custom WebClient for advanced authentication scenarios.
      Parameters:
      webClient - the pre-configured WebClient to use
      Returns:
      this builder

    • retry

      public RegistryClientOptions retry(boolean enabled, int maxAttempts, long initialDelayMs)
      Configures retry functionality for HTTP requests.
      Parameters:
      enabled - whether retry functionality is enabled
      maxAttempts - the maximum number of retry attempts (must be > 0 if enabled)
      initialDelayMs - the initial delay between retry attempts in milliseconds (must be > 0 if enabled)
      Returns:
      this builder

    • retry

      public RegistryClientOptions retry(boolean enabled, int maxAttempts, long initialDelayMs, double backoffMultiplier, long maxDelayMs)
      Configures retry functionality with exponential backoff for HTTP requests.
      Parameters:
      enabled - whether retry functionality is enabled
      maxAttempts - the maximum number of retry attempts (must be > 0 if enabled)
      initialDelayMs - the initial delay between retry attempts in milliseconds (must be > 0 if enabled)
      backoffMultiplier - the multiplier for exponential backoff (must be > 1.0 if enabled)
      maxDelayMs - the maximum delay between retries in milliseconds (must be > 0 if enabled)
      Returns:
      this builder

    • retry

      public RegistryClientOptions retry()
      Enables retry functionality with default settings (3 attempts, 1000ms initial delay, exponential backoff).
      Returns:
      this builder

    • disableRetry

      public RegistryClientOptions disableRetry()
      Disables retry functionality.
      Returns:
      this builder

    • vertx

      public RegistryClientOptions vertx(io.vertx.core.Vertx vertx)
      Sets a custom Vertx instance to use.
      Parameters:
      vertx - the Vertx instance to use
      Returns:
      this builder

    • trustStoreJks

      public RegistryClientOptions trustStoreJks(String path, String password)
      Configures SSL/TLS with a JKS (Java KeyStore) trust store. This allows the client to trust certificates signed by custom certificate authorities or self-signed certificates.
      Parameters:
      path - the path to the JKS trust store file (can be a file system path or classpath resource prefixed with "classpath:")
      password - the password for the trust store
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if path is null or empty

    • trustStorePkcs12

      public RegistryClientOptions trustStorePkcs12(String path, String password)
      Configures SSL/TLS with a PKCS#12 trust store. This allows the client to trust certificates signed by custom certificate authorities or self-signed certificates.
      Parameters:
      path - the path to the PKCS#12 trust store file (can be a file system path or classpath resource prefixed with "classpath:")
      password - the password for the trust store
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if path is null or empty

    • trustStorePem

      public RegistryClientOptions trustStorePem(String... certPaths)
      Configures SSL/TLS with PEM certificate file(s). This allows the client to trust certificates signed by custom certificate authorities or self-signed certificates.
      Parameters:
      certPaths - one or more paths to PEM certificate files (can be file system paths or classpath resources prefixed with "classpath:")
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if no certificate paths are provided

    • trustStorePemContent

      public RegistryClientOptions trustStorePemContent(String pemContent)
      Configures SSL/TLS with PEM certificate content (as a string). This allows the client to trust certificates without requiring file system access, which is useful in containerized or cloud environments where certificates are provided via environment variables or configuration systems.

      The content should be in standard PEM format with BEGIN/END markers. Multiple certificates can be provided in a single string, each delineated by the standard PEM markers (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----).

      Example:

       -----BEGIN CERTIFICATE-----
 MIIDXTCCAkWgAwIBAgIJAKJ0...
 -----END CERTIFICATE-----
 -----BEGIN CERTIFICATE-----
 MIIEYzCCA0ugAwIBAgIQAHmP...
 -----END CERTIFICATE-----
      Parameters:
      pemContent - the PEM certificate content as a string (may contain multiple certificates)
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if pemContent is null or empty

    • trustAll

      public RegistryClientOptions trustAll(boolean trustAll)
      Configures the client to trust all SSL/TLS certificates without validation.

      WARNING: This option should ONLY be used in development or testing environments. Using this in production environments creates a serious security vulnerability as it disables certificate validation, making the connection susceptible to man-in-the-middle attacks.

      Parameters:
      trustAll - if true, all certificates will be trusted without validation
      Returns:
      this builder

    • verifyHost

      public RegistryClientOptions verifyHost(boolean verifyHost)
      Configures whether to verify the hostname in the server's certificate matches the hostname being connected to. By default, hostname verification is enabled.

      WARNING: Disabling hostname verification reduces security and should only be done in development or testing environments.

      Parameters:
      verifyHost - if true, hostname verification will be performed (default); if false, it will be disabled
      Returns:
      this builder

    • clearTrustStore

      public RegistryClientOptions clearTrustStore()
      Clears any configured trust store settings, reverting to default JVM trust store.
      Returns:
      this builder

    • keystoreJks

      public RegistryClientOptions keystoreJks(String path, String password)
      Configures mutual TLS (mTLS) with a JKS (Java KeyStore) key store containing the client certificate. This enables client authentication where the server verifies the client's identity using the provided certificate.

      The key store should contain the client's private key and certificate chain.

      Parameters:
      path - the path to the JKS key store file (can be a file system path or classpath resource prefixed with "classpath:")
      password - the password for the key store
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if path is null or empty

    • keystorePkcs12

      public RegistryClientOptions keystorePkcs12(String path, String password)
      Configures mutual TLS (mTLS) with a PKCS#12 key store containing the client certificate. This enables client authentication where the server verifies the client's identity using the provided certificate.

      The key store should contain the client's private key and certificate chain.

      Parameters:
      path - the path to the PKCS#12 key store file (can be a file system path or classpath resource prefixed with "classpath:")
      password - the password for the key store
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if path is null or empty

    • keystorePem

      public RegistryClientOptions keystorePem(String certPath, String keyPath)
      Configures mutual TLS (mTLS) with PEM-formatted client certificate and private key files. This enables client authentication where the server verifies the client's identity using the provided certificate.

      The certificate file should contain the client certificate (and optionally the certificate chain). The key file should contain the unencrypted private key in PEM format.

      Parameters:
      certPath - the path to the PEM certificate file (can be a file system path or classpath resource prefixed with "classpath:")
      keyPath - the path to the PEM private key file (can be a file system path or classpath resource prefixed with "classpath:")
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if certPath or keyPath is null or empty

    • keystorePemContent

      public RegistryClientOptions keystorePemContent(String certContent, String keyContent)
      Configures mutual TLS (mTLS) with PEM-formatted client certificate and private key as strings. This enables client authentication where the server verifies the client's identity using the provided certificate. This method is useful in containerized or cloud environments where certificates are provided via environment variables or configuration systems.

      The certificate content should be in standard PEM format with BEGIN/END markers. The private key should be unencrypted and in PEM format.

      Example certificate format:

       -----BEGIN CERTIFICATE-----
 MIIDXTCCAkWgAwIBAgIJAKJ0...
 -----END CERTIFICATE-----

      Example private key format:

       -----BEGIN PRIVATE KEY-----
 MIIEvQIBADANBgkqhkiG9w0B...
 -----END PRIVATE KEY-----
      Parameters:
      certContent - the PEM certificate content as a string
      keyContent - the PEM private key content as a string
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if certContent or keyContent is null or empty, or doesn't contain valid PEM markers

    • clearKeyStore

      public RegistryClientOptions clearKeyStore()
      Clears any configured client certificate (key store) settings.
      Returns:
      this builder

    • proxy

      public RegistryClientOptions proxy(String host, int port)
      Configures an HTTP/HTTPS proxy for registry connections. This is useful in environments where direct internet access is restricted and all outbound connections must go through a proxy server.

      This proxy configuration will be used for both registry API calls and OAuth token endpoint calls (if OAuth authentication is configured).

      Parameters:
      host - the proxy server hostname or IP address
      port - the proxy server port number (typically 3128, 8080, or 8888)
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if host is null/empty or port is invalid

    • proxyAuth

      public RegistryClientOptions proxyAuth(String username, String password)
      Configures authentication credentials for the HTTP/HTTPS proxy. This should be called after proxy(String, int) if the proxy server requires authentication.
      Parameters:
      username - the proxy authentication username
      password - the proxy authentication password
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if username or password is null/empty

    • clearProxy

      public RegistryClientOptions clearProxy()
      Clears any configured proxy settings.
      Returns:
      this builder

    • httpAdapter

      public RegistryClientOptions httpAdapter(HttpAdapterType httpAdapterType)
      Sets the HTTP adapter type to use for client communication.

      The adapter type determines which underlying HTTP client implementation will be used:

      • HttpAdapterType.VERTX - Uses Vert.x WebClient (default when available). Requires kiota-http-vertx and vertx-auth-oauth2 dependencies.
      • HttpAdapterType.JDK - Uses JDK 11+ HttpClient. Requires kiota-http-jdk dependency. Minimal dependencies, better for simple apps.
      • HttpAdapterType.AUTO - Auto-detects available adapter at runtime. Prefers Vert.x if available, falls back to JDK adapter.

      Note: When using JDK adapter, the customWebClient(WebClient) option is not supported and will throw an exception at client creation time.

      Parameters:
      httpAdapterType - the HTTP adapter type to use
      Returns:
      this builder

    • enableOpenTelemetry

      public RegistryClientOptions enableOpenTelemetry()
      Enables OpenTelemetry trace context propagation for outgoing HTTP requests. When enabled, W3C trace context headers (traceparent, tracestate) will be injected into all HTTP requests made to the Registry.

      This requires the opentelemetry-api library to be on the classpath. If the OpenTelemetry API is not available at runtime, an IllegalStateException will be thrown when the client is created.

      Returns:
      this builder