API reference

The complete jp4 public surface as of v1.5, organized into categories. Each entry links to the standard Javadoc HTML for the class. The Javadoc itself lives at /api/javadoc/ and is generated from the source by the standard javadoc tool — the authoritative source of truth for every method signature, return type, exception list, and @since tag.

For task-oriented guidance see Cookbook and Guides. For deeper background on cross-cutting topics see In-depth concepts.

Client lifecycle

Class	What it does
P4Switch	Single client connection to one P4Runtime device. The main entry class for every jp4 program.
Connector	Fluent builder for opening a P4Switch connection: address, deviceId, electionId, reconnectPolicy, primary or secondary role.
ReconnectPolicy	Auto-reconnect configuration — noRetry() (default) or exponentialBackoff(initial, max, retries).
ElectionId	Unsigned 128-bit P4Runtime election id (low + high pair). of(long) shorthand for low-only ids.
MastershipStatus	Sealed parent for the Acquired / Lost events delivered to onMastershipChange listeners.
MastershipStatus.Acquired	Record signaling this client became primary; carries ourElectionId.
MastershipStatus.Lost	Record signaling this client is not primary; carries previousElectionId (nullable) and currentPrimaryElectionId (nullable).

Pipeline

Class	What it does
Pipeline	Bound pipeline view exposing the parsed P4Info plus the device-config descriptor.
P4Info	Schema wrapper over p4.config.v1.P4Info — name index for tables, actions, fields, entities, controller-metadata.
DeviceConfig	Sealed parent for the two device-config variants.
DeviceConfig.Bmv2	BMv2-flavoured JSON device config; fromFile(Path) and fromBytes(byte[]) factories.
DeviceConfig.Raw	Bytes-only escape hatch for non-BMv2 targets.
PipelineAction	Verb selector for SetForwardingPipelineConfig (default VERIFY_AND_COMMIT).

Schema accessors (sub-types of P4Info)

Class	What it does
TableInfo	Resolved table metadata: id, match fields, action set, size.
MatchFieldInfo	Match field metadata: name, kind, bit width.
MatchFieldInfo.Kind	Enum: EXACT / LPM / TERNARY / RANGE / OPTIONAL.
ActionInfo	Resolved action metadata: id, parameter list.
ActionParamInfo	Action parameter metadata: name, bit width.
CounterInfo / Unit	Counter declaration with unit (BYTES / PACKETS / BOTH / UNSPECIFIED).
MeterInfo / Unit	Meter declaration with unit (BYTES / PACKETS / UNSPECIFIED).
RegisterInfo	Register declaration: id, name, size.
ActionProfileInfo	Action profile declaration with table-id set the profile is referenced from.
PacketMetadataInfo	controller_packet_metadata field declaration.

Match types

Class	What it does
Match	Sealed parent; static lpm(cidr) and exact(value) shorthands.
Match.Exact	Exact-match key (value).
Match.Lpm	Longest-prefix-match key (value, prefixLen).
Match.Ternary	Ternary key (value, mask).
Match.Range	Range key (low, high).
Match.Optional	Optional key (value; null-safe wildcard).

Entity records

Records carrying typed data for each P4Runtime entity type.

Class	What it does
TableEntry	Table entry record; in(name) builder entry point.
TableEntryBuilder	Fluent builder for TableEntry — match, action, priority, idleTimeoutNs.
ActionInstance	Named action with parameter map; reachable from TableEntry.action(), ActionProfileMember.action().
ActionBuilder	Fluent builder for the .action(name).param(name, value) chain.
CounterEntry	One counter cell — name, index, packetCount, byteCount.
CounterData	Per-color packet/byte counter (used by MeterCounterData).
MeterEntry	One meter cell — name, index, config, per-color counter data.
MeterConfig	Meter rate config — cir, cburst, pir, pburst, eburst.
MeterCounterData	Per-color cumulative counters (green, yellow, red).
RegisterEntry	One register cell — name, index, serialised P4Data bytes.
ActionProfileMember	Action-profile member — profile name, member id, action.
ActionProfileGroup	Action-profile group — profile name, group id, max size, weighted members.
WeightedMember	Group member — id, weight, nullable watch port.
MulticastGroupEntry	Multicast group — id, replicas, metadata.
CloneSessionEntry	Clone session — id, replicas, classOfService, packetLengthBytes.
Replica	Per-port fan-out slot — nullable port, instance, backup-replica list.
BackupReplica	Backup replica — non-null port, instance.

