// https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Java_Code_Generator
==== Java Code Generator

===== YANG to Java code generator

The Java code for the configuration system is generated by the yang-maven-plugin
and the yang-jmx-generator-plugin.
The input Yang module files are converted to java files by the definition of
the module and the specified templates. the generated java code can represent
interfaces, classes, or abstract classes used for configuration.

====== Service interfaces generating

Service interfaces (SI) are generated from YANG "service-types". Each SI must
be defined as "identity" with a "base" statement set to "config:service-type",
or another SI. This is because a service must have a globally unique name.
Each SI must be annotated with @ServiceInterfaceAnnotation, and must extend
AbstractServiceInterface.

*Sample YANG module representing service interface* +

----
module config-test {
    yang-version 1;
    namespace "urn:opendaylight:params:xml:ns:yang:controller:test";
    prefix "test";

    import config { prefix config; revision-date 2013-04-05; }

    description
        "Testing API";

    revision "2013-06-13" {
        description
            "Initial revision";
    }

    identity testing {
        description
            "Test api";

        base "config:service-type";
        config:java-class "java.lang.AutoCloseable";
    }
}
----
The "description" node of identity is generated as javadoc in the service interface. +
The "config:java-class" is generated as *ServiceInterfaceAnnotation*. It specifies
java classes or interfaces in the "osgiRegistrationTypes" parameter. The module
implementing this service interface must instantiate a java object that can be
cast to any of the java types defined in "osgiRegistrationTypes".

*Generated java source file: AutoCloseableServiceInterface* +

----
package %prefix%.test;

/**
* Test api
*/
@org.opendaylight.controller.config.api.annotations.Description(value = "Test api")
@org.opendaylight.controller.config.api.annotations.ServiceInterfaceAnnotation(value = "testing", osgiRegistrationType = java.lang.AutoCloseable.class)
public interface AutoCloseableServiceInterface extends org.opendaylight.controller.config.api.annotations.AbstractServiceInterface
{

}
----

====== Module stubs generating

Modules are constructed during configuration transaction. A module implements
the ModuleMXBean interface. The ModuleMXBean interface represents getters and
setters for attributes that will be exposed to the configuration registry by
means of JMX. Attributes can either be simple types, or composite types.

Each ModuleMXBean must be defined in yang as "identity" with the base statement
set to "config:module-type". Not only are ModuleMXBeans generated, but also
ModuleFactory and Module stubs. Both are first generated as abstract classes
with almost full functionality. Then their implementations, which are allowed
to be modified by users, are generated, but only once.

===== Runtime beans generating

Runtime JMX beans are purposed to be the auditors: they capture data about
running module instances. A module can have zero or more runtime beans. Runtime
beans are hierarchically ordered, and each must be uniquely identified.
A runtime bean is defined as a configuration augment of a module, from which
interface RuntimeMXBean, RuntimeRegistrator, and RuntimeRegistretion are generated.
Augment definition contains arguments representing the data of a module that
must be watched.

===== RPCs

Method calls in yang must be specified as top level elements. The context,
where an RPC operation exits, must be defined in the RPC definition itself,
and in the runtime bean that provides method implementation.