binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/BindingMapping.java

   1 /*
   2  * Copyright (c) 2013 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.yangtools.yang.binding;
   9
  10 import static com.google.common.base.Preconditions.checkArgument;
  11
  12 import com.google.common.base.CharMatcher;
  13 import com.google.common.base.Splitter;
  14 import com.google.common.collect.BiMap;
  15 import com.google.common.collect.HashBiMap;
  16 import com.google.common.collect.ImmutableSet;
  17 import com.google.common.collect.Interner;
  18 import com.google.common.collect.Interners;
  19 import java.util.Collection;
  20 import java.util.Locale;
  21 import java.util.Optional;
  22 import java.util.Set;
  23 import java.util.regex.Matcher;
  24 import java.util.regex.Pattern;
  25 import org.opendaylight.yangtools.yang.common.QName;
  26 import org.opendaylight.yangtools.yang.common.QNameModule;
  27 import org.opendaylight.yangtools.yang.common.Revision;
  28
  29 public final class BindingMapping {
  30
  31     public static final String VERSION = "0.6";
  32
  33     public static final Set<String> JAVA_RESERVED_WORDS = ImmutableSet.of(
  34         // https://docs.oracle.com/javase/specs/jls/se9/html/jls-3.html#jls-3.9
  35         "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", "const", "continue",
  36         "default", "do", "double", "else", "enum", "extends", "final", "finally", "float", "for", "goto", "if",
  37         "implements", "import", "instanceof", "int", "interface", "long", "native", "new", "package", "private",
  38         "protected", "public", "return", "short", "static", "strictfp", "super", "switch", "synchronized", "this",
  39         "throw", "throws", "transient", "try", "void", "volatile", "while", "_",
  40         // https://docs.oracle.com/javase/specs/jls/se9/html/jls-3.html#jls-3.10.3
  41         "false", "true",
  42         // https://docs.oracle.com/javase/specs/jls/se9/html/jls-3.html#jls-3.10.7
  43         "null");
  44
  45     public static final String DATA_ROOT_SUFFIX = "Data";
  46     public static final String RPC_SERVICE_SUFFIX = "Service";
  47     public static final String NOTIFICATION_LISTENER_SUFFIX = "Listener";
  48     public static final String QNAME_STATIC_FIELD_NAME = "QNAME";
  49     public static final String PACKAGE_PREFIX = "org.opendaylight.yang.gen.v1";
  50     public static final String AUGMENTATION_FIELD = "augmentation";
  51
  52     private static final Splitter CAMEL_SPLITTER = Splitter.on(CharMatcher.anyOf(" _.-/").precomputed())
  53             .omitEmptyStrings().trimResults();
  54     private static final Pattern COLON_SLASH_SLASH = Pattern.compile("://", Pattern.LITERAL);
  55     private static final String QUOTED_DOT = Matcher.quoteReplacement(".");
  56     private static final Splitter DOT_SPLITTER = Splitter.on('.');
  57
  58     public static final String MODULE_INFO_CLASS_NAME = "$YangModuleInfoImpl";
  59     public static final String MODEL_BINDING_PROVIDER_CLASS_NAME = "$YangModelBindingProvider";
  60
  61     public static final String RPC_INPUT_SUFFIX = "Input";
  62     public static final String RPC_OUTPUT_SUFFIX = "Output";
  63
  64     private static final String NEGATED_PATTERN_PREFIX = "^(?!";
  65     private static final String NEGATED_PATTERN_SUFFIX = ").*$";
  66
  67     private static final Interner<String> PACKAGE_INTERNER = Interners.newWeakInterner();
  68
  69     private BindingMapping() {
  70         throw new UnsupportedOperationException("Utility class should not be instantiated");
  71     }
  72
  73     public static String getRootPackageName(final QName module) {
  74         return getRootPackageName(module.getModule());
  75     }
  76
  77     public static String getRootPackageName(final QNameModule module) {
  78         checkArgument(module != null, "Module must not be null");
  79         checkArgument(module.getRevision() != null, "Revision must not be null");
  80         checkArgument(module.getNamespace() != null, "Namespace must not be null");
  81         final StringBuilder packageNameBuilder = new StringBuilder();
  82
  83         packageNameBuilder.append(BindingMapping.PACKAGE_PREFIX);
  84         packageNameBuilder.append('.');
  85
  86         String namespace = module.getNamespace().toString();
  87         namespace = COLON_SLASH_SLASH.matcher(namespace).replaceAll(QUOTED_DOT);
  88
  89         final char[] chars = namespace.toCharArray();
  90         for (int i = 0; i < chars.length; ++i) {
  91             switch (chars[i]) {
  92                 case '/':
  93                 case ':':
  94                 case '-':
  95                 case '@':
  96                 case '$':
  97                 case '#':
  98                 case '\'':
  99                 case '*':
 100                 case '+':
 101                 case ',':
 102                 case ';':
 103                 case '=':
 104                     chars[i] = '.';
 105                     break;
 106                 default:
 107                     // no-op
 108             }
 109         }
 110
 111         packageNameBuilder.append(chars);
 112         if (chars[chars.length - 1] != '.') {
 113             packageNameBuilder.append('.');
 114         }
 115
 116         final Optional<Revision> optRev = module.getRevision();
 117         if (optRev.isPresent()) {
 118             // Revision is in format 2017-10-26, we want the output to be 171026, which is a matter of picking the
 119             // right characters.
 120             final String rev = optRev.get().toString();
 121             checkArgument(rev.length() == 10, "Unsupported revision %s", rev);
 122             packageNameBuilder.append("rev");
 123             packageNameBuilder.append(rev.substring(2, 4)).append(rev.substring(5, 7)).append(rev.substring(8));
 124         } else {
 125             // No-revision packages are special
 126             packageNameBuilder.append("norev");
 127         }
 128
 129         return normalizePackageName(packageNameBuilder.toString());
 130     }
 131
 132     public static String normalizePackageName(final String packageName) {
 133         if (packageName == null) {
 134             return null;
 135         }
 136
 137         final StringBuilder builder = new StringBuilder();
 138         boolean first = true;
 139
 140         for (String p : DOT_SPLITTER.split(packageName.toLowerCase())) {
 141             if (first) {
 142                 first = false;
 143             } else {
 144                 builder.append('.');
 145             }
 146
 147             if (Character.isDigit(p.charAt(0)) || BindingMapping.JAVA_RESERVED_WORDS.contains(p)) {
 148                 builder.append('_');
 149             }
 150             builder.append(p);
 151         }
 152
 153         // Prevent duplication of input string
 154         return PACKAGE_INTERNER.intern(builder.toString());
 155     }
 156
 157     public static String getClassName(final String localName) {
 158         checkArgument(localName != null, "Name should not be null.");
 159         return toFirstUpper(toCamelCase(localName));
 160     }
 161
 162     public static String getClassName(final QName name) {
 163         checkArgument(name != null, "Name should not be null.");
 164         return toFirstUpper(toCamelCase(name.getLocalName()));
 165     }
 166
 167     public static String getMethodName(final String yangIdentifier) {
 168         checkArgument(yangIdentifier != null,"Identifier should not be null");
 169         return toFirstLower(toCamelCase(yangIdentifier));
 170     }
 171
 172     public static String getMethodName(final QName name) {
 173         checkArgument(name != null, "Name should not be null.");
 174         return getMethodName(name.getLocalName());
 175     }
 176
 177     public static String getGetterSuffix(final QName name) {
 178         checkArgument(name != null, "Name should not be null.");
 179         final String candidate = toFirstUpper(toCamelCase(name.getLocalName()));
 180         return "Class".equals(candidate) ? "XmlClass" : candidate;
 181     }
 182
 183     public static String getPropertyName(final String yangIdentifier) {
 184         final String potential = toFirstLower(toCamelCase(yangIdentifier));
 185         if ("class".equals(potential)) {
 186             return "xmlClass";
 187         }
 188         return potential;
 189     }
 190
 191     private static String toCamelCase(final String rawString) {
 192         checkArgument(rawString != null, "String should not be null");
 193         Iterable<String> components = CAMEL_SPLITTER.split(rawString);
 194         StringBuilder builder = new StringBuilder();
 195         for (String comp : components) {
 196             builder.append(toFirstUpper(comp));
 197         }
 198         return checkNumericPrefix(builder.toString());
 199     }
 200
 201     private static String checkNumericPrefix(final String rawString) {
 202         if (rawString == null || rawString.isEmpty()) {
 203             return rawString;
 204         }
 205         char firstChar = rawString.charAt(0);
 206         if (firstChar >= '0' && firstChar <= '9') {
 207             return "_" + rawString;
 208         } else {
 209             return rawString;
 210         }
 211     }
 212
 213     /**
 214      * Create a {@link Pattern} expression which performs inverted match to the specified pattern. The input pattern
 215      * is expected to be a valid regular expression passing {@link Pattern#compile(String)} and to have both start and
 216      * end of string anchors as the first and last characters.
 217      *
 218      * @param pattern Pattern regular expression to negate
 219      * @return Negated regular expression
 220      * @throws IllegalArgumentException if the pattern does not conform to expected structure
 221      * @throws NullPointerException if pattern is null
 222      */
 223     public static String negatePatternString(final String pattern) {
 224         checkArgument(pattern.charAt(0) == '^' && pattern.charAt(pattern.length() - 1) == '$',
 225                 "Pattern '%s' does not have expected format", pattern);
 226
 227         /*
 228          * Converting the expression into a negation is tricky. For example, when we have:
 229          *
 230          *   pattern "a|b" { modifier invert-match; }
 231          *
 232          * this gets escaped into either "^a|b$" or "^(?:a|b)$". Either format can occur, as the non-capturing group
 233          * strictly needed only in some cases. From that we want to arrive at:
 234          *   "^(?!(?:a|b)$).*$".
 235          *
 236          *           ^^^         original expression
 237          *        ^^^^^^^^       tail of a grouped expression (without head anchor)
 238          *    ^^^^        ^^^^   inversion of match
 239          *
 240          * Inversion works by explicitly anchoring at the start of the string and then:
 241          * - specifying a negative lookahead until the end of string
 242          * - matching any string
 243          * - anchoring at the end of the string
 244          */
 245         final boolean hasGroup = pattern.startsWith("^(?:") && pattern.endsWith(")$");
 246         final int len = pattern.length();
 247         final StringBuilder sb = new StringBuilder(len + (hasGroup ? 7 : 11)).append(NEGATED_PATTERN_PREFIX);
 248
 249         if (hasGroup) {
 250             sb.append(pattern, 1, len);
 251         } else {
 252             sb.append("(?:").append(pattern, 1, len - 1).append(")$");
 253         }
 254         return sb.append(NEGATED_PATTERN_SUFFIX).toString();
 255     }
 256
 257     /**
 258      * Check if the specified {@link Pattern} is the result of {@link #negatePatternString(String)}. This method
 259      * assumes the pattern was not hand-coded but rather was automatically-generated, such that its non-automated
 260      * parts come from XSD regular expressions. If this constraint is violated, this method may result false positives.
 261      *
 262      * @param pattern Pattern to check
 263      * @return True if this pattern is a negation.
 264      * @throws NullPointerException if pattern is null
 265      * @throws IllegalArgumentException if the pattern does not conform to expected structure
 266      */
 267     public static boolean isNegatedPattern(final Pattern pattern) {
 268         return isNegatedPattern(pattern.toString());
 269     }
 270
 271     private static boolean isNegatedPattern(final String pattern) {
 272         return pattern.startsWith(NEGATED_PATTERN_PREFIX) && pattern.endsWith(NEGATED_PATTERN_SUFFIX);
 273     }
 274
 275     /**
 276      * Returns the {@link String} {@code s} with an {@link Character#isUpperCase(char) upper case} first character. This
 277      * function is null-safe.
 278      *
 279      * @param str the string that should get an upper case first character. May be <code>null</code>.
 280      * @return the {@link String} {@code str} with an upper case first character or <code>null</code> if the input
 281      *         {@link String} {@code str} was <code>null</code>.
 282      */
 283     public static String toFirstUpper(final String str) {
 284         if (str == null || str.length() == 0) {
 285             return str;
 286         }
 287         if (Character.isUpperCase(str.charAt(0))) {
 288             return str;
 289         }
 290         if (str.length() == 1) {
 291             return str.toUpperCase();
 292         }
 293         return str.substring(0, 1).toUpperCase() + str.substring(1);
 294     }
 295
 296     /**
 297      * Returns the {@link String} {@code s} with a {@link Character#isLowerCase(char) lower case} first character. This
 298      * function is null-safe.
 299      *
 300      * @param str the string that should get an lower case first character. May be <code>null</code>.
 301      * @return the {@link String} {@code str} with an lower case first character or <code>null</code> if the input
 302      *         {@link String} {@code str} was <code>null</code>.
 303      */
 304     private static String toFirstLower(final String str) {
 305         if (str == null || str.length() == 0) {
 306             return str;
 307         }
 308         if (Character.isLowerCase(str.charAt(0))) {
 309             return str;
 310         }
 311         if (str.length() == 1) {
 312             return str.toLowerCase();
 313         }
 314         return str.substring(0, 1).toLowerCase() + str.substring(1);
 315     }
 316
 317     /**
 318      * Returns Java identifiers, conforming to JLS9 Section 3.8 to use for specified YANG assigned names
 319      * (RFC7950 Section 9.6.4). This method considers two distinct encodings: one the pre-Fluorine mapping, which is
 320      * okay and convenient for sane strings, and an escaping-based bijective mapping which works for all possible
 321      * Unicode strings.
 322      *
 323      * @param assignedNames Collection of assigned names
 324      * @return A BiMap keyed by assigned name, with Java identifiers as values
 325      * @throws NullPointerException if assignedNames is null or contains null items
 326      * @throws IllegalArgumentException if any of the names is empty
 327      */
 328     public static BiMap<String, String> mapEnumAssignedNames(final Collection<String> assignedNames) {
 329         /*
 330          * Original mapping assumed strings encountered are identifiers, hence it used getClassName to map the names
 331          * and that function is not an injection -- this is evidenced in MDSAL-208 and results in a failure to compile
 332          * generated code. If we encounter such a conflict or if the result is not a valid identifier (like '*'), we
 333          * abort and switch the mapping schema to mapEnumAssignedName(), which is a bijection.
 334          *
 335          * Note that assignedNames can contain duplicates, which must not trigger a duplication fallback.
 336          */
 337         final BiMap<String, String> javaToYang = HashBiMap.create(assignedNames.size());
 338         boolean valid = true;
 339         for (String name : assignedNames) {
 340             checkArgument(!name.isEmpty());
 341             if (!javaToYang.containsValue(name)) {
 342                 final String mappedName = getClassName(name);
 343                 if (!isValidJavaIdentifier(mappedName) || javaToYang.forcePut(mappedName, name) != null) {
 344                     valid = false;
 345                     break;
 346                 }
 347             }
 348         }
 349
 350         if (!valid) {
 351             // Fall back to bijective mapping
 352             javaToYang.clear();
 353             for (String name : assignedNames) {
 354                 javaToYang.put(mapEnumAssignedName(name), name);
 355             }
 356         }
 357
 358         return javaToYang.inverse();
 359     }
 360
 361     // See https://docs.oracle.com/javase/specs/jls/se9/html/jls-3.html#jls-3.8
 362     private static boolean isValidJavaIdentifier(final String str) {
 363         return !str.isEmpty() && !JAVA_RESERVED_WORDS.contains(str)
 364                 && Character.isJavaIdentifierStart(str.codePointAt(0))
 365                 && str.codePoints().skip(1).allMatch(Character::isJavaIdentifierPart);
 366     }
 367
 368     private static String mapEnumAssignedName(final String assignedName) {
 369         checkArgument(!assignedName.isEmpty());
 370
 371         // Mapping rules:
 372         // - if the string is a valid java identifier and does not contain '$', use it as-is
 373         if (assignedName.indexOf('$') == -1 && isValidJavaIdentifier(assignedName)) {
 374             return assignedName;
 375         }
 376
 377         // - otherwise prefix it with '$' and replace any invalid character (including '$') with '$XX$', where XX is
 378         //   hex-encoded unicode codepoint (including plane, stripping leading zeroes)
 379         final StringBuilder sb = new StringBuilder().append('$');
 380         assignedName.codePoints().forEachOrdered(codePoint -> {
 381             if (codePoint == '$' || !Character.isJavaIdentifierPart(codePoint)) {
 382                 sb.append('$').append(Integer.toHexString(codePoint).toUpperCase(Locale.ROOT)).append('$');
 383             } else {
 384                 sb.appendCodePoint(codePoint);
 385             }
 386         });
 387         return sb.toString();
 388     }
 389 }