timebase-java-client

name	timebase-java-client
description	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.

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