Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "MoDisco/Components/KDMSourceExtension/Documentation/0.9"

(KDM.Source extension UI : a Code Source Synchronization Framework)
(ModelBrowserListener)
Line 135: Line 135:
  
 
===ModelBrowserListener===
 
===ModelBrowserListener===
This class only map the event "doubleClick" in the browser in order to call the openAndSelectEObjectInSourceFile method without adding a dependency between MoDisco Browser and kdm.source.extension.ui
+
This class only map the event "doubleClick" in the browser in order to call the ''openAndSelectEObjectInSourceFile'' method without adding a dependency between MoDisco Browser and kdm.source.extension.ui
  
 
== Requirements  ==
 
== Requirements  ==

Revision as of 07:27, 5 November 2010

MoDisco
Website
Download
Community
Mailing ListForums
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse SourceProject Set File

KDM.Source extension : a core metamodel for weaving Code models and KDM Inventory models

The component proposes a small framework for building weaving information between code models (Java, C++, ...) and physical resources (disk files and directories).

This framework reuses the KDM "Source" subpackage, which proposes a model for physical resources, known as "Inventory Model" (see figure here)

KDM inventory model also proposes SourceRegion/SourceRef concepts for weaving other kdm models (kdm code models, ...) with physical representation. Some references exist from other KDM subpackages to the SourceRef concept.

KDM Source Metamodel subpart (from the KDM Specification v 1.1)

MoDisco proposes to compose KDM inventory models with non-KDM models. For generic reuse reasons, a new metamodel extending KDM Source has been created.

A subpart of KDM Source model is extended for linking the SourceRegion concept with non-KDM elements, via the ASTNodeSourceRegion metaclass.

Moreover a recurrent pattern, in such a model composition, is to link KDM SourceFile with a code model element. Such a link is represented with CodeUnit2File metaclass.

MoDisco KDM Source extension Metamodel

This is a core metamodel that the developer should extend for describing a composition between a specific code metamodel and kdm.source.

How to create a composition metamodel between Code models and KDM Inventory models

Given a particular code metamodel (Such as the Java one), MoDisco proposes to extend KDMSourceExtension to define a metamodel composition between inventory models and code models.

The ASTNodeSourceRegion should be subclassed, and a reference to one concrete code metaclass should "specialize" the ASTNodeSourceRegion->node:EObject reference (one simple way is to set the new reference as derivated from the generic one).

(TODO : an opposite reference should be described for allowing navigation from code elements to the SourceRegion instances --> waiting for facet shortcut evolution to come)

In most cases the CodeUnit2File will be subclassed.

A reference example of such a composition metamodel is the Java Application example.

Java and kdm composition metamodel (extract)

How to develop a discoverer for the composition between code and KDM inventory models

Overview

After describing a composition metamodel, the contributor/adopter has to write an associated discoverer. Such a discoverer will instantiate elements for the composition metamodel described before (JavaSourceRegions...) Such a discoverer will have to manipulate the both kdm.source and code models.

A discoverer for the related code model is a prerequisite. The [Java Discoverer] is an example. Such a discoverer is not supposed to instantiate SourceRegions subclasses. To avoid ambiguity, we will talk about it as a "leaf code discoverer".

The composite discoverer should, in most cases, invoke the leaf discoverers (kdm.source and code). Another way is to provide the leaf models as parameters values to the composite discoverer.


A kdm.source model can be discovered using the [KDM Source discoverer]. Note that such a discoverer only provides a representation of files/directories. It does not instantiate SourceRegions subclasses.


A reference example of such a composition dicoverer is the Java Application discoverer example (Java class DiscoverKDMSourceAndJavaModel).

Composition discovery overview

Using the abstract AbstractComposedKDMSourceDiscoverer discoverer Java class

An abstract java class is proposed to facilitate and factorize some common code : AbstractComposedKDMSourceDiscoverer
This abstract discoverer proposes a process with four steps :

  1. initialize the composite model (to implement)
  2. discover the kdm.source model (already implemented)
  3. discover the others leaf models (to implement). In most cases there is only one code model
  4. terminate the discovery (weaving or saving actions)


Using the AbstractComposedKDMSourceDiscoverer is not mandatory.

