--- /dev/null
+:bug: https://bugs.opendaylight.org/show_bug.cgi?id=
+:rfc6020: https://tools.ietf.org/html/rfc6020
+:rfc6020bis: https://tools.ietf.org/html/draft-ietf-netmod-rfc6020bis
+:toc:
+
+= Analysis of Binding Specification v2
+
+== Introduction
+
+This document is intended for developers / designers participating in design of
+model-derived Java Binding for MD-SAL, or for developers interested
+in understanding issues with current design and initial input / reasoning for
+follow-up design of next version.
+
+IMPORTANT: This is living document, which may be updated when new issues
+are raised, solutions proposed.
+
+=== Assumed Knowledge
+
+* Good understanding of {rfc6020}[YANG language]
+* Good understanding of Java language, language syntax, semantics and rules.
+* Good understanding of common design patterns and their application in Java.
+
+Knowledge of other JVM-based languages such as Groovy or Scala, and understanding
+how these languages rendered their specific concepts is also beneficial.
+
+=== What is Java Binding Specification
+
+* Binding specification defines mapping of YANG modeled data to
+respective Java Objects, structures and DTOs
+* has compile time and runtime aspects, compile time aspects are mostly
+visible to users of MD-SAL
+* Currently used specification is
+https://wiki.opendaylight.org/view/YANG_Tools:YANG_to_Java_Mapping[Binding
+Specification v1]
+
+== Requirements for Binding Specification v2
+
+Interfaces & classes provided and generated by Binding Specification v2:
+
+* SHOULD model YANG semantics correctly
+* MUST NOT prevent support of YANG 1.1. See <<yang-11-changes>>
+* Provide / enforce maximal possible constrains during compile-time
+** This prevents bugs at compile time, more allows for assumptions at
+runtime and performance optimizations
+* Isolation - Code generation MUST BE isolated. Presence of additional model
+should not change generation of original model.
+* SHOULD allow for reusing instances of objects at various subtrees
+
+== Known issues of Binding Specification 1
+
+* <<correct-model-representation>>
+* <<missing-mappings>>
+* <<java-correctness>>
+* <<usability-issues>>
+* <<performance-issues>>
+
+[[correct-model-representation]]
+=== Issues preventing correct model generation
+
+** <<namespace-collision>>
+** <<spec-collision>>
+** <<outer-inner-class-collision>>
+
+[[namespace-collision]]
+==== Grouping, data, typedef and identity namespaces collide
+
+.Related bugs
+** {bug}138[138: Grouping, data, typedef and identity namespaces collide]
+
+
+This bugs shared common root in Binding Specification v1 and that was caused by
+not accounting for identifier namespace differences between Java and YANG.
+
+- Java has 1 namespace, where unique identifier is is *Package name with Class name*
+- YANG has 6 separate namespaces and allows for same name to be used
+in this separate namespaces.
+Module and submodule namespace::
+Each module and submodule name must be unique.
+Extension namespace::
+All extensions names defined in module and its submodules must be unique.
+Typedef namespace::
+All derived type names defined within a parent node or at the top
+level of the module or its submodules must be unique.
+Grouping namespace::
+All grouping names defined within a parent node or at the top
+level of the module or its submodules must be unique.
+Data namespace::
+All leafs, leaf-lists, lists, containers, choices, rpcs,
+notifications, and anyxmls defined (directly or through a uses
+statement) within a parent node or at the top level of the module
+must be unique.
+Identity namespace::
+All identity names defined in a module and its submodules share
+the same identity identifier namespace.
+
+.Example valid model
+[source, yang]
+----
+module example {
+ namespace "urn:example";
+
+ identity example {}
+ typedef example {type string;}
+ grouping example {}
+ container example {
+ container example {
+ leaf example {type example;}
+ }
+ }
+}
+----
+
+===== Proposed solution
+
+Use different packages names for identities, types, groupings and data tree
+items.
+
+The format of package name is `{gen-prefix}.{module-id}.{namespace-id}.{tree-id}` where:
+
+gen-prefix::
+ Constant prefix for all generated code in order to not conflict with hand-written
+ code. Value is `org.opendaylight.mdsal.gen.v2`
+module-id::
+ Module name translated to package identifier. It is shorter than namespace,
+ requires less substitutions and still is unique identifier of module, which
+ can not change over time.
+namespace-id::
+ One of YANG defined identifier namespaces:
+ * `ident` - identity namespace, package for identities
+ * `type` - type namespace, package for types
+ * `grp` - grouping namespace, package for groupings
+ * `data` - package for all instantiated data tree nodes
+tree-id::
+ Package identifier derived from `schema-node-identifier` in order to separate
+ namespace on each level of data tree.
+
+.Example
+* If module name is `example-network-topology` unique identifier is `example.network.topology`
+** `org.opendaylight.mdsal.gen.v2.urn.example.network.topology` - module specific items
+** `org.opendaylight.mdsal.gen.v2.urn.example.network.topology.type` - interfaces / classes representing derived types
+** `org.opendaylight.mdsal.gen.v2.urn.example.network.topology.grp` - interfaces / classes representing grouping and their
+children
+** `org.opendaylight.mdsal.gen.v2.urn.example.network.topology.data` - interfaces / classes representing notifications, rpcs,
+data tree
+
+[[spec-collision]]
+==== Methods introduced by Binding Specification conflicts with modeled items
+
+.Related bugs
+** {bug}157[157: Conflict appears when key of list is leaf with name `key`]
+
+
+Binding Specification v1 uses getter pattern for representing nested children
+derived from YANG model. Name of child is converted to valid JAVA name and
+prepended with `is` or `get` prefix.
+
+Unfortunately Java & Binding Specification v1 also uses `get` prefix for some
+methods.
+
+
+.Example conflicting model
+[source, yang]
+----
+container example {
+
+ list property {
+ key `key`;
+ leaf key { // <1>
+ type string;
+ }
+ }
+
+ leaf implemented-interface { // <2>
+ type string;
+ }
+
+ leaf class { // <3>
+ type string;
+ }
+
+}
+----
+<1> Conflicts with `getKey` introduced by `Identifiable` which is used for lists
+ with key
+<2> Conflicts with `getImplementedInterface` defined in `DataContainer` which is
+base interface of all generated lists, containers, cases, choices
+<3> Conflicts with `getClass` defined in `Object` which is root of all Java classes
+
+
+==== Enumeration mapping is based on incorrect assumptions
+
+.Related Bugs
+* {bug}2332[2332: Binding Java API Generator -> doesn't handle non-alphabetic signs in names of enum constants]
+
+Enumeration mapping was based on notion / idea that names of possibles values
+are `identifier` as defined in RFC6020, but actual name is string.
+
+.RFC 6020: Section 9.6.4 The enum Statement
+----
+It takes as an argument a string which is the assigned name. The
+string MUST NOT be zero-length and MUST NOT have any leading or
+trailing whitespace characters (any Unicode character with the
+"White_Space" property). The use of Unicode control codes SHOULD be
+avoided.
+----
+
+This mapping makes impossible to represent following model:
+
+[source, yang]
+----
+typedef math-operand {
+ type enumeration {
+ enum "+";
+ enum "/";
+ enum "*";
+ enum "-"";
+ }
+}
+----
+
+==== 4625: groupings should not share classes with their instantiations
+
+[[java-correctness]]
+=== Correct use of Java language
+
+* {bug}2791[2791]: Java Bindings: do not generate underscores in identifiers
+* {bug}5671[5671]: Java Binding: missing @return (binding spec. v2)
+
+
+[[outer-inner-class-collision]]
+==== Inner class with same name as outer class is not allowed
+
+.Related bugs
+* {bug}2360[2360: Inner class with same name as outer class is not allowed]
+
+Inner classes are used for generation of anonymous `union`, `bit` and `enumeration` types
+defined in model.
+
+In Java inner class MUST NOT have same name as outer class, which causes compilation
+error for following model:
+
+[source, yang]
+----
+grouping flags {
+ leaf flags {
+ type bits {
+ bit one;
+ bit two;
+ }
+ }
+}
+
+grouping status {
+ leaf status {
+ type enumeration {
+ enum open;
+ enum closed;
+ }
+ }
+}
+----
+
+
+=== Incompatibilities with allowed model upgrade paths
+
+==== Multiple augmentations of same target should result in one interface
+
+=== Mappings incompatible with YANG 1.1
+
+==== Identity mapping does not allow for identities with multiple bases
+
+YANG 1.1
+
+
+.Example model
+[source, yang]
+----
+module example-crypto-base {
+ yang-version 1.1;
+ namespace "urn:example:crypto-base";
+ prefix `crypto`;
+
+ identity crypto-alg {
+ description
+ "Base identity from which all crypto algorithms
+ are derived.";
+ }
+
+ identity symmetric-key {
+ description
+ "Base identity used to identify symmetric-key crypto
+ algorithms.";
+ }
+
+ identity public-key {
+ description
+ "Base identity used to identify public-key crypto
+ algorithms.";
+ }
+ }
+
+ module example-des {
+ yang-version 1.1;
+ namespace "urn:example:des";
+ prefix `des`;
+
+ import `example-crypto-base` {
+ prefix `crypto`;
+ }
+
+ identity des {
+ base "crypto:crypto-alg";
+ base "crypto:symmetric-key";
+ description "DES crypto algorithm";
+ }
+
+ identity des3 {
+ base "crypto:crypto-alg";
+ base "crypto:symmetric-key";
+ description "Triple DES crypto algorithm";
+ }
+}
+
+----
+
+==== Derived enumeration could limit valid values
+
+==== Derived bits could limit valid values
+
+
+[[missing-mappings]]
+=== Missing Mappings of YANG concepts
+
+* {bug}706[706]: Missing support for `anyxml` // Supplier<Source>
+
+[[usability-issues]]
+=== Usability issues
+
+
+* {bug}2872[2872]: Generated Java Enumerations should contain mapping to the string counter part
+* {bug}1870[1870]: Binding Specification: Type empty needs better representation than Boolean or Null vs NonNul
+* {bug}5673[5673]: Add "add"/"del" utility methods to builders.
+* {bug}5667[5667]: Incorrect use of format strings in generated code when backing type is an array (binding spec v2)
+
+
+[[enumeration-naming]]
+==== 2641: Enumeration value defined in yang model is translated without underscore
+
+
+==== Generate Equivalency for comparison of items by `key` and `unique`
+
+[[choice-case-childof]]
+==== ChildOf<> does not properly work with Choice / Case
+
+* {bug}1466[1466]: InstanceIdentifier is unable to represent Choice / Case, only children
+* {bug}1644[1644]: InstanceIdentifier does not properly capture choice-case child relationship
+
+[[list-mapping-semantics]]
+==== Mapping of list and leaf-list does not properly captures modeled semantic
+
+After analysis of specification, implementation of applications and
+MD-SAL, we found out that `list` and `leaf-list` keyword actually has three different
+behaviors based on combination of key and ordered-by statements.
+
+In order to correctly expose this to Binding Applications,
+representation in parent node should be extended to facilitate this
+mapping should be changed.
+
+.List mappings / behavior
+[cols=",,,",options="header",]
+|===
+|Key statement |Ordered-by |Behaviour |v2 Type
+|key is defined |system (default) |Unordered map |Map
+|key is defined |user |Ordered map |Map
+|key is not defined |-- |Ordered |List
+|===
+
+.Leaf list mapping / behavior
+[cols=",,",options="header",]
+|===
+|Ordered-by |Behaviour |v2 Type
+|system (default) |Unordered Distinct |Set
+|user |Ordered Distinct |Set
+|===
+
+
+
+
+[[empty-collections-instead-null]]
+==== 1097:Return an empty list and never null from list-valued parameters
+
+[[leaf-leaf-list-instance-identifiers]]
+==== Leaf, leaf-list Instance Identifiers
+
+Instance Identifier currently are constructed using classes as path
+arguments
+
+* is fine and allows for Instance Identifier to capture target type, but
+works only for *container* and *list*
+
+Instance Identifier needs to be extended to allow targeting:
+
+* leaves
+* choice and case statements
+
+[[proposed-solution-1]]
+Proposed solution
+
+Introduce *LeafPathArgument*. LeafPathArguments for leafes will be
+stored in interface describing parent container as constants.
+This will allow for use such as:
+
+[source, java]
+----
+InstanceIdentifier<Boolean> activePath = InstanceIdentifier.create(Foo.class).leaf(Foo.ACTIVE);
+ListenableFuture<Optional<Boolean>> active = tx.read(CONFIGURATION,activePath);
+----
+
+This will require changing signature of MD-SAL to allow Object in its
+interfaces if we want to read boolean directly.
+Other approach is to have special DTO which implements DataObject and
+encapsulates LeafValue, this will allow MD-SAL to still limit input
+to DataObject.
+
+
+[source, java]
+----
+InstanceIdentifier<LeafValue<Boolean>> activePath = InstanceIdentifier.create(Foo.class).leaf(Foo.ACTIVE);
+ListenableFuture<Optional<LeafValue<Boolean>>> active = tx.read(CONFIGURATION,activePath);
+----
+
+Note: Use of Optional is property of MD-SAL and not of Binding
+Specification
+
+
+==== Collections should be really immutable in immutable transfer objects
+
+
+=== Performance issues
+
+* {bug}3642[3642]: Improve equals() implementation
+* {bug}3147[3147]: auto generated code by YANGTOOLS could be more efficient.
+* {bug}5669[5669]: auto generated code by YANGTOOLS could be more efficient (binding spec. v2)
+
+
+=== Other
+
+* {bug}1478[1478]: Autoboxing support
+* {bug}1095[1095]: Simplify InstanceIdentifer creation
+* {bug}1117[1117]: Improve RPC API error handling
+* {bug}1459[1459]: Reorganize yang-binding
+* {bug}2289[2289]: Binding codegen: RFC6020 defines the order of evaluation for union members
+* {bug}5668[5668]: Binding codegen: RFC6020 defines the order of evaluation for union members (binding spec v2)
+
+
+
+
+
+
+
+
+
+[[yang-11-changes]]
+== Appendix 1: YANG 1.1 List of changes
+
+
+NOTE: This is verbatim copy of {rfc6020bis}##section-1.1[Section 1.1 of YANG 1.1 Draft]
+
+- Changed the YANG version from "1" to "1.1".
+- Made the `yang-version` statement mandatory.
+- Made noncharacters illegal in the built-in type `string`.
+- Defined the legal characters in YANG modules.
+- Changed the rules for the interpretation of escaped characters in
+ double quoted strings. This is an backwards incompatible change
+ from YANG version 1. A module that uses a character sequence that
+ is now illegal must change the string to match the new rules.
+- An unquoted string cannot contain any single or double quote
+ characters. This is an backwards incompatible change from YANG
+ version 1.
+- Extended the `if-feature` syntax to be a boolean expression over
+ feature names.
+- Allow `if-feature` in `bit`, `enum`, and `identity`.
+- Allow `if-feature` in `refine`.
+- Made `when` and `if-feature` illegal on list keys.
+- Allow `choice` as a shorthand case statement.
+- Added a new substatement `modifier` to pattern.
+- Allow `must` in `input`, `output`, and `notification`.
+- Allow `require-instance` in `leafref`.
+- Allow `augment` to add conditionally mandatory nodes.
+- Added a set of new XPath functions.
+- Clarified the XPath context's tree.
+- Defined the string value of an identityref in XPath expressions.
+- Clarified what unprefixed names mean in leafrefs in typedefs.
+- Allow identities to be derived from multiple base identities.
+- Allow enumerations and bits to be subtyped.
+- Allow leaf-lists to have default values.
+- Allow non-unique values in non-configuration leaf-lists.
+- Use [RFC7405] syntax for case-sensitive strings in the grammar.
+- Changed the module advertisement mechanism.
+- Changed the scoping rules for definitions in submodules. A
+ submodule can now reference all definitions in all submodules that
+ belong to the same module, without using the `include` statement.
+- Added a new statement `action` that is used to define operations
+ tied to data nodes.
+- Allow notifications to be tied to data nodes.
+- Added a new data definition statement `anydata`.
+- Allow types `empty` and `leafref` in unions.
+- Allow type `empty` in a `key`.
+
+
+[[yang-updating-module]]
+== Appendix 2: YANG 1.1 Updating a Module
+
+
+NOTE: _Italics text_ means section was added in YANG 1.1. This is verbatim
+copy of {rfc6020bis}#section-11[Section 11 of YANG 1.1 Draft]
+
+_As experience is gained with a module, it may be desirable to revise_
+that module. However, changes _to published modules_ are not allowed
+if they have any potential to cause interoperability problems between
+a client using an original specification and a server using an
+updated specification.
+
+For any published change, a new `revision` statement (Section 7.1.9)
+MUST be included in front of the existing `revision` statements. If
+there are no existing `revision` statements, then one MUST be added
+to identify the new revision. Furthermore, any necessary changes
+MUST be applied to any meta-data statements, including the
+`organization` and `contact` statements (Section 7.1.7,
+_Section 7.1.8)_.
+
+Note that definitions contained in a module are available to be
+imported by any other module, and are referenced in `import`
+statements via the module name. Thus, a module name MUST NOT be
+changed. Furthermore, the `namespace` statement MUST NOT be changed,
+since all XML elements are qualified by the namespace.
+
+Obsolete definitions MUST NOT be removed from _published_ modules since
+their identifiers may still be referenced by other modules.
+
+A definition _in a published module_ may be revised in any of the
+following ways:
+
+- An `enumeration` type may have new enums added, provided the old
+ enums's values do not change. _Note that inserting a new enum
+ before an existing enum or reordering existing enums will result
+ in new values for the existing enums, unless they have explicit
+ values assigned to them._
+
+- A `bits` type may have new bits added, provided the old bit
+ positions do not change. _Note that inserting a new bit before an
+ existing bit or reordering existing bit will result in new
+ positions for the existing bits, unless they have explicit
+ positions assigned to them._
+
+- A `range`, `length`, or `pattern` statement may expand the allowed
+ value space.
+
+- A `default` statement may be added to a leaf that does not have a
+ default value (either directly or indirectly through its type).
+
+- A `units` statement may be added.
+
+- A `reference` statement may be added or updated.
+
+- A `must` statement may be removed or its constraint relaxed.
+
+- _A `when` statement may be removed or its constraint relaxed._
+
+- A `mandatory` statement may be removed or changed from `true` to
+ `false`.
+
+- A `min-elements` statement may be removed, or changed to require
+ fewer elements.
+
+- A `max-elements` statement may be removed, or changed to allow
+ more elements.
+
+- A `description` statement may be added or clarified without
+ changing the semantics of the definition.
+
+- _A `base` statement may be added to an `identity` statement._
+
+- _A `base` statement may be removed from an `identityref` type,
+ provided there is at least one `base` statement left._
+
+- New typedefs, groupings, rpcs, notifications, extensions,
+ features, and identities may be added.
+
+- New data definition statements may be added if they do not add
+ mandatory nodes (Section 3) to existing nodes or at the top level
+ in a module or submodule, or if they are conditionally dependent
+ on a new feature (i.e., have an `if-feature` statement that refers
+ to a new feature).
+
+- A new `case` statement may be added.
+
+- A node that represented state data may be changed to represent
+ configuration, provided it is not mandatory (Section 3).
+
+- An `if-feature` statement may be removed, provided its node is not
+ mandatory (Section 3).
+
+- A `status` statement may be added, or changed from `current` to
+ `deprecated` or `obsolete`, or from `deprecated` to `obsolete`.
+
+- A `type` statement may be replaced with another `type` statement
+ that does not change the syntax or semantics of the type. For
+ example, an inline type definition may be replaced with a typedef,
+ but an int8 type cannot be replaced by an int16, since the syntax
+ would change.
+
+- Any set of data definition nodes may be replaced with another set
+ of syntactically and semantically equivalent nodes. For example,
+ a set of leafs may be replaced by a uses of a grouping with the
+ same leafs.
+
+- A module may be split into a set of submodules, or a submodule may
+ be removed, provided the definitions in the module do not change
+ in any other way than allowed here.
+
+- The `prefix` statement may be changed, provided all local uses of
+ the prefix also are changed.
+
+Otherwise, if the semantics of any previous definition are changed
+(i.e., if a non-editorial change is made to any definition other than
+those specifically allowed above), then this MUST be achieved by a
+new definition with a new identifier.
+
+In statements that have any data definition statements as
+substatements, those data definition substatements MUST NOT be
+reordered. _If new data definition statements are added, they can be
+added anywhere in the sequence of existing substatement._
+
+
+[[refactoring-model-example]]
+== Appendix 3: Refactoring YANG model example
+
+Design of binding specification version 2 in case of refactoring initial YANG model:
+
+Example 1a, 1b:
+[source,yang]
+----
+module foo1a {
+ namespace "urn:test:foo1a";
+ prefix f1a;
+
+ revision 2016-01-01 {
+ description "Initial YANG model";
+ }
+
+ container a {
+ container b {
+ container c {
+ }
+ }
+ }
+}
+
+module foo1b {
+ namespace "urn:test:foo1b";
+ prefix f1b;
+
+ revision 2016-01-01 {
+ description "First refactor only augment";
+ }
+
+ container a {
+ }
+
+ augment "/a" {
+ container b {
+ }
+ }
+
+ augment "/a/b" {
+ container c {
+ }
+ }
+}
+----
+Both previous modules foo1a & foo1b generate following instantiated Java structure:
+
+ getB getC
+data.A -> data.a.B -> data.a.b.C
+
+as augments become "invisible" in this one module context.
+
+Example 2a:
+----
+module foo2a {
+ namespace "urn:test:foo2a";
+ prefix f2b;
+
+ revision 2016-01-01 {
+ description "Second refactor one grouping";
+ }
+
+ grouping a {
+ container b {
+ container c {
+ }
+ }
+ }
+
+ container a {
+ uses a;
+ }
+}
+----
+In module foo2a, one grouping is added:
+----
+grp.A -> grp.a.B -> grp.a.bC
+ | getB | getC |
+data.A -> data.a.B -> data.a.b.C
+----
+
+Example 2b:
+----
+module foo2b {
+ namespace "urn:test:foo2b";
+ prefix f2;
+
+ revision 2016-01-01 {
+ description "Third refactor grouping augment";
+ }
+
+ grouping a {
+ container b {
+ }
+ }
+
+ container a {
+ uses a {
+ augment b {
+ container c {
+ }
+ }
+ }
+ }
+}
+----
+In module foo2b, one grouping and one augment is added:
+----
+grp.A -> grp.a.B
+ | getB | getC
+data.A -> data.a.B -> data.a.b.C
+----
+----
+module foo3 {
+ namespace "urn:test:foo3";
+ prefix f3;
+
+ revision 2016-01-01 {
+ description "Fourth refactor groupings only";
+ }
+
+ grouping a {
+ container b {
+ uses b;
+ }
+ }
+
+ grouping b {
+ container c {
+ }
+ }
+
+ container a {
+ uses a;
+ }
+}
+----
+----
+ grp B -> grp b.C
+ getB | getC |
+grp.A -> grp.a.B -> grp a.b.C
+ | getB | getC |
+data.A -> data.a.B -> data.a.b.C
+----
+
+* pros vs. binding spec v1:
+- well covered relations between elements
+- classes with same name in different packages (partially solves binding spec. v1 issue)
+
+* cons vs. binding spec v1:
+- higher amount of classes
+- higher memory consumption
+- amount of classes with same name (will be tackled by aliases)
+
+[[augmenting-model-example]]
+== Appendix 4: Augmenting YANG model example
+
+Design of binding specification version 2 in case of augment:
+
+* one YANG model
+----
+module foo1a {
+ namespace "urn:test:foo1a";
+ prefix f1a;
+
+ revision 2016-01-01 {
+ description "Default code";
+ }
+
+ container a {
+ container b {
+ container c {
+ }
+ }
+ container bar {
+ }
+ }
+}
+----
+or
+----
+module foo1b {
+ namespace "urn:test:foo1b";
+ prefix f1b;
+
+ revision 2016-01-01 {
+ description "First refactor, this code should look the same as the default code due
+ to the fact that these augments are in the same module";
+ }
+
+ container a {
+ }
+
+ augment a {
+ container b {
+ }
+ }
+
+ augment a {
+ container bar {
+ }
+ }
+
+ augment "/a/b" {
+ container c {
+ }
+ }
+}
+----
+Both previous modules foo1a & foo1b generate following instantiated Java structure:
+----
+A -> a.B -> a.b.C
+ -> a.Bar
+----
+* multiple YANG models
+----
+module foo2 {
+ namespace "urn:test:foo2";
+ prefix f2;
+
+ revision 2016-01-01 {
+ description "Augments of the same element should be put together";
+ }
+
+ import foo1a {
+ prefix f1;
+ revision-date 2016-01-01;
+ }
+
+ augment "/f1:a" {
+ container from-b {
+ }
+ }
+
+ augment "/f1:a/f1:b" {
+ container from-b-1 {
+ }
+ }
+
+ augment "/f1:a/f1:b" {
+ container from-b-2 {
+ }
+ }
+}
+----
+Previous module foo2 (alias "b") and foo1a (alias a) generates following instantiated java structure:
+----
+A -> a.B -> a.b.C
+ -> b.BB -> FromB1
+ -> FromB2
+ -> a.Bar
+ -> b.BA -> b.ba.FromB
+----
+
+[[dto-builder-example-snippet]]
+== Appendix 5: DTOs & builders
+DTO and builders needs to be in different packages
+----
+ container foo { class fooBuilder
+ }
+
+ container foo-builder { interface fooBuilder
+ }
+----
+
+----
+ list foo { data.Foo
+ key identifier; key.foo.FooIdentifier
+ leaf identifier {
+ type union { type.foo.identifier.IdentifierUnion
+ type string;
+ }
+ }
+ }
+
+ container foo-identifier { data.FooIdentifier
+ }
+
+ typedef foo-identifier { type.FooIdentifier
+ }
+----
+
+----
+ grouping nodes {
+ list node { for grouping key.grp.nodes.node.nodeidentifier
+ key id;
+ leaf id {
+ type leafref;
+ }
+ }
+ }
+
+ container nodes {
+ uses nodes; for instantiated key.data.nodes.node.nodeidentifier
+ }
+----
+
+[[mapping-example-snippet]]
+== Appendix 6: Various YANG model snippets & mappings
+----
+grouping A { -> grp.AGrouping
+ container B -> grp.a.BData
+ container B-DATA -> grp.a.BDataData
+}
+
+container A { -> data.A extends AGrouping
+ uses A; -> data.a.B extends BData
+ data.a.BData extends BDataData
+}
+----
+----
+grouping a { -> interface grp.AGrouping {
+ list b; List<? extends grp.a.BData>();
+} }
+
+container a { -> interface data.A extends AGrouping {
+ uses a; List<data.a.B> getB();
+} }
+----
\ No newline at end of file
Code Review / mdsal.git / blobdiff