binding2/mdsal-binding2-generator-util/src/main/java/org/opendaylight/mdsal/binding/javav2/generator/util/JavaIdentifierNormalizer.java

   1 /*
   2  * Copyright (c) 2017 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.javav2.generator.util;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.base.CharMatcher;
  12 import com.google.common.base.Splitter;
  13 import com.google.common.collect.ArrayListMultimap;
  14 import com.google.common.collect.ImmutableSet;
  15 import com.google.common.collect.ListMultimap;
  16 import java.util.Iterator;
  17 import java.util.List;
  18 import java.util.Set;
  19 import org.opendaylight.mdsal.binding.javav2.model.api.Enumeration;
  20 import org.opendaylight.mdsal.binding.javav2.model.api.Enumeration.Pair;
  21 import org.opendaylight.mdsal.binding.javav2.util.BindingMapping;
  22
  23 /**
  24  * This util class converts every non-java char in identifier to java char by
  25  * its unicode name (<a href=
  26  * "http://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.8">JAVA SE
  27  * SPECIFICATIONS - Identifiers</a>). There are special types of mapping
  28  * non-java chars to original identifiers according to specific
  29  * {@linkplain JavaIdentifier java type}:
  30  * <ul>
  31  * <li>class, enum, interface</li>
  32  * <li>
  33  * <ul>
  34  * <li>without special separator</li>
  35  * <li>the first character of identifier, any other first character of
  36  * identifier part mapped by non-Java char name from unicode and char in
  37  * identifier behind non-java char name are converting to upper case</li>
  38  * <li>examples:</li>
  39  * <li>
  40  * <ul>
  41  * <li>example* - ExampleAsterisk</li>
  42  * <li>example*example - ExampleAserisksExample</li>
  43  * <li>\example - ReverseSolidusExample</li>
  44  * <li>1example - DigitOneExample</li>
  45  * <li>example1 - Example1</li>
  46  * <li>int - IntReservedKeyword</li>
  47  * <li>con - ConReservedKeyword</li>
  48  * </ul>
  49  * </li>
  50  * </ul>
  51  * </li>
  52  * <li>enum value, constant</li>
  53  * <li>
  54  * <ul>
  55  * <li>used underscore as special separator</li>
  56  * <li>converted identifier to upper case</li>
  57  * <li>examples:</li>
  58  * <li>
  59  * <ul>
  60  * <li>example* - EXAMPLE_ASTERISK</li>
  61  * <li>example*example - EXAMPLE_ASTERISK_EXAMPLE</li>
  62  * <li>\example - REVERSE_SOLIDUS_EXAMPLE</li>
  63  * <li>1example - DIGIT_ONE_EXAMPLE</li>
  64  * <li>example1 - EXAMPLE1</li>
  65  * <li>int - INT_RESERVED_KEYWORD</li>
  66  * <li>con - CON_RESERVED_KEYWORD</li>
  67  * </ul>
  68  * </li>
  69  * </ul>
  70  * </li>
  71  * <li>method, variable</li>
  72  * <li>
  73  * <li>
  74  * <ul>
  75  * <li>without special separator</li>
  76  * <li>the first character of identifier is converting to lower case</li>
  77  * <li>any other first character of identifier part mapped by non-Java char name
  78  * from unicode and char in identifier behind non-java char name are converting
  79  * to upper case</li>
  80  * <li>examples:</li>
  81  * <li>
  82  * <ul>
  83  * <li>example* - exampleAsterisk</li>
  84  * <li>example*example - exampleAserisksExample</li>
  85  * <li>\example - reverseSolidusExample</li>
  86  * <li>1example - digitOneExample</li>
  87  * <li>example1 - example1</li>
  88  * <li>int - intReservedKeyword</li>
  89  * <li>con - conReservedKeyword</li>
  90  * </ul>
  91  * </li>
  92  * </ul>
  93  * </li>
  94  * <li>package - full package name (<a href=
  95  * "https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html">
  96  * Naming a package</a>)</li>
  97  * <li>
  98  * <li>
  99  * <ul>
 100  * <li>parts of package name are separated by dots</li>
 101  * <li>parts of package name are converting to lower case</li>
 102  * <li>if parts of package name are reserved Java or Windows keywords, such as
 103  * 'int' the suggested convention is to add an underscore to keyword</li>
 104  * <li>dash is parsed as underscore according to <a href=
 105  * "https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html">
 106  * Naming a package</a></li>
 107  * <li>examples:</li>
 108  * <li>
 109  * <ul>
 110  * <li>org.example* - org.exampleasterisk</li>
 111  * <li>org.example*example - org.exampleasteriskexample</li>
 112  * <li>org.\example - org.reversesolidusexample</li>
 113  * <li>org.1example - org.digitoneexample</li>
 114  * <li>org.example1 - org.example1</li>
 115  * <li>org.int - org.int_</li>
 116  * <li>org.con - org.con_</li>
 117  * <li>org.foo-cont - org.foo_cont</li>
 118  * </ul>
 119  * </li>
 120  * </ul>
 121  * </li>
 122  * </ul>
 123  *
 124  * There is special case in CLASS, INTERFACE, ENUM, ENUM VALUE, CONSTANT, METHOD
 125  * and VARIABLE if identifier contains single dash - then the converter ignores
 126  * the single dash in the way of the non-java chars. In other way, if dash is
 127  * the first or the last char in the identifier or there is more dashes in a row
 128  * in the identifier, then these dashes are converted as non-java chars.
 129  * Example:
 130  * <ul>
 131  * <li>class, enum, interface</li>
 132  * <li>
 133  * <ul>
 134  * <li>foo-cont - FooCont</li>
 135  * <li>foo--cont - FooHyphenMinusHyphenMinusCont</li>
 136  * <li>-foo - HyphenMinusFoo</li>
 137  * <li>foo- - FooHyphenMinus</li>
 138  * </ul>
 139  * </li>
 140  * <li>enum value, constant
 141  * <li>
 142  * <ul>
 143  * <li>foo-cont - FOO_CONT</li>
 144  * <li>foo--cont - FOO_HYPHEN_MINUS_HYPHEN_MINUS_CONT</li>
 145  * <li>-foo - HYPHEN_MINUS_FOO</li>
 146  * <li>foo- - FOO_HYPHEN_MINUS</li>
 147  * </ul>
 148  * </li>
 149  * <li>method, variable</li>
 150  * <li>
 151  * <ul>
 152  * <li>foo-cont - fooCont</li>
 153  * <li>foo--cont - fooHyphenMinusHyphenMinusCont</li>
 154  * <li>-foo - hyphenMinusFoo</li>
 155  * <li>foo- - fooHyphenMinus</li>
 156  * </ul>
 157  * </li>
 158  * </ul>
 159  *
 160  * Next special case talks about normalizing class name which already exists in
 161  * package - but with different camel cases (foo, Foo, fOo, ...). To every next
 162  * classes with same names will by added their actual rank (serial number),
 163  * except the first one. This working for CLASS, ENUM and INTEFACE java
 164  * identifiers. If there exist the same ENUM VALUES in ENUM (with different
 165  * camel cases), then it's parsed with same logic like CLASSES, ENUMS and
 166  * INTERFACES but according to list of pairs of their ENUM parent. Example:
 167  *
 168  * <ul>
 169  * <li>class, enum, interface</li>
 170  * <li>
 171  * <ul>
 172  * <li>package name org.example, class (or interface or enum) Foo - normalized
 173  * to Foo
 174  * <li>package name org.example, class (or interface or enum) fOo - normalized
 175  * to Foo1
 176  * </ul>
 177  * </li>
 178  * <li>enum value</li>
 179  * <li>
 180  * <ul>
 181  * <li>
 182  *
 183  * <pre>
 184  * type enumeration {
 185  *     enum foo;
 186  *     enum Foo;
 187  * }
 188  * </pre>
 189  *
 190  * </li>
 191  * <li>YANG enum values will be mapped to 'FOO' and 'FOO_1' Java enum
 192  * values.</li>
 193  * </ul>
 194  * </li>
 195  * </ul>
 196  */
 197 @Beta
 198 public final class JavaIdentifierNormalizer {
 199
 200     public static final Set<String> SPECIAL_RESERVED_PATHS = ImmutableSet.of(
 201         "org.opendaylight.yangtools.concepts",
 202         "org.opendaylight.yangtools.yang.common",
 203         "org.opendaylight.yangtools.yang.model",
 204         "org.opendaylight.mdsal.binding.javav2.spec",
 205         "java",
 206         "com");
 207
 208     private static final int FIRST_CHAR = 0;
 209     private static final int FIRST_INDEX = 1;
 210     private static final char UNDERSCORE = '_';
 211     private static final char DASH = '-';
 212     private static final String EMPTY_STRING = "";
 213     private static final String RESERVED_KEYWORD = "reserved_keyword";
 214     private static final ListMultimap<String, String> PACKAGES_MAP = ArrayListMultimap.create();
 215     private static final Set<String> PRIMITIVE_TYPES = ImmutableSet.of("char[]", "byte[]");
 216
 217     private static final CharMatcher DASH_MATCHER = CharMatcher.is(DASH);
 218     private static final CharMatcher DASH_OR_SPACE_MATCHER = CharMatcher.anyOf(" -");
 219     private static final Splitter DOT_SPLITTER = Splitter.on('.');
 220
 221     private JavaIdentifierNormalizer() {
 222         throw new UnsupportedOperationException("Util class");
 223     }
 224
 225     /**
 226      * <p>
 227      * According to <a href="https://tools.ietf.org/html/rfc7950#section-9.6.4">YANG RFC 7950</a>,
 228      * all assigned names in an enumeration MUST be unique. Created names are contained in the list
 229      * of {@link Enumeration.Pair}. This method adds actual index with underscore behind name of new
 230      * enum value only if this name already exists in one of the list of {@link Enumeration.Pair}.
 231      * Then, the name will be converted to java chars according to {@link JavaIdentifier#ENUM_VALUE}
 232      * and returned.
 233      * </p>
 234      * Example:
 235      *
 236      * <pre>
 237      * type enumeration {
 238      *     enum foo;
 239      *     enum Foo;
 240      * }
 241      * </pre>
 242      *
 243      * YANG enum values will be mapped to 'FOO' and 'FOO_1' Java enum values.
 244      *
 245      * @param name
 246      *            - name of new enum value
 247      * @param values
 248      *            - list of all actual enum values
 249      * @return converted and fixed name of new enum value
 250      */
 251     public static String normalizeEnumValueIdentifier(final String name, final List<Pair> values) {
 252         return convertIdentifierEnumValue(name, name, values, FIRST_INDEX);
 253     }
 254
 255     /**
 256      * Normalizing full package name by non java chars and reserved keywords.
 257      *
 258      * @param fullPackageName
 259      *            - full package name
 260      * @return normalized name
 261      */
 262     public static String normalizeFullPackageName(final String fullPackageName) {
 263         final Iterator<String> it = DOT_SPLITTER.split(fullPackageName).iterator();
 264         if (!it.hasNext()) {
 265             return fullPackageName;
 266         }
 267
 268         final StringBuilder sb = new StringBuilder(fullPackageName.length());
 269         while (true) {
 270             sb.append(normalizePartialPackageName(it.next()));
 271             if (!it.hasNext()) {
 272                 return sb.toString();
 273             }
 274             sb.append('.');
 275         }
 276     }
 277
 278     /**
 279      * Normalizing part of package name by non java chars.
 280      *
 281      * @param packageNamePart
 282      *            - part of package name
 283      * @return normalized name
 284      */
 285     public static String normalizePartialPackageName(final String packageNamePart) {
 286         // if part of package name consist from java or windows reserved word, return it with
 287         // underscore at the end and in lower case
 288         final String lowerPart = packageNamePart.toLowerCase();
 289         if (BindingMapping.JAVA_RESERVED_WORDS.contains(lowerPart)
 290                 || BindingMapping.WINDOWS_RESERVED_WORDS.contains(packageNamePart.toUpperCase())) {
 291             return lowerPart + UNDERSCORE;
 292         }
 293
 294         final String normalizedPart = DASH_MATCHER.replaceFrom(packageNamePart, UNDERSCORE);
 295
 296         final StringBuilder sb = new StringBuilder();
 297         final StringBuilder innerSb = new StringBuilder();
 298         for (int i = 0; i < normalizedPart.length(); i++) {
 299             final char c = normalizedPart.charAt(i);
 300             if (c == UNDERSCORE) {
 301                 if (innerSb.length() != 0) {
 302                     sb.append(normalizeSpecificIdentifier(innerSb.toString(), JavaIdentifier.PACKAGE));
 303                     innerSb.setLength(0);
 304                 }
 305                 sb.append(UNDERSCORE);
 306             } else {
 307                 innerSb.append(c);
 308             }
 309         }
 310         if (innerSb.length() != 0) {
 311             sb.append(normalizeSpecificIdentifier(innerSb.toString(), JavaIdentifier.PACKAGE));
 312         }
 313         // returned normalized part of package name
 314         return sb.toString();
 315     }
 316
 317     /**
 318      * Find and convert non Java chars in identifiers of generated transfer objects, initially
 319      * derived from corresponding YANG according to
 320      * <a href="http://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.8"> Java
 321      * Specifications - Identifiers</a>. If there is more same class names at the same package, then
 322      * append rank (serial number) to the end of them. Works for class, enum, interface.
 323      *
 324      * @param packageName
 325      *            - package of identifier
 326      * @param className
 327      *            - name of identifier
 328      * @return - java acceptable identifier
 329      */
 330     public static String normalizeClassIdentifier(final String packageName, final String className) {
 331         if (packageName.isEmpty() && PRIMITIVE_TYPES.contains(className)) {
 332             return className;
 333         }
 334         for (final String reservedPath : SPECIAL_RESERVED_PATHS) {
 335             if (packageName.startsWith(reservedPath)) {
 336                 return className;
 337             }
 338         }
 339         final String convertedClassName = normalizeSpecificIdentifier(className, JavaIdentifier.CLASS);
 340         // if packageName contains class name at the end, then the className is
 341         // name of inner class
 342         final String[] packageNameParts = packageName.split("\\.");
 343         String suppInnerClassPackageName = packageName;
 344         if (packageNameParts.length > 1) {
 345             if (Character.isUpperCase(packageNameParts[packageNameParts.length - 1].charAt(FIRST_CHAR))) {
 346                 final StringBuilder sb = new StringBuilder();
 347                 // ignore class name in package name - inner class name has
 348                 // to be normalizing according to original package of parent
 349                 // class
 350                 for (int i = 0; i < packageNameParts.length - 1; i++) {
 351                     if (!Character.isUpperCase(packageNameParts[i].charAt(FIRST_CHAR))) {
 352                         sb.append(packageNameParts[i]);
 353                         if (i != packageNameParts.length - 2 &&
 354                                 !Character.isUpperCase(packageNameParts[i+1].charAt(FIRST_CHAR))) {
 355                             sb.append('.');
 356                         }
 357                     } else {
 358                         break;
 359                     }
 360                 }
 361                 suppInnerClassPackageName = sb.toString();
 362             }
 363         }
 364
 365         return normalizeClassIdentifier(suppInnerClassPackageName, convertedClassName, convertedClassName, FIRST_INDEX);
 366     }
 367
 368     /**
 369      * Find and convert non Java chars in identifiers of generated transfer objects, initially
 370      * derived from corresponding YANG.
 371      *
 372      * @param identifier
 373      *            - name of identifier
 374      * @param javaIdentifier
 375      *            - java type of identifier
 376      * @return - java acceptable identifier
 377      */
 378     public static String normalizeSpecificIdentifier(final String identifier, final JavaIdentifier javaIdentifier) {
 379         final StringBuilder sb = new StringBuilder();
 380
 381         // if identifier isn't PACKAGE type then check it by reserved keywords
 382         if(javaIdentifier != JavaIdentifier.PACKAGE) {
 383             if (BindingMapping.JAVA_RESERVED_WORDS.contains(identifier.toLowerCase())
 384                     || BindingMapping.WINDOWS_RESERVED_WORDS.contains(identifier.toUpperCase())) {
 385                 return fixCasesByJavaType(
 386                         sb.append(identifier).append(UNDERSCORE).append(RESERVED_KEYWORD).toString().toLowerCase(),
 387                         javaIdentifier);
 388             }
 389         }
 390
 391         // check and convert first char in identifier if there is non-java char
 392         final char firstChar = identifier.charAt(FIRST_CHAR);
 393         if (!Character.isJavaIdentifierStart(firstChar)) {
 394             // converting first char of identifier
 395             sb.append(convertFirst(firstChar, existNext(identifier, FIRST_CHAR)));
 396         } else {
 397             sb.append(firstChar);
 398         }
 399         // check and convert other chars in identifier, if there is non-java char
 400         for (int i = 1; i < identifier.length(); i++) {
 401             final char actualChar = identifier.charAt(i);
 402             // ignore single dash as non java char - if there is more dashes in a row or dash is as
 403             // the last char in identifier then parse these dashes as non java chars
 404             if (actualChar == '-' && existNext(identifier, i)) {
 405                 if (identifier.charAt(i - 1) != DASH && identifier.charAt(i + 1) != DASH) {
 406                     sb.append(UNDERSCORE);
 407                     continue;
 408                 }
 409             }
 410             if (!Character.isJavaIdentifierPart(actualChar)) {
 411                 // prepare actual string of sb for checking if underscore exist on position of the
 412                 // last char
 413                 final String partialConvertedIdentifier = sb.toString();
 414                 sb.append(convert(actualChar, existNext(identifier, i),
 415                         partialConvertedIdentifier.charAt(partialConvertedIdentifier.length() - 1)));
 416             } else {
 417                 sb.append(actualChar);
 418             }
 419         }
 420         // apply camel case in appropriate way
 421         return fixCasesByJavaType(sb.toString().replace("__", "_").toLowerCase(), javaIdentifier);
 422     }
 423
 424     /**
 425      * Checking while there doesn't exist any class name with the same name
 426      * (regardless of camel cases) in package.
 427      *
 428      * @param packageName
 429      *            - package of class name
 430      * @param origClassName
 431      *            - original class name
 432      * @param actualClassName
 433      *            - actual class name with rank (serial number)
 434      * @param rank
 435      *            - actual rank (serial number)
 436      * @return converted identifier
 437      */
 438     private static String normalizeClassIdentifier(final String packageName, final String origClassName,
 439             final String actualClassName, final int rank) {
 440         if (PACKAGES_MAP.containsKey(packageName)) {
 441             for (final String existingName : PACKAGES_MAP.get(packageName)) {
 442                 if (existingName.toLowerCase().equals(actualClassName.toLowerCase())) {
 443                     final int nextRank = rank + 1;
 444                     return normalizeClassIdentifier(packageName, origClassName,
 445                             new StringBuilder(origClassName).append(rank).toString(), nextRank);
 446                 }
 447             }
 448         }
 449         PACKAGES_MAP.put(packageName, actualClassName);
 450         return actualClassName;
 451     }
 452
 453     /**
 454      * Fix cases of converted identifiers by Java type
 455      *
 456      * @param string
 457      *            - converted identifier
 458      * @param javaIdentifier
 459      *            - java type of identifier
 460      * @return converted identifier with right cases according to java type
 461      */
 462     private static String fixCasesByJavaType(final String convertedIdentifier, final JavaIdentifier javaIdentifier) {
 463         switch (javaIdentifier) {
 464             case CLASS:
 465             case ENUM:
 466             case INTERFACE:
 467                 return capitalize(fixCases(convertedIdentifier));
 468             case ENUM_VALUE:
 469             case CONSTANT:
 470                 return convertedIdentifier.toUpperCase();
 471             case METHOD:
 472             case VARIABLE:
 473                 return fixCases(convertedIdentifier);
 474             case PACKAGE:
 475                 return convertedIdentifier.replaceAll(String.valueOf(UNDERSCORE), EMPTY_STRING);
 476             default:
 477                 throw new IllegalArgumentException("Unknown java type of identifier : " + javaIdentifier.toString());
 478         }
 479     }
 480
 481     /**
 482      * Delete unnecessary chars in converted identifier and apply camel case in appropriate way.
 483      *
 484      * @param convertedIdentifier
 485      *            - original converted identifier
 486      * @return resolved identifier
 487      */
 488     private static String fixCases(final String convertedIdentifier) {
 489         final StringBuilder sb = new StringBuilder();
 490         if (convertedIdentifier.contains(String.valueOf(UNDERSCORE))) {
 491             boolean isFirst = true;
 492             for (final String part : convertedIdentifier.split(String.valueOf(UNDERSCORE))) {
 493                 if (isFirst) {
 494                     isFirst = false;
 495                     sb.append(part);
 496                 } else {
 497                     sb.append(capitalize(part));
 498                 }
 499             }
 500         } else {
 501             sb.append(convertedIdentifier);
 502         }
 503         return sb.toString();
 504     }
 505
 506     /**
 507      * Check if there exist next char in identifier behind actual char position
 508      *
 509      * @param identifier
 510      *            - original identifier
 511      * @param actual
 512      *            - actual char position
 513      * @return true if there is another char, false otherwise
 514      */
 515     private static boolean existNext(final String identifier, final int actual) {
 516         return identifier.length() > actual + 1;
 517     }
 518
 519     /**
 520      * Converting first char of identifier. This happen only if this char is
 521      * non-java char
 522      *
 523      * @param c
 524      *            - first char
 525      * @param existNext
 526      *            - existing of next char behind actual char
 527      * @return converted char
 528      */
 529     private static String convertFirst(final char c, final boolean existNext) {
 530         final String name = DASH_OR_SPACE_MATCHER.replaceFrom(Character.getName(c), UNDERSCORE);
 531         return existNext ? name + '_' : name;
 532     }
 533
 534     /**
 535      * Converting any char in java identifier, This happen only if this char is
 536      * non-java char
 537      *
 538      * @param c
 539      *            - actual char
 540      * @param existNext
 541      *            - existing of next char behind actual char
 542      * @param partialLastChar
 543      *            - last char of partial converted identifier
 544      * @return converted char
 545      */
 546     private static String convert(final char c, final boolean existNext, final char partialLastChar) {
 547         return partialLastChar == '_' ? convertFirst(c, existNext) : "_" + convertFirst(c, existNext);
 548     }
 549
 550     /**
 551      * Capitalize input string
 552      *
 553      * @param identifier
 554      *            - string to be capitalized
 555      */
 556     private static String capitalize(final String identifier) {
 557         return identifier.substring(FIRST_CHAR, FIRST_CHAR + 1).toUpperCase() + identifier.substring(1);
 558     }
 559
 560     private static String convertIdentifierEnumValue(final String name, final String origName, final List<Pair> values,
 561             final int rank) {
 562         String newName = name;
 563         for (final Pair pair : values) {
 564             if (pair.getName().toLowerCase().equals(name.toLowerCase())
 565                     || pair.getMappedName().toLowerCase().equals(name.toLowerCase())) {
 566                 int actualRank = rank;
 567                 final StringBuilder actualNameBuilder =
 568                         new StringBuilder(origName).append(UNDERSCORE).append(actualRank);
 569                 newName = convertIdentifierEnumValue(actualNameBuilder.toString(), origName, values, ++actualRank);
 570             }
 571         }
 572         return normalizeSpecificIdentifier(newName, JavaIdentifier.ENUM_VALUE);
 573     }
 574 }