opendaylight/adsal/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
  43 /**
  44  * Device manager allows interacting with devices on the network. Note that
  45  * under normal circumstances, {@link Device} objects should be retrieved from
  46  * the {@link FloodlightContext} rather than from {@link IDeviceManager}.
  47  */
  48 public interface IDeviceService {
  49
  50     /**
  51      * Fields used in devices for indexes and querying
  52      *
  53      * @see IDeviceService#addIndex
  54      */
  55     enum DeviceField {
  56         MAC, IPV4, VLAN, SWITCHPORT
  57     }
  58
  59     /**
  60      * Get the device with the given device key.
  61      *
  62      * @param deviceKey
  63      *            the key to search for
  64      * @return the device associated with the key, or null if no such device
  65      * @see IDevice#getDeviceKey()
  66      */
  67     public IDevice getDevice(Long deviceKey);
  68
  69     /**
  70      * Search for a device exactly matching the provided device fields. This is
  71      * the same lookup process that is used for packet_in processing and device
  72      * learning. Thus, findDevice() can be used to match flow entries from
  73      * switches to devices. Only the key fields as defined by the
  74      * {@link IEntityClassifierService} will be important in this search. All
  75      * key fields MUST be supplied.
  76      *
  77      * {@link queryDevices()} might be more appropriate!
  78      *
  79      * @param macAddress
  80      *            The MAC address
  81      * @param vlan
  82      *            the VLAN. Null means no VLAN and is valid even if VLAN is a
  83      *            key field.
  84      * @param ipv4Address
  85      *            the ipv4 address
  86      * @param port
  87      *            the node connector
  88      * @return an {@link IDevice} or null if no device is found.
  89      * @see IDeviceManager#setEntityClassifier(IEntityClassifierService)
  90      * @throws IllegalArgumentException
  91      *             if not all key fields of the current
  92      *             {@link IEntityClassifierService} are specified.
  93      */
  94     public IDevice findDevice(long macAddress, Short vlan, Integer ipv4Address,
  95             NodeConnector port) throws IllegalArgumentException;
  96
  97     /**
  98      * Get a destination device using entity fields that corresponds with the
  99      * given source device. The source device is important since there could be
 100      * ambiguity in the destination device without the attachment point
 101      * information. Search for a device in a given entity class. This is the
 102      * same as the lookup process for destination devices.
 103      *
 104      * Only the key fields as defined by the reference entity class will be
 105      * important in this search. All key fields MUST be supplied.
 106      *
 107      * @param entityClass
 108      *            The entity class in which to perform the lookup.
 109      * @param macAddress
 110      *            The MAC address for the destination
 111      * @param vlan
 112      *            the VLAN if available
 113      * @param ipv4Address
 114      *            The IP address if available.
 115      * @return an {@link IDevice} or null if no device is found.
 116      * @see IDeviceService#findDevice(long, Short, Integer, Long, Integer)
 117      * @throws IllegalArgumentException
 118      *             if not all key fields of the source's {@link IEntityClass}
 119      *             are specified.
 120      */
 121     public IDevice findClassDevice(IEntityClass entityClass, long macAddress,
 122             Short vlan, Integer ipv4Address) throws IllegalArgumentException;
 123
 124     /**
 125      * Get an unmodifiable collection view over all devices currently known.
 126      *
 127      * @return the collection of all devices
 128      */
 129     public Collection<? extends IDevice> getAllDevices();
 130
 131     /**
 132      * Create an index over a set of fields. This allows efficient lookup of
 133      * devices when querying using the indexed set of specified fields. The
 134      * index must be registered before any device learning takes place, or it
 135      * may be incomplete. It's OK if this is called multiple times with the same
 136      * fields; only one index will be created for each unique set of fields.
 137      *
 138      * @param perClass
 139      *            set to true if the index should be maintained for each entity
 140      *            class separately.
 141      * @param keyFields
 142      *            the set of fields on which to index
 143      */
 144     public void addIndex(boolean perClass, EnumSet<DeviceField> keyFields);
 145
 146     /**
 147      * Find devices that match the provided query. Any fields that are null will
 148      * not be included in the query. If there is an index for the query, then it
 149      * will be performed efficiently using the index. Otherwise, there will be a
 150      * full scan of the device list.
 151      *
 152      * @param macAddress
 153      *            The MAC address
 154      * @param vlan
 155      *            the VLAN
 156      * @param ipv4Address
 157      *            the ipv4 address
 158      * @param port
 159      *            the switch port
 160      * @return an iterator over a set of devices matching the query
 161      * @see IDeviceService#queryClassDevices(IEntityClass, Long, Short, Integer,
 162      *      Long, Integer)
 163      */
 164     public Iterator<? extends IDevice> queryDevices(Long macAddress,
 165             Short vlan, Integer ipv4Address, NodeConnector port);
 166
 167     /**
 168      * Find devices that match the provided query. Only the index for the
 169      * specified class will be searched. Any fields that are null will not be
 170      * included in the query. If there is an index for the query, then it will
 171      * be performed efficiently using the index. Otherwise, there will be a full
 172      * scan of the device list.
 173      *
 174      * @param entityClass
 175      *            The entity class in which to perform the query
 176      * @param macAddress
 177      *            The MAC address
 178      * @param vlan
 179      *            the VLAN
 180      * @param ipv4Address
 181      *            the ipv4 address
 182      * @param port
 183      *            the switch port
 184      * @return an iterator over a set of devices matching the query
 185      * @see IDeviceService#queryClassDevices(Long, Short, Integer, Long,
 186      *      Integer)
 187      */
 188     public Iterator<? extends IDevice> queryClassDevices(
 189             IEntityClass entityClass, Long macAddress, Short vlan,
 190             Integer ipv4Address, NodeConnector port);
 191
 192     /**
 193      * Adds a listener to listen for IDeviceManagerServices notifications
 194      *
 195      * @param listener
 196      *            The listener that wants the notifications
 197      * @param type
 198      *            The type of the listener
 199      */
 200     public void addListener(IDeviceListener listener);
 201
 202     /**
 203      * Specify points in the network where attachment points are not to be
 204      * learned.
 205      *
 206      * @param sw
 207      * @param port
 208      */
 209     public void addSuppressAPs(NodeConnector port);
 210
 211     public void removeSuppressAPs(NodeConnector port);
 212
 213     public Set<SwitchPort> getSuppressAPs();
 214
 215 }