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/QueryManager/Documentation/0.8"

(Tab refactoring)
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{MoDiscoTabs|QueryManager|
+
#REDIRECT [[MoDisco/Moved To Help Center]]
{{MoDiscoTab|QueryManager|Documentation|0.8}}{{MoDiscoTab|QueryManager|Documentation|0.9}}{{MoDiscoTab|QueryManager|Architecture|}}
+
}}
+
 
+
== How to create a MoDisco query set ==
+
 
+
The first step is to [[MoDisco/ProjectNature|create a MoDisco project]].
+
 
+
Then right-click on the MoDisco project and select '''New > Other ...'''.
+
 
+
[[Image:MoDisco_Facet_NewOther.png|520px]]
+
 
+
Select '''QuerySet Model''' and press the '''Next''' button
+
 
+
[[Image:MoDisco_NewQuerySetWizard.png]]
+
 
+
Choose a name for your model query set (''My.querySet'' in the
+
example) and press '''Finish'''.
+
 
+
[[Image:MoDisco_NewQuerySetWizard_Name.png]]
+
 
+
Open the "My.querySet" file and open the "Properties View"
+
 
+
Set the description of the query set and make sure that the query
+
set name is the same as the containing file name ("My" in the
+
example).
+
 
+
[[Image:MoDisco_QuerySetProperties.png]]
+
 
+
== How to create a MoDisco query ==
+
 
+
=== The easy way ===
+
 
+
Right-click on a query set, and choose '''Create Query'''.
+
 
+
[[Image:MoDisco_CreateQueryAction.png]]
+
 
+
This opens the Create Query wizard, with the parent query set already selected.
+
 
+
Fill in the query name, description, scope and return type. Then click '''Finish'''.
+
 
+
[[Image:MoDisco_CreateQueryWizard.png]]
+
 
+
A Java editor opens on the Java class that was created for your query. Complete the "evaluate" method body with your code:
+
 
+
[[Image:MoDisco_JavaQueryClassCode.png]]
+
 
+
Then do '''File > Save''' in the query set editor.
+
 
+
 
+
=== Manually ===
+
The wizard does everything for you, but it is still interesting to know how to create and edit a query manually. Also, the wizard only handles creating Java queries for now, so if you want to create an OCL query for example, then you have to do it manually.
+
 
+
Load the resources containing the meta-models used by the model
+
queries that will be owned by the query set. To load a meta-model
+
resource use the '''Load meta-model resource''' action in the query set editor.
+
 
+
[[Image:MoDisco_Query_LoadMetamodelResource.png]]
+
 
+
In this example, we choose to use the KDM meta-model.
+
 
+
[[Image:MoDisco_Query_Package_Selection_KDM.png]]
+
 
+
Fill the "Associated Metamodels" field with the ePackages
+
containing the meta-models used by the model queries that will be owned
+
by the query set.
+
 
+
[[Image:MoDisco_Query_Properties_AssociatedMetamodels.png]]
+
 
+
In this example we use the "core" package.
+
 
+
[[Image:MoDisco_Query_Associated_Metamodels_Core.png]]
+
 
+
Right click on the ModelQuerySet element and choose the
+
'''New Child > Java Model Query''' action to create a "Java Model Query".
+
 
+
[[Image:MoDisco_Query_NewChild_JavaModelQuery.png]]
+
 
+
Set the name, the description and the return type of the query.
+
Set the "Implementation Class Name" field with the qualified name of the
+
class that will contain the query's Java implementation.
+
 
+
[[Image:MoDisco_Query_JavaModelQuery_Properties.png]]
+
 
+
Fill the "Scope" field with the meta-class to which the query will be
+
applicable.
+
 
+
[[Image:MoDisco_QueryScope.png]]
+
 
+
[[Image:MoDisco_QueryScopeKDMEntity.png]]
+
 
+
[[Image:MoDisco_PropertiesScopeKDMEntity.png]]
+
 
+
A MoDisco project is also a "Plug-in project". To be able to
+
refer to the API of the used meta-model, we have to add the "org.eclipse.gmt.modisco.infra.query.core" plug-in and the meta-model
+
implementation plug-in to the plug-in dependencies.
+
 
