From 7f910da4d362965255e5fa232c9aa5496be8e7d5 Mon Sep 17 00:00:00 2001 From: Serban Jora Date: Wed, 1 Nov 2017 22:55:42 -0400 Subject: Add rst version of javatoscachecker presentation Remove pdf version Change-Id: Ia2872e5bf571e021db9b1af8ed06bcba587c4dec Issue-Id: MODELING-32 Signed-off-by: Serban Jora --- docs/javatoscachecker/checker.pdf | Bin 363675 -> 0 bytes docs/javatoscachecker/checker.rst | 89 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) delete mode 100644 docs/javatoscachecker/checker.pdf create mode 100644 docs/javatoscachecker/checker.rst diff --git a/docs/javatoscachecker/checker.pdf b/docs/javatoscachecker/checker.pdf deleted file mode 100644 index fcfbb43..0000000 Binary files a/docs/javatoscachecker/checker.pdf and /dev/null differ diff --git a/docs/javatoscachecker/checker.rst b/docs/javatoscachecker/checker.rst new file mode 100644 index 0000000..01321b0 --- /dev/null +++ b/docs/javatoscachecker/checker.rst @@ -0,0 +1,89 @@ +1. History +========== + + * Development started over 2 years ago as part of the Network Automation, the Intelligent Service Composition project + * It was supporting the model driven composition of resources/services/products + +2. Scope +======== + + * Development of a tool as generic as possible + - not bound to a particular schema/profile + - no particular type of post-processing (orchestrator) + - limited to TOSCA yaml profile + - Java language + +3. Goals +======== + + * Ensure that a (set of) TOSCA template(s)is conform to a correctly defined type system + - avoid errors at more expensive later processing stages + - pre-requisite to further processing: UI rendeing, persistence + + * Generate an intermediate form that could facilitate further processing + * Extensibility + - accommodate extensions to the standard and checks pertinent to these extensions + +4. The checker +============== + + * Validate yaml document + - supports streaming documents (multiple documents within one file), yaml anchors, etc + - currently uses the snakeyaml library + * Syntax check + - two pre-defined grammars, 1.0 and 1.1, with the possibility of handling a mix of documents version wise + + other versions/variants can be added 'on the fly', identified through the tosca_definitions_version entry + - accept the short forms + + declare the short forms within the grammar + + builds a canonical form from which the shorts forms are eliminated (so further processing steps do not need to handle them) + - grammar written in yaml + + easy to maintain/modify + + processed through a modified version of the kwalify library + * Checks + - type hierarchy checks for all constructs + + valid re-definitions: from relatively simple (properties) to rather complicated (interface opearations) + - valid type references: all referenced types are pre-declared (as super-types, as valid source types, etc) + - templates respect their respective type definition + + example: check type of interface operation inputs + + other references: capabilities and requirements in substitution mappings + - data checks: assignments match the type specification, function argument compatibility (for built-in functions), constraints matching + * Process the entire document tree specified through import statements + * Extensibility + - pluggable document locator/loader + - pluggable handlers at syntax check (pre/post validation) + - pluggable checks based on document location + + a new construct (new grammar) can be subject to new semantic checks plugged without checker code being re-built. + +5. Output +========= + + * Error reporting + - Differs depending on the stages + + Document position indication during parsing + + Document path and rule during syntax check + + Document path during checking + * Catalog + - No explicit representation of TOSCA constructs, offers a query interface with results being exposed as common Java types: maps, lists, .. + - domain specific (TOSCA constructs) navigation built through a proxy based approach on top of above representation + +6. Usage +======== + + * API + - simple API that allows access to any stage of the checker + + One can build an in-memory representation of a TOSCA document and skip the yaml parsing. + + Re-usable Catalog (hierarchical Catalogs) + + One or more documents can be processed and the resulting Catalog be preserved and used for later processing of other documents using the previous catalog as base catalog + * CLI + - basic command line interface + * Service + - stateful REST service layer on top of checker API + + a schema (document with type specifications) can be submitted and be referenced (imports) from subsequently submitted templates + + +7. Post-processing +================== + + * A tiny framework for additional processing + - one basic implementation of a JavaScript post-processor where the Catalog and topology graph are exposed to javascript scripts implementing business validation rules + -- cgit 1.2.3-korg