Sessions and configuration

One Equinix session for several domains, EquinixConfig options, and the metro registry.

One session across domains#

new Fabric(credentials) and new NetworkEdge(credentials) each create their own OAuth token and connection pool. A program that uses more than one domain opens an Equinix session, which owns one token and one pool and hands out domain clients that share them.

Java

import com.eqixiac.equinix.CustomerPortal;
import com.eqixiac.equinix.Design;
import com.eqixiac.equinix.Equinix;
import com.eqixiac.equinix.Fabric;
import com.eqixiac.equinix.NetworkEdge;

try (Equinix eq = new Equinix(credentials)) {
    Fabric fabric = eq.fabric();
    NetworkEdge networkEdge = eq.networkEdge();
    CustomerPortal portal = eq.customerPortal();
    Design design = eq.design();           // design engines over the session's Fabric client
}                                          // one close() releases the pool

The session exposes fabric(), networkEdge(), customerPortal(), ibxSmartView(), internetAccess(), projects(), iam(), sts() and design(), and creates each domain client on first use. The connection pool allows 50 connections in total and 20 per route. A program that needs one domain can still construct that client directly.

Configuration#

EquinixConfig holds the options that are fixed when a client is constructed, and Equinix and every domain client accept it.

Java

import com.eqixiac.equinix.EquinixConfig;
import com.eqixiac.equinix.core.http.CircuitBreaker;
import com.eqixiac.equinix.core.http.RetryPolicy;

EquinixConfig config = EquinixConfig.builder()
    .sandbox(false)
    .autoLoadMetros(false)                              // load the metro catalog lazily
    .enrichMetroRegistry(true)                          // merge per-IBX data from Internet Access
    .retryPolicy(RetryPolicy.defaultPolicy())
    .circuitBreaker(new CircuitBreaker(5, 30_000))      // open after 5 consecutive failures, for 30 s
    .peeringDbApiKey(System.getenv("PEERINGDB_API_KEY"))
    .build();

Equinix eq = new Equinix(credentials, config);

Option	Default	Effect
`sandbox`	`false`	Targets the sandbox environment
`autoLoadMetros`	`true`	Loads the metro catalog on an explicit `authenticate()`; otherwise it loads on the first `metroRegistry()` call
`enrichMetroRegistry`	`false`	Adds the Internet Access per-IBX catalogue to the metro registry
`retryPolicy`	`RetryPolicy.defaultPolicy()`	See Retries
`circuitBreaker`	none	See Circuit breaker
`peeringDbApiKey`	none	Credential for Peering Intelligence

EquinixConfig has no timeout options. The HTTP client uses 10 s to connect, 60 s for a socket read and 5 s to lease a pooled connection.

Metros#

MetroCode is an enum of well-known metros. A metro outside the enum is handled as follows.

A metro that the enum does not list deserializes to MetroCode.UNKNOWN, and the model keeps the code the service sent in metro.metroId().
MetroId is a normalized code string that can name any metro, so MetroId.of("ZZ") is valid for a metro that the enum does not list.
Builders that take a metro have a String overload next to the MetroCode one.

Metro registry#

metroRegistry() returns a cached snapshot of every metro from the Fabric Metros API, keyed by MetroId.

Java

import com.eqixiac.equinix.core.enums.MetroCode;
import com.eqixiac.equinix.design.geo.SpeedOfLightLatency;
import com.eqixiac.equinix.fabric.model.MetroRegistry;
import com.eqixiac.equinix.internetaccess.model.Ibx;

MetroRegistry registry = eq.metroRegistry();
registry.get("SV").ifPresent(m -> System.out.println(m.getName()));
boolean known = registry.contains("ZZ");

// With enrichMetroRegistry(true): per-IBX records, including coordinates.
Ibx sv5 = registry.ibx("SV5").orElseThrow();
Ibx la4 = registry.ibx("LA4").orElseThrow();
double roundTripFloorMs = SpeedOfLightLatency.roundTrip().millisBetween(sv5, la4);
List<Ibx> siliconValley = registry.ibxDetails("SV");

registry.refresh();    // re-reads both sources and swaps the snapshot in place

Fabric supplies the metro-level data: centroid, connected-metro latency, country and the Equinix ASN. Internet Access is the only Equinix API with per-IBX coordinates. The enrichment fetch is best-effort, so an Internet Access failure does not fail the registry load, and isEnriched() reports whether it succeeded.