Skip to main content

Java Business ID Generation

Evidence boundary: the interfaces and in-memory implementation behavior below were verified from teaql-core/teaql-runtime 1.525-RELEASE JAR signatures and bytecode. Automatic assignment during a generated application save has not been verified and is not claimed.

A business ID is an external or human-facing value such as an order, invoice, shipment, or case number. It is not TeaQL's internal entity ID.

Current Interface​

public interface BusinessIdGenerator {
    String generateBusinessId(
        UserContext ctx,
        Entity entity,
        EntityDescriptor entityDesc,
        PropertyDescriptor propertyDesc);
}

UserContext.generateBusinessId(...) delegates to a registered BusinessIdGenerator capability and throws when the capability is absent.

Capability Registration​

DefaultUserContext.capability(...) reads values stored under the capability class name. Register during context creation:

ctx.put(BusinessIdGenerator.class.getName(), businessIdGenerator);

Make that part of the context assembler/factory so every request receives the same application policy.

Assignment Boundary​

Runtime saveGraph(...) automatically invokes only the internal ID service; no automatic BusinessIdGenerator call was found in the released runtime path. The application creation policy must therefore:

  1. resolve the entity and property descriptors from current generated/runtime metadata;
  2. generate only when the business field is absent;
  3. call ctx.generateBusinessId(...);
  4. assign through the exact update method emitted by the generated entity;
  5. persist with auditAs(...) before save(...).

Do not copy an updateOrderNumber(...) method from an example without checking the generated entity.

Released In-Memory Implementation​

InMemoryBusinessIdGenerator reads business_id_rule from the property descriptor's additional information. The released implementation interprets PREFIX, LENGTH, uses the current date as yyyyMMdd, and defaults the sequence length to six. Its counters are stored in a process-local concurrent map.

That format belongs to this implementation; it is not a universal BusinessIdGenerator contract. Confirm how the current generator emits the metadata before relying on a KSML attribute spelling.

Because the counter resets with the process, the in-memory implementation is appropriate for isolated tests and evaluation—not as evidence of cluster-wide uniqueness.

Production Requirements​

  • Define global, tenant, region, or daily uniqueness scope.
  • Decide whether gaps after rollback/retry are acceptable.
  • Keep numbers immutable after successful creation.
  • Avoid embedding sensitive tenant/user data.
  • Test concurrent allocation, restart, failover, and duplicate-request retry.
  • Put a database uniqueness constraint on the business field when appropriate.

See Configure a Custom ID Generator for the complete decision and verification matrix.