# Timebase Java Client

> Use when user explicitly asks for TimeBase Java client code, for example typed stream reads/writes, stream creation, bound QQL execution from Java, client Maven/Gradle setup (Community or Enterprise Edition), or TimeBase Java client debugging.

- Skill: `epam/timebase-java-client` (Agent Skill, multi-file: 40 files)
- Install (CLI): `npx skillmds@latest add epam/timebase-java-client`
- Raw SKILL.md: https://api.skillmd.com/api/skills/epam/timebase-java-client/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: epam (https://skillmd.com/u/epam)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/epam/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