--- /dev/null
+/*
+ * Copyright (c) 2011,2012 Big Switch Networks, Inc.
+ *
+ * Licensed under the Eclipse Public License, Version 1.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at
+ *
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ *
+ * This file incorporates work covered by the following copyright and
+ * permission notice:
+ *
+ * Originally created by David Erickson, Stanford University
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an "AS
+ * IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+package org.opendaylight.controller.hosttracker;
+
+import java.util.Collection;
+import java.util.EnumSet;
+
+import org.opendaylight.controller.hosttracker.IDeviceService.DeviceField;
+
+/**
+ * A component that wishes to participate in entity classification needs to
+ * implement the IEntityClassifier interface, and register with the Device
+ * Manager as an entity classifier. An entity is classified by the classifier
+ * into an {@link IEntityClass}
+ *
+ * @author readams
+ */
+public interface IEntityClassifierService {
+ /**
+ * Classify the given entity into an IEntityClass. It is important that the
+ * key fields returned by {@link IEntityClassifierService#getKeyFields()} be
+ * sufficient for classifying entities. That is, if two entities are
+ * identical except for a field that is not a key field, they must be
+ * assigned the same class. Furthermore, entity classification must be
+ * transitive: For all entities x, y, z, if x and y belong to a class c, and
+ * y and z belong class c, then x and z must belong to class c.
+ *
+ * @param entity
+ * the entity to classify
+ * @return the IEntityClass resulting from the classification.
+ * @see IEntityClassifierService#getKeyFields()
+ */
+ IEntityClass classifyEntity(Entity entity);
+
+ /**
+ * Return the most general list of fields that should be used as key fields.
+ * If devices differ in any fields not listed here, they can never be
+ * considered a different device by any {@link IEntityClass} returned by
+ * {@link IEntityClassifierService#classifyEntity}. The key fields for an
+ * entity classifier must not change unless associated with a flush of all
+ * entity state. The list of key fields must be the union of all key fields
+ * that could be returned by {@link IEntityClass#getKeyFields()}.
+ *
+ * @return a set containing the fields that should not be wildcarded. May be
+ * null to indicate that all fields are key fields.
+ * @see {@link IEntityClass#getKeyFields()}
+ * @see {@link IEntityClassifierService#classifyEntity}
+ */
+ EnumSet<DeviceField> getKeyFields();
+
+ /**
+ * Reclassify the given entity into a class. When reclassifying entities, it
+ * can be helpful to take into account the current classification either as
+ * an optimization or to allow flushing any cached state tied to the key for
+ * that device. The entity will be assigned to a new device with a new
+ * object if the entity class returned is different from the entity class
+ * for curDevice.
+ *
+ * <p>
+ * Note that you must take steps to ensure you always return classes in some
+ * consistent ordering.
+ *
+ * @param curDevice
+ * the device currently associated with the entity
+ * @param entity
+ * the entity to reclassify
+ * @return the IEntityClass resulting from the classification
+ */
+ IEntityClass reclassifyEntity(IDevice curDevice, Entity entity);
+
+ /**
+ * Once reclassification is complete for a device, this method will be
+ * called. If any entities within the device changed their classification,
+ * it will split into one or more new devices for each of the entities. If
+ * two devices are merged because of a reclassification, then this will be
+ * called on each of the devices, with the same device in the newDevices
+ * collection.
+ *
+ * @param oldDevice
+ * the original device object
+ * @param newDevices
+ * all the new devices derived from the entities of the old
+ * device. If null, the old device was unchanged.
+ */
+ void deviceUpdate(IDevice oldDevice,
+ Collection<? extends IDevice> newDevices);
+
+ /**
+ * Adds a listener to listen for IEntityClassifierServices notifications
+ *
+ * @param listener
+ * The listener that wants the notifications
+ */
+ public void addListener(IEntityClassListener listener);
+}
Code Review / controller.git / blobdiff