blob: 46f690c397a0e6e56d813370fe62f17c0f848ce7 [file] [log] [blame]
<!--
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>