Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Handly/NewIn06"
m |
|||
| Line 11: | Line 11: | ||
=== On the Way to Non-Breaking Evolution === | === On the Way to Non-Breaking Evolution === | ||
| − | Building an API that can evolve without breaking is not easy, but it is vital for the long-term health of a project. The '''0.6''' release should get us closer to this goal by introducing ''contexts'' | + | Building an API that can evolve without breaking is not easy, but it is vital for the long-term health of a project. The '''0.6''' release should get us closer to this goal by introducing ''contexts'' and the ''model object'' as a means of facilitating future evolution of Handly. |
| + | |||
| + | ==== Contexts ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=499220 499220]) ==== | ||
Fundamentally, a context supplies values (data objects or services) associated with keys. When used as a method parameter or return value, it enables a more loosely coupled functional interaction and therefore allows for more independent variability of the participants of the interaction (a caller and a callee). | Fundamentally, a context supplies values (data objects or services) associated with keys. When used as a method parameter or return value, it enables a more loosely coupled functional interaction and therefore allows for more independent variability of the participants of the interaction (a caller and a callee). | ||
| Line 17: | Line 19: | ||
Composite contexts can emulate a ''dynamic scope'' or ''dynamic binding'' available in some programming languages and used to a great effect in such extensible systems as [https://www.gnu.org/software/emacs/emacs-paper.html EMACS]. | Composite contexts can emulate a ''dynamic scope'' or ''dynamic binding'' available in some programming languages and used to a great effect in such extensible systems as [https://www.gnu.org/software/emacs/emacs-paper.html EMACS]. | ||
| − | The interface <tt>org.eclipse.handly.context.IContext</tt> allows such context-facilitated functional interactions to remain type-safe by supporting two kinds of keys: <tt>org.eclipse.handly.util.Property</tt> and <tt>java.lang.Class</tt>. The <tt>Property</tt> class has been moved from the <tt>org.eclipse.handly.model</tt> package ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=498749 | + | The interface <tt>org.eclipse.handly.context.IContext</tt> allows such context-facilitated functional interactions to remain type-safe by supporting two kinds of keys: <tt>org.eclipse.handly.util.Property</tt> and <tt>java.lang.Class</tt>. The <tt>Property</tt> class has been moved from the <tt>org.eclipse.handly.model</tt> package ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=498749 498749]) and generalized to retain type information at runtime ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=498752 498752]) and to be able to provide a default value ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=498873 498873]). |
| + | |||
| + | As a first application of contexts in Handly, we have replaced the class <tt>org.eclipse.handly.model.ToStingStyle</tt> with a context ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=499540 499540]) and have also revised the signatures of a number of methods in the <tt>Element</tt> hierarchy, making them context-aware ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=500408 500408]). The new design should make it possible to evolve APIs in a non-breaking fashion by introducing new context properties or deprecating and replacing existing ones without changing the method signature, while making it easy to propagate context bindings across the call stack. | ||
| − | + | ==== The Model Object ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=500653 500653]) ==== | |
| − | Contexts | + | Contexts interplay with another new feature in Handly 0.6, the model object, which reifies the concept of the model as the owner of elements. The model object exposes a context (the ''model context''), which can supply information and services pertaining to the model as a whole. |
| − | One example of such a model-scoped service in '''0.6''' is the ''notification manager'' ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=505777 | + | One example of such a model-scoped service in '''0.6''' is the ''notification manager'' ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=505777 505777]). The introduction of notification manager API has allowed us to provide a fully-functional implementation of <tt>hWorkingCopyModeChanged()</tt> and <tt>NotifyingReconcileOperation</tt> right in the <tt>SourceFile</tt>, which previously needed to be duplicated across specific models. The only thing that model implementations will have to do to use this generic facility is to register a notification manager in the model context. |
The model object API also makes it possible to check the Handly ''API level'' supported by a model, which should enable future evolution of Handly without having to introduce "extension interfaces" such as <tt>IElement2</tt>, <tt>IElementImpl2</tt>, etc. to add new API methods. By checking the API level, generic code will be able to dynamically discover which API methods are supported by the model it is dealing with. | The model object API also makes it possible to check the Handly ''API level'' supported by a model, which should enable future evolution of Handly without having to introduce "extension interfaces" such as <tt>IElement2</tt>, <tt>IElementImpl2</tt>, etc. to add new API methods. By checking the API level, generic code will be able to dynamically discover which API methods are supported by the model it is dealing with. | ||
| Line 31: | Line 35: | ||
=== Other API Enhancements === | === Other API Enhancements === | ||
| − | * Support for files external to the workspace has been implemented on top of the Eclipse File System (EFS) API ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=500893 | + | * Support for files external to the workspace has been implemented on top of the Eclipse File System (EFS) API ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=500893 500893], [https://bugs.eclipse.org/bugs/show_bug.cgi?id=502000 502000]) |
| − | * The workspace-related functionality has been extracted from <tt>SourceFile</tt> to a new subclass, <tt>WorkspaceSourceFile</tt> ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=500676 | + | * The workspace-related functionality has been extracted from <tt>SourceFile</tt> to a new subclass, <tt>WorkspaceSourceFile</tt> ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=500676 500676]) |
| − | * Non-local file systems are now also supported ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=506453 | + | * Non-local file systems are now also supported ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=506453 506453], [https://bugs.eclipse.org/bugs/show_bug.cgi?id=506717 506717]) |
| − | * The buffer and working copy APIs have been revised and streamlined ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=505714 | + | * The buffer and working copy APIs have been revised and streamlined ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=505714 505714], [https://bugs.eclipse.org/bugs/show_bug.cgi?id=506332 506332]) |
| − | === Full | + | === Full List of Issues Addressed in This Release === |
0.6 - https://projects.eclipse.org/projects/technology.handly/releases/0.6/bugs | 0.6 - https://projects.eclipse.org/projects/technology.handly/releases/0.6/bugs | ||
Revision as of 02:22, 15 November 2016
New & Noteworthy for Handly 0.6
The 0.6 release is an incremental improvement of the entirely new design introduced in Handly 0.5. This release nearly completes the serious API (re-)work started a year ago in 0.4 and is expected to be a more stable base for early adopters.
Due to the API rework involved, this release introduces a number of breaking changes. Please see the migration guide if you are a current adopter.
Here are the highlights of this release.
On the Way to Non-Breaking Evolution
Building an API that can evolve without breaking is not easy, but it is vital for the long-term health of a project. The 0.6 release should get us closer to this goal by introducing contexts and the model object as a means of facilitating future evolution of Handly.
Contexts (499220)
Fundamentally, a context supplies values (data objects or services) associated with keys. When used as a method parameter or return value, it enables a more loosely coupled functional interaction and therefore allows for more independent variability of the participants of the interaction (a caller and a callee).
Composite contexts can emulate a dynamic scope or dynamic binding available in some programming languages and used to a great effect in such extensible systems as EMACS.
The interface org.eclipse.handly.context.IContext allows such context-facilitated functional interactions to remain type-safe by supporting two kinds of keys: org.eclipse.handly.util.Property and java.lang.Class. The Property class has been moved from the org.eclipse.handly.model package (498749) and generalized to retain type information at runtime (498752) and to be able to provide a default value (498873).
As a first application of contexts in Handly, we have replaced the class org.eclipse.handly.model.ToStingStyle with a context (499540) and have also revised the signatures of a number of methods in the Element hierarchy, making them context-aware (500408). The new design should make it possible to evolve APIs in a non-breaking fashion by introducing new context properties or deprecating and replacing existing ones without changing the method signature, while making it easy to propagate context bindings across the call stack.
The Model Object (500653)
Contexts interplay with another new feature in Handly 0.6, the model object, which reifies the concept of the model as the owner of elements. The model object exposes a context (the model context), which can supply information and services pertaining to the model as a whole.
One example of such a model-scoped service in 0.6 is the notification manager (505777). The introduction of notification manager API has allowed us to provide a fully-functional implementation of hWorkingCopyModeChanged() and NotifyingReconcileOperation right in the SourceFile, which previously needed to be duplicated across specific models. The only thing that model implementations will have to do to use this generic facility is to register a notification manager in the model context.
The model object API also makes it possible to check the Handly API level supported by a model, which should enable future evolution of Handly without having to introduce "extension interfaces" such as IElement2, IElementImpl2, etc. to add new API methods. By checking the API level, generic code will be able to dynamically discover which API methods are supported by the model it is dealing with.
Last but not least, the new API makes it possible to navigate from an element to the owning model and also supports models that can have multiple element trees. By using the equals method to compare the model objects, clients can test whether two elements belong to the same model or whether an element belongs to a specific model.
Other API Enhancements
- Support for files external to the workspace has been implemented on top of the Eclipse File System (EFS) API (500893, 502000)
- The workspace-related functionality has been extracted from SourceFile to a new subclass, WorkspaceSourceFile (500676)
- Non-local file systems are now also supported (506453, 506717)
- The buffer and working copy APIs have been revised and streamlined (505714, 506332)
Full List of Issues Addressed in This Release
0.6 - https://projects.eclipse.org/projects/technology.handly/releases/0.6/bugs