epam/timebase-agent-plugins/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`: routing table
• `references/mcp-assisted-discovery.md`: MCP discovery order
• `references/project-setup.md`: dependencies, repository, credentials, verification
• `references/message-types-and-schema.md`: POJOs, introspector, schema types
• `references/cursor-and-streams.md`: select/cursor filters, dynamic resubscription, live and reversed reads, multi-stream select
• `references/loader-writes.md`: TickLoader writes, write modes, error handling
• `references/stream-management.md`: stream creation, metadata, lifecycle, data removal
• `references/qql-execution-from-java.md`: executeQuery, bind parameters, embedded subscription
• `references/schema-evolution.md`: schema change analysis and application
• `references/locking-and-securities-update.md`: stream locking, bulk reference-data-stream rewrite pattern
• `references/json-message-conversion.md`: converting between JSON and a TimeBase message
• `references/stream-spaces.md`: reading/writing named stream partitions
• `references/import-export.md`: bulk file archive export/import
• `references/symbol-mapping-and-sync.md`: stream copy with symbol remapping, cross-instance sync
• `references/array-fields-and-codecs.md`: raw array-typed fields, custom debug printing
• `references/topics.md`: low-latency pub/sub as an alternative to durable streams
• `references/authentication.md`: connection entry points, username/password and OAuth2 setup, incl. Enterprise-only flows
• `references/api-discovery.md`: API checks
• `references/debugging-and-performance.md`: build, connection, binding, and throughput failures