--- /dev/null
+ALTO Developer Guide
+====================
+
+Overview
+--------
+
+The topics of this guide are:
+
+1. How to add alto projects as dependencies;
+
+2. How to put/fetch data from ALTO;
+
+3. Basic API and DataType;
+
+4. How to use customized service implementations.
+
+Adding ALTO Projects as Dependencies
+------------------------------------
+
+Most ALTO packages can be added as dependencies in Maven projects by
+putting the following code in the *pom.xml* file.
+
+::
+
+ <dependency>
+ <groupId>org.opendaylight.alto</groupId>
+ <artifactId>${THE_NAME_OF_THE_PACKAGE_YOU_NEED}</artifactId>
+ <version>${ALTO_VERSION}</version>
+ </dependency>
+
+The current stable version for ALTO is ``0.3.0-Boron``.
+
+Putting/Fetching data from ALTO
+-------------------------------
+
+Using RESTful API
+~~~~~~~~~~~~~~~~~
+
+There are two kinds of RESTful APIs for ALTO: the one provided by
+``alto-northbound`` which follows the formats defined in `RFC
+7285 <https://tools.ietf.org/html/rfc7285>`__, and the one provided by
+RESTCONF whose format is defined by the YANG model proposed in `this
+draft <https://tools.ietf.org/html/draft-shi-alto-yang-model-03>`__.
+
+One way to get the URLs for the resources from ``alto-northbound`` is to
+visit the IRD service first where there is a ``uri`` field for every
+entry. However, the IRD service is not yet implemented so currently the
+developers have to construct the URLs themselves. The base URL is
+``/alto`` and below is a list of the specific paths defined in
+``alto-core/standard-northbound-route`` using Jersey ``@Path``
+annotation:
+
+- ``/ird/{rid}``: the path to access *IRD* services;
+
+- ``/networkmap/{rid}[/{tag}]``: the path to access *Network Map* and
+ *Filtered Network Map* services;
+
+- ``/costmap/{rid}[/{tag}[/{mode}/{metric}]]``: the path to access
+ *Cost Map* and *Filtered Cost Map* services;
+
+- ``/endpointprop``: the path to access *Endpoint Property* services;
+
+- ``/endpointcost``: the path to access *Endpoint Cost* services.
+
+.. note::
+
+ The segments in brackets are optional.
+
+If you want to fetch the data using RESTCONF, it is highly recommended
+to take a look at the ``apidoc`` page
+(`http://{controller\_ip}:8181/apidoc/explorer/index.html <http://{controller_ip}:8181/apidoc/explorer/index.html>`__)
+after installing the ``odl-alto-release`` feature in karaf.
+
+It is also worth pointing out that ``alto-northbound`` only supports
+``GET`` and ``POST`` operations so it is impossible to manipulate the
+data through its RESTful APIs. To modify the data, use ``PUT`` and
+``DELETE`` methods with RESTCONF.
+
+.. note::
+
+ The current implementation uses the ``configuration`` data store and
+ that enables the developers to modify the data directly through
+ RESTCONF. In the future this approach might be disabled in the core
+ packages of ALTO but may still be available as an extension.
+
+Using MD-SAL
+~~~~~~~~~~~~
+
+You can also fetch data from the datastore directly.
+
+First you must get the access to the datastore by registering your
+module with a data broker.
+
+Then an ``InstanceIdentifier`` must be created. Here is an example of
+how to build an ``InstanceIdentifier`` for a *network map*:
+
+::
+
+ import org.opendaylight...alto...Resources;
+ import org.opendaylight...alto...resources.NetworkMaps;
+ import org.opendaylight...alto...resources.network.maps.NetworkMap;
+ import org.opendaylight...alto...resources.network.maps.NetworkMapKey;
+ ...
+ protected
+ InstanceIdentifier<NetworkMap> getNetworkMapIID(String resource_id) {
+ ResourceId rid = ResourceId.getDefaultInstance(resource_id);
+ NetworkMapKey key = new NetworkMapKey(rid);
+ InstanceIdentifier<NetworkMap> iid = null;
+ iid = InstanceIdentifier.builder(Resources.class)
+ .child(NetworkMaps.class)
+ .child(NetworkMap.class, key)
+ .build();
+ return iid;
+ }
+ ...
+
+With the ``InstanceIdentifier`` you can use ``ReadOnlyTransaction``,
+``WriteTransaction`` and ``ReadWriteTransaction`` to manipulate the data
+accordingly. The ``simple-impl`` package, which provides some of the
+AD-SAL APIs mentioned above, is using this method to get data from the
+datastore and then convert them into RFC7285-compatible objects.
+
+Basic API and DataType
+----------------------
+
+a. alto-basic-types: Defines basic types of ALTO protocol.
+
+b. alto-service-model-api: Includes the YANG models for the five basic
+ ALTO services defined in `RFC
+ 7285 <https://tools.ietf.org/html/rfc7285>`__.
+
+c. alto-resourcepool: Manages the meta data of each ALTO service,
+ including capabilities and versions.
+
+d. alto-northbound: Provides the root of RFC7285-compatible services at
+ http://localhost:8080/alto.
+
+e. alto-northbound-route: Provides the root of the network map resources
+ at http://localhost:8080/alto/networkmap/.
+
+How to customize service
+------------------------
+
+Define new service API
+~~~~~~~~~~~~~~~~~~~~~~
+
+Add a new module in ``alto-core/standard-service-models``. For example,
+we named our service model module as ``model-example``.
+
+Implement service RPC
+~~~~~~~~~~~~~~~~~~~~~
+
+Add a new module in ``alto-basic`` to implement a service RPC in
+``alto-core``.
+
+Currently ``alto-core/standard-service-models/model-base`` has defined a
+template of the service RPC. You can define your own RPC using
+``augment`` in YANG. Here is an example in ``alto-simpleird``.
+
+.. code:: yang
+
+ grouping "alto-ird-request" {
+ container "ird-request" {
+ }
+ }
+ grouping "alto-ird-response" {
+ container "ird" {
+ container "meta" {
+ }
+ list "resource" {
+ key "resource-id";
+ leaf "resource-id" {
+ type "alto-types:resource-id";
+ }
+ }
+ }
+ }
+ augment "/base:query/base:input/base:request" {
+ case "ird-request-data" {
+ uses "alto-ird-request";
+ }
+ }
+ augment "/base:query/base:output/base:response" {
+ case "ird-response-data" {
+ uses "alto-ird-response";
+ }
+ }
+
+Register northbound route
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If necessary, you can add a northbound route module in
+``alto-core/standard-northbound-routes``.
+
== ALTO Developer Guide ==
-=== Overview ===
-The topics of this guide are:
-
-. How to add alto projects as dependencies;
-. How to put/fetch data from ALTO;
-. Basic API and DataType;
-. How to use customized service implementations.
-
-=== Adding ALTO Projects as Dependencies ===
-
-Most ALTO packages can be added as dependencies in Maven projects by putting the
-following code in the _pom.xml_ file.
-
- <dependency>
- <groupId>org.opendaylight.alto</groupId>
- <artifactId>${THE_NAME_OF_THE_PACKAGE_YOU_NEED}</artifactId>
- <version>${ALTO_VERSION}</version>
- </dependency>
-
-The current stable version for ALTO is `0.3.0-Boron`.
-
-=== Putting/Fetching data from ALTO ===
-
-==== Using RESTful API ====
-
-There are two kinds of RESTful APIs for ALTO: the one provided by
-`alto-northbound` which follows the formats defined in
-link:https://tools.ietf.org/html/rfc7285[RFC 7285], and the one provided by
-RESTCONF whose format is defined by the YANG model proposed in
-link:https://tools.ietf.org/html/draft-shi-alto-yang-model-03[this draft].
-
-One way to get the URLs for the resources from `alto-northbound` is to visit
-the IRD service first where there is a `uri` field for every entry. However, the
-IRD service is not yet implemented so currently the developers have to construct
-the URLs themselves. The base URL is `/alto` and below is a list
-of the specific paths defined in `alto-core/standard-northbound-route`
-using Jersey `@Path` annotation:
-
-* `/ird/{rid}`: the path to access __IRD__ services;
-* `/networkmap/{rid}[/{tag}]`: the path to access __Network Map__ and __Filtered Network Map__ services;
-* `/costmap/{rid}[/{tag}[/{mode}/{metric}]]`: the path to access __Cost Map__ and __Filtered Cost Map__ services;
-* `/endpointprop`: the path to access __Endpoint Property__ services;
-* `/endpointcost`: the path to access __Endpoint Cost__ services.
-
-NOTE: The segments in brackets are optional.
-
-If you want to fetch the data using RESTCONF, it is highly recommended to take a
-look at the `apidoc` page (http://{CONTROLLER_IP}:8181/apidoc/explorer/index.html)
-after installing the `odl-alto-release` feature in karaf.
-
-It is also worth pointing out that `alto-northbound` only supports `GET` and
-`POST` operations so it is impossible to manipulate the data through its RESTful
-APIs. To modify the data, use `PUT` and `DELETE` methods with RESTCONF.
-
-NOTE: The current implementation uses the `configuration` data store and that
-enables the developers to modify the data directly through RESTCONF. In the future this
-approach might be disabled in the core packages of ALTO but may still be
-available as an extension.
-
-==== Using MD-SAL ====
-
-You can also fetch data from the datastore directly.
-
-First you must get the access to the datastore by registering your module with
-a data broker.
-
-Then an `InstanceIdentifier` must be created. Here is an example of how to build
-an `InstanceIdentifier` for a _network map_:
-
- import org.opendaylight...alto...Resources;
- import org.opendaylight...alto...resources.NetworkMaps;
- import org.opendaylight...alto...resources.network.maps.NetworkMap;
- import org.opendaylight...alto...resources.network.maps.NetworkMapKey;
- ...
- protected
- InstanceIdentifier<NetworkMap> getNetworkMapIID(String resource_id) {
- ResourceId rid = ResourceId.getDefaultInstance(resource_id);
- NetworkMapKey key = new NetworkMapKey(rid);
- InstanceIdentifier<NetworkMap> iid = null;
- iid = InstanceIdentifier.builder(Resources.class)
- .child(NetworkMaps.class)
- .child(NetworkMap.class, key)
- .build();
- return iid;
- }
- ...
-
-With the `InstanceIdentifier` you can use `ReadOnlyTransaction`,
-`WriteTransaction` and `ReadWriteTransaction` to manipulate the data
-accordingly. The `simple-impl` package, which provides some of the AD-SAL APIs
-mentioned above, is using this method to get data from the datastore and then
-convert them into RFC7285-compatible objects.
-
-=== Basic API and DataType
-
-.. alto-basic-types: Defines basic types of ALTO protocol.
-
-.. 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].
-
-.. alto-resourcepool: Manages the meta data of each ALTO service, including capabilities and versions.
-
-.. alto-northbound: Provides the root of RFC7285-compatible services at http://localhost:8080/alto.
-
-.. alto-northbound-route: Provides the root of the network map resources at http://localhost:8080/alto/networkmap/.
-
-=== How to customize service
-
-==== Define new service API
-
-Add a new module in `alto-core/standard-service-models`. For example, we named our
-service model module as `model-example`.
-
-==== Implement service RPC
-
-Add a new module in `alto-basic` to implement a service RPC in `alto-core`.
-
-Currently `alto-core/standard-service-models/model-base` has defined a template of the service RPC.
-You can define your own RPC using `augment` in YANG. Here is an example in `alto-simpleird`.
-
-[source,yang]
-include::augment.yang[]
-
-==== Register northbound route
-
-If necessary, you can add a northbound route module in `alto-core/standard-northbound-routes`.
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/alto-developer-guide.html
Code Review / docs.git / commitdiff