Jump to: navigation, search

OpenDaylight Controller:Binding Aware Components

SAL Guide Contents
Model-Driven Controller SAL
SAL:Infrastructure and Interfaces
SAL:Architecture Overview
SAL:YANG Schema
SAL:BI Data Format
SAL:BI Components
SAL:Binding-Aware SAL
SAL:Binding Model
SAL:BA Components
SAL:Example Workflows and Diagrams
Programmer Guide Top Level
Top Level Contents

Binding-Aware Components

In general, core binding aware components are variations of the binding-independent components, implementing similar contracts, but not using the binding-independent representation of data. Data used by binding-aware components is represented by generated Java proxies and TOs to facilitate static typing and to ease application and plugin development.

The following components implements similar contracts to binding-independent components:

  • Binding Aware Broker – the functionality (from Providers’ and Consumers’ perspective) is similar to the Binding-Independent Broker with the exception, that the generated proxies and TOs are used to represent data.
  • Binding Aware Consumer
  • Binding Aware Provider

The BI Data Repository does not have its binding-aware counter-part, but all other data processing contracts do.

Binding Aware Broker

The Binding Aware Broker is responsible for translating operations and calls between binding-aware components and the Binding Independent Broker.

Provided Functionality

Provider and Consumer Registration

Providers and Consumers need to register in order to use the Binding-Independent SAL layer and to expose their respective functionality via the SAL layer.

Consumer Registration

During registration the Broker gets the functionality from the Consumer. It uses the getFunctionality method from the Consumer contract, to register that functionality into the system

A Consumer is required to use the returned session for all communication with the Broker or any Broker service. The session is injected into the Consumer by invoking the method injectConsumerSession of the Consumer contract.

Provider Registration

During registration, the Broker gets the functionality from the Provider, using the method getFunctionality from Provider contract, to register that functionality into the system. A Provider is required to use the returned session for all communication with broker or any Broker service. The session is injected into the Provider by invoking the method injectProviderSession of the Provider contract.

Translation Proxy Generation

The Binding-Aware Broker is responsible for generation of Java proxy classes that implement generated Java-specific binding APIs TOs, and mappers, that translate these data and calls to binding-independent formats.

The generated proxies also translate from the binding-independent format to generated Java-specific binding formats.

The Binding-Aware Broker does not generate proxies and mappers directly, but uses the Binding Generator.

See Section Binding Generator for more information.

Call Translation

The Binding-Aware Broker is responsible for translation between binding-aware calls (generated Java language binding objects and functions) to the binding independent format. The binding independent format of calls is then used to communicate with the Binding-Independent Broker and with binding-independent Providers and Consumers such as the BI Data Repository. The Binding-Aware Broker also translates between binding-independent data and calls routed from the Binding-Independent Broker to model-specific Java structures. The call translation is done by generated mappers.

See Section Binding Generator for more information.

Notification Hub

Notification Hub 2.jpg The Binding Aware Broker exposes the Notification Publishing API to Providers and the Notification Consumer API to Consumers (applications and other providers). The Notification Publishing API and the Notification Consumer API use the Java type system and generics to distinguish between notification types.

Notify Call

Success = notify(Session, Notification)	

Where:

  • Success: set to OK by the Binding-Independent Broker if the notification has been successfully created
  • Session: provider session between the BI Broker and a Provider
  • Notification: an instance of Java-binding object representing the the notification contents.

On notify call, the Binding Aware Broker:

  1. Invokes the method on NotificationListener of all Consumers that subscribed to the notification.
  2. Translates the notification to the binding-independent format
  3. Forwards the notification in the binding-independent format to the BI Broker
    • The BI Broker forwards the notification to all registered listeners.
registerNotificationListener call
Success = registerNotificationListener(Session, NotificationType, NotificationListener listener)

Where:

  • Success: set to OK by the Binding-Independent Broker if the notification listener has been successfully registered
  • Session: client’s session between the BI Broker and a Client
  • NotificationType: Java Class object representing the type of notification for which the listener will be registered.
  • NotificationListener: an object implementing the NotificationListener that is called if the notification occurred.

RPC routing

RPC Routing 2.jpg

  1. The Consumer gets the generated proxy for the requested model / functionality.
  2. The Consumer constructs the instance of TO representing the input to the RPC.
  3. The Consumer invokes the method, which represents the RPC call, on the retrieved proxy.
  4. The generated proxy process the call:
    1. If the provider of RPC uses the same language-binding:
      1. the Provider implementation of RPC is invoked directly
    2. If the Provider is binding-independent
      1. the call are generated to the binding-independent form
      2. the binding-independent call is invoked on the BI Vroker
      3. the BI Broker routes the RPC, receives the BI independent response
      4. the BI independent response is translated to the language-binding format by the Binding-Aware Broker.

RPC Binding Aware Broker.jpg

System State Access & Modification

The broker unifies the access to the state of the system with use of Java-specific binding APIs. The broker does not implement the state functionality directly, but uses generated mappers to translate data from/to binding-independent formats and invocations of the BI Broker’s state repository API. The contracts implemented by the Binding-Aware Broker are similar to the data & state contracts of the BI broker, but use DTOs and Java Class objects representing DTO types instead of DOMNodes and QNames.

