plugins/org.eclipse.mylyn.docs.intent/discussion/specs/coarse_grained_synchronization.textile

	@bold@
	**bold**
	__italic__	
	-deleted-
	+added+
	??citation??
	@code@
	* list
	

	# list
	list

	^superscript^
	span %span% span


h1. Intent : Coarse grained synchronization


-truc- +truc+


1)
As a specifier
I want to specify a feature 'Create a class' (with Jnario-like syntax when possible)
So that
* developpers can code feature
* tests can be generated an written
* [user guide can be produced]
Given a requirement
When
* I create a Section named 'Create a class'
* I create a Model fragment pointing to a new Jnario file 
@M
 @ref "intent:/myIntentProject/createaclass.jnario"
M@
* Optional :  I add explanations in the section
Then
======>

2)
As a developper
I want to implement the feature specified in 1)
So that my modeler implement the feature
Given the intent section as specified in 1)
When 
* I create a new tool in my VSM to implement the feature
* I drag the created tool in the Intent Section
Then
====>

3)
As a tester
I want to test the feature specified in 1) and implemented in 2)
When
* I Generate my Java implementation
* drag the created java method in the Intent Section

3 bis)
As a tester
I want to test the feature specified in 1) and implemented in 2)
When
* I create a link to a new scenario model @ref "intent:/myIntentProject/createaclass.scenario"
Then
===> 


h2. Overview

For the time being, if you want to synchronize content with Intent, you have to describe the whole content inside Model fragments. This allows you to have a fine-grained synchronization, where you can associate each model element/feature to a dedicated section to have precise synchronization informations.

This can be a burden, especially when you describe a whole file/model or an important piece of code inside a paragraph.

This document specifies how Intent can handle coarse grained synchronization.

h2. Specification

Through this specification, we will take the example of the following test file : 

bc.. 
package my.java.project;

public class CreateAType {

	@Test
	public void createAClass() throws Exception {
		// some piece of code
	}
	// MIDDLE COMMENT
	
	@Test
	public void createAnEnumeration() throws Exception {
		// some piece of code
	}
}


===> granularité : classe / méthode (si pas de fragment : classe)

@ref "<PATH>

======> jdt// ariadne ?


h3. Syntax & parsing

We will name this concept *External Content Reference*, as the content to synchronize is not described directly inside the document, but through a reference to an external file.

h4. ExternalReference Syntax 

We propose the following syntax for referencing the content of an external file:

bc.. @ref "<FILE_LOCATION>"
@ref "<FILE_LOCATION>#//blocks[tag='<TAG>']" 

p. 

 
For example : 

bc.. @ref "my.java.project/src/my/java/project/CreateAType.java"
p. > Describes the text of all non-tagged content : 

bc.. 
package my.java.project;



bc.. "my.java.project/src/my/java/project/CreateAType.java#//blocks[tag='toto']"
p. > Describes the following text

bc.. 
	public void createAnEnumeration() throws Exception {
		// some piece of code
	}

bc.. @ref "java:/myTestProject/src/com.my.company.tests.CreateAType.java#//blocks[tag='Story(CreateAType)']"
p. > You can notice that the Story(CreateAType)@ tag has no end. In that case, we will return the file content from the start tag to the file end, excluding other tagged zones : 

bc.. 
public class CreateAType {

	// MIDDLE COMMENT
	
}

h4. ExternalContentReference parsing

The ModelingUnit parser will be modified to accept the described syntax.
It will represent an external content in an instance of the following EClass :

bc.. 
EClass ExternalContentReference extends ResourceDeclaration {
	// The inherited field "URI" will store the reference URI
}

