Interface IRegionTree

public interface IRegionTree
The region tree as a whole: lookup, validation, and the resolution operations the push router depends on.

A single IRegionTree is configured per deployment. Its standard spine (continents, ISO 3166-1 countries, ISO 3166-2 subdivisions) is imported from the authoritative ISO/M49 data rather than hand-authored; only the custom proximity leaves and the residencyBoundary/serverBinding annotations are deployment-specific. Because a mis-mapped region silently mis-routes a compliance-sensitive send, the tree MUST be validated at load (see validate()), failing loudly rather than resolving wrong later.

Author:
IIZI

  • Method Summary

    Modifier and Type
    Method
    Description
    IRegionNode
    getNode(String code)
    Looks up a node by its code.
    IRegionNode
    getRoot()
    Gets the root of the tree (WORLD).
    IRegionNode
    resolveHomeRegion(String homeRegionCode)
    Resolves a user's home-region code to the node that a send should treat as that user's location.
    IRegionScope
    scopeOf(List<String> subtreeRootCodes)
    Expands a set of region codes naming subtree roots into the concrete predicate "is a given node within any of these subtrees", for use as a filter's region selector or an operator's authorization scope.
    IRegionNode
    selectServingNode(IRegionNode target)
    Selects the server-bound node that should physically serve a target node, by bounded fallback.
    void
    validate()
    Validates the loaded tree, failing loudly on any inconsistency.

  • Method Details

    • getRoot

      IRegionNode getRoot()
      Gets the root of the tree (WORLD).
      Returns:
      The root node; never null.

    • getNode

      IRegionNode getNode(String code)
      Looks up a node by its code.
      Parameters:
      code - The region code (ISO, M49, or a custom leaf name).
      Returns:
      The node, or null if no node has that code.

    • resolveHomeRegion

      IRegionNode resolveHomeRegion(String homeRegionCode)
      Resolves a user's home-region code to the node that a send should treat as that user's location.

      A user's stored home_region is normally the coarsest node that satisfies compliance (a country, or a subdivision where a rule is finer). This returns the corresponding node, from which the router derives the residency ceiling and the region slice.

      Parameters:
      homeRegionCode - The user's stored home-region code, possibly null or unrecognized.
      Returns:
      The resolved node, or null if the code is unknown — which the router treats as an unresolved region, subject to the send's ResidencyPolicy.

    • selectServingNode

      IRegionNode selectServingNode(IRegionNode target)
      Selects the server-bound node that should physically serve a target node, by bounded fallback.

      If the target has a server binding, it is returned. Otherwise the tree walks upward to the nearest server-bound ancestor, but never past the target's residency ceiling. If no server-bound node exists at or below the ceiling, the result is null, which the router reports as region-unreachable — it does not fall past the ceiling to find a server, because that would be a residency violation.

      Parameters:
      target - The node to be served.
      Returns:
      The server-bound node that should serve target within its residency ceiling, or null if none exists.

    • scopeOf

      IRegionScope scopeOf(List<String> subtreeRootCodes)
      Expands a set of region codes naming subtree roots into the concrete predicate "is a given node within any of these subtrees", for use as a filter's region selector or an operator's authorization scope.
      Parameters:
      subtreeRootCodes - The codes naming the subtree roots.
      Returns:
      A scope object testing subtree membership; never null.

    • validate

      void validate() throws RegionTreeException
      Validates the loaded tree, failing loudly on any inconsistency.

      Checks that every node's parent link is consistent, that every ISO code is a real code, that the continent mapping round-trips, and that no residency boundary is mis-placed. This exists because the tree's standard spine is assembled from data: a wrong continent mapping or a missing country would otherwise become a silent mis-route of a compliance-sensitive send, caught by nobody. Validation MUST run at configuration load, not at send time.

      Throws:
      RegionTreeException - if the tree is inconsistent; the exception names the offending node and the specific inconsistency.