opendaylight/adsal/hosttracker/api/src/main/java/org/opendaylight/controller/hosttracker/IfIptoHost.java

   1 /*
   2  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8
   9 package org.opendaylight.controller.hosttracker;
  10
  11 import java.net.InetAddress;
  12 import java.util.List;
  13 import java.util.Set;
  14 import java.util.concurrent.Future;
  15
  16 import org.opendaylight.controller.hosttracker.hostAware.HostNodeConnector;
  17 import org.opendaylight.controller.sal.core.NodeConnector;
  18 import org.opendaylight.controller.sal.utils.Status;
  19
  20 /**
  21  * This interface defines the methods to retrieve information about learned
  22  * Hosts. Also provides methods to statically add/remove Hosts from the local
  23  * database.
  24  *
  25  */
  26
  27 public interface IfIptoHost {
  28     /**
  29      * Applications call this interface methods to determine IP address to MAC
  30      * binding and its connectivity to an OpenFlow switch in term of Node, Port,
  31      * and VLAN. These bindings are learned dynamically as well as can be added
  32      * statically through Northbound APIs. If a binding is unknown, then an ARP
  33      * request is initiated immediately to discover the host.
  34      *
  35      * @param id
  36      *            IP address and Mac Address combination encapsulated in IHostId
  37      *            interface
  38      * @return {@link org.opendaylight.controller.hosttracker.hostAware.HostNodeConnector}
  39      *         Class that contains the Host info such as its MAC address, Switch
  40      *         ID, port, VLAN. If Host is not found, returns NULL
  41      */
  42     public HostNodeConnector hostFind(IHostId id);
  43
  44     /**
  45      * Applications call this interface methods to determine IP address to MAC
  46      * binding and its connectivity to an OpenFlow switch in term of Node, Port,
  47      * and VLAN. These bindings are learned dynamically as well as can be added
  48      * statically through Northbound APIs. If a binding is unknown, then an ARP
  49      * request is initiated immediately to discover the host.
  50      *
  51      * @param addr
  52      *            IP address of the host
  53      * @return {@link org.opendaylight.controller.hosttracker.hostAware.HostNodeConnector}
  54      *         Class that contains the Host info such as its MAC address, Switch
  55      *         ID, port, VLAN. If Host is not found, returns NULL
  56      */
  57     public HostNodeConnector hostFind(InetAddress addr);
  58
  59     /**
  60      * Checks the local Host Database to see if a Host has been learned for a
  61      * given IP address and Mac combination using the HostId.
  62      *
  63      * @param id
  64      *            IP address and Mac Address combination encapsulated in IHostId
  65      *            interface
  66      * @return {@link org.opendaylight.controller.hosttracker.hostAware.HostNodeConnector}
  67      *         Class that contains the Host info such as its MAC address, Switch
  68      *         ID, port, VLAN. If Host is not found, returns NULL
  69      *
  70      */
  71     public HostNodeConnector hostQuery(IHostId id);
  72
  73     /**
  74      * Checks the local Host Database to see if a Host has been learned for a
  75      * given IP address and Mac combination using the HostId.
  76      *
  77      * @param addr
  78      *            IP address of the Host
  79      * @return {@link org.opendaylight.controller.hosttracker.hostAware.HostNodeConnector}
  80      *         Class that contains the Host info such as its MAC address, Switch
  81      *         ID, port, VLAN. If Host is not found, returns NULL
  82      *
  83      */
  84     public HostNodeConnector hostQuery(InetAddress addr);
  85
  86     /**
  87      * Initiates an immediate discovery of the Host for a given Host id. This
  88      * provides for the calling applications to block on the host discovery.
  89      *
  90      * @param id
  91      *            IP address and Mac Address combination encapsulated in IHostId
  92      *            interface
  93      * @return Future
  94      *         {@link org.opendaylight.controller.hosttracker.HostTrackerCallable}
  95      */
  96     public Future<HostNodeConnector> discoverHost(IHostId id);
  97
  98     /**
  99      * Initiates an immediate discovery of the Host for a given Host id. This
 100      * provides for the calling applications to block on the host discovery.
 101      *
 102      * @param addr
 103      *            IP address of the host
 104      * @return Future
 105      *         {@link org.opendaylight.controller.hosttracker.HostTrackerCallable}
 106      */
 107     public Future<HostNodeConnector> discoverHost(InetAddress addr);
 108
 109     /**
 110      * Returns the Network Hierarchy for a given Host. This API is typically
 111      * used by applications like Hadoop for Rack Awareness functionality.
 112      *
 113      * @param id
 114      *            IP address and Mac Address combination encapsulated in IHostId
 115      *            interface
 116      * @return List of String ArrayList containing the Hierarchies.
 117      */
 118     public List<List<String>> getHostNetworkHierarchy(IHostId id);
 119
 120     /**
 121      * Returns the Network Hierarchy for a given Host. This API is typically
 122      * used by applications like Hadoop for Rack Awareness functionality.
 123      *
 124      * @param addr
 125      *            IP address of the host
 126      * @return List of String ArrayList containing the Hierarchies.
 127      */
 128     public List<List<String>> getHostNetworkHierarchy(InetAddress addr);
 129
 130     /**
 131      * Returns all the the Hosts either learned dynamically or added statically
 132      * via Northbound APIs.
 133      *
 134      * @return Set of
 135      *         {@link org.opendaylight.controller.hosttracker.hostAware.HostNodeConnector}
 136      *         . Class that contains the Host info such as its MAC address,
 137      *         Switch ID, port, VLAN.
 138      */
 139     public Set<HostNodeConnector> getAllHosts();
 140
 141     /**
 142      * Returns all the "Active Hosts" learned "Statically" via Northbound APIs.
 143      * These Hosts are categorized as "Active" because the Switch and Port they
 144      * are connected to, are in up state.
 145      *
 146      * @return Set of
 147      *         {@link org.opendaylight.controller.hosttracker.hostAware.HostNodeConnector}
 148      *         . Class that contains the Host info such as MAC address, Switch
 149      *         ID, port, VLAN. If Host is not found, returns NULL
 150      */
 151     public Set<HostNodeConnector> getActiveStaticHosts();
 152
 153     /**
 154      * Returns all the "Inactive Hosts" learned "Statically" via Northbound
 155      * APIs. These Hosts are categorized as "Inactive" because either the Switch
 156      * or the Port they are connected to, is in down state.
 157      *
 158      * @return Set of HostNodeConnector
 159      *         {@link org.opendaylight.controller.hosttracker.hostAware.HostNodeConnector}
 160      *         . HostNodeConnector is Class that contains the Host info such as
 161      *         its MAC address, OpenFlowNode ID, port, VLAN.
 162      */
 163     public Set<HostNodeConnector> getInactiveStaticHosts();
 164
 165     /**
 166      * Hosts can be learned dynamically or added statically. This method allows
 167      * the addition of a Host to the local database statically.
 168      *
 169      * @param networkAddress
 170      *            IP Address of the Host
 171      * @param dataLayerAddress
 172      *            MAC Address of the Host
 173      * @param nc
 174      *            NodeConnector to which the host is attached
 175      * @param vlan
 176      *            VLAN the host belongs to (null or empty for no vlan)
 177      * @return The status object as described in {@code Status} indicating the
 178      *         result of this action.
 179      */
 180     public Status addStaticHost(String networkAddress, String dataLayerAddress, NodeConnector nc, String vlan);
 181
 182     /**
 183      * Allows the deletion of statically learned Host
 184      *
 185      * @param networkAddress
 186      * @return The status object as described in {@code Status} indicating the
 187      *         result of this action.
 188      */
 189     public Status removeStaticHost(String networkAddress);
 190
 191     /**
 192      * Allows the deletion of statically learned Host
 193      *
 194      * @param networkAddress
 195      * @param macAddress
 196      * @return The status object as described in {@code Status} indicating the
 197      *         result of this action.
 198      */
 199     public Status removeStaticHostUsingIPAndMac(String networkAddress, String macAddress);
 200 }