Class MulticloudEnvironmentCatalog

java.lang.Object
com.eqixiac.equinix.design.optimizer.model.MulticloudEnvironmentCatalog
public final class MulticloudEnvironmentCatalog extends Object
An immutable catalog of native provider-to-provider multicloud environments: the pairs of cloud regions that two providers interconnect directly, with no Equinix resource on the path.

Beta: the offerings catalogued here reached general availability in 2026.

The bundled catalog goes stale

standard() loads /json/multicloud_environments_2026_09.json, a dated copy of the providers' public documentation. It is not refreshed at run time: this SDK calls no AWS, Google Cloud, Oracle or Azure API. Providers add region pairs and change launch stages without notice, so an absent pair means "not in this copy", not "not offered". Each entry carries the URL it was read from and the date it was read; asOf() is the catalog's own date. Supply newer data with with(MulticloudEnvironment...), of(Collection) or load(InputStream) and hand the result to DeploymentWizard.Builder.multicloudEnvironments(...) or MetroOptimizer.Builder.multicloudEnvironments(...).

Bundled entries (as of 2026-09-21)
PairEntriesStatusPrimary source
AWS and Google Cloud8 region pairsGA https://docs.aws.amazon.com/interconnect/latest/userguide/region-availability.html, confirmed against Google's paired-locations page
AWS and Oracle Cloudus-east-1 and us-ashburn-1GA the same AWS page, confirmed against https://docs.oracle.com/en-us/iaas/Content/multicloud/interconnect-aws.htm
AWS and Microsoft Azure4 region pairsPREVIEW the same AWS page, which labels the provider "Preview"

Lookup rules

find(CloudProviderType, String, CloudProviderType, String) and regionsFor(CloudProviderType, CloudProviderType) treat the two clouds as an unordered pair. Region names are compared after trimming, ignoring case. At most one entry exists per region pair: adding an entry for a pair already present replaces it.

File format

{ "asOf": "2026-09-21", "disclaimer": "...",
  "environments": [
    { "sites": [ {"provider": "aws", "site": "us-east-1", "displayName": "..."},
                 {"provider": "gcp", "site": "us-east4"} ],
      "status": "GA",
      "supportedConnectionSizeMbps": [1000, 10000],
      "sizesNote": "...", "sources": ["https://..."], "asOf": "2026-09-21", "note": "..." } ] }

provider is a specification-style provider id (aws, gcp, oci, azure). A missing or unrecognized status loads as UNVERIFIED. An entry without exactly two sites of different providers is rejected with an IllegalArgumentException naming its index.

  • Method Details

    • standard

      public static MulticloudEnvironmentCatalog standard()
      The bundled catalog, loaded from the classpath on first use and shared afterwards. A failed load is not retained: the next call reads the resource again.
      Returns:
      the bundled catalog
      Throws:
      IllegalStateException - if the bundled resource is missing from the classpath
      UncheckedIOException - if it cannot be read

    • empty

      public static MulticloudEnvironmentCatalog empty()
      Returns:
      a catalog with no entries; every lookup on it is empty

    • of

      public static MulticloudEnvironmentCatalog of(Collection<MulticloudEnvironment> environments)
      Creates a catalog from caller-supplied entries, with no catalog-level date or disclaimer.
      Parameters:
      environments - the entries; a later entry for a region pair replaces an earlier one
      Returns:
      the catalog
      Throws:
      NullPointerException - if the collection or an element is null

    • load

      public static MulticloudEnvironmentCatalog load(InputStream json)
      Reads a catalog in the file format given in the class documentation. The stream is read to its end and not closed.
      Parameters:
      json - a UTF-8 JSON document
      Returns:
      the catalog
      Throws:
      UncheckedIOException - if the stream cannot be read or is not JSON
      IllegalArgumentException - if an entry is malformed; the message names the entry index

    • with

      public MulticloudEnvironmentCatalog with(MulticloudEnvironment... additions)
      Returns a catalog holding this catalog's entries plus the given ones. This catalog is unchanged. An addition for a region pair already present replaces that entry in place; other additions are appended in argument order. The catalog-level asOf() and disclaimer() are carried over and describe the original entries only; each added entry carries its own date.
      Parameters:
      additions - the entries to add or replace
      Returns:
      the extended catalog
      Throws:
      NullPointerException - if the array or an element is null

    • find

      public Optional<MulticloudEnvironment> find(CloudProviderType a, String aRegion, CloudProviderType z, String zRegion)
      Finds the environment joining two cloud regions. The two endpoints may be given in either order: find(AWS, "us-east-1", GOOGLE_CLOUD, "us-east4") and find(GOOGLE_CLOUD, "us-east4", AWS, "us-east-1") return the same entry. Region names are compared after trimming, ignoring case.
      Parameters:
      a - one cloud
      aRegion - its region in its own notation
      z - the other cloud
      zRegion - its region in its own notation
      Returns:
      the entry, or empty when the catalog has none for the pair or any argument is null. Empty does not mean the providers offer no such link; see the class documentation

    • regionsFor

      public List<MulticloudEnvironment> regionsFor(CloudProviderType a, CloudProviderType z)
      The region pairs the catalog holds between two clouds, in catalog order. The two clouds may be given in either order.
      Parameters:
      a - one cloud
      z - the other cloud
      Returns:
      the entries joining a and z, unmodifiable; empty when there is none, when either argument is null, or when both are the same cloud

    • environments

      public List<MulticloudEnvironment> environments()
      Returns:
      every entry, in catalog order; unmodifiable

    • isEmpty

      public boolean isEmpty()
      Returns:
      true when the catalog has no entries

    • asOf

      public String asOf()
      The ISO-8601 date the catalog file as a whole was compiled (2026-09-21 for the bundled catalog).
      Returns:
      the date, or null for a catalog built with of(Collection) or empty()

    • disclaimer

      public String disclaimer()
      Returns:
      the catalog file's disclaimer, or null when it has none