Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[stellation-res] VSF Demo (org.eclipse.stellation.scm.vsf) 
Hi,
Per Mark's note yesterday, we've checked in code for our "proof-of-concept" demo of 
a VSF (Virtual Source File) editor. Mark is showing it at OOPSLA tomorrow night
(Tuesday), but you're welcome to check it out, build it and give it a spin before that, 
if you like.

So, what''s a VSF?
Briefly, a set of source code fragments (and/or other content fragments), selected according to some criteria, and typically gathered from a number of different files. The key point is that you view and edit the set of fragments **as if it were a single 
source file"", arranged in a manner convenient to the task at hand.
The selection criteria could be an Eclipse-style text or Java search, a query
using Stellation fragment annotations, some other form of information retrieval
technique, an explicitly-specified fragment set, etc. Furthermore, the selection could be generated statically (e.g. the query results fragments found in a particular project revision), or dynamically (e.g. the results found by applying the query to an arbitrary 
project revision, or to a different project entirely).

As you probably know, the Stellation SCM facilities were always intended as the
foundation for team collaboration and communication facilities. Mark and I think 
that virtual source files offer very promising ways for
a) viewing only the code that's relevant to a particular concern or task, even
    when that code is scattered in fragments across a number of source files;
b) facilitating locking of a set of such related fragments.
c) communicating with other team members - since the "aggregate descriptor"
that defines a set of related fragments is itself an artifact that can be checked 
   in, versioned, and shared by other team members (so I can look at fragment
   sets and VSFs defined by other team members, and vice versa; note that
a VSF will include presentation-related information in addition to the underlying 
   query or fragment set).

The current VSF demo is pretty rough: in particular, we don't have the "editor
reconciliation" feature working yet.  (In other words, changes made to
a VSF file are not yet propagated to the associated .java files, and vice versa). 
However, Mark and I have already found it useful enough that we're including
it in our development tool set.

The demo code is contained in the project org.eclipse.stellation.scm.vsf,
within our CVS repository on dev.eclipse.org.
Note: the VSF demo does not use, or depend on, any of the other Stellation code. 

The demo includes:
* An Editor for viewing a set of Java fragments (fragment == method, for now)
  Method and type (class, interface) separators are inserted between fragments
  by default, but this is optional.
* Markers showing fragment boundaries, with a "hover" text popup detailing
  the origin of a given fragment.  (You can double-click on the marker to
  jump to the associated source).
* A Content Outline window listing all fragments in the current VSF, and also
  all VSFs within a given directory.  You can click a fragment to jump to it,
  and click one of the 'Available VSFs' to show it within the VSF editor.
* Context menu actions for:
  - generating textual .vsfspec files for selected .java files.
(A .vsfspec defines the contents of a given .vsf file; they're easy to edit) 
  - generating .vsf files from .vsfspec files
  - generating a .vsf and .vsfspec file for the current Eclipse search results
    (within a given Eclipse project).

The last feature is especially useful.  For example, I can search for all
 references to org.eclipse.core.resources.IMarker within the Eclipee JDT UI
source, generate a VSF from that, and then browse through a single file
containing every method within the JDT UI that references IMarker.
If I want to see a particular method in the context of its compilation unit
(.java file), I can double-click the fragment marker in the margin of the
VSF editor; a Java editor opens or activates (as needed) on the relevant
.java file with the selected method highlighted.

More specific details are provided in the file:
org.eclipse.stellation.scm.vsf/doc/DemoNotes

This is still a basic proof-of-concept, and far from complete.  I'm planning
to extend it in a number of ways:
* Direct change reconciliation between an edited VSF and the corresponding
   source files.
* Mixing of content types within a single VSF (e.g. Java, raw text, 'sticky note' 
  annotations, XML (i.e. plugin.xml fragments).
* Better tools for selecting and organizing fragments
* Full integration with Stellation SCM (of course!).

Suggestions are welcome, as always.

I also need to revamp the underlying architecture.  The current prototype is
based on JFace text, but doesn't use a lot of the JFace editor functionality
that looks to be useful in a full fledged VSF editor.  For example, it doesn't
yet use IDocumentPartitioner, IReconciler, or any of the related framework.
Building the VSF Demo has taught me a lot about how JFace and the Eclipse
UI frameworks work,  so the next version should follow "the Eclipse Way" a lot
more closely.

It's worth noting that the current Eclipse frameworks have limited support for
type-specific partitions (fragments) within a single IDocument.
Formatting, change reconciliation, content assist, syntax highlighting and
some other functionality can all be performed on a type-specific basis,
applied to documents partitioned into regions of different types.
However, as far as I know, there is not yet any support for 'handing off'
editing activity related to a particular typed region to a "typed region editor" 
designed to operate within a constrained portion (or portions) of a single
document.  (Caveat: I haven't read the Eclipse JDT Java Editor source
at all closely yet, and may have missed something).  I'm hoping to contact
the Eclipse editor framework designer and discuss what the best approaches
might be.

Of course, continuing work on the VSF editor must be juggled with restarting
work on the Stellation 'Client Core' repository support, and completing the alpha version of the Stellation CM client. Completing and releasing the alpha version 
is our next major priority.

Looking forward to comments and other input --

- Jim


--------------------------------------------------------------------
Jim Wright, IBM T.J. Watson Research Center
*** The Stellation project: Advanced SCM for Collaboration
*** http://www.eclipse.org/stellation
*** Work Email: jwright@xxxxxxxxxxxxxx ------- Personal Email: jim.wright@xxxxxxx

Back to the top