Southbound Yang Utils

Table of Contents

Contributors

Overview

This section provides an overview Yang southbound XML utils. This tool is a first step stone in integrating more in depth YANG in the ONOS southbound interface with a completa YANG to Java translator for class generation. For a reference at a future project please see YANG Models in ONOS

Interfaces, Classes, Scripts

• YangXMLUtils.java, provides method to create and read a configuration based on a provided XML schema derived from a yang model. 

• YangElement.java: class that contains an element to be retrieved or set in a XML configuration. it based on a base path and a Map of <key, value pairs> that contain the retrieved or to be set information.
• Xml Skeleton: file generated by the onos-yang-converter.sh script. Contains the skeleton of the XML configuration supported by the device and it's used as a basis for generation by YangXMLUtils.java
• onos-convert-yang.sh: bash script that takes in input the path for folder with .yang files and converts them into XML skeleton files using the pyang tool. The XML skeletons are put in a subfolder with the same name as the original one in the resource folder for the onos-drivers-utilities module.
• NetconfSession.java: interface that every type of transport connection to a NETCONF device must implement, represents the single access point for any operation on the device. It's methods are called by the driver with the payload generated form the utils.

Convert Yang models into XML skeletons

If you have your own yang models in a folder you can execute the onos-convert-yang.sh script with the path as a parameter.

$ onos-convert-yang <path_to_yang_models_folder>

This command will translate the .yang files in the passed folder to XML skeleton elements and puts them in $ONOS_ROOT/drivers/utilities/src/main/resources/<original yang folder name>. This make them available as a resource to the YangXMLUtils.java class

The command is based upon the Pyang tools library. If Pyang is not installed on your environment machine it will ask you to download it from https://github.com/mbj4668/pyang.

Use the converted xml skeletons from a driver

Once you converted the .yanf files with the script the YangXMLUtils provides xml serialization/deserialization capabilities:

• getXmlConfiguration enables you to provide a list of YangElements and obtain a configuration that has those element set with the value you specified. 
• readXmlConfiguration enables you to read a xml file that has arrived from a device asking for the values of a particular element contained in it and retrieve a list of Yang elements containing the base key and a map of key values pair with the data the xml configuration has for that element.

A YangElement is a class that contains the base path of the object to read or to set and a Map <element_subpath, value>.

An example can be made with this XML

<controller>
	<id>tcp:2.2.2.2:2</id>
	<ip-address>2.2.2.2</ip-address>
</controller>

To generate that XML from a yang model you will have to call getXmlConfiguration passing the relative path to the file and a list containing one YangElement with as basekey "controller" and as map { id:tcp:2.2.2.2:2 and ip-address:2.2.2.2}

new YangElement("controller", ImmutableMap.of("id",tcp:2.2.2.2:2 ,"ip-address",ip-address:2.2.2.2))

If the example XML is the configuration you want to read you will have to call readXmlConfiguration with the XMLConfiguration read from the xml string using the loadXml and the "controllers" as the basekey and you will obtain the same YangElement shown in the prior code snippet.

The XML generation is nested so if you pass multiple yang elements you will obtain a nested XML based on the yang model and the position of the elements in it. 

Future Work

This Yang to XML implementation is just a middle step into implementing a complete Yang parser and Yang to Java generator. That tool will provider a better integration and require less knowledge form the developer.