Class MetroRegistry

java.lang.Object
com.eqixiac.equinix.fabric.model.MetroRegistry
public final class MetroRegistry extends Object
An in-memory snapshot of every metro the Metros API returns, keyed by MetroId so lookups work for metros the MetroCode enum does not list. This is the authoritative, always-current set of metros (and their IBX data centers) - built by loading fabric.metros().list() once and caching the result - for code that needs to discover or validate metros rather than hard-code the enum.

Cross-source enrichment. Fabric's metros carry the metro-level picture (centroid coordinates, connected-metro latency, IBX codes) but no per-IBX detail; that lives in EIA's /internetAccess/v2/ibxs (per-IBX coordinates, country, metro association). When built with EquinixConfig.enrichMetroRegistry (or via load(Metros, Collection)), the registry merges both so it is the SDK's most complete location directory: ibx(String) returns the full EIA Ibx - ready for design.geo.SpeedOfLightLatency IBX-to-IBX math. The registry is deliberately cross-domain in that mode (fabric + internetaccess data, one lookup surface).

Each snapshot is immutable and swapped atomically: refresh() re-reads the same sources the registry was loaded from (the Metros API, plus the per-IBX source when enriched) and publishes a new snapshot in place, so every existing reference to the registry sees the fresh catalogue. Fabric.reloadMetroRegistry() delegates to it.

MetroRegistry registry = fabric.metroRegistry();
registry.get("SV").ifPresent(m -> System.out.println(m.getName() + " " + m.getIbxs()));
boolean exists = registry.contains(newMetroCode);   // works even if not in the MetroCode enum
registry.refresh();                                  // re-pull metros (+ IBX detail) at runtime

// With EquinixConfig.enrichMetroRegistry(true):
Ibx sv5 = registry.ibx("SV5").orElseThrow();
double ms = SpeedOfLightLatency.roundTrip().millisBetween(sv5, registry.ibx("LA4").orElseThrow());
Author:
ianjones

  • Method Details

    • load

      public static MetroRegistry load(Metros metros)
      Loads the registry by fetching every metro from the Metros API. Metros are keyed by their MetroId (the exact wire code), so distinct unlisted metros do not collide.
      Parameters:
      metros - the Metros client to read from (e.g. fabric.metros())
      Returns:
      a populated registry

    • load

      public static MetroRegistry load(Metros metros, Collection<? extends Ibx> ibxDetails)
      Loads the registry and enriches it with a fixed set of per-IBX records. refresh() re-reads the Metros API but re-applies these same records; prefer load(Metros, Supplier) when the per-IBX source should also be re-queried at refresh time.
      Parameters:
      metros - the Metros client to read from (e.g. fabric.metros())
      ibxDetails - per-IBX records to merge in (empty for an un-enriched registry)
      Returns:
      a populated registry

    • load

      public static MetroRegistry load(Metros metros, Supplier<Collection<? extends Ibx>> ibxSource)
      Loads the registry with a re-invocable per-IBX source (typically the EIA ibx catalogue - see the class notes on cross-source enrichment). The source is queried once now and again on every refresh(). IBXes are keyed case-insensitively by ibxCode; duplicates keep the first occurrence.
      Parameters:
      metros - the Metros client to read from (e.g. fabric.metros())
      ibxSource - supplies per-IBX records to merge in (empty collection for un-enriched)
      Returns:
      a populated registry

    • refresh

      public MetroRegistry refresh()
      Re-reads this registry's sources - the Metros API, and the per-IBX source when it was loaded with one - and atomically replaces the cached snapshot, so the registry reflects the live catalogue (new metros, new IBXes, coordinate updates) without rebuilding references to it. Thread-safe: readers see either the old snapshot or the new one, never a mix.
      Returns:
      this registry, refreshed

    • get

      public Optional<Metro> get(MetroId metroId)
      Parameters:
      metroId - the metro to look up
      Returns:
      the metro, or empty if not present (or metroId is null)

    • get

      public Optional<Metro> get(String code)
      Parameters:
      code - the raw metro code (e.g. "SV"); case-insensitive
      Returns:
      the metro, or empty if not present (or code is null/blank)

    • get

      public Optional<Metro> get(MetroCode code)
      Parameters:
      code - a well-known metro code
      Returns:
      the metro, or empty if not present (or code is null)

    • contains

      public boolean contains(String code)
      Parameters:
      code - the raw metro code; case-insensitive
      Returns:
      true if this registry contains a metro with that code

    • contains

      public boolean contains(MetroCode code)
      Parameters:
      code - a well-known metro code
      Returns:
      true if this registry contains that metro

    • all

      public Collection<Metro> all()
      Returns:
      all metros in the registry (unmodifiable)

    • metroIds

      public Set<MetroId> metroIds()
      Returns:
      the ids of every metro in the registry (unmodifiable)

    • ibxs

      public List<String> ibxs(String code)
      Parameters:
      code - the raw metro code; case-insensitive
      Returns:
      the IBX data-center codes within the metro, or an empty list if the metro is unknown or reports none

    • size

      public int size()
      Returns:
      the number of metros in the registry

    • ibx

      public Optional<Ibx> ibx(String ibxCode)
      Looks up per-IBX detail (coordinates, country, metro association) merged in at load time. Populated only when the registry was built with enrichment - see EquinixConfig.enrichMetroRegistry and the class notes.
      Parameters:
      ibxCode - the IBX data-center code (e.g. "SV5"); case-insensitive
      Returns:
      the IBX record, or empty if unknown or the registry is not enriched

    • ibxDetails

      public List<Ibx> ibxDetails(String metroCode)
      Returns the enriched per-IBX records associated with a metro (matched on the record's own metroCode). Empty when the registry is not enriched or the metro has no records - ibxs(String) still lists the metro's IBX codes from Fabric either way.
      Parameters:
      metroCode - the metro code (e.g. "SV"); case-insensitive
      Returns:
      the IBX records within that metro (unmodifiable)

    • isEnriched

      public boolean isEnriched()
      Returns:
      true if this registry carries merged per-IBX detail (built with EquinixConfig.enrichMetroRegistry and the EIA fetch succeeded)