Engine configuration

Configure the xbbg Java engine.

An immutable EngineConfig built with EngineConfig.builder() controls the Bloomberg transport, authorization, TLS, worker pools, request policies, subscription buffers, and SDK logging. Every field is optional.

Apply a configuration

import io.github.underloam.xbbg.Engine;
import io.github.underloam.xbbg.EngineConfig;
import io.github.underloam.xbbg.KeyColumn;
import io.github.underloam.xbbg.Xbbg;
import java.util.concurrent.CompletableFuture;

public class ConfigureEngineExample {
  public static void main(String[] args) {
    EngineConfig config =
        EngineConfig.builder()
            .host("localhost")
            .port(8194)
            .keyColumn(KeyColumn.SECURITY)
            .requestTimeoutMs(120_000)
            .build();

    // 1. Configure the shared engine used by Blp.* and Xbbg.engine().
    // Nothing connects until the first Blp.* or Xbbg.engine() call.
    Xbbg.configure(config);

    // 2. Open a dedicated Engine synchronously (blocks until sessions are ready).
    try (Engine engine = Engine.open(config)) {
      System.out.println("Available: " + engine.isAvailable() + ", keyColumn: " + engine.keyColumn());
    }

    // 3. Or connect a dedicated Engine asynchronously.
    CompletableFuture<Engine> futureEngine = Engine.connect(config);
    try (Engine asyncEngine = Xbbg.await(futureEngine)) {
      System.out.println("Async engine available: " + asyncEngine.isAvailable());
    }
  }
}

• Xbbg.configure(host, port) is shorthand for Xbbg.configure(EngineConfig.builder().host(host).port(port).build()). Xbbg.resetConfiguration() restores the default localhost:8194 configuration and closes any previously connected shared engine.
• EngineConfig#toBuilder() creates a new EngineConfig.Builder initialized with an existing configuration's fields. Passing null to an object setter on EngineConfig.Builder omits that field again.
• Builder setters check numeric ranges immediately (for example, ports must be 0..65535 and unsigned counts must not be negative, throwing IllegalArgumentException), and multi-field rules (such as combining zfpRemote with host or omitting required tls material) are validated by the native engine before any Bloomberg session starts, throwing BlpValidationException.

Connection

Builder method	Default	Meaning
host(String)	"localhost"	Host of a Desktop API session or direct Bloomberg endpoint.
port(int)	8194	TCP port (0..65535) for host.
servers(ServerAddress...) / servers(Collection<ServerAddress>)	empty	Ordered failover list of ServerAddress.of(host, port); replaces host and port when non-empty.
zfpRemote(String)	unset	"8194" or "8196": connect over a Zero Footprint (ZFP) leased line. Requires tls; cannot be combined with host, port, servers, or socks5.
auth(AuthConfig)	unset	Session identity authorization; see Authorization.
tls(TlsConfig)	unset	TLS client credentials and trust material; see TLS.
socks5(Socks5Config)	unset	Socks5Config.of(host, port) of a SOCKS5 proxy applied to every direct server connection.
numStartAttempts(int)	3	Session start attempts before the engine fails to start.
autoRestartOnDisconnection(boolean)	true	Let the Bloomberg SDK automatically restart a session after a disconnect.

B-PIPE and Server API hosts with failover

import io.github.underloam.xbbg.AuthConfig;
import io.github.underloam.xbbg.EngineConfig;
import io.github.underloam.xbbg.KeyColumn;
import io.github.underloam.xbbg.ServerAddress;
import io.github.underloam.xbbg.TlsConfig;
import io.github.underloam.xbbg.TlsMaterial;
import java.nio.file.Paths;

