[ONOS-7675] Initial implementation of IntProgrammable
Change-Id: I277ea7a56bb3a38debbb2959823df394a4103541
diff --git a/apps/inbandtelemetry/api/src/main/java/org/onosproject/inbandtelemetry/api/IntIntent.java b/apps/inbandtelemetry/api/src/main/java/org/onosproject/inbandtelemetry/api/IntIntent.java
new file mode 100644
index 0000000..21d5381
--- /dev/null
+++ b/apps/inbandtelemetry/api/src/main/java/org/onosproject/inbandtelemetry/api/IntIntent.java
@@ -0,0 +1,295 @@
+/*
+ * Copyright 2015-present Open Networking Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.inbandtelemetry.api;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.net.flow.DefaultTrafficSelector;
+import org.onosproject.net.flow.TrafficSelector;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+/**
+ * Represents an INT monitoring intent. Each intent is made up of a traffic slice
+ * to be monitored, as a form of TrafficSelector, types of metadata to collect,
+ * and other required parameters (INT header type, INT Report type, and Telemetry mode).
+ *
+ * IntIntent is converted to a set of flow rules to be installed on each INT-capable
+ * switch in the network, by IntService.
+ *
+ * Terminologies and descriptions are borrowed from INT specification.
+ *
+ * @see <a href="https://github.com/p4lang/p4-applications/blob/master/docs/INT.pdf">
+ * INT sepcification</a>
+ */
+@Beta
+public final class IntIntent {
+ /**
+ * Represents a type of INT metadata.
+ */
+ public enum IntMetadataType {
+ /**
+ * The unique ID of a switch.
+ */
+ SWITCH_ID,
+ /**
+ * The ports on which the INT packet was received and sent out.
+ */
+ L1_PORT_ID,
+ /**
+ * Time taken for the INT packet to be switched within the device.
+ */
+ HOP_LATENCY,
+ /**
+ * The build-up of traffic in the queue that the INT packet observes
+ * in the device while being forwarded.
+ */
+ QUEUE_OCCUPANCY,
+ /**
+ * The device local time when the INT packet was received on the ingress port.
+ */
+ INGRESS_TIMESTAMP,
+ /**
+ * The device local time when the INT packet was processed by the egress port.
+ */
+ EGRESS_TIMESTAMP,
+ /**
+ * The logical ports on which the INT packet was received and sent out.
+ */
+ L2_PORT_ID,
+ /**
+ * Current utilization of the egress port via witch the INT packet was sent out.
+ */
+ EGRESS_TX_UTIL
+ }
+
+ /**
+ * Represents an INT header type.
+ */
+ public enum IntHeaderType {
+ /**
+ * Intemediate devices must process this type of INT header.
+ */
+ HOP_BY_HOP,
+ /**
+ * Intemediate devices must ignore this type of INT header.
+ */
+ DESTINATION
+ }
+
+ /**
+ * Represents a type of telemetry report.
+ */
+ public enum IntReportType {
+ /**
+ * Report for flows matching certain definitions.
+ */
+ TRACKED_FLOW,
+ /**
+ * Reports for all dropeed packets matching a drop watchlist.
+ */
+ DROPPED_PACKET,
+ /**
+ * Reports for traffic entering a specific queue during a period of queue congestion.
+ */
+ CONGESTED_QUEUE
+ }
+
+ /**
+ * Represents telemetry mode.
+ */
+ public enum TelemetryMode {
+ /**
+ * Each network device generates its own telemetry reports.
+ */
+ POSTCARD,
+ /**
+ * Telemetry metadata is embedded in between the original
+ * headers of data packets as they traverse the network.
+ */
+ INBAND_TELEMETRY
+ }
+
+ private static final int DEFAULT_PRIORITY = 10;
+
+ // TrafficSelector to describe target flows to monitor
+ private final TrafficSelector selector;
+ // set of metadata type to collect
+ private final Set<IntMetadataType> metadataTypes;
+ // hop-by-hop or destination
+ private final IntHeaderType headerType;
+ // telemetry report types
+ private final Set<IntReportType> reportTypes;
+ // telemetry mode
+ private final TelemetryMode telemetryMode;
+
+ /**
+ * Creates an IntIntent.
+ *
+ * @param selector the traffic selector that identifies traffic to enable INT
+ * @param metadataTypes the types of metadata to collect
+ * @param headerType the type of INT header
+ * @param reportTypes the types of report to be generated
+ * @param telemetryMode the telemetry mode
+ */
+ private IntIntent(TrafficSelector selector, Set<IntMetadataType> metadataTypes,
+ IntHeaderType headerType, Set<IntReportType> reportTypes,
+ TelemetryMode telemetryMode) {
+ this.selector = selector;
+ this.metadataTypes = new HashSet<>(metadataTypes);
+ this.headerType = headerType;
+ this.reportTypes = new HashSet<>(reportTypes);
+ this.telemetryMode = telemetryMode;
+ }
+
+ /**
+ * Returns traffic selector of this intent.
+ *
+ * @return traffic selector
+ */
+ public TrafficSelector selector() {
+ return selector;
+ }
+
+ /**
+ * Returns a set of metadata type to be collected by this intent.
+ *
+ * @return set of metadata type
+ */
+ public Set<IntMetadataType> metadataTypes() {
+ return metadataTypes;
+ }
+
+ /**
+ * Returns a INT header type specified in this intent.
+ *
+ * @return INT header type
+ */
+ public IntHeaderType headerType() {
+ return headerType;
+ }
+
+ /**
+ * Returns a set of report type to be generated.
+ *
+ * @return set of report type
+ */
+ public Set<IntReportType> reportTypes() {
+ return reportTypes;
+ }
+
+ /**
+ * Returns a telemetry mode specified in this intent.
+ *
+ * @return telemtry mode
+ */
+ public TelemetryMode telemetryMode() {
+ return telemetryMode;
+ }
+
+ /**
+ * Returns a new builder.
+ *
+ * @return new builder
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * An IntIntent builder.
+ */
+ public static final class Builder {
+ private TrafficSelector selector = DefaultTrafficSelector.emptySelector();
+ private Set<IntMetadataType> metadataTypes = new HashSet<>();
+ private IntHeaderType headerType = IntHeaderType.HOP_BY_HOP;
+ private Set<IntReportType> reportTypes = new HashSet<>();
+ private TelemetryMode telemetryMode = TelemetryMode.INBAND_TELEMETRY;
+
+ /**
+ * Assigns a selector to the IntIntent.
+ *
+ * @param selector a traffic selector
+ * @return an IntIntent builder
+ */
+ public IntIntent.Builder withSelector(TrafficSelector selector) {
+ this.selector = selector;
+ return this;
+ }
+
+ /**
+ * Add a metadata type to the IntIntent.
+ *
+ * @param metadataType a type of metadata to collect
+ * @return an IntIntent builder
+ */
+ public IntIntent.Builder withMetadataType(IntMetadataType metadataType) {
+ this.metadataTypes.add(metadataType);
+ return this;
+ }
+
+ /**
+ * Assigns a header type to the IntIntent.
+ *
+ * @param headerType a header type
+ * @return an IntIntent builder
+ */
+ public IntIntent.Builder withHeaderType(IntHeaderType headerType) {
+ this.headerType = headerType;
+ return this;
+ }
+
+ /**
+ * Add a report type to the IntIntent.
+ *
+ * @param reportType a type of report
+ * @return an IntIntent builder
+ */
+ public IntIntent.Builder withReportType(IntReportType reportType) {
+ this.reportTypes.add(reportType);
+ return this;
+ }
+
+ /**
+ * Assigns a telemetry mode to the IntIntent.
+ *
+ * @param telemetryMode a telemetry mode
+ * @return an IntIntent builder
+ */
+ public IntIntent.Builder withTelemetryMode(TelemetryMode telemetryMode) {
+ this.telemetryMode = telemetryMode;
+ return this;
+ }
+
+ /**
+ * Builds the IntIntent.
+ *
+ * @return an IntIntent
+ */
+ public IntIntent build() {
+ checkArgument(!selector.criteria().isEmpty(), "Empty selector cannot match any flow.");
+ checkArgument(!metadataTypes.isEmpty(), "Metadata types cannot be empty.");
+ checkNotNull(headerType, "Header type cannot be null.");
+ checkNotNull(!reportTypes.isEmpty(), "Report types cannot be empty.");
+ checkNotNull(telemetryMode, "Telemetry mode cannot be null.");
+
+ return new IntIntent(selector, metadataTypes, headerType, reportTypes, telemetryMode);
+ }
+ }
+}