+
[[Image:MoDisco_QueryPluginDependencies.png]]
+
 
+
Create the query's implementation class.
+
 
+
[[Image:MoDisco_NewJavaQueryClass.png]]
+
 
+
The Java Query implementation class must implement
+
org.eclipse.gmt.modisco.query.core.java.IJavaModelQuery.
+
 
+
[[Image:MoDisco_NewJavaQueryClassWizard.png]]
+
 
+
[[Image:MoDisco_JavaQueryClassCode.png]]
+
 
+
==How to consult the MoDisco query set catalog through the UI==
+
If a query set model is valid, it is registered in the model
+
query set catalog. To consult the model query set catalog, we can use
+
the "Model Query Set" view.
+
 
+
To get this view select '''Windows > Show view > Other ...'''
+
in the menu bar and choose "Query Sets" in the list.
+
 
+
[[Image:MoDisco_Window_ShowView_Other.png]]
+
 
+
[[Image:MoDisco_ShowView_QuerySets.png]]
+
 
+
The "Query Sets" view presents the available query sets and their
+
queries. And for each query, its description and model location are displayed.
+
 
+
[[Image:MoDisco_QuerySetsView.png]]
+
 
+
==How to programmatically use the MoDisco query set catalog==
+
 
+
Here a MoDisco query API example is provided. For more
+
information please refer to the JavaDoc.
+
 
+
<source lang="java">
+
import org.eclipse.emf.ecore.EObject;
+
import org.eclipse.gmt.modisco.infra.query.ModelQuery;
+
import org.eclipse.gmt.modisco.infra.query.ModelQuerySet;
+
import org.eclipse.gmt.modisco.infra.query.core.AbstractModelQuery;
+
import org.eclipse.gmt.modisco.infra.query.core.ModelQuerySetCatalog;
+
import org.eclipse.gmt.modisco.infra.query.runtime.ModelQueryResult;
+
 
+
public class Example {
+
  public Integer main(EObject context) throws Exception {
+
    // Get the model query set catalog.
+
    ModelQuerySetCatalog catalog = ModelQuerySetCatalog.getSingleton();
+
    // Get the query set named "My".
+
    ModelQuerySet modelQuerySet = catalog.getModelQuerySet("My");
+
    // Select in the "My" query set a query named "myQuery".
+
    // modelQueryDescription is a model element.
+
    ModelQuery modelQueryDescription = null;
+
    for (ModelQuery modelQuery : modelQuerySet.getQueries()) {
+
      if (modelQuery.getName().equals("myQuery")) {
+
        modelQueryDescription = modelQuery;
+
        break;
+
      }
+
    }
+
    if (modelQueryDescription == null) {
+
      throw new Exception();
+
    }
+
    //Get a java instance of the querySet
+
    AbstractModelQuery myModelQuery = catalog
+
        .getModelQueryImpl(modelQueryDescription);
+
    //the model query set evaluation
+
    ModelQueryResult result = myModelQuery.evaluate(context);
+
    if (result.getException() != null) {
+
      throw new Exception();
+
    }
+
    return (Integer) result.getValue();
+
  }
+
}
+
</source>
+
 
