Jump to: navigation, search

Difference between revisions of "JSDT/Development"

(JSDT Sources)
(Development Environment Setup)
 
(22 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
== Contributing to JSDT ==
 
== Contributing to JSDT ==
 
The JSDT is driven by a very small development group with limited resources.  ANY serious developers or contributors will be enthusiastically welcomed.  For more information on how to become a Committer, check the standard Eclipse process (see [http://www.eclipse.org/projects/dev_process/new-committer.php New Committer Election]).  For more information about contributing to JSDT in general, or for questions about its internals, contact [mailto:wtp-dev@eclipse.org?subject=JSDT wtp-dev].
 
The JSDT is driven by a very small development group with limited resources.  ANY serious developers or contributors will be enthusiastically welcomed.  For more information on how to become a Committer, check the standard Eclipse process (see [http://www.eclipse.org/projects/dev_process/new-committer.php New Committer Election]).  For more information about contributing to JSDT in general, or for questions about its internals, contact [mailto:wtp-dev@eclipse.org?subject=JSDT wtp-dev].
 
  
 
=== JSDT Functional Testing ===
 
=== JSDT Functional Testing ===
Line 11: Line 10:
  
 
=== Reporting Bugs ===
 
=== Reporting Bugs ===
Report bugs through [http://bugs.eclipse.org/bugs/ Eclipse Bugzilla] under WebTools catagory, JSDT component.
+
[https://bugs.eclipse.org/bugs/enter_bug.cgi?product=JSDT Report a bug] through [http://bugs.eclipse.org/bugs/ Eclipse Bugzilla] under WebTools catagory, JSDT component.
  
 
Here is a [https://bugs.eclipse.org/bugs/buglist.cgi?list_id=3212991&resolution=---&classification=WebTools&query_format=advanced&product=JSDT list of open JSDT bugs]. We're working through them as fast as we can!
 
Here is a [https://bugs.eclipse.org/bugs/buglist.cgi?list_id=3212991&resolution=---&classification=WebTools&query_format=advanced&product=JSDT list of open JSDT bugs]. We're working through them as fast as we can!
  
=== JSDT Sources ===
+
You can receive notifications of incoming bugs by monitoring account ''jsdt.javascript-inbox@eclipse.org'' in https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email
  
Git Repositories:
+
=== Development Environment Setup ===
  
*[http://git.eclipse.org/c/jsdt/webtools.jsdt.core.git/ webtools.jsdt.core.git] [https://github.com/eclipse/webtools.jsdt.core GitHub]
+
There are several ways to setup the development environment. Here are 2 good ones:
*[http://git.eclipse.org/c/jsdt/webtools.jsdt.debug.git/ webtools.jsdt.debug.git] [https://github.com/eclipse/webtools.jsdt.debug GitHub]
+
 
*[http://git.eclipse.org/c/jsdt/webtools.jsdt.tests.git/ webtools.jsdt.tests.git] [https://github.com/eclipse/webtools.jsdt.tests GitHub]
+
==== Eclipse IDE + Target Platform aside ====
 +
 
 +
For this setup we will need two Eclipse installations: an '''Eclipse IDE''' ''for development'' and an '''Eclipse WTP''' to be used as a Target Platform in the development instance''.
 +
This setup is flexible:
 +
* IDE: For development we can use the latest SDK and add on top all the needed plugins
 +
* WTP We can switch different Target Platform (and Baseline) as needed, via '''Windows > Preferences > Plug-in Development'''
 +
 
 +
 
 +
''Example 1'': Simple setup to develop on Mars.1 :
 +
* IDE: eclipse-rcp-mars-1
 +
* WTP: eclipse-jee-mars-1
 +
 
 +
''Example 2''. Advanced setup, to use the latest IDE development:
 +
* IDE: latest M-Build from the [http://download.eclipse.org/eclipse/downloads/ eclipse/downloads] and add your development plugins.
 +
* WTP : '''Eclipse SDK + WTP SDK''', as example: get the SDK-4.5.1 from the [http://download.eclipse.org/eclipse/downloads/ eclipse/downloads] and add the WTP-SDK 3.7.1 adding it via the [http://download.eclipse.org/webtools/repository/mars/ webtools/repository/mars update site]
 +
 
 +
 
 +
==== Full WTP SDK Stack ====
 +
 
 +
The Full Stack is an installation made of Eclipse SDK + WTP SDK, to be used as both as dev environment and as a Target Platform at the same time. This solution shouldn't be faster than the previous setup, and it has limitations when testing again different targets, as it'll be needed to have multiple IDEs.
 +
 
 +
=== JSDT Sources ===
 +
 
 +
You find the Git Repository: [http://git.eclipse.org/c/jsdt/webtools.jsdt.git/ webtools.jsdt.git].
 +
See also [https://projects.eclipse.org/projects/webtools.jsdt/developer JSDT/Developer Resources]  
  
 
Detailed repository contents you can find at this page: http://wiki.eclipse.org/WTP_Git_Migration_Checklist
 
Detailed repository contents you can find at this page: http://wiki.eclipse.org/WTP_Git_Migration_Checklist
  
 
These plug-ins have no dependencies other than the Eclipse base (nor do they depend on anything else in WTP).  Using these plug-ins, a standalone JavaScript Project can be created and used:
 
These plug-ins have no dependencies other than the Eclipse base (nor do they depend on anything else in WTP).  Using these plug-ins, a standalone JavaScript Project can be created and used:
* webtools.jsdt.core.git/bundles/org.eclipse.wst.jsdt.core
+
* bundles/org.eclipse.wst.jsdt.core
* webtools.jsdt.core.git/bundles/org.eclipse.wst.jsdt.manipulation
+
* org.eclipse.wst.jsdt.manipulation
* webtools.jsdt.core.git/bundles/org.eclipse.wst.jsdt.ui
+
* org.eclipse.wst.jsdt.ui
  
 
The Feature project for these is:
 
The Feature project for these is:
* webtools.jsdt.core.git/features/org.eclipse.wst.jsdt.feature
+
* features/org.eclipse.wst.jsdt.feature
 +
 
 +
=== Building and testing JSDT locally ===
 +
 
 +
Simply run <tt>mvn clean verify -Pbuild-individual-bundles -DskipTests=false</tt>. This command will run the Unit-tests. After the build, you can install your JSDT snapshot in an Eclipse IDE or other RCP application using the p2 repository in location <tt>site/target/repository</tt>
 +
 
 +
=== Gerrit Reviews ===
 +
 
 +
==== Pushing a new patch for review ====
 +
 
 +
You can use [[Gerrit]] (mandatory reading, important to set up hooks, SSH keys, CLA & other) to push Git commits on JSDT repositories. The repo URL for JSDT@Gerrit is <tt>ssh://user@git.eclipse.org:29418/jsdt/webtools.jsdt</tt>. Once logged into Gerrit, you can see more details about the URL at https://git.eclipse.org/r/#/admin/projects/jsdt/webtools.jsdt .
 +
 
 +
Assuming you named this repo ''gerrit'', you can push a commit to one of this repository with
 +
<source lang="bash">
 +
$ git push gerrit HEAD:refs/for/master
 +
</source>
 +
This will give you the URL of the Gerrit review where you can interact with project committers to get your commit merged.
 +
 
 +
In case you need to push another version of the patch, don't forget to copy the <tt>Change-Id</tt> from the Gerrit review if you didn't set up the git hook. Providing another version of the patch doesn't require a new commit, simply amend the one you already pushed, and push it again:
 +
<source lang="bash">
 +
$ git log -1 #Shows the commit. Message should contain Sign-Off-By and Change-Id
 +
$ git add file/to/change
 +
$ git commit --amend # add --signoff if Sign-Off-By is missing, and copy Change-Id from Gerrit review if missing
 +
$ git push gerrit HEAD:refs/for/master # will create another version of the patch, on the same review.
 +
</source>
 +
 
 +
==== Reviewing a patch ====
 +
 
 +
Incoming patch automatically triggers a build and will receive an automated vote according to whether patch breaks the build/tests or not. The CI job providing this vote is https://hudson.eclipse.org/webtools/job/jsdt-gerrit.
 +
* Anytime Hudson votes with '''<span style="color: red">-1</span>''', it generally means that something is wrong with the patch: it breaks build or make a test failing, so the patch shouldn't be merged. The build log should be inspected by submitter and reviewers to understand the cause of the bug and submit (or assist in submitting) a better patch.
 +
* Hudson voting '''<span style="color: green">+1</span>''' means that the test didn't introduce any regression visible by build or automated tests.
 +
 
 +
Anyone is free to add comments and vote on a review. Committers have the final power to decide whether or not a patch can be merged.
 +
 
 +
==== List reviews and be notified ====
 +
 
 +
You can see the list of open Gerrit reviews at https://git.eclipse.org/r/#/q/status:open+project:jsdt/webtools.jsdt,n,z .
 +
 
 +
Regular contributors and committers should really subscribe to notifications of proposed patches. You can set up notifications for proposed incoming changes at https://git.eclipse.org/r/#/settings/projects
 +
 
 +
=== Static analysis with SonarQube ===
 +
 
 +
JSDT uses SonarQube to get reports about static analysis. Those can show potential bugs, performance traps, or just bad practices. Here is the status of JSDT on these topics: https://dev.eclipse.org/sonar/dashboard/index/org.eclipse.webtools.jsdt:jsdt-parent . Any help to clean up warnings is welcome!
 +
 
 +
== Architecture ==
  
 
=== HTML an JSP editors ===
 
=== HTML an JSP editors ===
Line 47: Line 114:
  
 
The following are the JUnits test plug-ins for JSDT:
 
The following are the JUnits test plug-ins for JSDT:
* webtools.jsdt.tests.git/tests/org.eclipse.wst.jsdt.core.tests.compiler  - (test suite is org.eclipse.wst.jsdt.core.tests.compiler.JSDTTestAll)
+
* tests/org.eclipse.wst.jsdt.core.tests.compiler  - (test suite is org.eclipse.wst.jsdt.core.tests.compiler.JSDTTestAll)
* webtools.jsdt.tests.git/tests/org.eclipse.wst.jsdt.core.tests.model - (test suite is org.eclipse.wst.jsdt.core.tests.model.AllJavaModelTests)
+
* tests/org.eclipse.wst.jsdt.core.tests.model - (test suite is org.eclipse.wst.jsdt.core.tests.model.AllJavaModelTests)
  
 
These test plug-ins are new to WTP 3.1 and above:
 
These test plug-ins are new to WTP 3.1 and above:
Line 57: Line 124:
 
* webtools.jsdt.tests.git/tests/org.eclipse.wst.jsdt.ui.tests  - (test suite is org.eclipse.wst.jsdt.ui.tests.JSDTUITests)
 
* webtools.jsdt.tests.git/tests/org.eclipse.wst.jsdt.ui.tests  - (test suite is org.eclipse.wst.jsdt.ui.tests.JSDTUITests)
  
== JSDT packages ==
+
=== JSDT packages ===
  
=== JSDT Core ===
+
==== JSDT Core ====
 
The JSDT core plugin (org.eclipse.wst.jsdt.core) provides the core JavaScript modeling.
 
The JSDT core plugin (org.eclipse.wst.jsdt.core) provides the core JavaScript modeling.
  
Line 203: Line 270:
 
|}
 
|}
  
===JSDT UI===
+
====JSDT UI====
 
User interface code
 
User interface code
  
Line 502: Line 569:
 
|}
 
|}
  
== Generating the parser ==
+
=== Generating the parser ===
 
Follow the instructions at http://www.eclipse.org/jdt/core/howto/generate%20parser/generateParser.html for generating the parser.  The parser grammer file is located in cvs at sourceediting/plugins/org.eclipse.wst.jsdt.core/grammer/js.g
 
Follow the instructions at http://www.eclipse.org/jdt/core/howto/generate%20parser/generateParser.html for generating the parser.  The parser grammer file is located in cvs at sourceediting/plugins/org.eclipse.wst.jsdt.core/grammer/js.g
  
== JUnit Tests ==
 
  
== Debugging JSDT ==
+
== Design ==
 +
The JavaScript Development Tools design would use the JDT design with the necessary adjustments made for JavaScript.
 +
 
 +
As far as the JavaScript Development Tools design is concerned, the major differences between Java and JavaScript are:
 +
 
 +
* Javascript has no explicit typing support, whereas in Java everything is typed, and incorporates argument types in function signatures.
 +
* At the top level, a JavaScript file can contain any program statement, whereas a Java file only contains a Class.
 +
* JavaScript has no classpath/jar file concept
 +
 
 +
Other areas where the java/JavaScript differences will necessitate changes:
 +
 
 +
* syntax differences - parse definitions
 +
* additional program elements with no correspondence in Java
 +
** object literals
 +
** for (var in collection)
 +
 
 +
=== Inferred Types ===
 +
 
 +
In order for some JDT-based functionality (such as code completion) to work correctly, class type information needs to be available. This information is not available in JavaScript, but it can be inferred in many cases. A type inferring framework has been put in place to support this functionality, examining the JavaScript Abstract Syntax Tree (AST) and generating "virtual" class information.  Type inferring is extensible, so the unique conventions among various JavaScript Toolkits (e.g. Dojo, jQuery, Prototype, etc.) can be handled, although through WTP 3.1 it has remained provisional.  Inferred types may participate in refactoring, but their visibility within the UI is still being discussed.
 +
 
 +
=== JavaScript file handling ===
 +
 
 +
Java files have a very top down structure, where files only contain classes, which only contain fields, methods, and inner classes, and program statements only contained within methods. Because of this, some JDT functionality will not work for JavaScript, because a program statement can be directly at the top of a JavaScript file. The relevant JDT code is still undergoing refactorings to support these scenarios.
 +
 
 +
=== Variable/function resolution ===
 +
 
 +
In Java, everything is resolvable because of the classpath, package structure, and import statements. This has no correspondence in JavaScript, where functions themselves may also be resolvable as types.
 +
 
 +
==== Libraries ====
 +
 
 +
The JSDT mimics the JDT Java Build Path and classpath container mechanisms to offer JavaScript library support.  JSDT libraries are collections of JavaScript source files that have prototyped object/class definitions and JSDoc.  The inference engine then models these libraries and places each object/field/function in the projects Global Scope, making them available to every JavaScript file in the project.  Because the library contents are not directly executed by JSDT, it isn't necessary for them to contain the complete implementation of those objects.  In fact, the standard JavaScript runtime is itself presented as a source file containing stubs for the specification's contents.  Bindings for nonstandard and future runtimes are similarly easy to create and use.
 +
 
 +
To illustrate-- the JSDT contains a FireFox library plugin with about 150k of JavaScript and JsDoc.  This library represents the class structure within the FireFox browser that is accessible to a web page's JavaScript, but does not contain any implementation to the functions it declares.  If a user wishes to target their JavaScript source to FireFox specifically, they would add the FireFox library to their project and gain content completion and hover help for the FireFox objects. Users may also limit the objects/functions/fields visible in the project by adding or removing libraries.
 +
 
 +
Libraries aren't limited to browser objects.  AJAX runtimes can fit nicely into libraries, as would a website's standard set of utility functions.  Really the possibilities are limitless.  And the library mechanism is extremely easy to expand both by the end-user or through extension points.
 +
 
 +
=== Functionality mapping ===
 +
 
 +
This table shows how the JDT functionality corresponds to the JavaScript functionality. It does not include anything where there is a direct one to one correspondence.
 +
 
 +
{| border="1"
 +
|-
 +
| '''JDT function''' || '''JSDT function'''
 +
|-
 +
| Build path || Libraries + Global Scope (frequently referred to as an "Include Path")
 +
|-
 +
| JDK level (1.4 vs 1.5) || ECMAscript level 3 vs 4 (v.3 supported now, v.4 will not be implemented as the specification was abandoned)
 +
|-
 +
| Compile || Validation & flow analysis
 +
|}
 +
 
 +
=== Extension Points ===
 +
 
 +
The JSDT functionality is embeddable. This means, for instance, that the JavaScript editing capabilities is embeddable within HTML and JSP Editors, both within script tags, and script attribute values.  The JSDT is flexible so script support in other languages is possible using translator interfaces being planned for WTP 3.1.
 +
 
 +
The following JSDT extension points are supported :
 +
 
 +
* Global Scope variable initializer
 +
* Global Scope container initializer core
 +
* Code formatter
 +
* Validation participant
 +
 
 +
<!--In addition, the JavaScript syntax tree will be presented as an XML dom (future), so that various XML processors can be run against it for a variety of reasons, for instance, a Schematron processor could be used to do validation.-->  Currently the JSDT is represented in an AST.
 +
 
 +
The following jsdt.ui extension points will be supported :
 +
 
 +
* Global Scope container initializer ui  (Wizzard, content assist images and type/text naming)
 +
* javascript element filter
 +
* javaScriptEditorTextHovers
 +
* jsdocCompletionProcessor
 +
* quickFixProcessors
 +
* quickAssistProcessors
 +
* foldingStructureProviders
 +
* queryParticipants
 +
* javaScriptCompletionProposalComputer
 +
* javaScriptCompletionProposalSorters
 +
 
  
 
[[Category:JSDT]]
 
[[Category:JSDT]]

Latest revision as of 23:59, 25 January 2016


JSDT
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source


As of WTP 3.0, JSDT is part of the Web Tools Platform.

Contributing to JSDT

The JSDT is driven by a very small development group with limited resources. ANY serious developers or contributors will be enthusiastically welcomed. For more information on how to become a Committer, check the standard Eclipse process (see New Committer Election). For more information about contributing to JSDT in general, or for questions about its internals, contact wtp-dev.

JSDT Functional Testing

Testing Scenarios

Reporting Bugs

Report a bug through Eclipse Bugzilla under WebTools catagory, JSDT component.

Here is a list of open JSDT bugs. We're working through them as fast as we can!

You can receive notifications of incoming bugs by monitoring account jsdt.javascript-inbox@eclipse.org in https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email

Development Environment Setup

There are several ways to setup the development environment. Here are 2 good ones:

Eclipse IDE + Target Platform aside

For this setup we will need two Eclipse installations: an Eclipse IDE for development and an Eclipse WTP to be used as a Target Platform in the development instance. This setup is flexible:

  • IDE: For development we can use the latest SDK and add on top all the needed plugins
  • WTP We can switch different Target Platform (and Baseline) as needed, via Windows > Preferences > Plug-in Development


Example 1: Simple setup to develop on Mars.1 :

  • IDE: eclipse-rcp-mars-1
  • WTP: eclipse-jee-mars-1

Example 2. Advanced setup, to use the latest IDE development:


Full WTP SDK Stack

The Full Stack is an installation made of Eclipse SDK + WTP SDK, to be used as both as dev environment and as a Target Platform at the same time. This solution shouldn't be faster than the previous setup, and it has limitations when testing again different targets, as it'll be needed to have multiple IDEs.

JSDT Sources

You find the Git Repository: webtools.jsdt.git. See also JSDT/Developer Resources

Detailed repository contents you can find at this page: http://wiki.eclipse.org/WTP_Git_Migration_Checklist

These plug-ins have no dependencies other than the Eclipse base (nor do they depend on anything else in WTP). Using these plug-ins, a standalone JavaScript Project can be created and used:

  • bundles/org.eclipse.wst.jsdt.core
  • org.eclipse.wst.jsdt.manipulation
  • org.eclipse.wst.jsdt.ui

The Feature project for these is:

  • features/org.eclipse.wst.jsdt.feature

Building and testing JSDT locally

Simply run mvn clean verify -Pbuild-individual-bundles -DskipTests=false. This command will run the Unit-tests. After the build, you can install your JSDT snapshot in an Eclipse IDE or other RCP application using the p2 repository in location site/target/repository

Gerrit Reviews

Pushing a new patch for review

You can use Gerrit (mandatory reading, important to set up hooks, SSH keys, CLA & other) to push Git commits on JSDT repositories. The repo URL for JSDT@Gerrit is ssh://user@git.eclipse.org:29418/jsdt/webtools.jsdt. Once logged into Gerrit, you can see more details about the URL at https://git.eclipse.org/r/#/admin/projects/jsdt/webtools.jsdt .

Assuming you named this repo gerrit, you can push a commit to one of this repository with

$ git push gerrit HEAD:refs/for/master

This will give you the URL of the Gerrit review where you can interact with project committers to get your commit merged.

In case you need to push another version of the patch, don't forget to copy the Change-Id from the Gerrit review if you didn't set up the git hook. Providing another version of the patch doesn't require a new commit, simply amend the one you already pushed, and push it again:

$ git log -1 #Shows the commit. Message should contain Sign-Off-By and Change-Id
$ git add file/to/change
$ git commit --amend # add --signoff if Sign-Off-By is missing, and copy Change-Id from Gerrit review if missing
$ git push gerrit HEAD:refs/for/master # will create another version of the patch, on the same review.

Reviewing a patch

Incoming patch automatically triggers a build and will receive an automated vote according to whether patch breaks the build/tests or not. The CI job providing this vote is https://hudson.eclipse.org/webtools/job/jsdt-gerrit.

  • Anytime Hudson votes with -1, it generally means that something is wrong with the patch: it breaks build or make a test failing, so the patch shouldn't be merged. The build log should be inspected by submitter and reviewers to understand the cause of the bug and submit (or assist in submitting) a better patch.
  • Hudson voting +1 means that the test didn't introduce any regression visible by build or automated tests.

Anyone is free to add comments and vote on a review. Committers have the final power to decide whether or not a patch can be merged.

List reviews and be notified

You can see the list of open Gerrit reviews at https://git.eclipse.org/r/#/q/status:open+project:jsdt/webtools.jsdt,n,z .

Regular contributors and committers should really subscribe to notifications of proposed patches. You can set up notifications for proposed incoming changes at https://git.eclipse.org/r/#/settings/projects

Static analysis with SonarQube

JSDT uses SonarQube to get reports about static analysis. Those can show potential bugs, performance traps, or just bad practices. Here is the status of JSDT on these topics: https://dev.eclipse.org/sonar/dashboard/index/org.eclipse.webtools.jsdt:jsdt-parent . Any help to clean up warnings is welcome!

Architecture

HTML an JSP editors

JSDT provides JavaScript support for the WTP HTML and JSP editors in the WTP Source Editing project Git repositories. GitHub

The following plug-in projects provide JSDT integration with WTP's HTML and JSP editors:

  • webtools.sourceediting.git/bundles/org.eclipse.wst.jsdt.web.core
  • webtools.sourceediting.git/bundles/plugins/org.eclipse.wst.jsdt.web.ui
  • webtools.sourceediting.git/bundles/plugins/org.eclipse.wst.jsdt.web.support.jsp - contains JSP-specific functionality
  • webtools.sourceediting.git/bundles/plugins/org.eclipse.wst.jsdt.support.firefox - contains bindings for Mozilla FireFox, current as of FF 2.0.x (deprecated)
  • webtools.sourceediting.git/bundles/plugins/org.eclipse.wst.jsdt.support.ie - contains bindings for Microsoft Internet explorer (deprecated)

JSDT tests

The following are the JUnits test plug-ins for JSDT:

  • tests/org.eclipse.wst.jsdt.core.tests.compiler - (test suite is org.eclipse.wst.jsdt.core.tests.compiler.JSDTTestAll)
  • tests/org.eclipse.wst.jsdt.core.tests.model - (test suite is org.eclipse.wst.jsdt.core.tests.model.AllJavaModelTests)

These test plug-ins are new to WTP 3.1 and above:

  • webtools.sourceediting.tests.git/tests/org.eclipse.wst.jsdt.web.core.tests - (test suite is org.eclipse.wst.jsdt.web.core.tests.translation.AllWebCoreTests)
  • webtools.sourceediting.tests.git/tests/org.eclipse.wst.jsdt.web.ui.tests - (test suite is org.eclipse.wst.jsdt.web.ui.tests.AllWebUITests)

These test plug-ins are new to WTP 3.2 and above:

  • webtools.jsdt.tests.git/tests/org.eclipse.wst.jsdt.ui.tests - (test suite is org.eclipse.wst.jsdt.ui.tests.JSDTUITests)

JSDT packages

JSDT Core

The JSDT core plugin (org.eclipse.wst.jsdt.core) provides the core JavaScript modeling.


Core plugin packages
package function
org.eclipse.wst.jsdt.core public apis for the module
org.eclipse.wst.jsdt.core.ast The public apis for the read-only AST used by inference engines
org.eclipse.wst.jsdt.core.compiler the public apis for the validator
org.eclipse.wst.jsdt.core.compiler.libraries libraries which define the javascript language apis and the browser DOM apis
org.eclipse.wst.jsdt.core.dom Modifiable JavaScript model DOM
org.eclipse.wst.jsdt.core.dom.rewrite support for updating the dom
org.eclipse.wst.jsdt.core.eval support for evaluating code fragments
org.eclipse.wst.jsdt.core.formatter public apis for javascript formatting
org.eclipse.wst.jsdt.core.infer support for inferencing and inferencing extensions
org.eclipse.wst.jsdt.core.search public apis for search
org.eclipse.wst.jsdt.core.util public utility apis
org.eclipse.wst.jsdt.internal.codeassist support for code assist and selection
org.eclipse.wst.jsdt.internal.codeassist.complete support for code assist
org.eclipse.wst.jsdt.internal.codeassist.impl support for code assist
org.eclipse.wst.jsdt.internal.codeassist.select support for code selection
org.eclipse.wst.jsdt.internal.compiler validation code
org.eclipse.wst.jsdt.internal.compiler.ast internal javascript AST (Abstract Syntax Tree)
org.eclipse.wst.jsdt.internal.compiler.batch support for batch validation
org.eclipse.wst.jsdt.internal.compiler.classfmt  ??
org.eclipse.wst.jsdt.internal.compiler.env  ??
org.eclipse.wst.jsdt.internal.compiler.flow support for analyzing code flow for unused vars, etc
org.eclipse.wst.jsdt.internal.compiler.impl implementation of public apis
org.eclipse.wst.jsdt.internal.compiler.lookup support for resolving var/function references
org.eclipse.wst.jsdt.internal.compiler.parser the parser
org.eclipse.wst.jsdt.internal.compiler.parser.diagnose the diagnose parser used when there are syntax errors
org.eclipse.wst.jsdt.internal.compiler.problem support for problem messages
org.eclipse.wst.jsdt.internal.compiler.util parser/validator utilities
org.eclipse.wst.jsdt.internal.core implementation of public apis
org.eclipse.wst.jsdt.internal.core.builder implementation of eclipse builder extension
org.eclipse.wst.jsdt.internal.core.dom.rewrite support for updating code on DOM changes
org.eclipse.wst.jsdt.internal.core.hierarchy support for generating class hierarchy
org.eclipse.wst.jsdt.internal.core.index support for indexing the model, used by search
org.eclipse.wst.jsdt.internal.core.interpret javascript interpreter - under development , currently not used
org.eclipse.wst.jsdt.internal.core.interpret.builtin implementation of javascript language functions used by interpreter
org.eclipse.wst.jsdt.internal.core.search searching functions
org.eclipse.wst.jsdt.internal.core.search.indexing indexing of javascript
org.eclipse.wst.jsdt.internal.core.search.matching functions to determine if possible search match is exact match
org.eclipse.wst.jsdt.internal.core.search.processing search
org.eclipse.wst.jsdt.internal.core.util internal utilities
org.eclipse.wst.jsdt.internal.formatter formatter implementation
org.eclipse.wst.jsdt.internal.formatter.align formatter implementation
org.eclipse.wst.jsdt.internal.formatter.comment comment formatter implementation
org.eclipse.wst.jsdt.internal.oaametadata support for OpenAjax metadata
org.eclipse.wst.jsdt.launching misc utilities
org.eclipse.wst.jsdt.libraries Library support

JSDT UI

User interface code

Core plugin packages
package function
org.eclipse.wst.jsdt.internal.corext refactoring support
org.eclipse.wst.jsdt.internal.corext.buildpath support for include path editing
org.eclipse.wst.jsdt.internal.corext.callhierarchy support for call hierarchy
org.eclipse.wst.jsdt.internal.corext.codemanipulation support for code refactoring
org.eclipse.wst.jsdt.internal.corext.dom
org.eclipse.wst.jsdt.internal.corext.dom.fragments support for manipulating dom fragments
org.eclipse.wst.jsdt.internal.corext.fix support for quick fix
org.eclipse.wst.jsdt.internal.corext.javadoc support for jsdoc editing
org.eclipse.wst.jsdt.internal.corext.refactoring support for refactoring
org.eclipse.wst.jsdt.internal.corext.refactoring.base support for refactoring
org.eclipse.wst.jsdt.internal.corext.refactoring.binary
org.eclipse.wst.jsdt.internal.corext.refactoring.changes refactoring change classes
org.eclipse.wst.jsdt.internal.corext.refactoring.code refactoring of code segments
org.eclipse.wst.jsdt.internal.corext.refactoring.code.flow support for refactoring of code segments
org.eclipse.wst.jsdt.internal.corext.refactoring.delegates support for "create delegates" action
org.eclipse.wst.jsdt.internal.corext.refactoring.generics currently unused
org.eclipse.wst.jsdt.internal.corext.refactoring.nls currently unused
org.eclipse.wst.jsdt.internal.corext.refactoring.nls.changes
org.eclipse.wst.jsdt.internal.corext.refactoring.participants
org.eclipse.wst.jsdt.internal.corext.refactoring.rename rename refactoring
org.eclipse.wst.jsdt.internal.corext.refactoring.reorg copy/move refactoring
org.eclipse.wst.jsdt.internal.corext.refactoring.scripting support for scripiting of refactoring
org.eclipse.wst.jsdt.internal.corext.refactoring.sef encapsulate field refactoring
org.eclipse.wst.jsdt.internal.corext.refactoring.structure
org.eclipse.wst.jsdt.internal.corext.refactoring.structure.constraints
org.eclipse.wst.jsdt.internal.corext.refactoring.surround
org.eclipse.wst.jsdt.internal.corext.refactoring.tagging
org.eclipse.wst.jsdt.internal.corext.refactoring.typeconstraints currently unused
org.eclipse.wst.jsdt.internal.corext.refactoring.typeconstraints.types currently unused
org.eclipse.wst.jsdt.internal.corext.refactoring.typeconstraints.typesets currently unused
org.eclipse.wst.jsdt.internal.corext.refactoring.typeconstraints2 currently unused
org.eclipse.wst.jsdt.internal.corext.refactoring.util refactoring utilities
org.eclipse.wst.jsdt.internal.corext.template.java support for templates
org.eclipse.wst.jsdt.internal.corext.util
org.eclipse.wst.jsdt.internal.ui
org.eclipse.wst.jsdt.internal.ui.actions implementation of actions
org.eclipse.wst.jsdt.internal.ui.browsing currently unused - support for browse perspective
org.eclipse.wst.jsdt.internal.ui.callhierarchy ui for call hierarchy
org.eclipse.wst.jsdt.internal.ui.commands
org.eclipse.wst.jsdt.internal.ui.compare compare ui
org.eclipse.wst.jsdt.internal.ui.dialogs various diaglogs
org.eclipse.wst.jsdt.internal.ui.dnd drag/drop support
org.eclipse.wst.jsdt.internal.ui.filters implementation of view filters
org.eclipse.wst.jsdt.internal.ui.fix automatic cleanup functions
org.eclipse.wst.jsdt.internal.ui.infoviews various views
org.eclipse.wst.jsdt.internal.ui.javadocexport export of js doc
org.eclipse.wst.jsdt.internal.ui.javaeditor javascirpt editor implementation
org.eclipse.wst.jsdt.internal.ui.javaeditor.saveparticipant
org.eclipse.wst.jsdt.internal.ui.javaeditor.selectionactions change selection actions
org.eclipse.wst.jsdt.internal.ui.model
org.eclipse.wst.jsdt.internal.ui.navigator implementation of navigator
org.eclipse.wst.jsdt.internal.ui.packageview implementation of script explorer
org.eclipse.wst.jsdt.internal.ui.preferences preferences ui
org.eclipse.wst.jsdt.internal.ui.preferences.cleanup ui for cleanup preferences
org.eclipse.wst.jsdt.internal.ui.preferences.formatter ui for formatter preferences
org.eclipse.wst.jsdt.internal.ui.refactoring ui for refactoring preferences
org.eclipse.wst.jsdt.internal.ui.refactoring.actions actions for refactoring
org.eclipse.wst.jsdt.internal.ui.refactoring.binary
org.eclipse.wst.jsdt.internal.ui.refactoring.code
org.eclipse.wst.jsdt.internal.ui.refactoring.contentassist
org.eclipse.wst.jsdt.internal.ui.refactoring.nls current unused
org.eclipse.wst.jsdt.internal.ui.refactoring.nls.search
org.eclipse.wst.jsdt.internal.ui.refactoring.reorg move/copy/delete
org.eclipse.wst.jsdt.internal.ui.refactoring.sef
org.eclipse.wst.jsdt.internal.ui.search search ui
org.eclipse.wst.jsdt.internal.ui.text javascript source editing utilites
org.eclipse.wst.jsdt.internal.ui.text.comment comment editing
org.eclipse.wst.jsdt.internal.ui.text.correction quick fix implementation
org.eclipse.wst.jsdt.internal.ui.text.folding folding implementation
org.eclipse.wst.jsdt.internal.ui.text.html editing of html inside jsdoc
org.eclipse.wst.jsdt.internal.ui.text.java content assist implementation
org.eclipse.wst.jsdt.internal.ui.text.java.hover hover help
org.eclipse.wst.jsdt.internal.ui.text.javadoc jsdoc editing
org.eclipse.wst.jsdt.internal.ui.text.spelling spell checking
org.eclipse.wst.jsdt.internal.ui.text.spelling.engine
org.eclipse.wst.jsdt.internal.ui.text.template.contentassist content assist templates
org.eclipse.wst.jsdt.internal.ui.text.template.preferences template editing
org.eclipse.wst.jsdt.internal.ui.typehierarchy type hierarchy ui
org.eclipse.wst.jsdt.internal.ui.util utilities
org.eclipse.wst.jsdt.internal.ui.viewsupport view utilities
org.eclipse.wst.jsdt.internal.ui.wizards wizards
org.eclipse.wst.jsdt.internal.ui.wizards.buildpaths include path editing
org.eclipse.wst.jsdt.internal.ui.wizards.buildpaths.newsourcepage
org.eclipse.wst.jsdt.internal.ui.wizards.dialogfields
org.eclipse.wst.jsdt.internal.ui.workingsets
org.eclipse.wst.jsdt.libraries
org.eclipse.wst.jsdt.ui
org.eclipse.wst.jsdt.ui.actions
org.eclipse.wst.jsdt.ui.dialogs
org.eclipse.wst.jsdt.ui.project
org.eclipse.wst.jsdt.ui.refactoring
org.eclipse.wst.jsdt.ui.search
org.eclipse.wst.jsdt.ui.text
org.eclipse.wst.jsdt.ui.text.folding
org.eclipse.wst.jsdt.ui.text.java
org.eclipse.wst.jsdt.ui.text.java.hover
org.eclipse.wst.jsdt.ui.wizards

Generating the parser

Follow the instructions at http://www.eclipse.org/jdt/core/howto/generate%20parser/generateParser.html for generating the parser. The parser grammer file is located in cvs at sourceediting/plugins/org.eclipse.wst.jsdt.core/grammer/js.g


Design

The JavaScript Development Tools design would use the JDT design with the necessary adjustments made for JavaScript.

As far as the JavaScript Development Tools design is concerned, the major differences between Java and JavaScript are:

  • Javascript has no explicit typing support, whereas in Java everything is typed, and incorporates argument types in function signatures.
  • At the top level, a JavaScript file can contain any program statement, whereas a Java file only contains a Class.
  • JavaScript has no classpath/jar file concept

Other areas where the java/JavaScript differences will necessitate changes:

  • syntax differences - parse definitions
  • additional program elements with no correspondence in Java
    • object literals
    • for (var in collection)

Inferred Types

In order for some JDT-based functionality (such as code completion) to work correctly, class type information needs to be available. This information is not available in JavaScript, but it can be inferred in many cases. A type inferring framework has been put in place to support this functionality, examining the JavaScript Abstract Syntax Tree (AST) and generating "virtual" class information. Type inferring is extensible, so the unique conventions among various JavaScript Toolkits (e.g. Dojo, jQuery, Prototype, etc.) can be handled, although through WTP 3.1 it has remained provisional. Inferred types may participate in refactoring, but their visibility within the UI is still being discussed.

JavaScript file handling

Java files have a very top down structure, where files only contain classes, which only contain fields, methods, and inner classes, and program statements only contained within methods. Because of this, some JDT functionality will not work for JavaScript, because a program statement can be directly at the top of a JavaScript file. The relevant JDT code is still undergoing refactorings to support these scenarios.

Variable/function resolution

In Java, everything is resolvable because of the classpath, package structure, and import statements. This has no correspondence in JavaScript, where functions themselves may also be resolvable as types.

Libraries

The JSDT mimics the JDT Java Build Path and classpath container mechanisms to offer JavaScript library support. JSDT libraries are collections of JavaScript source files that have prototyped object/class definitions and JSDoc. The inference engine then models these libraries and places each object/field/function in the projects Global Scope, making them available to every JavaScript file in the project. Because the library contents are not directly executed by JSDT, it isn't necessary for them to contain the complete implementation of those objects. In fact, the standard JavaScript runtime is itself presented as a source file containing stubs for the specification's contents. Bindings for nonstandard and future runtimes are similarly easy to create and use.

To illustrate-- the JSDT contains a FireFox library plugin with about 150k of JavaScript and JsDoc. This library represents the class structure within the FireFox browser that is accessible to a web page's JavaScript, but does not contain any implementation to the functions it declares. If a user wishes to target their JavaScript source to FireFox specifically, they would add the FireFox library to their project and gain content completion and hover help for the FireFox objects. Users may also limit the objects/functions/fields visible in the project by adding or removing libraries.

Libraries aren't limited to browser objects. AJAX runtimes can fit nicely into libraries, as would a website's standard set of utility functions. Really the possibilities are limitless. And the library mechanism is extremely easy to expand both by the end-user or through extension points.

Functionality mapping

This table shows how the JDT functionality corresponds to the JavaScript functionality. It does not include anything where there is a direct one to one correspondence.

JDT function JSDT function
Build path Libraries + Global Scope (frequently referred to as an "Include Path")
JDK level (1.4 vs 1.5) ECMAscript level 3 vs 4 (v.3 supported now, v.4 will not be implemented as the specification was abandoned)
Compile Validation & flow analysis

Extension Points

The JSDT functionality is embeddable. This means, for instance, that the JavaScript editing capabilities is embeddable within HTML and JSP Editors, both within script tags, and script attribute values. The JSDT is flexible so script support in other languages is possible using translator interfaces being planned for WTP 3.1.

The following JSDT extension points are supported :

  • Global Scope variable initializer
  • Global Scope container initializer core
  • Code formatter
  • Validation participant
 Currently the JSDT is represented in an AST.

The following jsdt.ui extension points will be supported :

  • Global Scope container initializer ui (Wizzard, content assist images and type/text naming)
  • javascript element filter
  • javaScriptEditorTextHovers
  • jsdocCompletionProcessor
  • quickFixProcessors
  • quickAssistProcessors
  • foldingStructureProviders
  • queryParticipants
  • javaScriptCompletionProposalComputer
  • javaScriptCompletionProposalSorters