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