See Section Binding-Independent Data Repository for more information.

Requirements

  • Notification handling should not result in the cyclic calls between Binding Aware Broker and the BI broker

Dependencies

Binding aware broker depends on:

  • Binding Generator – to generate proxies and mappers
  • Binding Independent Broker – to route calls to binding-independent providers and consumers

Binding Generator

The Binding Generator is an infrastructure component responsible for runtime generation of functionality and implementation of model bindings.

Provided Functionality

Generation of Proxies

The Binding Generator is responsible for generation of various types of proxies, which are defined in the Binding Model, and allows access to the Providers’ functionality, regardless the type of Provider.

Proxies provide a simple programmatic access to the Binding-Aware Broker functionality (e.g. RPC calls) and wrap the translation between data in a statically typed format to data in the binding-independent DOM format.

Generation of Data Transfer Object Builders

Transfer objects are not generated directly, but the Binding Generator creates an implementation of builders which are to be exposed to Consumers to expose the data.

Builder = getBuilder(TransferObjectClass)

Where:

  • Builder: An implementation of generated Java interface for building immutable DTOs.
  • TransferObjectClass: An Java Class object representing the DTO for which the builder should be generated.

Generation of TO Mappers

Generated mappers are not designed to be directly used to the Consumers, but to be used by Binding-Aware Broker

Mapper = getMapper(TransferObjectClass)

Where:

  • Mapper: An implementation of the DTOMapper Contract, specific for the supplied TransferObjectClass
  • TransferObjectClass: A Java Class object representing the interface describing the data transfer object.
Mapper = getMapper(SchemaPath)

Where:

  • Mapper: An implementation of the DTOMapper Contract, specific for the supplied TransferObjectClass
  • SchemaPath: An path in YANG schema representing the schema definition for the data.
DTOMapper contract

Implementations of DTOMapper contract are responsible for two-way mapping / translation of data in Binding-aware format (instances of generated DTOs) and binding-indepenendent Data DOM format.

TO = createDTO(DOMNode)

Where:

  • TO: DTO representing the data
  • DOMNode: Data DOM representation of data
DOMNode = createDOMNode(TO)

Where:

  • TO: DTO representing the data
  • DOMNode: Data DOM representation of data

Dependencies

The Binding Generator is dependent on:

  • Model Schema
  • Binding-independent Data Form
  • Binding Model
  • Model Schema Repository

Generation Workflow

Generation Workflow.jpg

The binding generation workflow is variation of the Netconf/YANG client workflow.

  • A Binding specification is generated during the development phase of consumers and providers, the format is set for generated sources of Java interfaces and TOs
  • The translation specification is dependent on the implementation of the Translation Compiler. The possibilities for the translation specification are:
    • Generated java source code – if static compilation is required
    • Annotations on interfaces in the binding specification
    • Packaged source YANG models
  • The Runtime Binding Generator is responsible for runtime generation of proxies, TOs, TO builders and mappers.

The generation workflow is as follows:

  • At development time:
    1. Developer adds a YANG model to the project (Consumer or Provider)
    2. Developer invokes the Java Binding Generator
    3. The Java Binding Generator generates the Binding Specification (Java interfaces of TOs, RPC services)
    4. Developer writes code using the generated Binding Specification and the Binding-Aware Broker APIs.
    5. Developer compiles the project
    6. YANG models are also bundled into compiled library
  • At runtime:
    1. Project is deployed to the Controller
    2. Project code requests RPC services and/or TO Builders via Binding-Aware Broker APIs
    3. The Binding-Aware Broker gets the instances of TO Builders and proxies from the Binding Generator and returns these instances to the project code
    4. Project code uses generated proxies.
    5. Proxies invokes Binding-Aware Broker functionality
    6. Binding-Aware Broker invokes TO translation (by using Generated Mapper) if the target is Binding-independent Provider. Otherwise Binding-Aware Broker passes TOs directly to the Provider.

Functional Requirements

The Binding Generator SHOULD:

  • Keep track of generated classes; supporting classes for the same revision of model SHOULD NOT be regenerated for a new Consumer / provider, but reused.
  • Generated TO Mappers, which should be thread-safe and stateless
  • Transfer Objects returned from TO Builders should be immutable.

Dependencies

The Binding Generator has the following dependencies:

  • Model Schema Repository
  • Binding-Independent model

Binding-Aware Consumer

The Binding-Aware Consumer is variation of the Consumer which does not use the Binding-Independent format for data and contracts. It uses generated bindings to access functionality provided by other components of the system.

Binding-Aware Provider

The Binding-Aware Provider is a variation of the Provider, which is not programmed using the Binding-Independent data and contract formats, but uses generated bindings to provide functionality to other components in the system. In general, most contracts for the Binding-Aware Provider are similar to Binding-Independent Provider contracts, but use DTOs and Java Class objects representing DTO types instead of DOMNodes and QNames.

Exposing an RPC Implementation

When a Provider implements RPC interfaces generated from bindings, it can register the implementation with the Broker by using the:

  • pull form – returning the objects implementing the contract in the return value from the getFunctionality method
  • push form – see Provider Registration for the Binding Aware Broker.