summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/javatoscachecker/checker.pdfbin363675 -> 0 bytes
-rw-r--r--docs/javatoscachecker/checker.rst89
2 files changed, 89 insertions, 0 deletions
diff --git a/docs/javatoscachecker/checker.pdf b/docs/javatoscachecker/checker.pdf
deleted file mode 100644
index fcfbb43..0000000
--- a/docs/javatoscachecker/checker.pdf
+++ /dev/null
Binary files 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
+