public class BpipeFailoverConfig {
  public static EngineConfig buildConfig(String tlsPassword) {
    return EngineConfig.builder()
        .servers(
            ServerAddress.of("bbg-primary.example.com", 8194),
            ServerAddress.of("bbg-secondary.example.com", 8194))
        .auth(AuthConfig.userApp("my-bpipe-app"))
        .tls(
            TlsConfig.builder()
                .clientCredentials(TlsMaterial.path(Paths.get("/etc/bpipe/client.p12")))
                .clientCredentialsPassword(tlsPassword)
                .trustMaterial(TlsMaterial.path(Paths.get("/etc/bpipe/trust.p7")))
                .build())
        .keyColumn(KeyColumn.SECURITY)
        .build();
  }
}

Authorization

AuthConfig provides static factory methods for all six Bloomberg authorization modes:

Factory method	Wire method	Identity
AuthConfig.user()	"user"	The operating-system logon user.
AuthConfig.app(appName)	"app"	A registered B-PIPE / SAPI application name.
AuthConfig.userApp(appName)	"userapp"	The operating-system logon user together with a registered application.
AuthConfig.directory(dirProperty)	"directory"	A user looked up through an Active Directory property.
AuthConfig.manual(appName, userId, ipAddress)	"manual"	An explicitly supplied Bloomberg user ID and IP address paired with an application name.
AuthConfig.token(token)	"token"	A pre-generated authorization token (toString() redacts the token).

Identity calls (engine.seatType(), engine.checkEntitlements(...), engine.identityIsAuthorized(...)) authorize lazily using the engine's AuthConfig, or as the Desktop logon user when auth is unset.

TLS

