Difference between revisions of "MoDisco/Components/FacetManager"

From Eclipsepedia

Jump to: navigation, search
m (Converting the first section into an introduction)
(doc review)
Line 1: Line 1:
 
The MoDisco role component introduced the "role" concept. A role
 
The MoDisco role component introduced the "role" concept. A role
 
is a kind of virtual class extension. Those "virtual classes" will never
 
is a kind of virtual class extension. Those "virtual classes" will never
have instances. An object can be conform to a role but can not be an
+
have instances. An object can conform to a role but can not be an
 
instance of a role.
 
instance of a role.
  
Line 8: Line 8:
 
some of them will have the role of "Manager" or "Developer".
 
some of them will have the role of "Manager" or "Developer".
  
The goal of role concept introduction is to be able to highlight
+
The goal of introducing the role concept is to be able to highlight
 
some model elements having a specific role.
 
some model elements having a specific role.
  
 
The MoDisco role feature allows describing and using roles. The
 
The MoDisco role feature allows describing and using roles. The
 
description is done by editing a model and the use is done through an
 
description is done by editing a model and the use is done through an
API. The main client of this API is the MoDisco browser.
+
API. The main client of this API is the MoDisco model browser.
  
 
==How to create a model role set==
 
==How to create a model role set==
Line 21: Line 21:
 
The second step is to [[MoDisco/QueryManager|create
 
The second step is to [[MoDisco/QueryManager|create
 
a query set]]. This query set will store boolean queries indicating if an
 
a query set]]. This query set will store boolean queries indicating if an
object is conform to a role.
+
object conforms to a role.
  
 
Right-click on the MoDisco project and select the "New > Other
 
Right-click on the MoDisco project and select the "New > Other
Line 48: Line 48:
 
[[Image:MoDisco_Role_newRoleSet_006.gif]]
 
[[Image:MoDisco_Role_newRoleSet_006.gif]]
  
Set the name of the role set and take care that the role set name
+
Set the name of the role set and make sure that the role set name
is the same than the containing file name ("My" in the example). The
+
is the same as the containing file name ("My" in the example). The
 
nsURI and prefix must also be filled.
 
nsURI and prefix must also be filled.
  
Line 78: Line 78:
 
[[Image:MoDisco_Role_newRoleSet_012.gif]]
 
[[Image:MoDisco_Role_newRoleSet_012.gif]]
  
To specify how to know if an object is conform to a role, we have
+
To specify how to know if an object conforms to a role, we have
 
to provide a boolean query. To provide this query we have to load the
 
to provide a boolean query. To provide this query we have to load the
 
model containing its description.
 
model containing its description.
Line 84: Line 84:
 
[[Image:MoDisco_Role_newRoleSet_013.gif]]
 
[[Image:MoDisco_Role_newRoleSet_013.gif]]
  
The query has to referred using the MoDisco protocol:
+
The query has to be referred to using the MoDisco protocol:
 
"modisco:/query/<querySetName>". In the example, we use the "My"
 
"modisco:/query/<querySetName>". In the example, we use the "My"
 
query set.
 
query set.
Line 90: Line 90:
 
[[Image:MoDisco_Role_newRoleSet_014.gif]]
 
[[Image:MoDisco_Role_newRoleSet_014.gif]]
  
Until the query set resource is referred, we have just to select the
+
Once the query set resource is referenced, we just have to select the
 
query describing the role. In the example this query is named
 
query describing the role. In the example this query is named
 
"isAbstract".
 
"isAbstract".
Line 97: Line 97:
  
 
At this step, if we save the model, the "red cross" should disappear
 
At this step, if we save the model, the "red cross" should disappear
from the file icon. This mean that the role set model is valid.
+
from the file icon. This means that the role set model is now valid.
  
 
[[Image:MoDisco_Role_newRoleSet_016.gif]]
 
[[Image:MoDisco_Role_newRoleSet_016.gif]]
Line 103: Line 103:
 
If the role has specific attributes or references which can be
 
If the role has specific attributes or references which can be
 
calculated, we can declare them. In this example, we will declare an
 
calculated, we can declare them. In this example, we will declare an
attribute indicating the number of abstract method contained in the
+
attribute indicating the number of abstract methods contained in the
 
abstract class. To create a new role attribute right-click on the role
 
abstract class. To create a new role attribute right-click on the role
element and select the "New > New Child > RoleAttribute" button.
+
element and select the "New Child > RoleAttribute" item.
  
 
[[Image:MoDisco_Role_newRoleSet_017.gif]]
 
[[Image:MoDisco_Role_newRoleSet_017.gif]]
  
 
The attribute's type and name must be set. The "Value Query" field must
 
The attribute's type and name must be set. The "Value Query" field must
be field with a reference to a query which is able to calculate the
+
be filled with a reference to a query which is used to calculate the
attribute's value. This query must have the same type than the attribute
+
attribute's value. This query must have the same type as the attribute
 
and be applicable to the virtually extended class.
 
and be applicable to the virtually extended class.
  
