graph/graph-api/src/main/java/org/opendaylight/graph/ConnectedGraph.java

   1 /*
   2  * Copyright (c) 2019 Orange.  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 package org.opendaylight.graph;
   9
  10 import java.util.List;
  11 import org.eclipse.jdt.annotation.NonNull;
  12 import org.opendaylight.yang.gen.v1.urn.ietf.params.xml.ns.yang.ietf.inet.types.rev130715.IpAddress;
  13 import org.opendaylight.yang.gen.v1.urn.ietf.params.xml.ns.yang.ietf.inet.types.rev130715.IpPrefix;
  14 import org.opendaylight.yang.gen.v1.urn.ietf.params.xml.ns.yang.ietf.inet.types.rev130715.Ipv4Address;
  15 import org.opendaylight.yang.gen.v1.urn.ietf.params.xml.ns.yang.ietf.inet.types.rev130715.Ipv6Address;
  16 import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.graph.rev220720.graph.topology.Graph;
  17 import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.graph.rev220720.graph.topology.graph.Edge;
  18 import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.graph.rev220720.graph.topology.graph.EdgeKey;
  19 import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.graph.rev220720.graph.topology.graph.Prefix;
  20 import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.graph.rev220720.graph.topology.graph.Vertex;
  21 import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.graph.rev220720.graph.topology.graph.VertexKey;
  22 import org.opendaylight.yang.gen.v1.urn.tbd.params.xml.ns.yang.network.topology.rev131021.network.topology.TopologyKey;
  23
  24 /**
  25  * Connected Graph class is the connected version of the Graph class from the graph yang model.
  26  *
  27  * <p>
  28  * Connected Graph is composed by Connected Vertex, Connected Edges and Prefix. It models Unidirectional Connected
  29  * Graph (see graph theory). So, Edge and Connected Edge are unidirectional, thus to connect bi-directionally 2 vertices
  30  * Va and Vb, it is necessary to setup 2 edges: Va to Vb and Vb to Va.
  31  * <pre>
  32  * {@code
  33  *        --------------     ---------------------------    --------------
  34  *        | Connected  |---->| Connected Edge Va to Vb |--->| Connected  |
  35  *   ---->|  Vertex    |     ---------------------------    |  Vertex    |---->
  36  *        |            |                                    |            |
  37  *        | - Key (Va) |                                    | - Key (Vb) |
  38  *   <----| - Vertex   |     ---------------------------    | - Vertex   |<----
  39  *        |            |<----| Connected Edge Vb to Va |<---|            |
  40  *        --------------     ---------------------------    --------------
  41  * }
  42  * </pre>
  43  *
  44  * @author Olivier Dugeon
  45  * @author Philippe Niger
  46  */
  47 public interface ConnectedGraph {
  48
  49     /**
  50      * Returns the Graph associated to this Connected Graph.
  51      *
  52      * @return Graph
  53      */
  54     Graph getGraph();
  55
  56     /**
  57      * Returns the list of Connected Vertices that form this graph.
  58      *
  59      * @return list of Connected Vertices
  60      */
  61     List<ConnectedVertex> getVertices();
  62
  63     /**
  64      * Returns the Vertex associated to the given key.
  65      *
  66      * @param key Unique Vertex Identifier
  67      * @return Vertex or null if there is no Vertex associated to the given key in this graph
  68      */
  69     ConnectedVertex getConnectedVertex(@NonNull Long key);
  70
  71     /**
  72      * Returns the Vertex associated to the given IP address.
  73      *
  74      * @param address IP address of the Loopback of the Vertex
  75      *
  76      * @return Vertex or null if there is no Vertex associated to the given IP address in this graph
  77      */
  78     ConnectedVertex getConnectedVertex(IpAddress address);
  79
  80     /**
  81      * Add Vertex in the Connected Graph. This action will automatically create the associated Connected Vertex and
  82      * update the Graph in the DataStore.
  83      *
  84      * @param vertex Vertex to be added
  85      *
  86      * @return Connected Vertex associated to the given Vertex
  87      */
  88     ConnectedVertex addVertex(Vertex vertex);
  89
  90     /**
  91      * Remove the Vertex in the Connected Graph. This action will automatically remove the associated Connected Vertex
  92      * and update the Graph in the DataStore.
  93      *
  94      * @param vertexKey Unique Vertex Identifier
  95      */
  96     void deleteVertex(VertexKey vertexKey);
  97
  98     /**
  99      * Returns the number of Vertices in the graph.
 100      *
 101      * @return number of vertices
 102      */
 103     int getVerticesSize();
 104
 105     /**
 106      * Returns the list of Connected Edges that form this graph.
 107      *
 108      * @return list of Connected Edges
 109      */
 110     List<ConnectedEdge> getEdges();
 111
 112     /**
 113      * Returns the Edge associated to the given key.
 114      *
 115      * @param key Unique Edge Identifier
 116      * @return Edge or null if there is no Edge associated to the given key in this graph
 117      */
 118     ConnectedEdge getConnectedEdge(@NonNull Long key);
 119
 120     /**
 121      * Returns the Edge associated to the given IPv4 address.
 122      *
 123      * @param address IPv4 address of the Edge
 124      *
 125      * @return Edge or null if there is no Edge associated to the given IP address in this graph
 126      */
 127     ConnectedEdge getConnectedEdge(Ipv4Address address);
 128
 129     /**
 130      * Returns the Edge associated to the given IPv6 address.
 131      *
 132      * @param address IPv6 address of the Edge
 133      *
 134      * @return Edge or null if there is no Edge associated to the given IP address in this graph
 135      */
 136     ConnectedEdge getConnectedEdge(Ipv6Address address);
 137
 138     /**
 139      * Returns the Edge associated to the given IP address.
 140      *
 141      * @param address IP address of the Edge
 142      *
 143      * @return Edge or null if there is no Edge associated to the given IP address in this graph
 144      */
 145     ConnectedEdge getConnectedEdge(IpAddress address);
 146
 147     /**
 148      * Add Edge in the Connected Graph. This action will automatically create the associated Connected Edge and
 149      * update the Graph in the DataStore.
 150      *
 151      * @param edge Edge to be added
 152      *
 153      * @return Connected Edge associated to the given Edge
 154      */
 155     ConnectedEdge addEdge(Edge edge);
 156
 157     /**
 158      * Remove the Edge in the Connected Graph. This action will automatically remove the associated Connected Edge
 159      * and update the Graph in the DataStore.
 160      *
 161      * @param edgeKey Unique Edge Identifier
 162      */
 163     void deleteEdge(EdgeKey edgeKey);
 164
 165     /**
 166      * Returns the number of Edges in the graph.
 167      *
 168      * @return number of edges
 169      */
 170     int getEdgesSize();
 171
 172     /**
 173      * Returns the list of Prefix that are stored in this graph.
 174      *
 175      * @return list of Prefix
 176      */
 177     List<Prefix> getPrefixes();
 178
 179     /**
 180      * Returns the Prefix associated to the given IP prefix.
 181      *
 182      * @param ippfx IPv4 or IPv6 prefix
 183      *
 184      * @return Prefix that match the given IPv4 or IPv6 prefix
 185      */
 186     Prefix getPrefix(IpPrefix ippfx);
 187
 188     /**
 189      * Add Prefix in the Connected Graph. This action will automatically update the Graph in the DataStore.
 190      *
 191      * @param prefix Prefix to be added
 192      *
 193      */
 194     void addPrefix(Prefix prefix);
 195
 196     /**
 197      * Remove the Prefix in the Connected Graph. This action will automatically update the Graph in the DataStore.
 198      *
 199      * @param ippfx IPv4 or IPv6 prefix
 200      */
 201     void deletePrefix(IpPrefix ippfx);
 202
 203     /**
 204      * Clear the Connected Graph by removing all Vertices, Edges and Prefixes. This also remove the associated Graph
 205      * in the Datastore.
 206      *
 207      */
 208     void clear();
 209
 210     /**
 211      * Returns the summary of the graph characteristics: number of Vertices, Edges and Prefix.
 212      *
 213      * @return characteristics of the Graph as a string
 214      */
 215     String getSummary();
 216
 217     /**
 218      * Register a trigger that is executed when a problem occurs on a Vertex or a Edge within the Connected Graph.
 219      *
 220      * @param trigger   Trigger to be registered
 221      * @param key       Topology Key Identifier
 222      *
 223      * @return          True if registration is done, false otherwise
 224      */
 225     boolean registerTrigger(ConnectedGraphTrigger trigger, TopologyKey key);
 226
 227     /**
 228      * Un-register a trigger that is already registered on the Connected Graph.
 229      *
 230      * @param trigger   Trigger to be unregistered
 231      * @param key       Topology Key Identifier
 232      *
 233      * @return          True if un-registration is done, false otherwise
 234      */
 235     boolean unRegisterTrigger(ConnectedGraphTrigger trigger, TopologyKey key);
 236 }