manuals/developer-guide/src/main/asciidoc/neutron/neutron.adoc

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