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