blob: 807d09eef1d0d412c2701041f9a5c6a63ad5c5c8 [file] [log] [blame]
Thomas Vachuska83e090e2014-10-22 14:25:35 -07001/*
Brian O'Connora09fe5b2017-08-03 21:12:30 -07002 * Copyright 2014-present Open Networking Foundation
Thomas Vachuska83e090e2014-10-22 14:25:35 -07003 *
Thomas Vachuska4f1a60c2014-10-28 13:39:07 -07004 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
Thomas Vachuska83e090e2014-10-22 14:25:35 -07007 *
Thomas Vachuska4f1a60c2014-10-28 13:39:07 -07008 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
Thomas Vachuska83e090e2014-10-22 14:25:35 -070015 */
Brian O'Connorabafb502014-12-02 22:26:20 -080016package org.onosproject.net.flow;
tom8bb16062014-09-12 14:47:46 -070017
Sangsik Yoonb1b823f2016-05-16 18:55:39 +090018import com.google.common.collect.Iterables;
Brian O'Connorabafb502014-12-02 22:26:20 -080019import org.onosproject.core.ApplicationId;
Thomas Vachuska42e8cce2015-07-29 19:25:18 -070020import org.onosproject.event.ListenerService;
Brian O'Connorabafb502014-12-02 22:26:20 -080021import org.onosproject.net.DeviceId;
tom8bb16062014-09-12 14:47:46 -070022
23/**
24 * Service for injecting flow rules into the environment and for obtaining
tom4d0c6632014-09-15 23:27:01 -070025 * information about flow rules already in the environment. This implements
26 * semantics of a distributed authoritative flow table where the master copy
27 * of the flow rules lies with the controller and the devices hold only the
28 * 'cached' copy.
tom8bb16062014-09-12 14:47:46 -070029 */
Thomas Vachuska42e8cce2015-07-29 19:25:18 -070030public interface FlowRuleService
31 extends ListenerService<FlowRuleEvent, FlowRuleListener> {
tom8bb16062014-09-12 14:47:46 -070032
33 /**
Brian O'Connor72cb19a2015-01-16 16:14:41 -080034 * The topic used for obtaining globally unique ids.
35 */
Sho SHIMIZUe2952e42015-09-11 17:11:21 -070036 String FLOW_OP_TOPIC = "flow-ops-ids";
Brian O'Connor72cb19a2015-01-16 16:14:41 -080037
38 /**
tom9b4030d2014-10-06 10:39:03 -070039 * Returns the number of flow rules in the system.
40 *
41 * @return flow rule count
42 */
43 int getFlowRuleCount();
44
45 /**
Thomas Vachuskaa8e74772018-02-26 11:33:35 -080046 * Returns the number of flow rules for the given device.
47 *
48 * @param deviceId device identifier
49 * @return number of flow rules for the given device
50 */
51 default int getFlowRuleCount(DeviceId deviceId) {
52 return 0;
53 }
54
55 /**
Jordan Haltermanb81fdc12019-03-04 18:12:20 -080056 * Returns the number of flow rules in the given state for the given device.
57 *
58 * @param deviceId the device identifier
59 * @param state the state for which to count flow rules
60 * @return number of flow rules in the given state for the given device
61 */
62 default int getFlowRuleCount(DeviceId deviceId, FlowEntry.FlowEntryState state) {
63 return 0;
64 }
65
66 /**
David Glantz0a5779c2021-09-22 14:34:14 -050067 * Returns the stored flow.
68 *
69 * @param rule the rule to look for
70 * @return a flow rule
71 */
72 FlowEntry getFlowEntry(FlowRule rule);
73
74 /**
tom8bb16062014-09-12 14:47:46 -070075 * Returns the collection of flow entries applied on the specified device.
tom4d0c6632014-09-15 23:27:01 -070076 * This will include flow rules which may not yet have been applied to
77 * the device.
tom8bb16062014-09-12 14:47:46 -070078 *
79 * @param deviceId device identifier
80 * @return collection of flow rules
81 */
alshabib1c319ff2014-10-04 20:29:09 -070082 Iterable<FlowEntry> getFlowEntries(DeviceId deviceId);
tom8bb16062014-09-12 14:47:46 -070083
84 /**
Sangsik Yoonb1b823f2016-05-16 18:55:39 +090085 * Returns a list of rules filtered by device id and flow live type.
86 *
87 * @param deviceId the device id to lookup
88 * @param liveType the flow live type to lookup
89 * @return collection of flow entries
90 */
91 default Iterable<FlowEntry> getFlowEntriesByLiveType(DeviceId deviceId,
92 FlowEntry.FlowLiveType liveType) {
93 return Iterables.filter(getFlowEntries(deviceId), fe -> fe.liveType() == liveType);
94 }
95
Georgios Katsikas5eba8aa2017-07-23 18:27:48 +020096 /**
97 * Returns a list of rules filtered by device id and flow state.
98 *
99 * @param deviceId the device id to lookup
100 * @param flowState the flow state to lookup
101 * @return collection of flow entries
102 */
103 default Iterable<FlowEntry> getFlowEntriesByState(DeviceId deviceId,
104 FlowEntry.FlowEntryState flowState) {
105 return Iterables.filter(getFlowEntries(deviceId), fe -> fe.state() == flowState);
106 }
107
Sangsik Yoonb1b823f2016-05-16 18:55:39 +0900108 // TODO: add createFlowRule factory method and execute operations method
109
110 /**
tom4d0c6632014-09-15 23:27:01 -0700111 * Applies the specified flow rules onto their respective devices. These
112 * flow rules will be retained by the system and re-applied anytime the
113 * device reconnects to the controller.
tom8bb16062014-09-12 14:47:46 -0700114 *
115 * @param flowRules one or more flow rules
tom8bb16062014-09-12 14:47:46 -0700116 */
alshabib219ebaa2014-09-22 15:41:24 -0700117 void applyFlowRules(FlowRule... flowRules);
tom8bb16062014-09-12 14:47:46 -0700118
119 /**
Kavitha Alagesanc69c66a2016-06-15 14:26:04 +0530120 * Purges all the flow rules on the specified device.
121 * @param deviceId device identifier
122 */
123 void purgeFlowRules(DeviceId deviceId);
124
125 /**
Daniele Moro43ac2892021-07-15 17:02:59 +0200126 * Purges all the flow rules on the specified device from the given application id.
127 * @param deviceId device identifier
128 * @param appId application identifier
129 */
130 default void purgeFlowRules(DeviceId deviceId, ApplicationId appId) {
131 throw new UnsupportedOperationException("purgeFlowRules not implemented!");
132 }
133
134 /**
tom4d0c6632014-09-15 23:27:01 -0700135 * Removes the specified flow rules from their respective devices. If the
136 * device is not presently connected to the controller, these flow will
137 * be removed once the device reconnects.
alshabib369d2942014-09-12 17:59:35 -0700138 *
139 * @param flowRules one or more flow rules
alshabib369d2942014-09-12 17:59:35 -0700140 */
141 void removeFlowRules(FlowRule... flowRules);
142
alshabiba68eb962014-09-24 20:34:13 -0700143 /**
Jonathan Hart3fc7e832016-05-23 15:41:11 -0700144 * Removes all rules submitted by a particular application.
alshabiba68eb962014-09-24 20:34:13 -0700145 *
Jonathan Hart3fc7e832016-05-23 15:41:11 -0700146 * @param appId ID of application whose flows will be removed
alshabiba68eb962014-09-24 20:34:13 -0700147 */
148 void removeFlowRulesById(ApplicationId appId);
149
150 /**
Jonathan Hart3fc7e832016-05-23 15:41:11 -0700151 * Returns a list of rules with this application ID.
alshabiba68eb962014-09-24 20:34:13 -0700152 *
Jonathan Hart3fc7e832016-05-23 15:41:11 -0700153 * @param id the application ID to look up
alshabiba68eb962014-09-24 20:34:13 -0700154 * @return collection of flow rules
155 */
Bharath Thiruveedula99849dc2016-11-17 22:04:38 +0530156 Iterable<FlowEntry> getFlowEntriesById(ApplicationId id);
157
158 /**
Jonathan Hart5acc88a2016-05-23 10:50:20 -0700159 * Returns a list of rules filtered by application and group id.
160 * <p>
161 * Note that the group concept here is simply a logical grouping of flows.
162 * This is not the same as a group in the
163 * {@link org.onosproject.net.group.GroupService}, and this method will not
164 * return flows that are mapped to a particular {@link org.onosproject.net.group.Group}.
165 * </p>
alshabibaa7e7de2014-11-12 19:20:44 -0800166 *
Jonathan Hart5acc88a2016-05-23 10:50:20 -0700167 * @param appId the application ID to look up
168 * @param groupId the group ID to look up
alshabibaa7e7de2014-11-12 19:20:44 -0800169 * @return collection of flow rules
170 */
171 Iterable<FlowRule> getFlowRulesByGroupId(ApplicationId appId, short groupId);
172
173 /**
alshabib902d41b2014-10-07 16:52:05 -0700174 * Applies a batch operation of FlowRules.
175 *
Brian O'Connor72cb19a2015-01-16 16:14:41 -0800176 * @param ops batch operation to apply
177 */
178 void apply(FlowRuleOperations ops);
179
Srikanth Vavilapalli95810f52015-09-14 15:49:56 -0700180 /**
181 * Returns the collection of flow table statistics of the specified device.
182 *
183 * @param deviceId device identifier
184 * @return collection of flow table statistics
185 */
186 Iterable<TableStatisticsEntry> getFlowTableStatistics(DeviceId deviceId);
Patryk Konopka7e40c012017-06-06 13:38:06 +0200187
188 /**
189 * Returns number of flow rules in ADDED state for specified device.
190 *
191 * @param deviceId device identifier
192 * @return number of flow rules in ADDED state
Jordan Haltermanb81fdc12019-03-04 18:12:20 -0800193 * @deprecated since 2.1
Patryk Konopka7e40c012017-06-06 13:38:06 +0200194 */
Jordan Haltermanb81fdc12019-03-04 18:12:20 -0800195 @Deprecated
Patryk Konopka7e40c012017-06-06 13:38:06 +0200196 default long getActiveFlowRuleCount(DeviceId deviceId) {
197 return 0;
198 }
pierventre16ff3292022-03-18 10:31:04 +0100199
200 /**
201 * Applies the specified flow rules onto their respective devices. Similar
202 * to {@link FlowRuleService#applyFlowRules(FlowRule...)} but expectation is
203 * that flow rules applied by subsequent calls using the same key will be
204 * executed sequentially. Flow rules applied through {@link FlowRuleService#applyFlowRules(FlowRule...)}
205 * might be executed in parallel.
206 *
207 * @param stripeKey an integer key
208 * @param flowRules one or more flow rules
209 */
210 default void applyFlowRules(int stripeKey, FlowRule... flowRules) {
211
212 }
213
214 /**
215 * Removes the specified flow rules from their respective devices. Similar
216 * to {@link FlowRuleService#removeFlowRules(FlowRule...)} but expectation is
217 * that flow rules removed by subsequent calls using the same key will be
218 * executed sequentially. Flow rules applied through {@link FlowRuleService#removeFlowRules(FlowRule...)}
219 * might be executed in parallel.
220 *
221 * @param stripeKey an integer key
222 * @param flowRules one or more flow rules
223 */
224 default void removeFlowRules(int stripeKey, FlowRule... flowRules) {
225
226 }
227
tom8bb16062014-09-12 14:47:46 -0700228}