Class TcoCalculator.Builder

java.lang.Object
com.eqixiac.equinix.design.value.tco.TcoCalculator.Builder
Enclosing class:
TcoCalculator
public static final class TcoCalculator.Builder extends Object
Fluent configuration for a TCO comparison, terminated by compare(). Setters validate eagerly (fail-fast IllegalArgumentExceptions), so a mistake surfaces at the call site rather than as a wrong number later.

Defaults: 1000 Mbps bandwidth, EVPL_VC connection type, Term.MONTH_12, egress volume 0 GB, the three single-cloud archetypes (once a peer cloud is set: PUBLIC_CLOUD_INTERNET, EQUINIX_INTERCONNECT and NATIVE_MULTICLOUD_INTERCONNECT, without ON_PREM), no Cloud Router, 1 cabinet, 1 cross-connect, 5.0 kW power draw, on-prem inputs from the bundled reference midpoints, and the standard layered rate-card chain (live Equinix pricing, then bundled reference figures). Cloud-to-cloud defaults: no peer cloud, path tier 1, AWS free tier not applied, reverse volume equal to the forward volume.

Constraints that span two levers are checked at compare(), because levers may be set in any order: the native archetype, toRegion, pathTier, reverseEgress and useAwsFreeTier(true) each require toCloud; toCloud requires fromCloud and must differ from it; useAwsFreeTier(true) requires AWS as one of the two clouds. Each violation is an IllegalArgumentException naming the lever.

