Skip to main content

Java Internal ID Generation

Evidence boundary: the API below was verified from teaql-core and teaql-runtime 1.525-RELEASE JAR signatures and bytecode. The current generated Java Golden Path is blocked before execution, so custom implementations still require an application build and provider-backed tests.

Internal IDs are persistence identities used for primary keys and entity references. Keep them separate from external business numbers.

Current Interface​

The released extension point is InternalIdGenerationService:

public interface InternalIdGenerationService {
    Long generateId(UserContext ctx, Entity entity);

    default long nextId(String typeName) {
        throw new UnsupportedOperationException(/* current runtime message */);
    }
}

generateId(...) is the entity-save path. nextId(...) is the lower-level path for framework components that need an ID with only a logical type name.

Runtime Registration​

Register the service during runtime construction:

TeaQLRuntime runtime = TeaQLRuntime.builder()
    .metadata(metaFactory)
    .idGenerationService(internalIdGenerationService)
    .build();

In runtime 1.525-RELEASE, saveGraph(...) checks whether the entity ID is null. When a service is registered, it calls generateId(ctx, entity) and uses the framework's internal assignment method before mutation execution. Application code must not call __internalSet(...) or patch generated entity dispatch methods.

Implementation Shape​

public final class ExternalInternalIdGenerationService
        implements InternalIdGenerationService {
    private final ExternalIdClient client;

    public ExternalInternalIdGenerationService(ExternalIdClient client) {
        this.client = client;
    }

    @Override
    public Long generateId(UserContext ctx, Entity entity) {
        return client.nextId(entity.typeName());
    }

    @Override
    public long nextId(String typeName) {
        return client.nextId(typeName);
    }
}

ExternalIdClient is application infrastructure, not a TeaQL type. Verify its thread safety, topology, failure behavior, and uniqueness guarantees.

The released teaql-sql-portable:1.525-RELEASE artifact also contains IdSpaceIdGenerator, backed by a teaql_id_space table. Its suitability still depends on the selected TeaQLDatabase, transaction semantics, DDL policy, and concurrency tests.

What Not to Use​

Older examples that invent a project interface named InternalIdGenerator, override a generic checkAndFix(Object), or call BaseEntity.setId(...) are not the verified 1.525-RELEASE runtime contract. Use the runtime builder and InternalIdGenerationService instead.

Verification​

  • Save new and existing entities and confirm IDs are assigned only when absent.
  • Save a graph with several new entity types.
  • Test concurrent allocation across every deployment node.
  • Test retry, restart, rollback, clock failure, and provider failover behavior.
  • Confirm generated source remains untouched.

See Configure a Custom ID Generator for the cross-stack decision and production test matrix.