Line 119: Line 119:
 
The role set is now ready to be used.
 
The role set is now ready to be used.
  
== How to consult the MoDisco role set catalog trough the UI ==
+
== How to consult the MoDisco role set catalog through the UI ==
  
 
If a role set model is valid, it is registered in the role set
 
If a role set model is valid, it is registered in the role set
Line 125: Line 125:
 
view.
 
view.
  
To get this view select "Windows > Show view > Other ..."
+
To open this view select "Windows > Show view > Other ..."
in the menu bar and chose "Role Set" in the list.
+
in the menu bar and choose "Role Set" in the list.
  
 
[[Image:MoDisco_Role_newRoleSet_019.gif]]
 
[[Image:MoDisco_Role_newRoleSet_019.gif]]
 
[[Image:MoDisco_Role_newRoleSet_020.gif]]
 
[[Image:MoDisco_Role_newRoleSet_020.gif]]
  
The "Role set" view presents the available role sets and them
+
The "Role set" view presents the available role sets and their
roles. For each role set the description model location is point out.
+
roles. For each role set the location of its description model is pointed out.
  
 
[[Image:MoDisco_Role_newRoleSet_021.gif]]
 
[[Image:MoDisco_Role_newRoleSet_021.gif]]
  
== How to programmatically use the MoDisco role set catalog. ==
+
== How to programmatically use the MoDisco role set catalog ==
  
Here a MoDisco role API example is provided. To have more
+
Here is an example of using the MoDisco role API. For more information please refer to the JavaDoc.
informations please refer to the JavaDoc.
+
  
 
  import org.eclipse.emf.ecore.EObject;
 
  import org.eclipse.emf.ecore.EObject;
Line 173: Line 172:
 
[[Image:MoDisco_Role_metamodel.png]]
 
[[Image:MoDisco_Role_metamodel.png]]
  
The role meta-model extends the ecore meta-model and use the
+
The role meta-model extends the ecore meta-model and uses the query meta-model.
query meta-model.
+
  
A roleSet is a kind of ePackage. A roleSet contains roles through
+
A RoleSet is a kind of EPackage. A RoleSet contains roles through
the eClassifier reference. A role is a kind of eClass.
+
the eClassifier reference. A role is a kind of EClass.
  
 
For a role instance, the eSuperType reference must be set to
 
For a role instance, the eSuperType reference must be set to
Line 183: Line 181:
  
 
The role class has one specific reference: conditionQuery. The
 
The role class has one specific reference: conditionQuery. The
conditionQuery reference points the ModelQuery class. The model queries
+
conditionQuery reference points to the ModelQuery class. The model queries
pointed by the conditionQuery reference must return a Boolean. Those
+
pointed to by the conditionQuery reference must return a Boolean. Those
queries are used to specify how to decide if an instance is conform to a
+
queries are used to specify how to decide whether an instance conforms to a
role. If the conditionQuery is empty all the instances of the class
+
role. If the conditionQuery is empty then all the instances of the class
referred by role instance trough the eSuperType reference, are conform
+
referred to by the role instance through the eSuperType reference conform
to the role.
+
to this role.
  
 
A role contains roleAttributes and roleReferences through the
 
A role contains roleAttributes and roleReferences through the
 
eStructuralFeature reference. The RoleAttribute and RoleReference
 
eStructuralFeature reference. The RoleAttribute and RoleReference
 
classes have a common super class: RoleStructuralFeature. The
 
classes have a common super class: RoleStructuralFeature. The
RoleStructuralFeature has one reference named valueQuery and pointing to
+
RoleStructuralFeature has one reference named valueQuery pointing to
 
the ModelQuery class. The valueQuery is used to compute the role
 
the ModelQuery class. The valueQuery is used to compute the role
 
structural feature value. The roleAttribute and roleReference must have
 
structural feature value. The roleAttribute and roleReference must have
the same type than the query they refer.
+
the same type as the query they refer to.

Revision as of 07:35, 3 December 2009

The MoDisco role component introduced the "role" concept. A role is a kind of virtual class extension. Those "virtual classes" will never have instances. An object can conform to a role but can not be an instance of a role.

For example, assuming we have a class named Employee and two roles: "Manager" and "Developer". We will have a set of Employee instances and some of them will have the role of "Manager" or "Developer".

The goal of introducing the role concept is to be able to highlight some model elements having a specific role.

The MoDisco role feature allows describing and using roles. The description is done by editing a model and the use is done through an API. The main client of this API is the MoDisco model browser.

Contents

How to create a model role set

The first step is to create a MoDisco project.

The second step is to create a query set. This query set will store boolean queries indicating if an object conforms to a role.

Right-click on the MoDisco project and select the "New > Other ..." button.

MoDisco Role newRoleSet 001.gif

Select "Role Model" and press the "Next" button

MoDisco Role newRoleSet 002.gif

Choose a name for your model role set (My.roleSet in the example) and press "Next".

MoDisco Role newRoleSet 003.gif


