Difference between revisions of "New Help for Old Friends V"

Latest revision as of 18:24, 17 December 2018

This page to to collect miscellaneous notes and pointers to changes coming up in the WTP 3.2 release. Its purpose it to be a central "jumping off" point for those adopters of WTP 3.1 that are moving to WTP 3.2. Most of this information may be already contained in various mailing lists and Bugzilla reports, but it is believed best to have a central place to get people started. Adopters: if you run into trouble or notice things that are not covered here, please let us know (wtp-dev is a good place). Web Tools is a Platform and we strive to provide compatible API evolution with clear migration instructions, etc., for the future.

One thing we have learned in the past is that some adopters do not move with us to every new release. Some early adopters went from 0.7 directly to 1.5, for example. Unfortunately, it is difficult to present the information in that way, covering perhaps multiple changes across different version ranges.

Note: as these notes develop and grow in number, they may occasionally be re-organized into categories, etc.

Server tools

• Module adopters changes [bug#291833]

Classes: ModuleDelegate and ProjectModule

The new changes introduce a new method getPath(IModule) inside of ModuleDelegate, this new method provide a way to get the path relative to its parent of the given module contained within the application. A default implementation that returns 'null' was provided but adopters should strongly consider to provide a proper implementation.

Common Components

• 218438 The org.eclipse.wst.common.ui.provisional.editors workaround package has been removed. Its classes offered a workaround to a post selection firing problem that has long since been fixed in the Eclipse Platform.
• The version of org.eclipse.wst.common.snippets has been incremented to 1.2.0 due to enhancement 282114.
• Bug 308326 - Validation Framework invokes the V1 validators too often

   The V1 validator is currently called per resource by the validation framework. A new element, runStrategy, is added in the org.eclipse.wst.validation.validator extension point. By specifying 'true' in the 'project' attribute, the validator will be called per project by the validation framework instead of per resource.

   <extension
         point="org.eclipse.wst.validation.validator">
    ...
        <runStrategy
             project="true">
        </runStrategy>
    ...
   </extension>

• When using faceted project framework API, make sure not to do direct string comparison on facet id and version string. Use == and compareTo operations on IProjectFacet and IProjectFacetVersion objects instead. These objects are maintained as singletons by the system and you can access them via static methods on ProjectFacetsManager class. This advice is not new for Helios release, but it becomes more important due to introduction of an aliasing subsystem that makes it easier for facet authors to manager evolution of their facets. In particular, with aliasing, you can not assume that ProjectFacetsManager.getProjectFacet( x ).getId().equals( x ) or that [IProjectFacet].getVersion( y ).getVersionString().equals( y ). Avoid string comparisons for proper operation with or without aliased facets.
  • In Helios release, the Java facet took advantage of the aliasing system to resolve several long-standing issues. See Bug 298905 and Bug 298906 for more information. If your code interacts with the Java facet at API-level, you may want to review it to make sure that string comparisons aren't being performed.

Java EE

• org.eclipse.jst.j2ee.core - Added support for Java EE 6, changed over to using javax.xml.namespace.QName for ServiceRef, EnvEntryType is not really used now in EnvEntry (any type can be used now, so it is a String), previously generic types now have specific type associations, plugin version id was bumped to 1.2.0 - see bug 252615 for details/comments.
• Modifications to the structure of J2EEFlexProjDeployable and other similar classes has brought some behaviour which was common in EAR projects into Web projects as well, which some server adapters may see as a regression or an unexpected change in behaviour. Specifically, binary files inside a web project such as EJBs or Clients may now be exposed as child modules rather than simple resources. Please see Bug 309206 for more details.
• Deprecated resources deleted from WTP 3.2
  • Module mapping code with bug 280151
    • class org/eclipse/jst/j2ee/internal/provider/J2EEUtilityJavaProjectsItemProvider.java
    • class org/eclipse/jst/j2ee/internal/provider/J2EEModulemapItemProviderAdapterFactory.java
    • class org/eclipse/jst/j2ee/internal/provider/UtilityJARMappingItemProvider.java
    • class org/eclipse/jst/j2ee/internal/provider/ModulemapItemProviderAdapterFactory.java
    • class org/eclipse/jst/j2ee/internal/provider/ModulemapItemProviderAdapter.java
    • class org/eclipse/jst/j2ee/internal/provider/ModuleMappingItemProvider.java
    • class org/eclipse/jst/j2ee/internal/provider/EARProjectMapItemProvider.java
    • class org/eclipse/jst/j2ee/internal/provider/ModulemapEditPlugin.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModulemapInit.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModulemapSwitch.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/UtilityJARMappingImpl.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModulemapAdapterFactory.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/UtilityJARMapping.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModulemapPackage.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModulemapPackageImpl.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModulemapFactory.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModuleMappingImpl.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModuleMapping.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/ModulemapFactoryImpl.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/EARProjectMapImpl.java
    • class org/eclipse/jst/j2ee/internal/earcreation/modulemap/EARProjectMap.java
  • Import classes code with bug 160088
    • class org/eclipse/jst/j2ee/internal/wizard/WizardClassesImportPage1.java
    • class org/eclipse/jst/j2ee/internal/wizard/WizardClassesImportMainPage.java
    • class org/eclipse/jst/j2ee/internal/wizard/ClassesImportWizard.java
    • class org/eclipse/jst/j2ee/internal/wizard/PackageNameResolver.java
    • class org/eclipse/jst/j2ee/internal/wizard/MinimizedFileSystemElement.java
  • Dead refactoring code (replaced with LTK) bug 274157
    • class org/eclipse/jst/j2ee/internal/actions/ImportClassesAction.java
    • class org/eclipse/jst/j2ee/internal/actions/J2EEDeleteAction.java
    • class org/eclipse/jst/j2ee/internal/actions/J2EEDeleteModuleActionPopulator.java
    • class org/eclipse/jst/j2ee/internal/actions/J2EEModuleRenameChange.java
    • class org/eclipse/jst/j2ee/internal/actions/J2EERenameAction.java
    • class org/eclipse/jst/j2ee/internal/actions/J2EERenameParticipant.java
    • class org/eclipse/jst/j2ee/internal/actions/J2EERenameResourceAction.java
    • class org/eclipse/jst/j2ee/internal/actions/J2EEResourceOpenListener.java
    • class org/eclipse/jst/j2ee/internal/actions/NewAppClientComponentAction.java
    • class org/eclipse/jst/j2ee/internal/actions/NewEARComponentAction.java
    • class org/eclipse/jst/j2ee/internal/actions/WTPBaseAction.java
    • class org/eclipse/jst/j2ee/internal/dialogs/DeleteEARComposite.java
    • class org/eclipse/jst/j2ee/internal/dialogs/DeleteEARDialog.java
    • class org/eclipse/jst/j2ee/internal/dialogs/DeleteModuleComposite.java
    • class org/eclipse/jst/j2ee/internal/dialogs/DeleteModuleDialog.java
    • class org/eclipse/jst/j2ee/internal/dialogs/DeleteModuleReferencesComposite.java
    • class org/eclipse/jst/j2ee/internal/dialogs/J2EEDeleteDialog.java
    • class org/eclipse/jst/j2ee/internal/dialogs/J2EEDeleteUIConstants.java
    • class org/eclipse/jst/j2ee/internal/dialogs/J2EEDeployStatusDialog.java
    • class org/eclipse/jst/j2ee/internal/dialogs/J2EEDeployUIConstants.java
    • class org/eclipse/jst/j2ee/internal/dialogs/J2EERenameDialog.java
    • class org/eclipse/jst/j2ee/internal/dialogs/J2EERenameUIConstants.java
    • class org/eclipse/jst/j2ee/internal/dialogs/RenameEARComposite.java
    • class org/eclipse/jst/j2ee/internal/dialogs/RenameEARDialog.java
    • class org/eclipse/jst/j2ee/internal/dialogs/RenameModuleComposite.java
    • class org/eclipse/jst/j2ee/internal/dialogs/RenameModuleDialog.java
    • class org/eclipse/jst/j2ee/internal/dialogs/RenameModuleReferencesComposite.java
    • class org/eclipse/jst/j2ee/internal/ear/actions/ArchiveEARUIResourceHandler.java
    • class org/eclipse/jst/j2ee/internal/ear/actions/EARImportListContentProvider.java
    • class org/eclipse/jst/j2ee/internal/ear/actions/ExportEARAction.java
    • class org/eclipse/jst/j2ee/internal/ear/actions/ImportEARAction.java
    • class org/eclipse/jst/j2ee/internal/ear/actions/ModulesProvider.java
    • class org/eclipse/jst/j2ee/internal/delete/ClasspathDeleteInfo.java
    • class org/eclipse/jst/j2ee/internal/delete/DeleteOptions.java
    • class org/eclipse/jst/j2ee/internal/rename/ClasspathRenameInfo.java
    • class org/eclipse/jst/j2ee/internal/rename/RenameOptions.java

JSDT

Perspective changes

The JavaScript Script Explorer view has been removed. All previous functionality is now available in the Project Explorer view, or adopter views utilizing the Common Navigator Framework.

Include Path added for web projects

Static and Dynamic Web Projects now have their WebContent folders added to the JavaScript project Include Path by default.

JavaScript Facet changes

The JavaScript Facet has been changed so that it can not be removed from new projects once installed (it is now fixed). This better reflects the reality of no removal operation existing in this or prior releases.

Other changes

• 293996 Main JavaScript preference page moved back to top-level

Source Editing

Versions

Code Folding

(PROVISIONAL)

Code folding in the Structured Source Editors (HTML, XML, JSP, CSS, DTD) has been completely re-factored. The previous code folding implementation used the Node Adapter framework the new code folding uses the Reconciling Strategy framework, see 281380 for the reasons behind this change.

If an implementer wishes to write their own folding strategy for a structured source editor then they must create an extension such as:

<extension point="org.eclipse.wst.sse.ui.editorConfiguration">
    <provisionalConfiguration
        type="foldingstrategy"
        class="org.eclipse.wst.xml.ui.internal.projection.XMLFoldingStrategy"
        target="org.eclipse.wst.html.core.htmlsource" />
</extension>

• type - must be "foldingstrategy"
• class - must be a class that extends org.eclipse.wst.sse.ui.internal.projection.AbstractStructuredFoldingStrategy
  • There are two abstract methods that the implementer must implement, and both are typically short, for examples see:
    • org.eclipse.wst.css.ui.internal.projection.CSSFoldingStrategy
    • org.eclipse.wst.dtd.ui.internal.projection.DTDFoldingStrategy
    • org.eclipse.wst.xml.ui.internal.projection.XMLFoldingStrategy
• target - is a structured source editor content type ID
  • any given content type ID can only have one associated folding strategy, if more then one extension specifies the same content type ID then whichever extension gets loaded first is the one that is used.

Notes:

• As of right now the XML, HTML, and JSP editors all use the XMLFoldingStrategy as their folding strategy.

• Removed Resources
  • org.eclipse.jst.jsp.ui.internal.projection (entire package)
    • ProjectionAnnotationModelChanges
    • ProjectionModelNodeAdapterFactoryHTML
    • ProjectionModelNodeAdapterFactoryJSP
    • ProjectionModelNodeAdapterHTML
    • ProjectionModelNodeAdapterJSP
    • ProjectionViewerInformation
    • StructuredTextFoldingProviderJSP
  • org.eclipse.wst.css.ui.internal.projection
    • ProjectionAnnotationModelChanges
    • ProjectionModelNodeAdapterFactoryCSS
    • ProjectionModelNodeAdapterCSS
    • ProjectionViewerInformation
    • StructuredTextFoldingProviderCSS
  • org.eclipse.wst.dtd.ui.internal.projection
    • StructuredTextFoldingProviderDTD
  • org.eclipse.wst.html.ui.internal.projection (entire package)
    • ProjectionAnnotationModelChanges
    • ProjectionModelNodeAdapterFactoryHTML
    • ProjectionModelNodeAdapterHTML
    • ProjectionViewerInformation
    • StructuredTextFoldingProviderHTML
  • org.eclipse.wst.html.ui.internal.projection
    • ProjectionAnnotationModelChanges
    • ProjectionModelNodeAdapterFactoryXML
    • ProjectionModelNodeAdapterXML
    • ProjectionViewerInformation
    • StructuredTextFoldingProviderXML
  • org.eclipse.wst.see.ui.internal.projection
    • IStructuredTextFoldingProvider
• Added Resources
  • org.eclipse.wst.see.ui.internal.projection.AbstractStructuredFoldingStrategy
  • org.eclipse.wst.css.ui.internal.projection.CSSFoldingStrategy
  • org.eclipse.wst.dtd.ui.internal.projection.DTDFoldingStrategy
  • org.eclipse.wst.xml.ui.internal.projection.XMLFoldingStrategy

Character Pairing

The Structured Text Editor now supports character pairing. This allows for immediate insertion of a "paired" character following a user-input character. Additional functionality includes closing the pairing when the paired character is entered, completing the pair by pressing enter, or tabbing to the position after the inserted character.

Below is an example of a character pairing that will function on the files with a content type of org.eclipse.core.runtime.xml but only for two specific partitions org.eclipse.wst.xml.XML_DEFAULT and org.eclipse.wst.xml.XML_DECL.

<extension
       point="org.eclipse.wst.sse.ui.characterPairing">
    <inserter
          class="org.eclipse.wst.xml.ui.internal.text.CharacterPairInserter"
          id="org.eclipse.wst.xml.ui.inserter">
       <contentTypeIdentifier
             id="org.eclipse.core.runtime.xml" partitions="org.eclipse.wst.xml.XML_DEFAULT,org.eclipse.wst.xml.XML_DECL">
       </contentTypeIdentifier>
    </inserter>
 </extension>

The class provided by inserter must extend org.eclipse.wst.sse.ui.typing.AbstractCharacterPairInserter. This class is responsible for identifying which characters will trigger pairing, what character is paired with that trigger, and if the trigger should execute. See org.eclipse.wst.xml.ui.internal.text.CharacterPairInserter for an implementation used in the XML editor.

Semantic Highlighting

The semantic highlighting framework has been extended. org.eclipse.wst.sse.ui.ISemanticHighlightingExtension provides the user with a new method of determining if a region of the editor is consumable by the highlighting strategy based on the org.eclipse.wst.sse.core.internal.provisional.IndexedRegion that contains the region.

Additionally, a semantic highlighting strategy can now have its style determined based on the value of a single preference key instead of several keys as before. To do this, the attribute styleStringKey must be added to the semanticHighlighting extension point element. This key identifies a preference value in the format of RGB foreground (#rrggbb) | RGB background (#rrggbb) | bold (true/false) | italic (true/false) | strikethrough (true/false) | underline (true/false)

Quick Outline

Structured Source Editors now support Quick Outlines. The Quick Outline allows for representation of the model in an outline where elements of the outline can be filtered based on the content of the filter text box. A Quick Outline requires an implementation of org.eclipse.wst.sse.ui.quickoutline.AbstractQuickOutlineConfiguration that provides the Quick Outline with a content provider, label provider, and optionally, a content selection provider that translates the selection between the editor and the outline.

The Quick Outline is an editor configuration for a Structured Text Editor whose target is a specific content type. Below is the editor configuration for XML's Quick Outline.

<extension point="org.eclipse.wst.sse.ui.editorConfiguration">
...
<quickOutlineConfiguration
	class="org.eclipse.wst.xml.ui.internal.quickoutline.XMLQuickOutlineConfiguration"
	target="org.eclipse.core.runtime.xml, org.eclipse.wst.xml.core.xmlsource" />
...
</extension>

If the selection between the editor does not directly correspond to the selection in the Quick Outline, an implementation of org.eclipse.wst.sse.ui.IContentSelectionProvider should be provided by the quick outline configuration. For example, if a text node is selected in the XML editor, XML's quick outline configuration will use its content selection provider to select the parent element of the text node for display in the Quick Outline.

DOM Conformity

• 244415 Attribute nodes now return the correct namespace for the XML prefix.
• 272378 Element nodes no longer return null for getAttribute/getAttributeNS when the element does not have that attribute

Content Assist

Summary

Content assist for Structured Source Editors (HTML, XML, JSP, CSS, DTD) has been completely re-implemented. The goal of this work was to make content assist across all Structured Source Editors centralized, more extensible, and with less duplication. The basis for this change was the content assist framework used by JDT (also used by JSDT), thus any implementers familiar with JDT's framework should be immediately comfortable with the new Structured Source Editor content assist framework. This change has also brought paged content assist to Structured Source Editors, allowing multiple invocations of content assist to reveal multiple filtered pages of content assist suggestions, just like JDT. Which of these pages and in which order they appear is completely configurable by user preferences.

All work for this change was done under Bug 258999. For an example of how JSDT migrated their content assist contributions from the new to old framework see Bug 309131.

Legacy Contributions

In the past extenders would use the org.eclipse.wst.sse.ui.editorConfiguration with a provisionalConfiguration element of type contentassistprocessor to contribute content assist suggestions to Structured Source Editors. This provisional configuration type has now been deprecated by the new framework. Any contributions through the now deprecated provisional configuration will still be picked up and will be displayed at the end of the default page (first page) of content assist suggestions shown to the user. While these contributions are still being picked up it is very strongly recommended that implementors of the deprecated provisional configuration migrate to the new framework.

New Extension Points

There are two new extension points org.eclipse.wst.see.ui.completionProposal and org.eclipse.wst.see.ui.completionProposalCategoriesConfiguration. The schema's for these extension points are well documented and should be referred to for more in depth documentation. The completionProposal extension is what is used to contribute content assist categories (pages) and computers (like the old processors) to Structured Source Editors. The completionProposalCategoriesConfiguration extension is only needed if an adopter of Structured Source Editors has an editor for a custom content type and would like to allow users to have control over the visibility and order of pages(user)/categories(internal) for the custom content type.

The completionProposal extension allows an extender to do three main things:

• add proposal computers - code that actually generates content assist suggestions
• add proposal categories - categories are represented to the user as pages of content assist and are made up of one or more computers
• Extended the activation context of an already existing computer

Example

The following example is taken from the schema documentation for the completionProposal extension point.

<extension point="org.eclipse.wst.sse.ui.completionProposal">
  <proposalCategory
      icon="icons/full/obj16/tag-macro.gif"
      id="org.eclipse.wst.xml.ui.proposalCategory.xmlTemplates"
      name="XML Templates">
  </proposalCategory>
  <proposalComputer
      activate="false"
      categoryId="org.eclipse.wst.xml.ui.proposalCategory.xmlTemplates"
      class="org.eclipse.wst.xml.ui.internal.contentassist.XMLTemplatesCompletionProposalComputer"
      id="org.eclipse.wst.xml.ui.proposalComputer.xmlTemplates">
    <contentType
        id="org.eclipse.core.runtime.xml">
    </contentType>
  </proposalComputer>
</extension>

<extension point="org.eclipse.wst.sse.ui.completionProposal">
  <proposalComputerExtendedActivation
      id="org.eclipse.wst.xml.ui.proposalCategory.xmlTemplates">
    <contentType
        id="org.eclipse.jst.jsp.core.jspsource">
      <partitionType
          id="org.eclipse.wst.xml.XML_DEFAULT">
      </partitionType>
    </contentType>
  </proposalComputerExtendedActivation>
</extension>

Explanation:

• Plugin A
  • define a proposal category named "XML Templates"
  • define a proposal computer XMLTemplatesCompletionProposalComputer that is part of the "XML Templates" category. This new computer will be activated for any partition type on the XML content type.
• Plugin B
  • Extends the activation context of the XMLTemplatesCompletionProposalComputer defined in Plugin A to the XML_DEFAULT partition type on JSP documents.

New API

• org.eclipse.wst.sse.ui.contentassist
  • ICompletionProposalComputer - interface extended when adding a new content assist computer
  • StructuredContentAssistProcessor - the processor that must be used by an editor if it wants to take advantage of the new content assist framework
• org.eclipse.wst.sse.ui.preferences
  • ICompletionProposalCategoriesConfigurationReader - implemented by users of the org.eclipse.wst.see.ui.completionProposalCategoriesConfiguration extension
  • ICompletionProposalCategoriesConfigurationWriter - maybe implemented by users of the org.eclipse.wst.see.ui.completionProposalCategoriesConfiguration extension
  • AbstractCompletionProposalCategoriesConfiguration - an implementation of ICompletionProposalCategoriesConfigurationReader and ICompletionProposalCategoriesConfigurationWriter that maybe extended by users of the org.eclipse.wst.see.ui.completionProposalCategoriesConfiguration extension
  • CodeAssistCyclingConfigurationBlock - for users of the org.eclipse.wst.see.ui.completionProposalCategoriesConfiguration extension who wish to give users preferences for changing the order and enablement of content assist pages/categories.

Note: If an extender has a custom content type with an implementation of StructuredTextViewerConfiguration and would like to take advantage of the new content assist then the implementation of StructuredTextViewerConfiguration should either no longer override StructuredTextViewerConfiguration#getContentAssistProcessors or the implementation should return an instance of StructuredContentAssistProcessor in their implementation of StructuredTextViewerConfiguration#getContentAssistProcessors. This is because all the work of determining which pages get displayed, in which order, for which partition types in which content types and then cycling through these pages is done by StructuredContentAssistProcessor. StructuredContentAssistProcessor is usable as is or it can extended and specific methods can be overridden to customize its behavior. See the documentation and type hierarchy of StructuredContentAssistProcessor for examples.

Deprecated Code

While none of this deprecated code was public API it is likely many adopters were using it anyways and should take careful note to stop using it. This is for multiple reasons. This code will no longer be supported. This means if an adopter finds an issue with this code the adopter will be asked to move to the new content assist framework rather then have the development team investigate deprecated code. This code will also be totally removed at some point because it is marked as internal and is no longer used internally. For these reasons adopters are again strongly recommended to move to the new framework.

• org.eclipse.wst.xml.ui.internal.contentassist
  • AbstractContentAssistProcessor
  • XMLContentAssistProcessor
  • NoRegionContentAssistProcessor
• org.eclipse.wst.html.ui.internal.contentassist
  • HTMLContentAssistProcessor
• org.eclipse.jst.jsp.ui.internal.contentassist
  • JSPStructuredContentAssistProcessor
  • JSPContentAssistProcessor
  • JSPELCompletionProcessor
  • JSPTaglibDirectiveContentAssistProcessor
  • JSPCompletionProcessor
  • JSPJavaContentAssistProcessor
  • JSPPropertyContentAssistProcessor
  • JSPUseBeanContentAssistProcessor
• org.eclipse.wst.css.ui.internal.contentassist
  • CSSContentAssistProcessor

Other changes

• 281914 Deprecated org.eclipse.wst.xml.ui.internal.tabletree.XMLEditorPluginHOLD_OLD class removed
• 289258 JSP Expression elements now translate so that the result of the expression is the direct argument to out.print().

Changes in Feature Content or Structure

WST.WS Features moved to JST.WEB Feature

• Bug 295151: move webservices out of non-Java web developer features.

The wst.ws* features used to be 'included' in the wst.web* features. They were moved to the jst.web* features.

New JSF Feature added, moving some JSF bundles

• Bug 302896: Break out JSF plugins into distinct features from the rest of jst.web

Bundles were move from one feature, to a new JSF feature, so anyone who used to prereq or install

org.eclipse.jst.web_core.feature, or

org.eclipse.jst.web_ui.feature

will now have to also prereq or install

org.eclipse.jsf.feature

in order to have a pick up the same JSF plugins that moved.

Reference

This document ONLY covers changes between WTP 3.1 and WTP 3.2. See also: New Help for Old Friends IV (3.1), New Help for Old Friends III (3.0), New Help for Old Friends II (2.0), and the original New Help for Old Friends (1.5)