binding2/mdsal-binding2-generator-impl/src/main/java/org/opendaylight/mdsal/binding/javav2/generator/impl/AuxiliaryGenUtils.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
   9 package org.opendaylight.mdsal.binding.javav2.generator.impl;
  10
  11 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingGeneratorUtil.encodeAngleBrackets;
  12 import static org.opendaylight.mdsal.binding.javav2.generator.util.Types.BOOLEAN;
  13
  14 import com.google.common.annotations.Beta;
  15 import com.google.common.annotations.VisibleForTesting;
  16 import com.google.common.base.Splitter;
  17 import com.google.common.base.Strings;
  18 import com.google.common.collect.Iterables;
  19 import java.util.List;
  20 import java.util.Map;
  21 import java.util.regex.Pattern;
  22 import org.opendaylight.mdsal.binding.javav2.generator.impl.txt.yangTemplateForModule;
  23 import org.opendaylight.mdsal.binding.javav2.generator.impl.txt.yangTemplateForNode;
  24 import org.opendaylight.mdsal.binding.javav2.generator.impl.util.YangTextTemplate;
  25 import org.opendaylight.mdsal.binding.javav2.generator.util.Types;
  26 import org.opendaylight.mdsal.binding.javav2.model.api.Constant;
  27 import org.opendaylight.mdsal.binding.javav2.model.api.Type;
  28 import org.opendaylight.mdsal.binding.javav2.model.api.type.builder.GeneratedTypeBuilder;
  29 import org.opendaylight.mdsal.binding.javav2.model.api.type.builder.GeneratedTypeBuilderBase;
  30 import org.opendaylight.mdsal.binding.javav2.model.api.type.builder.MethodSignatureBuilder;
  31 import org.opendaylight.mdsal.binding.javav2.util.BindingMapping;
  32 import org.opendaylight.yangtools.yang.common.QName;
  33 import org.opendaylight.yangtools.yang.model.api.ContainerSchemaNode;
  34 import org.opendaylight.yangtools.yang.model.api.ListSchemaNode;
  35 import org.opendaylight.yangtools.yang.model.api.Module;
  36 import org.opendaylight.yangtools.yang.model.api.NotificationDefinition;
  37 import org.opendaylight.yangtools.yang.model.api.RpcDefinition;
  38 import org.opendaylight.yangtools.yang.model.api.SchemaContext;
  39 import org.opendaylight.yangtools.yang.model.api.SchemaNode;
  40 import org.opendaylight.yangtools.yang.model.api.Status;
  41 import org.opendaylight.yangtools.yang.model.api.UnknownSchemaNode;
  42 import org.opendaylight.yangtools.yang.model.util.SchemaContextUtil;
  43
  44 /**
  45  * Auxiliary util class for {@link GenHelperUtil} class
  46  */
  47 @Beta
  48 final class AuxiliaryGenUtils {
  49
  50     private static final Splitter BSDOT_SPLITTER = Splitter.on("\\.");
  51     private static final char NEW_LINE = '\n';
  52     private static final Pattern UNICODE_CHAR_PATTERN = Pattern.compile("\\\\+u");
  53
  54     /**
  55      * Constant with the concrete name of identifier.
  56      */
  57     private static final String AUGMENT_IDENTIFIER_NAME = "augment-identifier";
  58
  59     /**
  60      * Constant with the concrete name of namespace.
  61      */
  62     private static final String YANG_EXT_NAMESPACE = "urn:opendaylight:yang:extension:yang-ext";
  63
  64     private AuxiliaryGenUtils() {
  65         throw new UnsupportedOperationException("Util class");
  66     }
  67
  68     static void annotateDeprecatedIfNecessary(final Status status, final GeneratedTypeBuilder builder) {
  69         if (status == Status.DEPRECATED) {
  70             builder.addAnnotation("", "Deprecated");
  71         }
  72     }
  73
  74     private static boolean hasBuilderClass(final SchemaNode schemaNode) {
  75         if (schemaNode instanceof ContainerSchemaNode || schemaNode instanceof ListSchemaNode ||
  76                 schemaNode instanceof RpcDefinition || schemaNode instanceof NotificationDefinition) {
  77             return true;
  78         }
  79         return false;
  80     }
  81
  82     static Constant qNameConstant(final GeneratedTypeBuilderBase<?> toBuilder, final String constantName,
  83                                   final QName name) {
  84         return toBuilder.addConstant(Types.typeForClass(QName.class), constantName, name);
  85     }
  86
  87     /**
  88      * Created a method signature builder as part of
  89      * <code>interfaceBuilder</code>.
  90      *
  91      * The method signature builder is created for the getter method of
  92      * <code>schemaNodeName</code>. Also <code>comment</code> and
  93      * <code>returnType</code> information are added to the builder.
  94      *
  95      * @param interfaceBuilder
  96      *            generated type builder for which the getter method should be
  97      *            created
  98      * @param schemaNodeName
  99      *            string with schema node name. The name will be the part of the
 100      *            getter method name.
 101      * @param comment
 102      *            string with comment for the getter method
 103      * @param returnType
 104      *            type which represents the return type of the getter method
 105      * @param status
 106      *            status from yang file, for deprecated annotation
 107      * @return method signature builder which represents the getter method of
 108      *         <code>interfaceBuilder</code>
 109      */
 110     static MethodSignatureBuilder constructGetter(final GeneratedTypeBuilder interfaceBuilder,
 111                                                   final String schemaNodeName, final String comment, final Type returnType, final Status status) {
 112
 113         final MethodSignatureBuilder getMethod = interfaceBuilder
 114                 .addMethod(getterMethodName(schemaNodeName, returnType));
 115         if (status == Status.DEPRECATED) {
 116             getMethod.addAnnotation("", "Deprecated");
 117         }
 118         getMethod.setComment(encodeAngleBrackets(comment));
 119         getMethod.setReturnType(returnType);
 120         return getMethod;
 121     }
 122
 123     /**
 124      * Creates the name of the getter method name from <code>localName</code>.
 125      *
 126      * @param localName
 127      *            string with the name of the getter method
 128      * @param returnType
 129      *            return type
 130      * @return string with the name of the getter method for
 131      *         <code>methodName</code> in JAVA method format
 132      */
 133     private static String getterMethodName(final String localName, final Type returnType) {
 134         final StringBuilder method = new StringBuilder();
 135         if (BOOLEAN.equals(returnType)) {
 136             method.append("is");
 137         } else {
 138             method.append("get");
 139         }
 140         final String name = BindingMapping.toFirstUpper(BindingMapping.getPropertyName(localName));
 141         method.append(name);
 142         return method.toString();
 143     }
 144
 145     static String createDescription(final SchemaNode schemaNode, final String fullyQualifiedName,
 146                                     final SchemaContext schemaContext, final boolean verboseClassComments) {
 147         final StringBuilder sb = new StringBuilder();
 148         final String nodeDescription = encodeAngleBrackets(schemaNode.getDescription());
 149         final String formattedDescription = YangTextTemplate.formatToParagraph(nodeDescription, 0);
 150
 151         if (!Strings.isNullOrEmpty(formattedDescription)) {
 152             sb.append(formattedDescription);
 153             sb.append(NEW_LINE);
 154         }
 155
 156         if (verboseClassComments) {
 157             final Module module = SchemaContextUtil.findParentModule(schemaContext, schemaNode);
 158             final StringBuilder linkToBuilderClass = new StringBuilder();
 159             final String[] namespace = Iterables.toArray(BSDOT_SPLITTER.split(fullyQualifiedName), String.class);
 160             final String className = namespace[namespace.length - 1];
 161
 162             if (hasBuilderClass(schemaNode)) {
 163                 linkToBuilderClass.append(className);
 164                 linkToBuilderClass.append("Builder");
 165             }
 166
 167             sb.append("<p>");
 168             sb.append("This class represents the following YANG schema fragment defined in module <b>");
 169             sb.append(module.getName());
 170             sb.append("</b>");
 171             sb.append(NEW_LINE);
 172             sb.append("<pre>");
 173             sb.append(NEW_LINE);
 174             sb.append(encodeAngleBrackets(yangTemplateForNode.render(schemaNode).body()));
 175             sb.append("</pre>");
 176             sb.append(NEW_LINE);
 177             sb.append("The schema path to identify an instance is");
 178             sb.append(NEW_LINE);
 179             sb.append("<i>");
 180             sb.append(YangTextTemplate.formatSchemaPath(module.getName(), schemaNode.getPath().getPathFromRoot()));
 181             sb.append("</i>");
 182             sb.append(NEW_LINE);
 183
 184             if (hasBuilderClass(schemaNode)) {
 185                 sb.append(NEW_LINE);
 186                 sb.append("<p>To create instances of this class use " + "{@link " + linkToBuilderClass + "}.");
 187                 sb.append(NEW_LINE);
 188                 sb.append("@see ");
 189                 sb.append(linkToBuilderClass);
 190                 sb.append(NEW_LINE);
 191                 if (schemaNode instanceof ListSchemaNode) {
 192                     final List<QName> keyDef = ((ListSchemaNode)schemaNode).getKeyDefinition();
 193                     if (keyDef != null && !keyDef.isEmpty()) {
 194                         sb.append("@see ");
 195                         sb.append(className);
 196                         sb.append("Key");
 197                     }
 198                     sb.append(NEW_LINE);
 199                 }
 200             }
 201         }
 202
 203         return replaceAllIllegalChars(sb);
 204     }
 205
 206     static String createDescription(final Module module, final boolean verboseClassComments) {
 207         final StringBuilder sb = new StringBuilder();
 208         final String moduleDescription = encodeAngleBrackets(module.getDescription());
 209         final String formattedDescription = YangTextTemplate.formatToParagraph(moduleDescription, 0);
 210
 211         if (!Strings.isNullOrEmpty(formattedDescription)) {
 212             sb.append(formattedDescription);
 213             sb.append(NEW_LINE);
 214         }
 215
 216         if (verboseClassComments) {
 217             sb.append("<p>");
 218             sb.append("This class represents the following YANG schema fragment defined in module <b>");
 219             sb.append(module.getName());
 220             sb.append("</b>");
 221             sb.append(NEW_LINE);
 222             sb.append("<pre>");
 223             sb.append(NEW_LINE);
 224             sb.append(encodeAngleBrackets(yangTemplateForModule.render(module).body()));
 225             sb.append("</pre>");
 226         }
 227
 228         return replaceAllIllegalChars(sb);
 229     }
 230
 231     /**
 232      * Returns first unique name for the augment generated type builder. The
 233      * generated type builder name for augment consists from name of augmented
 234      * node and serial number of its augmentation.
 235      *
 236      * @param builders
 237      *            map of builders which were created in the package to which the
 238      *            augmentation belongs
 239      * @param genTypeName
 240      *            string with name of augmented node
 241      * @return string with unique name for augmentation builder
 242      */
 243     static String augGenTypeName(final Map<String, GeneratedTypeBuilder> builders, final String genTypeName) {
 244         int index = 1;
 245         if (builders != null) {
 246             while (builders.containsKey(genTypeName + index)) {
 247                 index = index + 1;
 248             }
 249         }
 250         return genTypeName + index;
 251     }
 252
 253     /**
 254      * @param unknownSchemaNodes unknows schema nodes
 255      * @return nodeParameter of UnknownSchemaNode
 256      */
 257     static String getAugmentIdentifier(final List<UnknownSchemaNode> unknownSchemaNodes) {
 258         for (final UnknownSchemaNode unknownSchemaNode : unknownSchemaNodes) {
 259             final QName nodeType = unknownSchemaNode.getNodeType();
 260             if (AUGMENT_IDENTIFIER_NAME.equals(nodeType.getLocalName())
 261                     && YANG_EXT_NAMESPACE.equals(nodeType.getNamespace().toString())) {
 262                 return unknownSchemaNode.getNodeParameter();
 263             }
 264         }
 265         return null;
 266     }
 267
 268     @VisibleForTesting
 269     public static String replaceAllIllegalChars(final StringBuilder stringBuilder){
 270         final String ret = UNICODE_CHAR_PATTERN.matcher(stringBuilder).replaceAll("\\\\\\\\u");
 271         return ret.isEmpty() ? "" : ret;
 272     }
 273 }