Skip to main content
Jump to: navigation, search

Intent/Getting Started

< Intent
Revision as of 07:48, 21 October 2011 by William.piers.obeo.fr (Talk | contribs) (Writing the documentation)

A simple Intent use case: a metamodel documentation

Authors William Piers
Contact william.piers@obeo.fr

Copyright 2011 Obeo.


Introduction

The aim of this tutorial is to get you started with Intent by helping you create your first Intent documentation project. For the purpose of this tutorial, we will create an Intent project which documents the concepts described by a metamodel.

Intent Getting started screenshot.png

Open the Project Explorer (if necessary)

An Intent project is meant to store a single documentation, it can be viewed as a documentation repository. To visualize this repository, you must use the Project Explorer view.

Intent Getting started project explorer view.png

If you cannot see this view in your current workbench - basically the project explorer is the default view under the Resource perspective, so if you are under another perspective you may not see this view - use the menu item Window > Show View > Project Explorer.

Intent Getting started project explorer selection.png

Create an Intent Project

In order to create a new Intent project, use the menu item File > New > Project > Intent Project.

Intent Getting started new intent project.png

Choose the name you want for your project (to stay consistent with the rest of the tutorial you can choose org.eclipse.intent.relational.idoc), then click Finish>.

Intent Getting started new intent project1.png

Note: a second wizard page is available to initialize the new documentation with existing content. There is no need to use it in this tutorial because we want to write a very simple document.

Intent Getting started new intent project2.png

Clicking on finish will create the project. You can now open the Intent document by double-clicking on the "Document" index in the project explorer view.

Intent Getting started new intent project result.png

Initialize the Metamodel Project

In this tutorial we are going to document a metamodel, while building it. To achieve this task we first need to create an empty EMF project which will contain the metamodel. Use the menu item File > New > Project > Empty EMF Project.

Intent Getting started metamodel.png

We are going to define a "relational" metamodel which describes databases, so you can name the project org.eclipse.intent.relational. Click Finish>.

Intent Getting started metamodel2.png

The Intent editor

The Intent editor provides the following features:

  • Syntax highlighting
  • Content assistant (ctrl + space)
  • Error detection
  • Quick fixes (ctrl + shift + 1)
  • Dynamic outline
  • Quick outline (ctrl + O)
Intent Getting started intent editor.png


Writing the documentation

Now in the newly created document we can describe the metamodel goal. To structure the content of the document we can use a few structural concepts:

  • Document: the root of the intent document. There can be only one document per repository. A document contains Chapters.
  • Chapter: The sub parts of a document. Contains text, sections.
  • Section: The sub parts of a chapter. Contains text, sections and Modeling Units.
  • Modeling Units: Can only be contained by a section. Describes parts of an observed resource in order to synchronize it with the real world.

Using those contexts you can start to write the documentation:

Document {
    Chapter {
        The relational metamodel

        This chapter describes the relational metamodel.
        Section {
            The relational package

            This section describes the concepts of the relational package, which is the *main* package of the relational metamodel.
        }
    }
}

All of the text parts can use the textile constructs, such as bold (*bold text*), italic and so on.

Describing the metamodel

In this part we are going to define the metamodel content and synchronize the intent document with the real world.

Initialize the metamodel content

The modeling unit syntax allow to split the metamodel content definition in several locations in the document. This way you can easily document each aspect of the metamodel in different sections.

We can add a modeling unit to the first section:

Section {
	The relational package

	This section describes the concepts of the relational package, which is the *main* package of the relational metamodel.
			
	@M
		new EPackage relational {
			nsURI = "http://www.eclipse.org/intent/relational";
			nsPrefix = "relational";
		}
	M@
}

This modeling unit defines an EPackage named relational. Notice that the first word after the type (EPackage) is assumed by the Intent compiler to be the name of the instance.

An alternative syntax to this declaration is :

new EPackage {
	name = "relational"
	nsURI = "http://www.eclipse.org/intent/relational";
	nsPrefix = "relational";
};

Inside of this declaration we set the required fields, nsURI and prefix.

When saving the document, no error are detected as the EPackage is not yet synchronized with an actual resource.

Synchronization with the real world

To achieve the synchronization between the metamodel we describe and the real world, we need to define a Resource, which will symbolize the metamodel file that we want to keep synchronization with.

You can declare the resource in a separate section if you want:

Section {
    The metamodel resource

    The metamodel resource is defined under the 'model' folder of the metamodel plugin.

    @M
        Resource relationalResource {
	     URI = "platform:/resource/org.eclipse.intent.relational/model/relational.ecore";
	     content += relational;
 	 }
    M@
}

