manuals/developer-guide/src/main/asciidoc/controller/config-java-gen.adoc

   1 // https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Java_Code_Generator
   2 ==== Java Code Generator
   3
   4 ===== YANG to Java code generator
   5
   6 The Java code for the configuration system is generated by the yang-maven-plugin
   7 and the yang-jmx-generator-plugin.
   8 The input Yang module files are converted to java files by the definition of
   9 the module and the specified templates. the generated java code can represent
  10 interfaces, classes, or abstract classes used for configuration.
  11
  12 ====== Service interfaces generating
  13
  14 Service interfaces (SI) are generated from YANG "service-types". Each SI must
  15 be defined as "identity" with a "base" statement set to "config:service-type",
  16 or another SI. This is because a service must have a globally unique name.
  17 Each SI must be annotated with @ServiceInterfaceAnnotation, and must extend
  18 AbstractServiceInterface.
  19
  20 *Sample YANG module representing service interface* +
  21
  22 ----
  23 module config-test {
  24     yang-version 1;
  25     namespace "urn:opendaylight:params:xml:ns:yang:controller:test";
  26     prefix "test";
  27
  28     import config { prefix config; revision-date 2013-04-05; }
  29
  30     description
  31         "Testing API";
  32
  33     revision "2013-06-13" {
  34         description
  35             "Initial revision";
  36     }
  37
  38     identity testing {
  39         description
  40             "Test api";
  41
  42         base "config:service-type";
  43         config:java-class "java.lang.AutoCloseable";
  44     }
  45 }
  46 ----
  47 The "description" node of identity is generated as javadoc in the service interface. +
  48 The "config:java-class" is generated as *ServiceInterfaceAnnotation*. It specifies
  49 java classes or interfaces in the "osgiRegistrationTypes" parameter. The module
  50 implementing this service interface must instantiate a java object that can be
  51 cast to any of the java types defined in "osgiRegistrationTypes".
  52
  53 *Generated java source file: AutoCloseableServiceInterface* +
  54
  55 ----
  56 package %prefix%.test;
  57
  58 /**
  59 * Test api
  60 */
  61 @org.opendaylight.controller.config.api.annotations.Description(value = "Test api")
  62 @org.opendaylight.controller.config.api.annotations.ServiceInterfaceAnnotation(value = "testing", osgiRegistrationType = java.lang.AutoCloseable.class)
  63 public interface AutoCloseableServiceInterface extends org.opendaylight.controller.config.api.annotations.AbstractServiceInterface
  64 {
  65
  66 }
  67 ----
  68
  69 ====== Module stubs generating
  70
  71 Modules are constructed during configuration transaction. A module implements
  72 the ModuleMXBean interface. The ModuleMXBean interface represents getters and
  73 setters for attributes that will be exposed to the configuration registry by
  74 means of JMX. Attributes can either be simple types, or composite types.
  75
  76 Each ModuleMXBean must be defined in yang as "identity" with the base statement
  77 set to "config:module-type". Not only are ModuleMXBeans generated, but also
  78 ModuleFactory and Module stubs. Both are first generated as abstract classes
  79 with almost full functionality. Then their implementations, which are allowed
  80 to be modified by users, are generated, but only once.
  81
  82 ===== Runtime beans generating
  83
  84 Runtime JMX beans are purposed to be the auditors: they capture data about
  85 running module instances. A module can have zero or more runtime beans. Runtime
  86 beans are hierarchically ordered, and each must be uniquely identified.
  87 A runtime bean is defined as a configuration augment of a module, from which
  88 interface RuntimeMXBean, RuntimeRegistrator, and RuntimeRegistretion are generated.
  89 Augment definition contains arguments representing the data of a module that
  90 must be watched.
  91
  92 ===== RPCs
  93
  94 Method calls in yang must be specified as top level elements. The context,
  95 where an RPC operation exits, must be defined in the RPC definition itself,
  96 and in the runtime bean that provides method implementation.