dcaedt_validator/checker/src/main/java/org/onap/sdc/dcae/checker/package-info.java

   1 /**
   2  * The checker provides an api/tool for the verification of TOSCA yaml files
   3  * as specified in the OASIS specification found at:
   4  * http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/TOSCA-Simple-Profile-YAML-v1.0.pdf
   5  *
   6  * It provides a three stage processing of a tosca yaml file:
   7  *   - yaml verification: is the document a valid yaml document as per yaml.org/spec. In particular we're using the snakeyaml library for parsing the yaml document to a nested structure of java objects.
   8  *   - tosca yaml grammar validation: is the document a valid tosca yaml
   9  *   document, as per the the TOSCA simple profile for yaml. We use a modified
  10  *   version of the kwalify library for this task. The grammar for TOSCA yaml
  11  *   is itself a yaml document (found in the package in
  12  *   resources/tosca-schema.yaml). There are certain limitations on how far
  13  *   this grammar can go.
  14  *   - consistency verification: we check the type hierarchies for all TOSCA
  15  *   constructs (data types, capability types, node types, etc), the definition
  16  *   of all facets of a construct (properties, attributes, etc) across the type
  17  *   hierachies, the conformity of construct templates (node templates, ..) with
  18  *   their types, data valuations(input assignements, constants, function calls).
  19  *
  20  * Each stage is blocking, i.e. a stage will be performed only if the previous
  21  * one completed successfully.
  22  *
  23  * The verification is done across all the imported documents. The common TOSCA
  24  * types are by default made available to all documents being processed (the
  25  * specification is in resources/tosca-common-types.yaml). Networking related
  26  * types can be made available by importing resources/tosca-network-types.yaml
  27  * while the tosca nfv profile definitions are available at
  28  * resources/tosca-nfv-types.yaml.
  29  *
  30  * Besides snakeyaml and kwalify this package also has dependencies on Google's
  31  * guava library and Apache's jxpath.
  32  *
  33  * The three java interfaces exposed by the package are the Checker, Target
  34  * and Report. A Target represents a document processed by the Checker. While
  35  * the Checker starts with a top Target, through import statements it can end up
  36  * processing a number of Targets. The results of processing a Target are made
  37  * available through a Report which currently is nothing more that a list of
  38  * recorded errors.
  39  *
  40  * <div>
  41  * {@code
  42  *   Checker checker = new Checker();
  43  *       checker.check("tests/example.yaml");
  44  *
  45  *       for (Target t: checker.targets())
  46  *     System.out.println(t.getLocation() + "\n" + t.getReport());
  47  * }
  48  * </div>
  49  *
  50  * The errors are recorded as instances of Exception, mostly due to the fact
  51  * snakeyaml and kwalify do report errors as exceptions. As such there are 3
  52  * basic types of errros to be expected in a report: YAMLException (from
  53  * snakeyaml, related to parsing), ValidationException (from kwalify, tosca
  54  * grammar validation), TargetException (from the checker itself). This might
  55  * change as we're looking to unify the way errors are reported. A Report
  56  * object has a user friendly toString function.
  57  *
  58  * A CheckerException thrown during the checking process is an indication of a
  59  * malfunction in the checker itself.
  60  *
  61  * The checker handles targets as URIs. The resolution of a target consists in
  62  * going from a string representing some path/uri to the absolute URI. URIs can
  63  * be of any java recognizable schema: file, http, etc. A TargetResolver (not
  64  * currently exposed through the API) attempts in order:
  65  *   - if the String is an absolute URI, keep it as such
  66  *   - if the String is a relative URI attempt to resolve it as relative to
  67  * know search paths (pre-configured absolute URIs: current directory and the
  68  * root of the main target's URI). The option of adding custom search paths will
  69  * be added.
  70  *   - attempt to resolve as a classpath resource (a jar:file: URI)
  71  *
  72  * At this time there are no options for the checker (please provide
  73  * requirements to be considered).
  74  *
  75  *
  76  *
  77  * Other:
  78  *   - the checker performs during tosca grammar validation a 'normalization'
  79  *   process as the tosca yaml profile allows for short forms in the
  80  *   specification of a number of its constructs (see spec). The checker changes
  81  *   the actual structure of the parsed document such that only normalized
  82  *   (complete) forms of specification are present before the checking phase.
  83  *   (the kwalify library was extended in order to be able to specify these
  84  *   short forms in the grammar itself and process/tolerate them at validation
  85  *   time).
  86  *
  87  *   - the checker contains an internal catalog where the types and templates
  88  *   of different constructs are aggregated and indexed across all targets in
  89  *   order to facilitate the checking phase. Catalogs can be 'linked' and the
  90  *   resolution process delegated (the checker maintains a basic catalog with
  91  *   the core and common types and there is always a second catalog maintaining
  92  *   the information related to the current targets).
  93  *   The catalog is currently not exposed by the library.
  94  *
  95  *   - imports processing: the import statements present in a target are first
  96  *   'detected' during tosca yaml grammar validation phase. At that stage all
  97  *   imports are (recursively) parsed and validated (first 2 phases). Checking
  98  *   off all imports (recursively) is done during stage 3.
  99  *
 100  */
 101 package org.onap.sdc.dcae.checker;