manuals/user-guide/src/main/asciidoc/alto/alto-developer-guide.adoc

   1 == ALTO Developer Guide ==
   2
   3 === Overview ===
   4 The topics of this guide are:
   5
   6 . How to add alto projects as dependencies;
   7 . How to put/fetch data from ALTO;
   8 . How to use customized service implementations.
   9
  10 === Adding ALTO Projects as Dependencies ===
  11
  12 Most ALTO packages can be added as dependencies in Maven projects by putting the
  13 following code in the _pom.xml_ file.
  14
  15     <dependency>
  16         <groupId>org.opendaylight.alto</groupId>
  17         <artifactId>${THE_NAME_OF_THE_PACKAGE_YOU_NEED}</artifactId>
  18         <version>${ALTO_VERSION}</version>
  19     </dependency>
  20
  21 The current stable version for ALTO is `0.1.0-Lithium`.
  22
  23 === Putting/Fetching data from ALTO ===
  24
  25 ==== Using RESTful API ====
  26 There are two kinds of RESTful APIs for ALTO: the one provided by
  27 `alto-northbound` which follows the formats defined in
  28 link:https://tools.ietf.org/html/rfc7285[RFC 7285], and the one provided by
  29 RESTCONF whose format is defined by the YANG model proposed in
  30 link:https://tools.ietf.org/html/draft-shi-alto-yang-model-03[this draft].
  31
  32 One way to get the URLs for the resources from `alto-northbound` is to visit
  33 the IRD service first where there is a `uri` field for every entry. However, the
  34 IRD service is not yet implemented so currently the developers have to construct
  35 the URLs themselves. The base URL is `/controller/nb/v2/alto` and below is a list
  36 of the specific paths defined in `AltoNorthbound.java` in `alto-northbound`
  37 using Jersey `@Path` annotation:
  38
  39 * `/ird/{rid}`: the path to access __IRD__ services;
  40 * `/networkmap/{rid}[/{tag}]`: the path to access __Network Map__ services;
  41 * `/costmap/{rid}[/{tag}[/{mode}/{metric}]]`: the path to access __Cost Map__
  42 services;
  43 * `/filtered/networkmap/{rid}[/{tag}]`: the path to access __Filtered Network Map__
  44 services;
  45 * `/filtered/costmap/{rid}[/{tag}]`: the path to access __Filtered Cost Map__
  46 services;
  47 * `/endpointprop/lookup/{rid}[/{tag}]`: the path to access __Endpoint Property__
  48 services;
  49 * `/endpointcost/lookup/{rid}[/{tag}]`: the path to access __Endpoint Cost__
  50 services.
  51
  52 NOTE: The segments in brackets are optional.
  53
  54 If you want to fetch the data using RESTCONF, it is highly recommended to take a
  55 look at the `apidoc` page
  56 (http://{CONTROLLER_IP}:8181/apidoc/explorer/index.html)
  57 after installing the `alto-model` feature in karaf.
  58
  59 It is also worth pointing out that `alto-northbound` only supports `GET` and
  60 `POST` operations so it is impossible to manipulate the data through its RESTful
  61 APIs. To modify the data, use `PUT` and `DELETE` methods with RESTCONF.
  62
  63 NOTE: The current implementation uses the `configuration` data store and that
  64 enables the developers to modify the data directly through RESTCONF. In the future this
  65 approach might be disabled in the core packages of ALTO but may still be
  66 available as an extension.
  67
  68 ==== Using AD-SAL ====
  69 Five interfaces are defined in package `service-api-rfc7285`. Follow the steps
  70 below to use them:
  71
  72 . Determine the required service interface: `IRDService`, `NetworkMapService`,
  73 `CostMapService`, `EndpointPropertyService` or `EndpointCostService`;
  74 . Use the `ServiceHelper` to get the instance;
  75 . Call the corresponding methods with appropriate parameters.
  76
  77 ==== Using MD-SAL ====
  78 You can also fetch data from the data store directly.
  79
  80 First you must get the access to the data store by registering your module with
  81 a data broker.
  82
  83 Then an `InstanceIdentifier` must be created. Here is an example of how to build
  84 an `InstanceIdentifier` for a _network map_:
  85
  86   import org.opendaylight...alto...Resources;
  87   import org.opendaylight...alto...resources.NetworkMaps;
  88   import org.opendaylight...alto...resources.network.maps.NetworkMap;
  89   import org.opendaylight...alto...resources.network.maps.NetworkMapKey;
  90   ...
  91   protected
  92   InstanceIdentifier<NetworkMap> getNetworkMapIID(String resource_id) {
  93     ResourceId rid = ResourceId.getDefaultInstance(resource_id);
  94     NetworkMapKey key = new NetworkMapKey(rid);
  95     InstanceIdentifier<NetworkMap> iid = null;
  96     iid = InstanceIdentifier.builder(Resources.class)
  97                             .child(NetworkMaps.class)
  98                             .child(NetworkMap.class, key)
  99                             .build();
 100     return iid;
 101   }
 102   ...
 103
 104 With the `InstanceIdentifier` you can use `ReadOnlyTransaction`,
 105 `WriteTransaction` and `ReadWriteTransaction` to manipulate the data
 106 accordingly. The `simple-impl` package, which provides some of the AD-SAL APIs
 107 mentioned above, is using this method to get data from the data store and then
 108 convert them into RFC7285-compatible objects.
 109
 110 === Providing Customized Implementation ===
 111
 112 Currently it is very simple to provide a customized network map, the
 113 only thing you have to do is to put the data into the data store. Cost maps are
 114 more complex since there are no classes for the cost values by default, you have
 115 to define it using `augment` in YANG. Here is an example in `alto-hosttracker`.
 116
 117 [source,yang]
 118 include::augment.yang[]