| <!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 IDE 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 IDE 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="#sec:Views">1. Views</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_eclipse-standard-views">1.1. Eclipse Standard Views</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Project_Explorer_View">1.1.1. Project Explorer</a></li> |
| <li><a href="#sec:Outline_View">1.1.2. Outline</a></li> |
| <li><a href="#sec:Problems_View">1.1.3. Problems</a></li> |
| <li><a href="#sec:Console_View">1.1.4. Console</a></li> |
| <li><a href="#sec:History_View">1.1.5. History</a></li> |
| <li><a href="#sec:Error_Log_View">1.1.6. Error Log</a></li> |
| </ul> |
| </li> |
| <li><a href="#_n4js-specific-views">1.2. N4JS Specific Views</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_test-results">1.2.1. Test Results</a></li> |
| <li><a href="#_source-graphs">1.2.2. Source Graphs</a></li> |
| <li><a href="#_api-compare">1.2.3. API Compare</a></li> |
| <li><a href="#_performance-graphs">1.2.4. Performance Graphs</a></li> |
| <li><a href="#_source-mapping">1.2.5. Source Mapping</a></li> |
| <li><a href="#_xpect-view">1.2.6. Xpect View</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#_navigation">2. Navigation</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:Outline_Navigation">2.1. Outline</a> |
| <ul class="sectlevel3"> |
| <li><a href="#_quick-outline">2.1.1. Quick Outline</a></li> |
| <li><a href="#_normal-outline">2.1.2. Normal Outline</a></li> |
| </ul> |
| </li> |
| <li><a href="#_navigation-commands">2.2. Navigation Commands</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Navigate_to_Declaration">2.2.1. Navigate to Declaration</a></li> |
| <li><a href="#sec:find_by_references">2.2.2. Find by References</a></li> |
| <li><a href="#sec:Open_Type_Declaration">2.2.3. Open Type Declaration</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:Working_Sets">2.3. Working Sets</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Working_Set_Managers">2.3.1. Working Set Managers</a></li> |
| <li><a href="#sec:Working_Set_Constraints">2.3.2. Working Set Constraints</a></li> |
| <li><a href="#sec:Manual_Association_Working_Set_Manager_UI_Features">2.3.3. Manual Association Working Set Manager - UI Features</a></li> |
| <li><a href="#sec:Project_Name_Filter_Working_Set_Manager">2.3.4. Project Name Filter Working Set Manager</a></li> |
| <li><a href="#sec:Git_Repository_Working_Set_Manager">2.3.5. Git Repository Working Set Manager</a></li> |
| <li><a href="#sec:Project_Location_Working_Set_Manager">2.3.6. Project Location Working Set Manager</a></li> |
| <li><a href="#sec:N4JS_Project_Type_Working_Set_Manager">2.3.7. N4JS Project Type Working Set Manager</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#_assistance">3. Assistance</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:Content_Assist">3.1. Content Assist</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Complete_Keywords">3.1.1. Complete Keywords</a></li> |
| <li><a href="#sec:Complete_Annotations">3.1.2. Complete Annotations</a></li> |
| <li><a href="#sec:Complete_Identifier_Reference">3.1.3. Complete Identifier Reference</a></li> |
| <li><a href="#sec:Complete_Member_Overrides">3.1.4. Complete Member Overrides</a></li> |
| <li><a href="#sec:Constructor_Completion">3.1.5. Constructor Completion</a></li> |
| <li><a href="#sec:Complete_Function_Expression">3.1.6. Complete Function Expression with Known Type</a></li> |
| <li><a href="#sec:Complete_Variable_and_Parameter_Names">3.1.7. Complete Variable and Parameter Names</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:Quick_Fixes">3.2. Quick Fixes</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:N4JS_Issue_Properties">3.2.1. N4JS Issue User data</a></li> |
| <li><a href="#sec:N4JS_Issue_Fixes">3.2.2. N4JS Issue Fixes</a> |
| <ul class="sectlevel4"> |
| <li><a href="#sec:Linking_Issues">3.2.2.1. Linking Issues</a></li> |
| <li><a href="#sec:Import_Issues">3.2.2.2. Import Issues</a></li> |
| <li><a href="#sec:Visibility_Issues">3.2.2.3. Visibility Issues</a></li> |
| <li><a href="#sec:Classifier_Issues">3.2.2.4. Classifier Issues</a></li> |
| <li><a href="#sec:Function_Issues">3.2.2.5. Function Issues</a></li> |
| <li><a href="#sec:Syntax_Issues">3.2.2.6. Syntax Issues</a></li> |
| <li><a href="#sec:Conversion_Issues">3.2.2.7. Conversion Issues</a></li> |
| <li><a href="#sec:Type_Issues">3.2.2.8. Type Issues</a></li> |
| <li><a href="#sec:Expression_Issues">3.2.2.9. Expression Issues</a></li> |
| <li><a href="#sec:Super_Keyword_Issues">3.2.2.10. Super Keyword Issues</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#sec:Quick_Assist">3.3. Quick Assist</a></li> |
| <li><a href="#sec:Cleanup_Operations">3.4. Cleanup Operations</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Formatting">3.4.1. Formatting</a></li> |
| <li><a href="#sec:Organize_Imports">3.4.2. Organize Imports</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#_wizards">4. Wizards</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:N4JS_Project_Wizard">4.1. N4JS Project Wizard</a></li> |
| <li><a href="#sec:Empty_N4JS_File">4.2. Empty N4JS File</a></li> |
| <li><a href="#sec:Empty_JS_File">4.3. Empty JS File</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:N4JS_Class_File_Wizard">4.3.1. N4JS Class Wizard</a></li> |
| <li><a href="#field-properties">4.3.2. Field Properties</a></li> |
| <li><a href="#visibility-issues-or-final-super-classes">4.3.3. Visibility issues or <code>@Final</code> super classes</a></li> |
| <li><a href="#generation-1">4.3.4. Generation</a></li> |
| <li><a href="#preview-1">4.3.5. Preview</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:N4JS_Interface_Wizard">4.4. Interface Wizard</a> |
| <ul class="sectlevel3"> |
| <li><a href="#field-properties-1">4.4.1. Field Properties</a></li> |
| <li><a href="#visibility-issues">4.4.2. Visibility Issues</a></li> |
| <li><a href="#import-naming-conflicts">4.4.3. Import naming conflicts</a></li> |
| <li><a href="#generation-2">4.4.4. Generation</a></li> |
| <li><a href="#preview-2">4.4.5. Preview</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:N4JS_Enum_File_Wizard">4.5. Enum Wizard</a> |
| <ul class="sectlevel3"> |
| <li><a href="#field-properties-2">4.5.1. Field Properties</a></li> |
| <li><a href="#generation-3">4.5.2. Generation</a></li> |
| <li><a href="#preview-3">4.5.3. Preview</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#_execution-support">5. Execution Support</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:Non_UI_Execution">5.1. Non-UI Execution</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Non_UI_Debugging">5.1.1. Non-UI Debugging</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:UI_Execution">5.2. UI Execution</a></li> |
| </ul> |
| </li> |
| <li><a href="#_test-support">6. Test Support</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:N4JS_Mangelhaft_support">6.1. N4JS Mangelhaft support</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Asynchronous_Tests">6.1.1. Asynchronous Tests, Test Isolation and Timeouts</a></li> |
| <li><a href="#sec:Supported_xUnit_API">6.1.2. Supported xUnit API</a> |
| <ul class="sectlevel4"> |
| <li><a href="#sec:Test_Group">6.1.2.1. Test Group</a></li> |
| <li><a href="#sec:Test_Method">6.1.2.2. Test Method</a></li> |
| <li><a href="#sec:BeforeAll">6.1.2.3. BeforeAll Setup</a></li> |
| <li><a href="#sec:Before_Setup">6.1.2.4. Before Setup</a></li> |
| <li><a href="#sec:After_Teardown">6.1.2.5. After Teardown</a></li> |
| <li><a href="#sec:AfterAll_Teardown">6.1.2.6. AfterAll Teardown</a></li> |
| <li><a href="#sec:Test_Ignore">6.1.2.7. Test Ignore</a></li> |
| <li><a href="#sec:Timeout">6.1.2.8. Timeout</a></li> |
| <li><a href="#sec:Description">6.1.2.9. Description</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#sec:Test_Reporting">6.2. Test Reporting</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Test_Messages">6.2.1. Test Messages</a> |
| <ul class="sectlevel4"> |
| <li><a href="#_test-case-ids">6.2.1.1. Test Case IDs</a></li> |
| <li><a href="#sec:Start_Session">6.2.1.2. Start Session</a></li> |
| <li><a href="#sec:Ping_Session">6.2.1.3. Ping Session</a></li> |
| <li><a href="#sec:End_Session">6.2.1.4. End Session</a></li> |
| <li><a href="#sec:Start_Test">6.2.1.5. Start Test</a></li> |
| <li><a href="#sec:End_Test">6.2.1.6. End Test</a></li> |
| <li><a href="#sec:Ping_Test">6.2.1.7. Ping Test</a></li> |
| <li><a href="#sec:Test_Catalog">6.2.1.8. Test Catalog</a></li> |
| <li><a href="#sec:Test_Session_Example">6.2.1.9. Test Session Example</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:Test_Runtime_Configuration">6.2.2. Test Runtime Configuration</a></li> |
| <li><a href="#sec:Test_Plan">6.2.3. Test Plan</a></li> |
| <li><a href="#sec:Test_Environment_Configuration">6.2.4. Test Environment Configuration</a></li> |
| <li><a href="#sec:Test_Environment_Configuration_Example">6.2.5. Test Environment Configuration Example</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#_help-system">7. Help System</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:Built_In_Help">7.1. Built-In Help</a></li> |
| <li><a href="#sec:Context_Sensitive_Help">7.2. Context Sensitive Help</a></li> |
| <li><a href="#sec:Cheat_Sheets">7.3. Cheat Sheets</a></li> |
| <li><a href="#sec:JSDoc">7.4. JSDoc</a></li> |
| <li><a href="#sec:Hovering">7.5. Hovering</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Show_Type_Information_of_Selection">7.5.1. Show Type Information of Selection</a></li> |
| </ul> |
| </li> |
| <li><a href="#sec:Example_Projects_and_Files">7.6. Example Projects and Files</a></li> |
| </ul> |
| </li> |
| <li><a href="#_bug-management">8. Bug Management</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:Built_In_Xpect_Support">8.1. Built-In Xpect Support</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Report_View">8.1.1. Report View</a></li> |
| <li><a href="#sec:Generate_Bug_Report">8.1.2. Generate Bug Report</a></li> |
| <li><a href="#sec:Supported_Xpect_Tests">8.1.3. Supported Xpect Tests</a> |
| <ul class="sectlevel4"> |
| <li><a href="#sec:XPECT_N4JS_Errors">8.1.3.1. Errors, Warnings, Infos, Issues</a></li> |
| <li><a href="#sec:XPECT_N4JS_Noerrors">8.1.3.2. Noerrors</a></li> |
| <li><a href="#sec:XPECT_N4JS_Output">8.1.3.3. Output, OutputRegex</a></li> |
| <li><a href="#sec:XPECT_N4JS_Type_Of">8.1.3.4. Type Of</a></li> |
| <li><a href="#sec:XPECT_Advanced_Methods">8.1.3.5. Advanced methods</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#_cli">9. CLI</a> |
| <ul class="sectlevel2"> |
| <li><a href="#sec:Headless_Compiler">9.1. Headless Compiler</a></li> |
| <li><a href="#sec:Headless_Dependencies">9.2. Headless Dependnecies</a></li> |
| <li><a href="#sec:Headless_Execution">9.3. Headless Execution</a> |
| <ul class="sectlevel3"> |
| <li><a href="#sec:Cleaning_Headlessly">9.3.1. Cleaning Headlessly</a></li> |
| <li><a href="#sec:Running_Headlessly">9.3.2. Running Headlessly</a></li> |
| <li><a href="#sec:Information_about_running_headlessly">9.3.3. Information about running headlessly</a></li> |
| <li><a href="#sec:Testing_Headlessly">9.3.4. Testing Headlessly</a></li> |
| <li><a href="#sec:Information_about_testing_headlessly">9.3.5. Information about testing headlessly</a></li> |
| <li><a href="#_testresults">9.3.6. TestResults</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#sec:License">Appendix A: License</a></li> |
| <li><a href="#sec:Acronyms">Appendix B: Acronyms</a></li> |
| <li><a href="#_bibliography">Appendix C: Bibliography</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph center"> |
| <p><strong>Last Updated: 2019-08-08</strong></p> |
| </div> |
| <div class="paragraph center"> |
| <p><strong>Authors:</strong><br> |
| Jens von Pilgrim, Jakub Siberski, Mark-Oliver Reiser, Torsten Krämer, Ákos Kitta, Sebastian Zarnekow, Lorenzo Bettini, Jörg Reichert, Kristian Duske, Marcus Mews, Minh Quang Tran, Luca Beurer-Kellner</p> |
| </div> |
| <div style="page-break-after: always;"></div> |
| <h2 id="_abstract" class="discrete">Abstract</h2> |
| <div class="paragraph"> |
| <p>This document contains the N4JS IDE Specification.</p> |
| </div> |
| <h2 id="_introduction" class="discrete">Introduction</h2> |
| <div class="paragraph"> |
| <p>This document describes the features of the N4JS <a href="#AC">IDE</a>, that is the user interface and features available to users of the <a href="#AC">IDE</a>. The language N4JS is described in [<a href="#N4JSSpec">N4JSSpec</a>] and is not part of this document.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="sec:Views"><a class="anchor" href="#sec:Views"></a><a class="link" href="#sec:Views">1. Views</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This section briefly introduces all the views that belong to the application’s default perspective.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_eclipse-standard-views"><a class="anchor" href="#_eclipse-standard-views"></a><a class="link" href="#_eclipse-standard-views">1.1. Eclipse Standard Views</a></h3> |
| <div class="paragraph"> |
| <p>In the following we descibe views usually available in Eclipse based IDEs. Some of the views were slightly adjusted to match specific N4JS needs.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Project_Explorer_View"><a class="anchor" href="#sec:Project_Explorer_View"></a><a class="link" href="#sec:Project_Explorer_View">1.1.1. Project Explorer</a></h4> |
| <div class="paragraph"> |
| <p>The Project Explorer view shows the resources from the underlying workspace in a hierarchical way. From this view one can open a resource for editing in the associated editor or select it to perform an operation on the resource. A popup contest menu is available from the Project Explorer for each resources if used right clicks any of them. A lot of convenient actions are available for from the popping context menu: file modifications (such as Copy, Cut, Paste and Delete) and import/export. Project Explorer support file system modifications by drag-and-dropping resources. One can link the Project Explorer with the editors, if one enables the view-editor-linking then the node in the tree representing a particular resource in the workspace will be automatically revealed and highlighted once one activates the corresponding editor. This works the other way around as well, when a node is selected in the tree and the corresponding resource is opened in an editor, then the editor will be activated.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Outline_View"><a class="anchor" href="#sec:Outline_View"></a><a class="link" href="#sec:Outline_View">1.1.2. Outline</a></h4> |
| <div class="paragraph"> |
| <p>The Outline view is responsible for displaying the outline of a structured file that is currently opened in an editor. In case of opening an N4JS file the view depicts all the types defined in the file. The owned members, functions and methods of a particular type are represented in a tree structure. Furthermore in case of opening an N4JS file in the editor, one can link the Outline view with the editor which means whenever one selects a node from the outline view the corresponding item will be revealed and highlighted in the editor.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Problems_View"><a class="anchor" href="#sec:Problems_View"></a><a class="link" href="#sec:Problems_View">1.1.3. Problems</a></h4> |
| <div class="paragraph"> |
| <p>This view is used to show all validation errors and warnings in a table that are generated for workbench resources such as N4JS files. For instance when one writes and/or saves an N4JS file that contains validation errors and/or warnings those issues will be automatically logged into the Problems view. One can reveal the actual problem in the N4JS by simply double-clicking on the problem in the view. In this case the corresponding N4JS file will be opened (if it was not already opened), activated and the relevant line will be revealed in the editor. By default the grouping in the Problems view is done by the severity of the issues. One can group the issues by issue type or just disable the grouping at all. The first column of the table is the actual description of the issue for a particular resource. The second column names the problematic resource itself. The third column shows the relative path of the problematic resource. The location, fifth, column describes the problematic line in the resource. And last but not least the sixth column is for naming the type of the problem. This is optional and might be missing for some cases. One can customise the content of the view from the view menu. One can limit the number of revealed items in the table or can modify the behaviour of the content provider.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Console_View"><a class="anchor" href="#sec:Console_View"></a><a class="link" href="#sec:Console_View">1.1.4. Console</a></h4> |
| <div class="paragraph"> |
| <p>The Console view is used to reveal a text based output provided by a running process and also allows user to provide any input to the running process from the keyboard.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:History_View"><a class="anchor" href="#sec:History_View"></a><a class="link" href="#sec:History_View">1.1.5. History</a></h4> |
| <div class="paragraph"> |
| <p>History view supports a way to track the changes of the workbench resources. This view also responsible for providing a convenient way to reveal historical revisions of a particular resource and it is even supports a mechanism to compare two different revisions of a resource. By default this view only provides local historical information but if a resource is under version control then one can retrieve revisions for that particular resource even it was made by remotely by another IDE user.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Error_Log_View"><a class="anchor" href="#sec:Error_Log_View"></a><a class="link" href="#sec:Error_Log_View">1.1.6. Error Log</a></h4> |
| <div class="paragraph"> |
| <p>The Error Log view captures and logs all errors and warnings in a table generated by the application itself. Unlike Problems view the Error Log is responsible to collect and to reveal issues caused by a malfunctioned component or module of the IDE.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_n4js-specific-views"><a class="anchor" href="#_n4js-specific-views"></a><a class="link" href="#_n4js-specific-views">1.2. N4JS Specific Views</a></h3> |
| <div class="paragraph"> |
| <p>The following views are specific to N4JS. Some of these views are useful for developers of the N4JS language itself as they reveal internal details at runtime. Most of these views can be opened via <code>Windows/Show View/Other..</code>, see <code>N4JS</code> category.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_test-results"><a class="anchor" href="#_test-results"></a><a class="link" href="#_test-results">1.2.1. Test Results</a></h4> |
| <div class="paragraph"> |
| <p>The N4JS equivalent to the JUnit test view.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_source-graphs"><a class="anchor" href="#_source-graphs"></a><a class="link" href="#_source-graphs">1.2.2. Source Graphs</a></h4> |
| <div class="paragraph"> |
| <p>Shows the AST of the current source code in the editor windows.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_api-compare"><a class="anchor" href="#_api-compare"></a><a class="link" href="#_api-compare">1.2.3. API Compare</a></h4> |
| <div class="paragraph"> |
| <p>Shows compare results, i.e. the difference between an API definition project and its implementation.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_performance-graphs"><a class="anchor" href="#_performance-graphs"></a><a class="link" href="#_performance-graphs">1.2.4. Performance Graphs</a></h4> |
| <div class="paragraph"> |
| <p>Shows some performance measurements of typical tasks such as builds.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_source-mapping"><a class="anchor" href="#_source-mapping"></a><a class="link" href="#_source-mapping">1.2.5. Source Mapping</a></h4> |
| <div class="paragraph"> |
| <p>Shows source maps, i.e. the relation between N4JS source code and the generated plain JavaScript code.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_xpect-view"><a class="anchor" href="#_xpect-view"></a><a class="link" href="#_xpect-view">1.2.6. Xpect View</a></h4> |
| <div class="paragraph"> |
| <p>Shows result of an Xpext run, may be used to submit bug reports.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_navigation"><a class="anchor" href="#_navigation"></a><a class="link" href="#_navigation">2. Navigation</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>In this chapter we describe specific views and features to allow for easy navigation.</p> |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:Outline_Navigation"><a class="anchor" href="#sec:Outline_Navigation"></a><a class="link" href="#sec:Outline_Navigation">2.1. Outline</a></h3> |
| <div class="paragraph"> |
| <p>In general, a outline view and a quick outline are supported. Both outlines work similar, which is why both are specified together. The outline of an N4JS file is a tree which should show the following structure: <a id="sec:N4JS_Outline"></a></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Top-level defined classes, interfaces, roles, enums, functions and exported variables. For all these different types, icons are to be used (similar to JDT). Beside the name, type variables should be shown as well, if defined.</p> |
| </li> |
| <li> |
| <p>Members of classifiers are to be shown in the classifier branch. All members (fields, methods, field accessors) are to be shown, with appropriate icons indicating the type (field/member), static flag, access modifier, abstract flag. The icons should look similar to JDT.</p> |
| </li> |
| <li> |
| <p>an import declaration should have a node in the outline view, if multiple elements are imported these should represented as child nodes of that import declaration node. If the import uses aliases the original name and the alias name should appear in the outline node text.</p> |
| </li> |
| <li> |
| <p>for a non exported function declaration no outline node should be created</p> |
| </li> |
| <li> |
| <p>for a non exported variable declaration no outline node should be created</p> |
| </li> |
| <li> |
| <p>for a exported variable statement there should be a node in the outline, if this statement contains only one variable declaration the node represents this declaration. For multiple variable declarations in the statement the statement node just is a comma separated list of the variable names and for each variable there is child node</p> |
| </li> |
| <li> |
| <p>for fields, functions, methods, getters and variables their declared (return) type should be shown (by adding : typeName after the element name). If the type is inferred then the type name should be presented in a different color</p> |
| </li> |
| <li> |
| <p>for functions, methods and setters each formal parameter should be represented by its declared or inferred type (when inferred than with different color)</p> |
| </li> |
| <li> |
| <p>constructors are represented by the method icon and a decorator in the top right corner</p> |
| </li> |
| <li> |
| <p>enumeration literals are represented with the same decoration as static final fields</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The top-level elements must be sortable either by order in the file (default) or alphabetically.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_quick-outline"><a class="anchor" href="#_quick-outline"></a><a class="link" href="#_quick-outline">2.1.1. Quick Outline</a></h4> |
| <div class="paragraph"> |
| <p>The quick outline supports two modes. The modes are iteratively selected by pressing <span class="keyseq"><kbd>CMD/CTRL</kbd>+<kbd>O</kbd></span>.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">owned</dt> |
| <dd> |
| <p>This is the default mode, only members directly owned by the type are shown</p> |
| </dd> |
| <dt class="hdlist1">inherited</dt> |
| <dd> |
| <p>In this mode, the owned members are shown including inherited, consumed, or polyfilled members. The origin is also shown and a different color is used to highlight the special status of these members. For usability reasons (limiting the number of filters), inherited, consumed and polyfilled members are treated similarly.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_normal-outline"><a class="anchor" href="#_normal-outline"></a><a class="link" href="#_normal-outline">2.1.2. Normal Outline</a></h4> |
| <div class="paragraph"> |
| <p>In the normal outline view, toggles are used for the same purpose. Visualisations are similar to the quick outline view.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">inherited</dt> |
| <dd> |
| <p>By default, only owned members of a type are shown. If the "inherited" toggle is active, inherited, consumed, or polyfilled members as well. For usability reasons (limiting the number of filters), inherited, consumed, and polyfilled members are treated similarly.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sidebarblock"> |
| <div class="content"> |
| <a href="https://github.com/eclipse/n4js/issues/99" class="gray" title="GitHub Issues"><span class="image"><img src="images/issue.svg" alt=""></span> #99</a> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">sorting</dt> |
| <dd> |
| <p>By default, all elements are sorted in the order of their appearance in the source code. If alphabetic sorting is enabled, they are sorted alphabetically.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="admonitionblock todo"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-todo" title="Todo"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Potential improvements:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>show decorator when a member overrides and member from a super class / super interface or role</p> |
| </li> |
| <li> |
| <p>show object literals and their members in the outline view (just filter <code>eAllContents</code> of an element that already has a node in outline view for object literals)</p> |
| </li> |
| <li> |
| <p>show function expression in the outline view (just filter <code>eAllContents</code> of an element that already has a node in outline view for function expressions)</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_navigation-commands"><a class="anchor" href="#_navigation-commands"></a><a class="link" href="#_navigation-commands">2.2. Navigation Commands</a></h3> |
| <div class="sect3"> |
| <h4 id="sec:Navigate_to_Declaration"><a class="anchor" href="#sec:Navigate_to_Declaration"></a><a class="link" href="#sec:Navigate_to_Declaration">2.2.1. Navigate to Declaration</a></h4> |
| <div class="paragraph"> |
| <p>It is possible to Command-click on almost every reference and jump to its declaration.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:find_by_references"><a class="anchor" href="#sec:find_by_references"></a><a class="link" href="#sec:find_by_references">2.2.2. Find by References</a></h4> |
| <div class="paragraph"> |
| <p>For each referenceable element in an open N4JS file you can click your mouse and invoke the context menu to select <code>Find references</code>. Then in the Eclipse search view all found references are displayed as tree: each match is structured by resource path and coarse grained element in the resource (like a method). If there are multiple matches within a method only the first match is linked but in its display string the total match count is shown in brackets.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>find by references shows the result as tree in the Eclipse search view with having elements that are members or have defined type displayed as nodes</p> |
| </li> |
| <li> |
| <p>every found reference is displayed under its nearest parent that is a member or has a defined type</p> |
| </li> |
| <li> |
| <p>if there a multiple found references in a node only the first one is displayed (and linked) + the number of all total matches is shown as part of the display string (like in JDT)</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Open_Type_Declaration"><a class="anchor" href="#sec:Open_Type_Declaration"></a><a class="link" href="#sec:Open_Type_Declaration">2.2.3. Open Type Declaration</a></h4> |
| <div class="paragraph"> |
| <p>One can quickly browse the workbench for available types. The declaration of the types can be opened in editor from this dialog. The N4JS type search dialog can be raised with the <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>T</kbd> key binding (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>T</kbd> on Windows and Linux systems).</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Enter <strong>exact type name</strong>, prefix name or a camel case pattern to run a query against the types. The following rules and patterns are supported.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Wildcards</strong>: <code>?</code> for any character and <code>*</code> for any string.</p> |
| </li> |
| <li> |
| <p><strong>Camel case</strong>: <code>DM</code> will return with all types that contains <code>D</code> and <code>M</code> with the given order such as <code>DataMap</code> and <code>DataMapEntry</code> but not <code>ImmutableDataMap</code>.</p> |
| <div class="paragraph"> |
| <p><code>AcBuGr</code> will return with all types that contain <code>Ac</code>, <code>Bu</code> and <code>Gr</code> with the given order such as <code>ActionButtonGroup</code>.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><strong>Highlighting</strong>: The matching types names are highlighted according to the matching parts.</p> |
| </li> |
| <li> |
| <p><strong>Decorator</strong> for duplicate type names: The internally used fully qualified name of the type will be appended to the type name automatically, so one can easily distinguish between types even there are type name collision.</p> |
| </li> |
| <li> |
| <p><strong>Opening types in editor</strong>: Type declarations can be opened in the editor in the following ways: after entering the type name prefix or pattern to the filter text one can navigate among the filtered items with the up and/or down arrow keys. Simply hitting return on the keyboard or clicking on the ’OK’ button the currently selected declaration of the selected type will be opened in the editor. For opening multiple type declarations one can use the <kbd>Shift</kbd> modifier to select more than one element. Single type can be opened with double clicking on it in the dialog.</p> |
| </li> |
| <li> |
| <p><strong>History</strong>: Once a type is being opened then it will be available among the recently opened type in the type search dialog. These items will show up in the upper part of the list in the dialog.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect2 language-bash"> |
| <h3 id="sec:Working_Sets"><a class="anchor" href="#sec:Working_Sets"></a><a class="link" href="#sec:Working_Sets">2.3. Working Sets</a></h3> |
| <div class="paragraph"> |
| <p>Working sets are used to logically group resources, projects in the Project Explorer (navigator) and in the UI in general. Although a couple of projects can be easily handled and shown without any sophisticated working set support in the navigator, larger code sources consisting of multiple projects could cause some trouble when one has to maintain them. Indeed one could use multiple workspaces and could switch between them or can simply manually open-close relevant projects, but this gets cumbersome too.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This section describes the general design of the N4JS specific working set support and also introduces a couple of use cases while enumerating the constraints.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Working_Set_Managers"><a class="anchor" href="#sec:Working_Set_Managers"></a><a class="link" href="#sec:Working_Set_Managers">2.3.1. Working Set Managers</a></h4> |
| <div class="paragraph"> |
| <p>Just like the JDT (<code>org.eclipse.jdt.internal.ui.workingsets.WorkingSetModel</code>) based working set support, the N4JS IDE based approach is also aware of the <code>org.eclipse.ui.IWorkingSet</code> and the <code>org.eclipse.ui.IWorkingSetManager</code> APIs but besides simply using them it comes with its own implementation and adapts it to the default Eclipse based one, furthermore it also comes with an Eclipse extension point based mechanism to support various working set managers at the same time to provide even better user experience and a more convenient way of working set management.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A working set manager can be contributed to the IDE via the <code>org.eclipse.n4js.ui.workingSetManager</code> extension point, then the implementation class must implement the <code>org.eclipse.n4js.ui.workingsets.WorkingSetManager</code> interface but it is highly recommended to rather extend the <code>org.eclipse.n4js.ui.workingsets.WorkingSetManagerImpl</code> class. Guice based dependency injection should also be considered when implementing the custom working set manager. It means that each custom working set manager implementation must have a public <em>no-args</em> constructor. This <em>no-args</em> constructor will be invoked when creating the instances via <code>IConfigurationElement#createExecutableExtension(String)</code> method. Then the members, if any will be injected by the working set manager broker. Below <code>plugin.xml</code> snippet describes how to contribute a custom working set manager to the IDE.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"> <extension |
| point="org.eclipse.n4js.ui.workingSetManager"> |
| <manager |
| class="some.package.name.MyExecutableExtensionFactory:some.package.name.MyWorkingSetManager"> |
| </manager> |
| </extension></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>By default the N4JS IDE comes with five different built-in working set managers. These are the followings:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Manual Association Working Set Manager,</p> |
| </li> |
| <li> |
| <p>Project Name Filter Working Set Manager,</p> |
| </li> |
| <li> |
| <p>Git Repository Working Set Manager,</p> |
| </li> |
| <li> |
| <p>Project Location Working Set Manager and</p> |
| </li> |
| <li> |
| <p>N4JS Project Type Working Set Manager.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The benefits and the details of each built-in working set managers will be discussed in later sections but first we have to distinguish between three conceptually different working set manager approaches.</p> |
| </div> |
| <div class="paragraph"> |
| <p>First off, IDE supports fully static working set managers. Fully static working set managers might manage any arbitrary number of working sets, and each working set might be associated with any number of Eclipse projects. That means, user might create, edit and remove working sets and manually associate projects with individual working sets. One project might belong to multiple working sets. There is a dedicated working set, <em>Other Projects</em>, that cannot be renamed and/or deleted. When no user defined working sets are available this dedicated working set will be still available. IDE comes with one single fully static working set manager: <em>Manual Association Working Set Manager</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The second kind of working set manager is the semi-dynamic one. That means, user can create, modify and delete working sets, but the associations between the projects and the working sets are automatic. This means, the user might define a working set - project association rule, and the projects will be automatically associated with the working sets. Just like in the above kind, one project might belong to multiple working sets and here as well, there is a dedicated working set manager, that cannot be modified: <em>Other Projects</em>. IDE comes with one semi-dynamic working set manager. That is the <em>Project Name Filter Working Set Manager</em>. User might define a project name filter rule with a regular expression, and each project which name matches a pattern will be associated with the working set. If a project does not comply to any working set manager rule, then it will belong to the <em>Other Projects</em> working set.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The third kind of working set manager is the fully-dynamic working set manager. Both the working sets and the project associations are done by some implementation specific rules. Such as Git repository provider based, or project location based approaches. These working set managers have the dedicated <em>Other Projects</em> working set that is used as a fallback working set. For instance, if the <em>Git Repository Working Set Manager</em> is the active one, all projects that are shared with Git will belong to the corresponding working set manager but if a project is not yet a shared project, then it will belong to the dedicated fallback working set. As always that working set manager cannot be deleted and/or modified.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Working_Set_Constraints"><a class="anchor" href="#sec:Working_Set_Constraints"></a><a class="link" href="#sec:Working_Set_Constraints">2.3.2. Working Set Constraints</a></h4> |
| <div class="paragraph"> |
| <p>This section enumerates a set of constraints that have to considered by both end users and implementors:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Working set manager identifier must be unique.</p> |
| </li> |
| <li> |
| <p>The identifier of the working set manager must be unique per container working set managers.</p> |
| </li> |
| <li> |
| <p>Each working set must have a working set with <em>Other Projects</em> unique ID and name.</p> |
| </li> |
| <li> |
| <p>Working sets with <em>Other Projects</em> unique ID must not be editable nor deletable.</p> |
| </li> |
| <li> |
| <p>At least one working set should be visible (not hidden) per working set managers.</p> |
| </li> |
| <li> |
| <p>Working set managers are activated when the <em>Working Sets</em> are configured as <em>Top Level Elements</em> in the <em>Project Explorer</em>.</p> |
| </li> |
| <li> |
| <p>Working set order can be specified and customized by the user if it is not specified yet, then a case sensitive ordering based on the working set names should be applied.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Manual_Association_Working_Set_Manager_UI_Features"><a class="anchor" href="#sec:Manual_Association_Working_Set_Manager_UI_Features"></a><a class="link" href="#sec:Manual_Association_Working_Set_Manager_UI_Features">2.3.3. Manual Association Working Set Manager - UI Features</a></h4> |
| <div class="paragraph"> |
| <p>This section describes the working set manager by introducing the UI capabilities as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This working set manager is a fully static working set manager and activated and used as the default one when the working set manager support is turned on in the IDE. With this working set manager one can create a new working set by simply defining a unique name for the working set and associating any number of workspace project to the working set. Furthermore existing working sets can be modified and deleted but the <em>Other Projects</em> working set. The working set support can be turned on in the <em>Project Explorer</em> view. Via the view menu one has to select <em>Top Level Elements</em> <em>></em> <em>Working Sets</em> menu item.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/activate_working_set_managers.png" alt="Activate_Working_Set_Managers" width="50%"> |
| </div> |
| <div class="title">Figure 1. Activate Working Set Managers</div> |
| </div> |
| <div class="paragraph"> |
| <p>After the working set manager mode activation, a new toolbar contribution item become visible and user can select among the available working set managers.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/select_working_set_manager_01.png" alt="Select_Working_Set_Manager" width="50%"> |
| </div> |
| <div class="title">Figure 2. Select Working Set Manager</div> |
| </div> |
| <div class="paragraph"> |
| <p>As the below picture depicts the available working set managers are listed and the currently active manager is marked with a check. In our case that is the <em>Manual Association Working Set Manager</em>.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/select_working_set_manager_02.png" alt="Activate_Working_Set_Manager" width="25%"> |
| </div> |
| <div class="title">Figure 3. Activate Working Set Manager</div> |
| </div> |
| <div class="paragraph"> |
| <p>Once the the <em>Configure Manual Association…​</em> menu item is selected, the working set manager configuration dialog pops up. By clicking on the <em>New…​</em> button in the configuration dialog, a new working set wizard will be invoked and the manual working set - project association can be configured.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/configure_working_sets_01.png" alt="Configure_Working_Sets" width="25%"> |
| </div> |
| <div class="title">Figure 4. Configure Working Sets</div> |
| </div> |
| <div class="paragraph"> |
| <p>In the wizard after specifying the desired unique name of the working set an arbitrary number of workspace projects can be associated with the working set. It is important to note, that a project can be associated with more than one working sets. If a project is not associated with any working sets then it will be automatically linked to the fallback <em>Other Projects</em> working set.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/working_set_project_association.png" alt="Configure_Working_Set_Project_Association" width="50%"> |
| </div> |
| <div class="title">Figure 5. Working Set - Projects Association</div> |
| </div> |
| <div class="paragraph"> |
| <p>Once all the changes made are confirmed and the configuration dialog is closed via the <em>OK</em> button, the <em>Project Explorer</em> will be refreshed and will reflect the working set changes.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/working_sets_in_navigator.png" alt="Custom_Working_Sets_In_Project_Explorer" width="25%"> |
| </div> |
| <div class="title">Figure 6. Custom Working Sets In Project Explorer</div> |
| </div> |
| <div class="paragraph"> |
| <p>The order of the working sets can be configured and customized in the working set manager configuration dialog, or just simply reordering it from the navigator itself by drag and dropping the available working set managers.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/working_set_reorder.png" alt="Re_Ordering_Working_Sets_In_Project_Explorer" width="25%"> |
| </div> |
| <div class="title">Figure 7. Re-ordering Working Sets In Project Explorer</div> |
| </div> |
| <div class="paragraph"> |
| <p>Besides changing the order of the working sets, working sets can be hidden from the navigator. Just like the ordering, this can be changed from the working set configuration dialog, or by simply selecting working sets in the navigator and hiding them via <em>Hide Selected Working Set</em> menu item. Important to note, at least one working set should be visible in the navigator, so if all the working sets are selected in the navigator, then the menu item will be disabled. Same behavior in the working set customization dialog, if all items are unchecked, then the <em>OK</em> button is disabled in the dialog.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/working_set_hide.png" alt="Hide_Working_Sets_In_Project_Explorer" width="25%"> |
| </div> |
| <div class="title">Figure 8. Hide Working Sets In Project Explorer</div> |
| </div> |
| <div class="paragraph"> |
| <p>Once at least one working set is hidden from the UI, then a new toolbar contribution become visible in the <em>Project Explorer</em>. This UI contribution provides a quick, convenient way to show a specific or all hidden working sets in the navigator. It is worth to note, if a project is automatically associated with the <em>Other Projects</em> working set (because it does not belong to any working sets due to the lack of manual association) it will be not shown in the navigator if the <em>Other Projects</em> working set is hidden. Once all working sets are visible, indeed the <em>Show Hidden Working Sets</em> toolbar contribution become invisible.</p> |
| </div> |
| <div class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/04_navigation/fig/working_set_show.png" alt="Show_Hidden_Working_Sets_In_Project_Explorer" width="25%"> |
| </div> |
| <div class="title">Figure 9. Show Hidden Working Sets In Project Explorer</div> |
| </div> |
| <div class="paragraph"> |
| <p>Besides the above described generic working set UI support, projects can be associated with working sets by simply drag and dropping them from one working set into another. Note, this is only supported for the <em>Manual Association Working Set Manager</em>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Project_Name_Filter_Working_Set_Manager"><a class="anchor" href="#sec:Project_Name_Filter_Working_Set_Manager"></a><a class="link" href="#sec:Project_Name_Filter_Working_Set_Manager">2.3.4. Project Name Filter Working Set Manager</a></h4> |
| <div class="paragraph"> |
| <p>As mentioned earlier, this working set is a semi-dynamic working set. The working sets can be created, edited and deleted by the user by simply specifying project name filter pattern as valid regular expressions but the project association itself is fully automatic. If the name of a project does not match with any project name filter rule, then the project will be associated with the <em>Other Projects</em> working set. Although reordering the working sets from the navigator by simple drag and dropping them is supported, project association is disabled.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Git_Repository_Working_Set_Manager"><a class="anchor" href="#sec:Git_Repository_Working_Set_Manager"></a><a class="link" href="#sec:Git_Repository_Working_Set_Manager">2.3.5. Git Repository Working Set Manager</a></h4> |
| <div class="paragraph"> |
| <p>This working set is a fully-dynamic working set. Projects will be associated by the Git providers. It means, if a project is imported from a pre-configured local Git repository, then the project will be associated with the working set linked with the Git repository. The subset of the available working sets is become automatically updated once the Git repository preferences changed by the user. These preferences can be changed on the <em>Git</em> perspective in the <em>Git Repositories</em> view by simple adding or hiding/removing a repository from the view.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Project_Location_Working_Set_Manager"><a class="anchor" href="#sec:Project_Location_Working_Set_Manager"></a><a class="link" href="#sec:Project_Location_Working_Set_Manager">2.3.6. Project Location Working Set Manager</a></h4> |
| <div class="paragraph"> |
| <p>This fully-dynamic working set manager calculates the subset of available working sets based on the parent folder of the projects. The benefit of this working set manager is to support the convention recommended by the maven/Git folder structuring. The following constraints are applied when associating the projects with the available working sets:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If a project is located in the root of the Eclipse workspace, then it will be associated with <em>Other Projects</em> working set.</p> |
| </li> |
| <li> |
| <p>If a project is nested somewhere in the Eclipse workspace, then it will be associated with a working set that has the same name as the parent folder of the project. Let assume the Eclipse workspace root points to <code>/eclipse/root</code> and there is a project <code>P1</code> nested in the workspace root at <code>/eclipse/root/path/to/nested/location/P1</code>, then the associated working set will be <code>location</code>.</p> |
| </li> |
| <li> |
| <p>If a project is not contained in the workspace, but has a Git provider that is configured in IDE, and the project root is the local Git repository root, then the associated working set name will be the name of the Git repository. For example, if we have Eclipse workspace root pointing to <code>/eclipse/root</code> location and a <code>P2</code> project located <code>/some/path/to/git/P2</code> but this location is the location of a registered Git repository, then the name of the associated working set will be neither <code>Other Projects</code> not <code>git</code> but <code>P2</code> since that is known Git local repository root.</p> |
| </li> |
| <li> |
| <p>If project <code>P3</code> is not contained in the Eclipse workspace but contained in a known local Git repository just like above, but the project root is not the local Git repository root, then the name of the parent folder will be considered as the name of the associated working set. This rule is a hybrid alternative of the second and the third constraints, hence for instance if the project is under <code>/some/path/to/git/repositoryName/plugins/P3</code> and <code>repositoryName</code> is local git repository, then the name of the associated working set will be <code>plugins</code> and not <code>repositoryName</code>.</p> |
| </li> |
| <li> |
| <p>Else the associated working set will be the <em>Other Projects</em> fallback working set.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:N4JS_Project_Type_Working_Set_Manager"><a class="anchor" href="#sec:N4JS_Project_Type_Working_Set_Manager"></a><a class="link" href="#sec:N4JS_Project_Type_Working_Set_Manager">2.3.7. N4JS Project Type Working Set Manager</a></h4> |
| <div class="paragraph"> |
| <p>This is working set manager is a N4JS specific fully-dynamic working set manager. The working sets will be calculated based on the instances defined by the <code>org.eclipse.n4js.n4mf.ProjectType</code> type. Each accessible N4JS project will be associated to a working set based on the project type. A workspace project will be associated with the <em>Other Projects</em> fallback working set if any of the followings are true to the project:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The project is not accessible. (It does not exist or is not opened.)</p> |
| </li> |
| <li> |
| <p>The project does not configured with <em>Xtext</em> nature.</p> |
| </li> |
| <li> |
| <p>The project does not have an <em>Xtext</em> builder command ID.</p> |
| </li> |
| <li> |
| <p>The project does not have a valid N4 manifest file.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_assistance"><a class="anchor" href="#_assistance"></a><a class="link" href="#_assistance">3. Assistance</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>In this chapter we describe all kind of tools assisting the user when writing code, i.e. content assist, quickfixes, quick assists, etc.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title=""></i> |
| </td> |
| <td class="content"> |
| Not all features are yet implemented! |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:Content_Assist"><a class="anchor" href="#sec:Content_Assist"></a><a class="link" href="#sec:Content_Assist">3.1. Content Assist</a></h3> |
| <div class="paragraph"> |
| <p>Content assist may change the document at various places at once. In those cases, it is important to prevent flickering in the editor. The FQNImporter provides a blue print how to adjust line numbers properly and scroll the viewport of the current editor to minimize flickering in the UI.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Completions not listed here as they are provided by template proposals:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Classifier declaration template proposal</p> |
| </li> |
| <li> |
| <p>Function declaration template proposal</p> |
| </li> |
| <li> |
| <p>Getter/Setter pair template proposal</p> |
| </li> |
| </ol> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Complete_Keywords"><a class="anchor" href="#sec:Complete_Keywords"></a><a class="link" href="#sec:Complete_Keywords">3.1.1. Complete Keywords</a></h4> |
| <div class="paragraph"> |
| <p>Complete keyword which are syntactically correct at a given location. Do not suggest completions which would lead to wrong code.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Keywords that contain only a single character are not proposed since they would pollute the proposal window and don’t offer added value.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Special attention has to be given to operators. Since they are modelled in the grammar and not as cross references, their validaty is purely syntactically. That is, there is no generic facility in Xtext, that allows to filter unapplicable operators as there is for cross references.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Complete_Annotations"><a class="anchor" href="#sec:Complete_Annotations"></a><a class="link" href="#sec:Complete_Annotations">3.1.2. Complete Annotations</a></h4> |
| <div class="paragraph"> |
| <p>Annotations can be proposed depending on the following elements or the context.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Complete_Identifier_Reference"><a class="anchor" href="#sec:Complete_Identifier_Reference"></a><a class="link" href="#sec:Complete_Identifier_Reference">3.1.3. Complete Identifier Reference</a></h4> |
| <div class="paragraph"> |
| <p>References to identifiers can be automatically completed. This is even true if the declaration is not imported yet, as the import may be automatically added as well.</p> |
| </div> |
| <div class="openblock"> |
| <div class="title">Complete identifier references</div> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>The IDE supports auto-completion of an identifier referencing to a declaration.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Complete type references.</p> |
| </li> |
| <li> |
| <p>Complete function references.</p> |
| </li> |
| <li> |
| <p>Complete variable references.</p> |
| </li> |
| <li> |
| <p>Complete parameter references.</p> |
| </li> |
| <li> |
| <p>If necessary, imports are added automatically to complete reference <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>r</mi></math> to declaration <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>D</mi></math>.</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>-</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <div class="paragraph"> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="3.0mm"/><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mfenced close=")" open="("><mi>r</mi><mi>D</mi></mfenced></math><br> |
| <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="3.0mm"/><mo>⇔</mo></math><br> |
| <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="3.0mm"/><mi>r</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>D</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi></math><br> |
| <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="3.0mm"/><mi>D</mi><mo>∈</mo><mi>r</mi><mo>.</mo><mi>m</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi></math><br> |
| <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="3.0mm"/><mo>⊕</mo></math><br> |
| <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="3.0mm"/><mo>∃</mo><mstyle mathvariant="monospace"><mtext>NamedImportSpecifier</mtext></mstyle><mi>N</mi><mi>I</mi><mi>S</mi><mi>:</mi></math><br> |
| <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="3.0mm"/><mi>W</mi><mi>I</mi><mi>S</mi><mo>.</mo><mi>i</mi><mi>m</mi><mi>p</mi><mi>o</mi><mi>r</mi><mi>t</mi><mi>D</mi><mi>e</mi><mi>c</mi><mi>l</mi><mo>.</mo><mi>i</mi><mi>m</mi><mi>p</mi><mi>o</mi><mi>r</mi><mi>t</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>=</mo><mi>D</mi><mo>.</mo><mi>m</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi></math><br> |
| <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="3.0mm"/><mo>∨</mo><mo>∃</mo><mstyle mathvariant="monospace"><mtext>WildcardImportSpecifier</mtext></mstyle><mi>W</mi><mi>I</mi><mi>S</mi><mi>:</mi></math></p> |
| </div> |
| </dd> |
| <dt class="hdlist1">Description</dt> |
| <dd> |
| <p>There might be multiple declarations <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>D</mi></math> in project (or in dependent projects) with <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>D</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>r</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi></math>. If the declaration <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>D</mi></math> is not local, then a named import may be created by the content assist:</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>If the declaration <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>D</mi></math> is local, no import is created</p> |
| </li> |
| <li> |
| <p>If an import enabling access to the declaration already exists, no other import is created.</p> |
| </li> |
| <li> |
| <p>If an alias already exists, the alias name is used, even if the prefix was different when the content assist was activated.</p> |
| </li> |
| <li> |
| <p>If the import would conflict with an existing member, an alias is proposed along with the import. Linked editing helps to choose a proper alias.</p> |
| </li> |
| <li> |
| <p>All imports from a single module are done within a single import declaration. The exception to this rule are wildcard imports that provide a simple name which is currently unused. In that case, a new import may be necessary to disambiguate the wildcard.</p> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| <li> |
| <p>If the identifier reference refers to a function (or method), an opening and a closing parenthesis are appended and |
| the cursor is positioned between these two parentheses.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Complete_Member_Overrides"><a class="anchor" href="#sec:Complete_Member_Overrides"></a><a class="link" href="#sec:Complete_Member_Overrides">3.1.4. Complete Member Overrides</a></h4> |
| <div class="openblock"> |
| <div class="title">Complete Member Overrides Inside a classifier</div> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>A prefix of an inherited member can be used to autocomplete that to a complete declaration. |
| This is in particular true for methods.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Constructor_Completion"><a class="anchor" href="#sec:Constructor_Completion"></a><a class="link" href="#sec:Constructor_Completion">3.1.5. Constructor Completion</a></h4> |
| <div class="openblock"> |
| <div class="title">Constructor Completion</div> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>Constructor Completion Based on the declared fields and super constructor, constructor methods can be completed.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Complete_Function_Expression"><a class="anchor" href="#sec:Complete_Function_Expression"></a><a class="link" href="#sec:Complete_Function_Expression">3.1.6. Complete Function Expression with Known Type</a></h4> |
| <div class="openblock"> |
| <div class="title">Complete Function Expression</div> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>If a function expression is used as an argument or assigned to a typed variable, the signature of the function can be derived from the type. This can be used to complete a function expression.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Complete_Variable_and_Parameter_Names"><a class="anchor" href="#sec:Complete_Variable_and_Parameter_Names"></a><a class="link" href="#sec:Complete_Variable_and_Parameter_Names">3.1.7. Complete Variable and Parameter Names</a></h4> |
| <div class="openblock"> |
| <div class="title">Type based completion of Variable and Parameter Names</div> |
| <div class="content"> |
| <div class="paragraph"> |
| <p>Variable and parameter names can be completed based on the type. Camel case detection is used to propose different variations.</p> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Completion of variables references see <a href="#sec:Complete_Identifier_Reference">Complete Identifier Reference</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:Quick_Fixes"><a class="anchor" href="#sec:Quick_Fixes"></a><a class="link" href="#sec:Quick_Fixes">3.2. Quick Fixes</a></h3> |
| <div class="paragraph"> |
| <p>Quick fixes try to solve issues, i.e. errors or warnings, automatically. This is done by rewriting code, either at the location of the issue or at referenced locations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In all cases, a quick fix must only be suggested if the following preconditions are fulfilled:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>All locations at which modifications have to be done must be writeable.</p> |
| </li> |
| <li> |
| <p>If bindings are involved, e.g., names are to be changed, all previous bindings must remain similar. This might be more complicated as it seems!</p> |
| </li> |
| </ol> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:N4JS_Issue_Properties"><a class="anchor" href="#sec:N4JS_Issue_Properties"></a><a class="link" href="#sec:N4JS_Issue_Properties">3.2.1. N4JS Issue User data</a></h4> |
| <div class="paragraph"> |
| <p>As some quick fixes need more information to decide upfront which strategy to use, some issues provide additional data. These properties are defined in the file <code>IssueUserDataKeys.java</code> in the <code>org.eclipse.n4js.validation</code> package. They can for example be accessed by passing the according key to the <code>getUserData</code> method of an <code>N4JSIssue</code> instance. They are also available as array based Xtext Issue user data.<br></p> |
| </div> |
| <div class="paragraph"> |
| <p>All available user data keys are described for each Issue code in <a href="#sec:N4JS_Issue_Fixes">N4JS Issue Fixes</a>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:N4JS_Issue_Fixes"><a class="anchor" href="#sec:N4JS_Issue_Fixes"></a><a class="link" href="#sec:N4JS_Issue_Fixes">3.2.2. N4JS Issue Fixes</a></h4> |
| <div class="paragraph"> |
| <p>The principle idea is to provide a quick fix for every issue, if it is possible to automatically solve it.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Linking_Issues"><a class="anchor" href="#sec:Linking_Issues"></a><a class="link" href="#sec:Linking_Issues">3.2.2.1. Linking Issues</a></h5> |
| <div class="paragraph"> |
| <p>Linking issues are special in that they are created by the standard Xtext linker and use all the same built-in issue code <code>Diagnostic.LINKING_DIAGNOSTIC</code>. Therefore, we cannot refer to these issues using one of our custom N4JS issue codes.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Diagnostic.LINKING_DIAGNOSTIC</dt> |
| <dd> |
| <p><code>Couldn’t resolve reference to <em>n</em></code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Add missing import declaration for unresolved name <em>n</em>.</p> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Precondition |
| </td> |
| <td class="hdlist2"> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>An exported identifiable element <em>e</em> with name <em>n</em> exists in another module <em>m</em>.</p> |
| </li> |
| <li> |
| <p><em>e</em> is visible from the given location.</p> |
| </li> |
| </ol> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Label |
| </td> |
| <td class="hdlist2"> |
| <p><code>Import <em>n</em> - <em>m</em></code></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p>An import declaration was added such that name <em>n</em> is now resolvable at the given location and bound to <em>e</em>.</p> |
| </dd> |
| <dt class="hdlist1">Description</dt> |
| <dd> |
| <p>Some important notes:</p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p><code>A</code> separate quick fix is proposed for each candidate element instead of having a single generic quick fix for adding imports and showing a dialog later (for example, create two quick fixes “Import class <code>X</code> from module M1" and “Import interface <code>X</code> from module M2" instead of a single quick fix “Add import for name X").<br> |
| This is unusual for quick fixes, because it means significant work has to be done upfront when creating the quick fix / modification proposals, which raises performance concerns. However,</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>the JDT handles this the same way and</p> |
| </li> |
| <li> |
| <p>this brings the implementation closer to content assist allowing more reuse, therefore this decision was taken.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>For consistency, matching of lower/upper/camel case is to be handled as in code completion during content assist. The same applies to display string formatting, esp. name formatting and coloring of element <em>e</em> and module <em>m</em>.</p> |
| </li> |
| <li> |
| <p>Note that here we can make more assumptions than during import as part of content assist. For example, we know that the element is not imported yet (otherwise there would not be an error) and there won’t be a need for an alias and linked editing.</p> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Import_Issues"><a class="anchor" href="#sec:Import_Issues"></a><a class="link" href="#sec:Import_Issues">3.2.2.2. Import Issues</a></h5> |
| |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Visibility_Issues"><a class="anchor" href="#sec:Visibility_Issues"></a><a class="link" href="#sec:Visibility_Issues">3.2.2.3. Visibility Issues</a></h5> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">VIS_ILLEGAL_MEMBER_ACCESS</dt> |
| <dd> |
| <p><code>The <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>m</mi><mi>e</mi><mi>m</mi><mi>b</mi><mi>e</mi><mi>r</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi></math> <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>m</mi><mi>e</mi><mi>m</mi><mi>b</mi><mi>e</mi><mi>r</mi></math> is not visible.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Change access modifier to protected/public or remove <code>@Internal</code> annotation.</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>The file containing the declaration of <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>m</mi><mi>e</mi><mi>m</mi><mi>b</mi><mi>e</mi><mi>r</mi></math> is modifiable</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p>The access modifier has been changed so that <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>m</mi><mi>e</mi><mi>m</mi><mi>b</mi><mi>e</mi><mi>r</mi></math> is visible at issue location.</p> |
| </dd> |
| <dt class="hdlist1">User Data</dt> |
| <dd> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>ACCESS_SUGGESTION</strong> The most restrictive modifier making the member visible.</p> |
| </li> |
| <li> |
| <p><strong>DECLARATION_OBJECT_URI</strong> The EObject URI of the member declaration</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>This table shows the access modifier changes to perform to fix the visibility issue while maintaining the strongest access restrictions possible.</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <colgroup> |
| <col style="width: 14.2857%;"> |
| <col style="width: 14.2857%;"> |
| <col style="width: 14.2857%;"> |
| <col style="width: 14.2857%;"> |
| <col style="width: 14.2857%;"> |
| <col style="width: 14.2857%;"> |
| <col style="width: 14.2858%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-center valign-top" rowspan="2"><p class="tableblock"><code>Access Modifier</code></p></td> |
| <td class="tableblock halign-center valign-top" colspan="6"><p class="tableblock"><code>Accessible From</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Inside Module</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Inside Project</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Vendor Subtypes</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Vendor Projects</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Other Subtypes</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Everywhere</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>private</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>protected@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>protected</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>protected@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>protected</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>protected@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>protected</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>protected</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Member access modifier changes for quick fixes</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">VIS_ILLEGAL_FUN_ACCESS</dt> |
| <dd> |
| <p><code>The function <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>f</mi></math> is not visible.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Change access modifier to protected/public or remove <code>@Internal</code> annotation.</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p>The access modifier has been changed so that <em>f</em> is visible at issue location.</p> |
| </dd> |
| <dt class="hdlist1">User Data</dt> |
| <dd> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>ACCESS_SUGGESTION</strong> The most restrictive modifier making the function visible.</p> |
| </li> |
| <li> |
| <p><strong>DECLARATION_OBJECT_URI</strong> The EObject URI of the function declaration</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">VIS_ILLEGAL_TYPE_ACCESS</dt> |
| <dd> |
| <p><code>The type <em>T</em> is not visible.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Change access modifier to protected/public or remove <code>@Internal</code> annotation.</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p>The access modifier has been changed so that <em>T</em> is visible at issue location.</p> |
| </dd> |
| <dt class="hdlist1">User Data</dt> |
| <dd> |
| <p>see VIS_ILLEGAL_FUN_ACCESS</p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">VIS_ILLEGAL_VARIABLE_ACCESS</dt> |
| <dd> |
| <p><code>The variable <em>v</em> is not visible.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Change access modifier to protected/public or remove <code>@Internal</code> annotation.</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>Module containing <em>v</em> is writeable.</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p>The access modifier has been changed so that <em>v</em> is visible at issue location.</p> |
| </dd> |
| <dt class="hdlist1">User Data</dt> |
| <dd> |
| <p>see VIS_ILLEGAL_FUN_ACCESS</p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>For type, variable and function visibility issues the following changes have to be made to solve the visibility issue:</p> |
| </div> |
| <table id="tab:typeAccessControl" class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 1. Type,function and variable access modifier changes for quick fixes</caption> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <th class="tableblock halign-center valign-top" rowspan="2"><p class="tableblock">Access Modifier</p></th> |
| <th class="tableblock halign-center valign-top" colspan="4"><p class="tableblock">Accessible From</p></th> |
| </tr> |
| <tr> |
| <th class="tableblock halign-center valign-top"><p class="tableblock">Module</p></th> |
| <th class="tableblock halign-center valign-top"><p class="tableblock">Project</p></th> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Vendor</p></th> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">World</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>private</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export project</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export project</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export project</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public@Internal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public@Internal</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>export public</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Classifier_Issues"><a class="anchor" href="#sec:Classifier_Issues"></a><a class="link" href="#sec:Classifier_Issues">3.2.2.4. Classifier Issues</a></h5> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">CLF_EXTEND_FINAL</dt> |
| <dd> |
| <p><code>Cannot extend final class <em>C</em>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Remove <code>@Final</code> annotation in class <em>C</em></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mo>¬</mo><mi>C</mi><mo>.</mo><mi>f</mi><mi>i</mi><mi>n</mi><mi>a</mi><mi>l</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_OBSERVABLE_MISSING</dt> |
| <dd> |
| <p><code>Class <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> extends observable class <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> and must therefore be annotated with @Observable.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Add <code>@Obervable</code> annotation in class <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0.</mn></msub><mi>o</mi><mi>b</mi><mi>s</mi><mi>e</mi><mi>r</mi><mi>v</mi><mi>a</mi><mi>b</mi><mi>l</mi><mi>e</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_OVERRIDE_ANNOTATION</dt> |
| <dd> |
| <p><code>The <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> overriding <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> must be annotated with @Override.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Add <code>@Override</code> annotation to <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Label</dt> |
| <dd> |
| <p><code>Add @Override</code></p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0.</mn></msub><mi>o</mi><mi>v</mi><mi>e</mi><mi>r</mi><mi>r</mi><mi>i</mi><mi>d</mi><mi>e</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_OVERRIDE_FINAL</dt> |
| <dd> |
| <p><code>The <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> cannot override final <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Remove <code>@Final</code> annotation in <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mo>¬</mo><msub><mi>e</mi><mn>1.</mn></msub><mi>f</mi><mi>i</mi><mi>n</mi><mi>a</mi><mi>l</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_OVERRIDE_VISIBILITY</dt> |
| <dd> |
| <p><code>The <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> cannot reduce the visibility of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Set access modifier of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> to access modifier of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0.</mn></msub><mi>a</mi><mi>c</mi><mi>c</mi><mo>=</mo><mo>=</mo><msub><mi>e</mi><mn>1.</mn></msub><mi>a</mi><mi>c</mi><mi>c</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_OVERRIDE_NON_EXISTENT</dt> |
| <dd> |
| <p><code>The <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> must override or implement a <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> from a super class, consumed role or implemented interface.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Remove <code>@Override</code> annotation in <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Label</dt> |
| <dd> |
| <p><code>Remove @Override</code></p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mo>¬</mo><msub><mi>e</mi><mn>1.</mn></msub><mi>o</mi><mi>v</mi><mi>e</mi><mi>r</mi><mi>r</mi><mi>i</mi><mi>d</mi><mi>e</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_REDEFINED_TYPE_NOT_SAME_TYPE</dt> |
| <dd> |
| <p><code>Type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> must equal type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>2</mn></msub></math>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Set declared type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> to declared type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>2</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>τ</mi><msub><mi>e</mi><mn>0</mn></msub><mo>=</mo><msub><mi>e</mi><mn>2</mn></msub></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_REDEFINED_MEMBER_TYPE_INVALID</dt> |
| <dd> |
| <p><code>Type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> does not conform to <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>2</mn></msub></math> <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math>: <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>3</mn></msub></math>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Set declared type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> to declared type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>τ</mi><msub><mi>e</mi><mn>0</mn></msub><mo>=</mo><msub><mi>e</mi><mn>1</mn></msub></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_REDEFINED_METHOD_TYPE_CONFLICT</dt> |
| <dd> |
| <p><code>Signature of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> does not conform to <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>2</mn></msub></math>: <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>3</mn></msub></math>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Set declared type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> to declared type of <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>2</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>τ</mi><msub><mi>e</mi><mn>0</mn></msub><mo>=</mo><msub><mi>e</mi><mn>2</mn></msub></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_MISSING_IMPLEMENTATION</dt> |
| <dd> |
| <p><code>Class <em>C</em> must either be defined abstract or implement <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>m</mi></math>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Declare <em>C</em> as abstract</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi><mo>.</mo><mi>a</mi><mi>b</mi><mi>s</mi><mi>t</mi><mi>r</mi><mi>a</mi><mi>c</mi><mi>t</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_ABSTRACT_BODY</dt> |
| <dd> |
| <p><code>Abstract methods do not specify a body.</code> for method <em>M</em></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Remove abstract annotation from method.</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mo>¬</mo><mi>M</mi><mo>.</mo><mi>a</mi><mi>b</mi><mi>s</mi><mi>t</mi><mi>r</mi><mi>a</mi><mi>c</mi><mi>t</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_ABSTRACT_MISSING</dt> |
| <dd> |
| <p><code>The abstract <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> in class <em>C</em> can only be defined in an abstract class.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Declare <em>C</em> as abstract</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi><mo>.</mo><mi>a</mi><mi>b</mi><mi>s</mi><mi>t</mi><mi>r</mi><mi>a</mi><mi>c</mi><mi>t</mi></math></p> |
| </dd> |
| <dt class="hdlist1">Multi appliable</dt> |
| <dd> |
| <p>false</p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_MISSING_BODY</dt> |
| <dd> |
| <p><code>The <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> has to have either a body or must be defined abstract.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Declare <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> as abstract</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1.</mn></msub><mi>a</mi><mi>b</mi><mi>s</mi><mi>t</mi><mi>r</mi><mi>a</mi><mi>c</mi><mi>t</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_EXT_EXTERNAL_N4JSD</dt> |
| <dd> |
| <p><code><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> declared as external have to be placed in a file with file extension ’n4jsd’.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Remove external annotation</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mo>¬</mo><msub><mi>e</mi><mn>0.</mn></msub><mi>e</mi><mi>x</mi><mi>t</mi><mi>e</mi><mi>r</mi><mi>n</mi><mi>a</mi><mi>l</mi></math></p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| <li> |
| <p>Change module file extension to n4jsd</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p>module file extension is n4jsd</p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">CLF_NOT_EXPORTED_NOT_PRIVATE</dt> |
| <dd> |
| <p><code>A <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> with visibility <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>1</mn></msub></math> must be marked as exported.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Export <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>e</mi><mn>0</mn></msub></math> is exported</p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Function_Issues"><a class="anchor" href="#sec:Function_Issues"></a><a class="link" href="#sec:Function_Issues">3.2.2.5. Function Issues</a></h5> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| FUN_BLOCK |
| </td> |
| <td class="hdlist2"> |
| <p><code>Functions declarations should not be placed in blocks. Use a function expression or move the statement to the top of the outer function.</code> with function <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>F</mi></math></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Change function declaration to function expression</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd/><mtd><mo>∃</mo><mstyle mathvariant="monospace"><mtext>Variable</mtext></mstyle><mi> </mi><mi>v</mi><mo>∈</mo><mi>F</mi><mo>.</mo><mi>v</mi><mi>e</mi><mi>e</mi><mi>:</mi></mtd></mtr><mtr><mtd/><mtd><mspace width="3.0em"/><mi>v</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>F</mi></mtd></mtr><mtr><mtd/><mtd><mspace width="3.0em"/><mo>∧</mo><mi>v</mi><mo>.</mo><mi>e</mi><mi>x</mi><mi>p</mi><mi>r</mi><mo>.</mo><mi>μ</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>FunctionExpression</mtext></mstyle></mtd></mtr><mtr><mtd/><mtd><mspace width="3.0em"/><mo>∧</mo><mi>v</mi><mo>.</mo><mi>e</mi><mi>x</mi><mi>p</mi><mi>r</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>,</mo><mi>v</mi><mo>.</mo><mi>e</mi><mi>x</mi><mi>p</mi><mi>r</mi><mo>.</mo><mi>b</mi><mi>o</mi><mi>d</mi><mi>y</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>b</mi><mi>o</mi><mi>d</mi><mi>y</mi></mtd></mtr></mtable></math> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Description</dt> |
| <dd> |
| <p>Change function declaration to function expression assigned to variable of the function name</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Syntax_Issues"><a class="anchor" href="#sec:Syntax_Issues"></a><a class="link" href="#sec:Syntax_Issues">3.2.2.6. Syntax Issues</a></h5> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">AST_STR_FUN_NOT_NESTED</dt> |
| <dd> |
| <p><code>Functions must only be declared on script level or as part of other expressions</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Change function declaration to function expression assigned to variable of the function name</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="openblock"> |
| <div class="content"> |
| <math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd/><mtd><mo>∃</mo><mstyle mathvariant="monospace"><mtext>Variable</mtext></mstyle><mi> </mi><mi>v</mi><mo>∈</mo><mi>F</mi><mo>.</mo><mi>v</mi><mi>e</mi><mi>e</mi><mi>:</mi></mtd></mtr><mtr><mtd/><mtd><mspace width="3.0em"/><mi>v</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>F</mi></mtd></mtr><mtr><mtd/><mtd><mspace width="3.0em"/><mo>∧</mo><mi>v</mi><mo>.</mo><mi>e</mi><mi>x</mi><mi>p</mi><mi>r</mi><mo>.</mo><mi>μ</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>FunctionExpression</mtext></mstyle></mtd></mtr><mtr><mtd/><mtd><mspace width="3.0em"/><mo>∧</mo><mi>v</mi><mo>.</mo><mi>e</mi><mi>x</mi><mi>p</mi><mi>r</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>,</mo><mi>v</mi><mo>.</mo><mi>e</mi><mi>x</mi><mi>p</mi><mi>r</mi><mo>.</mo><mi>b</mi><mi>o</mi><mi>d</mi><mi>y</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>b</mi><mi>o</mi><mi>d</mi><mi>y</mi></mtd></mtr></mtable></math> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">SYN_MODIFIER_BAD_ORDER</dt> |
| <dd> |
| <p><code>Modifiers should appear in this order: O </code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Rearrange access modifiers</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p>Modifiers are in order O</p> |
| </dd> |
| <dt class="hdlist1">Description</dt> |
| <dd> |
| <p>Reorder the access modifiers to match the N4JS compliant order.</p> |
| </dd> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Conversion_Issues"><a class="anchor" href="#sec:Conversion_Issues"></a><a class="link" href="#sec:Conversion_Issues">3.2.2.7. Conversion Issues</a></h5> |
| |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Type_Issues"><a class="anchor" href="#sec:Type_Issues"></a><a class="link" href="#sec:Type_Issues">3.2.2.8. Type Issues</a></h5> |
| |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Expression_Issues"><a class="anchor" href="#sec:Expression_Issues"></a><a class="link" href="#sec:Expression_Issues">3.2.2.9. Expression Issues</a></h5> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">EXP_WRONG_NUMBER_OF_TYPEARGS</dt> |
| <dd> |
| <p><code>Incorrect number of type arguments for <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>T</mi></math> <em>C</em>: expected <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>p</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi></math>, got <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi></math>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Remove superfluous arguments</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi><mo>></mo><mi>t</mi><mi>p</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi></math></p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi><mo>=</mo><mi>t</mi><mi>p</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi></math></p> |
| </dd> |
| <dt class="hdlist1">Description</dt> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">EXP_NUM_OF_ARGS_TOO_MANY</dt> |
| <dd> |
| <p><code>Incorrect number of arguments: expected <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>f</mi><mi>p</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi></math>, got <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>a</mi><mi>r</mi><mi>g</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi></math>.</code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Remove superfluous arguments</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>a</mi><mi>r</mi><mi>g</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi><mo>></mo><mi>f</mi><mi>p</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi></math></p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>a</mi><mi>r</mi><mi>g</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi><mo>=</mo><mi>f</mi><mi>p</mi><mi>c</mi><mi>o</mi><mi>u</mi><mi>n</mi><mi>t</mi></math></p> |
| </dd> |
| <dt class="hdlist1">Description</dt> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1">EXP_CAST_UNNECESSARY</dt> |
| <dd> |
| <p><code>Unnecessary cast from <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> to <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>T</mi></math></code></p> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Remove cast</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Precondition</dt> |
| <dd> |
| <p>–</p> |
| </dd> |
| <dt class="hdlist1">Postcondition</dt> |
| <dd> |
| <p>cast removed</p> |
| </dd> |
| <dt class="hdlist1">Description</dt> |
| </dl> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Super_Keyword_Issues"><a class="anchor" href="#sec:Super_Keyword_Issues"></a><a class="link" href="#sec:Super_Keyword_Issues">3.2.2.10. Super Keyword Issues</a></h5> |
| |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Quick_Assist"><a class="anchor" href="#sec:Quick_Assist"></a><a class="link" href="#sec:Quick_Assist">3.3. Quick Assist</a></h3> |
| |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:Cleanup_Operations"><a class="anchor" href="#sec:Cleanup_Operations"></a><a class="link" href="#sec:Cleanup_Operations">3.4. Cleanup Operations</a></h3> |
| <div class="sect3"> |
| <h4 id="sec:Formatting"><a class="anchor" href="#sec:Formatting"></a><a class="link" href="#sec:Formatting">3.4.1. Formatting</a></h4> |
| |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Organize_Imports"><a class="anchor" href="#sec:Organize_Imports"></a><a class="link" href="#sec:Organize_Imports">3.4.2. Organize Imports</a></h4> |
| <div class="paragraph"> |
| <p>Import statements can be cleaned up or automatically inserted by invoking <code>Organize Imports</code>. <code>Organize Imports</code> is available in the context menu <code>Source / Organise imports</code> , in menu <code>Source > Organize imports</code> or by hitting <kbd>Cmd</kbd> + <kbd>Option</kbd> +<kbd>O</kbd> (Win/Linux - <kbd>Ctrl</kbd> +<kbd>Alt</kbd> +<kbd>O</kbd>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a valid file without errors, this will result in the following actions:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Unused explicit imports will be removed.</p> |
| </li> |
| <li> |
| <p>Unused wildcard imports will be removed.</p> |
| </li> |
| <li> |
| <p>In each import statement the imported elements will be lexicographically sorted depending on the imported element’s name.</p> |
| </li> |
| <li> |
| <p>All import statements will be lexicographically sorted depending on the module specifier as major and the element name as minor key.</p> |
| </li> |
| <li> |
| <p>All import statements will be moved to the top of the file.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For a file with error-conditions of unresolved references, this will result in the automatic actions:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All ambiguous wildcard imports will be presented in one dialog, requesting the user to resolve the ambiguity.</p> |
| </li> |
| <li> |
| <p>Each uniquely resolvable <code>unresolved Classifier</code> will be added by a named import. The search scope is limited to the dependencies declared in the current project-setup.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>No action will be taken, if …​</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>a classifier with name <code>X</code> is already imported by name from a module <code>A</code> and a unknown member of this classifier is marked. Even though the import of <code>X</code> from a different module <code>B</code> could remove this error, the semantic consequences could not be evaluated. The state will be left as-is.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If more then one option leads to a possible resolution the situation should be clarified using quick-fixes, e.g. if …​</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>more then one module provides an element, which would render a formerly unresolved reference to be valid.</p> |
| </li> |
| <li> |
| <p>for a wildcard-imported element <code>X</code> there are unknown members and a different module provides an element <code>X</code> containing the missing members. In such a case a named import of <code>X</code> would be proposed, optionally using an alias.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_wizards"><a class="anchor" href="#_wizards"></a><a class="link" href="#_wizards">4. Wizards</a></h2> |
| <div class="sectionbody"> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title=""></i> |
| </td> |
| <td class="content"> |
| Some descriptions may be outdated. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title=""></i> |
| </td> |
| <td class="content"> |
| All requirement sections are not linked to real issues. They were left here as an example and to complete the issues. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:N4JS_Project_Wizard"><a class="anchor" href="#sec:N4JS_Project_Wizard"></a><a class="link" href="#sec:N4JS_Project_Wizard">4.1. N4JS Project Wizard</a></h3> |
| <div class="paragraph"> |
| <p>Wizard creates a new N4JS project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following information is to be specified by the user:</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Project Name |
| </td> |
| <td class="hdlist2"> |
| <p>string, name of project</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Default Location |
| </td> |
| <td class="hdlist2"> |
| <p>boolean, true by default</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Location |
| </td> |
| <td class="hdlist2"> |
| <p>string, computed default location, if user set location then default location flag must be false</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Project Type |
| </td> |
| <td class="hdlist2"> |
| <p>enumeration, the type of the new project</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The following files are to be created:</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Project Folder |
| </td> |
| <td class="hdlist2"> |
| <p>with name of project at given location</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Manifest |
| </td> |
| <td class="hdlist2"> |
| <p>with default project structure and name</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Source Folder |
| </td> |
| <td class="hdlist2"> |
| <p>default source folder (src)</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Output Folder |
| </td> |
| <td class="hdlist2"> |
| <p>default source folder (src-gen)</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Empty_N4JS_File"><a class="anchor" href="#sec:Empty_N4JS_File"></a><a class="link" href="#sec:Empty_N4JS_File">4.2. Empty N4JS File</a></h3> |
| <div class="paragraph"> |
| <p>The following information is to be specified by the user:</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Package Name |
| </td> |
| <td class="hdlist2"> |
| <p>dot separated name of the package, empty by default (or set to the package/folder selected in the navigator)</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Module Name |
| </td> |
| <td class="hdlist2"> |
| <p>string, name of the module – must be a valid module name without extension</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The following files are to be created:</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Package Folder(s) |
| </td> |
| <td class="hdlist2"> |
| <p>if folders representing package structure do not exist, they are to be created</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Module File |
| </td> |
| <td class="hdlist2"> |
| <p>empty file with name of module and extension <code>n4js</code> in the appropriate package folder</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Empty_JS_File"><a class="anchor" href="#sec:Empty_JS_File"></a><a class="link" href="#sec:Empty_JS_File">4.3. Empty JS File</a></h3> |
| <div class="paragraph"> |
| <p>Similar to <a href="#sec:Empty_N4JS_File">Empty N4JS File</a> but with the file extension <code>js</code>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:N4JS_Class_File_Wizard"><a class="anchor" href="#sec:N4JS_Class_File_Wizard"></a><a class="link" href="#sec:N4JS_Class_File_Wizard">4.3.1. N4JS Class Wizard</a></h4> |
| <div class="paragraph"> |
| <p>It is recommended to define a single classifier in a file, the name of the classifier should have the same name as the file. Based on that assumption, file wizards are provided for N4JS classes, interfaces and enumerations.</p> |
| </div> |
| <div class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/06_wizards/fig/newclasswizard.png" alt="newclasswizard"> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="field-properties"><a class="anchor" href="#field-properties"></a><a class="link" href="#field-properties">4.3.2. Field Properties</a></h4> |
| <div class="paragraph"> |
| <p><a id="Class_File_Wizard-Project_Field"></a> The New N4JS Class wizard offers following fields:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Project</dt> |
| <dd> |
| <p>Specifies the containing project.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413a"></a><strong>Req. GH-1413a:</strong> <a href="#Req-GH-1413a">Project constraints</a> (ver. 1)</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Constraints |
| </td> |
| <td class="hdlist2"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>It is a path of a valid project in the current workspace</p> |
| </li> |
| <li> |
| <p>This field must not be empty</p> |
| </li> |
| </ol> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413b"></a><strong>Req. GH-1413b:</strong> <a href="#Req-GH-1413b">Project browse button</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Browse Button</dt> |
| <dd> |
| <p>Browsing only allows the selection of projects in the current workspace. Project creation is not possible.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413c"></a><strong>Req. GH-1413c:</strong> <a href="#Req-GH-1413c">Project initial selection inference</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Initial selection</dt> |
| <dd> |
| <p>The project should be derived from the initial selection.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413d"></a><strong>Req. GH-1413d:</strong> <a href="#Req-GH-1413d">Project content assist</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Content Assist</dt> |
| <dd> |
| <p>Workspace projects</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div id="Class_File_Wizard-Source_Folder_Field" class="dlist"> |
| <dl> |
| <dt class="hdlist1">Source folder</dt> |
| <dd> |
| <p>Specifies the containing source folder.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413e"></a><strong>Req. GH-1413e:</strong> <a href="#Req-GH-1413e">Source folder constraints</a> (ver. 1)</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Constraints |
| </td> |
| <td class="hdlist2"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>The folder is listed as source folder in the project manifest</p> |
| </li> |
| <li> |
| <p>This field must not be empty.</p> |
| </li> |
| <li> |
| <p>The name is a valid path that means each segment of the path matches the following expression:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-ebnf" data-lang="ebnf">[a-zA-z_](([\\.][a-zA-z_0-9\\-])|[a-zA-z_0-9\\-])*</code></pre> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413f"></a><strong>Req. GH-1413f:</strong> <a href="#Req-GH-1413f">Source folder browse button</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Browse Button</dt> |
| <dd> |
| <p>Browsing only allows the selection of source folders in the selected project. The dialog should provide a list of all source folders of the selected project. This includes nested source folders. A list element is a relative path of a source folder in the project.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413g"></a><strong>Req. GH-1413g:</strong> <a href="#Req-GH-1413g">Source folder initial selection inference</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Initial selection</dt> |
| <dd> |
| <p>The source folder field should be derived from the initial selection</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413h"></a><strong>Req. GH-1413h:</strong> <a href="#Req-GH-1413h">Source folder content assist</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Content Assist</dt> |
| <dd> |
| <p>source folders defined by the project manifest</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div id="Class_File_Wizard-Module_Specifier_Field" class="dlist"> |
| <dl> |
| <dt class="hdlist1">Module specifier</dt> |
| <dd> |
| <p>Specifies the module specifier. May only specify a module container (a folder) but could also include module name. May also be an already existing module. Does not include the file extension.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413i"></a><strong>Req. GH-1413i:</strong> <a href="#Req-GH-1413i">Module specifier constraints</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>The specifier is a valid module specifier that is |
| - Segments are separated by the path separator |
| - No separator at the beginning or end</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413j"></a><strong>Req. GH-1413j:</strong> <a href="#Req-GH-1413j">Module specifier completion</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Manually inserting a specifier ending with a separator is valid. |
| It is then interpreted as base path for the full module specifier automatically completed by the class name. (cf. grey suffix)</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413k"></a><strong>Req. GH-1413k:</strong> <a href="#Req-GH-1413k">Module specifier grey suffix</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>A grey suffix should suggest the attached class name as module name if the specifier only specifies a base path.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413l"></a><strong>Req. GH-1413l:</strong> <a href="#Req-GH-1413l">Module specifier browse button</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Browsing only allows the selection of modules or module containers in the selected source folder. The browse dialog has to offer a module container creation functionality. In contrast to the other parts of the wizard, the creation of module containers in this dialog should be immediate and on file system level. This is important to comply with the conceptual model of eclipse and the operating system.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When inserting a non-existent path in the text input and opening the browse dialog, an additional dialog should ask the user whether he wants to create this structure on the file system. If he denies, the dialog shows the selection to the level it already exists on the file system.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413m"></a><strong>Req. GH-1413m:</strong> <a href="#Req-GH-1413m">Module specifier initial selection inference</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>The module specifier should be derived from the initial selection by using the container of the selection as initial module container</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413n"></a><strong>Req. GH-1413n:</strong> <a href="#Req-GH-1413n">Module specifier content assist</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Modules in the selected source folder</p> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph todo"> |
| <p>For now the spec doesn’t specify any constraints for module specifiers</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Class name</dt> |
| <dd> |
| <p>Specifies the class name.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413o"></a><strong>Req. GH-1413o:</strong> <a href="#Req-GH-1413o">Class name basic constraints</a> (ver. 1)</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Constraints |
| </td> |
| <td class="hdlist2"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>The name is a valid n4js class identifier Must not be empty</p> |
| </li> |
| <li> |
| <p>If the target module already exists no other type with the same identifier may exist in this module</p> |
| </li> |
| </ol> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413p"></a><strong>Req. GH-1413p:</strong> <a href="#Req-GH-1413p">Class name conflict validation</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the target module already exists no other type with the same identifier may exist in this module</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413q"></a><strong>Req. GH-1413q:</strong> <a href="#Req-GH-1413q">File type options</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Definition file (.n4jsd)</dt> |
| <dd> |
| <p>Specifies whether the class should be declared external. This option changes the file extension to <code>n4jsd</code></p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413r"></a><strong>Req. GH-1413r:</strong> <a href="#Req-GH-1413r">Access modifier constraints</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Specifies the access modifiers of the class. One of <code>public</code>, <code>project</code>, <strong>private</strong>. <code>@Internal</code> is an additionally selectable option.</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Constraints |
| </td> |
| <td class="hdlist2"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>One of the provided access modifiers has to be selected</p> |
| </li> |
| <li> |
| <p>The <code>@Internal</code> option is only selectable in case of <code>public</code> or <code>project</code></p> |
| </li> |
| </ol> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Other modifiers</dt> |
| <dd> |
| <p>Specifies other modifiers and annotations of the class. The non-exclusive options are <code>@Final</code> and <strong>@N4JS</strong></p> |
| </dd> |
| </dl> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413s"></a><strong>Req. GH-1413s:</strong> <a href="#Req-GH-1413s">Other modifiers constraints</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Constraints</dt> |
| <dd> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p><strong>@N4JS</strong> annotation is only enabled and selectable if the Definition File box is checked</p> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Super class</dt> |
| <dd> |
| <p>Specifies the super class</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413t"></a><strong>Req. GH-1413t:</strong> <a href="#Req-GH-1413t">Super class constraints</a> (ver. 1)</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Constraints |
| </td> |
| <td class="hdlist2"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>A valid absolute class specifier that is a module specifier and a class name separated by a dot.</p> |
| </li> |
| </ol> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413u"></a><strong>Req. GH-1413u:</strong> <a href="#Req-GH-1413u">Super class browse button</a> (ver. 1)</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Browse Button |
| </td> |
| <td class="hdlist2"> |
| <p>Browsing allows the selection of all classes in the current workspace with modifiable source and visible classes with unmodifiable sources.</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413v"></a><strong>Req. GH-1413v:</strong> <a href="#Req-GH-1413v">Super class content assist</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Content Assist</dt> |
| <dd> |
| <p>All classes matching mentioned criteria</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div id="Class_File_Wizard-Interfaces_Field" class="dlist"> |
| <dl> |
| <dt class="hdlist1">Interfaces</dt> |
| <dd> |
| <p>Specifies the implemented interfaces of the class</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413w"></a><strong>Req. GH-1413w:</strong> <a href="#Req-GH-1413w">Interfaces constraints</a> (ver. 1)</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>A valid absolute interface specifier that is a module specifier and an interface name separated by a dot.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413x"></a><strong>Req. GH-1413x:</strong> <a href="#Req-GH-1413x">Interfaces browsing</a> (ver. 1)</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Add Button</dt> |
| <dd> |
| <p>Browsing allows the selection of all interfaces in the current workspace with modifiable source and visible interfaces with unmodifiable sources.</p> |
| </dd> |
| <dt class="hdlist1">Remove Button</dt> |
| <dd> |
| <p>Removes the selected interface from the list. Disabled if nothing is selected.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413y"></a><strong>Req. GH-1413y:</strong> <a href="#Req-GH-1413y">Interfaces content assist</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Text input is available by clicking in empty space at the end of the list. Content Assist provides all interfaces matching mentioned criteria.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413z1"></a><strong>Req. GH-1413z1:</strong> <a href="#Req-GH-1413z1">Create method stubs</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Specifies if the wizard should generate method stubs for all abstract methods of the newly generated class. That are abstract super class methods or methods that need to be implemented by the class to conform to the selected interfaces.</p> |
| </div> |
| </div> |
| </div> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413z2"></a><strong>Req. GH-1413z2:</strong> <a href="#Req-GH-1413z2">Create method stub conflict detection</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the selected interfaces are impossible to implement (e.g. method name overlap with unrelated parameter types) this option needs to be disabled and a warning needs to be shown.</p> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph todo"> |
| <p>Shouldn’t this be a constraint of the selected interfaces? (Never generate invalid code)</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="visibility-issues-or-final-super-classes"><a class="anchor" href="#visibility-issues-or-final-super-classes"></a><a class="link" href="#visibility-issues-or-final-super-classes">4.3.3. Visibility issues or <code>@Final</code> super classes</a></h4> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413z3"></a><strong>Req. GH-1413z3:</strong> <a href="#Req-GH-1413z3">Visibility issue conflict solving</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>By allowing the user to select invisible interfaces and super classes or unextendable <code>@Final</code>-annotated super classes, accessability issues may come up. The goal is to never generate a file containing invalid code. To accomplish this, conflicts must get solved before the file is generated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The slight limitation of the selection of interfaces and classes to elements from modifiable sources (cf. <a href="#Req-GH-1413u">super class browse button</a>) allows to solve all possibly occurring visibility issues.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the modifications by finishing the wizard do imply changes different from insertions and creations, a compare view is to be shown, giving the user an overview of the needed changes before they’re applied.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="generation-1"><a class="anchor" href="#generation-1"></a><a class="link" href="#generation-1">4.3.4. Generation</a></h4> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413z4"></a><strong>Req. GH-1413z4:</strong> <a href="#Req-GH-1413z4">Wizard generation</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following changes are to be made by the wizard:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Create a new file containing the new class (optional)</p> |
| </li> |
| <li> |
| <p>Insert the new class into the specified module</p> |
| </li> |
| <li> |
| <p>Change the source module of the super class to fix possible visibility issues (optional)</p> |
| </li> |
| <li> |
| <p>Change the source module of the interfaces to fix possible visibility issues (optional)</p> |
| </li> |
| <li> |
| <p>Change the project manifest to add a new source folder (optional) or add new project dependencies (optional)</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="preview-1"><a class="anchor" href="#preview-1"></a><a class="link" href="#preview-1">4.3.5. Preview</a></h4> |
| <div class="openblock requirement"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="Req-GH-1413z5"></a><strong>Req. GH-1413z5:</strong> <a href="#Req-GH-1413z5">Generation preview</a> (ver. 1)</p> |
| </div> |
| <div class="paragraph"> |
| <p>On the right of the wizard form a preview window should be provided. It should preview the full path of the generated file and all code that is generated with the options of the wizard. Changes should be updated in realtime as the user is choosing different options.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:N4JS_Interface_Wizard"><a class="anchor" href="#sec:N4JS_Interface_Wizard"></a><a class="link" href="#sec:N4JS_Interface_Wizard">4.4. Interface Wizard</a></h3> |
| <div class="paragraph"> |
| <p>The N4JS interface wizards is strongly similar to the <a href="#sec:N4JS_Class_File_Wizard">N4JS Class Wizard</a>. The following paragraph is meant to state the differences and will strongly refer to the N4JS Class Wizard as a lot of properties stay the same.</p> |
| </div> |
| <div class="imageblock center"> |
| <div class="content"> |
| <img src="chapters/06_wizards/fig/newinterfacewizard.png" alt="newinterfacewizard"> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="field-properties-1"><a class="anchor" href="#field-properties-1"></a><a class="link" href="#field-properties-1">4.4.1. Field Properties</a></h4> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Project |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the containing project. |
| See <a href="#Class_File_Wizard-Project_Field">N4JS Class Wizard Project</a>.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Source Folder |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the containing source folder.<br> |
| See <a href="#Class_File_Wizard-Source_Folder_Field">N4JS Class Wizard Source Folder</a></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Module Specifier |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the containing source folder.<br> |
| See <a href="#Class_File_Wizard-Module_Specifier_Field">N4JS Class Wizard Module specifier</a></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Interface name |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the name of the interface<br></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Constraints</dt> |
| <dd> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>The name is a valid n4js interface identifier</p> |
| </li> |
| <li> |
| <p>Must not be empty</p> |
| </li> |
| <li> |
| <p>If the target module already exists, no other type with the same identifier may exist in this module</p> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Definition file (.n4jsd) |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies whether the interface should be declared external. This option changes the file extension to <code>n4jsd</code> .</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Access Modifiers |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the interface’s access modifiers</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#Req-GH-1413r">N4JS Class Wizard Modifier Field</a> except for the following point:</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Other than classes, interfaces must not be declared as <code>@Final</code>, therefore this option is removed.</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Interfaces</dt> |
| <dd> |
| <p>The interfaces the interface is implementing</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#Class_File_Wizard-Interfaces_Field">N4JS Class Wizard Interfaces field</a> except for the following point:</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Other than classes interfaces must not be declared as <code>@Final</code>, therefore this option is removed.</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Create method stubs</dt> |
| <dd> |
| <p>Specifies if the wizard should generate method stubs for all abstract methods of the newly generated class. That are abstract super interface methods or methods that need to be implemented by the interface to conform to the given interfaces.</p> |
| <div class="paragraph"> |
| <p>If the selected interfaces are impossible to implement (e.g. method name overlap with unrelated parameter types) this option needs to be disabled and a warning needs to be shown.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph todo"> |
| <p>Shouldn’t this be a constraint of the selected interfaces? (Never generate invalid code)</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="visibility-issues"><a class="anchor" href="#visibility-issues"></a><a class="link" href="#visibility-issues">4.4.2. Visibility Issues</a></h4> |
| <div class="paragraph"> |
| <p>As the user might select invisible interfaces, the wizard has to solve these visibility issues. See ** for details.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="import-naming-conflicts"><a class="anchor" href="#import-naming-conflicts"></a><a class="link" href="#import-naming-conflicts">4.4.3. Import naming conflicts</a></h4> |
| <div class="paragraph"> |
| <p>As the user may select identically named interfaces, the wizard has to solve these naming conflicts. See |
| <strong><a href="#Req-GH-1413z3">Class Wizard Visibility Issues</a></strong> for details.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="generation-2"><a class="anchor" href="#generation-2"></a><a class="link" href="#generation-2">4.4.4. Generation</a></h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Create a new file at the given module specifier location (optional)</p> |
| </li> |
| <li> |
| <p>Insert the new interface into the specified module</p> |
| </li> |
| <li> |
| <p>Change the source module of the super class to fix visibility issues (optional)</p> |
| </li> |
| <li> |
| <p>Change the source module of the interfaces to fix possible visibility issues (optional)</p> |
| </li> |
| <li> |
| <p>Change the project manifest to add a possibly new source folder (optional) or add new project dependencies (optional)</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="preview-2"><a class="anchor" href="#preview-2"></a><a class="link" href="#preview-2">4.4.5. Preview</a></h4> |
| <div class="paragraph"> |
| <p>The Interface Wizard should provided a preview. (See <a href="#sec:N4JS_Wizards:Wizard_Preview">Wizard Preview</a>)</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:N4JS_Enum_File_Wizard"><a class="anchor" href="#sec:N4JS_Enum_File_Wizard"></a><a class="link" href="#sec:N4JS_Enum_File_Wizard">4.5. Enum Wizard</a></h3> |
| <div class="paragraph"> |
| <p>The N4JS Enum File wizards provides the user a wizard to create enums. When speaking of enums in this context ordinary enums as specified in the N4JS Specification are meant.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="field-properties-2"><a class="anchor" href="#field-properties-2"></a><a class="link" href="#field-properties-2">4.5.1. Field Properties</a></h4> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Project |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the containing project.<br> |
| See <a href="#Class_File_Wizard-Project_Field">N4JS Class Wizard Project</a></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Source Folder |
| </td> |
| <td class="hdlist2"> |
| <p> Specifies the containing source folder.<br> |
| See <a href="#Class_File_Wizard-Source_Folder_Field">N4JS Class Wizard Source Folder</a></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Module Specifier |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the containing source folder. See <a href="#Class_File_Wizard-Module_Specifier_Field">N4JS Class Wizard Module specifier</a></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Enum name |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the name of the interface<br></p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Constraints</dt> |
| <dd> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>The name is a valid n4js enum identifier</p> |
| </li> |
| <li> |
| <p>Must not be empty</p> |
| </li> |
| <li> |
| <p>If the target module already exists, no other type with the same identifier may exist in this module</p> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Modifiers |
| </td> |
| <td class="hdlist2"> |
| <p>Specifies the interface’s access modifiers |
| + |
| Allows the user to select from following modifier options: <code>public</code>,<code>project</code>,<code>private</code>. The wizard automatically adds missing <code>export</code> if needed. |
| + |
| Furthermore the enum can be declared <code>@Internal</code> using a checkbox.</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph todo"> |
| <p>Should the enum wizard also provide functionality to create enum literals?</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="generation-3"><a class="anchor" href="#generation-3"></a><a class="link" href="#generation-3">4.5.2. Generation</a></h4> |
| <div class="paragraph"> |
| <p>The following changes are to be made by the wizard:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Create a new file containing the new enum (optional, only if module doesn’t exists yet )</p> |
| </li> |
| <li> |
| <p>Insert the new enum into the specified module</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="preview-3"><a class="anchor" href="#preview-3"></a><a class="link" href="#preview-3">4.5.3. Preview</a></h4> |
| <div class="paragraph"> |
| <p>The Enum Wizard should provided a preview. (See <a href="#sec:N4JS_Wizards:Wizard_Preview">Wizard Preview</a>)</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_execution-support"><a class="anchor" href="#_execution-support"></a><a class="link" href="#_execution-support">5. Execution Support</a></h2> |
| <div class="sectionbody"> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title=""></i> |
| </td> |
| <td class="content"> |
| Parts of this document may be outdated. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Non_UI_Execution"><a class="anchor" href="#sec:Non_UI_Execution"></a><a class="link" href="#sec:Non_UI_Execution">5.1. Non-UI Execution</a></h3> |
| <div class="sect3"> |
| <h4 id="sec:Non_UI_Debugging"><a class="anchor" href="#sec:Non_UI_Debugging"></a><a class="link" href="#sec:Non_UI_Debugging">5.1.1. Non-UI Debugging</a></h4> |
| <div class="paragraph"> |
| <p>not supported yet</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:UI_Execution"><a class="anchor" href="#sec:UI_Execution"></a><a class="link" href="#sec:UI_Execution">5.2. UI Execution</a></h3> |
| <div class="paragraph"> |
| <p>The N4JS IDE supports launching a file via a so called "runner". That is, a selected file is started as main |
| file with Node.js or Chrome, depending on the available runners.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title=""></i> |
| </td> |
| <td class="content"> |
| Chrome support not available yet. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>For testing, a file, package, or even a whole project can be executed with a "tester". In that case, instead of directly executing the selected resource with Node.js (or other runners), the "mangelhaft" framework is used to run the selected resource or all its content as tests. For test support in general, see next chapter.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Running or testing a resource is done via a launch configuration. This can be configured.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The node.js runner/tester allows for configuration of</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>the NODE_MODULE path. This can be adjusted if the automatically path is not suited.</p> |
| </li> |
| <li> |
| <p>other environment variables (simply as key=value pairs per line)</p> |
| </li> |
| <li> |
| <p>node.js options to be passed as arguments to node.js</p> |
| </li> |
| <li> |
| <p>the system loader to be used, this is "System.js" by default</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| Since in the JavaScript world these configurations are often used, it is cumbersome, particularly for tests, to define them for every single file. Thus the N4JS IDE copies the node.js settings found in a project launch configuration to a resource specific launch configuration.</p> |
| </div> |
| <div class="sidebarblock"> |
| <div class="content"> |
| <a href="https://github.com/eclipse/n4js/issues/716" class="gray" title="GitHub Issues"><span class="image"><img src="images/issue.svg" alt=""></span> #716</a> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_test-support"><a class="anchor" href="#_test-support"></a><a class="link" href="#_test-support">6. Test Support</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>N4IDE provides tests support by allowing different <em>TestRunner</em>s to extend it with test specific functionality. This allows to support specialized and very different from each other test requirements (e.g. nodejs based tests, browser based interactive ui tests, server integration tests).</p> |
| </div> |
| <div id="fig:test_support_diagram" class="imageblock"> |
| <div class="content"> |
| <img src="chapters/09_testsupport/fig/cd_testsupport.png" alt="cd testsupport"> |
| </div> |
| <div class="title">Figure 10. Test Support Diagram</div> |
| </div> |
| <div class="paragraph"> |
| <p>Explanation of the main components:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><em>User Project</em></dt> |
| <dd> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>a project with production code (e.g. <code>src</code> folder), and test code (e.g. test folder)</p> |
| </li> |
| <li> |
| <p>test code may contain special language features contributed by <em>Test Library</em></p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| <dt class="hdlist1"><em>N4IDE</em></dt> |
| <dd> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>manage user project, including all test related parts (e.g. support test related code, validate some test code constraints)</p> |
| </li> |
| <li> |
| <p>host runner, allow its UI contributions</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| <dt class="hdlist1"><em>Test Runner</em></dt> |
| <dd> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>contribute to N4IDE necessary elements (test results view, user test selection, test start/stop actions)</p> |
| </li> |
| <li> |
| <p>use N4IDE mechanisms to access user project test fragment (e.g. discover tests)</p> |
| </li> |
| <li> |
| <p>configure <em>Test Execution Environment</em></p> |
| </li> |
| <li> |
| <p>manage test runtime (e.g. start/stop execution environment)</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| <dt class="hdlist1"><em>Test Execution Environment</em></dt> |
| <dd> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>hosts (directly or indirectly) js engine in which tests are executed</p> |
| </li> |
| <li> |
| <p>executes test library logic</p> |
| </li> |
| <li> |
| <p>is responsible for some tests execution aspects (e.g. test isolation)</p> |
| </li> |
| <li> |
| <p>deals with some execution errors (e.g. no callback from async test, infinite loop in test)</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| <dt class="hdlist1"><em>Test Library</em></dt> |
| <dd> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>provides test api that user can use in his project</p> |
| </li> |
| <li> |
| <p>coordinates scheduling and test code execution (e.g. order of tests, execution of setups / teardowns)</p> |
| </li> |
| <li> |
| <p>creates test results</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>Below picture and listings depicts the components of the Test Runner in the IDE:</p> |
| </div> |
| <div id="fig:test_runner_components" class="imageblock" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/09_testsupport/fig/test_runner_components.png" alt="test runner components" width="75%"> |
| </div> |
| <div class="title">Figure 11. Test Runner Components</div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| <em>Test Delegate</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>After the test discovery it starts and stops the test session via the Test Facade.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>Test Facade</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Ensures that an embedded HTTP server is running to receive messages from the Test Execution Environment. Registers a test session into the IDE side via the Test Finite State Machine Registry and triggers the actual test running at Test Execution Environment.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>HTTP Server</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>HTTP server is listening for HTTP requests from the Test Execution Environment via its RESTful API.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>Resource Router Servlet</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>This servlet is deployed into the servlet container of the HTTP Server. The servlet percepts the HTTP requests from the Test Execution Environment and delegates the request body to the corresponding REST Endpoint Logic.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>REST Endpoint Logic</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Parses the HTTP request bodies, creates special events and sends them to all subscribers via the Test Event Bus.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>Test Event Bus</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>This component is used to asynchronously deliver messages between the main test runner components in a decoupled fashion.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>Test Finite State Machine Registry</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>This registry is used to cache test sessions represented as test trees and Test Finite State Machines. Percepts all messages initially sent by the Test Execution Environment and delegates them to the corresponding subscribers.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>Test Finite State Machine</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Ensures the lifecycle of a test session. Handles timeouts duo to possible communication errors between the HTTP server and the Test Execution Environment.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>Test Tree Registry</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Registry to handle the state of a test session. Responsible for updating a test tree associated with a test session with the received test results.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| <em>Test UI</em> |
| </td> |
| <td class="hdlist2"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>This UI component provides feedback about the running test session to the end-user.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2 language-n4js"> |
| <h3 id="sec:N4JS_Mangelhaft_support"><a class="anchor" href="#sec:N4JS_Mangelhaft_support"></a><a class="link" href="#sec:N4JS_Mangelhaft_support">6.1. N4JS Mangelhaft support</a></h3> |
| <div id="fig:xUnitSupportDesign" class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/09_testsupport/fig/xUnitSupportDesign.png" alt="xUnitSupportDesign" width="75%"> |
| </div> |
| <div class="title">Figure 12. xUnit Support Design</div> |
| </div> |
| <div class="paragraph"> |
| <p>In this section and subsections we specify N4IDE support for testing with Mangelhaft.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Mangelhaft is N4JS <em>Test Library</em>. It is focused more on a xUnit tests than other forms of testing (BDD, Acceptance Testing, Functional UI Testing).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following test scenarios are supported on different <em>Test Execution Environment</em>s:</p> |
| </div> |
| <table id="tab:Test_Scenarios" class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 2. Test Scenarios</caption> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-center valign-top">Test</th> |
| <th class="tableblock halign-center valign-top">Node</th> |
| <th class="tableblock halign-center valign-top">Browser</th> |
| <th class="tableblock halign-center valign-top">Wrapper</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Plain</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>yes</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>yes</code></p></td> |
| <td class="tableblock halign-center valign-top"></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">DOM</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>yes</code></p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">non-interactive UI</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-center valign-top"></td> |
| <td class="tableblock halign-center valign-top"></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">interactive UI (iUI)</p></th> |
| <td class="tableblock halign-center valign-top"></td> |
| <td class="tableblock halign-center valign-top"></td> |
| <td class="tableblock halign-center valign-top"></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">(non UI) Server</p></th> |
| <td class="tableblock halign-center valign-top"></td> |
| <td class="tableblock halign-center valign-top"></td> |
| <td class="tableblock halign-center valign-top"></td> |
| </tr> |
| <tr> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">iUI Server</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>-</code></p></td> |
| <td class="tableblock halign-center valign-top"></td> |
| <td class="tableblock halign-center valign-top"></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="sect3"> |
| <h4 id="sec:Asynchronous_Tests"><a class="anchor" href="#sec:Asynchronous_Tests"></a><a class="link" href="#sec:Asynchronous_Tests">6.1.1. Asynchronous Tests, Test Isolation and Timeouts</a></h4> |
| <div class="paragraph"> |
| <p>A special problem about JavaScript tests is to control asynchronous tests and non-terminating tests.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Performance and test isolation are conflicting goals: a perfect isolation would mean to run every tests by a separate JavaScript engine, which is not performant. For that reason, all tests are run by the same JS-engine in general. A test has to notify the test runner when it has been finished (successfully or with failure). If it does not finish in a defined time (timeout), <em>Test Execution Environment</em> or <em>Manglehaft</em> needs to handle that (e.g. restart node vm in which code is executed)…​</p> |
| </div> |
| <div class="paragraph"> |
| <p>Main concerns with running test in parallel on js side are:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Timeouts Mangelhaft is supposed to track test timeout. If tests are running in fake parallel mode achieved by cooperative multitasking, then one test running eats up time for other test. This can cause tests to timeout when running in parallel, while succeed when running in sequential mode.</p> |
| </li> |
| <li> |
| <p>Mutability on client. Tests running in parallel can affect each other by mutating global state in which they operate. When they run in sequential mode this can happen too, but it is much less likely to.</p> |
| </li> |
| <li> |
| <p>Mutable state on the server. Tests running on the same session/login are prone to affecting each other through server interaction (and or mutating data on the server).</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Supported_xUnit_API"><a class="anchor" href="#sec:Supported_xUnit_API"></a><a class="link" href="#sec:Supported_xUnit_API">6.1.2. Supported xUnit API</a></h4> |
| <div class="paragraph"> |
| <p>xUnit API is user facing API for defining tests. It allows test developer to define tests and configure some test execution aspects. N4IDE (via <em>Test Runner</em> extension) supports defined API by :</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>gathering information via AST analysis and reflection</p> |
| </li> |
| <li> |
| <p>presenting user available actions, based on gathered information</p> |
| </li> |
| <li> |
| <p>gathering user input and configurations for test execution</p> |
| </li> |
| <li> |
| <p>generating proper data for test infrastructure, based on user actions</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Test_Group"><a class="anchor" href="#sec:Test_Group"></a><a class="link" href="#sec:Test_Group">6.1.2.1. Test Group</a></h5> |
| <div class="paragraph"> |
| <p>A test group is a logical collection of tests. It is created by grouping <code>N4ClassDeclarations</code> that contain test methods or test methods directly (see <a href="#sec:Test_Method">Test Method</a>). Those classes or individual methods can be assigned to a <em>Group</em> by annotating them with <code>@Group</code> annotation. This annotation takes non empty list of strings as parameter. Passed strings are used as category name (which is like its id).</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xtext" data-lang="xtext">Annotation: |
| '@Group' |
| (' $group+=$STRING ')? |
| AnnotatedElement |
| ; |
| |
| AnnnotatedElement: |
| N4JSClassDeclaration | N4JSMethodDeclaration |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>@Group</code> properties</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>name → <code>Group</code></p> |
| </li> |
| <li> |
| <p>targets → N4Method, N4Class</p> |
| </li> |
| <li> |
| <p>retention policy → RUNTIME</p> |
| </li> |
| <li> |
| <p>transitive → YES</p> |
| </li> |
| <li> |
| <p>repeatable → YES</p> |
| </li> |
| <li> |
| <p>arguments → <em>String</em>s</p> |
| </li> |
| <li> |
| <p>arguments are optional → NO</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Test_Method"><a class="anchor" href="#sec:Test_Method"></a><a class="link" href="#sec:Test_Method">6.1.2.2. Test Method</a></h5> |
| <div class="paragraph"> |
| <p><em>Test Method</em> marks procedure that has to be executed by <em>Test Library</em>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xtext" data-lang="xtext">Annotation: |
| '@Test' |
| AnnotatedElement |
| ; |
| |
| AnnnotatedElement: |
| N4JSMethodDeclaration |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>@Test</code> properties</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>name → <code>Test</code></p> |
| </li> |
| <li> |
| <p>targets → N4Method</p> |
| </li> |
| <li> |
| <p>retention policy → RUNTIME</p> |
| </li> |
| <li> |
| <p>transitive → NO</p> |
| </li> |
| <li> |
| <p>repeatable → NO</p> |
| </li> |
| <li> |
| <p>arguments → none</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Additional <em>TestMethod</em> constraints:</p> |
| </div> |
| <div class="paragraph"> |
| <p>Test Method <a id="cnst:Test_Method"></a></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>allowed only <code>N4ClassDeclarations</code> in project test fragment</p> |
| </li> |
| <li> |
| <p>method must be public</p> |
| </li> |
| <li> |
| <p>method takes no parameters</p> |
| </li> |
| <li> |
| <p>method return type is <code>Promise?</code></p> |
| </li> |
| <li> |
| <p>method must not be referenced by other owning class members or other classes (also no <em>@override</em>)</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:BeforeAll"><a class="anchor" href="#sec:BeforeAll"></a><a class="link" href="#sec:BeforeAll">6.1.2.3. BeforeAll Setup</a></h5> |
| <div class="paragraph"> |
| <p><code>@BeforeAll</code> marks method that will be executed once before <strong>all</strong> tests in a given test class will be executed.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xtext" data-lang="xtext">Annotation: |
| '@BeforeAll' |
| AnnotatedElement |
| ; |
| |
| AnnnotatedElement: |
| N4JSMethodDeclaration |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>@BeforeAll</code> properties</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>name → <code>BeforeAll</code></p> |
| </li> |
| <li> |
| <p>targets → N4Method</p> |
| </li> |
| <li> |
| <p>retention policy → RUNTIME</p> |
| </li> |
| <li> |
| <p>transitive → NO</p> |
| </li> |
| <li> |
| <p>repeatable → NO</p> |
| </li> |
| <li> |
| <p>arguments → none</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The same constraints apply as for the test method, see <a href="#cnst:Test_Method">Test Method Constraints</a>.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Before_Setup"><a class="anchor" href="#sec:Before_Setup"></a><a class="link" href="#sec:Before_Setup">6.1.2.4. Before Setup</a></h5> |
| <div class="paragraph"> |
| <p><code>@Before</code> marks method that will be executed once before <strong>each</strong> tests in a given test class will be executed.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xtext" data-lang="xtext">Annotation: |
| '@Before' |
| AnnotatedElement |
| ; |
| |
| AnnnotatedElement: |
| N4JSMethodDeclaration |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>@Before</code> properties</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>name → <code>Before</code></p> |
| </li> |
| <li> |
| <p>targets → N4Method</p> |
| </li> |
| <li> |
| <p>retention policy → RUNTIME</p> |
| </li> |
| <li> |
| <p>transitive → NO</p> |
| </li> |
| <li> |
| <p>repeatable → NO</p> |
| </li> |
| <li> |
| <p>arguments → none</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The same constraints apply as for the test method, see <a href="#cnst:Test_Method">Test Method Constraints</a>.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:After_Teardown"><a class="anchor" href="#sec:After_Teardown"></a><a class="link" href="#sec:After_Teardown">6.1.2.5. After Teardown</a></h5> |
| <div class="paragraph"> |
| <p><code>@After</code> marks method that will be executed once after <strong>each</strong> tests in a given test class will be executed.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xtext" data-lang="xtext">Annotation: |
| '@After' |
| AnnotatedElement |
| ; |
| |
| AnnnotatedElement: |
| N4JSMethodDeclaration |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>@After</code> properties</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>name → <code>After</code></p> |
| </li> |
| <li> |
| <p>targets → N4Method</p> |
| </li> |
| <li> |
| <p>retention policy → RUNTIME</p> |
| </li> |
| <li> |
| <p>transitive → NO</p> |
| </li> |
| <li> |
| <p>repeatable → NO</p> |
| </li> |
| <li> |
| <p>arguments → none</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The same constraints apply as for the test method, see <a href="#cnst:Test_Method">Test Method Constraints</a>.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:AfterAll_Teardown"><a class="anchor" href="#sec:AfterAll_Teardown"></a><a class="link" href="#sec:AfterAll_Teardown">6.1.2.6. AfterAll Teardown</a></h5> |
| <div class="paragraph"> |
| <p><code>@AfterAll</code> marks method that will be executed once after <strong>all</strong> tests in a given test class will be executed.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xtext" data-lang="xtext">Annotation: |
| '@After' |
| AnnotatedElement |
| ; |
| |
| AnnnotatedElement: |
| N4JSMethodDeclaration |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="ulist Test Fixture][cnst:Test_Fixture"> |
| <ul class="Test Fixture][cnst:Test_Fixture"> |
| <li> |
| <p>allowed only in class marked with <em>@TestClass</em></p> |
| </li> |
| <li> |
| <p>method must be public</p> |
| </li> |
| <li> |
| <p>method takes no parameters</p> |
| </li> |
| <li> |
| <p>method return type is <code>void</code></p> |
| </li> |
| <li> |
| <p>method must not be referenced by other owning class members</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><code>@AfterAll</code> properties</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>name → <code>AfterAll</code></p> |
| </li> |
| <li> |
| <p>targets → N4Method</p> |
| </li> |
| <li> |
| <p>retention policy → RUNTIME</p> |
| </li> |
| <li> |
| <p>transitive → NO</p> |
| </li> |
| <li> |
| <p>repeatable → NO</p> |
| </li> |
| <li> |
| <p>arguments → none</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The same constraints apply as for the test method, see <a href="#cnst:Test_Method">Test Method Constraints</a>.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Test_Ignore"><a class="anchor" href="#sec:Test_Ignore"></a><a class="link" href="#sec:Test_Ignore">6.1.2.7. Test Ignore</a></h5> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| name |
| </td> |
| <td class="hdlist2"> |
| <p>@Ignore</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| targets |
| </td> |
| <td class="hdlist2"> |
| <p>N4Method, N4Class</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| retention policy |
| </td> |
| <td class="hdlist2"> |
| <p>RUNTIME</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| transitive |
| </td> |
| <td class="hdlist2"> |
| <p>YES</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| repeatable |
| </td> |
| <td class="hdlist2"> |
| <p>NO</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| arguments |
| </td> |
| <td class="hdlist2"> |
| <p>String reason</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| arguments are optional |
| </td> |
| <td class="hdlist2"> |
| <p>→ Yes</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><em>Test Ignore</em> allows to mark tests that should be skipped during the test execution. That is the preferred way to temporarily disable tests without removing them (or commenting them out). Test developers may provide reason for skipping to make reason/intentions clearer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This annotation is <em>transitive</em>, which means that: <em>Test Method</em> is considered as marked with <em>Test Skip</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>explicitly when it is directly marked or</p> |
| </li> |
| <li> |
| <p>implicitly, when container of a <em>Test Method</em> is marked.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If a class is marked as <code>@Ignore</code>, then all its contained test methods will be ignored.<br> |
| When <code>@Ignore</code> occurs at class level in a test class hierarchy chain, then the following rules are applied. Assume the following test classes:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">export public class A { |
| |
| @Test |
| public aTest(): void { |
| console.log('A#aTest'); |
| } |
| |
| }</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">import { A } from "A" |
| |
| @Ignore('Class B is ignored.') |
| export public class B extends A { |
| |
| @Test |
| public b1Test(): void { |
| console.log('B#b1Test'); |
| } |
| |
| @Ignore("Method B#b2Test is ignored.") |
| @Test |
| public b2Test(): void { |
| console.log("B#b2Test"); |
| } |
| |
| }</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">import { B } from "B" |
| |
| export public class C extends B { |
| |
| @Test |
| public cTest(): void { |
| console.log('C#cTest'); |
| } |
| |
| }</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>When module <em>A</em> is being tested, then it is obvious that all the test methods of <code>A</code> will be tested. No methods will be skipped at all.</p> |
| </li> |
| <li> |
| <p>When module <em>B</em> is being tested, then although the inherited members of class <code>A</code> will be included in the test tree, all methods, including the inherited ones (from class <code>A</code> from module <em>A</em>) will be skipped. Nothing will be tested.</p> |
| </li> |
| <li> |
| <p>When module <em>C</em> is being tested, then all inherited members from class <code>B</code> and class <code>A</code> will be collected an included in the test tree. The <code>@Ignore</code> annotation declared at class level at <code>B</code> will be ignored but the <code>@Ignore</code> at method level in class <code>B</code> will be considered. In a nutshell, the following methods will be executed:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>A#aTest</code></p> |
| </li> |
| <li> |
| <p><code>B#b1Test</code></p> |
| </li> |
| <li> |
| <p><code>C#cTest</code></p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The above described behavior is identical to the behavior of <em>JUnit 4</em> with respect to the <code>@Ignore</code> annotation handling in case of test class inheritance.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Timeout"><a class="anchor" href="#sec:Timeout"></a><a class="link" href="#sec:Timeout">6.1.2.8. Timeout</a></h5> |
| <div class="paragraph"> |
| <p><em>Timeout</em> allows test developer to set custom timeout when executing given test code. This can be used to set timeout for both <em>Test Method</em>s or <em>Test Fixtures</em></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xtext" data-lang="xtext">Annotation: |
| '@Timeout' |
| ($timoeout+=$INT)? |
| AnnotatedElement |
| ; |
| |
| AnnnotatedElement: |
| N4JSClassDeclaration | N4JSMethodDeclaration |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>@Timeout</code> properties</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>name → <code>Timeout</code></p> |
| </li> |
| <li> |
| <p>targets → N4Method, N4Class</p> |
| </li> |
| <li> |
| <p>retention policy → RUNTIME</p> |
| </li> |
| <li> |
| <p>transitive → YES</p> |
| </li> |
| <li> |
| <p>repeatable → NO</p> |
| </li> |
| <li> |
| <p>arguments → Number</p> |
| </li> |
| <li> |
| <p>arguments are optional → NO</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Description"><a class="anchor" href="#sec:Description"></a><a class="link" href="#sec:Description">6.1.2.9. Description</a></h5> |
| <div class="paragraph"> |
| <p><em>Description</em> allows test developer provide string describing given test or test class that <em>can</em> be used in IDE test view or in the test report.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xtext" data-lang="xtext">Annotation: |
| '@Description' |
| ($desc+=$STRING)? |
| AnnotatedElement |
| ; |
| |
| AnnnotatedElement: |
| N4JSClassDeclaration | N4JSMethodDeclaration |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>@Description</code> properties</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>name → <code>Description</code></p> |
| </li> |
| <li> |
| <p>targets → N4Method, N4Class</p> |
| </li> |
| <li> |
| <p>retention policy → RUNTIME</p> |
| </li> |
| <li> |
| <p>transitive → YES</p> |
| </li> |
| <li> |
| <p>arguments → String</p> |
| </li> |
| <li> |
| <p>arguments are optional → NO</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Test_Reporting"><a class="anchor" href="#sec:Test_Reporting"></a><a class="link" href="#sec:Test_Reporting">6.2. Test Reporting</a></h3> |
| <div class="paragraph"> |
| <p><em>Test Runtime Environment</em> communicates with <em>Test Runner</em> over HTTP. Defined communication is based on protocol used between lupenrein and old ide. It is used to send the information about test execution progress from the <em>Test Runtime</em> to <em>Test Runner</em>. Information send by this protocol is not equivalent to test results. <em>Test Runner</em> interprets progress it receives and based on gathered information it generates test results. Under specific conditions <em>Test Runner</em> may change reported test status PASS to test result FAILED and put this information to the test report e.g. when timeout happens (see note on timeouts below).</p> |
| </div> |
| <div id="fig:sm_TestListener" class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/09_testsupport/fig/sm_TestListener.png" alt="sm TestListener" width="25%"> |
| </div> |
| <div class="title">Figure 13. TestListener</div> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#fig:sm_TestListener">Test Listener</a> shows Communication flow expected by the <em>Test Runner</em>. When the <em>Test Runner</em> is started first it waits for <em>Start Session</em> message. Next <em>Test Tree</em> message is expected. This describes list of all tests that are expected to be executed. For all tests in the list <em>Test Runner</em> expects <em>Test Start</em> and <em>Test End</em> message to be received. <em>End Session</em> is expected to be last message in the test session. <em>Ping</em> message can be send multiple times in between other messages to manage synchronization issues between <em>Test Runner</em> and <em>Test Runtime</em> (see below).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Since all communication is asynchronous, IDE <em>Test Runner</em> must assume some timeout values that will define standard wait time during communication:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Initial 90s timeout to wait for the <em>Start Session</em> message. It may be fixed or adjusted to given environment (local/remote) and project (library/application).</p> |
| </li> |
| <li> |
| <p>Default timeout between all other test messages is 10 seconds. <em>Test Runtime</em> may notify IDE <em>Test Runner</em> that it should wait longer with <em>Ping</em> <em>test message</em>. This is one time thing, as soon as another command is received the default timeout will have to be reused again.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Do to the asynchronous nature of the tests, status updates can be given out of order by the Test Runtime Environment. The only sure thing is that all tests begin with <em>SessionStart</em> and ends with a <em>SessionEnd</em>. Furthermore a <em>TestStart</em> will be send before the <em>TestEnd</em> for a particular test.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Test_Messages"><a class="anchor" href="#sec:Test_Messages"></a><a class="link" href="#sec:Test_Messages">6.2.1. Test Messages</a></h4> |
| <div class="paragraph"> |
| <p>IDE <em>Test Runner</em> will be waiting for specific messages from <em>Test Runtime</em>. We assume that communication will be done over HTTP protocol. <em>Test Execution Environement</em> should be configured by the <em>Test Runner</em> in a way that <em>Test Runtime</em> knows address where it has to send messages (see |
| <a href="#sec:Test_Runtime_Configuration">Test Runtime Configuration</a>). <em>Test Runner</em> exposes RESTful API allowing him to receive messages. Below we define parts of that api that enable specific messages to be communicated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When defining <em>Test Message</em>s we assume following model of tests:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">TestTree { |
| ID sessionId, |
| Array<TestSuite>? testSuites |
| } |
| |
| TestSuite { |
| string name, |
| Array<TestCase>? testCases, |
| Array<TestSuite>? children |
| } |
| |
| TestCase { |
| ID id, |
| string className, |
| string origin, |
| string name, |
| string displayName, |
| TestResult? result |
| } |
| |
| TestResult { |
| TestStatus teststatus, |
| number elapsed, |
| string? expected, |
| string? actual, |
| string? message, |
| array<string>? trace |
| } |
| |
| enum TestStatus { |
| PASSED, SKIPPED, FAILED, ERROR |
| } |
| |
| ID { |
| string value |
| }</code></pre> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="_test-case-ids"><a class="anchor" href="#_test-case-ids"></a><a class="link" href="#_test-case-ids">6.2.1.1. Test Case IDs</a></h5> |
| <div class="paragraph"> |
| <p>The ID of a test case in the following specifications is referred to as <code>testID</code>. |
| This ID is of the following structure:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>testID: fqn '#' methodName</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When used as part of the URL the testID is percent-escaped as defined in <a href="https://tools.ietf.org/html/rfc3986#section-2.1">RFC3986 Section 2.1</a>. This is necessarry to circumvent the fact that the N4JS FQN delimiter <code>/</code> is a reserved character in URLs and cannot be used in its original form.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Start_Session"><a class="anchor" href="#sec:Start_Session"></a><a class="link" href="#sec:Start_Session">6.2.1.2. Start Session</a></h5> |
| <div class="paragraph"> |
| <p>Signals start of the test session. When user triggers test execution, configures <em>IDETestRunnerCtrl</em>, afterwards IDE <em>Listener</em> waits for this message from <em>TestRunner</em>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">StartSession : |
| uri : /n4js/testing/sessions/{sessionID}/start |
| method : POST |
| contentType : application/vnd.n4js.start_session_req.tm+json |
| accept: application/json |
| responses: |
| 200: |
| 400:</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Start session request object MIME type <em>application/vnd.n4js.start_session_req.tm+json</em>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">{ |
| map<string, string>? properties |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Ping_Session"><a class="anchor" href="#sec:Ping_Session"></a><a class="link" href="#sec:Ping_Session">6.2.1.3. Ping Session</a></h5> |
| <div class="paragraph"> |
| <p>Signals that test runner is still busy doing things, and will report later to the listener.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">PingSession : |
| uri : /n4js/testing/sessions/{sessionID}/ping |
| method : POST |
| contentType : application/vnd.n4js.ping_session_req.tm+json |
| accept: application/json |
| responses: |
| 200: |
| 400:</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Ping session request object MIME type <em>application/vnd.n4js.ping_session_req.tm+json</em>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">{ |
| number timeout, |
| string? comment |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:End_Session"><a class="anchor" href="#sec:End_Session"></a><a class="link" href="#sec:End_Session">6.2.1.4. End Session</a></h5> |
| <div class="paragraph"> |
| <p>Signals end of test session Notifies IDE <em>Listener</em> that session is finished and no further related <em>TestMessage</em>s are expected. IDE, can stop listening and proceed with its own tasks (e.g. create summary test report ).</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">EndSession : |
| uri : /n4js/testing/sessions/{sessionID}/end |
| method : POST |
| responses: |
| 200: |
| 400:</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Start_Test"><a class="anchor" href="#sec:Start_Test"></a><a class="link" href="#sec:Start_Test">6.2.1.5. Start Test</a></h5> |
| <div class="paragraph"> |
| <p>Signals that a test run has started. Updates the state of the test reported with the <em>tree</em> .</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">StartTest : |
| uri : /n4js/testing/sessions/{sessionID}/tests/{testID}/start |
| method : POST |
| contentType : application/vnd.n4js.start_test_req.tm+json |
| accept: application/json |
| responses: |
| 200: |
| contentType : application/vnd.n4js.start_test_res.tm+json |
| 400:</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Start test request object MIME type <em>application/vnd.n4js.start_test_req.tm+json</em>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">{ |
| number timeout, |
| map<string, string>? properties |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Start test response object MIME type <em>application/vnd.n4js.start_test_res.tm+json</em>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">{ |
| links : [ |
| { |
| rel: "ping test", |
| uri: "/n4js/testing/sessions/{sessionID}/tests/{testID}/ping" |
| }, |
| { |
| rel: "end test", |
| uri: "/n4js/testing/sessions/{sessionID}/tests/{testID}/end" |
| } |
| ] |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:End_Test"><a class="anchor" href="#sec:End_Test"></a><a class="link" href="#sec:End_Test">6.2.1.6. End Test</a></h5> |
| <div class="paragraph"> |
| <p>Signals that a test run has ended. Updates the state of the test reported with the <em>tree</em> .</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">EndTest : |
| uri : /n4js/testing/sessions/{sessionID}/tests/{testID}/end |
| method : POST |
| contentType : application/vnd.n4js.end_test_req.tm+json |
| accept: application/json |
| responses: |
| 200: |
| 400:</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>End test request object MIME type <em>application/vnd.n4js.end_test_req.tm+json</em>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">{ |
| TestResult result |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Ping_Test"><a class="anchor" href="#sec:Ping_Test"></a><a class="link" href="#sec:Ping_Test">6.2.1.7. Ping Test</a></h5> |
| <div class="paragraph"> |
| <p>Notifies IDE that <em>TestRunner</em> is doing something (e.g. test setup/teardown code, long running test). Without this notification IDE might interpret long pause in received messages as timeout, <em>TestRunner</em> crash or other issues (in consequence it might terminate whole test execution environment).</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">PingTest : |
| uri : /n4js/testing/sessions/{sessionID}/tests/{testID}/ping |
| method : POST |
| contentType : application/vnd.n4js.ping_test_req.tm+json |
| accept: application/json |
| responses: |
| 200: |
| 400:</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Ping test request object MIME type <em>application/vnd.n4js.ping_test_req.tm+json</em>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">{ |
| number timeout, |
| string? comment |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Test_Catalog"><a class="anchor" href="#sec:Test_Catalog"></a><a class="link" href="#sec:Test_Catalog">6.2.1.8. Test Catalog</a></h5> |
| <div class="paragraph"> |
| <p>Assembles and returns with the test catalog representing all the tests available in the underlying <em>IN4JSCore</em> specific workspace. The content of the test catalog is calculated dynamically. The test catalog calculation depends on the current built state of the workspace. If the workspace was cleaned and not built yet, then a test catalog containing zero test suites (and test cases) will be provided as a response. If the workspace is built and in consistent state, then a catalog containing all test cases will be sent as the response body. The provided test catalog format complies to the Mangelhaft reporters.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">TestCatalog : |
| uri : /n4js/testing/sessions/testcatalog |
| method : GET |
| contentType : application/vnd.n4js.assemble_test_catalog_req.tm+json |
| accept: application/json |
| responses: |
| 200: |
| 400:</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Below listings represents an example of the test catalog format:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">{ |
| "endpoint": "http://localhost:9415", |
| "sessionId": "fc3a425c-b675-47d7-8602-8877111cf909", |
| "testDescriptors": [ |
| { |
| "origin": "SysProjectA-0.0.1", |
| "fqn": "T/T", |
| "testMethods": [ |
| "t" |
| ] |
| }, |
| { |
| "origin": "TestProjectA-0.0.1", |
| "fqn": "A/A", |
| "testMethods": [ |
| "a" |
| ] |
| }, |
| { |
| "origin": "TestProjectA-0.0.1", |
| "fqn": "B/B", |
| "testMethods": [ |
| "b1", |
| "b2" |
| ] |
| }, |
| { |
| "origin": "TestProjectB-0.0.1", |
| "fqn": "CSub1/CSub1", |
| "testMethods": [ |
| "c1", |
| "c2" |
| ] |
| }, |
| { |
| "origin": "TestProjectB-0.0.1", |
| "fqn": "CSub2/CSub2", |
| "testMethods": [ |
| "c1", |
| "c2", |
| "c3" |
| ] |
| } |
| ] |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:Test_Session_Example"><a class="anchor" href="#sec:Test_Session_Example"></a><a class="link" href="#sec:Test_Session_Example">6.2.1.9. Test Session Example</a></h5> |
| <div class="paragraph"> |
| <p>Below example demonstrates what are the expected HTTP requests and JSON structures for a simple test group.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">class A { |
| |
| @Test |
| public void foo() {} |
| |
| @Test |
| @Ignore |
| public void bar() {} |
| } |
| |
| class B { |
| |
| @Test |
| public void baz() {} |
| } |
| |
| class C { |
| |
| @Test |
| public void qux() {} |
| }</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/start/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.start_session_req.tm+json; charset=ISO-8859-1</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FC%23qux/start/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.start_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "timeout": 1000 |
| } |
| |
| |
| Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FB%23baz/start/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.start_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "timeout": 1000 |
| } |
| |
| |
| Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FA%23bar/start/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.start_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "timeout": 1000 |
| } |
| |
| |
| Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FA%23foo/start/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.start_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "timeout": 1000 |
| }</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FA%23bar/ping |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.ping_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "timeout": 1000 |
| } |
| |
| |
| Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FC%23qux/ping/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.ping_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "timeout": 2000 |
| }</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FB%23baz/end/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.end_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "message": "Some optional message.", |
| "trace": [ |
| "trace_element_1", |
| "trace_element_2", |
| "trace_element_3" |
| ], |
| "expected": "1", |
| "testStatus": "FAILED", |
| "elapsedTime": 100, |
| "actual": "2" |
| } |
| |
| |
| Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FC%23qux/end/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.end_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "message": "Some failure message.", |
| "trace": [ |
| "trace_element_1", |
| "trace_element_2", |
| "trace_element_3" |
| ], |
| "expected": "4", |
| "testStatus": "FAILED", |
| "elapsedTime": 50, |
| "actual": "3" |
| } |
| |
| |
| Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2F%23foo/end/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.end_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "expected": "2", |
| "testStatus": "PASSED", |
| "elapsedTime": 60, |
| "actual": "power of 2 for 2" |
| } |
| |
| |
| Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/tests/Test%2FA%23bar/end/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.end_test_req.tm+json; charset=ISO-8859-1 |
| Body: |
| { |
| "testStatus": "SKIPPED", |
| "elapsedTime": 0, |
| }</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">Request method: POST |
| Request path: http://localhost:9415/n4js/testing/sessions/19f47a37-c1d1-4cb7-a514-1e131f26ab13/end/ |
| Headers: Accept=*/* |
| Content-Type=application/vnd.n4js.end_session_req.tm+json; charset=ISO-8859-1</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Test_Runtime_Configuration"><a class="anchor" href="#sec:Test_Runtime_Configuration"></a><a class="link" href="#sec:Test_Runtime_Configuration">6.2.2. Test Runtime Configuration</a></h4> |
| <div class="paragraph"> |
| <p><em>Test Runner</em> must gather relevant information and send it to <em>Test Environment</em> to allow proper test execution:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>gathering user input and test options</p> |
| </li> |
| <li> |
| <p>gathering information about user project test code</p> |
| </li> |
| <li> |
| <p>maintaining proper name mappings (e.g. if project is minimized test names/references must be mapped correctly)</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Test_Plan"><a class="anchor" href="#sec:Test_Plan"></a><a class="link" href="#sec:Test_Plan">6.2.3. Test Plan</a></h4> |
| <div class="paragraph"> |
| <p><em>Test Runner</em> uses N4IDE infrastructure to obtain information about test fragment of the user project. Based on that information and user input in UI (e.g. triggering test execution on whole project) IDE can determine <em>Test Method</em>s that should be executed. Such test list or <em>Test Plan</em> is send to <em>Test Environment</em> and is expected to be executed by a <em>Test Library</em>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">TestPlan { |
| Array<TestProcedure> procedures |
| } |
| |
| TestProcedure { |
| string functionName, |
| string functionType, |
| string functionContainer, |
| string containerModule |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Test_Environment_Configuration"><a class="anchor" href="#sec:Test_Environment_Configuration"></a><a class="link" href="#sec:Test_Environment_Configuration">6.2.4. Test Environment Configuration</a></h4> |
| <div class="paragraph"> |
| <p>Additionally <em>Test Runner</em> sends to <em>Test Environment</em> other configuration options:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>Test Runner</em> test communication protocol base url (<em>baseURL</em>)</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Test_Environment_Configuration_Example"><a class="anchor" href="#sec:Test_Environment_Configuration_Example"></a><a class="link" href="#sec:Test_Environment_Configuration_Example">6.2.5. Test Environment Configuration Example</a></h4> |
| <div class="paragraph"> |
| <p>For example assuming that user selects <em>ProjectX</em> to test that contains only one test class in <em>src/test/n4js/core</em> path like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">class MyTestClass{ |
| |
| @BeforeAll |
| public void someOneTimeSetup(){ /* setup code */} |
| |
| @Test |
| public void testA(){ /* some test code*/ } |
| @Test |
| public void testB(){ /* some test code*/ } |
| @Test |
| public void testC(){ /* some test code*/ } |
| |
| @After |
| public void afterCleanup(){ /* setup code */} |
| |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Configuration sent for <em>Test Execution Environment</em> would look like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-json" data-lang="json">{ |
| "baseURL" : "http://localhost:1234/", |
| "testPlan": |
| [ |
| { |
| "functionName": "someOneTimeSetup", |
| "functionType": "@BeforeAll", |
| "functionContainer": "MyTestClass", |
| "containerModule": "test/n4js/core/MyTestClass", |
| }, |
| { |
| "functionName": "testA", |
| "functionType": "@Test", |
| "functionContainer": "MyTestClassA", |
| "containerModule": "test/n4js/core/MyTestClassA", |
| }, |
| { |
| "functionName": "afterCleanup", |
| "functionType": "@After", |
| "functionContainer": "MyTestClassA", |
| "containerModule": "test/n4js/core/MyTestClassA", |
| }, |
| { |
| "functionName": "testB", |
| "functionType": "@Test", |
| "functionContainer": "MyTestClassA", |
| "containerModule": "test/n4js/core/MyTestClassA", |
| }, |
| { |
| "functionName": "afterCleanup", |
| "functionType": "@After", |
| "functionContainer": "MyTestClassA", |
| "containerModule": "test/n4js/core/MyTestClassA", |
| }, |
| { |
| "functionName": "testC", |
| "functionType": "@Test", |
| "functionContainer": "MyTestClassA", |
| "containerModule": "test/n4js/core/MyTestClassA", |
| }, |
| { |
| "functionName": "afterCleanup", |
| "functionType": "@After", |
| "functionContainer": "MyTestClassA", |
| "containerModule": "test/n4js/core/MyTestClassA", |
| } |
| ] |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_help-system"><a class="anchor" href="#_help-system"></a><a class="link" href="#_help-system">7. Help System</a></h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="sec:Built_In_Help"><a class="anchor" href="#sec:Built_In_Help"></a><a class="link" href="#sec:Built_In_Help">7.1. Built-In Help</a></h3> |
| |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Context_Sensitive_Help"><a class="anchor" href="#sec:Context_Sensitive_Help"></a><a class="link" href="#sec:Context_Sensitive_Help">7.2. Context Sensitive Help</a></h3> |
| |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Cheat_Sheets"><a class="anchor" href="#sec:Cheat_Sheets"></a><a class="link" href="#sec:Cheat_Sheets">7.3. Cheat Sheets</a></h3> |
| |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:JSDoc"><a class="anchor" href="#sec:JSDoc"></a><a class="link" href="#sec:JSDoc">7.4. JSDoc</a></h3> |
| |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Hovering"><a class="anchor" href="#sec:Hovering"></a><a class="link" href="#sec:Hovering">7.5. Hovering</a></h3> |
| <div class="paragraph"> |
| <p>Hovering over an element (such as type, field, method, function or variable declaration) in the N4JS editor will cause a tooltip appear containing information about the underlying element. Currently this information is the type (could be the inferred type as well), the name and the keyword (such as class, variable, field) of the actual element. By default the tooltip does not grab the focus from the currently active workbench window and will automatically disappear after the focus is lost from the element. One can grab the focus for the tooltip by clicking into the tooltip area or pressing <kbd>F2</kbd> function key.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Show_Type_Information_of_Selection"><a class="anchor" href="#sec:Show_Type_Information_of_Selection"></a><a class="link" href="#sec:Show_Type_Information_of_Selection">7.5.1. Show Type Information of Selection</a></h4> |
| <div class="paragraph"> |
| <p>In some cases, during the development process, one would like to know what is the actual or even the inferred type of an N4JS expression. To use this functionality one can select the desired expression in the editor and invoke the ’Show Type Information’ command via the <kbd>Cmd</kbd> + <kbd>Option</kbd>+ <kbd>I</kbd> ( <kbd>Ctrl</kbd> + <kbd>Alt</kbd>+ <kbd>I</kbd> Windows/Linux) from the keyboard. This case a popup window will be raised containing the type information of the actual selection.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Example_Projects_and_Files"><a class="anchor" href="#sec:Example_Projects_and_Files"></a><a class="link" href="#sec:Example_Projects_and_Files">7.6. Example Projects and Files</a></h3> |
| |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_bug-management"><a class="anchor" href="#_bug-management"></a><a class="link" href="#_bug-management">8. Bug Management</a></h2> |
| <div class="sectionbody"> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title=""></i> |
| </td> |
| <td class="content"> |
| Parts of this document may be outdated. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="sec:Built_In_Xpect_Support"><a class="anchor" href="#sec:Built_In_Xpect_Support"></a><a class="link" href="#sec:Built_In_Xpect_Support">8.1. Built-In Xpect Support</a></h3> |
| <div class="paragraph"> |
| <p>N4IDE contains built-in support for <a href="http://www.xpect-tests.org/">xpect</a> based tests. The purpose of those is to create tests for N4IDE support for user code, not the user code itself. Users can create <em>fileName.n4js.xt</em> to write their test for a given N4IDE functionality. Those files can be executed (via context menu, run configurations, etc.) to verify user expectations.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Report_View"><a class="anchor" href="#sec:Report_View"></a><a class="link" href="#sec:Report_View">8.1.1. Report View</a></h4> |
| <div class="paragraph"> |
| <p>When executing xpect tests, users can view the results in a special view available in the IDE: <kbd>Window</kbd> → <kbd>Show View</kbd> → <kbd>Other</kbd> → <kbd>Test Views</kbd> → <kbd>Xpect View</kbd>.</p> |
| </div> |
| <div id="fig:test_view" class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/11_bugmanagement/fig/testView.png" alt="testView" width="75%"> |
| </div> |
| <div class="title">Figure 14. Test View</div> |
| </div> |
| <div class="paragraph"> |
| <p>This view allows user to generate bug report (see <a href="#sec:Generate_Bug_Report">Generating Bug Reports</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>In case of failing tests, users can see additional information (e.g. a stacktrace), or call a comparison view.</p> |
| </div> |
| <div id="fig:comparison" class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/11_bugmanagement/fig/comparison.png" alt="comparison" width="75%"> |
| </div> |
| <div class="title">Figure 15. Comparison</div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Generate_Bug_Report"><a class="anchor" href="#sec:Generate_Bug_Report"></a><a class="link" href="#sec:Generate_Bug_Report">8.1.2. Generate Bug Report</a></h4> |
| <div class="paragraph"> |
| <p>Generating bug reports can be done when there is some <code>.n4js.xt</code> file with all passing expectations, and at least one of them marked with <em>FIXME</em>. In this case icon of the executed test suite changes and via context menu user can call generate bug report option. When it is done, user can see contents of the bug generated in the console view. This output is prepared for out JIRA ticketing system.</p> |
| </div> |
| <div id="fig:bug_report" class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/11_bugmanagement/fig/bugReport.png" alt="bugReport" width="75%"> |
| </div> |
| <div class="title">Figure 16. Bug Report</div> |
| </div> |
| <div class="paragraph"> |
| <p>There is also possibility to generate bug report via file selection and context menu. In this case xpect test is not executed, only bug contents are generated.</p> |
| </div> |
| <div id="fig:bug" class="imageblock center" style="text-align: center"> |
| <div class="content"> |
| <img src="chapters/11_bugmanagement/fig/bug.png" alt="bug" width="50%"> |
| </div> |
| <div class="title">Figure 17. Submited Bug</div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Supported_Xpect_Tests"><a class="anchor" href="#sec:Supported_Xpect_Tests"></a><a class="link" href="#sec:Supported_Xpect_Tests">8.1.3. Supported Xpect Tests</a></h4> |
| <div class="paragraph"> |
| <p>Xpect methods are special form of comments inside <em>.xt</em> files. General syntax for declaring usage of such method is <em>XPECT</em> marker followed by <em>XpectMethodName</em> and parameters for that method, all placed in comment. This can have three forms:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Single line comment (see the first comment in the listing below), Notice <strong><code>→</code></strong> separating the method name and its parameters.</p> |
| </li> |
| <li> |
| <p>Multi line comment with one method invocation, notice <strong><code>-</code></strong> separating the method name and its parameters</p> |
| </li> |
| <li> |
| <p>Multi line comment with multiple method invocations, simmilar to one above, but each line of method parameters indicates separate method invocation</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">//XPECT errors --> "Couldn't resolve reference to IdentifiableElement 'consoleX'." at "consoleX" |
| consoleX.log(10); |
| |
| /*XPECT errors --- |
| "Couldn't resolve reference to IdentifiableElement 'logY'." at "logY" |
| ---*/ |
| console.logY(10); |
| |
| /*XPECT errors --- |
| "Couldn't resolve reference to IdentifiableElement 'log'." at "log" |
| "Couldn't resolve reference to IdentifiableElement 'ref'." at "ref" |
| --- */ |
| log(ref);</code></pre> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:XPECT_N4JS_Errors"><a class="anchor" href="#sec:XPECT_N4JS_Errors"></a><a class="link" href="#sec:XPECT_N4JS_Errors">8.1.3.1. Errors, Warnings, Infos, Issues</a></h5> |
| <div class="paragraph"> |
| <p><em>Errors</em>, <em>Warnings</em>, <em>Infos</em> are xpect methods that allow to capture marker of given severity. Additionally <em>Issues</em> allows to allow markers of all above severities.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All of those methods can be used single invocations or as mutline invocations.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">//XPECT errors --> "Couldn't resolve reference to IdentifiableElement 'x'." at "x" |
| console.log(x) |
| |
| //XPECT warnings --> "Variable names should start with lower case letter." at "String" |
| var String = "some string"</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:XPECT_N4JS_Noerrors"><a class="anchor" href="#sec:XPECT_N4JS_Noerrors"></a><a class="link" href="#sec:XPECT_N4JS_Noerrors">8.1.3.2. Noerrors</a></h5> |
| <div class="paragraph"> |
| <p>No errors allows to catch (and suppress) marker of any severity (<em>error</em>, <em>warning</em>, <em>info</em>).</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">//XPECT noerrors --> "window object should be recognized" |
| console.log(window)</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:XPECT_N4JS_Output"><a class="anchor" href="#sec:XPECT_N4JS_Output"></a><a class="link" href="#sec:XPECT_N4JS_Output">8.1.3.3. Output, OutputRegex</a></h5> |
| <div class="paragraph"> |
| <p>Output methods are special in sense that they are not intended to be used on single element of the script, but they apply to the whole script.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">/* XPECT output --- |
| <== |
| stdout: |
| hello world |
| stderr: |
| ==> |
| --- */ |
| console.log("hello world")</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Second method accepts regex expressions. This allows to deal with troublesome output (e.g. dates)</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">/* XPECT outputRegex --- |
| <== |
| stdout: |
| [^\n]* |
| stderr: |
| ==> |
| --- */ |
| console.log(new Date())</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">/* XPECT outputRegex --- |
| <== |
| stdout: |
| hello world |
| stderr: |
| |
| [^\n]+ |
| throw ' cruel world' |
| \^ |
| cruel world |
| ==> |
| --- */ |
| console.log("hello world") |
| throw ' cruel world'</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:XPECT_N4JS_Type_Of"><a class="anchor" href="#sec:XPECT_N4JS_Type_Of"></a><a class="link" href="#sec:XPECT_N4JS_Type_Of">8.1.3.4. Type Of</a></h5> |
| <div class="paragraph"> |
| <p>Xpect type methods allow test type inference, both for inferred type or expected type.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-n4js" data-lang="n4js">//XPECT type of 'probablySomeString' --> string |
| var probablySomeString = "some string"; |
| |
| var union{string,number} u; |
| // XPECT expectedType at 'null' --> {function(number?):string} |
| u.toString = null</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="sec:XPECT_Advanced_Methods"><a class="anchor" href="#sec:XPECT_Advanced_Methods"></a><a class="link" href="#sec:XPECT_Advanced_Methods">8.1.3.5. Advanced methods</a></h5> |
| <div class="paragraph"> |
| <p>There are also other methods provided, that allow to test quick fixes and content assist. Their parameters syntax is more complicated. Additionally they actively modify contents of the editor, or even close it if needed. Their usage exceeds scope of this document.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_cli"><a class="anchor" href="#_cli"></a><a class="link" href="#_cli">9. CLI</a></h2> |
| <div class="sectionbody"> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title=""></i> |
| </td> |
| <td class="content"> |
| Parts of this document may be outdated. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2 language-bash"> |
| <h3 id="sec:Headless_Compiler"><a class="anchor" href="#sec:Headless_Compiler"></a><a class="link" href="#sec:Headless_Compiler">9.1. Headless Compiler</a></h3> |
| <div class="paragraph"> |
| <p>The headless compiler is provided as a separate tool, coming as a single jar file <code>n4jsc.jar</code>. It is to be invoked via</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">java -jar n4jsc.jar</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Simply invoking the headless compiler with no further arguments will print out a description of command line options.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The headless compiler works in three major modes (given as arguments to the switch <code>-bt</code>):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>compilation of single files (<code>-bt singlefile</code>, <em>default</em>),</p> |
| </li> |
| <li> |
| <p>compilation of given projects (<code>-bt projects</code>) or</p> |
| </li> |
| <li> |
| <p>compilation of all projects (<code>-bt allprojects</code>)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The command-line invocation usually has the form of</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">java -jar n4jsc.jar ^$[options]$^ file1 file2 ...</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Standard compiler <em>options</em>:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--buildType</code> , <code>-bt</code> <em>mode</em></dt> |
| <dd> |
| <p>With <em>mode</em> as exactly one of</p> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">singlefile</dt> |
| <dd> |
| <p>only the source files given by <em>file1</em>, <em>file2</em>, …​ are compiled.</p> |
| </dd> |
| <dt class="hdlist1">projects</dt> |
| <dd> |
| <p><em>file1</em>, <em>file2</em>, …​ denote projects (folders containing a <code>manifest.n4mf</code>). These projects will be compiled.</p> |
| </dd> |
| <dt class="hdlist1">allprojects</dt> |
| <dd> |
| <p>All project found under the project-root(s) are compiled. There should be no <em>file…​</em> given.</p> |
| </dd> |
| <dt class="hdlist1">dontcompile</dt> |
| <dd> |
| <p>Nothing will be compiled. There should be no <em>file…​</em> given. (This is the default if no <code>-t</code> option is given).</p> |
| </dd> |
| </dl> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>--projectlocations</code> (<code>-pl</code>) <code>path</code></dt> |
| <dd> |
| <p><a id="opt-projectlocations"></a> provide folder(s) to search for projects. If not set, the base folder of the running JVM will be taken as the location. Multiple folders are separated by the systems path-separator (’<code>:</code>’ on Mac / Unix and ’<code>;</code>’ on Windows). Only direct subfolders will be queried for projects. A subfolder is assumed to be a N4JS-project if it contains a <code>manifest.n4mf</code> file. All found projects are taken into consideration for dependency-resolution. Example on Linux:<br> |
| <code>-pl /rootA/: /rootB:/some/absolute/path/to/projects</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>Advanced compiler options (optional):</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--notests</code></dt> |
| <dd> |
| <p>turn off compilation of code in test-folders. Can not be combined with <code>–testonly</code></p> |
| </dd> |
| <dt class="hdlist1"><code>--testonly</code></dt> |
| <dd> |
| <p>only compile test code. Externals and sources will not be compiled. Can not be combined with <code>–notests</code></p> |
| </dd> |
| <dt class="hdlist1"><code>--keepCompiling</code></dt> |
| <dd> |
| <p>try to compile even if some errors occur.</p> |
| </dd> |
| <dt class="hdlist1"><code>--preference</code> <em>file</em></dt> |
| <dd> |
| <p>uses <em>file</em> as there internal preferences-store similar to the preferences internally stored by the N4IDE.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>Additional command line options (optional):</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--help</code> , <code>-h</code> </dt> |
| <dd> |
| <p>prints out help to the console and exits.</p> |
| </dd> |
| <dt class="hdlist1"><code>--verbose</code> , <code>-v</code></dt> |
| <dd> |
| <p>verbose output during build</p> |
| </dd> |
| <dt class="hdlist1"><code>--debug</code> </dt> |
| <dd> |
| <p>before executing, summarises the information of the current setup like resolved pathnames and other information, carries on with normal workflow and prints additional status information about loading and unloading projects and processing each resource.</p> |
| </dd> |
| <dt class="hdlist1"><code>--log</code></dt> |
| <dd> |
| <p>write a log file <code>n4jsc.log</code> to the base folder. (Change filename with <code>–logfile filename</code>)</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2 language-bash"> |
| <h3 id="sec:Headless_Dependencies"><a class="anchor" href="#sec:Headless_Dependencies"></a><a class="link" href="#sec:Headless_Dependencies">9.2. Headless Dependnecies</a></h3> |
| <div class="paragraph"> |
| <p>Compiler can manage dependencies of the processed projects:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--installMissingDependencies</code> , <code>-imd</code> </dt> |
| <dd> |
| <p>alnalyzes available projects and installs missing dependencies</p> |
| </dd> |
| <dt class="hdlist1"><code>--targetPlatformInstallLocation</code> , <code>-tl</code></dt> |
| <dd> |
| <p>location to which dependencies will be installed, if not provided temporal location will be used</p> |
| </dd> |
| <dt class="hdlist1"><code>--npmrcRootLocation</code></dt> |
| <dd> |
| <p>location of the <em>.npmrc</em> file to be used in <em>npm</em> invocations</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2 language-bash"> |
| <h3 id="sec:Headless_Execution"><a class="anchor" href="#sec:Headless_Execution"></a><a class="link" href="#sec:Headless_Execution">9.3. Headless Execution</a></h3> |
| <div class="paragraph"> |
| <p>For headless compiling, running and testing of N4JS code a general command line tool is provided. Many parameters of the different use cases are shared. Although you can combine the use cases each of them is described in its own section. This section is about running compiled code.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For compiling refer to <a href="#sec:Headless_Compiler">Headless Compiler</a> for executing tests refer to <a href="#_test_support">Tests</a>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Cleaning_Headlessly"><a class="anchor" href="#sec:Cleaning_Headlessly"></a><a class="link" href="#sec:Cleaning_Headlessly">9.3.1. Cleaning Headlessly</a></h4> |
| <div class="paragraph"> |
| <p>It is possible to use the headless compiler to clean projects by using the following option</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--clean</code> (<code>-c</code>)</dt> |
| <dd> |
| <p>When this option is used. The headless compiler only cleans projects without compilation. Moreover, the use of this option requires that the option <code>-t</code> must be specified and must be either <code>-t projects</code> or <code>-t allprojects</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>For instance, <code>n4jsc --clean -t allprojects -pl path/to/project</code> or <code>n4jsc --clean -t projects project1 project2</code> are valid use while <code>n4jsc --clean -t singlefile file1 file2</code> is invalid. |
| After the calling the command with <code>--clean (</code>-c`), the output folders of the specified projects (e.g. <code>src-gen</code> folders) are cleaned.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Running_Headlessly"><a class="anchor" href="#sec:Running_Headlessly"></a><a class="link" href="#sec:Running_Headlessly">9.3.2. Running Headlessly</a></h4> |
| <div class="paragraph"> |
| <p>Running code from the command line requires basically three different pieces of information:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>The locations where projects, libraries and environments can be found must be given.</p> |
| </li> |
| <li> |
| <p>The starting point of execution must be given by pointing to a module.</p> |
| </li> |
| <li> |
| <p>Since there are multiple different project types, an adequate Runner has to be selected.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>The follwing command line switches are used to provide this information:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--projectlocations</code> (<code>-pl</code>) <code>path</code></dt> |
| <dd> |
| <p>path of locations to search for projects (c.f. <a href="#sec:Headless_Compiler">Headless Compiler</a> ,<a href="#opt-projectlocations">Project Locations</a>)</p> |
| </dd> |
| <dt class="hdlist1"><code>--runWith</code> (<code>-rw</code>) <code>VAL</code></dt> |
| <dd> |
| <p>denotes the runner-id (as listed with --list-runners) or at least the last segment of it</p> |
| </dd> |
| <dt class="hdlist1"><code>--run</code> (<code>-r</code>) <code>FILE</code></dt> |
| <dd> |
| <p>source-module to run. Note you should point to the full location of the source file (*.n4js). The runner is <em>responsible to determine the compiled file</em>. It is not sufficient to give a project-relative path, it always needs to be a full path to the source file.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>It is possible to compile and run with a single CLI line. Compilation always precedes the execution. It the compilation fails the runner will not be started.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To ease the usage of different runners it is allowed to provide the last segment(s) of the runner-id in a case-insensitive way, e.g. one can use the runner with id <code>org.eclipse.n4js.runner.nodejs.NODEJS</code> as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">.. --runWith org.eclipse.n4js.runner.nodejs.NODEJS ..</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or in short</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">.. --rw NODEJS ..</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or even lower-cased with</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">.. --rw nodejs ..</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Assume having a common workspace location ’wsp’ with a project ’P1’ containing the module ’A’. The following line shows how to run this code:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">java -jar n4jsc.jar -pl wsp -rw nodejs -r wsp/P1/src/A.n4js</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Information_about_running_headlessly"><a class="anchor" href="#sec:Information_about_running_headlessly"></a><a class="link" href="#sec:Information_about_running_headlessly">9.3.3. Information about running headlessly</a></h4> |
| <div class="paragraph"> |
| <p>Available runner-ids can be actively queried:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--listRunners</code> (<code>-lr</code>)</dt> |
| <dd> |
| <p>prints out a list of all available command-line runners</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Testing_Headlessly"><a class="anchor" href="#sec:Testing_Headlessly"></a><a class="link" href="#sec:Testing_Headlessly">9.3.4. Testing Headlessly</a></h4> |
| <div class="paragraph"> |
| <p>Testing code from the command line requires basically three different pieces of information:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>The locations where projects, libraries and environments can be found must be given.</p> |
| </li> |
| <li> |
| <p>The starting point of test execution must be given by pointing to what is supposed to be tested (single file / whole project)/</p> |
| </li> |
| <li> |
| <p>Since there are multiple different project types, an adequate Tester has to be selected.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>The follwing command line switches are used to provide this information:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--projectlocations</code> (<code>-pl</code>) <code>path</code></dt> |
| <dd> |
| <p>path of locations to search for projects (c.f. <a href="#sec:Headless_Compiler">Headless Compiler</a> ,<a href="#opt-projectlocations">Project Locations</a>)</p> |
| </dd> |
| <dt class="hdlist1"><code>--testWith</code> (<code>-tw</code>) <code>VAL</code></dt> |
| <dd> |
| <p>denotes the tester-id (as listed with --list-testers) or at least the last segment of it</p> |
| </dd> |
| <dt class="hdlist1"><code>--test</code> (<code>-t</code>) <code>FILE</code></dt> |
| <dd> |
| <p>source-module to run. Note you should point to the full location of the project with tests, specific folder inside project with tests or the test source file (*.n4js). It is not sufficient to give a project-relative path, it always needs to be a full path to the source file.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>It is possible to compile and run with a single CLI line. Compilation always precedes the execution. It the compilation fails the tester will not be started.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To ease the usage of different testers it is allowed to provide the last segment(s) of the tester-id in a case-insensitive way, e.g. one can use the runner with id <code>org.eclipse.n4js.tester.nodejs.NODEJS_MANGELHAFT</code> as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">.. --runWith org.eclipse.n4js.tester.nodejs.NODEJS_MANGELHAFT ..</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or in short</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">.. --rw NODEJS_MANGELHAFT ..</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or even lower-cased with</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">.. --rw nodejs_mangelhaft ..</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Assume having a common workspace location ’wsp’ with a project ’P1’ containing the module ’TestA’. The following line shows how to execute this test code:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-bash" data-lang="bash">java -jar n4jsc.jar -pl wsp -tw nodejs_mangelhaft -t wsp/P1/src/TestA.n4js</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="sec:Information_about_testing_headlessly"><a class="anchor" href="#sec:Information_about_testing_headlessly"></a><a class="link" href="#sec:Information_about_testing_headlessly">9.3.5. Information about testing headlessly</a></h4> |
| <div class="paragraph"> |
| <p>Available tester-ids can be actively queried:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>--listTesters</code> (<code>-lt</code>)</dt> |
| <dd> |
| <p>prints out a list of all available command-line testers</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_testresults"><a class="anchor" href="#_testresults"></a><a class="link" href="#_testresults">9.3.6. TestResults</a></h4> |
| <div class="paragraph"> |
| <p>TODO</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="sec:License"><a class="anchor" href="#sec:License"></a><a class="link" href="#sec:License">Appendix A: License</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This specification and the accompanying materials is made available |
| under the terms of the Eclipse Public License v1.0 which accompanies |
| this distribution, and is available at <a href="http://www.eclipse.org/legal/epl-v10.html" class="bare">http://www.eclipse.org/legal/epl-v10.html</a></p> |
| </div> |
| <h3 id="_eclipse-public-license-v-1-0" class="discrete">Eclipse Public License - v 1.0</h3> |
| <div class="paragraph"> |
| <p>THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE |
| PUBLIC LICENSE (<code>AGREEMENT</code>). ANY USE, REPRODUCTION OR DISTRIBUTION OF |
| THE PROGRAM CONSTITUTES RECIPIENT’S ACCEPTANCE OF THIS AGREEMENT.</p> |
| </div> |
| <h4 id="_1-definitions" class="discrete">1. DEFINITIONS</h4> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>Contribution</code> means: </dt> |
| <dd> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>in the case of the initial Contributor, the initial code and |
| documentation distributed under this Agreement, and</p> |
| </li> |
| <li> |
| <p>in the case of each subsequent Contributor:</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>changes to the Program, and</p> |
| </li> |
| <li> |
| <p>additions to the Program;</p> |
| <div class="paragraph"> |
| <p>where such changes and/or additions to the Program originate from and |
| are distributed by that particular Contributor. A Contribution |
| ’originates’ from a Contributor if it was added to the Program by such |
| Contributor itself or anyone acting on such Contributor’s behalf. |
| Contributions do not include additions to the Program which:</p> |
| </div> |
| <div class="olist lowerroman"> |
| <ol class="lowerroman" type="i"> |
| <li> |
| <p>are separate modules of software distributed in conjunction with the Program |
| under their own license agreement, and</p> |
| </li> |
| <li> |
| <p>are not derivative works of the Program.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>Contributor</code></dt> |
| <dd> |
| <p>means any person or entity that distributes the Program.</p> |
| </dd> |
| <dt class="hdlist1"><code>Licensed Patents</code> </dt> |
| <dd> |
| <p>mean patent claims licensable by a Contributor |
| which are necessarily infringed by the use or sale of its Contribution |
| alone or when combined with the Program.</p> |
| </dd> |
| <dt class="hdlist1"><code>Program</code> </dt> |
| <dd> |
| <p>means the Contributions distributed in accordance with this |
| Agreement.</p> |
| </dd> |
| <dt class="hdlist1"><code>Recipient</code> </dt> |
| <dd> |
| <p>means anyone who receives the Program under this |
| Agreement, including all Contributors.</p> |
| </dd> |
| </dl> |
| </div> |
| <h4 id="_2-grant-of-rights" class="discrete">2. GRANT OF RIGHTS</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Subject to the terms of this Agreement, each Contributor hereby |
| grants Recipient a non-exclusive, worldwide, royalty-free copyright |
| license to reproduce, prepare derivative works of, publicly display, |
| publicly perform, distribute and sublicense the Contribution of such |
| Contributor, if any, and such derivative works, in source code and |
| object code form.</p> |
| </li> |
| <li> |
| <p>Subject to the terms of this Agreement, each Contributor hereby |
| grants Recipient a non-exclusive, worldwide, royalty-free patent license |
| under Licensed Patents to make, use, sell, offer to sell, import and |
| otherwise transfer the Contribution of such Contributor, if any, in |
| source code and object code form. This patent license shall apply to the |
| combination of the Contribution and the Program if, at the time the |
| Contribution is added by the Contributor, such addition of the |
| Contribution causes such combination to be covered by the Licensed |
| Patents. The patent license shall not apply to any other combinations |
| which include the Contribution. No hardware per se is licensed |
| hereunder.</p> |
| </li> |
| <li> |
| <p>Recipient understands that although each Contributor grants the |
| licenses to its Contributions set forth herein, no assurances are |
| provided by any Contributor that the Program does not infringe the |
| patent or other intellectual property rights of any other entity. Each |
| Contributor disclaims any liability to Recipient for claims brought by |
| any other entity based on infringement of intellectual property rights |
| or otherwise. As a condition to exercising the rights and licenses |
| granted hereunder, each Recipient hereby assumes sole responsibility to |
| secure any other intellectual property rights needed, if any. For |
| example, if a third party patent license is required to allow Recipient |
| to distribute the Program, it is Recipient’s responsibility to acquire |
| that license before distributing the Program.</p> |
| </li> |
| <li> |
| <p>Each Contributor represents that to its knowledge it has sufficient |
| copyright rights in its Contribution, if any, to grant the copyright |
| license set forth in this Agreement.</p> |
| </li> |
| </ol> |
| </div> |
| <h4 id="_3-requirements" class="discrete">3. REQUIREMENTS</h4> |
| <div class="paragraph"> |
| <p>A Contributor may choose to distribute the Program in object code form |
| under its own license agreement, provided that:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>it complies with the terms and conditions of this Agreement; and</p> |
| </li> |
| <li> |
| <p>its license agreement:</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>effectively disclaims on behalf of all Contributors all warranties |
| and conditions, express and implied, including warranties or conditions |
| of title and non-infringement, and implied warranties or conditions of |
| merchantability and fitness for a particular purpose;</p> |
| </li> |
| <li> |
| <p>effectively excludes on behalf of all Contributors all liability for |
| damages, including direct, indirect, special, incidental and |
| consequential damages, such as lost profits;</p> |
| </li> |
| <li> |
| <p>states that any provisions which differ from this Agreement are |
| offered by that Contributor alone and not by any other party; and</p> |
| </li> |
| <li> |
| <p>states that source code for the Program is available from such |
| Contributor, and informs licensees how to obtain it in a reasonable |
| manner on or through a medium customarily used for software exchange.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>When the Program is made available in source code form:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>it must be made available under this Agreement; and</p> |
| </li> |
| <li> |
| <p>a copy of this Agreement must be included with each copy of the |
| Program.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Contributors may not remove or alter any copyright notices contained |
| within the Program.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each Contributor must identify itself as the originator of its |
| Contribution, if any, in a manner that reasonably allows subsequent |
| Recipients to identify the originator of the Contribution.</p> |
| </div> |
| <h4 id="_4-commercial-distribution" class="discrete">4. COMMERCIAL DISTRIBUTION</h4> |
| <div class="paragraph"> |
| <p>Commercial distributors of software may accept certain responsibilities |
| with respect to end users, business partners and the like. While this |
| license is intended to facilitate the commercial use of the Program, the |
| Contributor who includes the Program in a commercial product offering |
| should do so in a manner which does not create potential liability for |
| other Contributors. Therefore, if a Contributor includes the Program in |
| a commercial product offering, such Contributor (<code>Commercial |
| Contributor</code>) hereby agrees to defend and indemnify every other |
| Contributor (<code>Indemnified Contributor</code>) against any losses, damages |
| and costs (collectively <code>Losses</code>) arising from claims, lawsuits and |
| other legal actions brought by a third party against the Indemnified |
| Contributor to the extent caused by the acts or omissions of such |
| Commercial Contributor in connection with its distribution of the |
| Program in a commercial product offering. The obligations in this |
| section do not apply to any claims or Losses relating to any actual or |
| alleged intellectual property infringement. In order to qualify, an |
| Indemnified Contributor must: a) promptly notify the Commercial |
| Contributor in writing of such claim, and b) allow the Commercial |
| Contributor to control, and cooperate with the Commercial Contributor |
| in, the defense and any related settlement negotiations. The Indemnified |
| Contributor may participate in any such claim at its own expense.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, a Contributor might include the Program in a commercial |
| product offering, Product X. That Contributor is then a Commercial |
| Contributor. If that Commercial Contributor then makes performance |
| claims, or offers warranties related to Product X, those performance |
| claims and warranties are such Commercial Contributor’s responsibility |
| alone. Under this section, the Commercial Contributor would have to |
| defend claims against the other Contributors related to those |
| performance claims and warranties, and if a court requires any other |
| Contributor to pay any damages as a result, the Commercial Contributor |
| must pay those damages.</p> |
| </div> |
| <h4 id="_5-no-warranty" class="discrete">5. NO WARRANTY</h4> |
| <div class="paragraph"> |
| <p>EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED |
| ON AN <code>AS IS</code> BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, |
| EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES |
| OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR |
| A PARTICULAR PURPOSE. Each Recipient is solely responsible for |
| determining the appropriateness of using and distributing the Program |
| and assumes all risks associated with its exercise of rights under this |
| Agreement , including but not limited to the risks and costs of program |
| errors, compliance with applicable laws, damage to or loss of data, |
| programs or equipment, and unavailability or interruption of operations.</p> |
| </div> |
| <h4 id="_6-disclaimer-of-liability" class="discrete">6. DISCLAIMER OF LIABILITY</h4> |
| <div class="paragraph"> |
| <p>EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR |
| ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, |
| INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING |
| WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF |
| LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
| NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR |
| DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED |
| HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</p> |
| </div> |
| <h4 id="_7-general" class="discrete">7. GENERAL</h4> |
| <div class="paragraph"> |
| <p>If any provision of this Agreement is invalid or unenforceable under |
| applicable law, it shall not affect the validity or enforceability of |
| the remainder of the terms of this Agreement, and without further action |
| by the parties hereto, such provision shall be reformed to the minimum |
| extent necessary to make such provision valid and enforceable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If Recipient institutes patent litigation against any entity (including |
| a cross-claim or counterclaim in a lawsuit) alleging that the Program |
| itself (excluding combinations of the Program with other software or |
| hardware) infringes such Recipient’s patent(s), then such Recipient’s |
| rights granted under Section 2(b) shall terminate as of the date such |
| litigation is filed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All Recipient’s rights under this Agreement shall terminate if it fails |
| to comply with any of the material terms or conditions of this Agreement |
| and does not cure such failure in a reasonable period of time after |
| becoming aware of such noncompliance. If all Recipient’s rights under |
| this Agreement terminate, Recipient agrees to cease use and distribution |
| of the Program as soon as reasonably practicable. However, Recipient’s |
| obligations under this Agreement and any licenses granted by Recipient |
| relating to the Program shall continue and survive.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Everyone is permitted to copy and distribute copies of this Agreement, |
| but in order to avoid inconsistency the Agreement is copyrighted and may |
| only be modified in the following manner. The Agreement Steward reserves |
| the right to publish new versions (including revisions) of this |
| Agreement from time to time. No one other than the Agreement Steward has |
| the right to modify this Agreement. The Eclipse Foundation is the |
| initial Agreement Steward. The Eclipse Foundation may assign the |
| responsibility to serve as the Agreement Steward to a suitable separate |
| entity. Each new version of the Agreement will be given a distinguishing |
| version number. The Program (including Contributions) may always be |
| distributed subject to the version of the Agreement under which it was |
| received. In addition, after a new version of the Agreement is |
| published, Contributor may elect to distribute the Program (including |
| its Contributions) under the new version. Except as expressly stated in |
| Sections 2(a) and 2(b) above, Recipient receives no rights or licenses |
| to the intellectual property of any Contributor under this Agreement, |
| whether expressly, by implication, estoppel or otherwise. All rights in |
| the Program not expressly granted under this Agreement are reserved.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This Agreement is governed by the laws of the State of New York and the |
| intellectual property laws of the United States of America. No party to |
| this Agreement will bring a legal action under this Agreement more than |
| one year after the cause of action arose. Each party waives its rights |
| to a jury trial in any resulting litigation.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="sec:Acronyms"><a class="anchor" href="#sec:Acronyms"></a><a class="link" href="#sec:Acronyms">Appendix B: Acronyms</a></h2> |
| <div class="sectionbody"> |
| <table id="AC" class="tableblock frame-all grid-all spread language-bash"> |
| <colgroup> |
| <col style="width: 8.3333%;"> |
| <col style="width: 41.6666%;"> |
| <col style="width: 8.3333%;"> |
| <col style="width: 41.6668%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>CDep</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Compile-Time Dependency</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>RDep</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Run-Time Dependency</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>LDep</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Load-Time Dependency</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>IDep</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Initialization-Time Dependency</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>EDep</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Execution-Time Dependency</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>ANTLR</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">ANother Tool for Language Recognition</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>API</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Application Programming Interface</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>AST</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Abstract Syntax Tree</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>ASI</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Automatic Semicolon Insertion</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>BNF</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Backus-Naur Form</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>CLI</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Command Line Interface (including a headless compiler and runner.)</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>DI</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Dependency Injection</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>DIC</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">DI Component</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>DOM</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Document Object Model</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>DSL</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Domain Specific Language</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>EBNF</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Extended Backus-Naur Form</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>EMF</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Eclipse Modeling Framework <a id="EMF"></a></p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>FQN</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Fully Qualified Name</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>GLB</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Greatest Lower Bound, also known as <em>infimum</em></p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>GCST</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Greatest Common Sub Type, also known as <em>meet</em></p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>IDE</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Integrated Development Environment</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>IDL</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Interface Definition Language</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>LSP</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Liskov Substitution Principle [<a href="#Martin96b">Martin96b</a>]</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>LUB</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Least Upper Bound, also known as <em>supremum</em></p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>LCST</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Least Common Super Type, also known as <em>join</em></p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>N4JS</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">N4JS for JavaScript</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>N4JSED</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">N4JS Environment Definition</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>N4JSIDE</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">N4JS Integrated Development Environment (Eclipse-based IDE for all N4JS related languages and projects)</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>VM</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Virtual Machine</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>XML</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Extensible Markup Language</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>XSLT / XSL</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">XSL Transformations</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>XSL</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Extensible Stylesheet Language</p></th> |
| </tr> |
| <tr> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>WYSIWYG</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">What You See Is What You Get</p></th> |
| <td class="tableblock halign-center valign-top"><p class="tableblock"><code>WLOG</code></p></td> |
| <th class="tableblock halign-left valign-top"><p class="tableblock">Without loss of generality</p></th> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_bibliography"><a class="anchor" href="#_bibliography"></a><a class="link" href="#_bibliography">Appendix C: Bibliography</a></h2> |
| <div class="sectionbody"> |
| <div class="openblock bibliography"> |
| <div class="content"> |
| <div class="paragraph"> |
| <p><a id="N4JSSpec"></a><em>N4JS Language Specification</em>. </p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="Martin96b"></a>Martin, Robert C. (1996). <em>The Liskov Substitution Principle</em>. Retrieved from <a href="http://www.objectmentor.com/publications/lsp.pdf" class="bare">http://www.objectmentor.com/publications/lsp.pdf</a></p> |
| </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> |