TlsConfig pairs clientCredentials (PKCS#12) and trustMaterial (PKCS#7). Both materials must be supplied as file paths (TlsMaterial.path(Path) or TlsMaterial.path(String)) or both as in-memory DER bytes (TlsMaterial.bytes(byte[]) or TlsMaterial.bytes(ByteBuffer)). Mixing a path with bytes is rejected.

TlsConfig.Builder method	Meaning
clientCredentials(TlsMaterial)	PKCS#12 client credentials (file path or DER bytes).
clientCredentialsPassword(String)	Password for the client credentials (defaults to empty string when omitted).
trustMaterial(TlsMaterial)	PKCS#7 trusted certificates (file path or DER bytes).
handshakeTimeoutMs(int)	TLS handshake timeout in milliseconds (non-negative; SDK default when omitted).
crlFetchTimeoutMs(int)	Certificate revocation list fetch timeout in milliseconds (non-negative; SDK default when omitted).

In-memory TlsMaterial.bytes(...) copies the byte array or ByteBuffer immediately and passes DER bytes directly to the Bloomberg SDK without writing temporary files to disk:

import io.github.underloam.xbbg.AuthConfig;
import io.github.underloam.xbbg.EngineConfig;
import io.github.underloam.xbbg.TlsConfig;
import io.github.underloam.xbbg.TlsMaterial;
import java.util.Base64;

public class InMemoryTlsConfig {
  public static EngineConfig fromBase64Secrets(
      String p12Base64, String p7Base64, String password) {
    byte[] clientDer = Base64.getDecoder().decode(p12Base64);
    byte[] trustDer = Base64.getDecoder().decode(p7Base64);

    return EngineConfig.builder()
        .host("bpipe.example.com")
        .port(8194)
        .auth(AuthConfig.app("my-bpipe-app"))
        .tls(
            TlsConfig.builder()
                .clientCredentials(TlsMaterial.bytes(clientDer))
                .clientCredentialsPassword(password)
                .trustMaterial(TlsMaterial.bytes(trustDer))
                .handshakeTimeoutMs(10_000)
                .crlFetchTimeoutMs(5_000)
                .build())
        .build();
  }
}

ZFP leased lines and SOCKS5 proxies

import io.github.underloam.xbbg.EngineConfig;
import io.github.underloam.xbbg.Socks5Config;
import io.github.underloam.xbbg.TlsConfig;
import io.github.underloam.xbbg.TlsMaterial;

public class ZfpAndSocks5Config {
  public static EngineConfig zfpConfig(String password) {
    return EngineConfig.builder()
        .zfpRemote("8194")
        .tls(
            TlsConfig.builder()
                .clientCredentials(TlsMaterial.path("/etc/bpipe/client.p12"))
                .clientCredentialsPassword(password)
                .trustMaterial(TlsMaterial.path("/etc/bpipe/trust.p7"))
                .build())
        .build();
  }

  public static EngineConfig socks5Config() {
    return EngineConfig.builder()
        .host("bpipe.example.com")
        .port(8194)
        .socks5(Socks5Config.of("proxy.example.com", 1080))
        .build();
  }
}

Requests, retries, and validation

Builder method	Default	Meaning
requestTimeoutMs(long)	0 (disabled)	Hard per-request timeout in milliseconds. Timed-out requests fail with BlpTimeoutException.
retryPolicy(RetryPolicy)	maxRetries=0, initialDelayMs=1000, backoffFactor=2.0, maxDelayMs=30000	Retries transient session/worker failures only; Bloomberg request, validation, and timeout errors are never retried.
validationMode(ValidationMode)	ValidationMode.DISABLED	Field validation for bdp, bds, and bdh: DISABLED, LENIENT, or STRICT.
fieldCachePath(Path) / fieldCachePath(String)	~/.xbbg/field_cache.json	File path for the persisted field-type cache.
bqlAppName(String)	unset	Default BQL clientContext.appName element (must not be blank; independent of auth).
keyColumn(KeyColumn)	KeyColumn.TICKER (deprecated)	Name of the security column in request and recipe results: KeyColumn.TICKER or KeyColumn.SECURITY.

import io.github.underloam.xbbg.EngineConfig;
import io.github.underloam.xbbg.KeyColumn;
import io.github.underloam.xbbg.RetryPolicy;
import io.github.underloam.xbbg.ValidationMode;

public class RequestPolicyConfig {
  public static EngineConfig buildConfig() {
    return EngineConfig.builder()
        .requestTimeoutMs(120_000)
        .retryPolicy(
            RetryPolicy.builder()
                .maxRetries(3)
                .initialDelayMs(500)
                .backoffFactor(2.0)
                .maxDelayMs(10_000)
                .build())
        .validationMode(ValidationMode.STRICT)
        .keyColumn(KeyColumn.SECURITY)
        .bqlAppName("research-pipeline")
        .build();
  }
}

Sharding wide requests

Builder method	Default	Meaning
shardRequests(boolean)	false	Split eligible multi-security bdp and bdh requests into concurrent shards.
shardThreshold(int)	20	Minimum number of securities before sharding applies (at least 2).
shardChunkSize(int)	16	Maximum number of securities per shard.
shardMaxConcurrent(int)	4	Maximum in-flight shards per request.

Sharded results preserve input order and merge result metadata, entitlement IDs, and Bloomberg support RequestIds across all shards.

Pools and runtime threads

Builder method	Default	Meaning
requestPoolSize(int)	2	Number of request worker sessions (must be at least 1).
runtimeWorkerThreads(int)	2	Threads in the native async runtime (must be at least 1).
subscriptionPoolSize(int)	1	Pre-warmed subscription sessions started with the engine (0 or more).
maxSubscriptionSessions(int)	32	Maximum live subscription sessions (at least 1 and at least subscriptionPoolSize).
warmupServices(Collection<String>)	["//blp/refdata", "//blp/apiflds"]	Bloomberg services opened when request workers start; an empty collection opens none.

Subscriptions and session health

Builder method	Default	Meaning
subscriptionStreamCapacity(int)	256	Default per-subscription buffer capacity (at least 1); overridden per stream by StreamOptions.Builder#streamCapacity.
overflowPolicy(OverflowPolicy)	OverflowPolicy.DROP_NEWEST	Buffer overflow behavior: DROP_NEWEST (closes with BlpSubscriptionDataLossException), BLOCK (waits briefly on a forwarding task, then fails if still full), or DROP_OLDEST (evicts oldest updates and reports exact counts via sub.deliveries()).
subscriptionFlushThreshold(int)	16	Maximum already-queued updates combined into one subscription read batch (at least 1).
streamsDeactivatedWarnMs(long)	30000	Emit a warning event when a topic's streams stay deactivated this long (0 disables).
maxEventQueueSize(int)	10000	Bloomberg SDK event queue size.
commandQueueSize(int)	256	Internal command channel capacity (at least 1).
slowConsumerHiWaterMark(double)	0.75	Slow-consumer warning high water mark (0.0..1.0 of maxEventQueueSize).
slowConsumerLoWaterMark(double)	0.5	Slow-consumer warning low water mark (0.0 up to < 1.0).
keepAliveEnabled(boolean)	true	Enable Bloomberg SDK keep-alive pings.
keepAliveInactivityMs(int)	20000	Idle time in milliseconds before sending a keep-alive ping.
keepAliveResponseTimeoutMs(int)	10000	Time in milliseconds to wait for a keep-alive response before declaring the connection down.

Logging, warnings, and callback executors

Native and SDK logging

• Xbbg.setLogLevel(LogLevel) and Xbbg.getLogLevel() control xbbg's process-wide native log level on stderr: LogLevel.TRACE, DEBUG, INFO, WARN (default), or ERROR.
• EngineConfig.Builder#sdkLogLevel(SdkLogLevel) controls the Bloomberg C++ SDK's own logging: SdkLogLevel.OFF (default), FATAL, ERROR, WARN, INFO, DEBUG, or TRACE. SDK messages are forwarded into the xbbg native log.

Structured warnings (XbbgWarnings)

Diagnostics that are not errors — delayed data on requests (BlpDelayedDataWarning / XBBG_DELAYED_DATA) or streams (BlpDelayedDataWarning / XBBG_DELAYED_STREAM), rejected subscription fields (BlpFieldWarning / XBBG_FIELD_EXCEPTION), and the once-per-JVM ticker key-column deprecation (DeprecationWarning / XBBG_TICKER_KEY_COLUMN) — are delivered through XbbgWarnings.

When no listener is registered, warnings are logged to the java.util.logging logger io.github.underloam.xbbg at Level.WARNING. Registering a listener with XbbgWarnings.addListener(...) routes all warnings to your listener instead:

import io.github.underloam.xbbg.LogLevel;
import io.github.underloam.xbbg.Xbbg;
import io.github.underloam.xbbg.XbbgWarning;
import io.github.underloam.xbbg.XbbgWarnings;
import java.util.function.Consumer;

public class LoggingAndWarningsExample {
  public static void main(String[] args) {
    Xbbg.setLogLevel(LogLevel.INFO);

    Consumer<XbbgWarning> listener =
        warning ->
            System.err.println(
                warning.type()
                    + " ["
                    + warning.code()
                    + "]: "
                    + warning.message()
                    + warning.detail().map(d -> " (" + d + ")").orElse(""));

    XbbgWarnings.addListener(listener);
  }
}

Callback executor

By default, xbbg completes its CompletableFutures on a cached pool of daemon threads named xbbg-callback-N. You can inspect or replace this executor with Xbbg.callbackExecutor() and Xbbg.setCallbackExecutor(Executor) (pass null to restore the default), or call VirtualThreads.useForCallbacks() from io.github.underloam:xbbg-jdk17 on Java 21+ so every future completion runs on its own virtual thread.

WARNING

Never pass a same-thread executor (such as Runnable::run) if your callbacks block on Xbbg.await(...) or blocking subscription reads: a same-thread executor runs directly on the native bridge thread, which would stall other native completions.

Related pages

Installation

Configure the Bloomberg runtime path or provisioning source with Xbbg.setSdkPath and Xbbg.setSdkSource.

Quickstart

Choose between Xbbg.configure(), Engine.connect(), and Engine.open().

Streaming

Per-subscription buffers, overflow policies, and shared feeds.

Node.js configuration

The identical engine configuration surface in @xbbg/core.