binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/InterfaceTemplate.xtend

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.mdsal.binding.java.api.generator
   9
  10 import static extension org.opendaylight.mdsal.binding.spec.naming.BindingMapping.getGetterMethodForNonnull
  11 import static extension org.opendaylight.mdsal.binding.spec.naming.BindingMapping.getGetterMethodForRequire
  12 import static extension org.opendaylight.mdsal.binding.spec.naming.BindingMapping.isGetterMethodName
  13 import static extension org.opendaylight.mdsal.binding.spec.naming.BindingMapping.isNonnullMethodName
  14 import static extension org.opendaylight.mdsal.binding.spec.naming.BindingMapping.isRequireMethodName
  15 import static org.opendaylight.mdsal.binding.model.util.Types.BOOLEAN
  16 import static org.opendaylight.mdsal.binding.model.util.Types.STRING
  17 import static org.opendaylight.mdsal.binding.spec.naming.BindingMapping.REQUIRE_PREFIX
  18 import static org.opendaylight.mdsal.binding.spec.naming.BindingMapping.AUGMENTATION_FIELD
  19 import static org.opendaylight.mdsal.binding.spec.naming.BindingMapping.BINDING_EQUALS_NAME
  20 import static org.opendaylight.mdsal.binding.spec.naming.BindingMapping.BINDING_HASHCODE_NAME
  21 import static org.opendaylight.mdsal.binding.spec.naming.BindingMapping.BINDING_TO_STRING_NAME
  22 import static org.opendaylight.mdsal.binding.spec.naming.BindingMapping.DATA_CONTAINER_IMPLEMENTED_INTERFACE_NAME
  23
  24 import com.google.common.annotations.VisibleForTesting;
  25 import com.google.common.base.MoreObjects
  26 import java.util.List
  27 import java.util.Locale
  28 import java.util.Map.Entry
  29 import java.util.Set
  30 import org.gaul.modernizer_maven_annotations.SuppressModernizer
  31 import org.opendaylight.mdsal.binding.model.api.AnnotationType
  32 import org.opendaylight.mdsal.binding.model.api.Constant
  33 import org.opendaylight.mdsal.binding.model.api.Enumeration
  34 import org.opendaylight.mdsal.binding.model.api.GeneratedType
  35 import org.opendaylight.mdsal.binding.model.api.JavaTypeName
  36 import org.opendaylight.mdsal.binding.model.api.MethodSignature
  37 import org.opendaylight.mdsal.binding.model.api.Type
  38 import org.opendaylight.mdsal.binding.model.util.Types
  39 import org.opendaylight.mdsal.binding.model.util.TypeConstants
  40
  41 /**
  42  * Template for generating JAVA interfaces.
  43  */
  44  @SuppressModernizer
  45 class InterfaceTemplate extends BaseTemplate {
  46     /**
  47      * List of constant instances which are generated as JAVA public static final attributes.
  48      */
  49     val List<Constant> consts
  50
  51     /**
  52      * List of method signatures which are generated as method declarations.
  53      */
  54     val List<MethodSignature> methods
  55
  56     /**
  57      * List of enumeration which are generated as JAVA enum type.
  58      */
  59     val List<Enumeration> enums
  60
  61     /**
  62      * List of generated types which are enclosed inside <code>genType</code>
  63      */
  64     val List<GeneratedType> enclosedGeneratedTypes
  65
  66     var Entry<Type, Set<BuilderGeneratedProperty>> typeAnalysis
  67
  68     /**
  69      * Creates the instance of this class which is used for generating the interface file source
  70      * code from <code>genType</code>.
  71      *
  72      * @throws NullPointerException if <code>genType</code> is <code>null</code>
  73      */
  74     new(GeneratedType genType) {
  75         super(genType)
  76         consts = genType.constantDefinitions
  77         methods = genType.methodDefinitions
  78         enums = genType.enumerations
  79         enclosedGeneratedTypes = genType.enclosedTypes
  80     }
  81
  82     /**
  83      * Template method which generate the whole body of the interface.
  84      *
  85      * @return string with code for interface body in JAVA format
  86      */
  87     override body() '''
  88         «type.formatDataForJavaDoc.wrapToDocumentation»
  89         «type.annotations.generateAnnotations»
  90         «generatedAnnotation»
  91         public interface «type.name»
  92             «superInterfaces»
  93         {
  94
  95             «generateInnerClasses»
  96
  97             «generateEnums»
  98
  99             «generateConstants»
 100
 101             «generateMethods»
 102
 103         }
 104
 105     '''
 106
 107     def private generateAnnotations(List<AnnotationType> annotations) '''
 108         «IF annotations !== null && !annotations.empty»
 109             «FOR annotation : annotations»
 110                 «annotation.generateAnnotation»
 111             «ENDFOR»
 112         «ENDIF»
 113     '''
 114
 115     def private generateAccessorAnnotations(MethodSignature method) '''
 116          «val annotations = method.annotations»
 117          «IF annotations !== null && !annotations.empty»
 118              «FOR annotation : annotations»
 119                   «IF method.returnType != BOOLEAN || !(annotation.identifier == OVERRIDE)»
 120                       «annotation.generateAnnotation»
 121                   «ENDIF»
 122              «ENDFOR»
 123         «ENDIF»
 124     '''
 125
 126     /**
 127      * Template method which generates the interface name declaration.
 128      *
 129      * @return string with the code for the interface declaration in JAVA format
 130      */
 131     def private superInterfaces()
 132     '''
 133     «IF (!type.implements.empty)»
 134          extends
 135          «FOR type : type.implements SEPARATOR ","»
 136              «type.importedName»
 137          «ENDFOR»
 138      « ENDIF»
 139      '''
 140
 141     /**
 142      * Template method which generates inner classes inside this interface.
 143      *
 144      * @return string with the source code for inner classes in JAVA format
 145      */
 146     def private generateInnerClasses() '''
 147         «IF !enclosedGeneratedTypes.empty»
 148             «FOR innerClass : enclosedGeneratedTypes SEPARATOR "\n"»
 149                 «generateInnerClass(innerClass)»
 150             «ENDFOR»
 151         «ENDIF»
 152     '''
 153
 154     /**
 155      * Template method which generates JAVA enum type.
 156      *
 157      * @return string with inner enum source code in JAVA format
 158      */
 159     def private generateEnums() '''
 160         «IF !enums.empty»
 161             «FOR e : enums SEPARATOR "\n"»
 162                 «val enumTemplate = new EnumTemplate(javaType.getEnclosedType(e.identifier), e)»
 163                 «enumTemplate.generateAsInnerClass»
 164             «ENDFOR»
 165         «ENDIF»
 166     '''
 167
 168     /**
 169      * Template method wich generates JAVA constants.
 170      *
 171      * @return string with constants in JAVA format
 172      */
 173     def private generateConstants() '''
 174         «IF !consts.empty»
 175             «FOR c : consts»
 176                 «IF !c.name.startsWith(TypeConstants.PATTERN_CONSTANT_NAME)»
 177                     «emitConstant(c)»
 178                 «ENDIF»
 179             «ENDFOR»
 180         «ENDIF»
 181     '''
 182
 183     /**
 184      * Template method which generates the declaration of the methods.
 185      *
 186      * @return string with the declaration of methods source code in JAVA format
 187      */
 188     def private generateMethods() '''
 189         «IF !methods.empty»
 190             «FOR m : methods SEPARATOR "\n"»
 191                 «IF m.isDefault»
 192                     «generateDefaultMethod(m)»
 193                 «ELSEIF m.isStatic»
 194                     «generateStaticMethod(m)»
 195                 «ELSEIF m.parameters.empty && m.name.isGetterMethodName»
 196                     «generateAccessorMethod(m)»
 197                 «ELSE»
 198                     «generateMethod(m)»
 199                 «ENDIF»
 200             «ENDFOR»
 201         «ENDIF»
 202     '''
 203
 204     def private generateDefaultMethod(MethodSignature method) {
 205         if (method.name.isNonnullMethodName) {
 206             generateNonnullMethod(method)
 207         } else if (method.name.isRequireMethodName) {
 208             generateRequireMethod(method)
 209         } else {
 210             switch method.name {
 211                 case DATA_CONTAINER_IMPLEMENTED_INTERFACE_NAME : generateDefaultImplementedInterface
 212                 default :
 213                     if (VOID == method.returnType.identifier) {
 214                         generateNoopVoidInterfaceMethod(method)
 215                     }
 216             }
 217         }
 218     }
 219
 220     def private generateStaticMethod(MethodSignature method) {
 221         switch method.name {
 222             case BINDING_EQUALS_NAME : generateBindingEquals
 223             case BINDING_HASHCODE_NAME : generateBindingHashCode
 224             case BINDING_TO_STRING_NAME : generateBindingToString
 225         }
 226     }
 227
 228     def private generateMethod(MethodSignature method) '''
 229         «method.comment.asJavadoc»
 230         «method.annotations.generateAnnotations»
 231         «method.returnType.importedName» «method.name»(«method.parameters.generateParameters»);
 232     '''
 233
 234     def private generateNoopVoidInterfaceMethod(MethodSignature method) '''
 235         «method.comment.asJavadoc»
 236         «method.annotations.generateAnnotations»
 237         default «VOID.importedName» «method.name»(«method.parameters.generateParameters») {
 238             // No-op
 239         }
 240     '''
 241
 242     def private accessorJavadoc(MethodSignature method, String orString) {
 243         accessorJavadoc(method, orString, null)
 244     }
 245
 246     def private accessorJavadoc(MethodSignature method, String orString, JavaTypeName exception) {
 247         val propName = method.propertyNameFromGetter
 248         val propReturn = propName + orString
 249
 250         return wrapToDocumentation('''
 251             Return «propReturn»
 252
 253             «method.comment?.referenceDescription.formatReference»
 254             @return {@code «method.returnType.importedName»} «propReturn»
 255             «IF exception !== null»
 256                 @throws «exception.importedName» if «propName» is not present
 257             «ENDIF»
 258         ''')
 259     }
 260
 261     def private generateAccessorMethod(MethodSignature method) {
 262         return '''
 263             «accessorJavadoc(method, ", or {@code null} if it is not present.")»
 264             «method.generateAccessorAnnotations»
 265             «method.returnType.nullableType» «method.name»();
 266         '''
 267     }
 268
 269     def private generateDefaultImplementedInterface() '''
 270         @«OVERRIDE.importedName»
 271         default «CLASS.importedName»<«type.fullyQualifiedName»> «DATA_CONTAINER_IMPLEMENTED_INTERFACE_NAME»() {
 272             return «type.fullyQualifiedName».class;
 273         }
 274     '''
 275
 276     @VisibleForTesting
 277     def generateBindingHashCode() '''
 278         «val augmentable = analyzeType»
 279         «IF augmentable || !typeAnalysis.value.empty»
 280             /**
 281              * Default implementation of {@link «Object.importedName»#hashCode()} contract for this interface.
 282              * Implementations of this interface are encouraged to defer to this method to get consistent hashing
 283              * results across all implementations.
 284              *
 285              * @param obj Object for which to generate hashCode() result.
 286              * @return Hash code value of data modeled by this interface.
 287              * @throws «NPE.importedName» if {@code obj} is null
 288              */
 289             static int «BINDING_HASHCODE_NAME»(final «type.fullyQualifiedNonNull» obj) {
 290                 final int prime = 31;
 291                 int result = 1;
 292                 «FOR property : typeAnalysis.value»
 293                     result = prime * result + «property.importedUtilClass».hashCode(obj.«property.getterMethodName»());
 294                 «ENDFOR»
 295                 «IF augmentable»
 296                     for (var augmentation : obj.augmentations().values()) {
 297                         result += augmentation.hashCode();
 298                     }
 299                 «ENDIF»
 300                 return result;
 301             }
 302         «ENDIF»
 303     '''
 304
 305     def private generateBindingEquals() '''
 306         «val augmentable = analyzeType»
 307         «IF augmentable || !typeAnalysis.value.isEmpty»
 308             /**
 309              * Default implementation of {@link «Object.importedName»#equals(«Object.importedName»)} contract for this interface.
 310              * Implementations of this interface are encouraged to defer to this method to get consistent equality
 311              * results across all implementations.
 312              *
 313              * @param thisObj Object acting as the receiver of equals invocation
 314              * @param obj Object acting as argument to equals invocation
 315              * @return True if thisObj and obj are considered equal
 316              * @throws «NPE.importedName» if {@code thisObj} is null
 317              */
 318             static boolean «BINDING_EQUALS_NAME»(final «type.fullyQualifiedNonNull» thisObj, final «Types.objectType().importedName» obj) {
 319                 if (thisObj == obj) {
 320                     return true;
 321                 }
 322                 final «type.fullyQualifiedName» other = «CODEHELPERS.importedName».checkCast(«type.fullyQualifiedName».class, obj);
 323                 if (other == null) {
 324                     return false;
 325                 }
 326                 «FOR property : ByTypeMemberComparator.sort(typeAnalysis.value)»
 327                     if (!«property.importedUtilClass».equals(thisObj.«property.getterName»(), other.«property.getterName»())) {
 328                         return false;
 329                     }
 330                 «ENDFOR»
 331                 return «IF augmentable»thisObj.augmentations().equals(other.augmentations())«ELSE»true«ENDIF»;
 332             }
 333         «ENDIF»
 334     '''
 335
 336     def generateBindingToString() '''
 337         «val augmentable = analyzeType»
 338         /**
 339          * Default implementation of {@link «Object.importedName»#toString()} contract for this interface.
 340          * Implementations of this interface are encouraged to defer to this method to get consistent string
 341          * representations across all implementations.
 342          *
 343          * @param obj Object for which to generate toString() result.
 344          * @return {@link «STRING.importedName»} value of data modeled by this interface.
 345          * @throws «NPE.importedName» if {@code obj} is null
 346          */
 347         static «STRING.importedName» «BINDING_TO_STRING_NAME»(final «type.fullyQualifiedNonNull» obj) {
 348             final «MoreObjects.importedName».ToStringHelper helper = «MoreObjects.importedName».toStringHelper("«type.name»");
 349             «FOR property : typeAnalysis.value»
 350                 «CODEHELPERS.importedName».appendValue(helper, "«property.name»", obj.«property.getterName»());
 351             «ENDFOR»
 352             «IF augmentable»
 353                 «CODEHELPERS.importedName».appendValue(helper, "«AUGMENTATION_FIELD»", obj.augmentations().values());
 354             «ENDIF»
 355             return helper.toString();
 356         }
 357     '''
 358
 359     def private generateNonnullMethod(MethodSignature method) '''
 360         «val ret = method.returnType»
 361         «val name = method.name»
 362         «accessorJavadoc(method, ", or an empty list if it is not present.")»
 363         «method.annotations.generateAnnotations»
 364         default «ret.importedNonNull» «name»() {
 365             return «CODEHELPERS.importedName».nonnull(«name.getGetterMethodForNonnull»());
 366         }
 367     '''
 368
 369     def private generateRequireMethod(MethodSignature method) '''
 370         «val ret = method.returnType»
 371         «val name = method.name»
 372         «val fieldName = name.toLowerCase(Locale.ROOT).replace(REQUIRE_PREFIX, "")»
 373         «accessorJavadoc(method, ", guaranteed to be non-null.", NSEE)»
 374         default «ret.importedNonNull» «name»() {
 375             return «CODEHELPERS.importedName».require(«getGetterMethodForRequire(name)»(), "«fieldName»");
 376         }
 377     '''
 378
 379     def private String nullableType(Type type) {
 380         if (type.isObject && (Types.isMapType(type) || Types.isListType(type))) {
 381             return type.importedNullable
 382         }
 383         return type.importedName
 384     }
 385
 386     def private static boolean isObject(Type type) {
 387         // The return type has a package, so it's not a primitive type
 388         return !type.getPackageName().isEmpty()
 389     }
 390
 391     private def boolean analyzeType() {
 392         if (typeAnalysis === null) {
 393             typeAnalysis = analyzeTypeHierarchy(type)
 394         }
 395         typeAnalysis.key !== null
 396     }
 397 }