opendaylight/hosttracker_new/api/src/main/java/org/opendaylight/controller/hosttracker/IDeviceService.java

   1 /*
   2  * Copyright (c) 2011,2012 Big Switch Networks, Inc.
   3  *
   4  * Licensed under the Eclipse Public License, Version 1.0 (the
   5  * "License"); you may not use this file except in compliance with the
   6  * License. You may obtain a copy of the License at
   7  *
   8  *      http://www.eclipse.org/legal/epl-v10.html
   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
  13  * implied. See the License for the specific language governing
  14  * permissions and limitations under the License.
  15  *
  16  * This file incorporates work covered by the following copyright and
  17  * permission notice:
  18  *
  19  *    Originally created by David Erickson, Stanford University
  20  *
  21  *    Licensed under the Apache License, Version 2.0 (the "License");
  22  *    you may not use this file except in compliance with the
  23  *    License. You may obtain a copy of the License at
  24  *
  25  *         http://www.apache.org/licenses/LICENSE-2.0
  26  *
  27  *    Unless required by applicable law or agreed to in writing,
  28  *    software distributed under the License is distributed on an "AS
  29  *    IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
  30  *    express or implied. See the License for the specific language
  31  *    governing permissions and limitations under the License.
  32  */
  33
  34 package org.opendaylight.controller.hosttracker;
  35
  36 import java.util.Collection;
  37 import java.util.EnumSet;
  38 import java.util.Iterator;
  39 import java.util.Set;
  40
  41 import org.opendaylight.controller.sal.core.NodeConnector;
  42 import org.osgi.service.device.Device;
  43
  44 /**
  45  * Device manager allows interacting with devices on the network. Note that
  46  * under normal circumstances, {@link Device} objects should be retrieved from
  47  * the {@link FloodlightContext} rather than from {@link IDeviceManager}.
  48  */
  49 public interface IDeviceService {
  50
  51     /**
  52      * Fields used in devices for indexes and querying
  53      *
  54      * @see IDeviceService#addIndex
  55      */
  56     enum DeviceField {
  57         MAC, IPV4, VLAN, SWITCHPORT
  58     }
  59
  60     /**
  61      * The source device for the current packet-in, if applicable.
  62      */
  63     // public static final String CONTEXT_SRC_DEVICE =
  64     // "net.floodlightcontroller.devicemanager.srcDevice";
  65
  66     /**
  67      * The destination device for the current packet-in, if applicable.
  68      */
  69     // public static final String CONTEXT_DST_DEVICE =
  70     // / "net.floodlightcontroller.devicemanager.dstDevice";
  71
  72     /**
  73      * The original destination device for the current packet-in
  74      */
  75     // public static final String CONTEXT_ORIG_DST_DEVICE =
  76     // "net.floodlightcontroller.devicemanager.origDstDevice";
  77
  78     /**
  79      * A FloodlightContextStore object that can be used to interact with the
  80      * FloodlightContext information created by BVS manager.
  81      */
  82     // public static final FloodlightContextStore<IDevice> fcStore =
  83     // new FloodlightContextStore<IDevice>();
  84
  85     /**
  86      * Get the device with the given device key.
  87      *
  88      * @param deviceKey
  89      *            the key to search for
  90      * @return the device associated with the key, or null if no such device
  91      * @see IDevice#getDeviceKey()
  92      */
  93     public IDevice getDevice(Long deviceKey);
  94
  95     /**
  96      * Search for a device exactly matching the provided device fields. This is
  97      * the same lookup process that is used for packet_in processing and device
  98      * learning. Thus, findDevice() can be used to match flow entries from
  99      * switches to devices. Only the key fields as defined by the
 100      * {@link IEntityClassifierService} will be important in this search. All
 101      * key fields MUST be supplied.
 102      *
 103      * {@link queryDevices()} might be more appropriate!
 104      *
 105      * @param macAddress
 106      *            The MAC address
 107      * @param vlan
 108      *            the VLAN. Null means no VLAN and is valid even if VLAN is a
 109      *            key field.
 110      * @param ipv4Address
 111      *            the ipv4 address
 112      * @param port
 113      *            the node connector
 114      * @return an {@link IDevice} or null if no device is found.
 115      * @see IDeviceManager#setEntityClassifier(IEntityClassifierService)
 116      * @throws IllegalArgumentException
 117      *             if not all key fields of the current
 118      *             {@link IEntityClassifierService} are specified.
 119      */
 120     public IDevice findDevice(long macAddress, Short vlan, Integer ipv4Address,
 121             NodeConnector port) throws IllegalArgumentException;
 122
 123     /**
 124      * Get a destination device using entity fields that corresponds with the
 125      * given source device. The source device is important since there could be
 126      * ambiguity in the destination device without the attachment point
 127      * information. Search for a device in a given entity class. This is the
 128      * same as the lookup process for destination devices.
 129      *
 130      * Only the key fields as defined by the reference entity class will be
 131      * important in this search. All key fields MUST be supplied.
 132      *
 133      * @param entityClass
 134      *            The entity class in which to perform the lookup.
 135      * @param macAddress
 136      *            The MAC address for the destination
 137      * @param vlan
 138      *            the VLAN if available
 139      * @param ipv4Address
 140      *            The IP address if available.
 141      * @return an {@link IDevice} or null if no device is found.
 142      * @see IDeviceService#findDevice(long, Short, Integer, Long, Integer)
 143      * @throws IllegalArgumentException
 144      *             if not all key fields of the source's {@link IEntityClass}
 145      *             are specified.
 146      */
 147     public IDevice findClassDevice(IEntityClass entityClass, long macAddress,
 148             Short vlan, Integer ipv4Address) throws IllegalArgumentException;
 149
 150     /**
 151      * Get an unmodifiable collection view over all devices currently known.
 152      *
 153      * @return the collection of all devices
 154      */
 155     public Collection<? extends IDevice> getAllDevices();
 156
 157     /**
 158      * Create an index over a set of fields. This allows efficient lookup of
 159      * devices when querying using the indexed set of specified fields. The
 160      * index must be registered before any device learning takes place, or it
 161      * may be incomplete. It's OK if this is called multiple times with the same
 162      * fields; only one index will be created for each unique set of fields.
 163      *
 164      * @param perClass
 165      *            set to true if the index should be maintained for each entity
 166      *            class separately.
 167      * @param keyFields
 168      *            the set of fields on which to index
 169      */
 170     public void addIndex(boolean perClass, EnumSet<DeviceField> keyFields);
 171
 172     /**
 173      * Find devices that match the provided query. Any fields that are null will
 174      * not be included in the query. If there is an index for the query, then it
 175      * will be performed efficiently using the index. Otherwise, there will be a
 176      * full scan of the device list.
 177      *
 178      * @param macAddress
 179      *            The MAC address
 180      * @param vlan
 181      *            the VLAN
 182      * @param ipv4Address
 183      *            the ipv4 address
 184      * @param port
 185      *            the switch port
 186      * @return an iterator over a set of devices matching the query
 187      * @see IDeviceService#queryClassDevices(IEntityClass, Long, Short, Integer,
 188      *      Long, Integer)
 189      */
 190     public Iterator<? extends IDevice> queryDevices(Long macAddress,
 191             Short vlan, Integer ipv4Address, NodeConnector port);
 192
 193     /**
 194      * Find devices that match the provided query. Only the index for the
 195      * specified class will be searched. Any fields that are null will not be
 196      * included in the query. If there is an index for the query, then it will
 197      * be performed efficiently using the index. Otherwise, there will be a full
 198      * scan of the device list.
 199      *
 200      * @param entityClass
 201      *            The entity class in which to perform the query
 202      * @param macAddress
 203      *            The MAC address
 204      * @param vlan
 205      *            the VLAN
 206      * @param ipv4Address
 207      *            the ipv4 address
 208      * @param port
 209      *            the switch port
 210      * @return an iterator over a set of devices matching the query
 211      * @see IDeviceService#queryClassDevices(Long, Short, Integer, Long,
 212      *      Integer)
 213      */
 214     public Iterator<? extends IDevice> queryClassDevices(
 215             IEntityClass entityClass, Long macAddress, Short vlan,
 216             Integer ipv4Address, NodeConnector port);
 217
 218     /**
 219      * Adds a listener to listen for IDeviceManagerServices notifications
 220      *
 221      * @param listener
 222      *            The listener that wants the notifications
 223      * @param type
 224      *            The type of the listener
 225      */
 226     public void addListener(IDeviceListener listener);
 227
 228     /**
 229      * Specify points in the network where attachment points are not to be
 230      * learned.
 231      *
 232      * @param sw
 233      * @param port
 234      */
 235     public void addSuppressAPs(NodeConnector port);
 236
 237     public void removeSuppressAPs(NodeConnector port);
 238
 239     public Set<SwitchPort> getSuppressAPs();
 240
 241 }