docs/developer-guide/neutron-northbound.rst

   1 Neutron Northbound
   2 ==================
   3
   4 How to add new API support
   5 --------------------------
   6
   7 OpenStack Neutron is a moving target. It is continuously adding new
   8 features as new rest APIs. Here is a basic step to add new API support:
   9
  10 In the Neutron Northbound project:
  11
  12 -  Add new YANG model for it under ``neutron/model/src/main/yang`` and
  13    ``update neutron.yang``
  14
  15 -  Add northbound API for it, and neutron-spi
  16
  17    -  Implement ``Neutron<New API>Request.java`` and
  18       ``Neutron<New API>Norhtbound.java`` under
  19       ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/``
  20
  21    -  Implement ``INeutron<New API>CRUD.java`` and new data structure if
  22       any under
  23       ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/``
  24
  25    -  update
  26       ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/NeutronCRUDInterfaces.java``
  27       to wire new CRUD interface
  28
  29    -  Add unit tests, ``Neutron<New structure>JAXBTest.java`` under
  30       ``neutron/neutron-spi/src/test/java/org/opendaylight/neutron/spi/``
  31
  32 -  update
  33    ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/NeutronNorthboundRSApplication.java``
  34    to wire new northbound api to ``RSApplication``
  35
  36 -  Add transcriber, ``Neutron<New API>Interface.java`` under
  37    ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/``
  38
  39 -  update
  40    ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/NeutronTranscriberProvider.java``
  41    to wire a new transcriber
  42
  43    -  Add integration tests ``Neutron<New API>Tests.java`` under
  44       ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/``
  45
  46    -  update
  47       ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/ITNeutronE2E.java``
  48       to run a newly added tests.
  49
  50 In OpenStack networking-odl
  51
  52 -  Add new driver (or plugin) for new API with tests.
  53
  54 In a southbound Neutron Provider
  55
  56 -  implement actual backend to realize those new API by listening
  57    related YANG models.
  58
  59 How to write transcriber
  60 ------------------------
  61
  62 For each Neutron data object, there is an ``Neutron*Interface`` defined
  63 within the transcriber artifact that will write that object to the
  64 MD-SAL configuration datastore.
  65
  66 All ``Neutron*Interface`` extend ``AbstractNeutronInterface``, in which
  67 two methods are defined:
  68
  69 -  one takes the Neutron object as input, and will create a data object
  70    from it.
  71
  72 -  one takes an uuid as input, and will create a data object containing
  73    the uuid.
  74
  75 ::
  76
  77     protected abstract T toMd(S neutronObject);
  78     protected abstract T toMd(String uuid);
  79
  80 In addition the ``AbstractNeutronInterface`` class provides several
  81 other helper methods (``addMd``, ``updateMd``, ``removeMd``), which
  82 handle the actual writing to the configuration datastore.
  83
  84 The semantics of the ``toMD()`` methods
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86
  87 Each of the Neutron YANG models defines structures containing data.
  88 Further each YANG-modeled structure has it own builder. A particular
  89 ``toMD()`` method instantiates an instance of the correct builder, fills
  90 in the properties of the builder from the corresponding values of the
  91 Neutron object and then creates the YANG-modeled structures via the
  92 ``build()`` method.
  93
  94 As an example, one of the ``toMD`` code for Neutron Networks is
  95 presented below:
  96
  97 ::
  98
  99     protected Network toMd(NeutronNetwork network) {
 100         NetworkBuilder networkBuilder = new NetworkBuilder();
 101         networkBuilder.setAdminStateUp(network.getAdminStateUp());
 102         if (network.getNetworkName() != null) {
 103             networkBuilder.setName(network.getNetworkName());
 104         }
 105         if (network.getShared() != null) {
 106             networkBuilder.setShared(network.getShared());
 107         }
 108         if (network.getStatus() != null) {
 109             networkBuilder.setStatus(network.getStatus());
 110         }
 111         if (network.getSubnets() != null) {
 112             List<Uuid> subnets = new ArrayList<Uuid>();
 113             for( String subnet : network.getSubnets()) {
 114                 subnets.add(toUuid(subnet));
 115             }
 116             networkBuilder.setSubnets(subnets);
 117         }
 118         if (network.getTenantID() != null) {
 119             networkBuilder.setTenantId(toUuid(network.getTenantID()));
 120         }
 121         if (network.getNetworkUUID() != null) {
 122             networkBuilder.setUuid(toUuid(network.getNetworkUUID()));
 123         } else {
 124             logger.warn("Attempting to write neutron network without UUID");
 125         }
 126         return networkBuilder.build();
 127     }
 128