2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.controller.sal.rest.doc.impl;
10 import static org.opendaylight.controller.sal.rest.doc.util.RestDocgenUtil.resolveNodesName;
12 import java.io.IOException;
13 import java.util.ArrayList;
14 import java.util.Collections;
15 import java.util.HashMap;
16 import java.util.List;
19 import org.apache.commons.lang3.BooleanUtils;
20 import org.json.JSONArray;
21 import org.json.JSONException;
22 import org.json.JSONObject;
23 import org.opendaylight.controller.sal.rest.doc.model.builder.OperationBuilder;
24 import org.opendaylight.yangtools.yang.common.QName;
25 import org.opendaylight.yangtools.yang.model.api.AnyXmlSchemaNode;
26 import org.opendaylight.yangtools.yang.model.api.ChoiceCaseNode;
27 import org.opendaylight.yangtools.yang.model.api.ChoiceNode;
28 import org.opendaylight.yangtools.yang.model.api.ConstraintDefinition;
29 import org.opendaylight.yangtools.yang.model.api.ContainerSchemaNode;
30 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
31 import org.opendaylight.yangtools.yang.model.api.IdentitySchemaNode;
32 import org.opendaylight.yangtools.yang.model.api.LeafListSchemaNode;
33 import org.opendaylight.yangtools.yang.model.api.LeafSchemaNode;
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.RpcDefinition;
37 import org.opendaylight.yangtools.yang.model.api.SchemaContext;
38 import org.opendaylight.yangtools.yang.model.api.TypeDefinition;
39 import org.opendaylight.yangtools.yang.model.api.type.BinaryTypeDefinition;
40 import org.opendaylight.yangtools.yang.model.api.type.BitsTypeDefinition;
41 import org.opendaylight.yangtools.yang.model.api.type.BitsTypeDefinition.Bit;
42 import org.opendaylight.yangtools.yang.model.api.type.EnumTypeDefinition.EnumPair;
43 import org.opendaylight.yangtools.yang.model.api.type.IdentityrefTypeDefinition;
44 import org.opendaylight.yangtools.yang.model.api.type.LengthConstraint;
45 import org.opendaylight.yangtools.yang.model.api.type.UnionTypeDefinition;
46 import org.opendaylight.yangtools.yang.model.util.BooleanType;
47 import org.opendaylight.yangtools.yang.model.util.Decimal64;
48 import org.opendaylight.yangtools.yang.model.util.EnumerationType;
49 import org.opendaylight.yangtools.yang.model.util.ExtendedType;
50 import org.opendaylight.yangtools.yang.model.util.Int16;
51 import org.opendaylight.yangtools.yang.model.util.Int32;
52 import org.opendaylight.yangtools.yang.model.util.Int64;
53 import org.opendaylight.yangtools.yang.model.util.Int8;
54 import org.opendaylight.yangtools.yang.model.util.StringType;
55 import org.opendaylight.yangtools.yang.model.util.Uint16;
56 import org.opendaylight.yangtools.yang.model.util.Uint32;
57 import org.opendaylight.yangtools.yang.model.util.Uint64;
58 import org.opendaylight.yangtools.yang.model.util.Uint8;
59 import org.slf4j.Logger;
60 import org.slf4j.LoggerFactory;
63 * Generates JSON Schema for data defined in Yang
65 public class ModelGenerator {
67 private static Logger _logger = LoggerFactory.getLogger(ModelGenerator.class);
69 private static final String BASE_64 = "base64";
70 private static final String BINARY_ENCODING_KEY = "binaryEncoding";
71 private static final String MEDIA_KEY = "media";
72 private static final String ONE_OF_KEY = "oneOf";
73 private static final String UNIQUE_ITEMS_KEY = "uniqueItems";
74 private static final String MAX_ITEMS = "maxItems";
75 private static final String MIN_ITEMS = "minItems";
76 private static final String SCHEMA_URL = "http://json-schema.org/draft-04/schema";
77 private static final String SCHEMA_KEY = "$schema";
78 private static final String MAX_LENGTH_KEY = "maxLength";
79 private static final String MIN_LENGTH_KEY = "minLength";
80 private static final String REQUIRED_KEY = "required";
81 private static final String REF_KEY = "$ref";
82 private static final String ITEMS_KEY = "items";
83 private static final String TYPE_KEY = "type";
84 private static final String PROPERTIES_KEY = "properties";
85 private static final String DESCRIPTION_KEY = "description";
86 private static final String OBJECT_TYPE = "object";
87 private static final String ARRAY_TYPE = "array";
88 private static final String ENUM = "enum";
89 private static final String INTEGER = "integer";
90 private static final String NUMBER = "number";
91 private static final String BOOLEAN = "boolean";
92 private static final String STRING = "string";
93 private static final String ID_KEY = "id";
94 private static final String SUB_TYPES_KEY = "subTypes";
96 private static final Map<Class<? extends TypeDefinition<?>>, String> YANG_TYPE_TO_JSON_TYPE_MAPPING;
99 Map<Class<? extends TypeDefinition<?>>, String> tempMap1 = new HashMap<Class<? extends TypeDefinition<?>>, String>(
101 tempMap1.put(StringType.class, STRING);
102 tempMap1.put(BooleanType.class, BOOLEAN);
103 tempMap1.put(Int8.class, INTEGER);
104 tempMap1.put(Int16.class, INTEGER);
105 tempMap1.put(Int32.class, INTEGER);
106 tempMap1.put(Int64.class, INTEGER);
107 tempMap1.put(Uint16.class, INTEGER);
108 tempMap1.put(Uint32.class, INTEGER);
109 tempMap1.put(Uint64.class, INTEGER);
110 tempMap1.put(Uint8.class, INTEGER);
111 tempMap1.put(Decimal64.class, NUMBER);
112 tempMap1.put(EnumerationType.class, ENUM);
115 YANG_TYPE_TO_JSON_TYPE_MAPPING = Collections.unmodifiableMap(tempMap1);
118 private Module topLevelModule;
120 public ModelGenerator() {
123 public JSONObject convertToJsonSchema(Module module, SchemaContext schemaContext) throws IOException, JSONException {
124 JSONObject models = new JSONObject();
125 topLevelModule = module;
126 processContainers(module, models, schemaContext);
127 processRPCs(module, models, schemaContext);
128 processIdentities(module, models);
132 private void processContainers(Module module, JSONObject models, SchemaContext schemaContext) throws IOException,
135 String moduleName = module.getName();
137 for (DataSchemaNode childNode : module.getChildNodes()) {
138 JSONObject configModuleJSON = null;
139 JSONObject operationalModuleJSON = null;
141 String childNodeName = childNode.getQName().getLocalName();
143 * For every container in the module
145 if (childNode instanceof ContainerSchemaNode) {
146 configModuleJSON = processContainer((ContainerSchemaNode) childNode, moduleName, true, models, true,
148 operationalModuleJSON = processContainer((ContainerSchemaNode) childNode, moduleName, true, models,
149 false, schemaContext);
152 if (configModuleJSON != null) {
153 _logger.debug("Adding model for [{}]", OperationBuilder.CONFIG + childNodeName);
154 configModuleJSON.put("id", OperationBuilder.CONFIG + childNodeName);
155 models.put(OperationBuilder.CONFIG + childNodeName, configModuleJSON);
157 if (operationalModuleJSON != null) {
158 _logger.debug("Adding model for [{}]", OperationBuilder.OPERATIONAL + childNodeName);
159 operationalModuleJSON.put("id", OperationBuilder.OPERATIONAL + childNodeName);
160 models.put(OperationBuilder.OPERATIONAL + childNodeName, operationalModuleJSON);
167 * Process the RPCs for a Module Spits out a file each of the name <rpcName>-input.json and <rpcName>-output.json
168 * for each RPC that contains input & output elements
171 * @throws JSONException
172 * @throws IOException
174 private void processRPCs(Module module, JSONObject models, SchemaContext schemaContext) throws JSONException,
177 Set<RpcDefinition> rpcs = module.getRpcs();
178 String moduleName = module.getName();
179 for (RpcDefinition rpc : rpcs) {
181 ContainerSchemaNode input = rpc.getInput();
183 JSONObject inputJSON = processContainer(input, moduleName, true, models, schemaContext);
184 String filename = "(" + rpc.getQName().getLocalName() + ")input";
185 inputJSON.put("id", filename);
186 // writeToFile(filename, inputJSON.toString(2), moduleName);
187 models.put(filename, inputJSON);
190 ContainerSchemaNode output = rpc.getOutput();
191 if (output != null) {
192 JSONObject outputJSON = processContainer(output, moduleName, true, models, schemaContext);
193 String filename = "(" + rpc.getQName().getLocalName() + ")output";
194 outputJSON.put("id", filename);
195 models.put(filename, outputJSON);
201 * Processes the 'identity' statement in a yang model and maps it to a 'model' in the Swagger JSON spec.
204 * The module from which the identity stmt will be processed
206 * The JSONObject in which the parsed identity will be put as a 'model' obj
207 * @throws JSONException
209 private void processIdentities(Module module, JSONObject models) throws JSONException {
211 String moduleName = module.getName();
212 Set<IdentitySchemaNode> idNodes = module.getIdentities();
213 _logger.debug("Processing Identities for module {} . Found {} identity statements", moduleName, idNodes.size());
215 for (IdentitySchemaNode idNode : idNodes) {
216 JSONObject identityObj = new JSONObject();
217 String identityName = idNode.getQName().getLocalName();
218 _logger.debug("Processing Identity: {}", identityName);
220 identityObj.put(ID_KEY, identityName);
221 identityObj.put(DESCRIPTION_KEY, idNode.getDescription());
223 JSONObject props = new JSONObject();
224 IdentitySchemaNode baseId = idNode.getBaseIdentity();
226 if (baseId == null) {
228 * This is a base identity. So lets see if it has sub types. If it does, then add them to the model
231 Set<IdentitySchemaNode> derivedIds = idNode.getDerivedIdentities();
233 if (derivedIds != null) {
234 JSONArray subTypes = new JSONArray();
235 for (IdentitySchemaNode derivedId : derivedIds) {
236 subTypes.put(derivedId.getQName().getLocalName());
238 identityObj.put(SUB_TYPES_KEY, subTypes);
242 * This is a derived entity. Add it's base type & move on.
244 props.put(TYPE_KEY, baseId.getQName().getLocalName());
247 // Add the properties. For a base type, this will be an empty object as required by the Swagger spec.
248 identityObj.put(PROPERTIES_KEY, props);
249 models.put(identityName, identityObj);
254 * Processes the container node and populates the moduleJSON
259 * @throws JSONException
260 * @throws IOException
262 private JSONObject processContainer(ContainerSchemaNode container, String moduleName, boolean addSchemaStmt,
263 JSONObject models, SchemaContext schemaContext) throws JSONException, IOException {
264 return processContainer(container, moduleName, addSchemaStmt, models, (Boolean) null, schemaContext);
267 private JSONObject processContainer(ContainerSchemaNode container, String moduleName, boolean addSchemaStmt,
268 JSONObject models, Boolean isConfig, SchemaContext schemaContext) throws JSONException, IOException {
269 JSONObject moduleJSON = getSchemaTemplate();
271 moduleJSON = getSchemaTemplate();
273 moduleJSON = new JSONObject();
275 moduleJSON.put(TYPE_KEY, OBJECT_TYPE);
277 String containerDescription = container.getDescription();
278 moduleJSON.put(DESCRIPTION_KEY, containerDescription);
280 JSONObject properties = processChildren(container.getChildNodes(), container.getQName(), moduleName, models,
281 isConfig, schemaContext);
282 moduleJSON.put(PROPERTIES_KEY, properties);
286 private JSONObject processChildren(Iterable<DataSchemaNode> nodes, QName parentQName, String moduleName,
287 JSONObject models, SchemaContext schemaContext) throws JSONException, IOException {
288 return processChildren(nodes, parentQName, moduleName, models, null, schemaContext);
292 * Processes the nodes
299 * @throws JSONException
300 * @throws IOException
302 private JSONObject processChildren(Iterable<DataSchemaNode> nodes, QName parentQName, String moduleName,
303 JSONObject models, Boolean isConfig, SchemaContext schemaContext) throws JSONException, IOException {
305 JSONObject properties = new JSONObject();
307 for (DataSchemaNode node : nodes) {
308 if (isConfig == null || node.isConfiguration() == isConfig) {
310 String name = resolveNodesName(node, topLevelModule, schemaContext);
311 JSONObject property = null;
312 if (node instanceof LeafSchemaNode) {
313 property = processLeafNode((LeafSchemaNode) node);
314 } else if (node instanceof ListSchemaNode) {
315 property = processListSchemaNode((ListSchemaNode) node, moduleName, models, isConfig, schemaContext);
317 } else if (node instanceof LeafListSchemaNode) {
318 property = processLeafListNode((LeafListSchemaNode) node);
320 } else if (node instanceof ChoiceNode) {
321 property = processChoiceNode((ChoiceNode) node, moduleName, models, schemaContext);
323 } else if (node instanceof AnyXmlSchemaNode) {
324 property = processAnyXMLNode((AnyXmlSchemaNode) node);
326 } else if (node instanceof ContainerSchemaNode) {
327 property = processContainer((ContainerSchemaNode) node, moduleName, false, models, isConfig,
331 throw new IllegalArgumentException("Unknown DataSchemaNode type: " + node.getClass());
334 property.putOpt(DESCRIPTION_KEY, node.getDescription());
335 properties.put(name, property);
344 * @throws JSONException
346 private JSONObject processLeafListNode(LeafListSchemaNode listNode) throws JSONException {
347 JSONObject props = new JSONObject();
348 props.put(TYPE_KEY, ARRAY_TYPE);
350 JSONObject itemsVal = new JSONObject();
351 processTypeDef(listNode.getType(), itemsVal);
352 props.put(ITEMS_KEY, itemsVal);
354 ConstraintDefinition constraints = listNode.getConstraints();
355 processConstraints(constraints, props);
364 * @throws JSONException
365 * @throws IOException
367 private JSONObject processChoiceNode(ChoiceNode choiceNode, String moduleName, JSONObject models,
368 SchemaContext schemaContext) throws JSONException, IOException {
370 Set<ChoiceCaseNode> cases = choiceNode.getCases();
372 JSONArray choiceProps = new JSONArray();
373 for (ChoiceCaseNode choiceCase : cases) {
374 String choiceName = choiceCase.getQName().getLocalName();
375 JSONObject choiceProp = processChildren(choiceCase.getChildNodes(), choiceCase.getQName(), moduleName,
376 models, schemaContext);
377 JSONObject choiceObj = new JSONObject();
378 choiceObj.put(choiceName, choiceProp);
379 choiceObj.put(TYPE_KEY, OBJECT_TYPE);
380 choiceProps.put(choiceObj);
383 JSONObject oneOfProps = new JSONObject();
384 oneOfProps.put(ONE_OF_KEY, choiceProps);
385 oneOfProps.put(TYPE_KEY, OBJECT_TYPE);
394 * @throws JSONException
396 private void processConstraints(ConstraintDefinition constraints, JSONObject props) throws JSONException {
397 boolean isMandatory = constraints.isMandatory();
398 props.put(REQUIRED_KEY, isMandatory);
400 Integer minElements = constraints.getMinElements();
401 Integer maxElements = constraints.getMaxElements();
402 if (minElements != null) {
403 props.put(MIN_ITEMS, minElements);
405 if (maxElements != null) {
406 props.put(MAX_ITEMS, maxElements);
411 * Parses a ListSchema node.
413 * Due to a limitation of the RAML--->JAX-RS tool, sub-properties must be in a separate JSON schema file. Hence, we
414 * have to write some properties to a new file, while continuing to process the rest.
420 * @throws JSONException
421 * @throws IOException
423 private JSONObject processListSchemaNode(ListSchemaNode listNode, String moduleName, JSONObject models,
424 Boolean isConfig, SchemaContext schemaContext) throws JSONException, IOException {
426 String fileName = (BooleanUtils.isNotFalse(isConfig) ? OperationBuilder.CONFIG : OperationBuilder.OPERATIONAL)
427 + listNode.getQName().getLocalName();
429 JSONObject childSchemaProperties = processChildren(listNode.getChildNodes(), listNode.getQName(), moduleName,
430 models, schemaContext);
431 JSONObject childSchema = getSchemaTemplate();
432 childSchema.put(TYPE_KEY, OBJECT_TYPE);
433 childSchema.put(PROPERTIES_KEY, childSchemaProperties);
436 * Due to a limitation of the RAML--->JAX-RS tool, sub-properties must be in a separate JSON schema file. Hence,
437 * we have to write some properties to a new file, while continuing to process the rest.
439 // writeToFile(fileName, childSchema.toString(2), moduleName);
440 childSchema.put("id", fileName);
441 models.put(fileName, childSchema);
443 JSONObject listNodeProperties = new JSONObject();
444 listNodeProperties.put(TYPE_KEY, ARRAY_TYPE);
446 JSONObject items = new JSONObject();
447 items.put(REF_KEY, fileName);
448 listNodeProperties.put(ITEMS_KEY, items);
450 return listNodeProperties;
458 * @throws JSONException
460 private JSONObject processLeafNode(LeafSchemaNode leafNode) throws JSONException {
461 JSONObject property = new JSONObject();
463 String leafDescription = leafNode.getDescription();
464 property.put(DESCRIPTION_KEY, leafDescription);
466 processConstraints(leafNode.getConstraints(), property);
467 processTypeDef(leafNode.getType(), property);
476 * @throws JSONException
478 private JSONObject processAnyXMLNode(AnyXmlSchemaNode leafNode) throws JSONException {
479 JSONObject property = new JSONObject();
481 String leafDescription = leafNode.getDescription();
482 property.put(DESCRIPTION_KEY, leafDescription);
484 processConstraints(leafNode.getConstraints(), property);
491 * @throws JSONException
493 private void processTypeDef(TypeDefinition<?> leafTypeDef, JSONObject property) throws JSONException {
495 if (leafTypeDef instanceof ExtendedType) {
496 processExtendedType(leafTypeDef, property);
497 } else if (leafTypeDef instanceof EnumerationType) {
498 processEnumType((EnumerationType) leafTypeDef, property);
500 } else if (leafTypeDef instanceof BitsTypeDefinition) {
501 processBitsType((BitsTypeDefinition) leafTypeDef, property);
503 } else if (leafTypeDef instanceof UnionTypeDefinition) {
504 processUnionType((UnionTypeDefinition) leafTypeDef, property);
506 } else if (leafTypeDef instanceof IdentityrefTypeDefinition) {
507 property.putOpt(TYPE_KEY, ((IdentityrefTypeDefinition) leafTypeDef).getIdentity().getQName().getLocalName());
508 } else if (leafTypeDef instanceof BinaryTypeDefinition) {
509 processBinaryType((BinaryTypeDefinition) leafTypeDef, property);
511 // System.out.println("In else: " + leafTypeDef.getClass());
512 String jsonType = YANG_TYPE_TO_JSON_TYPE_MAPPING.get(leafTypeDef.getClass());
513 if (jsonType == null) {
516 property.putOpt(TYPE_KEY, jsonType);
524 * @throws JSONException
526 private void processExtendedType(TypeDefinition<?> leafTypeDef, JSONObject property) throws JSONException {
527 Object leafBaseType = leafTypeDef.getBaseType();
528 if (leafBaseType instanceof ExtendedType) {
529 // recursively process an extended type until we hit a base type
530 processExtendedType((TypeDefinition<?>) leafBaseType, property);
532 List<LengthConstraint> lengthConstraints = ((ExtendedType) leafTypeDef).getLengthConstraints();
533 for (LengthConstraint lengthConstraint : lengthConstraints) {
534 Number min = lengthConstraint.getMin();
535 Number max = lengthConstraint.getMax();
536 property.putOpt(MIN_LENGTH_KEY, min);
537 property.putOpt(MAX_LENGTH_KEY, max);
539 String jsonType = YANG_TYPE_TO_JSON_TYPE_MAPPING.get(leafBaseType.getClass());
540 property.putOpt(TYPE_KEY, jsonType);
548 private void processBinaryType(BinaryTypeDefinition binaryType, JSONObject property) throws JSONException {
549 property.put(TYPE_KEY, STRING);
550 JSONObject media = new JSONObject();
551 media.put(BINARY_ENCODING_KEY, BASE_64);
552 property.put(MEDIA_KEY, media);
557 * @param enumLeafType
559 * @throws JSONException
561 private void processEnumType(EnumerationType enumLeafType, JSONObject property) throws JSONException {
562 List<EnumPair> enumPairs = enumLeafType.getValues();
563 List<String> enumNames = new ArrayList<String>();
564 for (EnumPair enumPair : enumPairs) {
565 enumNames.add(enumPair.getName());
567 property.putOpt(ENUM, new JSONArray(enumNames));
574 * @throws JSONException
576 private void processBitsType(BitsTypeDefinition bitsType, JSONObject property) throws JSONException {
577 property.put(TYPE_KEY, ARRAY_TYPE);
578 property.put(MIN_ITEMS, 0);
579 property.put(UNIQUE_ITEMS_KEY, true);
580 JSONArray enumValues = new JSONArray();
582 List<Bit> bits = bitsType.getBits();
583 for (Bit bit : bits) {
584 enumValues.put(bit.getName());
586 JSONObject itemsValue = new JSONObject();
587 itemsValue.put(ENUM, enumValues);
588 property.put(ITEMS_KEY, itemsValue);
595 * @throws JSONException
597 private void processUnionType(UnionTypeDefinition unionType, JSONObject property) throws JSONException {
599 StringBuilder type = new StringBuilder();
600 for (TypeDefinition<?> typeDef : unionType.getTypes()) {
601 if (type.length() > 0) {
604 type.append(YANG_TYPE_TO_JSON_TYPE_MAPPING.get(typeDef.getClass()));
607 property.put(TYPE_KEY, type);
611 * Helper method to generate a pre-filled JSON schema object.
614 * @throws JSONException
616 private JSONObject getSchemaTemplate() throws JSONException {
617 JSONObject schemaJSON = new JSONObject();
618 schemaJSON.put(SCHEMA_KEY, SCHEMA_URL);