|  | <!-- | 
|  | This document is provided as a template along with some guidance for creating | 
|  | your project proposal. This is just a template. Feel free to change it as | 
|  | you see fit (add sections, remove section). We feel, however, that the | 
|  | suggestions represented in this document represent the reasonable minimum | 
|  | amount of information to move forward. | 
|  |  | 
|  | Please keep the formatting in this document simple. Please do not edit | 
|  | this document in Microsoft Word as it adds huge piles of markup that make | 
|  | it difficult to restyle. | 
|  |  | 
|  | More information is available here: | 
|  |  | 
|  | http://wiki.eclipse.org/Development_Resources/HOWTO/Pre-Proposal_Phase | 
|  |  | 
|  | Direct any questions about this template to emo@eclipse.org | 
|  | --> | 
|  |  | 
|  | <html> | 
|  | <head> | 
|  |  | 
|  | <!-- | 
|  | Include the title here. We will parse it out of here and include it on the | 
|  | rendered webpage. Do not duplicate the title within the text of your page. | 
|  | --> | 
|  |  | 
|  | <title>Handly</title> | 
|  | </head> | 
|  |  | 
|  | <!-- | 
|  | We make use of the 'classic' HTML Definition List (dl) tag to specify | 
|  | committers. I know... you haven't seen this tag in a long while... | 
|  | --> | 
|  |  | 
|  | <style> | 
|  | dt { | 
|  | display: list-item; | 
|  | list-style-position:outside; | 
|  | list-style-image:url(/eclipse.org-common/themes/Phoenix/images/arrow.gif); | 
|  | margin-left:16px; | 
|  | } | 
|  | dd { | 
|  | margin-left:25px; | 
|  | margin-bottom:5px; | 
|  | } | 
|  | </style> | 
|  |  | 
|  | <body> | 
|  | <p>The Handly project is a proposed open source project under the <a | 
|  | href="http://www.eclipse.org/projects/project_summary.php?projectid=technology">Technology | 
|  | Top-Level Project</a>.</p> | 
|  |  | 
|  | <!-- | 
|  | The communication channel must be specified. Typically, this is the | 
|  | "Proposals" forum. In general, you don't need to change this. | 
|  | --> | 
|  | <p>This proposal is in the Project Proposal Phase (as defined in the | 
|  | Eclipse Development Process) and is written to declare its intent and | 
|  | scope. We solicit additional participation and input from the Eclipse | 
|  | community. Please send all feedback to the | 
|  | <a href="http://www.eclipse.org/forums/eclipse.proposals">Eclipse Proposals</a> | 
|  | Forum.</p> | 
|  |  | 
|  | <h2>Summary</h2> | 
|  |  | 
|  | <p>The Handly project aims to provide a foundation for construction of | 
|  | language-oriented handle-based models not unlike the JDT Java Model in | 
|  | their essential qualities. It borrows from core design patterns and principles | 
|  | used in the Java Model, but aims for a generalized albeit partial basic | 
|  | implementation, on top of which complete handle-based models for languages | 
|  | of diverse kinds could be built with relative ease. The project includes | 
|  | a layer of integration with Xtext.</p> | 
|  |  | 
|  | <h2>Background</h2> | 
|  |  | 
|  | <!-- | 
|  | Optionally provide the background that has lead you to creating this project. | 
|  | --> | 
|  |  | 
|  | <p>It is well known that the Java Model is one of the pillars of Eclipse | 
|  | Java development tools (JDT). To a great extent, it is the Java Model that | 
|  | makes possible seamless tool integration and unified user experience in JDT. | 
|  | The Java Model is designed to be a lightweight, fault-tolerant model with | 
|  | elements to which a reference can be kept; the model that is well suited | 
|  | for presenting in views. It meets those design goals with a handle-based, | 
|  | lazily-populated model that keeps no resolved information and wrappers the | 
|  | workspace resource model. Meanwhile, models with similar design properties | 
|  | might play an equally important role in Eclipse-based development tools | 
|  | for other languages.</p> | 
|  |  | 
|  | <p>It seems that core design patterns and principles used in the Java Model | 
|  | can be just as relevant to handle-based models for other languages. But as | 
|  | the Java Model shows, implementation of those patterns and principles might | 
|  | be a nontrivial undertaking. Doing it from scratch, over and over again for | 
|  | each language does not appear to be an attractive proposition, especially | 
|  | when dealing with languages on a large scale (e.g. DSL engineering). Can | 
|  | those patterns and principles be (at least partially) implemented in | 
|  | a framework of general usefulness? That is the question that seems | 
|  | worthwhile to investigate.<p> | 
|  |  | 
|  | <h2>Scope</h2> | 
|  |  | 
|  | <!-- | 
|  | All projects must have a well-defined scope. Describe, concisely, what | 
|  | is in-scope and (optionally) what is out-of-scope. An Eclipse project | 
|  | cannot have an open-ended scope. | 
|  | --> | 
|  |  | 
|  | The project is going to encompass the following areas of work: | 
|  |  | 
|  | <ul> | 
|  | <li><b>Core framework.</b> The main proposition of the project is a framework | 
|  | that attempts to distill the core abstractions of a handle-based model | 
|  | into a uniform API and aims to provide the raw materials deemed generally | 
|  | useful for implementing such models.</li> | 
|  | <li><b>Common UI components.</b> The API provided by the core framework | 
|  | can potentially enable construction of reusable UI components. | 
|  | This might be an area for future work.</li> | 
|  | <li><b>Integration with other Eclipse projects.</b> A layer of integration | 
|  | with the Xtext project is provided initially. Other integration layers | 
|  | may be devised in the future, when and if appropriate.</li> | 
|  | <li><b>Exemplary implementations.</b> To encourage adoption of the framework, | 
|  | comprehensive examples of its use must be provided. These examples would be | 
|  | most fruitful if they could also serve as practical tools.</li> | 
|  | </ul> | 
|  |  | 
|  | <h2>Description</h2> | 
|  |  | 
|  | <!-- | 
|  | Describe the project here. Be concise, but provide enough information that | 
|  | somebody who doesn't already know very much about your project idea or domain | 
|  | has at least a fighting chance of understanding its purpose. | 
|  | --> | 
|  |  | 
|  | <p>It can be said that handle-based models are an important ingredient in | 
|  | an Eclipse IDE, if only because the workspace resource model is handle-based. | 
|  | The handle-based Java Model of JDT provides further evidence. The Java Model | 
|  | also shows that the (programming-language agnostic) resource model is often | 
|  | not enough: a language or a group of languages may need its own handle-based | 
|  | model that defines a code-centric view on resources and supports navigation | 
|  | down to structural elements inside a source file (which requires parsing | 
|  | the contents of the file). It is this class of language-oriented handle-based | 
|  | models that is the main interest of this project.</p> | 
|  |  | 
|  | <p>The project aims to investigate technology needed to deal with such | 
|  | handle-based models on a large scale. In particular, the project will attempt | 
|  | to distill the core abstractions of a handle-based model into a uniform API | 
|  | and supply basic building blocks for construction of such models. It borrows | 
|  | heavily from some of the design patterns and principles used in the Java Model, | 
|  | but aims for a generalized albeit partial implementation.</p> | 
|  |  | 
|  | <p>Thus, the project will provide a uniform API and a partial implementation for | 
|  | the central notion of a handle that acts like a key to a model element and has | 
|  | the following principal characteristics:</p> | 
|  |  | 
|  | <ul> | 
|  | <li>a value object - immutable, equality isn't based on identity</li> | 
|  | <li>can define the behavior of an element, but doesn't keep any element | 
|  | state (beyond the key information) - lightweight, never stale, references can | 
|  | be kept for a long time</li> | 
|  | <li>can refer to non-existing elements - existence can be tested with | 
|  | exists()</li> | 
|  | </ul> | 
|  |  | 
|  | <p>A handle-based design gives a lot of freedom when resolving handles to find | 
|  | the corresponding element state (the body). For instance, an implementation | 
|  | can maintain a (not strictly) bounded LRU cache of element bodies. The handle | 
|  | acts like a key into the cache. The model swaps out bodies to make room for | 
|  | other elements (unsaved changes can never be swapped out). Bodies store the | 
|  | cached structure and attributes for a particular element and are computed on | 
|  | demand. The basic building blocks for such implementation will be supplied | 
|  | by the project.</p> | 
|  |  | 
|  | <p>Furthermore, the project will support the notion of a working copy | 
|  | (of a source file), its editing and reconciling. A layer of integration | 
|  | with Xtext will be provided for editing and reconciling a working copy | 
|  | connected to an Xtext editor.</p> | 
|  |  | 
|  | <p>While providing a uniform handle-based API, the project will try to impose | 
|  | as minimal restrictions as possible on the shape or the underlying language(s) | 
|  | of attainable models.</p> | 
|  |  | 
|  | <h2>Relationship with other Eclipse projects</h2> | 
|  |  | 
|  | <p>The project rests upon the Eclipse Platform and includes a layer of | 
|  | integration with Xtext; integration with other Eclipse projects is possible | 
|  | in the future.</p> | 
|  |  | 
|  | <p>There are existing efforts at Eclipse that might be viewed as related to | 
|  | the project in a way:</p> | 
|  |  | 
|  | <ul> | 
|  | <li><b>The IDE Meta-tooling Platform (IMP)</b> has a much wider scope | 
|  | than this project, and a different emphasis. Among other things, it provides | 
|  | a 'universal' language-oriented handle-based model, with limited extensibility. | 
|  | The current implementation doesn't support elements inside compilation units, | 
|  | the notion of a reconcilable working copy, or a handle/body design with a | 
|  | bounded LRU cache of bodies, all of which we'll have already covered in the | 
|  | initial contribution. More important, our approach is fundamentally different. | 
|  | Instead of providing a single complete handle-based model supposed to be a | 
|  | universal fit for all languages, we intend to provide an abstract API and a | 
|  | partial implementation for constructing any number of specific language-oriented | 
|  | handle-based models, with few restrictions on the shape of the model. | 
|  | <b>Update:</b> the IMP project has recently been archived (January 2014).</li> | 
|  | <li><b>Dynamic Languages Toolkit (DLTK)</b> provides (among other things) | 
|  | an extensible handle-based model intended for dynamic languages. The design | 
|  | and implementation are largely influenced by the Java Model. The DLTK model | 
|  | does support elements inside source modules and is otherwise similar to the | 
|  | Java Model in all essential qualities. However, it is predefined to contain | 
|  | elements pertaining to (a subset of) dynamic languages (e.g. a source module | 
|  | may contain types, fields and methods; a type may contain fields, methods and | 
|  | inner types). We aim to support implementation of custom handle-based models | 
|  | of almost arbitrary shapes, for languages of diverse kinds (including | 
|  | domain-specific languages).</li> | 
|  | <li><b>Xtext</b> is a wonderful tool for language engineering. It covers | 
|  | many important components of an Eclipse-based IDE in a generic and extensible | 
|  | way, but does not explicitly address handle-based models. As part of the | 
|  | initial contribution we'll provide an integration layer to support editing and | 
|  | reconciling of a working copy connected to an Xtext editor. We regard both | 
|  | projects as complementary and hope to collaborate with the Xtext team on | 
|  | further facilitating construction of handle-based models for Xtext-based | 
|  | languages. That said it's our explicit goal to keep the core framework | 
|  | completely neutral of any specific language implementation technology and | 
|  | encapsulate such dependencies strictly within corresponding integration layers. | 
|  | </li> | 
|  | </ul> | 
|  |  | 
|  | <h2>Why Eclipse?</h2> | 
|  |  | 
|  | <!-- | 
|  | Answer these two questions:	What value does this project bring to the Eclipse | 
|  | community? What value do you expect to obtain from hosting your project at Eclipse? | 
|  |  | 
|  | What value do you get by having your project at Eclipse over and above the value | 
|  | of hosting at Eclipse Labs? | 
|  | --> | 
|  |  | 
|  | <p>We believe the nature of this project makes Eclipse the right home for it. | 
|  | As stated above, handle-based models can play an important role in an | 
|  | Eclipse-based IDE. This supports our hope that the area of work to be developed | 
|  | by the project might be interesting and useful to the Eclipse community. | 
|  | At the same time, such project should definitely benefit from the wider | 
|  | exposure with the Eclipse community. We do welcome and hope for open | 
|  | participation and contributions from the community; diversity is really | 
|  | important for this project to succeed. The project would also benefit from | 
|  | the commendable Eclipse development process and IP management.</p> | 
|  |  | 
|  | <h2>Initial Contribution</h2> | 
|  |  | 
|  | <!-- | 
|  | Projects are expected to arrive at Eclipse with existing code. | 
|  |  | 
|  | Describe the existing code that will be contributed to the project. Please provide | 
|  | a couple of paragraphs describing the code with modest detail, including important | 
|  | information like code ownership (who holds the copyright?), and some consideration | 
|  | of community that exists around the code. Include a listing of third-party libraries | 
|  | and associated licenses. | 
|  | --> | 
|  |  | 
|  | <p>The initial code base will be contributed by | 
|  | <a href="http://v8.1c.ru/eng/about_1c/">1C LLC</a> | 
|  | and includes the core framework and a layer of integration with Xtext.</p> | 
|  |  | 
|  | <p>Although the code is pretty stable and has been used internally with | 
|  | promising results, we regard it only as a starting point. The intent is to | 
|  | come up with a really nice design in this problem area through an open and | 
|  | transparent development process informed by community feedback.</p> | 
|  |  | 
|  | <p>Some parts of the initial design and implementation were adapted from | 
|  | Eclipse JDT and Xtext projects. The code makes direct references to the | 
|  | following third-party libraries, already present in the Eclipse Orbit | 
|  | repository:</p> | 
|  |  | 
|  | <ul> | 
|  | <li>com.google.inject 3.0.0 - Apache License, Version 2.0</li> | 
|  | <li>com.google.guava 10.0.1 - Apache License, Version 2.0</li> | 
|  | <li>org.apache.log4j 1.2.15 - Apache License, Version 2.0</li> | 
|  | </ul> | 
|  |  | 
|  | <h2>Legal Issues</h2> | 
|  |  | 
|  | <!-- | 
|  | Please describe any potential legal issues in this section. Does somebody else | 
|  | own the trademark to the project name? Is there some issue that prevents you | 
|  | from licensing the project under the Eclipse Public License? Are parts of the | 
|  | code available under some other license? Are there any LGPL/GPL bits that you | 
|  | absolutely require? | 
|  | --> | 
|  |  | 
|  | <p>There are no known legal issues.</p> | 
|  |  | 
|  | <h2>Committers</h2> | 
|  |  | 
|  | <!-- | 
|  | List any initial committers that should be provisioned along with the | 
|  | new project. Include affiliation, but do not include email addresses at | 
|  | this point. | 
|  | --> | 
|  |  | 
|  | <p>The following individuals are proposed as initial committers to the project:</p> | 
|  |  | 
|  | <dl> | 
|  | <dt>Vladimir Piskarev, 1C (lead)</dt> | 
|  | <dd>Vladimir is the main developer of the existing framework</dd> | 
|  | <dt>George Suaridze, 1C (co-lead)</dt> | 
|  | <dd>George is an early adopter of the existing framework</dd> | 
|  | </dl> | 
|  |  | 
|  | <p>We welcome additional committers and contributions.</p> | 
|  |  | 
|  | <!-- | 
|  | Describe any initial contributions of code that will be brought to the | 
|  | project. If there is no existing code, just remove this section. | 
|  | --> | 
|  |  | 
|  | <h2>Mentors</h2> | 
|  |  | 
|  | <!-- | 
|  | New Eclipse projects require a minimum of two mentors from the Architecture | 
|  | Council. You need to identify two mentors before the project is created. The | 
|  | proposal can be posted before this section is filled in (it's a little easier | 
|  | to find a mentor when the proposal itself is public). | 
|  | --> | 
|  |  | 
|  | <p>The following Architecture Council members will mentor this | 
|  | project:</p> | 
|  |  | 
|  | <ul> | 
|  | <li>Doug Schaefer</li> | 
|  | <li>Marcel Bruch</li> | 
|  | </ul> | 
|  |  | 
|  | <h2>Interested Parties</h2> | 
|  |  | 
|  | <!-- | 
|  | Provide a list of individuals, organisations, companies, and other Eclipse | 
|  | projects that are interested in this project. This list will provide some | 
|  | insight into who your project's community will ultimately include. Where | 
|  | possible, include affiliations. Do not include email addresses. | 
|  | --> | 
|  |  | 
|  | <p>The following individuals, organisations, companies and projects have | 
|  | expressed interest in this project:</p> | 
|  |  | 
|  | <ul> | 
|  | <li>itemis AG</li> | 
|  | <!-- | 
|  | <li>Somebody else, Affiliation</li> | 
|  | --> | 
|  | </ul> | 
|  |  | 
|  | <h2>Project Scheduling</h2> | 
|  |  | 
|  | <!-- | 
|  | Describe, in rough terms, what the basic scheduling of the project will | 
|  | be. You might, for example, include an indication of when an initial contribution | 
|  | should be expected, when your first build will be ready, etc. Exact | 
|  | dates are not required. | 
|  | --> | 
|  |  | 
|  | <p>The initial contribution is to be expected shortly after creation of the | 
|  | project and approval of the Eclipse IP Team. The first milestone build based | 
|  | on the initial code base should follow soon after that. Although no exact dates | 
|  | are given, we intend to make the initial contribution available to the | 
|  | community as soon as technically and legally possible.</p> | 
|  |  | 
|  | <h2>Changes to this Document</h2> | 
|  |  | 
|  | <!-- | 
|  | List any changes that have occurred in the document here. | 
|  | You only need to document changes that have occurred after the document | 
|  | has been posted live for the community to view and comment. | 
|  | --> | 
|  |  | 
|  | <table> | 
|  | <tr> | 
|  | <th>Date</th> | 
|  | <th>Change</th> | 
|  | </tr> | 
|  | <tr> | 
|  | <td>10-Jan-2014</td> | 
|  | <td>Document created</td> | 
|  | </tr> | 
|  | </table> | 
|  | </body> | 
|  | </html> |