API 参考

jp4 v1.5 完整公开接口,按类别组织。每个条目链接到该类的标准 Javadoc HTML 页面。Javadoc 本身位于 /api/javadoc/,由 javadoc 工具从源码生成 —— 是每个方法签名、返回类型、异常列表、@since 标记的权威来源。

说明: 详细 API 文档采用标准 Javadoc 格式 (英文)。本页面提供分类导航和每个类的中文简介,便于按需查阅。

任务导向指引请见 Cookbook 与 指南。跨主题深入背景请见 深入概念。

客户端生命周期

类	作用
P4Switch	客户端到单个 P4Runtime 设备的连接。每个 jp4 程序的主入口类。
Connector	流式连接构建器:地址、deviceId、electionId、reconnectPolicy、主控或从属角色。
ReconnectPolicy	自动重连配置 —— noRetry()(默认)或 exponentialBackoff(initial, max, retries)。
ElectionId	P4Runtime 无符号 128 位 election id (low + high 对)。of(long) 是只填 low 的快捷形式。
MastershipStatus	sealed 父类,投递给 onMastershipChange 监听器的 Acquired / Lost 事件。
MastershipStatus.Acquired	"本客户端成为主控" record;携带 ourElectionId。
MastershipStatus.Lost	"本客户端不是主控" record;携带 previousElectionId(可空)和 currentPrimaryElectionId(可空)。

流水线

类	作用
Pipeline	已绑定的流水线视图,暴露解析后的 P4Info 加设备配置描述符。
P4Info	对 p4.config.v1.P4Info 的 schema 包装 —— table、action、字段、实体、controller-metadata 的名称索引。
DeviceConfig	sealed 父类,涵盖两个设备配置变体。
DeviceConfig.Bmv2	BMv2 风味 JSON 设备配置;fromFile(Path) 和 fromBytes(byte[]) 工厂方法。
DeviceConfig.Raw	面向非 BMv2 目标的"只字节"逃生口。
PipelineAction	SetForwardingPipelineConfig 的动词选择器(默认 VERIFY_AND_COMMIT)。

Schema 访问器(P4Info 子类型)

类	作用
TableInfo	解析后的表元数据:id、匹配字段、动作集合、size。
MatchFieldInfo	匹配字段元数据:名称、kind、位宽。
MatchFieldInfo.Kind	枚举:EXACT / LPM / TERNARY / RANGE / OPTIONAL。
ActionInfo	解析后的动作元数据:id、参数列表。
ActionParamInfo	动作参数元数据:名称、位宽。
CounterInfo / Unit	counter 声明及单位(BYTES / PACKETS / BOTH / UNSPECIFIED)。
MeterInfo / Unit	meter 声明及单位(BYTES / PACKETS / UNSPECIFIED)。
RegisterInfo	register 声明:id、名称、size。
ActionProfileInfo	action profile 声明,带引用该 profile 的表 id 集合。
PacketMetadataInfo	controller_packet_metadata 字段声明。

匹配类型

类	作用
Match	sealed 父类;静态 lpm(cidr) 和 exact(value) 快捷工厂。
Match.Exact	精确匹配键(value)。
Match.Lpm	最长前缀匹配键(value、prefixLen)。
Match.Ternary	ternary 键(value、mask)。
Match.Range	range 键(low、high)。
Match.Optional	optional 键(value;null 安全通配)。

实体记录

每种 P4Runtime 实体类型的有类型数据 record。

类	作用
TableEntry	表条目 record;in(name) 构建器入口。
TableEntryBuilder	TableEntry 流式构建器 —— match、action、priority、idleTimeoutNs。
ActionInstance	带参数 map 的具名动作;从 TableEntry.action()、ActionProfileMember.action() 可达。
ActionBuilder	.action(name).param(name, value) 链的流式构建器。
CounterEntry	一个 counter cell —— 名称、index、packetCount、byteCount。
CounterData	逐色的 packet/byte counter(被 MeterCounterData 使用)。
MeterEntry	一个 meter cell —— 名称、index、config、逐色计数数据。
MeterConfig	meter 速率配置 —— cir、cburst、pir、pburst、eburst。
MeterCounterData	三色累积计数(green、yellow、red)。
RegisterEntry	一个 register cell —— 名称、index、序列化后的 P4Data 字节。
ActionProfileMember	action profile 成员 —— profile 名、member id、action。
ActionProfileGroup	action profile 组 —— profile 名、group id、最大 size、加权成员。
WeightedMember	组成员 —— id、weight、可空 watch port。
MulticastGroupEntry	组播组 —— id、replicas、metadata。
CloneSessionEntry	克隆会话 —— id、replicas、classOfService、packetLengthBytes。
Replica	每端口扇出 slot —— 可空 port、instance、backup replica 列表。
BackupReplica	备份 replica —— 非空 port、instance。