+
== How to package a query set in a plug-in ==
+
To package a query set in a plug-in, an extension must be added in the file plugin.xml (contained in the query set's project). The extension point to use is: org.eclipse.gmt.modisco.infra.query.registration.
+
Here is an example of a query set declaration:
+
  <plugin>
+
    <extension
+
          point="org.eclipse.gmt.modisco.infra.query.registration">
+
        <modelqueryset
+
              file="_example_jdkAndEclipseQuerySet.querySet">
+
        </modelqueryset>
+
    </extension>
+
  </plugin>
+
Thanks to this extension declaration, The MoDisco project is ready to be exported as a plug-in.
+
 
+
 
+
==Query Meta-model Description==
+
 
+
[[Image:MoDisco_Query_Metamodel.png]]
+
 
+
ModelQuerySet is the root of the query model. One root per query
+
model is expected.
+
 
+
ModelQuerySet::name must be unique (in the Eclipse platform) and
+
equal to the containing file name. We recommend to use a name prefix
+
with a namespace, for example: org.eclipse.gmt.modisco.example1.querySet1.
+
 
+
ModelQuerySet::isEditable is true if the query can be edited. If
+
the query is stored into a compiled file then ModelQuerySet::isEditable is
+
false.
+
 
+
ModelQuerySet::getQuery(EString) returns the contained ModelQuery
+
having the requested name.
+
 
+
ModelQuerySet::associatedMetamodels points to the meta-models
+
used by the contained queries.
+
 
+
ModelQuerySet::queries refers to the contained queries.
+
 
+
ModelQuery is an abstract class representing a query.
+
 
+
ModelQuery::name is the query name. In each query set the query
+
names must be unique.
+
 
+
ModelQuery::parameters a set of ModelQueryParameter instances
+
describing the query parameters.
+
 
+
ModelQuery::returnType is an ecore::DataType representing the
+
query return type.
+
 
+
ModelQuery::scope is the set of types on which the query is
+
applicable. Those types are represented by ecore::DataType instances.
+
 
+
ModelQueryParameter is a class representing the query parameters.
+
 
+
ModelQueryParameter::type is an ecore::DataType representing the
+
query parameter type.
+
 
+
ModelQueryParameter::name is the parameter name. In each query
+
the parameter names must be unique.
+
 
+
ModelQuery::isExternalContextDependent must be true if two
+
evaluations of the same query with the same context and parameters can
+
return different results.
+
 
+
JavaModelQuery is a sub class of ModelQuery which points to a
+
Java implemented query.
+
 
+
JavaModelQuery::implemenationClassName contains the qualified
+
name of the class implementing the query. This class must be a sub class
+
of org.eclipse.gmt.modisco.infra.query.core.java.IJavaModelQuery. The
+
Java implementation class must be stored in the same plug-in (or plug-in
+
project) as the query model.
+
 
+
OCLModelQuery::query is the OCL query string.
+
 
+
 
+
== JXPath Queries ==
+
=== JXPath Meta-model Extension Description ===
+
[[Image:MoDisco_Query_jxpath_metamodel.png|JXPath Query Meta-model Extension]]
+
 
+
A JXPathModelQuery is a ModelQuery describing a '''[http://commons.apache.org/jxpath/ JXPath]''' expression.
+
 
+
The JXPath expressions are stored into the JXPathModelQuery::query attribure.
+
 
+
=== Example ===
+
 
+
The '''[http://dev.eclipse.org/svnroot/modeling/org.eclipse.gmt.modisco/plugins/trunk/org.eclipse.gmt.modisco.infra.query.doc/doc/resources/jxpathQueryTest.querySet jxpathQueryTest.querySet]'''
+
model provides an example of a JXPath query. The JXPathQuery stored into
+
'''[http://dev.eclipse.org/svnroot/modeling/org.eclipse.gmt.modisco/plugins/trunk/org.eclipse.gmt.modisco.infra.query.doc/doc/resources/jxpathQueryTest.querySet jxpathQueryTest.querySet]''' returns the name of the EPackage passed in the query
+
context.
+
 
+
== How to log in a Java query ==
+
If you want to log errors or messages in a Java query, you can use the MoDisco logger, like this (where Activator is the class that is already generated by default in your MoDisco project):
+
* To log an error message:
+
MoDiscoLogger.logError("Error message", Activator.getDefault());
+
* To log an exception:
+
MoDiscoLogger.logError(exception, Activator.getDefault());
+
* To log an information message:
+
MoDiscoLogger.logInfo("Error message", Activator.getDefault());
+
* ... (see also the other methods on MoDiscoLogger)
+
 
+
 
+
[[Category:MoDisco]]
+

Latest revision as of 11:31, 2 April 2012

  1. REDIRECT MoDisco/Moved To Help Center

Copyright © Eclipse Foundation, Inc. All Rights Reserved.