binding2/mdsal-binding2-generator-impl/src/main/java/org/opendaylight/mdsal/binding/javav2/generator/impl/RpcActionGenHelper.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 com.google.common.base.Preconditions.checkState;
  12 import static org.opendaylight.mdsal.binding.javav2.generator.impl.AuxiliaryGenUtils.annotateDeprecatedIfNecessary;
  13 import static org.opendaylight.mdsal.binding.javav2.generator.impl.AuxiliaryGenUtils.checkModuleAndModuleName;
  14 import static org.opendaylight.mdsal.binding.javav2.generator.impl.AuxiliaryGenUtils.createDescription;
  15 import static org.opendaylight.mdsal.binding.javav2.generator.impl.AuxiliaryGenUtils.resolveListKeyTOBuilder;
  16 import static org.opendaylight.mdsal.binding.javav2.generator.impl.GenHelperUtil.addImplementedInterfaceFromUses;
  17 import static org.opendaylight.mdsal.binding.javav2.generator.impl.GenHelperUtil.addRawInterfaceDefinition;
  18 import static org.opendaylight.mdsal.binding.javav2.generator.impl.GenHelperUtil.moduleTypeBuilder;
  19 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingGeneratorUtil.encodeAngleBrackets;
  20 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.ACTION;
  21 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.INPUT;
  22 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.INSTANCE_IDENTIFIER;
  23 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.INSTANTIABLE;
  24 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.KEYED_INSTANCE_IDENTIFIER;
  25 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.LIST_ACTION;
  26 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.OUTPUT;
  27 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.RPC;
  28 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.RPC_CALLBACK;
  29 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.TREE_NODE;
  30 import static org.opendaylight.mdsal.binding.javav2.generator.util.BindingTypes.augmentable;
  31 import static org.opendaylight.mdsal.binding.javav2.generator.util.Types.CLASS;
  32 import static org.opendaylight.mdsal.binding.javav2.generator.util.Types.VOID;
  33 import static org.opendaylight.mdsal.binding.javav2.generator.util.Types.parameterizedTypeFor;
  34
  35 import com.google.common.annotations.Beta;
  36 import com.google.common.base.Optional;
  37 import java.util.Collection;
  38 import java.util.Map;
  39 import java.util.Set;
  40 import org.opendaylight.mdsal.binding.javav2.generator.spi.TypeProvider;
  41 import org.opendaylight.mdsal.binding.javav2.generator.util.BindingGeneratorUtil;
  42 import org.opendaylight.mdsal.binding.javav2.model.api.GeneratedType;
  43 import org.opendaylight.mdsal.binding.javav2.model.api.type.builder.GeneratedTOBuilder;
  44 import org.opendaylight.mdsal.binding.javav2.model.api.type.builder.GeneratedTypeBuilder;
  45 import org.opendaylight.mdsal.binding.javav2.model.api.type.builder.MethodSignatureBuilder;
  46 import org.opendaylight.mdsal.binding.javav2.spec.runtime.BindingNamespaceType;
  47 import org.opendaylight.yangtools.yang.common.QName;
  48 import org.opendaylight.yangtools.yang.model.api.ActionDefinition;
  49 import org.opendaylight.yangtools.yang.model.api.ActionNodeContainer;
  50 import org.opendaylight.yangtools.yang.model.api.ContainerSchemaNode;
  51 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
  52 import org.opendaylight.yangtools.yang.model.api.ListSchemaNode;
  53 import org.opendaylight.yangtools.yang.model.api.Module;
  54 import org.opendaylight.yangtools.yang.model.api.OperationDefinition;
  55 import org.opendaylight.yangtools.yang.model.api.RpcDefinition;
  56 import org.opendaylight.yangtools.yang.model.api.SchemaContext;
  57 import org.opendaylight.yangtools.yang.model.api.UnknownSchemaNode;
  58 import org.opendaylight.yangtools.yang.model.util.SchemaContextUtil;
  59
  60 /**
  61  *
  62  * Util class used for generation of types for RPCs, routedRPCs and Actions (YANG 1.1 only)
  63  * in Binding spec. v2. In case of routed RPC detected in input YANG, RPC is turned to Action.
  64  *
  65  */
  66 @Beta
  67 public final class RpcActionGenHelper {
  68
  69     private static final QName CONTEXT_REFERENCE =
  70             QName.create("urn:opendaylight:yang:extension:yang-ext", "2013-07-09", "context-reference").intern();
  71
  72     private RpcActionGenHelper() {
  73         throw new UnsupportedOperationException("Util class");
  74     }
  75
  76     /**
  77      * Let's find out what context we are talking about
  78      * 1. routed RPC
  79      * 2. global RPC
  80      *
  81      * In 1st case, we need Binding Generator behave like YANG 1.1 Action
  82      *
  83      * @param schemaNode RPC input node
  84      * @return presence optional
  85      */
  86     private static Optional<QName> getRoutingContext(final DataSchemaNode schemaNode) {
  87         for (UnknownSchemaNode extension : schemaNode.getUnknownSchemaNodes()) {
  88             if (CONTEXT_REFERENCE.equals(extension.getNodeType())) {
  89                 return Optional.fromNullable(extension.getQName());
  90             }
  91         }
  92         return Optional.absent();
  93     }
  94
  95     /**
  96      * Converts Yang 1.1 <b>Actions</b> to list of <code>Type</code> objects.
  97      * @param module  module from which is obtained set of all Action objects to
  98      *            iterate over them
  99      * @param genCtx input, generated context
 100      * @param verboseClassComments verbosity switch
 101      * @return generated context
 102      */
 103     static Map<Module, ModuleContext> actionMethodsToGenType(final Module module, Map<Module, ModuleContext> genCtx,
 104             final SchemaContext schemaContext, final boolean verboseClassComments, Map<String, Map<String,
 105             GeneratedTypeBuilder>> genTypeBuilders, TypeProvider typeProvider) {
 106
 107         checkModuleAndModuleName(module);
 108         final Collection<DataSchemaNode> potentials = module.getChildNodes();
 109         for (DataSchemaNode potential : potentials) {
 110             if (potential instanceof ActionNodeContainer) {
 111                 final Set<ActionDefinition> actions = ((ActionNodeContainer) potential).getActions();
 112                 for (ActionDefinition action: actions) {
 113                     genCtx.get(module).addChildNodeType(potential, resolveOperation(potential, action, module,
 114                             schemaContext, verboseClassComments, genTypeBuilders, genCtx, typeProvider, true));
 115                 }
 116             }
 117         }
 118         return genCtx;
 119     }
 120
 121     /**
 122      * Converts global <b>RPCs</b> inputs and outputs sub-statements of the module
 123      * to the list of <code>Type</code> objects. In addition, containers
 124      * and lists which belong to input or output are also part of returning list.
 125      * Detected routed RPCs are turned to Yang 1.1 Actions
 126      *
 127      * @param module
 128      *            module from which is obtained set of all RPC objects to
 129      *            iterate over them
 130      * @param genCtx input, generated context
 131      * @param verboseClassComments verbosity switch
 132      *
 133      * @throws IllegalArgumentException
 134      *             <ul>
 135      *             <li>if the module is null</li>
 136      *             <li>if the name of module is null</li>
 137      *             </ul>
 138      * @throws IllegalStateException
 139      *             if set of RPCs from module is null
 140      *
 141      * @return generated context
 142      */
 143      static Map<Module, ModuleContext> rpcMethodsToGenType(final Module module, Map<Module, ModuleContext> genCtx,
 144             final SchemaContext schemaContext, final boolean verboseClassComments, Map<String, Map<String,
 145              GeneratedTypeBuilder>> genTypeBuilders, TypeProvider typeProvider) {
 146
 147         checkModuleAndModuleName(module);
 148         final Set<RpcDefinition> rpcDefinitions = module.getRpcs();
 149         checkState(rpcDefinitions != null, "Set of RPCs from module " + module.getName() + " cannot be NULL.");
 150         if (rpcDefinitions.isEmpty()) {
 151             return genCtx;
 152         }
 153
 154         for (final RpcDefinition rpc : rpcDefinitions) {
 155             DataSchemaNode parent = (DataSchemaNode) SchemaContextUtil.findDataSchemaNode(schemaContext, rpc.getPath().getParent());
 156             //routedRPC?
 157             if (getRoutingContext(parent).isPresent()) {
 158                 genCtx.get(module).addChildNodeType(parent, resolveOperation(parent, rpc, module, schemaContext,
 159                         verboseClassComments, genTypeBuilders, genCtx, typeProvider, true));
 160             } else {
 161                 //global RPC only
 162                 genCtx.get(module).addTopLevelNodeType(resolveOperation(parent, rpc, module, schemaContext,
 163                         verboseClassComments, genTypeBuilders, genCtx, typeProvider, false));
 164
 165             }
 166         }
 167         return genCtx;
 168     }
 169
 170     /**
 171      * Converts RPC, Action or routed RPC into generated type
 172      * @return generated type
 173      */
 174     private static GeneratedTypeBuilder resolveOperation(final DataSchemaNode parent, final OperationDefinition operation,
 175             final Module module, final SchemaContext schemaContext, final boolean verboseClassComments,
 176             Map<String, Map<String, GeneratedTypeBuilder>> genTypeBuilders, final Map<Module, ModuleContext> genCtx,
 177             TypeProvider typeProvider, final boolean isAction) {
 178
 179         //operation name
 180         final String operationName = operation.getQName().getLocalName();
 181         //concrete operation name
 182         final StringBuilder sb = new StringBuilder(operationName).append('_');
 183         if (isAction) {
 184             sb.append("Action");
 185         } else {
 186             sb.append("Rpc");
 187         }
 188         final GeneratedTypeBuilder interfaceBuilder = moduleTypeBuilder(module, sb.toString(),
 189                 verboseClassComments);
 190
 191         final String basePackageName = interfaceBuilder.getPackageName();
 192
 193         interfaceBuilder.setDescription(createDescription(operation, interfaceBuilder.getFullyQualifiedName(),
 194                 schemaContext, verboseClassComments));
 195         final String operationComment = encodeAngleBrackets(operation.getDescription());
 196         final MethodSignatureBuilder operationMethod = interfaceBuilder.addMethod("invoke");
 197
 198         //input
 199         final ContainerSchemaNode input = operation.getInput();
 200         final GeneratedTypeBuilder inType = resolveOperationNode(module, operation.getInput(), basePackageName,
 201                 schemaContext, operationName, verboseClassComments, typeProvider, genTypeBuilders, genCtx, true);
 202         annotateDeprecatedIfNecessary(operation.getStatus(), inType);
 203         genCtx.get(module).addChildNodeType(input, inType);
 204
 205         //output
 206         final ContainerSchemaNode output = operation.getOutput();
 207         final GeneratedTypeBuilder outType = resolveOperationNode(module, operation.getOutput(), basePackageName,
 208                 schemaContext, operationName, verboseClassComments, typeProvider, genTypeBuilders, genCtx, false);
 209         annotateDeprecatedIfNecessary(operation.getStatus(), outType);
 210         genCtx.get(module).addChildNodeType(output, outType);
 211
 212         final GeneratedType inTypeInstance = inType.toInstance();
 213         operationMethod.addParameter(inTypeInstance, "input");
 214
 215         if (isAction) {
 216             //action, routed RPC
 217             String packageName = BindingGeneratorUtil.packageNameForGeneratedType(basePackageName, parent.getPath(),
 218                     BindingNamespaceType.Data);
 219             GeneratedTypeBuilder parentType = addRawInterfaceDefinition(packageName, parent, schemaContext,
 220                     parent.getQName().getLocalName(), verboseClassComments, genTypeBuilders);
 221             parentType.addImplementsType(TREE_NODE);
 222             parentType.addImplementsType(augmentable(parentType));
 223             annotateDeprecatedIfNecessary(parent.getStatus(), parentType);
 224
 225             GenHelperUtil.resolveDataSchemaNodes(module, basePackageName, parentType, parentType,
 226                     ((ContainerSchemaNode) parent).getChildNodes(), genCtx, schemaContext, verboseClassComments,
 227                     genTypeBuilders, typeProvider);
 228
 229             operationMethod.addParameter(parameterizedTypeFor(INSTANCE_IDENTIFIER, parentType), "ii");
 230
 231             if (parent instanceof ListSchemaNode) {
 232                 //ListAction
 233                 final GeneratedTOBuilder keyType = resolveListKeyTOBuilder(basePackageName, (ListSchemaNode) parent);
 234                 operationMethod.addParameter(
 235                         parameterizedTypeFor(KEYED_INSTANCE_IDENTIFIER, parentType, keyType), "kii");
 236                 operationMethod.setReturnType(keyType);
 237                 interfaceBuilder.addImplementsType(parameterizedTypeFor(LIST_ACTION, parentType, inType, outType));
 238             } else {
 239                 //Action
 240                 operationMethod.addParameter(parameterizedTypeFor(INSTANCE_IDENTIFIER, parentType), "ii");
 241                 interfaceBuilder.addImplementsType(parameterizedTypeFor(ACTION, parentType, inType, outType));
 242             }
 243         } else {
 244             //RPC
 245             interfaceBuilder.addImplementsType(parameterizedTypeFor(RPC, inType, outType));
 246         }
 247
 248         operationMethod.addParameter(parameterizedTypeFor(RPC_CALLBACK, outType), "callback");
 249
 250         operationMethod.setComment(operationComment);
 251         operationMethod.setReturnType(VOID);
 252
 253         return interfaceBuilder;
 254     }
 255
 256     private static GeneratedTypeBuilder resolveOperationNode(final Module module, final ContainerSchemaNode
 257             operationNode, final String basePackageName, final SchemaContext schemaContext, final String
 258             operationName, final boolean verboseClassComments, TypeProvider typeProvider, Map<String, Map<String,
 259             GeneratedTypeBuilder>> genTypeBuilders, final Map<Module, ModuleContext> genCtx, final boolean isInput) {
 260
 261         final GeneratedTypeBuilder nodeType = addRawInterfaceDefinition(basePackageName, operationNode, schemaContext,
 262                 operationName, verboseClassComments, genTypeBuilders);
 263         addImplementedInterfaceFromUses(operationNode, nodeType, genCtx);
 264         nodeType.addImplementsType(TREE_NODE);
 265         if (isInput) {
 266             nodeType.addImplementsType(parameterizedTypeFor(INPUT, nodeType));
 267         } else {
 268             nodeType.addImplementsType(parameterizedTypeFor(OUTPUT, nodeType));
 269         }
 270         nodeType.addImplementsType(parameterizedTypeFor(INSTANTIABLE, nodeType));
 271         nodeType.addImplementsType(augmentable(nodeType));
 272         GenHelperUtil.resolveDataSchemaNodes(module, basePackageName, nodeType, nodeType, operationNode.getChildNodes(), genCtx,
 273                 schemaContext, verboseClassComments, genTypeBuilders, typeProvider);
 274
 275         final MethodSignatureBuilder nodeMethod = nodeType.addMethod("implementedInterface");
 276         nodeMethod.setReturnType(parameterizedTypeFor(CLASS, nodeType));
 277         nodeMethod.addAnnotation("", "Override");
 278
 279         return nodeType;
 280     }
 281 }