timebase-java-client

# TimeBase Java Client ## Mission Teach correct use of the TimeBase Java client API: connection lifecycle, schema and binding, cursors and loaders, and QQL execution from Java. Prefer MCP-grounded stream and schema facts before generating code. ## When to use this skill Use only when the user explicitly requests Java together with TimeBase. Typical tasks: - reads/writes via `TickLoader`/`TickCursor`, - stream creation with `Introspector` or explicit `RecordClassDescriptor`, - `executeQuery` with bound result POJOs, - TimeBase Java client Maven/Gradle setup, - OAuth2 connection setup, - debugging binding, connection, or build/dependency-resolution failures. Do not use for pure QQL authoring with no Java binding (use the `qql-generator` skill instead) or for pure MCP discovery with no code to write. ## How to route requests 1. Confirm the user asked for Java + TimeBase, not generic Java help. 2. When stream names, schema, symbols, or time bounds matter, use MCP discovery first (`references/mcp-assisted-discovery.md`). 3. Detect the target project: Maven (`pom.xml`) or Gradle (`build.gradle`/`build.gradle.kts`). Preserve its existing Java version and dependency-management style. 4. Before generating connection, stream, or cursor/loader code, verify the exact API shape from the target project's dependency sources/javadoc or a compile probe. 5. Pick the smallest proven reference and example for the access pattern. 6. For project setup and build verification, use `references/project-setup.md`. ## Local API verification rules - Do not invent interfaces, members, or overloads from memory when dependency sources, javadoc, or compile checks are available. - If the API shape is still unclear after checking bundled references, use a small compile probe instead of guessing. ## Mandatory policy - Ground stream keys and schema from MCP or user input. Do not invent field names, type names, or stream keys. - Prefer built-in message types over inventing custom POJOs when schema matches. See `references/message-types-and-schema.md` for what's built in per edition. - Use raw (`RawMessage`) mode only for schemas without generated/bound classes. - When QQL authoring is central, use the QQL generator skill first. Return here for Java execution and binding when the user supplies final QQL. - Prefer QQL text with embedded subscription (stream union, symbol filter, time filter) over the deprecated `executeQuery` overloads that take explicit stream/entity/time-range arrays. - Use placeholder-based credentials for repository access and preserve any existing naming convention the project already uses. Never hardcode repository credentials. If dependency resolution fails with 401/403, report that the configured credentials are missing or incorrect. - Never assume Community vs Enterprise Edition. Resolve it per `references/project-setup.md` before generating dependency coordinates. - Keep `DXTickDB`, `TickCursor`, and `TickLoader` lifecycle explicit (try-with-resources). - Start read-only unless writes are required. Do not write to streams unless the user asked. ## MCP-first workflow When the task depends on live server context: 1. `get_server_configuration` 2. `list_streams` 3. `get_stream_schema` 4. `get_stream_time_range` and `get_stream_symbols` when needed 5. Generate Java using grounded names and types from those results If MCP is unavailable, state what is missing and ask the user for stream/schema context before finalizing bound types. ## Capability map - [`references/workflow-selection.md`](references/workflow-selection.md): routing table - [`references/mcp-assisted-discovery.md`](references/mcp-assisted-discovery.md): MCP discovery order - [`references/project-setup.md`](references/project-setup.md): dependencies, repository, credentials, verification - [`references/message-types-and-schema.md`](references/message-types-and-schema.md): POJOs, introspector, schema types - [`references/cursor-and-streams.md`](references/cursor-and-streams.md): select/cursor filters, dynamic resubscription, live and reversed reads, multi-stream select - [`references/loader-writes.md`](references/loader-writes.md): `TickLoader` writes, write modes, error handling - [`references/stream-management.md`](references/stream-management.md): stream creation, metadata, lifecycle, data removal - [`references/qql-execution-from-java.md`](references/qql-execution-from-java.md): `executeQuery`, bind parameters, embedded subscription - [`references/schema-evolution.md`](references/schema-evolution.md): schema change analysis and application - [`references/locking-and-securities-update.md`](references/locking-and-securities-update.md): stream locking, bulk reference-data-stream rewrite pattern - [`references/json-message-conversion.md`](references/json-message-conversion.md): converting between JSON and a TimeBase message - [`references/stream-spaces.md`](references/stream-spaces.md): reading/writing named stream partitions - [`references/import-export.md`](references/import-export.md): bulk file archive export/import - [`references/symbol-mapping-and-sync.md`](references/symbol-mapping-and-sync.md): stream copy with symbol remapping, cross-instance sync - [`references/array-fields-and-codecs.md`](references/array-fields-and-codecs.md): raw array-typed fields, custom debug printing - [`references/topics.md`](references/topics.md): low-latency pub/sub as an alternative to durable streams - [`references/authentication.md`](references/authentication.md): connection entry points, username/password and OAuth2 setup, incl. Enterprise-only flows - [`references/api-discovery.md`](references/api-discovery.md): API checks - [`references/debugging-and-performance.md`](references/debugging-and-performance.md): build, connection, binding, and throughput failures