opendaylight/hosttracker_new/api/src/main/java/org/opendaylight/controller/hosttracker/IEntityClassifierService.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
  39 import org.opendaylight.controller.hosttracker.IDeviceService.DeviceField;
  40
  41 /**
  42  * A component that wishes to participate in entity classification needs to
  43  * implement the IEntityClassifier interface, and register with the Device
  44  * Manager as an entity classifier. An entity is classified by the classifier
  45  * into an {@link IEntityClass}
  46  *
  47  * @author readams
  48  */
  49 public interface IEntityClassifierService {
  50     /**
  51      * Classify the given entity into an IEntityClass. It is important that the
  52      * key fields returned by {@link IEntityClassifierService#getKeyFields()} be
  53      * sufficient for classifying entities. That is, if two entities are
  54      * identical except for a field that is not a key field, they must be
  55      * assigned the same class. Furthermore, entity classification must be
  56      * transitive: For all entities x, y, z, if x and y belong to a class c, and
  57      * y and z belong class c, then x and z must belong to class c.
  58      *
  59      * @param entity
  60      *            the entity to classify
  61      * @return the IEntityClass resulting from the classification.
  62      * @see IEntityClassifierService#getKeyFields()
  63      */
  64     IEntityClass classifyEntity(Entity entity);
  65
  66     /**
  67      * Return the most general list of fields that should be used as key fields.
  68      * If devices differ in any fields not listed here, they can never be
  69      * considered a different device by any {@link IEntityClass} returned by
  70      * {@link IEntityClassifierService#classifyEntity}. The key fields for an
  71      * entity classifier must not change unless associated with a flush of all
  72      * entity state. The list of key fields must be the union of all key fields
  73      * that could be returned by {@link IEntityClass#getKeyFields()}.
  74      *
  75      * @return a set containing the fields that should not be wildcarded. May be
  76      *         null to indicate that all fields are key fields.
  77      * @see {@link IEntityClass#getKeyFields()}
  78      * @see {@link IEntityClassifierService#classifyEntity}
  79      */
  80     EnumSet<DeviceField> getKeyFields();
  81
  82     /**
  83      * Reclassify the given entity into a class. When reclassifying entities, it
  84      * can be helpful to take into account the current classification either as
  85      * an optimization or to allow flushing any cached state tied to the key for
  86      * that device. The entity will be assigned to a new device with a new
  87      * object if the entity class returned is different from the entity class
  88      * for curDevice.
  89      *
  90      * <p>
  91      * Note that you must take steps to ensure you always return classes in some
  92      * consistent ordering.
  93      *
  94      * @param curDevice
  95      *            the device currently associated with the entity
  96      * @param entity
  97      *            the entity to reclassify
  98      * @return the IEntityClass resulting from the classification
  99      */
 100     IEntityClass reclassifyEntity(IDevice curDevice, Entity entity);
 101
 102     /**
 103      * Once reclassification is complete for a device, this method will be
 104      * called. If any entities within the device changed their classification,
 105      * it will split into one or more new devices for each of the entities. If
 106      * two devices are merged because of a reclassification, then this will be
 107      * called on each of the devices, with the same device in the newDevices
 108      * collection.
 109      *
 110      * @param oldDevice
 111      *            the original device object
 112      * @param newDevices
 113      *            all the new devices derived from the entities of the old
 114      *            device. If null, the old device was unchanged.
 115      */
 116     void deviceUpdate(IDevice oldDevice,
 117             Collection<? extends IDevice> newDevices);
 118
 119     /**
 120      * Adds a listener to listen for IEntityClassifierServices notifications
 121      *
 122      * @param listener
 123      *            The listener that wants the notifications
 124      */
 125     public void addListener(IEntityClassListener listener);
 126 }