Instrumenting the leaf code discoverers for retrieving visited source regions

In most cases, code discoverers have access to physical localization for each portion of code that is modeled.

There are two ways for a composite discoverer to catch such an information when invoking the leaf discoverer :

  • subclass some leaf discoverer implementation classes.
  • add a listener to the leaf discoverer to listen for source regions visit events.

The second way implies that the leaf discoverer extends the org.eclipse.modisco.kdm.source.extension.discovery.AbstractRegionDiscoverer class to support the registering of org.eclipse.modisco.kdm.source.extension.discovery.SourceRegionVisitListener.

AbstractRegionDiscoverer.notifyRegionSourceVisit must be called when appropriate from inside the leaf discoverer.

The [Java discoverer] implementation class illustrates such a pattern application.

The following figure illustrates the architecture for leaf and composite discoverers related to a CSharp metamodel.

Applicative Architecture for CSharp leaf and composite discoverers example

Instantiate source region nodes

Once the composite discoverer has the capability to retrieve information about sources regions visited and associated code model elements, it will instantiate the SourceRegion.

Resources Distribution and memory usage

Creating one SourceRegion instance for each code model element may induce some memory usage issues. Considering a given code metamodel, it may be interesting to have a strategy for dispatching model elements (from the composition model) into more than one XMI resource file.

Thus, EMF lazy resource loading mechanism enables opening and working with some subpart of the model.

A reference implementation for this strategy is in the [Java Application discovery].

KDM.Source extension UI : a Code Source Synchronization Framework

The component proposes a small framework for synchronizing model element with their source code. The idea is to be able to browse a model of any technology, and to have the possibility to directly navigate to its source code in the right editor.

This framework uses the KDM Extension framework which deal with weaving a model with its source code

The component exposed two extension-points for providing strategy of synchronization , those extensions are to be provided for every technology a code synchronization is needed for.

An example of what the result looks like as been implemented for Java, for more informations on how to use it see the: Java Code Source Synchronization user manual

Result of a code synchronization

SourceStrategy

This extension point aims at declaring strategies to resolve the ASTNodeSourceRegion of an element

 public interface SourceStrategy{	
    public ASTNodeSourceRegion getASTNodeSourceRegion(final EObject eObject);	
    public boolean isApplicableTo(final Notifier target);
 }
  • getASTNodeSourceRegion : Generic method to retrieve the ASTNodeSourceRegion of an element. Each strategy has to implements this method because depending on the technology the ASTNodeSourceRegion information might be contained by the element itself, or by an other model such has the MoDisco Composition one
  • isApplicableTo : Determines if the source object can be handled by this strategy. Each strategy has to implements this method with its own criteria (most of the time a verification of a metamodel URI will be enough)

RevealingStrategy

This extension point aims at declaring strategies to open the file which contains the element, and then to select it in its editor.

 public interface RevealingStrategy {
    public void revealInTextEditor(final IFile file,final SourceRegion sourceRegion);
    public void selectInTextEditor(final IEditorPart iEditorPart,final SourceRegion sourceRegion);
    public boolean isApplicableTo(final Notifier target);
 }
  • revealInTextEditor :
    • Parameter file : the file detected by the SourceStrategy
  • selectInTextEditor : select
    • Parameter iEditorPart : the editor in which the selection has to be done
  • isApplicableTo : Determines if the source object can be handled by this strategy. Each strategy has to implements this method with its own criteria (most of the time a verification of a metamodel URI will be enough)

ModelBrowserListener

This class only map the event "doubleClick" in the browser in order to call the openAndSelectEObjectInSourceFile method without adding a dependency between MoDisco Browser and kdm.source.extension.ui

Requirements

To use the plug-in you need:

  • JDK 1.5 or above
  • a version of Eclipse 3.6 or above with the following set of plug-ins installed
  • EMF 2.5.0 or higher

Source Repository

All of the source code is stored in a public source repository, which you can access at:

https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/trunk/org.eclipse.modisco.kdm.source.extension/


Code Synchronization Framework :

https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/trunk/org.eclipse.modisco.kdm.source.extension.ui


Connector between Model Browser and Code Synchronization:

https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/trunk/org.eclipse.modisco.kdm.source.extension.ui.browser

Back to the top