--- /dev/null
+== ALTO Developer Guide ==
+
+=== Overview ===
+The topics of this guide are:
+
+. How to add alto projects as dependencies;
+. How to put/fetch data from ALTO;
+. 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.1.0-Lithium`.
+
+=== 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 `/controller/nb/v2/alto` and below is a list
+of the specific paths defined in `AltoNorthbound.java` in `alto-northbound`
+using Jersey `@Path` annotation:
+
+* `/ird/{rid}`: the path to access __IRD__ services;
+* `/networkmap/{rid}[/{tag}]`: the path to access __Network Map__ services;
+* `/costmap/{rid}[/{tag}[/{mode}/{metric}]]`: the path to access __Cost Map__
+services;
+* `/filtered/networkmap/{rid}[/{tag}]`: the path to access __Filtered Network Map__
+services;
+* `/filtered/costmap/{rid}[/{tag}]`: the path to access __Filtered Cost Map__
+services;
+* `/endpointprop/lookup/{rid}[/{tag}]`: the path to access __Endpoint Property__
+services;
+* `/endpointcost/lookup/{rid}[/{tag}]`: 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 `alto-model` 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 AD-SAL ====
+Five interfaces are defined in package `service-api-rfc7285`. Follow the steps
+below to use them:
+
+. Determine the required service interface: `IRDService`, `NetworkMapService`,
+`CostMapService`, `EndpointPropertyService` or `EndpointCostService`;
+. Use the `ServiceHelper` to get the instance;
+. Call the corresponding methods with appropriate parameters.
+
+==== Using MD-SAL ====
+You can also fetch data from the data store directly.
+
+First you must get the access to the data store 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 data store and then
+convert them into RFC7285-compatible objects.
+
+=== Providing Customized Implementation ===
+
+Currently it is very simple to provide a customized network map, the
+only thing you have to do is to put the data into the data store. Cost maps are
+more complex since there are no classes for the cost values by default, you have
+to define it using `augment` in YANG. Here is an example in `alto-hosttracker`.
+
+[source,yang]
+include::augment.yang[]
--- /dev/null
+== ALTO User Guide
+
+=== Overview
+The ALTO project provides support for _Application Layer Traffic
+Optimization_ services defined in link:https://tools.ietf.org/html/rfc7285[RFC
+7285].
+
+In the Lithium release, ALTO uses the YANG model described in
+link:https://tools.ietf.org/html/draft-shi-alto-yang-model-03[this draft].
+
+=== ALTO Architecture
+
+There are three kinds of ALTO packages in OpenDaylight.
+
+. **Core**
+The **core** packages include:
+.. `alto-model`: Defines the YANG model of ALTO services in MD-SAL
+.. `service-api-rfc7285`: Defines interfaces for ALTO services in AD-SAL
+.. `alto-northbound`: Implements the RFC7285-compatible RESTful API
+. **Basic**
+The **basic** packages include:
+.. Basic implementations of ALTO services:
+... `alto-provider`: Implements the services defined in `alto-model`
+... `simple-impl`: Implements the services defined in `service-api-rfc7285`
+.. Utilities:
+... `alto-manager`: Provides a karaf command line tool to manipulate network
+maps and cost maps.
+. **Service**
+The **service** packages include:
+.. `alto-hosttracker`: Generates a network map, a corresponding cost map and
+the endpoint cost service based on <<_l2switch_user_guide, l2switch>>.
+
+=== Configuring ALTO
+
+There are three packages that require their own configuration files,
+including `alto-provider`, `alto-hosttracker` and `simple-impl`. However, the
+only configurable option is the type of the data broker in all three
+configuration files.
+
+=== Administering or Managing ALTO
+
+To enable ALTO, the features must be installed first.
+
+[source,bash]
+karaf > feature:install odl-alto-provider
+karaf > feature:install odl-alto-manager
+karaf > feature:install odl-alto-northbound
+karaf > feature:install odl-alto-hosttracker
+
+==== Managing Data with RESTCONF
+
+After installing `odl-alto-provider` feature in karaf, it is possible to manage
+network-maps and cost-maps using RESTCONF. Take a look at all the operations
+provided by `alto-model` at the API service page which can be found at
+`http://localhost:8181/apidoc/explorer/index.html`.
+
+With the example input below you can insert a network map into the data store,
+either by filling the form in the API doc page, or by using tools such as `curl`.
+
+[source,bash]
+HOST_IP=localhost # IP address of the controller
+CREDENTIAL=admin:admin # username and password for authentication
+BASE_URL=$HOST_IP:8181/restconf/config
+SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
+RESOURCE_ID=test_odl # Should match the one in the input file
+curl -X PUT -H "content-type:application/yang.data+json" \
+ -d @example-input.json -u $CREDENTIAL \
+ http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
+
+[source,json]
+include::example-input.json[]
+
+[[read-restconf]]Use the following command to see the results:
+
+[source,bash]
+HOST_IP=localhost # IP address of the controller
+CREDENTIAL=admin:admin # username and password for authentication
+BASE_URL=$HOST_IP:8181/restconf/config
+SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
+RESOURCE_ID=test_odl
+curl -X GET -u $CREDENTIAL http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
+
+Use `DELETE` method to remove the data from the data store.
+
+[source,bash]
+HOST_IP=localhost # IP address of the controller
+CREDENTIAL=admin:admin # username and password for authentication
+BASE_URL=$HOST_IP:8181/restconf/config
+SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
+RESOURCE_ID=test_odl
+curl -X DELETE -H "content-type:application/yang.data+json" \
+ -u $CREDENTIAL http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
+
+==== Using `alto-manager`
+
+The `alto-manager` package provides a karaf command line tool which wraps up
+the functions described in the last section.
+
+[source,bash]
+karaf > alto-create <type> <resource-file>
+karaf > alto-delete <type> <resource-id>
+
+Currently only `network-map` and `cost-map` are supported. Also the resource
+files used in `alto-manager` follow the RFC7285-compatible format instead of
+RESTCONF format.
+
+The following example shows how to use `alto-manager` to put a network map into
+the data store.
+
+[source,bash]
+karaf > alto-create network-map example-rfc7285-networkmap.json
+
+[source,json]
+include::example-rfc7285-networkmap.json[]
+
+==== Using `alto-hosttracker`
+
+As a real instance of ALTO services, `alto-hosttracker` reads data from
+`l2switch` and generates a network map with resource id
+`hosttracker-network-map` and a cost map with resource id `hostracker-cost-map`.
+It can only work with OpenFlow-enabled networks.
+
+After installing the `odl-alto-hosttracker` feature, the corresponding network
+map and cost map will be inserted into the data store. Follow the steps in
+<<read-restconf, how to read data with RESTCONF>> to see the contents.
Code Review / alto.git / commitdiff