Select "RoleSet" in the "Model Object" list and press "Finish"

MoDisco Role newRoleSet 004.gif

MoDisco Role newRoleSet 005.gif

Open the "My.roleSet" file and open the "Properties View"

MoDisco Role newRoleSet 006.gif

Set the name of the role set and make sure that the role set name is the same as the containing file name ("My" in the example). The nsURI and prefix must also be filled.

MoDisco Role newRoleSet 007.gif

Load the resources containing the meta-model extended by the role set. To load a meta-model resource the user must use the "Load meta-model resource" action.

MoDisco Role newRoleSet 008.gif

In this example, we choose to use the Java meta-model.

MoDisco Role newRoleSet 009.gif

Fill the "Extended package" field with the ePackages containing the virtually extended meta-model.

MoDisco Role newRoleSet 010.gif

Right click on the RoleSet element and choose the "New Child > Role" action to create a role.

MoDisco Role newRoleSet 011.gif

Set the role name and the class that the role will extend.

MoDisco Role newRoleSet 012.gif

To specify how to know if an object conforms to a role, we have to provide a boolean query. To provide this query we have to load the model containing its description.

MoDisco Role newRoleSet 013.gif

The query has to be referred to using the MoDisco protocol: "modisco:/query/<querySetName>". In the example, we use the "My" query set.

MoDisco Role newRoleSet 014.gif

Once the query set resource is referenced, we just have to select the query describing the role. In the example this query is named "isAbstract".

MoDisco Role newRoleSet 015.gif

At this step, if we save the model, the "red cross" should disappear from the file icon. This means that the role set model is now valid.

MoDisco Role newRoleSet 016.gif

If the role has specific attributes or references which can be calculated, we can declare them. In this example, we will declare an attribute indicating the number of abstract methods contained in the abstract class. To create a new role attribute right-click on the role element and select the "New Child > RoleAttribute" item.

MoDisco Role newRoleSet 017.gif

The attribute's type and name must be set. The "Value Query" field must be filled with a reference to a query which is used to calculate the attribute's value. This query must have the same type as the attribute and be applicable to the virtually extended class.

MoDisco Role newRoleSet 018.gif


The role set is now ready to be used.

How to consult the MoDisco role set catalog through the UI

If a role set model is valid, it is registered in the role set catalog. To consult the role set catalog, we can use the "Role Set" view.

To open this view select "Windows > Show view > Other ..." in the menu bar and choose "Role Set" in the list.

MoDisco Role newRoleSet 019.gif File:MoDisco Role newRoleSet 020.gif

The "Role set" view presents the available role sets and their roles. For each role set the location of its description model is pointed out.

MoDisco Role newRoleSet 021.gif

How to programmatically use the MoDisco role set catalog

Here is an example of using the MoDisco role API. For more information please refer to the JavaDoc.

import org.eclipse.emf.ecore.EObject;
import org.eclipse.gmt.modisco.infra.query.core.exception.ModelQueryException;
import org.eclipse.gmt.modisco.infra.role.Role;
import org.eclipse.gmt.modisco.infra.role.RoleSet;
import org.eclipse.gmt.modisco.infra.role.core.RoleContext;
import org.eclipse.gmt.modisco.infra.role.core.RoleSetCatalog;
import org.eclipse.gmt.modisco.infra.role.core.exception.ModiscoRoleException;

public class Example {

	public Integer getNbAbstractMethod(EObject eObject)
			throws ModelQueryException, ModiscoRoleException {
		RoleSet roleSet = RoleSetCatalog.getSingleton().getRoleSet("My");
		RoleContext context = new RoleContext();
		context.addRoleSet(roleSet);
		Role role = roleSet.getRole("AbstractClassDeclaration");
		if (context.isInstance(eObject, role)) {
			Object object = context.get(eObject, role
					.getEStructuralFeature("nbAbstractMethod"));
			if (object instanceof Integer) {
				Integer nbAbstractMethod = (Integer) object;
				return nbAbstractMethod;
			}
		}
		return null;
	}
}

Role Meta-model Description

MoDisco Role metamodel.png

The role meta-model extends the ecore meta-model and uses the query meta-model.

A RoleSet is a kind of EPackage. A RoleSet contains roles through the eClassifier reference. A role is a kind of EClass.

For a role instance, the eSuperType reference must be set to specify which class the role virtually extends.

The role class has one specific reference: conditionQuery. The conditionQuery reference points to the ModelQuery class. The model queries pointed to by the conditionQuery reference must return a Boolean. Those queries are used to specify how to decide whether an instance conforms to a role. If the conditionQuery is empty then all the instances of the class referred to by the role instance through the eSuperType reference conform to this role.

A role contains roleAttributes and roleReferences through the eStructuralFeature reference. The RoleAttribute and RoleReference classes have a common super class: RoleStructuralFeature. The RoleStructuralFeature has one reference named valueQuery pointing to the ModelQuery class. The valueQuery is used to compute the role structural feature value. The roleAttribute and roleReference must have the same type as the query they refer to.