X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=binding%2Fmdsal-binding-java-api-generator%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fmdsal%2Fbinding%2Fjava%2Fapi%2Fgenerator%2FBuilderTemplate.xtend;h=4e16bdba05153a9cb8ade207b3613d027c364f08;hb=03403f7c7422a1ab8be0e5fc256e4850463c4b18;hp=240a6515d7e3a25daf85e8916e91f6586b95481c;hpb=4fe6932b0f3911ee4a7684d3c9616efbbeb053a1;p=mdsal.git

diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderTemplate.xtend b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderTemplate.xtend
index 240a6515d7..4e16bdba05 100644
--- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderTemplate.xtend
+++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderTemplate.xtend
@@ -20,6 +20,7 @@ import java.util.List
 import java.util.Map
 import java.util.Set
 import java.util.regex.Pattern
+import org.opendaylight.mdsal.binding.model.api.AnnotationType
 import org.opendaylight.mdsal.binding.model.api.GeneratedProperty
 import org.opendaylight.mdsal.binding.model.api.GeneratedTransferObject
 import org.opendaylight.mdsal.binding.model.api.GeneratedType
@@ -43,6 +44,9 @@ class BuilderTemplate extends AbstractBuilderTemplate {
      */
     public static val BUILDER = "Builder";
 
+    static val AUGMENTATION_FIELD_UPPER = AUGMENTATION_FIELD.toFirstUpper
+    static val SUPPRESS_WARNINGS = JavaTypeName.create(SuppressWarnings)
+
     /**
      * Constructs new instance of this class.
      * @throws IllegalArgumentException if <code>genType</code> equals <code>null</code>
@@ -63,7 +67,8 @@ class BuilderTemplate extends AbstractBuilderTemplate {
      * @return string with JAVA source code
      */
     override body() '''
-        «wrapToDocumentation(formatDataForJavaDoc(type))»
+        «wrapToDocumentation(formatDataForJavaDoc(targetType))»
+        «targetType.annotations.generateDeprecatedAnnotation»
         public class «type.name» implements «Builder.importedName»<«targetType.importedName»> {
 
             «generateFields(false)»
@@ -97,6 +102,14 @@ class BuilderTemplate extends AbstractBuilderTemplate {
         }
     '''
 
+    override generateDeprecatedAnnotation(AnnotationType ann) {
+        val forRemoval = ann.getParameter("forRemoval")
+        if (forRemoval !== null) {
+            return "@" + DEPRECATED.importedName + "(forRemoval = " + forRemoval.value + ")"
+        }
+        return "@" + SUPPRESS_WARNINGS.importedName + "(\"deprecation\")"
+    }
+
     /**
      * Generate default constructor and constructor for every implemented interface from uses statements.
      */
@@ -245,8 +258,9 @@ class BuilderTemplate extends AbstractBuilderTemplate {
                 «val cValue = c.value as Map<String, String>»
                 «val String fieldSuffix = c.getName.substring(TypeConstants.PATTERN_CONSTANT_NAME.length)»
                 «IF cValue.size == 1»
-                   private static final «Pattern.importedName» «Constants.MEMBER_PATTERN_LIST»«fieldSuffix» = «Pattern.importedName».compile("«cValue.keySet.get(0).escapeJava»");
-                   private static final String «Constants.MEMBER_REGEX_LIST»«fieldSuffix» = "«cValue.values.get(0).escapeJava»";
+                   «val firstEntry = cValue.entrySet.iterator.next»
+                   private static final «Pattern.importedName» «Constants.MEMBER_PATTERN_LIST»«fieldSuffix» = «Pattern.importedName».compile("«firstEntry.key.escapeJava»");
+                   private static final String «Constants.MEMBER_REGEX_LIST»«fieldSuffix» = "«firstEntry.value.escapeJava»";
                 «ELSE»
                    private static final «Pattern.importedName»[] «Constants.MEMBER_PATTERN_LIST»«fieldSuffix» = «CodeHelpers.importedName».compilePatterns(«ImmutableList.importedName».of(
                    «FOR v : cValue.keySet SEPARATOR ", "»"«v.escapeJava»"«ENDFOR»));
@@ -259,6 +273,16 @@ class BuilderTemplate extends AbstractBuilderTemplate {
         «ENDFOR»
     '''
 
+    def private generateSetter(GeneratedProperty field) {
+        val returnType = field.returnType
+        if (returnType instanceof ParameterizedType) {
+            if (Types.isListType(returnType)) {
+                return generateListSetter(field, returnType.actualTypeArguments.get(0))
+            }
+        }
+        return generateSimpleSetter(field, returnType)
+    }
+
     def private generateListSetter(GeneratedProperty field, Type actualType) '''
         «val restrictions = restrictionsForSetter(actualType)»
         «IF restrictions !== null»
@@ -278,7 +302,7 @@ class BuilderTemplate extends AbstractBuilderTemplate {
 
     '''
 
-    def private generateSetter(GeneratedProperty field, Type actualType) '''
+    def private generateSimpleSetter(GeneratedProperty field, Type actualType) '''
         «val restrictions = restrictionsForSetter(actualType)»
         «IF restrictions !== null»
             «generateCheckers(field, restrictions, actualType)»
@@ -295,10 +319,6 @@ class BuilderTemplate extends AbstractBuilderTemplate {
         }
     '''
 
-    private def Type getActualType(ParameterizedType ptype) {
-        return ptype.getActualTypeArguments.get(0)
-    }
-
     /**
      * Template method which generates setter methods
      *
@@ -312,17 +332,14 @@ class BuilderTemplate extends AbstractBuilderTemplate {
             }
         «ENDIF»
         «FOR property : properties»
-            «IF property.returnType instanceof ParameterizedType && Types.isListType(property.returnType)»
-                «generateListSetter(property, getActualType(property.returnType as ParameterizedType))»
-            «ELSE»
-                «generateSetter(property, property.returnType)»
-            «ENDIF»
+            «generateSetter(property)»
         «ENDFOR»
 
         «IF augmentType !== null»
-            public «type.name» add«AUGMENTATION_FIELD.toFirstUpper»(«Class.importedName»<? extends «augmentType.importedName»> augmentationType, «augmentType.importedName» augmentationValue) {
+            «val augmentTypeRef = augmentType.importedName»
+            public «type.name» add«AUGMENTATION_FIELD_UPPER»(«Class.importedName»<? extends «augmentTypeRef»> augmentationType, «augmentTypeRef» augmentationValue) {
                 if (augmentationValue == null) {
-                    return remove«AUGMENTATION_FIELD.toFirstUpper»(augmentationType);
+                    return remove«AUGMENTATION_FIELD_UPPER»(augmentationType);
                 }
 
                 if (!(this.«AUGMENTATION_FIELD» instanceof «HashMap.importedName»)) {
@@ -333,7 +350,7 @@ class BuilderTemplate extends AbstractBuilderTemplate {
                 return this;
             }
 
-            public «type.name» remove«AUGMENTATION_FIELD.toFirstUpper»(«Class.importedName»<? extends «augmentType.importedName»> augmentationType) {
+            public «type.name» remove«AUGMENTATION_FIELD_UPPER»(«Class.importedName»<? extends «augmentTypeRef»> augmentationType) {
                 if (this.«AUGMENTATION_FIELD» instanceof «HashMap.importedName») {
                     this.«AUGMENTATION_FIELD».remove(augmentationType);
                 }
@@ -342,11 +359,45 @@ class BuilderTemplate extends AbstractBuilderTemplate {
         «ENDIF»
     '''
 
-    private def createDescription(GeneratedType type) {
+    private def createDescription(GeneratedType targetType) {
+        val target = type.importedName
         return '''
-        Class that builds {@link «type.importedName»} instances.
-
-        @see «type.importedName»
+        Class that builds {@link «target»} instances. Overall design of the class is that of a
+        <a href="https://en.wikipedia.org/wiki/Fluent_interface">fluent interface</a>, where method chaining is used.
+
+        <p>
+        In general, this class is supposed to be used like this template:
+        <pre>
+          <code>
+            «target» createTarget(int fooXyzzy, int barBaz) {
+                return new «target»Builder()
+                    .setFoo(new FooBuilder().setXyzzy(fooXyzzy).build())
+                    .setBar(new BarBuilder().setBaz(barBaz).build())
+                    .build();
+            }
+          </code>
+        </pre>
+
+        <p>
+        This pattern is supported by the immutable nature of «target», as instances can be freely passed around without
+        worrying about synchronization issues.
+
+        <p>
+        As a side note: method chaining results in:
+        <ul>
+          <li>very efficient Java bytecode, as the method invocation result, in this case the Builder reference, is
+              on the stack, so further method invocations just need to fill method arguments for the next method
+              invocation, which is terminated by {@link #build()}, which is then returned from the method</li>
+          <li>better understanding by humans, as the scope of mutable state (the builder) is kept to a minimum and is
+              very localized</li>
+          <li>better optimization oportunities, as the object scope is minimized in terms of invocation (rather than
+              method) stack, making <a href="https://en.wikipedia.org/wiki/Escape_analysis">escape analysis</a> a lot
+              easier. Given enough compiler (JIT/AOT) prowess, the cost of th builder object can be completely
+              eliminated</li>
+        </ul>
+
+        @see «target»
+        @see «Builder.importedName»
     '''
     }
 
@@ -361,7 +412,7 @@ class BuilderTemplate extends AbstractBuilderTemplate {
     }
 
     private def generateAugmentation() '''
-        @«SuppressWarnings.importedName»({ "unchecked", "checkstyle:methodTypeParameterName"})
+        @«SUPPRESS_WARNINGS.importedName»({ "unchecked", "checkstyle:methodTypeParameterName"})
         public <E$$ extends «augmentType.importedName»> E$$ «AUGMENTABLE_AUGMENTATION_NAME»(«Class.importedName»<E$$> augmentationType) {
             return (E$$) «AUGMENTATION_FIELD».get(«CodeHelpers.importedName».nonNullValue(augmentationType, "augmentationType"));
         }