manuals/developer-guide/src/main/asciidoc/core/odl-controller-AD-SAL-overview.adoc

   1 == Overview of AD-SAL\r
   2 \r
   3 API-Driven Service Abstraction Layer (AD-SAL) is a flavour of the SAL created for the OpenDaylight controller project. The main task of AD-SAL is primarily to create a layer against which the applications can be developed without needing to know the underlying SDN protocols. Using AD-SAL, you can control two different type of network elements in an SDN fashion, meaning by accessing them in a programmatic way. \r
   4 \r
   5 AD-SAL was introduced based on the requirements of the network user, such as:\r
   6 \r
   7 * Given a network element, list the neighbours and build the network graph.\r
   8 \r
   9 * Given a network element, list the interfaces attached to it and what properties they carry.\r
  10 \r
  11 Starting from these requirements, we can also assume that certain aspects of the SDN protocols would be common no matter what the actual protocol is doing underneath. This idea allows us to describe the aspects in a generic way using a Java Contract which is usually a set of Java interfaces and supporting objects that represent the data. This way of creating contracts that allows a consumer of the contract to be insulated by the possible implementation is rather common in the Java world. Some examples are as follows:\r
  12 \r
  13 * https://www.jcp.org/en/jsr/detail?id=315[Servlet 3.0]\r
  14 \r
  15 * http://en.wikipedia.org/wiki/Jax-rs[JAX-RS]\r
  16 \r
  17 These examples use http://en.wikipedia.org/wiki/Java_Specification_Request[JSR (Java Specification Request)] which can be implemented by different providers.\r
  18 \r
  19 For example Servlet 3.0 contracts can be implemented by Tomcat or Jetty or other servlet container. Going by the same analogy, the protocol plugins (i.e. the components that can understand an SDN protocol and convert them to the common layer) can implement one or more of these contracts based on the capabilities. The SAL defined in AD-SAL is just an adaptation layer to enable the protocol plugins to speak common aspects but only if they can do it. The SAL does not force a lowest common denominator for all to be spoken, but rather given a certain aspect if the protocol plugins supports it, it will be supported in a common fashion.\r
  20 \r
  21 === An example of protocols in AD-SAL\r
  22 \r
  23 image::multiprotocol_AD-SAL.jpg[title="Protocols in AD-SAL", alt="Protocols in AD-SAL"]\r
  24 \r
  25 \r
  26 In the image above, there are 4 types of contracts, identified by the coloured triangles, and there are 3 protocol plugins that provide implementation for those contracts. \r
  27 \r
  28 For example the *Topology* contract (the one used to learn the network graph) is implemented by all of the protocol plugins while the *Bridge Configuration* contract is only implemented by OVSDB because the others are not capable of it. That is perfectly fine and actually expected because that allows us not to revert to the lowest common denominator feature for all the protocol plugins. \r
  29 \r
  30 The image below explains how an application has to deal with the optional presence of a contract on a given network element. In the image, an application is trying to create a bridge on Nodes O1, O2 and OF1, the first two are capable of that contract, the third one is not, so the application has to take care of it and handle the return code.\r
  31 \r
  32 image::Applications_AD-SAL.jpg[title="Applications using AD-SAL", alt="Applications using AD-SAL"]\r
  33 \r
  34 In summary AD-SAL is just enforcing that the protocol plugins speak a common language for words that can be expressed in a common language. The dictionary of the common language is not hardcoded, it can be extended supplying new contracts to AD-SAL such that new protocols plugin can implement it and applications can consume them.\r
  35 \r
  36 To migrate from AD-SAL to MD-SAL, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:AD-SAL_Compatibility[MD-SAL:AD-SAL Compatibility].\r
  37 \r
  38 NOTE: For information on MD-SAL, see the relevant pages in this document.\r
  39 \r
  40 === Differences between AD-SAL and MD-SAL\r
  41 \r
  42 .Differences between AD-SAL and MD-SAL\r
  43 \r
  44 [cols="2*", options="header"]\r
  45 \r
  46 |===\r
  47 \r
  48 |AD-SAL  |MD-SAL \r
  49 \r
  50 |API-Driven SAL\r
  51 \r
  52 |Model-Driven SAL\r
  53 \r
  54 \r
  55 |The SAL APIs request routing between consumers and providers. Data adaptations are all statically defined at compile or build time.\r
  56 \r
  57 |The SAL APIs request routing between consumers and providers as defined from models, and data adaptations are provided by internal adaptation plugins.\r
  58 \r
  59 |The AD-SAL typically has both northbound and southbound APIs even for functions or services that are mapped 1:1 between southbound plugins and northbound plugins.\r
  60 \r
  61 |The MD-SAL allows both the northbound and southbound plugins to use the same API generated from a model. One plugin becomes an API (service) provider; the other becomes an API (service) consumer.\r
  62 \r
  63 |In AD-SAL there is a dedicated REST API for each northbound or southbound plugin.\r
  64 \r
  65 | MD-SAL provides a common REST API to access data and functions defined in models.\r
  66 \r
  67 |The AD-SAL provides request routing (selects a southbound plugin based on service type) and optionally provides service adaptation, if an northbound (Service, abstract) API is different from its corresponding southbound (protocol) API.\r
  68 \r
  69 | The MD-SAL provides request routing and the infrastructure to support service adaptation, but it does not provide service adaptation itself, service adaptation is provided by plugins.\r
  70 \r
  71 \r
  72 |Request routing is based on plugin type. The SAL knows which node instance is served by which plugin, and when a northbound plugin requests an operation on a given node, the request is routed to the appropriate plugin which then routes the request to the appropriate node.\r
  73 \r
  74 | Request Routing in the MD-SAL is done on both protocol type and node instances, since node instance data is exported from the plugin into the SAL.\r
  75 \r
  76 |AD-SAL is stateless.\r
  77 \r
  78 | MD-SAL can store data for models defined by plugins. Provider and consumer plugins can exchange data through the MD-SAL storage.\r
  79 \r
  80 \r
  81 |Limited to flow-capable device and service models only.\r
  82 \r
  83 |Model agnostic. It can support any device or service models and is not limited to flow-capable device and service models only.\r
  84 \r
  85 \r
  86 \r
  87 |AD-SAL services usually provide both asynchronous and synchronous versions of the same API method.\r
  88 \r
  89 |In MD-SAL, service model APIs only provide asynchronous APIs, but they return a *java.concurrent.Future* object, which allows a caller to block until the call is processed and a result object is available. Same API can be used for both synchronous and asynchronous approach. Thus MD-SAL encourages asynchronous approach to application design but does not preclude synchronous applications.\r
  90 \r
  91 \r
  92 \r
  93 \r
  94 \r
  95 \r
  96 \r