| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 1.5.5"> |
| <meta name="author" content="2019-08-08 13:15:33 CEST"> |
| <title>N4JS Design Specification</title> |
| <link rel="stylesheet" href="styles/spec.min.css"> |
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"> |
| <!-- ************* docinfo ******************************************************************* --> |
| |
| |
| <!-- ************* Favicon ************--> |
| <link rel="icon" href="images/favicon.ico" /> |
| |
| <!-- ************* Back-to-top JQuery ************* --> |
| <script src="https://code.jquery.com/jquery-1.12.4.js"></script> |
| <script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script> |
| |
| |
| <link href="styles/prism.min.css" rel="stylesheet" /> |
| <script type="text/javascript" async |
| src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML"> |
| </script> |
| |
| <!-- ************* Styles ************* --> |
| <link rel="stylesheet" type="text/css" href="styles/n4jsspec-adoc.css"> |
| |
| |
| <!-- ****************** NavBar ****************** --> |
| <div id="menubar"> |
| <div class="banner"> |
| <a href="https://www.eclipse.org/n4js/#"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS"></a> |
| </div> |
| <ul> |
| <li><a href="index.html">Index</a></li> |
| </ul> |
| </div> |
| <!-- ************* docinfo ******************************************************************* --> |
| <style> |
| .admonitionblock td.icon .icon-todo:before{content:"\f249";color:#f4ee42} |
| </style> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>N4JS Design Specification</h1> |
| <div class="details"> |
| <span id="author" class="author">2019-08-08 13:15:33 CEST</span><br> |
| <span id="revnumber">version 0.9</span> |
| </div> |
| <div id="toc" class="toc2"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="introduction.html#_introduction">1. Introduction</a> |
| <ul class="sectlevel2"> |
| <li><a href="introduction.html#notation">1.1. Notation</a></li> |
| <li><a href="introduction.html#sec:IDE_Overview">1.2. IDE Components</a> |
| <ul class="sectlevel3"> |
| <li><a href="introduction.html#sec:Naming_Conventions">1.2.1. Naming Conventions</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="eclipse_setup.html#_eclipse-setup">2. Eclipse Setup</a> |
| <ul class="sectlevel2"> |
| <li><a href="eclipse_setup.html#_system-requirements">2.1. System Requirements</a></li> |
| <li><a href="eclipse_setup.html#_contribute">2.2. Contribute</a> |
| <ul class="sectlevel3"> |
| <li><a href="eclipse_setup.html#_eclipse-installer">2.2.1. Eclipse Installer</a> |
| <ul class="sectlevel4"> |
| <li><a href="eclipse_setup.html#_changing-the-setup-script">2.2.1.1. Changing the Setup Script</a></li> |
| </ul> |
| </li> |
| <li><a href="eclipse_setup.html#_manual-ide-configuration">2.2.2. Manual IDE Configuration</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="release_engineering.html#_release-engineering">3. Release Engineering</a> |
| <ul class="sectlevel2"> |
| <li><a href="release_engineering.html#_nightly-build-on-eclipse-infrastructure">3.1. Nightly build on Eclipse infrastructure</a></li> |
| <li><a href="release_engineering.html#_build-the-n4js-ide-from-command-line">3.2. Build the N4JS IDE from command line</a> |
| <ul class="sectlevel3"> |
| <li><a href="release_engineering.html#_publish-maven-tooling-code-org-eclipse-n4js-releng-util-code">3.2.1. Publish maven-tooling <code>org.eclipse.n4js.releng.util</code></a></li> |
| <li><a href="release_engineering.html#sec:test-verdaccio">3.2.2. Test Verdaccio containing n4js-libs</a></li> |
| <li><a href="release_engineering.html#_generation-of-eclipse-help-for-spec-and-design-document">3.2.3. Generation of Eclipse help for spec and design document</a></li> |
| </ul> |
| </li> |
| <li><a href="release_engineering.html#_updating-frameworks-and-dependencies">3.3. Updating frameworks and dependencies</a> |
| <ul class="sectlevel3"> |
| <li><a href="release_engineering.html#_update-of-eclipse-emf-xtext-etc">3.3.1. Update of Eclipse, EMF, Xtext, etc.</a></li> |
| <li><a href="release_engineering.html#_update-of-the-embedded-jre">3.3.2. Update of the embedded JRE</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="tips_and_tricks.html#_tips-and-tricks">4. Tips and Tricks</a> |
| <ul class="sectlevel2"> |
| <li><a href="tips_and_tricks.html#_naming">4.1. Naming</a></li> |
| <li><a href="tips_and_tricks.html#_logging">4.2. Logging</a></li> |
| <li><a href="tips_and_tricks.html#_cancellation-handling">4.3. Cancellation Handling</a></li> |
| <li><a href="tips_and_tricks.html#_caching">4.4. Caching</a></li> |
| <li><a href="tips_and_tricks.html#_dependency-injection">4.5. Dependency Injection</a></li> |
| <li><a href="tips_and_tricks.html#_miscellaneous">4.6. Miscellaneous</a></li> |
| </ul> |
| </li> |
| <li><a href="parser.html#_parser">5. Parser</a> |
| <ul class="sectlevel2"> |
| <li><a href="parser.html#sec:Parser_Overview">5.1. Overview</a></li> |
| <li><a href="parser.html#sec:N4JS_Parser">5.2. N4JS Parser</a></li> |
| <li><a href="parser.html#sec:Parser_Generation_Post_Processing">5.3. Parser Generation Post-Processing</a> |
| <ul class="sectlevel3"> |
| <li><a href="parser.html#sec:Automatic_Semicolon_Insertion">5.3.1. Automatic Semicolon Insertion</a> |
| <ul class="sectlevel4"> |
| <li><a href="parser.html#sec:Injected_code_in_the_Antlr_grammar_file">5.3.1.1. Injected code in the Antlr grammar file</a></li> |
| <li><a href="parser.html#sec:Customized_error_recovery">5.3.1.2. Customized error recovery</a></li> |
| </ul> |
| </li> |
| <li><a href="parser.html#sec:_No_line_terminator_allowed_here__handling">5.3.2. Async and <code>No line terminator allowed here</code> Handling</a></li> |
| <li><a href="parser.html#sec:Regular_Expression">5.3.3. Regular Expression</a></li> |
| <li><a href="parser.html#sec:Unicode">5.3.4. Unicode</a></li> |
| <li><a href="parser.html#sec:Literals">5.3.5. Literals</a></li> |
| </ul> |
| </li> |
| <li><a href="parser.html#sec:Modifiers">5.4. Modifiers</a></li> |
| <li><a href="parser.html#sec:Conflict_Resolutions">5.5. Conflict Resolutions</a> |
| <ul class="sectlevel3"> |
| <li><a href="parser.html#sec:Reserved_Keywords_vs__Identifier_Names">5.5.1. Reserved Keywords vs. Identifier Names</a></li> |
| <li><a href="parser.html#sec:Operators_and_Generics">5.5.2. Operators and Generics</a></li> |
| </ul> |
| </li> |
| <li><a href="parser.html#sec:Content_Assist_Parser">5.6. Content-Assist Parser</a></li> |
| </ul> |
| </li> |
| <li><a href="type_system.html#_type-system">6. Type System</a> |
| <ul class="sectlevel2"> |
| <li><a href="type_system.html#sec:Type_Model_and_Grammar">6.1. Type Model and Grammar</a> |
| <ul class="sectlevel3"> |
| <li><a href="type_system.html#sec:Type_Model_Overview">6.1.1. Type Model Overview</a></li> |
| <li><a href="type_system.html#sec:Built_in_Types">6.1.2. Built-in and Primitive Types</a></li> |
| <li><a href="type_system.html#sec:Type_Model_DSL">6.1.3. Type Model DSL</a></li> |
| </ul> |
| </li> |
| <li><a href="type_system.html#sec:Type_System_Implementation">6.2. Type System Implementation</a></li> |
| <li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal">6.3. Type Inference of AST</a> |
| <ul class="sectlevel3"> |
| <li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal__Background">6.3.1. Background</a></li> |
| <li><a href="type_system.html#sec:Triggering_Type_Inference_of_AST">6.3.2. Triggering</a></li> |
| <li><a href="type_system.html#sec:Traversal_Order_During_Type_Inference_of_AST">6.3.3. Traversal Order</a></li> |
| <li><a href="type_system.html#sec:Cross_References_During_Type_Inference_of_AST">6.3.4. Cross-References</a></li> |
| <li><a href="type_system.html#sec:Function_Accessor_Bodies_During_Type_Inference_of_AST">6.3.5. Function/Accessor Bodies</a></li> |
| <li><a href="type_system.html#sec:Poly_Expressions_During_Type_Inference_of_AST">6.3.6. Poly Expressions</a></li> |
| <li><a href="type_system.html#sec:Constraint_Solver_used_During_Type_Inference_of_AST">6.3.7. Constraint Solver</a></li> |
| <li><a href="type_system.html#sec:Type_Guards_During_Type_Inference_of_AST">6.3.8. Type Guards</a></li> |
| </ul> |
| </li> |
| <li><a href="type_system.html#sec:Structural_Typing">6.4. Structural Typing</a></li> |
| </ul> |
| </li> |
| <li><a href="#_type-index">7. Type Index</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:Type_Index_Design_Rationale">7.1. Design Rationale</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Getting_the_Xtext_Index_Content_IResourceDescriptions">7.1.1. Getting the Xtext Index (<code>IResourceDescriptions</code>) Content</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:Design_Overview">7.2. Design Overview</a></li> |
| <li><a href="#sec:N4JS_Resource_Load_States">7.3. N4JS Resource Load States</a></li> |
| <li><a href="#sec:Type_Builder">7.4. Types Builder</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Type_Inference_not_allowed_in_Type_Builder">7.4.1. Type Inference not allowed in Types Builder</a></li> |
| <li><a href="#sec:ComputedTypeReferences">7.4.2. Deferred Type References</a></li> |
| <li><a href="#sec:Use_cases_of_ComputedTypeRef">7.4.3. Use cases of DeferredTypeRef</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:Incremental_Builder_Overview">7.5. Incremental Builder (Overview)</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Incremental_Builder_Overview__XtextBuilder">7.5.1. XtextBuilder</a></li> |
| <li><a href="#sec:Incremental_Builder_Overview__IBuilderState">7.5.2. IBuilderState</a> |
| <ul class="sectlevel4"> |
| <li><a href="#copy-and-update-xtext-index">7.5.2.1. Copy and Update Xtext Index</a></li> |
| <li><a href="#build-state-setup-phase">7.5.2.2. Build State Setup Phase</a></li> |
| <li><a href="#process-queued-uris">7.5.2.3. Process Queued URIs</a></li> |
| <li><a href="#queueing-affected-resources">7.5.2.4. Queueing Affected Resources</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:Incremental_Builder_Overview__Example">7.5.3. Example</a></li> |
| </ul> |
| </li> |
| <li><a href="#dirty-state-handling">7.6. Dirty state handling</a> |
| <ul class="sectlevel3"> |
| <li><a href="#use-case-restoring-types-from-user-data">7.6.1. Use case: Restoring types from user data</a></li> |
| <li><a href="#use-case-updating-the-xtext-index">7.6.2. Use case: Updating the Xtext index</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="project_model.html#_project-model">8. Project Model</a> |
| <ul class="sectlevel2"> |
| <li><a href="project_model.html#sec:Package_json">8.1. Package.json File</a></li> |
| <li><a href="project_model.html#_accessing-project-information">8.2. Accessing Project Information</a> |
| <ul class="sectlevel3"> |
| <li><a href="project_model.html#sec:IN4JSCore">8.2.1. IN4JSCore</a></li> |
| <li><a href="project_model.html#sec:N4JSModel">8.2.2. N4JSModel</a></li> |
| <li><a href="project_model.html#sec:N4JSWorkspace">8.2.3. N4JSWorkspace</a></li> |
| <li><a href="project_model.html#sec:N4JSProject">8.2.4. N4JSProject</a></li> |
| <li><a href="project_model.html#sec:SourceContainer">8.2.5. SourceContainer</a></li> |
| <li><a href="project_model.html#sec:N4JSProjectsStateHelper">8.2.6. N4JSProjectsStateHelper</a></li> |
| </ul> |
| </li> |
| <li><a href="project_model.html#sec:Caching">8.3. Caching</a> |
| <ul class="sectlevel3"> |
| <li><a href="project_model.html#_caching-of-externallibraryworkspace">8.3.1. Caching of ExternalLibraryWorkspace</a></li> |
| <li><a href="project_model.html#_caching-of-n4jsprojectsstatehelper">8.3.2. Caching of N4JSProjectsStateHelper</a></li> |
| </ul> |
| </li> |
| <li><a href="project_model.html#sec:WildcardPathFilter">8.4. WildcardPathFilter</a></li> |
| <li><a href="project_model.html#sec:ProjectUtils">8.5. ProjectUtils</a></li> |
| </ul> |
| </li> |
| <li><a href="binding.html#_binding">9. Binding</a> |
| <ul class="sectlevel2"> |
| <li><a href="binding.html#sec:Binding_Design_Rationale">9.1. Design Rationale</a></li> |
| <li><a href="binding.html#sec:Binding_to_Members">9.2. Binding to Members</a></li> |
| <li><a href="binding.html#sec:Binding_Getter_Setter">9.3. Getter / Setter Binding</a></li> |
| <li><a href="binding.html#chap:Statics">9.4. Static Member Binding</a></li> |
| <li><a href="binding.html#sec:Binding_Enumeration">9.5. Enumeration Literals Binding</a></li> |
| <li><a href="binding.html#sec:Accessibility_of_types_and_members">9.6. Accessibility of types and members</a></li> |
| <li><a href="binding.html#sec:Member_Scope_Example">9.7. Member Scope Example</a></li> |
| <li><a href="binding.html#sec:Scoping_for_Members_of_Composed_Type_Explained">9.8. Scoping for Members of Composed Type (Union/Intersection) Example</a></li> |
| <li><a href="binding.html#sec:Binding_of_Structurally_References_Types">9.9. Structurally References Types</a></li> |
| <li><a href="binding.html#sec:Building">9.10. Building</a> |
| <ul class="sectlevel3"> |
| <li><a href="binding.html#sec:Build_Phases">9.10.1. Build Phases</a></li> |
| <li><a href="binding.html#sec:Build_Scenarios">9.10.2. Build Scenarios</a></li> |
| <li><a href="binding.html#sec:Lazy_linking_problem">9.10.3. Lazy linking problem</a></li> |
| </ul> |
| </li> |
| <li><a href="binding.html#sec:Proxies_and_Proxy_Resolution">9.11. Proxies and Proxy Resolution (Overview)</a> |
| <ul class="sectlevel3"> |
| <li><a href="binding.html#xtexts-lazy-linking-proxies">9.11.1. Xtext’s Lazy Linking Proxies</a></li> |
| <li><a href="binding.html#standard-emf-proxies">9.11.2. Standard EMF Proxies</a></li> |
| <li><a href="binding.html#_how-is-proxy-resolution-triggered">9.11.3. How is Proxy Resolution Triggered?</a></li> |
| <li><a href="binding.html#_when-is-proxy-resolution-allowed">9.11.4. When is Proxy Resolution Allowed?</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="validation.html#_validation">10. Validation</a> |
| <ul class="sectlevel2"> |
| <li><a href="validation.html#sec:validation_overview">10.1. Validation overview</a></li> |
| <li><a href="validation.html#sec:validation_control_flow">10.2. Validation control flow</a></li> |
| <li><a href="validation.html#sec:validation_issue_ids">10.3. Issue IDs and Messages</a></li> |
| <li><a href="validation.html#sec:validation_usage_patterns">10.4. Usage Pattern</a></li> |
| <li><a href="validation.html#sec:validation_links">10.5. Links</a></li> |
| </ul> |
| </li> |
| <li><a href="references.html#_references">11. References</a> |
| <ul class="sectlevel2"> |
| <li><a href="references.html#sec:usecases">11.1. Use cases</a></li> |
| <li><a href="references.html#sec:calculation_algorithm">11.2. Calculation algorithm</a> |
| <ul class="sectlevel3"> |
| <li><a href="references.html#sec:Xtext_default_implementation">11.2.1. Xtext default implementation</a></li> |
| <li><a href="references.html#sec:N4_implementation">11.2.2. N4JS implementation</a></li> |
| </ul> |
| </li> |
| <li><a href="references.html#sec:PerformanceOfDependencyCalculation">11.3. Performance Of Dependency Calculation</a></li> |
| <li><a href="references.html#sec:kinds_of_references">11.4. Kinds of references</a> |
| <ul class="sectlevel3"> |
| <li><a href="references.html#sec:Cross_References_to_be_ignored">11.4.1. Cross References to be ignored</a></li> |
| <li><a href="references.html#sec:Cross_References_to_be_handled">11.4.2. Cross References to be handled</a></li> |
| </ul> |
| </li> |
| <li><a href="references.html#sec:transitive_dependencies">11.5. Transitive dependencies</a></li> |
| <li><a href="references.html#sec:find-references">11.6. Find references</a> |
| <ul class="sectlevel3"> |
| <li><a href="references.html#_background">11.6.1. Background</a></li> |
| <li><a href="references.html#_how-find-references-work">11.6.2. How Find References Work</a> |
| <ul class="sectlevel4"> |
| <li><a href="references.html#_step-1-convert-cursor-position-to-declared-element">11.6.2.1. Step 1: Convert Cursor Position to Declared Element</a></li> |
| <li><a href="references.html#_step-2-convert-declared-element-to-target-uris">11.6.2.2. Step 2: Convert Declared Element to Target URIs</a></li> |
| <li><a href="references.html#_step-3-filter-potential-resources">11.6.2.3. Step 3: Filter Potential Resources</a></li> |
| <li><a href="references.html#_step-4-search-references-in-resource">11.6.2.4. Step 4: Search References in Resource</a></li> |
| <li><a href="references.html#_limitations-and-possible-enhancements">11.6.2.5. Limitations and Possible Enhancements</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="compilation.html#_compilation">12. Compilation</a> |
| <ul class="sectlevel2"> |
| <li><a href="compilation.html#chap:compilation">12.1. Introduction</a> |
| <ul class="sectlevel3"> |
| <li><a href="compilation.html#sec:general_design_rationals">12.1.1. General design rationals</a> |
| <ul class="sectlevel4"> |
| <li><a href="compilation.html#sec:logging_and_error_reporting">12.1.1.1. Logging and error reporting</a></li> |
| <li><a href="compilation.html#sec:progress_monitor">12.1.1.2. Progress monitor</a></li> |
| </ul> |
| </li> |
| <li><a href="compilation.html#sec:Xtext_Integration">12.1.2. Xtext Integration</a> |
| <ul class="sectlevel4"> |
| <li><a href="compilation.html#sec:xtext_default_behaviour">12.1.2.1. Xtext default behaviour</a></li> |
| <li><a href="compilation.html#sec:n4js_requirements">12.1.2.2. N4JS requirements</a></li> |
| <li><a href="compilation.html#sec:compiler_discovery_in_ui">12.1.2.3. Compiler discovery in UI</a></li> |
| <li><a href="compilation.html#sec:compiler_discovery_in_headless">12.1.2.4. Compiler discovery in headless</a></li> |
| <li><a href="compilation.html#sec:general_generator_implementation">12.1.2.5. General generator implementation</a></li> |
| <li><a href="compilation.html#sec:general_generator_activation">12.1.2.6. General generator activation</a></li> |
| </ul> |
| </li> |
| <li><a href="compilation.html#sec:Overview_of_Input_Models">12.1.3. Overview of the Input Models</a></li> |
| </ul> |
| </li> |
| <li><a href="compilation.html#sec:Core_Generator">12.2. Generators</a> |
| <ul class="sectlevel3"> |
| <li><a href="compilation.html#sec:Compiler_Components">12.2.1. Generator Components</a></li> |
| <li><a href="compilation.html#sec:Generator_architecture">12.2.2. Generator architecture</a></li> |
| <li><a href="compilation.html#sec:Unified_Compiler_Configuration">12.2.3. Unified Compiler Configuration</a></li> |
| </ul> |
| </li> |
| <li><a href="compilation.html#sec:Transpilers">12.3. Transpilers</a> |
| <ul class="sectlevel3"> |
| <li><a href="compilation.html#sec:Phases">12.3.1. Overview</a></li> |
| <li><a href="compilation.html#relation-between-ast-and-im">12.3.2. Relation between AST and IM</a></li> |
| <li><a href="compilation.html#implementation-overview">12.3.3. Implementation Overview</a></li> |
| <li><a href="compilation.html#sec:Guidelines_for_Implementing_Transformations">12.3.4. Guidelines for Implementing Transformations</a></li> |
| <li><a href="compilation.html#symbol-table-in-the-im">12.3.5. Symbol Table in the IM</a></li> |
| </ul> |
| </li> |
| <li><a href="compilation.html#sec:N4JS_to_EcmaScript_Transpiler">12.4. N4JS-to-EcmaScript Transpiler</a> |
| <ul class="sectlevel3"> |
| <li><a href="compilation.html#sec:Overview_of_Transformations">12.4.1. Overview of Transformations</a></li> |
| <li><a href="compilation.html#sec:Transpiling_members">12.4.2. Transpiling members</a> |
| <ul class="sectlevel4"> |
| <li><a href="compilation.html#sec:Transpiling_members__Delegating_members">12.4.2.1. Techniques for special member handling</a></li> |
| <li><a href="compilation.html#sec:Transpiling_members__Partial_shadowing_of_getter_setter_pairs">12.4.2.2. Partial shadowing</a></li> |
| <li><a href="compilation.html#sec:Transpiling_members__Consuming_or_inheriting_members_of_an_interface">12.4.2.3. Consuming or inheriting members of an interface</a></li> |
| <li><a href="compilation.html#sec:Transpiling_members__Static_polyfill">12.4.2.4. Static polyfill</a></li> |
| <li><a href="compilation.html#sec:Transpiling_members__API_implementation_stubs">12.4.2.5. API / implementation stubs</a></li> |
| </ul> |
| </li> |
| <li><a href="compilation.html#sec:Support_for_incomplete_API_implementation_testing_in_the_N4JS_to_EcmaScript_5_Transpiler">12.4.3. Support for incomplete API implementation testing</a> |
| <ul class="sectlevel4"> |
| <li><a href="compilation.html#sec:Modifications_in_Impl_projects">12.4.3.1. Modifications in Impl projects</a></li> |
| <li><a href="compilation.html#sec:Implementation_of_stub_generation">12.4.3.2. Implementation of stub-generation</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="compilation.html#sec:n4jsc_Headless_Compiler_Interface">12.5. n4jsc Headless Compiler Interface</a> |
| <ul class="sectlevel3"> |
| <li><a href="compilation.html#sec:building_the_headless_compiler">12.5.1. building the headless compiler</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="execution.html#_execution">13. Execution</a> |
| <ul class="sectlevel2"> |
| <li><a href="execution.html#sec:N4JS_Project_Execution_And_Linking_Model">13.1. N4JS Project Execution And Linking Model</a> |
| <ul class="sectlevel3"> |
| <li><a href="execution.html#subsec:N4JS_Execution_With_NodeJS">13.1.1. N4JS Execution With NodeJS</a></li> |
| </ul> |
| </li> |
| <li><a href="execution.html#sec:N4JS_Execution_And_Linking_File">13.2. N4JS Execution And Linking File</a> |
| <ul class="sectlevel3"> |
| <li><a href="execution.html#subsec:NodeJS_Specific_ELF">13.2.1. NodeJS Specific ELF</a></li> |
| </ul> |
| </li> |
| <li><a href="execution.html#sec:Runners-execution">13.3. Runners</a> |
| <ul class="sectlevel3"> |
| <li><a href="execution.html#subsec:N4_Runtime_Environments_Convention">13.3.1. N4 Runtime Environments Convention</a></li> |
| <li><a href="execution.html#subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment">13.3.2. Passing Information from IDE to Execution Code in Runtime Environment</a></li> |
| <li><a href="execution.html#subsec:Runners_Design">13.3.3. Runners Design</a></li> |
| </ul> |
| </li> |
| <li><a href="execution.html#sec:Legacy_Execution_Engine">13.4. Legacy Execution Engine</a></li> |
| <li><a href="execution.html#sec:Design">13.5. Design</a> |
| <ul class="sectlevel3"> |
| <li><a href="execution.html#sec:Usage_Outside_N4JSIDE">13.5.1. Usage Outside N4JSIDE</a> |
| <ul class="sectlevel4"> |
| <li><a href="execution.html#sec:Use_Node_with_Maven">13.5.1.1. Use Node with Maven</a></li> |
| </ul> |
| </li> |
| <li><a href="execution.html#sec:Usage_Inside_N4JSIDE">13.5.2. Usage Inside N4JSIDE</a></li> |
| </ul> |
| </li> |
| <li><a href="execution.html#sec:Runtime_Injection">13.6. Runtime Injection</a> |
| <ul class="sectlevel3"> |
| <li><a href="execution.html#sec:Running_String_Code">13.6.1. Running String Code</a></li> |
| <li><a href="execution.html#sec:Running_File_Code">13.6.2. Running File Code</a></li> |
| <li><a href="execution.html#sec:Injection_Code_Example">13.6.3. Injection Code Example</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="tests.html#_tests">14. Tests</a> |
| <ul class="sectlevel2"> |
| <li><a href="tests.html#sec:Performance_Tests">14.1. Performance Tests</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#sec:Synthetic_Performance_Tests">14.1.1. Synthetic Performance Tests</a> |
| <ul class="sectlevel4"> |
| <li><a href="tests.html#sec:Design_of_Generator">14.1.1.1. Design of Generator</a></li> |
| <li><a href="tests.html#sec:Design_of_Performance_Test_Execution">14.1.1.2. Design of Performance Test Configuration and Execution</a></li> |
| <li><a href="tests.html#sec:JUnit_Configuration">14.1.1.3. JUnit Configuration</a></li> |
| <li><a href="tests.html#sec:JUnitBenchmark_Test_Configuration">14.1.1.4. JUnitBenchmark Test Configuration</a></li> |
| <li><a href="tests.html#sec:JUnitBenchmark_Report_Configuration">14.1.1.5. JUnitBenchmark Report Configuration</a></li> |
| <li><a href="tests.html#sec:JUnitBenchmark_Run_Configuration">14.1.1.6. JUnitBenchmark Run Configuration</a></li> |
| <li><a href="tests.html#sec:JUnitBenchmark_Example">14.1.1.7. JUnitBenchmark Example</a></li> |
| <li><a href="tests.html#sec:Note_on_Jenkins_Job">14.1.1.8. Note on Jenkins Job</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:ECMA_Tests">14.2. ECMA Tests</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#sec:Grammar_Tests">14.2.1. Grammar Tests</a> |
| <ul class="sectlevel4"> |
| <li><a href="tests.html#sec:Negative_Tests">14.2.1.1. Negative Tests</a></li> |
| <li><a href="tests.html#sec:Test_Exclusion">14.2.1.2. Test Exclusion</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:Integration_Tests">14.3. Integration Tests</a></li> |
| <li><a href="tests.html#sec:Test_Helpers">14.4. Test Helpers</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#sec:Parameterized_N4JS_Tests">14.4.1. Parameterized N4JS tests</a> |
| <ul class="sectlevel4"> |
| <li><a href="tests.html#sec:ParameterizedXtextRunner">14.4.1.1. ParameterizedXtextRunner</a></li> |
| <li><a href="tests.html#sec:TestCodeProvider">14.4.1.2. TestCodeProvider</a></li> |
| <li><a href="tests.html#sec:Example_Of_Parameterized_Parser_Test">14.4.1.3. Example of parameterized parser test</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:Issue_Suppression">14.5. Issue Suppression</a></li> |
| <li><a href="tests.html#sec:Xpect_Tests">14.6. Xpect Tests</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#sec:Xpect_Test_Setup">14.6.1. Xpect Test Setup</a></li> |
| <li><a href="tests.html#sec:Xpect_Issue_Suppression">14.6.2. Xpect Issue Suppression</a></li> |
| <li><a href="tests.html#sec:Xpect_Provided_Test_Methods">14.6.3. Xpect Provided Test Methods</a> |
| <ul class="sectlevel4"> |
| <li><a href="tests.html#errors">14.6.3.1. errors</a></li> |
| <li><a href="tests.html#warnings">14.6.3.2. warnings</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:N4JS_Specific_Xpect_Test_Methods">14.6.4. N4JS Specific Xpect Test Methods</a> |
| <ul class="sectlevel4"> |
| <li><a href="tests.html#sec:XPECT_noerrors">14.6.4.1. noerrors and nowarnings</a></li> |
| <li><a href="tests.html#sec:XPECT_scope">14.6.4.2. scope</a></li> |
| <li><a href="tests.html#sec:XPECT_scopeWithPosition">14.6.4.3. scopeWithPosition</a></li> |
| <li><a href="tests.html#sec:XPECT_scopeWithResource">14.6.4.4. scopeWithResource</a></li> |
| <li><a href="tests.html#sec:XPECT_binding">14.6.4.5. binding</a></li> |
| <li><a href="tests.html#sec:XPECT_linkedPathname">14.6.4.6. linkedPathname</a></li> |
| <li><a href="tests.html#sec:XPECT_type_of">14.6.4.7. type of</a></li> |
| <li><a href="tests.html#sec:XPECT_expectedType">14.6.4.8. expectedType</a></li> |
| <li><a href="tests.html#sec:XPECT_elementKeyword">14.6.4.9. elementKeyword</a></li> |
| <li><a href="tests.html#sec:XPECT_accessModifier">14.6.4.10. accessModifier</a></li> |
| <li><a href="tests.html#sec:XPECT_compileResult">14.6.4.11. compileResult</a></li> |
| <li><a href="tests.html#sec:XPECT_output">14.6.4.12. output</a></li> |
| <li><a href="tests.html#sec:XPECT_outputRegEx">14.6.4.13. outputRegEx</a></li> |
| <li><a href="tests.html#sec:XPECT_calculatedAccessModifier">14.6.4.14. calculatedAccessModifier</a></li> |
| <li><a href="tests.html#sec:XPECT_spec">14.6.4.15. spec</a></li> |
| <li><a href="tests.html#sec:XPECT_deadCode">14.6.4.16. deadCode</a></li> |
| <li><a href="tests.html#sec:XPECT_returnOrThrows">14.6.4.17. returnOrThrows</a></li> |
| <li><a href="tests.html#sec:XPECT_lint">14.6.4.18. lint</a></li> |
| <li><a href="tests.html#sec:XPECT_lintFails">14.6.4.19. lintFails</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:FIXME_Xpect_modifier">14.6.5. FIXME Xpect modifier</a></li> |
| <li><a href="tests.html#sec:Expectmatrix_Xpect_Test_Methods">14.6.6. Expectmatrix Xpect tests</a></li> |
| <li><a href="tests.html#xpect-lint-tests">14.6.7. Xpect Lint Tests</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#xpect-proposal-tests">14.7. Xpect Proposal Tests</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#sec:Validation_vs__Non_Validation">14.7.1. Validation vs. Non-Validation</a></li> |
| <li><a href="tests.html#sec:General_Proposal_Test_Features">14.7.2. General Proposal Test Features</a> |
| <ul class="sectlevel4"> |
| <li><a href="tests.html#sec:Test_Variables">14.7.2.1. Test Variables</a></li> |
| <li><a href="tests.html#sec:Location_and_Selection">14.7.2.2. at – Location and Selection</a></li> |
| <li><a href="tests.html#sec:Multi_Line_Expectations_in_Proposal_Tests">14.7.2.3. Multi Line Expectations in Proposal Tests</a></li> |
| <li><a href="tests.html#sec:Timeout">14.7.2.4. Timeout and Performance</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#proposals-verify-existence-of-proposals">14.7.3. proposals – Verify Existence of Proposals</a></li> |
| <li><a href="tests.html#sec:Verify_displayed_string">14.7.4. display – Verify displayed string</a></li> |
| <li><a href="tests.html#sec:Apply_Proposal">14.7.5. apply – Apply Proposal</a> |
| <ul class="sectlevel4"> |
| <li><a href="tests.html#resource-application-in-other-files">14.7.5.1. resource – application in other files</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:Content_Assist_Cycling">14.7.6. kind – Content Assist Cycling</a></li> |
| <li><a href="tests.html#fileValidVerify-validation-status">14.7.7. fileValid – Verify validation status</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:Apply_Proposal_And_Execute_Tests">14.8. Apply Proposal And Execute Tests</a></li> |
| <li><a href="tests.html#sec:Organize_Imports_Test">14.9. Organize Imports Test</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#organizeimports">14.9.1. organizeImports</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:Access_Control_Test">14.10. Access Control Test</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#test-scenarios">14.10.1. Test Scenarios</a></li> |
| <li><a href="tests.html#n4js-code-generator">14.10.2. N4JS Code Generator</a></li> |
| <li><a href="tests.html#xtext-issue-matcher">14.10.3. Xtext Issue Matcher</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:Smoke_Tests">14.11. Smoke Tests</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#how-to-handle-smoke-test-errors">14.11.1. How to handle smoke test errors?</a></li> |
| <li><a href="tests.html#smoketester-and-exceptionanalyzer">14.11.2. SmokeTester and ExceptionAnalyzer</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:UI_Tests_with_SWTBot">14.12. UI Tests with SWTBot</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#writing-swtbot-tests">14.12.1. Writing SWTBot Tests</a></li> |
| <li><a href="tests.html#running-swtbot-tests">14.12.2. Running SWTBot Tests</a></li> |
| </ul> |
| </li> |
| <li><a href="tests.html#sec:Debugging_UI_Tests">14.13. Debugging UI Tests</a> |
| <ul class="sectlevel3"> |
| <li><a href="tests.html#sec:Connecting_to_the_X_server_on_the_build_node">14.13.1. Connecting to the X-server on the build-node</a></li> |
| <li><a href="tests.html#sec:Tools_to_investigate_the_java_stack">14.13.2. Tools to investigate the java-stack</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="ui_concepts.html#_ui-concepts">15. UI Concepts</a> |
| <ul class="sectlevel2"> |
| <li><a href="ui_concepts.html#sec:User_Interface_Concepts">15.1. User Interface Concepts</a> |
| <ul class="sectlevel3"> |
| <li><a href="ui_concepts.html#sec:Eclipse_UI_Concepts">15.1.1. Eclipse UI Concepts</a> |
| <ul class="sectlevel4"> |
| <li><a href="ui_concepts.html#sec:Label_Provider">15.1.1.1. Label Provider</a></li> |
| <li><a href="ui_concepts.html#sec:Markers">15.1.1.2. Markers</a></li> |
| <li><a href="ui_concepts.html#sec:Commands__Toolbar_and_Menus">15.1.1.3. Commands, Toolbar and Menus</a></li> |
| <li><a href="ui_concepts.html#sec:Content_Assist">15.1.1.4. Content Assist</a></li> |
| <li><a href="ui_concepts.html#sec:Quick_Fixes">15.1.1.5. Quick Fixes</a></li> |
| <li><a href="ui_concepts.html#sec:Quick_Assist">15.1.1.6. Quick Assist</a></li> |
| <li><a href="ui_concepts.html#sec:Clean_Up_Actions">15.1.1.7. Clean Up Actions</a></li> |
| <li><a href="ui_concepts.html#sec:Save_Actions">15.1.1.8. Save Actions</a></li> |
| <li><a href="ui_concepts.html#sec:Auto_Edit">15.1.1.9. Auto Edit</a></li> |
| <li><a href="ui_concepts.html#sec:Template_Proposals">15.1.1.10. Template Proposals</a></li> |
| <li><a href="ui_concepts.html#sec:Outline_View___Quick_Outline">15.1.1.11. Outline View / Quick Outline</a></li> |
| <li><a href="ui_concepts.html#sec:Navigator__Package_Explorer__Project_Explorer">15.1.1.12. Navigator, Package Explorer, Project Explorer</a></li> |
| <li><a href="ui_concepts.html#sec:Hyperlinking_and_Navigation">15.1.1.13. Hyperlinking and Navigation</a></li> |
| <li><a href="ui_concepts.html#sec:Syntax_and_Semantic_Coloring">15.1.1.14. Syntax and Semantic Coloring</a></li> |
| <li><a href="ui_concepts.html#sec:Code_Formatter">15.1.1.15. Code Formatter</a></li> |
| <li><a href="ui_concepts.html#sec:Wizards">15.1.1.16. Wizards</a></li> |
| <li><a href="ui_concepts.html#sec:Cheat_Sheets">15.1.1.17. Cheat Sheets</a></li> |
| <li><a href="ui_concepts.html#sec:Context_sensitive_Help">15.1.1.18. Context-sensitive Help</a></li> |
| <li><a href="ui_concepts.html#sec:Hovers">15.1.1.19. Hovers</a></li> |
| <li><a href="ui_concepts.html#sec:Folding">15.1.1.20. Folding</a></li> |
| <li><a href="ui_concepts.html#sec:Customizable_validation___severity">15.1.1.21. Customizable validation / severity</a></li> |
| <li><a href="ui_concepts.html#sec:Proposals">15.1.1.22. Proposals</a></li> |
| </ul> |
| </li> |
| <li><a href="ui_concepts.html#sec:Non_Eclipse_UI_Concepts">15.1.2. Non-Eclipse UI Concepts</a> |
| <ul class="sectlevel4"> |
| <li><a href="ui_concepts.html#sec:Overlays">15.1.2.1. Overlays</a></li> |
| <li><a href="ui_concepts.html#sec:Goto__Inferred__Type">15.1.2.2. Goto (Inferred) Type</a></li> |
| <li><a href="ui_concepts.html#sec:Postfix_Completion">15.1.2.3. Postfix Completion</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="ui_concepts.html#_user-interface-resources">15.2. User Interface Resources</a> |
| <ul class="sectlevel3"> |
| <li><a href="ui_concepts.html#_icons">15.2.1. Icons</a> |
| <ul class="sectlevel4"> |
| <li><a href="ui_concepts.html#_eclipse-platform-icons">15.2.1.1. Eclipse Platform Icons</a></li> |
| <li><a href="ui_concepts.html#_n4js-specific-icons">15.2.1.2. N4JS Specific Icons</a></li> |
| <li><a href="ui_concepts.html#_high-resolution-icons">15.2.1.3. High Resolution Icons</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="formatting.html#_formatting">16. Formatting</a> |
| <ul class="sectlevel2"> |
| <li><a href="formatting.html#sec:FmtObjective">16.1. Objective</a> |
| <ul class="sectlevel3"> |
| <li><a href="formatting.html#sec:FmtFormatting_Comments">16.1.1. Formatting Comments</a></li> |
| </ul> |
| </li> |
| <li><a href="formatting.html#sec:FmtArchitecture">16.2. Architecture</a> |
| <ul class="sectlevel3"> |
| <li><a href="formatting.html#sec:Implementation_example">16.2.1. Implementation example</a></li> |
| </ul> |
| </li> |
| <li><a href="formatting.html#sec:FmtFormatter_Implementation_Guidelines">16.3. Formatter Implementation Guidelines</a></li> |
| <li><a href="formatting.html#sec:FmtConfiguration">16.4. Configuration</a></li> |
| <li><a href="formatting.html#sec:FmtUI_Integration">16.5. UI Integration</a></li> |
| <li><a href="formatting.html#sec:FmtUnit_Testing_with_Xpect">16.6. Unit Testing with Xpect</a></li> |
| </ul> |
| </li> |
| <li><a href="external_libraries.html#_external-libraries">17. External Libraries</a> |
| <ul class="sectlevel2"> |
| <li><a href="external_libraries.html#sec:Major_Components">17.1. Major Components</a> |
| <ul class="sectlevel3"> |
| <li><a href="external_libraries.html#subsec:External_Resources">17.1.1. External Resources</a></li> |
| <li><a href="external_libraries.html#subsec:External_Library_Workspace">17.1.2. External Library Workspace</a></li> |
| <li><a href="external_libraries.html#subsec:External_Library_Preference_Store">17.1.3. External Library Preference Store</a></li> |
| <li><a href="external_libraries.html#subsec:npm_Manager">17.1.4. Library Manager</a></li> |
| <li><a href="external_libraries.html#subsec:External_Library_Builder_Helper">17.1.5. External Library Builder</a></li> |
| <li><a href="external_libraries.html#subsec:External_Library_Xtext_Index_Persister">17.1.6. External Library Xtext Index Persister</a></li> |
| <li><a href="external_libraries.html#subsec:External_Library_Preference_Page">17.1.7. External Library Preference Page</a></li> |
| </ul> |
| </li> |
| <li><a href="external_libraries.html#sec:Headless_External_Library_Support">17.2. Headless External Library Support</a> |
| <ul class="sectlevel3"> |
| <li><a href="external_libraries.html#_custom-npm-settings">17.2.1. Custom npm settings</a></li> |
| </ul> |
| </li> |
| <li><a href="external_libraries.html#sec:lmFutureWork">17.3. Future Work</a> |
| <ul class="sectlevel3"> |
| <li><a href="external_libraries.html#subsec:lmMultipleDependencyScope">17.3.1. Multiple Dependency Scope</a></li> |
| <li><a href="external_libraries.html#subsec:lmRunTestsFromLibrary">17.3.2. Run Tests from TestLibrary</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="json_support.html#sec:JSON_Support">18. JSON Support</a> |
| <ul class="sectlevel2"> |
| <li><a href="json_support.html#sec:JSON_Parser">18.1. JSON Parser</a> |
| <ul class="sectlevel3"> |
| <li><a href="json_support.html#sec:JSON_Parser_Unicode_Escaping">18.1.1. Escaping Unicode Control Characters in String Literals</a></li> |
| <li><a href="json_support.html#sec:JSON_Parser_Empty_Text">18.1.2. Empty Text</a></li> |
| <li><a href="json_support.html#sec:JSON_Parser_Nested_Structures">18.1.3. Nested Structures</a></li> |
| <li><a href="json_support.html#sec:JSON_Parser_Whitespace">18.1.4. Whitespace</a></li> |
| <li><a href="json_support.html#sec:JSON_Parser_Comments">18.1.5. Comments</a></li> |
| </ul> |
| </li> |
| <li><a href="json_support.html#sec:JSON_Language_Extensions">18.2. JSON Language Extensions</a> |
| <ul class="sectlevel3"> |
| <li><a href="json_support.html#sec:JSON_Validator_Extensions">18.2.1. JSON Validator Extensions</a> |
| <ul class="sectlevel4"> |
| <li><a href="json_support.html#sec:File_Specitic_Validator_Extensions">18.2.1.1. File-Specific Validator Extensions</a></li> |
| <li><a href="json_support.html#sec:JSON_Declarative_JSON_Validator_Extensions">18.2.1.2. Declarative JSON Validator Extensions</a></li> |
| </ul> |
| </li> |
| <li><a href="json_support.html#_json-resource-description-strategy">18.2.2. JSON Resource Description Strategy</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="jsdoc.html#_jsdoc">19. JSDoc</a> |
| <ul class="sectlevel2"> |
| <li><a href="jsdoc.html#sec:Design_Rationale">19.1. Design Rationale</a> |
| <ul class="sectlevel3"> |
| <li><a href="jsdoc.html#_general-design">19.1.1. General Design</a></li> |
| <li><a href="jsdoc.html#sec:Type_Expressions">19.1.2. Type Expressions</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="docexporter.html#_docexporter">20. DocExporter</a> |
| <ul class="sectlevel2"> |
| <li><a href="docexporter.html#sec:Specification_Exporter">20.1. Specification Exporter</a></li> |
| </ul> |
| </li> |
| <li><a href="rename_refactoring.html#_rename-refactoring">21. Rename Refactoring</a> |
| <ul class="sectlevel2"> |
| <li><a href="rename_refactoring.html#_rename-refactoring-ui-interaction">21.1. Rename Refactoring UI interaction</a></li> |
| <li><a href="rename_refactoring.html#_renameelementprocessor-interaction">21.2. RenameElementProcessor interaction</a></li> |
| </ul> |
| </li> |
| <li><a href="flow_graphs.html#chap:flowgraphs">22. Flow Graphs</a> |
| <ul class="sectlevel2"> |
| <li><a href="flow_graphs.html#sec:flowgraphs_overview">22.1. Flow graphs overview</a> |
| <ul class="sectlevel3"> |
| <li><a href="flow_graphs.html#_internal-graph">22.1.1. Internal graph</a></li> |
| <li><a href="flow_graphs.html#_optimizations">22.1.2. Optimizations</a></li> |
| <li><a href="flow_graphs.html#_api-for-client-analyses">22.1.3. API for client analyses</a> |
| <ul class="sectlevel4"> |
| <li><a href="flow_graphs.html#_mapping-from-internal-to-ast-elements">22.1.3.1. Mapping from internal to AST elements</a></li> |
| <li><a href="flow_graphs.html#_graph-visitor">22.1.3.2. Graph visitor</a></li> |
| <li><a href="flow_graphs.html#_graph-explorer">22.1.3.3. Graph explorer</a></li> |
| <li><a href="flow_graphs.html#_branch-walker">22.1.3.4. Branch walker</a></li> |
| <li><a href="flow_graphs.html#_example-1-compute-string-for-each-path">22.1.3.5. Example 1: Compute string for each path</a></li> |
| <li><a href="flow_graphs.html#_path-quantor">22.1.3.6. Path quantor</a></li> |
| </ul> |
| </li> |
| <li><a href="flow_graphs.html#_control-flow-analyses">22.1.4. Control flow analyses</a> |
| <ul class="sectlevel4"> |
| <li><a href="flow_graphs.html#_dead-code-analysis">22.1.4.1. Dead code analysis</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="flow_graphs.html#sec:dataflow">22.2. Dataflow</a> |
| <ul class="sectlevel3"> |
| <li><a href="flow_graphs.html#_dataflow-graph">22.2.1. Dataflow graph</a></li> |
| <li><a href="flow_graphs.html#_dataflow-analyses">22.2.2. Dataflow analyses</a> |
| <ul class="sectlevel4"> |
| <li><a href="flow_graphs.html#_def-def-def-nothing-analysis">22.2.2.1. Def→Def / Def→Nothing analysis</a></li> |
| <li><a href="flow_graphs.html#_def-use-decl-analysis">22.2.2.2. Def|Use←Decl analysis</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="publish_npms.html#sec:publish-npms-to-public">23. Publish npms</a> |
| <ul class="sectlevel2"> |
| <li><a href="publish_npms.html#sec:publish-npms-n4js-maven">23.1. Publish n4js-libs to during maven build</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_a_hints.html#sec:Hints">Appendix A: Hints</a> |
| <ul class="sectlevel2"> |
| <li><a href="appendix_a_hints.html#sec:XtextInjection">A.1. Xtext Injection</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_a_hints.html#sec:DI_MultipleInjectors_Singletons">A.1.1. Multiple Injectors and Singletons</a> |
| <ul class="sectlevel4"> |
| <li><a href="appendix_a_hints.html#sec:DI_avoid_duplicate_singletons">A.1.1.1. Avoiding duplicate singletons</a> |
| <ul class="sectlevel5"> |
| <li><a href="appendix_a_hints.html#sec:DI_binding_in_shared">A.1.1.1.1. Defining binding in the shared injector</a></li> |
| <li><a href="appendix_a_hints.html#sec:DI_binding_in_custom">A.1.1.1.2. Defining binding in the custom injector</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="appendix_a_hints.html#sec:DI_Hints">A.1.2. Dependency Injection Hints</a> |
| <ul class="sectlevel4"> |
| <li><a href="appendix_a_hints.html#sec:DI_custom_bundle">A.1.2.1. Use DI in custom bundle, use DI with extensions</a> |
| <ul class="sectlevel5"> |
| <li><a href="appendix_a_hints.html#sec:DI_custom_bundle_problem">A.1.2.1.1. Problem</a></li> |
| <li><a href="appendix_a_hints.html#sec:DI_custom_bundle_solution">A.1.2.1.2. Solution</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_a_hints.html#sec:Access_Other_DSL_Injector">A.1.2.2. How do I get the Guice Injector of my language?</a> |
| <ul class="sectlevel5"> |
| <li><a href="appendix_a_hints.html#sec:DSL_Injector_UI_context">A.1.2.2.1. UI context</a></li> |
| <li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_context">A.1.2.2.2. Non UI context but with injection context</a></li> |
| <li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_non_injection_context">A.1.2.2.3. Non UI context without injection context</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_a_hints.html#sec:Cancel_Indicator">A.1.2.3. How do I get cancel indicators in different contexts?</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="appendix_a_hints.html#sec:Eclipse">A.2. Eclipse</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_a_hints.html#sec:Show_Xtext_Index">A.2.1. Show the current Xtext index</a></li> |
| <li><a href="appendix_a_hints.html#sec:Plugin_spy">A.2.2. Plug-in spy</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_a_hints.html#sec:Maven-hints">A.3. Maven</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_a_hints.html#how-to-check-for-maven-mojo-updates">A.3.1. How to check for Maven MOJO updates</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#_module-loading">Appendix B: Module Loading</a> |
| <ul class="sectlevel2"> |
| <li><a href="appendix_b_module_loading.html#sec:Dependency_Management">B.1. Dependency Management</a></li> |
| <li><a href="appendix_b_module_loading.html#ecmascript-modules">B.2. ECMAScript Modules</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_b_module_loading.html#sec:ES5_Modules_Systems">B.2.1. ES5 Modules Systems</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:ES6_Modules">B.2.2. ES6 Modules</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#sec:ECMAScript_Module_Loaders">B.3. ECMAScript Module Loaders</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_b_module_loading.html#sec:ES6_Module_Loaders">B.3.1. ES6 Module Loaders</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Polyfills_for_ES6_Module_Loaders">B.3.2. Polyfills for ES6 Module Loaders</a> |
| <ul class="sectlevel4"> |
| <li><a href="appendix_b_module_loading.html#sec:es6_module_loader">B.3.2.1. es6-module-loader</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:SystemJS">B.3.2.2. SystemJS</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Demo">B.3.2.3. Demo</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#case-study-typescript">B.4. Case Study : TypeScript</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_b_module_loading.html#sec:ES6_Modules_Support">B.4.1. ES6 Modules Support</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:TypeScript_and_Module_Loading">B.4.2. TypeScript and Module Loading</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#sec:Cyclic_Dependencies">B.5. Cyclic Dependencies</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_b_module_loading.html#sec:Setup">B.5.1. Setup</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Transpile_and_Execute">B.5.2. Transpile and Execute</a> |
| <ul class="sectlevel4"> |
| <li><a href="appendix_b_module_loading.html#sec:Module_Format___AMD">B.5.2.1. Module Format = AMD</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Module_Format___CommonJS">B.5.2.2. Module Format = CommonJS</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Module_Format___SystemJS">B.5.2.3. Module Format = SystemJS</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#sec:Conclusion">B.5.3. Conclusion</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#system.register-as-transpilation-target">B.6. System.register as transpilation target</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_b_module_loading.html#sec:Introduction">B.6.1. Introduction</a> |
| <ul class="sectlevel4"> |
| <li><a href="appendix_b_module_loading.html#sec:External_Transpilers">B.6.1.1. External Transpilers</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Example_of_a_System_register_module">B.6.1.2. Example of a System.register module</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#sec:Structure_of_a_System_register_module">B.6.2. Structure of a System.register module</a></li> |
| <li><a href="appendix_b_module_loading.html#_transpilation-hints">B.6.3. Transpilation Hints</a> |
| <ul class="sectlevel4"> |
| <li><a href="appendix_b_module_loading.html#sec:Handling_Imports">B.6.3.1. Handling Imports</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:__exportFn__">B.6.3.2. <<exportFn>></a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Handling_Exports">B.6.3.3. Handling Exports</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#sec:Examples_w__Circular_Dependencies">B.6.4. Examples w/ Circular Dependencies</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:N4JS_Examples_w__Circular_Dependencies">B.6.5. N4JS Examples w/ Circular Dependencies</a> |
| <ul class="sectlevel4"> |
| <li><a href="appendix_b_module_loading.html#sec:Unresolved_Cyclic_Dependencies">B.6.5.1. Unresolved Cyclic Dependencies</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Variables___Functions">B.6.5.2. Examples with Variables & Functions</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Classes">B.6.5.3. Examples with Classes</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Examples_with_SubClassing">B.6.5.4. Examples with SubClassing</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Miscellaneous">B.6.5.5. Miscellaneous</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#_resources">B.6.6. Resources</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#sec:CommonJS_as_transpilation_target">B.7. CommonJS as transpilation target</a> |
| <ul class="sectlevel3"> |
| <li><a href="appendix_b_module_loading.html#_introduction-2">B.7.1. Introduction</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Transpilation_Hints">B.7.2. Transpilation Hints</a> |
| <ul class="sectlevel4"> |
| <li><a href="appendix_b_module_loading.html#sec:Import_Statements">B.7.2.1. Import Statements</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Export_Statements">B.7.2.2. Export Statements</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:Tracking_Live_Bindings">B.7.2.3. Tracking Live Bindings</a></li> |
| <li><a href="appendix_b_module_loading.html#sec:A_complete_example">B.7.2.4. A complete example</a></li> |
| </ul> |
| </li> |
| <li><a href="appendix_b_module_loading.html#_resources-2">B.7.3. Resources</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="appendix_c_license.html#sec:License">Appendix C: License</a></li> |
| <li><a href="appendix_d_acronyms.html#sec:Acronyms">Appendix D: Acronyms</a></li> |
| <li><a href="appendix_e_bibliography_and_footnotes.html#_bibliography-and-footnotes">Appendix E: Bibliography and Footnotes</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"><div class="sect1"> |
| <h2 id="_type-index"><a class="anchor" href="#_type-index"></a><a class="link" href="#_type-index">7. Type Index</a></h2> |
| <div class="sectionbody"> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:Type_Index_Design_Rationale"><a class="anchor" href="#sec:Type_Index_Design_Rationale"></a><a class="link" href="#sec:Type_Index_Design_Rationale">7.1. Design Rationale</a></h3> |
| <div class="paragraph"> |
| <p>We use a separate types model to represent types, see <a href="type_system.html#sec:Type_Model_and_Grammar">Type Model and Grammar</a>. Declared elements (e.g., classes) |
| in N4JS are parsed and a new types model instance is derived from them. All type references (of the N4JS <a href="appendix_d_acronyms.html#AC">AST</a>) |
| are then bound to these type instances and not to the N4JS declaration. However, there exists a relation between a type |
| and its declaration. The type instances (which are EObjects) are added to the resource of the N4JS file as part of |
| the public interface of the resource. This public interface is represented by a <code>TModule</code>. While the actual source code |
| is the first element of a resource (index 0), the module is stored at index 1. It contains the derived type information, |
| the information about exported variables and functions as well as information about the project and vendor. The Xtext |
| serializer ignores the additional element. Besides, the complete type instances are stored in the user data section of |
| the <code>IEObjectDescription</code> of the <code>TModule</code>. Since the user data only allows strings to be stored, the EObjects are serialized |
| (within a virtual resource). When a reference is then bound to a type, the type can be directly recreated (deserialized) |
| from the user data. The deserialized EObject is then added to the appropriate resource. It is not necessary to load the |
| complete file just to refer to a type from that file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The design relies on two key features of Xtext:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Besides the parsed text (i.e., the AST), other elements can be stored in a resource, which are then ignored by |
| the Xtext serializer, while still being properly contained in an EMF resource.</p> |
| </li> |
| <li> |
| <p>The <code>DerivedStateAwareResource</code> allows some kind of post processing steps when reading a resource. This enables a custom |
| class, here <code>N4JSDerivedStateComputer</code>, to create the types models (TClass, TRole and so on) from the parsed <code>N4ClassDeclaration</code>, |
| <code>N4RoleDeclaration</code> and so on.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Getting_the_Xtext_Index_Content_IResourceDescriptions"><a class="anchor" href="#sec:Getting_the_Xtext_Index_Content_IResourceDescriptions"></a><a class="link" href="#sec:Getting_the_Xtext_Index_Content_IResourceDescriptions">7.1.1. Getting the Xtext Index (<code>IResourceDescriptions</code>) Content</a></h4> |
| <div class="paragraph"> |
| <p>An instance of the <code>IResourceDescriptions</code> can be acquired from the resource description provider. Just like all services |
| in Xtext, this can be injected into the client code as well. The resource descriptions accepts a non-null resource set. |
| The resource set argument is mandatory to provide the index with the proper state. We are differentiating between three |
| different state. The first one is the persisted one, basically the builder state is a resource description as well, and |
| it provides a content that is based on the persisted state of the files (in our case the modules and package.json file) |
| on the file system. The second one is the live scoped index, this is modification and dirty state aware. Namely when using |
| this resource descriptions then an object description will be searched in the resource set itself first, then in the dirty |
| editor’s index, finally among the persisted ones. The third index is the named builder scoped one. This index should not be |
| used by common client code, since it is designed and implemented for the Xtex builder itself.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A resource set and hence the index can be acquired from the N4JS core, in such cases an optional N4JS project can be specified. |
| The N4JS project argument is used to retrieve the underlying Eclipse resource project (if present) and get the resource set from |
| the resource set provider. This is completely ignored when the application is running in headless mode and Eclipse resource |
| projects are not available. It is also important to note that the resource set is always configured to load only the persisted |
| states.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the Eclipse platform is running, the workspace is available and the all N4JS projects are backed by an Eclipse resource |
| project. With the Eclipse resource project the resource sets can be initialized properly via the resource set initializer |
| implementations. This mechanism is used to get the global objects (such as console) and the built-in types (such as string, |
| number) into the resource set via the corresponding resource set adapters. In the headless case a special resource set |
| implementation is used; <code>ResourceSetWithBuiltInScheme</code>. This implementation is responsible to initialize the globals and the |
| built-in types into itself.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:Design_Overview"><a class="anchor" href="#sec:Design_Overview"></a><a class="link" href="#sec:Design_Overview">7.2. Design Overview</a></h3> |
| <div class="paragraph"> |
| <p><a href="#fig:cd_TypeModelWithXtextIndex">Type Model With Xtext Index</a> shows a simplified UML class diagram with the involved |
| classes. In the figure, a class (defined as N4ClassExpression in the <a href="appendix_d_acronyms.html#AC">AST</a> and its type TClass) is used as a sample, |
| declared type—roles or enums are handled similarly.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the Eclipse project build the <code>N4JSResourceDescriptionManager</code> (resp. by the logic of its super class) is called by the |
| <code>N4JSGenerateImmediatelyBuilderState</code> to get the resource description for a resource. The resource description manager loads |
| the resource to create / update the resource descriptions. Loading an Xtext resource means that it is reparsed again. |
| All cross references are handled here only by the lazy linker so that the node model will contain an unresolved proxy |
| for all cross references.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After the resource is loaded there is a derived state installed to the resource. For this the <code>N4JSDerivedStateComputer</code> will |
| be called. It will take the parse result (= EObject tree in first slot of the resource) and navigate through these objects |
| to create type trees for each encountered exportable object that are stored in exported <code>TModule</code> of the resource. |
| <a href="#fig:cd_CreateTypeFromAST">Create Type From AST</a>, a snippet of <a href="#fig:cd_TypeModelWithXtextIndex">Type Model with Xtext Index</a>, |
| shows only the classes involved when creating the types from the resource.</p> |
| </div> |
| <div id="fig:cd_CreateTypeFromAST" class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/cd_CreateTypeFromAST.png" alt="cd CreateTypeFromAST"> |
| </div> |
| <div class="title">Figure 11. Type From AST</div> |
| </div> |
| <div id="fig:cd_TypeModelWithXtextIndex" class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/cd_CreateTypeFromIndex.png" alt="cd CreateTypeFromIndex"> |
| </div> |
| <div class="title">Figure 12. Create Type From Index</div> |
| </div> |
| <div id="fig:cd_SerializeToIndex" class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/cd_SerializeToIndex.png" alt="cd SerializeToIndex"> |
| </div> |
| <div class="title">Figure 13. Serialize To Index</div> |
| </div> |
| <div class="paragraph language-javascript"> |
| <p>For these elements types have to be derived as they are exportable: <code>N4ClassDeclaration</code>, <code>N4RoleDeclaration</code>, <code>N4InterfaceDeclaration</code>, |
| <code>N4EnumDeclaration</code>, <code>ExportedVariableDeclaration</code> and <code>FunctionDeclaration</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After loading and initializing the resources now all cross references in the resources are resolved. For this the |
| <code>ErrorAwareLinkingService</code> is used. This class will in turn call the <code>N4JSScopeProvider</code> to first try to do scoping locally |
| but eventually also delegate to the global scope provider to find linked elements outside the current resource. This |
| will be done e.g. for every import statement inside the N4JS resource.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For determine the global scope all visible containers for this resource are calculated. For this the project description |
| (= loaded package.json file) is used to determine which folders of the current project should be included for looking for |
| N4JS resources. Also all referenced projects and their resources are added to the visible containers. For these containers |
| <code>N4JSGlobalScopeProvider</code> builds up a container scope. This container scope will be a <code>N4JSTypesScope</code> instance.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For the actual linked element in the resource to be resolved, its fully qualified name is used. This name is calculated by |
| using the <code>IQualifiedNameConverter</code>. We bound a custom class named <code>N4JSQualifiedNameConverter</code> who converts the <code>/</code> inside the |
| qualified name to a dot, so e.g. <code>my/module/MyFileName</code> is converted to <code>my.module.MyFileName</code>. Btw. the initial qualified name |
| was derived from the node model.</p> |
| </div> |
| <div class="paragraph"> |
| <p>With this qualified name <code>N4JSTypeScope.getSingleElement</code> is called. This method does the actual resolving of the cross reference. |
| For this the URI of the cross reference is used to determine the linked resource.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are now three cases:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the resource which contains the linked EObject is already loaded the EObject description found for the URI is returned</p> |
| </li> |
| <li> |
| <p>If the resource is not loaded but the first slot of the resource is empty the referenced type is tried to be rebuild from |
| an existing resource description for the linked resource inside the Xtext index.</p> |
| </li> |
| <li> |
| <p>If the resource is not loaded and the first slot is set, the linked EObject will be resolved with the fragment of the |
| given URI.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>While calculating the resource description for a <code>N4JSResource</code>, the EObject descriptions of their exported objects have to be |
| calculated as well. For this the <code>N4JSResourceDescriptionStrategy</code> is used. For computing the exported objects of a resource only |
| the root <code>TModule</code> and its contained types and variables are taken in consideration.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The EObjectDescriptions for a n4js resource include:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>An exported representation of the derived <code>TModule</code>. This carries these properties:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>a qualified name (e.g. <code>my.module.MyFileName</code> when the resource is stored under <code>src/my/module/MyFileName.js</code> in the project and |
| the project description has marked src has src folder). The calculation of the qualified name is delegated to the <code>N4JSNamingUtil</code>.</p> |
| </li> |
| <li> |
| <p>the user data which is the serialized string of the exported <code>TModule</code> itself. It includes the types determined for this |
| resource, so for every element found in this resource, that is contained in an <code>ExportStatement</code>, an EObject has been created |
| before in <code>N4JSDerivedStateComputer</code>. In most cases this an EObject extending <code>Type</code> from the types model, e.g. <code>TClass</code> for |
| <code>N4ClassDeclaration</code>. There is an exception for <code>ExportedVariableDeclaration</code> where <code>TVariable</code> is used as representative (and this |
| EObject is not contained in the types model only in the N4JS model). For usability reasons (quicker quick fix etc.), also |
| top level types not exported yet are stored in the <code>TModel</code>.</p> |
| </li> |
| <li> |
| <p>the information on project and vendor id are part of the module descriptor.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Descriptions for all top level types that are defined in the resource. These descriptions do not have any special properties, |
| so they just have a name.</p> |
| </li> |
| <li> |
| <p>All exported variables are also described in the resource description. They don’t carry any special information either.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The EObjectDescription for an EObject contained in an <code>ExportStatement</code>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>the qualified name of the module export (e.g. for a <code>N4ClassDeclaration</code> the qualified name <code>my.module.MyFileName.MyClassName</code> would |
| be produced, when the resource is stored under <code>src/my/module/MyFileName.js</code> in the project, the project description has marked |
| src has src folder and the N4 class uses the name MyClassName]). The calculation of the qualified name is delegated to the |
| <code>N4JSNamingUtil</code>.</p> |
| </li> |
| <li> |
| <p>the EObject represented by the EObject description, here this is not the actual EObject from N4JS but the type EObject from |
| the TypeSystem, that has been inferenced by using <code>N4JSTypeInferencer</code></p> |
| </li> |
| <li> |
| <p>the user data is only an empty map for this EObjectDescription</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>With this the resource description for a resource should be fully created / updated. <a href="#fig:cd_SerializeToIndex">Serialize to Index</a> |
| shows the classes involved creating the resource and EObjectDescriptions, along with the serialized type information.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:N4JS_Resource_Load_States"><a class="anchor" href="#sec:N4JS_Resource_Load_States"></a><a class="link" href="#sec:N4JS_Resource_Load_States">7.3. N4JS Resource Load States</a></h3> |
| <div class="paragraph"> |
| <p>Below state diagram depicts the state transitions when loading and resolving an N4JS resource.</p> |
| </div> |
| <div class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/resource_set_load_states.png" alt="resource set load states"> |
| </div> |
| <div class="title">Figure 14. N4JS Resource resolution states</div> |
| </div> |
| <div class="paragraph"> |
| <p>Additionally, the following table relates the values of the resource’s flags to the states.</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <colgroup> |
| <col style="width: 11.1111%;"> |
| <col style="width: 11.1111%;"> |
| <col style="width: 11.1111%;"> |
| <col style="width: 11.1111%;"> |
| <col style="width: 11.1111%;"> |
| <col style="width: 11.1111%;"> |
| <col style="width: 11.1111%;"> |
| <col style="width: 11.1111%;"> |
| <col style="width: 11.1112%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">State</th> |
| <th class="tableblock halign-left valign-top">Parse Result</th> |
| <th class="tableblock halign-left valign-top">AST</th> |
| <th class="tableblock halign-left valign-top">TModule</th> |
| <th class="tableblock halign-left valign-top">ASTMetaInfoCache</th> |
| <th class="tableblock halign-left valign-top">loaded</th> |
| <th class="tableblock halign-left valign-top">fullyInitialized</th> |
| <th class="tableblock halign-left valign-top">fullyProcessed</th> |
| <th class="tableblock halign-left valign-top">reconciled</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Created</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Created'</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Loaded</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">with lazy linking proxies</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Pre-linked</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">with lazy linking proxies</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">with stubs</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Fully Initialized</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">with lazy linking proxies</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">with DeferredTypeRefs</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Fully Processed</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Loaded from Description</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">proxy</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">indeterminate</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Loaded from Description'</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">proxy</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">with DeferredTypeRefs</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">indeterminate</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Fully Initialized ®</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">with lazy linking proxies</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>null</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">indeterminate</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Fully Processed ®</p></th> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">available</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">indeterminate</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Remarks:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>oddities are shown in red ink, in the above figure.</p> |
| </li> |
| <li> |
| <p>in the above figure:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>"AST (proxy)" means the AST consists of only a single node of type <code>Script</code> and that is a proxy,</p> |
| </li> |
| <li> |
| <p>"AST (lazy)" means the AST is completely created, but cross-references are represented by unresolved |
| Xtext lazy-linking proxies,</p> |
| </li> |
| <li> |
| <p>"TModule (stubs)" means the TModule has been created with incomplete information, e.g. return types of |
| all TMethods/TFunctions will be <code>null</code> (only used internally by the incremental builder),</p> |
| </li> |
| <li> |
| <p>"TModule (some deferred)" means the TModule has been created, does not contain stub, but some |
| `TypeRef`s are `DeferredTypeRef`s that are supposed to be replaced by proper `TypeRef`s during post-processing.</p> |
| </li> |
| <li> |
| <p>"AST" and "TModule" means the AST/TModule is available without any qualifications.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>state <strong>Created'</strong>: only required because Xtext does not clear flag <code>fullyInitialized</code> upon unload; that is done lazily |
| when <code>#load()</code> is invoked at a later time.. Thus, we do not reach state <strong>Created</strong> when unloading from state |
| <strong>Fully Initialized</strong> but instead get to state <strong>Created'</strong>. To reach state <strong>Created</strong> from <strong>Fully Initialized</strong> we have to |
| explicitly invoke <code>#discardDerivedState()</code> before(!) unloading.</p> |
| </li> |
| <li> |
| <p>state <strong>Loaded from Description'</strong>: transition <code>#unloadAST()</code> from state <strong>Fully Initialized</strong> leaks a non-post-processed |
| TModule into state <strong>Loaded from Description</strong>, which is inconsistent with actually loading a TModule from the index, |
| because those are always fully processed. Hence, the addition of state <strong>Loaded from Description'</strong>.</p> |
| </li> |
| <li> |
| <p>states <strong>Fully Initialized ®</strong> and <strong>Fully Processed ®</strong>: these states are reached via reconciliation of a pre-existing |
| TModule with a newly loaded AST. These states differ in an unspecified way from their corresponding non-reconciled |
| states. For example, in state <strong>Fully Initialized ®</strong> the TModule does not contain any DeferredTypeRefs while, at the |
| same time, the TModule isn’t fully processed, because proxy resolution, typing, etc. have not taken place, yet.</p> |
| </li> |
| <li> |
| <p>TODO old text (clarify this; I could not reproduce this behavior): when <code>unloadAST</code> is called, <code>fullyInitialized</code> remains |
| unchanged. This is why the value of <code>fullyInitialized</code> should be indeterminate in row <strong>Loaded from Description</strong>; it |
| depends on the previous value if the state <strong>Loaded from Description</strong> was reached by calling <code>unloadAST</code>.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:Type_Builder"><a class="anchor" href="#sec:Type_Builder"></a><a class="link" href="#sec:Type_Builder">7.4. Types Builder</a></h3> |
| <div class="paragraph"> |
| <p>When a resource is loaded, it is parsed, linked, post-processed, validated and eventually compiled. For linking and validation |
| type information is needed, and as described above the type information is created automatically when loading a resource using |
| the types builder. <a href="#fig:ad_resourceLoading">Resource Loading</a> shows an activity model with the different actions performed when |
| a resource is loaded.</p> |
| </div> |
| <div id="fig:ad_resourceLoading" class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/ad_resourceLoading.png" alt="ad resourceLoading"> |
| </div> |
| <div class="title">Figure 15. Activity Diagram, Resource Loading</div> |
| </div> |
| <div class="paragraph"> |
| <p>The blue colored steps are standard Xtext workflow. Handling the TModule and storing that in the index are N4 specific (red background).</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Type_Inference_not_allowed_in_Type_Builder"><a class="anchor" href="#sec:Type_Inference_not_allowed_in_Type_Builder"></a><a class="link" href="#sec:Type_Inference_not_allowed_in_Type_Builder">7.4.1. Type Inference not allowed in Types Builder</a></h4> |
| <div class="paragraph"> |
| <p>A crucial point in the workflow described above is the combination of types model building and type inference. In some cases, |
| the type of a given element is not directly stated in the AST but has to be inferred from an expression and other types. For |
| example, when a variable declaration does not declare the variable’s type explicitly but provides an initializer expression, |
| the actual type of the variable is inferred to be the type of the expression.</p> |
| </div> |
| <div class="paragraph"> |
| <p>However, the types builder cannot be allowed to use type inference, mainly for two reasons:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>type inference through Xsemantics could lead to resolution of cross-references (i.e. EMF proxies generated by the lazy |
| linker) and because the types builder is triggered when getContents() is called on the containing <code>N4JSResource</code> this would |
| break a basic contract of EMF resources.</p> |
| </li> |
| <li> |
| <p>type inference could cause other resources to be loaded which would lead to problems (infinite loops or strange results) |
| in case of circular dependencies. This is illustrated in <a href="#fig:sd_typesBuilder_problem">Types Builder Problem</a> and |
| <a href="#fig:sd_typesBuilder_proxies">Types Builder Proxies</a>.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Therefore, whenever the type of a particular element has to be inferred, the types builder will use a special type reference |
| called <code>DeferredTypeRef</code> <sup class="footnote">[<a id="_footnoteref_3" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_3" title="View footnote.">3</a>]</sup>, |
| in order to defer the actual type inference to a later stage, i.e. the post-processing stage.</p> |
| </div> |
| <div id="fig:sd_typesBuilder_problem" class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/sd_typesBuilder_problem.png" alt="sd typesBuilder problem"> |
| </div> |
| <div class="title">Figure 16. Sequence Diagram, Types Builder Problem</div> |
| </div> |
| <div id="fig:sd_typesBuilder_proxies" class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/sd_typesBuilder_proxies.png" alt="sd typesBuilder proxies"> |
| </div> |
| <div class="title">Figure 17. Sequence Diagram, Types Builder with Proxies</div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:ComputedTypeReferences"><a class="anchor" href="#sec:ComputedTypeReferences"></a><a class="link" href="#sec:ComputedTypeReferences">7.4.2. Deferred Type References</a></h4> |
| <div class="paragraph"> |
| <p>Whenever type inference would be required to obtain the actual type of an element, the types builder will insert a stub to defer |
| actual type inference (see previous section). A dedicated subclass of <code>TypeRef</code>, called <code>DeferredTypeRef</code>, is used that contains neither |
| the actual type information nor any information necessary to perform the type inference at a later point in time. Later, this |
| <code>DeferredTypeRef</code> will be replaced during post-processing, see <code>TypeDeferredProcessor</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All <code>DeferredTypeRef</code>s will be replaced by the actual types during post-processing. One important reason for resolving |
| all <code>DeferredTypeRef</code>s as early as possible is that they are not suited for serialization and therefore have to be removed |
| from the types model before populating the Xtext index, which includes serializing the TModule into the user data of the |
| root element. This is always assured by the logic that manages the triggering of the post-processing phase.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To manually trigger resolution of all <code>DeferredTypeRef</code>s in a given types model, simply call method <code>performPostProcessing(CancelIndicator)</code> |
| of the containing <code>N4JSResource</code> (should never be required by client code such as validations).</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Use_cases_of_ComputedTypeRef"><a class="anchor" href="#sec:Use_cases_of_ComputedTypeRef"></a><a class="link" href="#sec:Use_cases_of_ComputedTypeRef">7.4.3. Use cases of DeferredTypeRef</a></h4> |
| <div class="paragraph"> |
| <p>Currently, <code>DeferredTypeRef</code>s are created by the types builder only in these cases:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>actual type of an exported TVariable if no declared type but an initialization expression are given.</p> |
| </li> |
| <li> |
| <p>actual type of a TField if no declared type but an initialization expression are given.</p> |
| </li> |
| <li> |
| <p>actual type of properties of ObjectLiterals if not declared explicitly.</p> |
| </li> |
| <li> |
| <p>actual type of formal parameters and return value of function expressions if not declared explicitly.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Note that this overview might easily get out-dated; see references to class <code>DeferredTypeRef</code> in the code.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:Incremental_Builder_Overview"><a class="anchor" href="#sec:Incremental_Builder_Overview"></a><a class="link" href="#sec:Incremental_Builder_Overview">7.5. Incremental Builder (Overview)</a></h3> |
| <div class="paragraph"> |
| <p>This section provides a brief overview of how the incremental builder works.</p> |
| </div> |
| <div class="paragraph"> |
| <p>General remarks:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The N4JS incremental builder is a combination of Eclipse builder infrastructure, Xtext-specific builder functionality and |
| several adjustments for N4JS and N4MF.</p> |
| </li> |
| <li> |
| <p>The <code>IBuilderState</code> implementation is identical to the persisted Xtext index. No matter how many Xtext languages are supported |
| by the application, only a single <code>IBuilderState</code> instance is available in the application. Since we have one single <code>IBuilderState</code>, |
| we have one single persisted Xtext index throughout the application.</p> |
| </li> |
| <li> |
| <p>For simplicity, the below description assumes we have only N4JS projects in the workspace and no other Xtext languages are |
| installed.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Major components:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>XtextBuilder</code> (inherits from Eclipse’s <code>IncrementalProjectBuilder</code>):</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>the actual incremental builder</p> |
| </li> |
| <li> |
| <p>note: Eclipse will create one instance of <code>XtextBuilder</code> per project at startup.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><code>IBuilderState</code> (Xtext specific; no Eclipse pendant):<br> |
| identical to the <code>Xtext index</code>, i.e. the globally shared, persisted instance of<br> |
| <code>IResourceDescriptions</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Main workflow:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>for each project that contains at least one resource that requires rebuilding, Eclipse will call the |
| project’s <code>XtextBuilder</code>.</p> |
| </li> |
| <li> |
| <p>each <code>XtextBuilder</code> will perform some preparations and will then delegate to <code>IBuilderState</code> which will iterate over |
| all resources in the builder’s project that require rebuilding.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Incremental_Builder_Overview__XtextBuilder"><a class="anchor" href="#sec:Incremental_Builder_Overview__XtextBuilder"></a><a class="link" href="#sec:Incremental_Builder_Overview__XtextBuilder">7.5.1. XtextBuilder</a></h4> |
| <div class="paragraph"> |
| <p>Whenever a change in the workspace happens …​</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p><a id="itm:start"></a> Eclipse will collect all projects that contain changed resources and compute a project-level build |
| order (using the <code>build order</code> of the workspace, see <code>Workspace#getBuildOrder()</code>, which is based on project dependencies)</p> |
| </li> |
| <li> |
| <p>for the first <sup class="footnote">[<a id="_footnoteref_4" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_4" title="View footnote.">4</a>]</sup> project with changed resources, Eclipse will invoke |
| method <code>IncrementalProjectBuilder#build(int,Map,IProgressMonitor)</code> of the project’s <code>XtextBuilder</code><br> |
| (NOTE: from this point on, we are in the context of a <code>current project</code>)</p> |
| </li> |
| <li> |
| <p>in <code>XtextBuilder#build(int,Map,IProgressMonitor)</code>:<br> |
| the builder creates an empty instance of <code>ToBeBuilt</code> (Xtext specific)</p> |
| </li> |
| <li> |
| <p>in <code>XtextBuilder#incrementalBuild(IResourceDelta,IProgressMonitor)</code>:</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>The builder will iterate over all files in the project and for each will notify a <code>ToBeBuiltComputer</code> about the |
| change (added, updated, or deleted) which can then decide how to update the <code>ToBeBuilt</code> instance,</p> |
| </li> |
| <li> |
| <p>then forwards to <code>#doBuild()</code> .</p> |
| <div class="paragraph"> |
| <p>Note: if user changes 1..* files in a single project but later more files in other, dependant projects |
| need to be built, the above step will happen for all projects, but will have an effect only for the first project that contains the actual file changes (i.e. in the standard case of saving a single file <code>ToBeBuilt</code> will always be non-empty for the <code>first</code> project, and always empty for the other, dependant projects; if a <code>Save All</code> is done, <code>ToBeBuilt</code> could be non-empty for later projects as well).</p> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>in <code>XtextBuilder#doBuild(ToBeBuilt,IProgressMonitor,BuildType)</code>:</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>first check if <code>ToBeBuilt</code> is empty AND global build queue does not contain URIs for current project → then abort (nothing to do here)</p> |
| </li> |
| <li> |
| <p>creates instance of BuildData with:</p> |
| <div class="olist lowerroman"> |
| <ol class="lowerroman" type="i"> |
| <li> |
| <p>name of current project (as string)</p> |
| </li> |
| <li> |
| <p>newly created, fresh <code>ResourceSet</code></p> |
| </li> |
| <li> |
| <p>the <code>ToBeBuilt</code> (containing URIs of actually changed resources within current project, possibly filtered by <code>ToBeBuiltComputer</code>)</p> |
| </li> |
| <li> |
| <p>the <code>QueuedBuildData</code> (an injected singleton)</p> |
| </li> |
| <li> |
| <p>mode flag <code>indexingOnly</code> (only true during crash recovery)</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>invoke <code>IBuilderState</code> passing the <code>BuildData</code><br> |
| → updates itself (it is the global Xtext index) to reflect all changes in <code>current project</code>; validates and updates markers; runs transpiler (see below for details)</p> |
| </li> |
| <li> |
| <p>invoke all registered <code>IXtextBuilderParticipants</code> (Xtext specific) for the <code>current project</code></p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>this is where normally we would do validation and run the transpiler; however, for performance reasons (do not load resource again) we already do this in the <code>IBuilderState</code> (this is the idea of the <code>GenerateImmediatelyBuilderState</code>)</p> |
| </li> |
| <li> |
| <p>in our implementation, almost nothing is done here, except trivial stuff such as deleting files during clean build</p> |
| <div class="paragraph"> |
| <p>At this point: returning from all methods.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>back in <code>XtextBuilder#build(int,Map,IProgressMonitor)</code>:<br> |
| → return with an array of IProjects; in our case: we return all other N4JSProjects referenced in the package.json of the project</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>important: these are <strong>not</strong> the projects that will be processed next: we need to continue with projects that depend on the current project, not with projects the current project depends on!</p> |
| </li> |
| <li> |
| <p>Eclipse calls the returned projects <code>interestingProjects</code> and uses that as a hint for further processing; details not discussed here.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>continue with step <a href="#itm:start">one</a>:<br> |
| Eclipse will invoke <code>XtextBuilder#build(int,Map,IProgressMonitor)</code> again for all other projects that have a dependency to the <code>current project</code> of the previous iteration, plus all remaining projects with changed resources.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Incremental_Builder_Overview__IBuilderState"><a class="anchor" href="#sec:Incremental_Builder_Overview__IBuilderState"></a><a class="link" href="#sec:Incremental_Builder_Overview__IBuilderState">7.5.2. IBuilderState</a></h4> |
| <div class="paragraph"> |
| <p>Invoked: once for each project containing a changed resource and dependant projects.<br> |
| Input: one instance of <code>BuildData</code>, as created by <code>XtextBuilder</code>, containing:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>name of current project (as string)</p> |
| </li> |
| <li> |
| <p>newly created, fresh <code>ResourceSet</code></p> |
| </li> |
| <li> |
| <p>the <code>ToBeBuilt</code></p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>set of to-be-deleted URIs</p> |
| </li> |
| <li> |
| <p>set of to-be-updated URIs</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>the <code>QueuedBuildData</code>, an injected singleton maintaining the following values <sup class="footnote">[<a id="_footnoteref_5" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_5" title="View footnote.">5</a>]</sup>:</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>a queue of URIs per project (below called the <code>global queue</code>)<br> |
| (actually stored in <code>QueuedBuildData#projectNameToChangedResource</code>)</p> |
| </li> |
| <li> |
| <p>a collection of <code>all remaining URIs</code><br> |
| (derived value: queued URIs of all projects + queues URIs not associated to a project (does not happen in N4JS))</p> |
| </li> |
| <li> |
| <p>a collection of <code>pending deltas</code> (always empty in N4JS; probably only used for interaction with Java resources)</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>mode flag <code>indexingOnly</code> (only true during crash recovery)</p> |
| </li> |
| </ol> |
| </div> |
| <div class="sect4"> |
| <h5 id="copy-and-update-xtext-index"><a class="anchor" href="#copy-and-update-xtext-index"></a><a class="link" href="#copy-and-update-xtext-index">7.5.2.1. Copy and Update Xtext Index</a></h5> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>in <code>IBuilderState#update(BuildData,IProgressMonitor)</code>:<br> |
| creates a copy of its <code>ResourceDescriptionsData</code> called <code>newData</code> <sup class="footnote">[<a id="_footnoteref_6" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_6" title="View footnote.">6</a>]</sup></p> |
| </li> |
| <li> |
| <p>in <code>AbstractBuilderState#doUpdate(…​)</code>:<br> |
| updates <code>newData</code> by writing new resource descriptions into it.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Creates a new load operation (<code>LoadOperation</code>) instance from the <code>BuildData#getToBeUpdated()</code> and loads all entries. While iterating and loading the resource descriptions, it updates <code>newData</code> by registering new resource descriptions that are being created on the fly from the most recent version of the corresponding resources.</p> |
| </li> |
| <li> |
| <p>Adds these resources to the current project’s build queue. (<code>BuildData#queueURI(URI uri)</code>)</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>for all to-be-deleted URIs given in <code>ToBeBuilt</code> in the <code>BuildData</code>, removes the corresponding <code>IResourceDescription</code> from <code>newData</code></p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>ToBeBuilt#getAndRemoveToBeDeleted()</code> returns all URIs that have been marked for deletion but not marked for update and will clear the set of to-be-deleted URIs in <code>ToBeBuilt</code>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="build-state-setup-phase"><a class="anchor" href="#build-state-setup-phase"></a><a class="link" href="#build-state-setup-phase">7.5.2.2. Build State Setup Phase</a></h5> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Calculates a set <code>allRemainingURIs</code> <sup class="footnote">[<a id="_footnoteref_7" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_7" title="View footnote.">7</a>]</sup> as follows:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Initially contains all resource URIs from <code>newData</code>.</p> |
| </li> |
| <li> |
| <p>All URIs will be removed from it that are marked for update (<code>BuildData#getToBeUpdated()</code>).</p> |
| </li> |
| <li> |
| <p>Finally, all URIs will be removed from it that are already queued for build/rebuild. (<code>BuildData#getAllRemainingURIs()</code>).</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Creates an empty set <code>allDeltas</code> of resource description deltas<br> |
| (c.f. <code>IResourceDescription.Delta</code>). <sup class="footnote">[<a id="_footnoteref_8" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_8" title="View footnote.">8</a>]</sup></p> |
| </li> |
| <li> |
| <p><a id="itm:processDeleted"></a> <strong>Process Deleted:</strong> for all to-be-deleted URIs, creates a delta where the old state is the current state of the resource and the new state is <code>null</code> and adds it to <code>allDeltas</code>.</p> |
| </li> |
| <li> |
| <p>Adds all <code>pending deltas</code> from <code>QueuedBuildData</code> to <code>allDeltas</code> (does not apply to N4JS).</p> |
| </li> |
| <li> |
| <p><strong><a id="itm:enqueueAffectedResources"></a>Enqueue affected resources, part 1:</strong> adds to the <code>global queue</code> the URIs of all resources affected by the changes in <code>allDeltas</code>.</p> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title=""></i> |
| </td> |
| <td class="content"> |
| For N4JS, <code>allDeltas</code> always seems to be empty at this point, so this does nothing at all. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p>Creates an empty set <code>changedDeltas</code> for storing deltas that were modified by the build phase and represent an actual change. Unlike <code>allDeltas</code>, this set contains only those URIs that were processed by the builder - the underlying user data information contains the differences between the old and the new state.</p> |
| </li> |
| <li> |
| <p>Creates a new <code>current queue</code> and adds all URIs from the <code>global queue</code> that belong to the <code>current project</code>.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="process-queued-uris"><a class="anchor" href="#process-queued-uris"></a><a class="link" href="#process-queued-uris">7.5.2.3. Process Queued URIs</a></h5> |
| <div class="paragraph"> |
| <p>Processes all elements from the queue until it contains no more elements.</p> |
| </div> |
| <div id="itm:loadRes" class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Load the resource for the first/next URI on the current queue</p> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title=""></i> |
| </td> |
| <td class="content"> |
| In case of a move, the loaded resource could have a different URI! |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p>Once the resource has been loaded, it removes its URI from the current queue to ensure it will not be processed again.</p> |
| </li> |
| <li> |
| <p>If the loaded resource is already marked for deletion, stop processing this resource and continue with next URI from the current queue (go to step <a href="#itm:loadRes">Load Res</a>) |
| <sup class="footnote">[<a id="_footnoteref_9" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_9" title="View footnote.">9</a>]</sup></p> |
| </li> |
| <li> |
| <p>Resolves all lazy cross references in the loaded resource. This will trigger post-processing, including all type inference (c.f. <code>ASTProcessor#processAST(…​)</code>).</p> |
| </li> |
| <li> |
| <p>Creates a delta for the loaded resource, including</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>a resource description based on the new state of the resource, wrapped into the <code>EObject</code>-based resource description (as with the Xtext index persistence in <code>EMFBasedPersister#saveToResource()</code>).</p> |
| </li> |
| <li> |
| <p>a resource description for the same resource with the state before the build process.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>Adds this new delta to <code>allDeltas</code> and, if the delta represents a change (according to <code>DefaultResourceDescriptionDelta#internalHasChanges()</code>), also adds it to <code>changedDeltas</code>.</p> |
| </li> |
| <li> |
| <p>Adds the resource description representing the new state, stored in the delta, to <code>newData</code>, i.e. the copied <code>ResourceDescriptionsData</code>, replacing the old resource description of the loaded resource <sup class="footnote">[<a id="_footnoteref_10" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_10" title="View footnote.">10</a>]</sup>.</p> |
| </li> |
| <li> |
| <p>If the current queue is non-empty, go to step <a href="#itm:loadRes">Load Res</a> and continue with the next URI in the current queue.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="queueing-affected-resources"><a class="anchor" href="#queueing-affected-resources"></a><a class="link" href="#queueing-affected-resources">7.5.2.4. Queueing Affected Resources</a></h5> |
| <div class="paragraph"> |
| <p>When the current queue contains no more URIs (all have been processed) …​</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p><a id="itm:updateGlobalQueue"></a> <strong>Enqueue affected resources, part 2:</strong> add to the global queue URIs for all resources affected by the changes in <code>changedDeltas</code> <sup class="footnote">[<a id="_footnoteref_11" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_11" title="View footnote.">11</a>]</sup>.</p> |
| </li> |
| <li> |
| <p>Returns from <code>#doUpdate()</code>, returning <code>allDeltas</code> (only used for event notification).</p> |
| </li> |
| <li> |
| <p>back in <code>IBuilderState#update(BuildData,IProgressMonitor)</code>:<br> |
| makes the <code>newData</code> the publicly visible, persistent state of the IBuilderState (i.e. the <code>official</code> Xtext index all other code will see).</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>We now provide some more details on how the global queue is being updated, i.e. steps <a href="#itm:enqueueAffectedResources">Enqueue Affected Resources</a> and <a href="#itm:updateGlobalQueue">Update Global Queue</a>. |
| Due to the language specific customizations for N4JS, this second resource-enqueuing phase is the trickiest part of the incremental building process and has the largest impact on how other resources will be processed and enqueued at forthcoming builder state phases.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If <code>allDeltas</code> is empty, nothing to do.</p> |
| </li> |
| <li> |
| <p>If <code>allDeltas</code> contains at least one element, we have to check other affected resources by going through the set of all resource URIs (<code>allRemainingURIs</code>) calculated in in the beginning of the build process.</p> |
| </li> |
| <li> |
| <p>Assume we have at least one element in the <code>allDeltas</code> set, the latter case is true and we must check all elements whether they are affected or not. We simply iterate through the <code>allRemainingURIs</code> set and retrieve the old state of the resource description using the resource URI.</p> |
| </li> |
| <li> |
| <p>Once the resource description with the old state is retrieved, we check if it is affected through the corresponding resource description manager. Since we currently support two languages, we have two different ways for checking whether a resource has changed or not. One for package.json files and the other for the N4JS language related resources.</p> |
| </li> |
| <li> |
| <p>The package.json method is the following: get all project IDs referenced from the <code>candidate</code> package.json and compare it with the container-project name of the package.json files from the <code>deltas</code>. The referenced IDs are the followings:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>tested project IDs,</p> |
| </li> |
| <li> |
| <p>implemented project IDs,</p> |
| </li> |
| <li> |
| <p>dependency project IDs,</p> |
| </li> |
| <li> |
| <p>provided runtime library IDs,</p> |
| </li> |
| <li> |
| <p>required runtime library IDs and</p> |
| </li> |
| <li> |
| <p>extended runtime environment ID.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>The N4JS method is the following:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>We consider only those changed deltas which represent an actual change (<code>IResourceDescription.Delta#haveEObjectDescriptionsChanged()</code>) and have a valid file extension (<code>.n4js</code>, <code>.n4jsd</code> or <code>.js</code>).</p> |
| </li> |
| <li> |
| <p>For each <code>candidate</code>, we calculate the imported FQNs. The imported FQNs includes indirectly imported names besides the directly imported ones. Indirectly imported FQNs are, for instance, the FQNs of all transitively extended super class names of a direct reference.</p> |
| </li> |
| <li> |
| <p>We state that a <code>candidate</code> is affected if there is a dependency (for example name imported by a <code>candidate</code>) to any name exported by the description from a delta. That is, it computes if a candidate (with given <code>importedNames</code>) is affected by a change represented by the description from the delta.</p> |
| </li> |
| <li> |
| <p>If a <code>candidate</code> is affected we have to do an additional dependency check due to the lack of distinct unique FQNs. If a project containing the delta equals with the project contained by the candidate, or if the project containing the candidate has a direct dependency to the project containing the delta, we mark a candidate as affected.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>If a candidate was marked as affected, it will be removed from the <code>allRemainingURIs</code> and will be added to the build queue.</p> |
| </li> |
| <li> |
| <p>If a candidate has been removed from the <code>allRemainingURIs</code> and queued for the build, we assume its <code>TModule</code> information stored in the user data is obsolete. To invalidate the obsolete information, we wrap the delta in the custom resource description delta so whenever the <code>TModule</code> information is asked for, it will be missing. We then register this wrapped delta into the copied Xtext index, end the builder state for the actual project then invoke the Xtext builder with the next dependent project.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Incremental_Builder_Overview__Example"><a class="anchor" href="#sec:Incremental_Builder_Overview__Example"></a><a class="link" href="#sec:Incremental_Builder_Overview__Example">7.5.3. Example</a></h4> |
| <div class="paragraph"> |
| <p>To conclude this section, we briefly describe the state of the above five phases through a simple example. Assume a |
| workspace with four N4JS projects: <em>P1</em>, <em>P2</em>, <em>P3</em> and <em>PX</em>. Each project has one single module with one single |
| publicly visible class. Also let’s assume project <em>P2</em> depends on <em>P1</em> and <em>P3</em> depends on <em>P2</em>. Project <em>PX</em> have |
| no dependencies to other projects. Project <em>P1</em> has a module <em>A.n4js</em> with a class <code>A</code>, project <em>P2</em> has one single |
| module <em>B.n4js</em>. This module has a public exported class <code>B</code> which extends class <code>A</code>. Furthermore, project <em>P3</em> has |
| one single module: <em>C.n4js</em>. This module contains one exported public class <code>C</code> which extends <code>B</code>. Finally, project |
| <em>PX</em> has a module <em>X.n4js</em> containing a class <code>X</code> that has no dependencies to any other classes. The figure below |
| picture depicts the dependencies between the projects, the modules and the classes as described above.</p> |
| </div> |
| <div class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/builderStateExample.png" alt="builderStateExample"> |
| </div> |
| <div class="title">Figure 18. Builder State Example</div> |
| </div> |
| <div class="paragraph"> |
| <p>For the sake of simplification, the table below describes a symbol table for all resources:</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 3. Resource Symbol Table</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">P1/src/A.n4js</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">P2/src/B.n4js</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">B</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">P3/src/C.n4js</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">C</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">PX/src/X.n4js</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Let assume auto-build is enabled and the workspace contains no errors and/or warnings. We make one simple modification |
| and expect one single validation error in class <code>C</code> after the incremental builder finished its processing; we delete the |
| method <code>foo()</code> from class <code>A</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After deleting the method in the editor and saving the editor content, a workspace modification operation will run and |
| that will trigger an auto-build job. The auto-build job will try to build the container project <em>P1</em> of module <em>A</em>. Since |
| the project is configured with the Xtext builder command, a builder state update will be performed through the Xtext builder. |
| Initially, due to an Eclipse resource change event (we literally modify the resource from the editor and save it), the |
| <code>ToBeBuilt</code> instance wrapped into the <code>BuildData</code> will contain the URI of the module <em>A</em> marked for an update. When updating |
| the copied index content, module <em>A</em> will be queued for a build. While processing the queued elements for project <em>P1</em>, |
| module <em>A</em> will be processed and will be added to the <code>allDeltas</code> set. Besides that, it will be added to the <code>changedDeltas</code> |
| set as well. That is correct, because its <code>TModule</code> information has been changed after deleting the public <code>foo()</code> method. |
| When queuing affected resources, iterating through the set of <code>allRemainingURIs</code>, we recognize that module <em>B</em> is affected. |
| That is indeed true; module <em>B</em> imports the qualified name of class <code>A</code> from module <em>A</em> and project <em>P2</em> has a direct |
| dependency to <em>P1</em>. In this builder state phase, when building project <em>P1</em>, module <em>C</em> is not considered as affected. |
| Although class <code>C</code> from module <em>C</em> also imports the qualified name of class <code>A</code> from module <em>A</em>, project <em>P3</em> does not |
| have a direct dependency to project <em>P1</em>. When module <em>B</em> becomes enqueued for a forthcoming build phase, we assume its |
| <code>TModule</code> information is obsolete. We invalidate this <code>TModule</code> related user data information on the resource description |
| by wrapping the resource description into a custom implementation (<code>ResourceDescriptionWithoutModuleUserData</code>). Due to this |
| wrapping the resource description for module <em>B</em> will be marked as changed (<code>IResourceDescription.Delta#haveEObjectDescriptionsChanged()</code>) |
| whenever the old and current states are being compared.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse builder will recognize (via <code>IProjectDescription#getDynamicReferences()</code>) that project <em>P2</em> depends on project <em>P1</em> |
| so the Xtext builder will run for project <em>P2</em> as well. At the previous phase we have enqueued module <em>B</em> for the build. |
| We will therefore run into a builder state update again. We do not have any resource changes this time, so <code>ToBeBuilt</code> will |
| be empty. Since <code>ToBeBuilt</code> is empty, we do not have to update the copied Xtext index state before the builder state setup |
| phase. As the result of the previous builder state, phase module <em>B</em> is already enqueued for a build. When processing <em>B</em> |
| we register it into the <code>allDeltas</code> set. That happens for each resource being processed by the builder state. But it will be |
| registered into the <code>changedDeltas</code> because we have previously wrapped module <em>B</em> into a customized resource description delta |
| to hide its obsolete <code>TModule</code> related user data information. Based on the builder state rules and logic described above, |
| module <em>C</em> will be marked as an affected resource, will be queued for build and will be wrapped into a customized resource |
| description delta to hide its <code>TModule</code> related user data information.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the next builder state phase, when building project <em>P3</em>, we apply the same logic as we applied for project <em>P2</em>. The |
| builder state will process module <em>C</em> and will update the Xtext index state. No additional resources will be found as |
| affected ones, nothing will be queued for build. The build will terminate, since there were no changed <code>IResource</code> instances |
| and the build queue is empty.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The outcome of the incremental build will be a workspace that contains exactly one validation error. The error will be |
| associated with module <em>C</em> which was exactly our expectation, however, we have to clarify that transitive <em>C</em> dependency |
| was built due to wrong reasons. Module <em>C</em> was build because we wrapped module <em>B</em> to hide its user data information and |
| not because it imports and uses class <code>A</code> from module <em>A</em> which should be the logical and correct reason.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="dirty-state-handling"><a class="anchor" href="#dirty-state-handling"></a><a class="link" href="#dirty-state-handling">7.6. Dirty state handling</a></h3> |
| <div class="paragraph"> |
| <p>When two or more (N4)JS files are opened in editors and one of them is changed but without persisting this change the other |
| open editors should be notified and if this change breaks (or heals) references in one of the other open resources their editors |
| should updated so that warn and error markers are removed or added accordingly.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When there are changes in the currently open editor these changes are propagated to all other open editors. Each Xtext editor has |
| got its own resource set. The <code>N4JSUpdateEditorStateJob</code> runs for each open editor different from the editor where the changes have |
| been made. In those editors the affected resources are unloaded and removed from the resource set. Then the Xtext resource of |
| these editors is reparsed. After reparsing scoping and linking is invoked again, but now the references resources are rebuild |
| as <code>EObjectDescription</code>s. The <code>N4JSResource</code> holds its own content that only contains 1..n slots when proxified. |
| <code>N4JSTypeScope.getSingleElement</code> (called when resolving cross references and the linked element should be returned) will return the |
| <code>EObjectDescription</code> created from the <code>ModuleAwareContentsList</code> in <code>N4JSResource</code>, that contains the first slot as proxy and the other |
| slots as types. <a href="#fig:dirty_state_handling1">Sequence Diagram: Dirty State, Trigger <code>N4JSUpdateEditorStateJob</code></a> shows the flow to trigger the <code>N4JSUpdateEditorStateJob</code> and <a href="#fig:dirty_state_handling2">Sequence Diagram: Dirty State, <code>N4JSUpdateEditorStateJob</code> in Detail</a> |
| shows the sequence logic of the <code>N4JSUpdateEditorStateJob</code> in detail.</p> |
| </div> |
| <div id="fig:dirty_state_handling1" class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/dirty_state_handling1.png" alt="dirty state handling1"> |
| </div> |
| <div class="title">Figure 19. Sequence Diagram: Dirty State, Trigger <code>N4JSUpdateEditorStateJob</code></div> |
| </div> |
| <div id="fig:dirty_state_handling2" class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/dirty_state_handling2.png" alt="dirty state handling2"> |
| </div> |
| <div class="title">Figure 20. Sequence Diagram: Dirty State, <code>N4JSUpdateEditorStateJob</code> in Detail</div> |
| </div> |
| <div class="paragraph"> |
| <p>A concrete example should illustrate the behaviour of the dirty state handling in conjunction with fully and partial loading |
| of resources:</p> |
| </div> |
| <div class="paragraph"> |
| <p>Let A.js as above, and B.js as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">import A from "A.js" |
| export class B {}</code></pre> |
| </div> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>assume is opened and loaded: is created with</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>is filled with a special proxy to resolve the <a href="appendix_d_acronyms.html#AC">AST</a> of A only if needed.</p> |
| </li> |
| <li> |
| <p>will be set to type A, loaded from <code>EObjectDescription</code> of A.js/A</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><a href="appendix_d_acronyms.html#AC">AST</a> of A.js is to be accessed, e.g., for displaying JSDoc. A.js is not opened in an editor! is modified as follows:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>is filled with <a href="appendix_d_acronyms.html#AC">AST</a>, i.e. proxy in 0 is resolved</p> |
| </li> |
| <li> |
| <p>is updated with parsed type: 1) proxify , 2) unload (remove from content), 3) reload with parsed types again</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Assume now that A.js is opened and edited by the user.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Reconceiler replaces with modified <a href="appendix_d_acronyms.html#AC">AST</a></p> |
| </li> |
| <li> |
| <p>LazyLinker updates </p> |
| </li> |
| <li> |
| <p>is proxified</p> |
| </li> |
| <li> |
| <p>B <code>searches</code> for A and finds updated </p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p><em>Each opened Xtext editor has got its own resource set!</em> Such a resource set contains the resource for the currently edited |
| file in the first place. When starting editing the file, the resource is reparsed , reloaded and linking (resolving the cross |
| references) is done. By resolving the cross references <code>N4JSTypeScope</code> is used and now the URIs of the linked elements are belonging |
| to resources not contained in the resource set of the editor so these resources a create in the resource set and their contents |
| is loaded from the resource descriptions via |
| <code>N4JSResource.loadFromDescription</code> .</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the resource content is loaded from the existing resource description available from Xtext index the first slot is set to be |
| a proxy with name <code>#:astProxy</code>. |
| After that for all exported EObject descriptions of that resource description the user data is fetched and deserialized to types |
| and these types are added to the slots of the resource in order they were exported. But the order is not that important anymore.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As the resource set for the editor is configured to use the DirtyStateManager ( <code>ExternalContentSupport.configureResourceSet(resourceSet, dirtyStateManager)</code> ), |
| all other open editors will be notified by changes in the current editor. This is done by <code>N4JSDirtyStateEditorSupport</code> that schedules |
| a <code>N4JSUpdateEditorStateJob</code> that create a new resource description change event.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Via <code>isAffected</code> and <code>ResourceDescription.getImportedNames</code> it is determine if a change in another resource affects this resource.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Before loading the resource always <code>N4JSDerivedStateComputer.installDerivedState</code> is execute that, as we learned earlier, is responsible |
| for creating the types in the resource.</p> |
| </div> |
| <div class="paragraph"> |
| <p>On every change to a N4JS file that requires a reparse the <code>N4JSDerivedStateComputer.discardDerivedState</code> is executed. This method do an |
| unload on every root element at the positions 1 to n. In the <code>N4JSUnloader</code> all contents of the this root elements are proxified (i.e. |
| there is a proxy URI set to each of them) and the references to the <a href="appendix_d_acronyms.html#AC">AST</a> are set to null (to avoid notifications causing |
| concurrent model changes). The proxification indicates for all callers of these elements, that they have to reload them. Afterwards |
| it discards the complete content of the resource. The content is build up again with the reparse of the N4JS file content.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As each editor has its own resource set, only the resource belonging to the current editor is fully loaded. All other referenced |
| resources are only partially loaded, i.e. only the slot 1 of these resources are loaded (i.e. the types model elements) in this |
| resource set. Linking is done only against these types model elements. Synchronization between the resource sets of multiple open |
| editors is done via update job as described above.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-case-restoring-types-from-user-data"><a class="anchor" href="#use-case-restoring-types-from-user-data"></a><a class="link" href="#use-case-restoring-types-from-user-data">7.6.1. Use case: Restoring types from user data</a></h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Use case: referencing resources in editor: This has been described already in context of dirty state handling</p> |
| </li> |
| <li> |
| <p>Use case: referencing resources from JAR: This is still to be implemented.% taskIDE-37</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-case-updating-the-xtext-index"><a class="anchor" href="#use-case-updating-the-xtext-index"></a><a class="link" href="#use-case-updating-the-xtext-index">7.6.2. Use case: Updating the Xtext index</a></h4> |
| <div class="paragraph"> |
| <p>When a N4JS file is changed in way that requires reparsing the file, the underlying resource is completely unloaded and loaded again. |
| By this the also the elements at the Xtext index are recreated again, belonging to this resource (i.e. new entries for new elements |
| in the resource, update index elements of changed elements, delete index entries for deleted elements).</p> |
| </div> |
| <div class="paragraph"> |
| <p>When Eclipse is closed the Xtext index is serialized in a file.</p> |
| </div> |
| <div class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/index_serialization.png" alt="index serialization"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When starting Eclipse again, the Xtext index is restored from this file:</p> |
| </div> |
| <div class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/07_typeindex/images/loading_existing_index.png" alt="loading existing index"> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div id="footer"> |
| <div id="footer-text"> |
| Version 0.9<br> |
| Last updated 2019-08-08 13:15:33 CEST |
| </div> |
| </div> |
| <!-- ************* docinfo-footer *************************************************************** --> |
| <div class="Grid social" style="color:#d5dfea"> |
| <div class="Cell Cell--2-12 m-Cell--withMargin"> |
| <h2>Quick Links</h2> |
| <ul> |
| <li><a href="../downloads.html">Download</a></li> |
| <li><a href="../userguides/index.html">Documentation</a></li> |
| <li><a href="https://github.com/eclipse/n4js/">Source</a></li> |
| <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li> |
| </ul> |
| </div> |
| <div class="Cell Cell--2-12 m-Cell--withMargin"> |
| <br/><br/> |
| <ul> |
| <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li> |
| <li><a href="http://n4js.blogspot.de/">Blog</a></li> |
| <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li> |
| <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li> |
| <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li> |
| </ul> |
| </div> |
| <div class="Cell Cell--2-12 m-Cell--withMargin"> |
| <br/><br/> |
| <ul> |
| <li><a href="http://www.eclipse.org/">Eclipse Home</a></li> |
| <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li> |
| <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li> |
| <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li> |
| <li><a href="http://www.eclipse.org/legal/">Legal</a></li> |
| </ul> |
| </div> |
| <div style="clear: both; height: 0; overflow: hidden;"></div> |
| </div> |
| |
| <!-- ************* UI Scripts ************* --> |
| <script type="text/javascript" src="scripts/back-to-top.js"></script> |
| |
| <script type="text/javascript" src="scripts/treeview.js"></script> |
| <script type="text/javascript" src="scripts/toc.js"></script> |
| |
| <!-- ************* Prism.js Syntax Highlighting ************* --> |
| <script src="scripts/prism.js"></script> |
| |
| <script type="text/javascript"> |
| // Add the 'toclist' id for search function |
| $(".toc2 > ul").attr('id', 'toclist'); |
| // Generate a Search input form |
| $("#toclist > li:first-of-type").before('<input type="text" id="pagesearch" onkeyup="search()" placeholder="Search for section...">'); |
| $("#toclist > li:first-of-type").before('<i id="clear" class="fa fa-times-circle-o"></i>'); |
| $("#clear").click(function(){ |
| $("#pagesearch").val(''); |
| search(); |
| $('.toc2 > ul').treeView('collapseAll'); |
| }); |
| // intialize Treeview.js |
| $(".toc2 > ul").treeView(); |
| // Initialize Scrollspy |
| </script> |
| <!-- ************* docinfo-footer *************************************************************** --> |
| </body> |
| </html> |
