Module me.ahoo.cosid.core
Package me.ahoo.cosid.runtime

Class CosIdRuntime

java.lang.Object
me.ahoo.cosid.runtime.CosIdRuntime
All Implemented Interfaces:
AutoCloseable
public final class CosIdRuntime extends Object implements AutoCloseable
The one registry and lifecycle owner of stores, the machine slot and generators (07-runtime-and-spring.md ยง1). Its generators are fixed at start (D17); there is no global singleton, and runtimes in one JVM do not share a slot. Code that needs ids gets the runtime, or its generators, from whoever started it: in Spring, inject the IdGenerator beans; static code (4.x DefaultIdGeneratorProvider.INSTANCE) keeps them in a holder of its own, set when the context has started and cleared when it closes (the migration guide shows one).

Lookups of a disabled generator (D24, GeneratorSpec.Disabled) throw GeneratorDisabledException.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes in reverse dependency order: generators (terminal state, time-based ones first), the slot (released with the largest timestamp they issued), stores, the own executor.
    Map<String,GeneratorInfo>
    describe()
    What each generator is: its layout, slot and window, its ready values and batch size, and the like.
    IdFiller
    filler()
    Fills CosId fields from this runtime's generators.
    OptionalLong
    generated(String name)
    The ids the generator of that name issued through the views of this runtime: its generator, stringGenerator, text(name), get by an interface type, periodic(name) excluded, and the filler(); a uuidv7 generator counts every id it issues, by its concrete type too.
    IdGenerator
    generator(String name)
    The long generator of that name.
    <T> T
    get(String name, Class<T> type)
    The generator of that name as type: an IdGenerator, PartsIdGenerator (time-based) or GroupedIdGenerator (periodic segment), the concrete generator (TimeBasedGenerator, SegmentGenerator, PeriodicSegmentGenerator, UuidV7Generator; never counted), or for long ids a StringIdGenerator, an IntIdGenerator (range checked) or its IdCodec; for the 80-bit CosId its PartsCodec; for a periodic segment its GroupedCodec.
    Set<String>
    machines()
    The machines that started: those an enabled time-based generator chose (D37).
    String
    namespace()
    The namespace of the runtime: of the default machine and of the segment keys.
    PeriodicSegmentGenerator
    periodic(String name)
    The periodic segment generator of that name.
    Optional<SlotLease>
    slot()
    The slot lease of the default machine.
    Optional<SlotLease>
    slot(String machine)
    The slot lease of a machine (D37).
    static CosIdRuntime
    start(RuntimeSpec spec, RuntimeOptions options)
    Checks the whole spec, then opens the stores, acquires the slot and creates the generators, rolling back what was created on failure.
    StringIdGenerator
    stringGenerator(String name)
    The long generator of that name with its codec.
    Supplier<String>
    text(String name)
    The text ids of the generator of that name, whatever its strategy (R1-int-01): the codec of its long ids, its parts codec (cosid80), its grouped codec (periodic segment) or the canonical UUID form (uuidv7, D46).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • start

      public static CosIdRuntime start(RuntimeSpec spec, RuntimeOptions options)
      Checks the whole spec, then opens the stores, acquires the slot and creates the generators, rolling back what was created on failure. The machine slot is acquired only when a time-based generator is enabled, and only the stores that the enabled generators and the slot use are opened.
      Parameters:
      spec - the spec
      options - the options
      Returns:
      the started runtime
      Throws:
      CosIdException - if the spec is invalid (a time-based generator without a machine, a layout narrower than the machine bits, an unknown store, a store timeout above the reserve timeout, ...) or a step fails

    • namespace

      public String namespace()
      The namespace of the runtime: of the default machine and of the segment keys.
      Returns:
      the namespace

    • generator

      public IdGenerator generator(String name)
      The long generator of that name.
      Parameters:
      name - the generator name
      Returns:
      the generator
      Throws:
      NoSuchElementException - if there is none, or it issues no long ids
      GeneratorDisabledException - if it is disabled

    • stringGenerator

      public StringIdGenerator stringGenerator(String name)
      The long generator of that name with its codec. For the text ids of any strategy, cosid80, periodic segments and uuidv7 included, use text(String).
      Parameters:
      name - the generator name
      Returns:
      the generator
      Throws:
      NoSuchElementException - if there is none, or it has no long ids (cosid80, periodic segment, uuidv7: use text(String))
      GeneratorDisabledException - if it is disabled

    • periodic

      public PeriodicSegmentGenerator periodic(String name)
      The periodic segment generator of that name.
      Parameters:
      name - the generator name
      Returns:
      the generator
      Throws:
      NoSuchElementException - if there is none
      GeneratorDisabledException - if it is disabled

    • generated

      public OptionalLong generated(String name)
      The ids the generator of that name issued through the views of this runtime: its generator, stringGenerator, text(name), get by an interface type, periodic(name) excluded, and the filler(); a uuidv7 generator counts every id it issues, by its concrete type too.
      Parameters:
      name - the generator name
      Returns:
      the count; empty unless RuntimeOptions.countGenerated() is on, or when it is disabled
      Throws:
      NoSuchElementException - if there is none

    • get

      public <T> T get(String name, Class<T> type)
      The generator of that name as type: an IdGenerator, PartsIdGenerator (time-based) or GroupedIdGenerator (periodic segment), the concrete generator (TimeBasedGenerator, SegmentGenerator, PeriodicSegmentGenerator, UuidV7Generator; never counted), or for long ids a StringIdGenerator, an IntIdGenerator (range checked) or its IdCodec; for the 80-bit CosId its PartsCodec; for a periodic segment its GroupedCodec.

      Whatever it returns belongs to the runtime (R1-core-18): never close it, even where its type is AutoCloseable; it closes with the runtime (close()), and closing it earlier would break every other user of the generator.

      Type Parameters:
      T - the wanted type
      Parameters:
      name - the generator name
      type - the wanted type
      Returns:
      the generator
      Throws:
      NoSuchElementException - if there is none of that type
      GeneratorDisabledException - if it is disabled

    • describe

      public Map<String,GeneratorInfo> describe()
      What each generator is: its layout, slot and window, its ready values and batch size, and the like.
      Returns:
      the generators by name, in name order; a disabled one tells disabled = true

    • slot

      public Optional<SlotLease> slot()
      The slot lease of the default machine.
      Returns:
      the lease, or empty without a leased default machine

    • slot

      public Optional<SlotLease> slot(String machine)
      The slot lease of a machine (D37).
      Parameters:
      machine - the machine name; "default" for the default one
      Returns:
      the lease, or empty when that machine is static or did not start (no enabled generator chose it)

    • machines

      public Set<String> machines()
      The machines that started: those an enabled time-based generator chose (D37).
      Returns:
      the machine names in name order, "default" included when it started

    • text

      public Supplier<String> text(String name)
      The text ids of the generator of that name, whatever its strategy (R1-int-01): the codec of its long ids, its parts codec (cosid80), its grouped codec (periodic segment) or the canonical UUID form (uuidv7, D46).
      Parameters:
      name - the generator name
      Returns:
      the text ids
      Throws:
      NoSuchElementException - if there is none
      GeneratorDisabledException - if it is disabled

    • filler

      public IdFiller filler()
      Fills CosId fields from this runtime's generators.
      Returns:
      the filler

    • close

      public void close()
      Closes in reverse dependency order: generators (terminal state, time-based ones first), the slot (released with the largest timestamp they issued), stores, the own executor. Closing again does nothing.
      Specified by:
      close in interface AutoCloseable
      Throws:
      CosIdException - if a step failed; every step still ran