In the resource declaration you have to set two fields:

  • URI : Allows to set (=) the location of the actual resource to synchronize with the document. Here we define that the metamodel (relational.ecore) is located inside of the model folder of the org.eclipse.intent.relational plugin found in the workspace (platform:/resource).
	URI = "platform:/resource/org.eclipse.intent.relational/model/relational.ecore";
  • content : Allows to add content to the resource. Here we add (+=) the previously defined relational EPackage.
	content += relational;
	

When saving the document, the Synchronizer detects that the resource does not exists.

Intent Getting started null resource.png

You can directly create the metamodel by applying the quick fix (Right-click on the error> Quick Fix > press Enter). From now on you will be able to define the metamodel content in the document through modeling units and synchronize the actual resource using the quickfixes, by applying differences from the document to the actual resource.

Contribute to the metamodel content

Now you can contribute content to your metamodel when writing the documentation, regularly synchronizing the actual resource using the quick fixes.

Below are some samples of modeling unit that can be contributed in any order inside of the intent document.

  • A NamedElement superclass, which can be added to the The relational package Section :
@M
	relational {
		eClassifiers += new EClass NamedElement {
			abstract = "true";
			eStructuralFeatures += new EAttribute {
				name = "name";
				eType = String;
			};
		};
	}
M@

In this modeling unit we use an inline declaration for the name EAttribute, using the new instruction.

The new element is detected by Intent as a synchronization warning, as it is not defined into the actual metamodel (the relational.ecore file).

Intent Getting started sync warning.png

We now want to transfer the definition we made in the document to the actual file. To achieve this, you can right click on this warning, and click on Quick fix. This will give the following dialog:

Intent Getting started sync fix.png

If you double click - or type enter - on the proposed quick fix, it will open a dialog showing a comparison between the real world resource (the "working copy") and the intent document resource.

Intent Getting started sync compare.png

Using this dialog you can apply changes from left to right using the top right arrows, and finally click on Commit to save the applied changes. If you apply all the changes it will make the document synchronization warning disappear.

You can proceed like this for all the further elements.

  • A Database concept :
Section {
	The database concept

	This concept symbolizes a database and allows to store schemas.

	@M
		relational {
			eClassifiers += new EClass Database {
	 			eSuperTypes += NamedElement;
	 			eStructuralFeatures += new EReference {
	 				name = "ownedSchemas";
	 				eType = DBSchema;
	 				containment = "true";
	 			};
	 		};
		}
	M@		
}

In this modeling unit there are two references to other modeling units: eSuperTypes refers to the previously declared NamedElement and ownedSchemas refers to a DBSchema concept.

There is no need to declare NamedElement before Database to allow Database to use it.

As no DBSchema has not be defined yet, the Compiler detects the following error, which will be gone after that the DBSchema concept will be defined.

Intent Getting started type not found.png
  • Below are the definitions of some other concepts of the metamodel. You can try to write them by you own and use this as a reference:
@M
relational {
	eClassifiers += new EClass DBSchema {
		eSuperTypes += NamedElement;
		eStructuralFeatures += new EReference {
			name = "ownedTables";
			eType = DBTable;
			upperBound = "-1";
			containment = "true";
		};
	};
	eClassifiers += new EClass DBTable {
		eSuperTypes += NamedElement;
		eStructuralFeatures += new EReference {
			name = "ownedColumns";
			eType = DBColumn;
			upperBound = "-1";
			containment = "true";
		};
	};
	eClassifiers += new EClass DBColumn {
		eSuperTypes += NamedElement;
		eStructuralFeatures += new EAttribute {
			name = "type";
			eType = DBDataType;
		};
	};
	eClassifiers += new EEnum DBDataType {
		eLiterals += new EEnumLiteral {
			name = "VARCHAR";
			literal = "VARCHAR";
			value = "0";
		};
		eLiterals += new EEnumLiteral {
			name = "NUMBER";
			literal = "NUMBER";
			value = "1";
		};
	};
}
M@

Following evolutions using Intent's synchronizer

Now we can use the couple document/metamodel kept in synchronization by intent in situation.

For instance, an user of the relational metamodel found that he wants to put several schemas into a database, which sounds legit. So he opens the metamodel file, changes the upperBound attribute of the Database EClass to "-1" in order to make it multiple.

Intent Getting started metamodel change.png

When reopening the database section, Intent has detected the desynchronization:

Intent Getting started metamodel change error.png

The following actions are up to you, as Intent is just a way to point any desynchronization issues: so you can either modify the document & the associated text description to match the change, or revert the metamodel modification made by the user because it doesn't match your requirements.

Intent Getting started doc fixed.png

Back to the top