p. The External Content Reference extends ResourceDeclaration so that the compiler can create a resource to store the external content reference (see "following section":#ExternalContentReferenceCompilation .

bc.. 
ExternalContentReference {
    eStructuralFeatures += new EAttributes markedAsMerged {
         eType = EBoolean;
    };
}
p. This attribute will allow to determine whether the external content should be overridden with the last working copy value (if true) or not (see "following section":#ExternalContentReferenceCompilation .


bc.. 
ExternalContentReference {
     eStructuralFeatures += new EReference externalContent {
        eType = EObject;
     };
}
p. This reference stores the last valid value for the external content (set by the compiler).

h3. ExternalContentReference Compilation

h4. Compilation

We will add a new case to the @ModelingUnitGenerator@ when having to compile and @ExternalContentReference@, that will call a new @ExternalContentReferenceGenerator@.

* If the ExternalContentReference's externalContent reference is null (i.e. not initialized) or if it is marked as merge (i.e. we should get the latest working copy value), then we have to get the working copy value of this external Content. To do so, we get the external content EObject using the compiler's resource set (extensible through a "Resource Factory":#Extensibility ).
* Otherwise, we use the value of this reference

We will register this external reference contribution in the compiler's information holder, so that : 
* the external content can be saved as any other Intent resource (the only difference is that instead of defining it inside model fragments, the generated element has been copied from working copy)
* traceability informations can be registered (and used e.g. for hyperlink detections)

h4. Extensibility

We saw that the compiler uses the ResourceSet to get the External Content. So for instance : 

bc.. @ref "platform:/resource/myProject/myEcore.ecore"
p. will be resolved with the default resource factories.

If we want to provide a way to get the java files external content (in our example, java files with tags, we will have to write a new @ResourceFactory@ associated to the @java@ protocol.

h3. ExternalContentReference Synchronization

h4. Synchronization

No change will be brought to the Intent synchronizer : it will still compare the resource generated by Intent (that was calculated using the ExternalContentReference's externalContent) and the working copy value (recalculated using the provided resource factories). It will raised synchronization issues on the ExternalContentReference if differences are found.

To fix an issue related to an ExternalContentReference, we just have to mark it as merged (set the attribute to true): then the compiler will get the latest working copy version and the synchronization issue will be fixed.

h5. Dealing with references out of scope

If you are synchronizing a model element referencing other model elements, the compiled copy element will reference the working copy elements.

For instance, with the following ecore model : 

bc.. Package p1 {
 EClass c1 extends c2
 EClass c2
}

p. if you are only referencing c1, then the copy c1 will extends the working copy version of c2.

bc.. @ref "platform:/resource/my.java.project/test.ecore#//c1"

h3. Displaying file content in Model Fragments

We want to display the content associated to the external content reference inside the Modeling Fragment (for instance the java file).

To do so, we will provide an extension point in the IntentEditor plugin, allowing to provide an @IExternalContentGraphicalRenderer@ defined as below:
* @boolean isRenderedFrom(EObject externalContent)@ :  This methods indicates whether this IExternalContentGraphicalRenderer can be applied on the given externalContent, according for example to  the externalContent's EClass.
* @void render(EObject externalContent, IntentEditor editor)@.This could draw the text of a Java file, or the image of diagram.

h3. Drag and drop support

When dragging an IResource/model element that can be handled by one of the provided @IResourceFactory@, the ExternalContentReference should be automatically created.

To drop for instance a new java file, user will have to:
* open it with the sample reflective editor
* drop the content inside the Intent document.

If a ResourceDeclaration matching this java file's URI is found, we will drop it as a ModelFragment (existing dropping mechanism). If not, we will display a pop-up allowing the end-user to choose between fine and coarse-grained synchronization.

h3. Hyperlink support

To open some kind of editors (e.g. a Java editor), we will have to create a FileEditorInput (instead of a URIEditorInput which is the default). As the IntentEditor plugin does not depends on org.eclipse.core.resource, we will not be able to do so. Hence we will add the following method to the @IExternalContentGraphicalRendered@ : 
* @boolean openEditor(ExternalContentReference externalContentReference)@. If false is returned, then the default URIEditorInput-based opening mechanism will be used. 

h3. Documentation Export

When exporting the documentation, we will add a boolean allowing to specify whether external content should be rendered or not.

Each contribution will be able to override the export of the ExternalContent (with guards to avoid overriding the behavior when not relevant), and for instance : 
* override the header template to add a new javascript library to handle java syntaxic coloring
* override the ExternalContent export to print the java file
* override the ExternalContent export to copy and reference an image (e.g. for diagrams)

h3. Write a contribution to reference java files with tags

To prove the extensibility of this approach, we will provide an extension allowing to make external references to java files. All pieces of code defined inside tags (see examples above) will me matched.

This task includes all possible extension (doc export, hyperlink detectors, graphical rendering in editor...).

h3. Tests

2 kind of tests will be written: 
* Test the external references with models
* Test the external references with the Java file extension

Notice that these test will not test the UI rendering of java files.

h3. Performances 

After a first implementation, we will analyse the performances of this mechanism, and add, if required:
* Caching mechanisms (for example using hashcodes/timestamps to determine if a java file has changed and needs to be compared, cache parsed java tags...)
* Provide a fine grained synchronization, to only compare the files that have changed