读查询

每个实体读族的有类型查询构建器。7 个共享同一形状:服务端过滤、where(Predicate) 客户端过滤、5 个终端方法(all / one / stream / allAsync / oneAsync)。

类	服务端过滤
ReadQuery	表读:match(field, MatchKind)
CounterReadQuery	index(long)
MeterReadQuery	index(long)
RegisterReadQuery	index(long)
ActionProfileMemberReadQuery	memberId(long)
ActionProfileGroupReadQuery	groupId(long)
MulticastGroupReadQuery	groupId(long)
CloneSessionReadQuery	sessionId(long)

流消息

投递给 onPacketIn / onDigest / onIdleTimeout / onPacketDropped 监听器的记录,以及外出的 PacketOut 构建器。

类	作用
PacketIn	入站报文 —— payload、controller-metadata 字段访问器(metadata(name)、metadataInt(name)、metadataLong(name))。
PacketOut	外出报文 record。
PacketOut.Builder	流式构建器 —— payload(...)、metadata(name, value)。
DigestEvent	入站 DigestList —— 名称、list id、逐条 payload、时间戳、digest id。
DigestConfig	外出 DigestEntry.Config —— maxTimeout、maxListSize、ackTimeout。
IdleTimeoutEvent	入站 IdleTimeoutNotification —— 老化的 TableEntry 列表、时间戳。
DropEvent	内部丢弃事件 —— reason、时间戳、解析后的 PacketIn(如有)、消息。
DropEvent.Reason	枚举:SUBSCRIBER_LAG / QUEUE_FULL / FILTERED。

批量操作

类	作用
BatchBuilder	多更新批量 —— insert(e) / modify(e) / delete(e) / execute()。
WriteResult	BatchBuilder.execute() 结果 —— submitted 计数、逐条失败。
UpdateFailure	每条被拒更新一条 —— batch 下标、错误码、消息。

异常

全部继承自 P4RuntimeException;层次结构对应故障发生的位置。

类	含义
P4RuntimeException	sealed 父类。
P4ConnectionException	传输 / 主控权 / 已关闭交换机故障。
P4ArbitrationLost	特化 —— 主控被拒(连接或重夺)。
P4PipelineException	P4Info / 设备配置 / schema 问题。
P4OperationException	设备端拒绝了 Write 或 Read RPC。
ErrorCode	枚举,镜像 gRPC 规范错误码(OK / INVALID_ARGUMENT / NOT_FOUND / ALREADY_EXISTS / UNIMPLEMENTED / ...)。
OperationType	P4OperationException 上的枚举 —— INSERT / MODIFY / DELETE / READ。

值类型

API 中使用的小型原生包装。

类	作用
Bytes	canonical-bytestring 容器;of(byte[]) 构造,equals/hashCode 遵从前导零约定。
Mac	48 位 MAC 地址;fromBytes(byte[]) 和 ZERO 常量。
Ip4	IPv4 地址;of(String) 解析点分四段,toBytes() 返回 4 字节。
Ip6	IPv6 地址;of(String) 解析冒号十六进制,toBytes() 返回 16 字节。
ElectionId	无符号 128 位 id;见 客户端生命周期。

权威参考

上面所有链接指向标准 Javadoc,由 javadoc 工具按项目标准 tag 约定生成(@since 1.0.0 / @since 1.5.0 等标记标明每个类或方法的引入版本;@implNote 标记非规范性实现细节)。Maven Central 的 jar 坐标见 快速开始。