Package top.wcpe.beacon.agent.api

Class NodeDeclaration

java.lang.Object
top.wcpe.beacon.agent.api.NodeDeclaration
public final class NodeDeclaration extends Object
节点自声明（FR-243，见 ADR-0086）：业务插件为本节点声明「容量」与「自定义键值标签」。

部分刷新：两类字段各自可选——缺省即不刷新该字段（不是刷成空）。其中 capacity() 用 Optional 与「容量 0」区分；labels() 用 hasLabels() 与「提交空标签集（= 清空全部标签）」区分。

不解释语义：Beacon 只承载「节点声明了哪些 key=value」，不定义任何 key 的业务含义， 由接入方在自己的命名空间下自行解释（ADR-0086 §5）。

有界：标签沿用 FR-227 既有约束（key ≤ 32 / value ≤ 128 / 单节点 ≤ 20 个标签）， 超界由控制面按「声明被拒」处置（门面取值 REJECTED）。

值对象不可变：标签在构造时防御性拷贝并包装为不可修改视图，构造后外部改动不影响本对象。

  • Method Details

    • ofCapacity

      public static NodeDeclaration ofCapacity(int capacity)
      只刷新容量（如 NodeDeclaration.ofCapacity(100)）。
      Parameters:
      capacity - 新容量；0 是合法值，语义为「容量为 0」，与「不刷新」不同

    • ofLabels

      public static NodeDeclaration ofLabels(Map<String,String> labels)
      只刷新标签（提供即整体替换，不合并）。
      Parameters:
      labels - 新的完整标签集；空 Map 表示清空该节点全部标签

    • of

      public static NodeDeclaration of(int capacity, Map<String,String> labels)
      同时刷新容量与标签。
      Parameters:
      capacity - 新容量（0 合法）
      labels - 新的完整标签集（空 Map 表示清空全部标签）

    • capacity

      public Optional<Integer> capacity()
      本次声明的容量。
      Returns:
      空 = 本次不刷新容量（区别于 Optional.of(0)）

    • hasLabels

      public boolean hasLabels()
      本次声明是否携带标签。
      Returns:
      true = 标签随本次声明下发（整体替换，空 labels() 即清空）；false = 不刷新标签

    • labels

      public Map<String,String> labels()
      本次声明的标签整体集合。

      hasLabels() 为 false 时返回空 Map（此时其含义是「不刷新」而非「清空」， 判定一律以 hasLabels() 为准）。返回值为不可修改视图，绝不外抛可变引用。