Read queries

Typed query builders for each entity-read family. All seven share the same shape: a server-side filter, a where(Predicate) client-side filter, and five terminals (all / one / stream / allAsync / oneAsync).

Class	Server-side filter
ReadQuery	Table reads: match(field, MatchKind)
CounterReadQuery	index(long)
MeterReadQuery	index(long)
RegisterReadQuery	index(long)
ActionProfileMemberReadQuery	memberId(long)
ActionProfileGroupReadQuery	groupId(long)
MulticastGroupReadQuery	groupId(long)
CloneSessionReadQuery	sessionId(long)

Stream messages

Records delivered to onPacketIn / onDigest / onIdleTimeout / onPacketDropped listeners, plus the outbound PacketOut builder.

Class	What it does
PacketIn	Inbound packet — payload, controller-metadata field accessors (metadata(name), metadataInt(name), metadataLong(name)).
PacketOut	Outbound packet record.
PacketOut.Builder	Fluent builder — payload(...), metadata(name, value).
DigestEvent	Inbound DigestList — name, list id, per-entry payloads, timestamp, digest id.
DigestConfig	Outbound DigestEntry.Config — maxTimeout, maxListSize, ackTimeout.
IdleTimeoutEvent	Inbound IdleTimeoutNotification — list of expired TableEntrys, timestamp.
DropEvent	Internal drop event — reason, timestamp, parsed PacketIn (if any), message.
DropEvent.Reason	Enum: SUBSCRIBER_LAG / QUEUE_FULL / FILTERED.

Batch operations

Class	What it does
BatchBuilder	Multi-update batch — insert(e) / modify(e) / delete(e) / execute().
WriteResult	Result of BatchBuilder.execute() — submitted count, per-update failures.
UpdateFailure	One per rejected update — batch index, error code, message.

Exceptions

All extend P4RuntimeException; the hierarchy maps to where the failure happened.

Class	What it signals
P4RuntimeException	Sealed parent.
P4ConnectionException	Transport / mastership / closed-switch failures.
P4ArbitrationLost	Specialised — primary denied (connect or re-claim).
P4PipelineException	P4Info / device-config / schema problems.
P4OperationException	Device-side rejection of a Write or Read RPC.
ErrorCode	Enum mirroring the gRPC canonical codes (OK / INVALID_ARGUMENT / NOT_FOUND / ALREADY_EXISTS / UNIMPLEMENTED / ...).
OperationType	Enum on P4OperationException — INSERT / MODIFY / DELETE / READ.

Value types

Small primitive wrappers used across the API.

Class	What it does
Bytes	Canonical-bytestring container; of(byte[]) constructor, equals/hashCode aware of the leading-zero convention.
Mac	48-bit MAC address; fromBytes(byte[]) and ZERO constant.
Ip4	IPv4 address; of(String) parses dotted-quad, toBytes() returns 4-byte.
Ip6	IPv6 address; of(String) parses colon-hex, toBytes() returns 16-byte.
ElectionId	Unsigned 128-bit id; see Client lifecycle.

Authoritative reference

Everything above links to the standard Javadoc, which is generated from the source by the javadoc tool with the project's standard tag conventions (@since 1.0.0 / @since 1.5.0 markers indicate when each class or method was added; @implNote for non-normative implementation details). For the Maven Central jar coordinate see the Quick start.