manuals/developer-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 . Basic API and DataType;
   9 . How to use customized service implementations.
  10
  11 === Adding ALTO Projects as Dependencies ===
  12
  13 Most ALTO packages can be added as dependencies in Maven projects by putting the
  14 following code in the _pom.xml_ file.
  15
  16     <dependency>
  17         <groupId>org.opendaylight.alto</groupId>
  18         <artifactId>${THE_NAME_OF_THE_PACKAGE_YOU_NEED}</artifactId>
  19         <version>${ALTO_VERSION}</version>
  20     </dependency>
  21
  22 The current stable version for ALTO is `0.2.0-Beryllium`.
  23
  24 === Putting/Fetching data from ALTO ===
  25
  26 ==== Using RESTful API ====
  27
  28 There are two kinds of RESTful APIs for ALTO: the one provided by
  29 `alto-northbound` which follows the formats defined in
  30 link:https://tools.ietf.org/html/rfc7285[RFC 7285], and the one provided by
  31 RESTCONF whose format is defined by the YANG model proposed in
  32 link:https://tools.ietf.org/html/draft-shi-alto-yang-model-03[this draft].
  33
  34 One way to get the URLs for the resources from `alto-northbound` is to visit
  35 the IRD service first where there is a `uri` field for every entry. However, the
  36 IRD service is not yet implemented so currently the developers have to construct
  37 the URLs themselves. The base URL is `/alto` and below is a list
  38 of the specific paths defined in `alto-core/standard-northbound-route`
  39 using Jersey `@Path` annotation:
  40
  41 * `/ird/{rid}`: the path to access __IRD__ services;
  42 * `/networkmap/{rid}[/{tag}]`: the path to access __Network Map__ and __Filtered Network Map__ services;
  43 * `/costmap/{rid}[/{tag}[/{mode}/{metric}]]`: the path to access __Cost Map__ and __Filtered Cost Map__ services;
  44 * `/endpointprop`: the path to access __Endpoint Property__ services;
  45 * `/endpointcost`: the path to access __Endpoint Cost__ services.
  46
  47 NOTE: The segments in brackets are optional.
  48
  49 If you want to fetch the data using RESTCONF, it is highly recommended to take a
  50 look at the `apidoc` page (http://{CONTROLLER_IP}:8181/apidoc/explorer/index.html)
  51 after installing the `odl-alto-release` feature in karaf.
  52
  53 It is also worth pointing out that `alto-northbound` only supports `GET` and
  54 `POST` operations so it is impossible to manipulate the data through its RESTful
  55 APIs. To modify the data, use `PUT` and `DELETE` methods with RESTCONF.
  56
  57 NOTE: The current implementation uses the `configuration` data store and that
  58 enables the developers to modify the data directly through RESTCONF. In the future this
  59 approach might be disabled in the core packages of ALTO but may still be
  60 available as an extension.
  61
  62 ==== Using MD-SAL ====
  63
  64 You can also fetch data from the datastore directly.
  65
  66 First you must get the access to the datastore by registering your module with
  67 a data broker.
  68
  69 Then an `InstanceIdentifier` must be created. Here is an example of how to build
  70 an `InstanceIdentifier` for a _network map_:
  71
  72   import org.opendaylight...alto...Resources;
  73   import org.opendaylight...alto...resources.NetworkMaps;
  74   import org.opendaylight...alto...resources.network.maps.NetworkMap;
  75   import org.opendaylight...alto...resources.network.maps.NetworkMapKey;
  76   ...
  77   protected
  78   InstanceIdentifier<NetworkMap> getNetworkMapIID(String resource_id) {
  79     ResourceId rid = ResourceId.getDefaultInstance(resource_id);
  80     NetworkMapKey key = new NetworkMapKey(rid);
  81     InstanceIdentifier<NetworkMap> iid = null;
  82     iid = InstanceIdentifier.builder(Resources.class)
  83                             .child(NetworkMaps.class)
  84                             .child(NetworkMap.class, key)
  85                             .build();
  86     return iid;
  87   }
  88   ...
  89
  90 With the `InstanceIdentifier` you can use `ReadOnlyTransaction`,
  91 `WriteTransaction` and `ReadWriteTransaction` to manipulate the data
  92 accordingly. The `simple-impl` package, which provides some of the AD-SAL APIs
  93 mentioned above, is using this method to get data from the datastore and then
  94 convert them into RFC7285-compatible objects.
  95
  96 === Basic API and DataType
  97
  98 .. alto-basic-types: Defines basic types of ALTO protocol.
  99
 100 .. alto-service-model-api: Includes the YANG models for the five basic ALTO services defined in link:https://tools.ietf.org/html/rfc7285[RFC 7285].
 101
 102 .. alto-resourcepool: Manages the meta data of each ALTO service, including capabilities and versions.
 103
 104 .. alto-northbound: Provides the root of RFC7285-compatible services at http://localhost:8080/alto.
 105
 106 .. alto-northbound-route: Provides the root of the network map resources at http://localhost:8080/alto/networkmap/.
 107
 108 === How to customize service
 109
 110 ==== Define new service API
 111
 112 Add a new module in `alto-core/standard-service-models`. For example, we named our
 113 service model module as `model-example`.
 114
 115 ==== Implement service RPC
 116
 117 Add a new module in `alto-basic` to implement a service RPC in `alto-core`.
 118
 119 Currently `alto-core/standard-service-models/model-base` has defined a template of the service RPC.
 120 You can define your own RPC using `augment` in YANG. Here is an example in `alto-simpleird`.
 121
 122 [source,yang]
 123 include::augment.yang[]
 124
 125 ==== Register northbound route
 126
 127 If necessary, you can add a northbound route module in `alto-core/standard-northbound-routes`.