Currency contract for the onPrem* overrides: caller-supplied values are taken to be in the comparison currency (the currency the egress rates resolved to). The bundled midpoints are published in the reference data's own currency (USD), so when the comparison currency is known to differ, an on-prem archetype still relying on any midpoint is reported unpriced (with the reason) rather than relabelled - supply all four overrides in the comparison currency to price it.

  • Method Details

    • egress

      public TcoCalculator.Builder egress(double amount, DataUnit unit)
      Sets the monthly cloud data-egress volume the comparison is built around (default 0).
      Parameters:
      amount - the volume in units per month
      unit - the unit the amount is expressed in (decimal/SI conversions)
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the amount is negative or not finite, or the unit is null

    • egressTerabytes

      public TcoCalculator.Builder egressTerabytes(double terabytes)
      Shorthand for egress(terabytes, DataUnit.TERABYTE) (1 TB = 1000 GB).

    • fromCloud

      public TcoCalculator.Builder fromCloud(CloudProviderType provider)
      Sets the cloud provider the egress leaves - the provider whose internet and private egress rates are looked up.
      Parameters:
      provider - the cloud provider
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the provider is null, or equals a toCloud(...) already set

    • inRegion

      public TcoCalculator.Builder inRegion(String region)
      Sets the provider region the egress originates in, in the provider's own region notation (e.g. "us-east-1", "westeurope"). Optional: region-agnostic rate cards ignore it, but the provider-API adapters need it.
      Parameters:
      region - the provider region identifier (may be null for provider-wide rates)
      Returns:
      this builder for method chaining

    • toCloud

      public TcoCalculator.Builder toCloud(CloudProviderType provider)
      Declares the peer cloud and makes the comparison cloud-to-cloud (see the TcoCalculator class documentation): the internet, Equinix and native archetypes are priced two-sided, NATIVE_MULTICLOUD_INTERCONNECT joins the default archetype set and ON_PREM leaves it (it carries no cloud egress and is reported unpriced when requested explicitly). Beta.
      Parameters:
      provider - the cloud at the other end; must differ from fromCloud(...)
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the provider is null, or equals a fromCloud(...) already set (the same check runs again at compare())

    • toRegion

      public TcoCalculator.Builder toRegion(String region)
      Sets the peer cloud's region in its own notation (e.g. "us-east4"). Optional. The bundled reference data uses it to select Google's transport location; with no region it prices a Google Cloud side at the North America location and says so in the figure's provenance.
      Parameters:
      region - the peer region identifier (may be null)
      Returns:
      this builder for method chaining

    • pathTier

      public TcoCalculator.Builder pathTier(int pathTier)
      Sets the AWS connectivity-scope tier of the native link: 1 local (default), 2 regional, 3 continental, 4 long-haul, 5 maximum scope. AWS assigns the tier from the Region paths the interconnect serves and publishes no path-to-tier table, so it is an input, never derived. Providers without a tier concept ignore it.
      Parameters:
      pathTier - the tier, 1-5
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if outside 1-5

    • useAwsFreeTier

      public TcoCalculator.Builder useAwsFreeTier(boolean useAwsFreeTier)
      Opts in to the AWS free tier for the native link: one free tier-1 500 Mbps interconnect per AWS Region per generally-available provider. Off by default and never inferred, because the SDK cannot know whether the account already uses its free interconnect for the Region and provider. When set and the request is eligible (bandwidth at or below 500 Mbps, tier 1, eligible peer) the AWS side is priced at zero; when set but ineligible, the listed rate applies and the provenance says why.
      Parameters:
      useAwsFreeTier - true to apply the free tier where eligible
      Returns:
      this builder for method chaining

    • reverseEgress

      public TcoCalculator.Builder reverseEgress(double amount, DataUnit unit)
      Sets the monthly volume flowing from the peer cloud back to fromCloud - the traffic the peer cloud bills as egress. When not set, a cloud-to-cloud comparison assumes it equals the forward volume set with egress(double, DataUnit) and states that assumption in TcoComparison.getTrafficNote().
      Parameters:
      amount - the volume in units per month
      unit - the unit the amount is expressed in (decimal/SI conversions)
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the amount is negative or not finite, or the unit is null

    • viaMetro

      public TcoCalculator.Builder viaMetro(MetroCode metro)
      Sets the Equinix metro the interconnect lands in, used for metro-sensitive rate lookups. Omit the call entirely for a metro-agnostic comparison.
      Parameters:
      metro - the Equinix metro
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the metro is null (omit the call instead)

    • bandwidthMbps

      public TcoCalculator.Builder bandwidthMbps(int bandwidthMbps)
      Sets the interconnect bandwidth in Mbps (default 1000). Drives the Fabric connection price, the CSP interconnect-port fee, and the on-prem carrier-transit line.
      Parameters:
      bandwidthMbps - the bandwidth in Mbps
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if not positive

    • connectionType

      public TcoCalculator.Builder connectionType(ConnectionType connectionType)
      Sets the Fabric connection type priced for the Equinix archetype (default EVPL_VC).
      Parameters:
      connectionType - the connection type
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if null

    • includeCloudRouter

      public TcoCalculator.Builder includeCloudRouter(String packageCode)
      Adds a Fabric Cloud Router of the given package to the Equinix archetype (none is included by default). If the rate card cannot price the package, the archetype is reported as not fully priced with a note naming the missing router - its partial figures stay visible but it is excluded from the recommendation rather than silently under-priced.
      Parameters:
      packageCode - the router package code (e.g. "STANDARD")
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the package code is null or blank

    • term

      public TcoCalculator.Builder term(Term term)
      Sets the commitment term (default Term.MONTH_12). It feeds the term-aware rate lookups and defines the horizon archetypes are ranked over (MRC × months + setup).
      Parameters:
      term - the commitment term
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if null

    • currency

      public TcoCalculator.Builder currency(String currency)
      Sets the currency every figure is compared in (default USD). Figures quoted in another currency are converted: rates pinned with exchangeRates, then currencyConverter, then live ECB reference rates (one call), then the SDK's bundled table. Only a currency no source covers is unpriced.
      Parameters:
      currency - ISO 4217 code
      Returns:
      this builder for method chaining

    • exchangeRates

      public TcoCalculator.Builder exchangeRates(CommercialTerms.ExchangeRates rates)
      Pins exchange rates to currency(String); they take precedence over every other source.
      Parameters:
      rates - the rates, or null for none
      Returns:
      this builder for method chaining

    • currencyConverter

      public TcoCalculator.Builder currencyConverter(CurrencyConverter converter)
      Supplies a converter (for example a live FX feed) ranked below pinned rates and above the defaults.
      Parameters:
      converter - the converter, or null for none
      Returns:
      this builder for method chaining

    • defaultRates

      public TcoCalculator.Builder defaultRates(CurrencyConverter defaults)
      Replaces the default rate sources (live ECB rates, then the bundled table), for example with CurrencyConverters.bundledOnly() for an offline run.
      Parameters:
      defaults - the fallback converter, or null for the defaults
      Returns:
      this builder for method chaining

    • rateCard

      public TcoCalculator.Builder rateCard(RateCard rateCard)
      Sets the rate card that prices every component of the comparison. When omitted, the standard layered chain (RateCard.standardChain(fabric)) applies: live Equinix Fabric pricing first, then the bundled ReferenceRateCard, which also supplies indicative cloud-egress rates. A supplied card replaces that chain entirely; layer it yourself (e.g. RateCard.layered(custom, RateCard.standardChain(fabric))) to keep the defaults as a fallback.
      Parameters:
      rateCard - the rate card to price with, or null to use the standard chain
      Returns:
      this builder for method chaining

    • archetypes

      public TcoCalculator.Builder archetypes(DeploymentArchetype... archetypes)
      Restricts the comparison to the given archetypes. The default is PUBLIC_CLOUD_INTERNET, ON_PREM and EQUINIX_INTERCONNECT; when a peer cloud is set with toCloud(...) it is PUBLIC_CLOUD_INTERNET, EQUINIX_INTERCONNECT and NATIVE_MULTICLOUD_INTERCONNECT. Requesting the native archetype without a peer cloud fails at compare(). Requesting ON_PREM with a peer cloud is accepted; the breakdown is reported unpriced with the reason and is never recommended.
      Parameters:
      archetypes - the archetypes to compare
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the array is null, empty, or contains null

    • cabinets

      public TcoCalculator.Builder cabinets(int cabinets)
      Sets the number of colocation cabinets for the Equinix-interconnect archetype (default 1). The per-cabinet ColocationItem.CABINET quote - when the rate card prices one - is multiplied by this count.

    • crossConnects

      public TcoCalculator.Builder crossConnects(int crossConnects)
      Sets the number of Equinix cross-connects for the Equinix-interconnect archetype (default 1). The per-unit ColocationItem.CROSS_CONNECT quote (or the reference cross-connect figure when no colocation rate is supplied) is multiplied by this count; zero omits cross-connects entirely.

    • powerKw

      public TcoCalculator.Builder powerKw(double powerKw)
      Sets the power draw in kW (default 5.0). Note the dual use: it scales both the on-prem power/space line (per-kW midpoint × kW) and the Equinix archetype's colocation power line when the rate card prices ColocationItem.POWER_PER_KW - tuning it for one side changes the other.
      Parameters:
      powerKw - the power draw in kW
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if negative or not finite

    • onPremTransitPerMbpsMonth

      public TcoCalculator.Builder onPremTransitPerMbpsMonth(BigDecimal value)
      Overrides the on-prem carrier-transit rate per Mbps per month, in the comparison currency.

    • onPremHardwareMonthly

      public TcoCalculator.Builder onPremHardwareMonthly(BigDecimal value)
      Overrides the amortized on-prem hardware monthly cost, in the comparison currency.

    • onPremCrossConnectMonthly

      public TcoCalculator.Builder onPremCrossConnectMonthly(BigDecimal value)
      Overrides the on-prem cross-connect monthly cost, in the comparison currency.

    • onPremPowerPerKwMonth

      public TcoCalculator.Builder onPremPowerPerKwMonth(BigDecimal value)
      Overrides the on-prem power/space rate per kW per month, in the comparison currency.

    • additionalLineItem

      public TcoCalculator.Builder additionalLineItem(String label, BigDecimal monthly)
      Adds an arbitrary named monthly cost - e.g. compute, storage, or software the rate cards do not price - folded into every priced archetype's breakdown and total. Because it is applied uniformly, it makes the absolute TCO figures realistic without changing which archetype is cheapest (the savings comparison is unaffected). Call multiple times for multiple line items.
      Parameters:
      label - the line-item label shown in each breakdown
      monthly - the monthly amount (in the comparison currency)
      Returns:
      this builder for method chaining

    • compare

      public TcoComparison compare()
      Runs the comparison.
      Returns:
      the TCO comparison across the requested archetypes
      Throws:
      IllegalArgumentException - if levers conflict: the native archetype, toRegion, pathTier, reverseEgress or useAwsFreeTier(true) without toCloud; toCloud without, or equal to, fromCloud; or useAwsFreeTier(true) when neither cloud is AWS