Interface IRegionNode

public interface IRegionNode
A node in the universal region tree.

Regions form a tree, not a flat set. The spine is standard and authoritative: continent tops (UN M49), then country nodes (ISO 3166-1, e.g. SE, IN), then subdivision nodes (ISO 3166-2, e.g. SE-AB, IN-KA). Below the ISO subdivision the leaves are custom proximity nodes that describe where iiziServers physically sit (e.g. STOCKHOLM_NORTH, BANGALORE); no standard governs those, because they are infrastructure, not jurisdiction.

The tree supports two traversals, each answering a different question:

  • Up — fallback. Given a target node with no operational server, walk toward the root to the nearest ancestor that has one. This is bounded: the walk MUST NOT cross a residency boundary upward, because doing so would serve a user's data from outside their legal jurisdiction. If no server exists at or below the residency boundary, the send fails as region-unreachable; it does not fall past the ceiling.
  • Down — scope. Naming an interior node in a filter targets that node and all its descendants. Naming IN targets all of India; naming a leaf targets just that leaf.
Author:
IIZI

  • Method Summary

    Modifier and Type
    Method
    Description
    List<IRegionNode>
    getChildren()
    Gets the immediate children of this node, empty if it is a leaf.
    String
    getCode()
    Gets the stable identifier of this region node.
    IRegionNode
    getParent()
    Gets the parent of this node, or null if this is the root (WORLD).
    boolean
    hasServerBinding()
    Reports whether an operational iiziServer is bound at this node.
    boolean
    isResidencyBoundary()
    Reports whether fallback may cross this node upward.
    boolean
    isWithin(IRegionNode ancestor)
    Reports whether this node is contained in the subtree rooted at ancestor — that is, whether ancestor equals this node or is a transitive parent of it.
    IRegionNode
    residencyCeiling()
    Computes the residency ceiling for this node: the nearest ancestor (or this node itself) that is a residency boundary.

  • Method Details

    • getCode

      String getCode()
      Gets the stable identifier of this region node.

      For standard nodes this is the ISO or M49 code (SE, SE-AB, a continent code); for custom proximity leaves it is the deployment-defined name. The code is the node's wire and configuration identity and MUST be unique across the tree.

      Returns:
      The region code; never null.

    • getParent

      IRegionNode getParent()
      Gets the parent of this node, or null if this is the root (WORLD).
      Returns:
      The parent node, or null at the root.

    • getChildren

      List<IRegionNode> getChildren()
      Gets the immediate children of this node, empty if it is a leaf.
      Returns:
      An unmodifiable list of child nodes; never null.

    • isResidencyBoundary

      boolean isResidencyBoundary()
      Reports whether fallback may cross this node upward.

      A residency boundary is the ceiling of a jurisdiction — almost always an ISO country node such as IN or SE. Fallback (the up-walk from a serverless node toward one with a server) is permitted within the boundary (Bangalore may fall back to Mumbai to India-generic) but MUST NOT cross it (India MUST NOT fall back to APAC, which would place India data on a server outside India). Exactly one boundary node lies on the path from any leaf to the root under a jurisdiction; it is that node's residency ceiling.

      Returns:
      true if this node is a residency boundary that fallback may not cross upward.

    • hasServerBinding

      boolean hasServerBinding()
      Reports whether an operational iiziServer is bound at this node.

      Only nodes with a server binding can perform a send directly; a target node without one is resolved by bounded fallback to the nearest server-bound ancestor within its residency ceiling.

      Returns:
      true if a server serves this node.

    • residencyCeiling

      IRegionNode residencyCeiling()
      Computes the residency ceiling for this node: the nearest ancestor (or this node itself) that is a residency boundary.

      This is the jurisdiction within which this node's data must remain and within which fallback may move freely. For a Bangalore node the ceiling is IN. If no ancestor is a boundary (a jurisdiction-free branch), the ceiling is the root and residency is effectively unconstrained.

      Returns:
      The residency ceiling node; never null.

    • isWithin

      boolean isWithin(IRegionNode ancestor)
      Reports whether this node is contained in the subtree rooted at ancestor — that is, whether ancestor equals this node or is a transitive parent of it.

      This is the primitive behind both the region-selector test ("is this target in the filter's target subtree?") and the authorization test ("is this target under a subtree the operator is authorized for?"). Both an inclusion filter and an authorization scope are expressed as sets of subtree roots, and membership is this test against each.

      Parameters:
      ancestor - The candidate ancestor subtree root.
      Returns:
      true if this node is within ancestor's subtree.