CPS-1381: Query large outputs using descendants/limit/depth query parameter.

descendants is optional query parameter with default value of "all". possible values of descendants is as below :

1.  all : to get all descendants 
2.  none: don't include descendants
3.  number : positive number 0 to n, to query nodes till nth descendant 

1. we need to support different version for this query API for backward compatibility 

descendants is optional query parameter with default value of "all". possible values of descendants is as below :

1.  all : to get all descendants 
2.  none: don't include descendants
3.  number : positive number 0 to n, to query nodes till nth descendant 

1. we need to support different version for this query API for backward compatibility 

/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/node:
  $ref: 'cpsDataV2.yml#/nodeByDataspaceAndAnchor'

/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes/query:
  $ref: 'cpsQueryV2.yml#/nodesByDataspaceAndAnchorAndCpsPath'

nodesByDataspaceAndAnchorAndCpsPath:
  get:
    description: Query data nodes for the given dataspace and anchor using CPS path
    tags:
      - cps-query
    summary: Query data nodes
    operationId: getNodesByDataspaceAndAnchorAndCpsPathV2
    parameters:
      - $ref: 'components.yml#/components/parameters/dataspaceNameInPath'
      - $ref: 'components.yml#/components/parameters/anchorNameInPath'
      - $ref: 'components.yml#/components/parameters/cpsPathInQuery'
      - $ref: 'components.yml#/components/parameters/descendantsInQuery'
...

descendantsInQuery:
  name: descendants
  in: query
  description: descendants parameter to limit descendants. use "all", "none" or number
  required: false
  schema:
    type: string
    default: all
    example: 3
    pattern: <use pattern to validate accepted values for descendants>
Notes : return error descendants value if less then -1 and invalid string values.

DataRestController.java

@Override
public ResponseEntity<Object> getNodeByDataspaceAndAnchorV2(final String dataspaceName, final String anchorName,
    final String xpath, final String descendants) {
    final FetchDescendantsOption fetchDescendantsOption = getFetchDescendantOption(descendants);
    final DataNode dataNode = cpsDataService.getDataNode(dataspaceName, anchorName, xpath,
        fetchDescendantsOption);
    final String prefix = prefixResolver.getPrefix(dataspaceName, anchorName, xpath);
    return new ResponseEntity<>(DataMapUtils.toDataMapWithIdentifier(dataNode, prefix), HttpStatus.OK);
}

private FetchDescendantsOption getFetchDescendantOption(final String descendants) {
    if (null == descendants || descendants.trim().isEmpty()
            || "-1".equals(descendants) || "all".equals(descendants)) {
        return FetchDescendantsOption.INCLUDE_ALL_DESCENDANTS;
    } else if ("0".equals(descendants) || "none".equals(descendants)) {
        return FetchDescendantsOption.OMIT_DESCENDANTS;
    } else {
        final Integer depth = Integer.valueOf(descendants);
        return new FetchDescendantsOption(depth);
    }
}

QueryRestController.java

@Override
public ResponseEntity<Object> getNodesByDataspaceAndAnchorAndCpsPathV2(final String dataspaceName,
    final String anchorName, final String cpsPath, final String descendants) {
    final FetchDescendantsOption fetchDescendantsOption = getFetchDescendantOption(descendants);
    final Collection<DataNode> dataNodes =
        cpsQueryService.queryDataNodes(dataspaceName, anchorName, cpsPath, fetchDescendantsOption);
    final List<Map<String, Object>> dataMaps = new ArrayList<>(dataNodes.size());
    String prefix = null;
    for (final DataNode dataNode : dataNodes) {
        if (prefix == null) {
            prefix = prefixResolver.getPrefix(dataspaceName, anchorName, dataNode.getXpath());
        }
        final Map<String, Object> dataMap = DataMapUtils.toDataMapWithIdentifier(dataNode, prefix);
        dataMaps.add(dataMap);
    }
    return new ResponseEntity<>(jsonObjectMapper.asJsonString(dataMaps), HttpStatus.OK);
}