Core concepts and general usage

Components

Hawk is an extensible system. Currently, it contains the following kinds of components:

Type	Role	Current implementations
Change listeners	React to changes in the graph produced by the updaters	Tracing, Validation
Graph backends	Integrate database technologies	Neo4j, OrientDB, Greycat
Model drivers	Integrate modelling technologies	Ecore, BPMN, Modelio, IFC2x3/IFC4 in this repo, and UML2
Query languages	Translate high-level queries into efficient graph queries	Epsilon Object Language, Epsilon Pattern Language, OrientDB SQL
Updaters	Update the graph based on the detected changes in the models and metamodels	Built-in
VCS managers	Integrate file-based model repositories	Local folders, SVN repositories, Git repositories, Eclipse workspaces, HTTP files

General usage

Using Hawk generally involves these steps:

1. Create a new Hawk index, based on a specific backend (e.g. Neo4j or OrientDB).
2. Add the required metamodels to the index.
3. Add the model repositories to be monitored.
4. Wait for the initial batch insert (may take some time in large repositories).
5. Add the desired indexed and derived attributes.
6. Perform fast and efficient queries on the graph, using one of the supported query languages (see table above).

In the following sections, we will show how to perform these steps.

Managing indexes with the Hawk view

To manage and use Hawk indexes, first open the “Hawk” Eclipse view, using “Window > Show View > Other... > Hawk > Hawk”. It should look like this:

Hawk indexes are queried and managed from this view. From left to right, the buttons are:

• Query: opens the query dialog.
• Run: starts a Hawk index if it was stopped.
• Stop: stops a Hawk index if it was running.
• Sync: request the Hawk index to check the indexed repositories immediately.
• Delete: removes an index from the Hawk view, without deleting the actual database (it can be usually recovered later using the “Import” button). To remove a local index completely, select it and press Shift+Delete.
• New: creates a new index (more info below).
• Import: imports a Hawk index from a factory. Hawk itself only provides a “local” factory that looks at the subdirectories of the current Eclipse workspace.
• Configure: opens the index configuration dialog, which allows for managing the registered metamodels, the repositories to be indexed, the attributes to be derived and the attributes to be indexed.

Creating a new index

To create a new index, open the Hawk view and use the “New” button to open this dialog:

The dialog requires these fields:

• Name: a descriptive name for the index. Only used as an identifier.
• Instance type: Hawk only supports local instances, but mondo-integration can add support for remote instances.
• Local storage folder: folder that will store the actual database. If the folder exists, Hawk will reuse that database instead of creating a new one.
• Remote location: only used for the remote instances in mondo-integrtion.
• Enabled plugins: list of plugins that are currently enabled in Hawk.
• Back-end: database backend to be used (currently either Neo4j or OrientDB).
• Min/max delay: minimum and maximum delays in milliseconds between synchronisations. Hawk will start at the minimum value: every time it does not find any changes, it will double the delay up to the maximum value. If it finds a change, it will reset back to the minimum value. Periodic synchronisation can be completely disabled by changing the minimum and maximum delays to 0: in this mode, Hawk will only synchronise on startup, when a repository is added or when the user requests it manually.

Once these fields have been filled in, Hawk will create and set up the index in a short period.

Managing metamodels

After creating the index, the next step is to register the metamodels of the models that are going to be indexed. To do this, select the index in the Hawk view and either double click it or click on the “Configure” button. The configure dialog will open:

The configure dialog has several tabs. For managing metamodels, we need to go to the “Metamodels” tab. It will list the URIs of the currently registered metamodels. If a metamodel we need is not listed there, we can use the “Add” button to provide Hawk with the appropriate file to be indexed (e.g. the .ecore file for EMF-based models, or the metamodel-descriptor.xml for Modelio-based models). We can also “Remove” metamodels: this will remove all dependent models and metamodels as well.

To try out Hawk, we recommend adding the JDTAST.ecore metamodel, which was used in the GraBaTs 2009 case study from AtlanMod. For Modelio metamodels, use the metamodel-descriptor.xml for Modelio 3.6 projects (for older projects, use the older descriptors included as metamodel_*.xml files in the Modelio 3.6 sources).

Keep in mind that metamodels may have dependencies to others. You will need to either add all metamodels at once, or add each metamodel after those it depends upon. If adding all the metamodels at once, Hawk will rearrange their addition taking into account their mutual dependencies.

Note: the EMF driver can parse regular Ecore metamodels with the .ecore extension.

Note: regarding the Modelio metamodel-descriptor.xml files, you can find those as part of the Modelio source code.

Managing repositories

Having added the metamodels of the models to be indexed, the following step is to add the repositories to be indexed. To do so, go to the “Indexed Locations” tab of the Hawk configure dialog, and use the “Add” button. Hawk will present the following dialog:

![Hawk add repository dialog](img/hawk_add_repo.png**

The fields to be used are as follows:

• Type: type of repository to be indexed.
• Location: URL or path to the repository.
  • For local folders, it is recommended to use the “Browse...” button to produce the adequate `file://** URL.
  • For SVN, it is best to copy and paste the full URL.
  • For Git repositories, use the new JGitRepository connector: the old Git connector is deprecated. You can use a path to the root folder of your Git clone, or a file://path/to/repo[?branch=BRANCH] URL (where the optional ?branch=BRANCH part can be used to specify a branch other than the one currently checked out).
  • For Workspace repositories, the location is irrelevant: selecting any directory from “Browse...” will work just the same.
• User + pass: for private SVN repositories, these will be the username and password to be used to connect to the repository. Hawk will store the password on the Eclipse secure storage.

To try out Hawk, after adding the JDTAST.ecore metamodel from the previous section, we recommend adding a folder with a copy of the set0.xmi file. It has around 70k model elements. To watch over the indexing process, look at the “Error Log” view or run Eclipse with the -console option.

The supported file extensions are as follows:

Driver	Extensions
EMF	.xmi, .model, any extensions in the EMF extension factory map that use XMIResourceFactoryImpl, any extensions mentioned through the org.hawk.emf.model.extraExtensions Java system property (e.g. -Dorg.hawk.emf.model.extraExtensions=.railway,.rail).
UML2	.uml. .profile.uml files can be indexed normally and also registered as metamodels.
BPMN	.bpmn, .bpmn2.
Modelio	.exml, .ramc. Parses mmversion.dat internally for metadata.
IFC	.ifc, .ifcxml, .ifc.txt, .ifcxml.txt, .ifc.zip, .ifczip.

Managing indexed attributes

Simply indexing the models into the graph will already speed up considerably some common queries, such as finding all the instances of a type: in Hawk, this is done through direct edge traversal instead of going through the entire model. However, queries that filter model elements through the value of their attributes will need additional indexing to be set up.

For instance, if we wanted to speed up return Class.all.selectOne(c|c.name='MyClass'); (which returns the class named “MyClass”), we would need to index the name attribute in the Class type. To do so, we need to go to the Hawk configure dialog, select the “Indexed Attributes” tab and press the “Add” button. This dialog will open:

Its fields are as follows:

• Metamodel URI: the URI of the metamodel that has the type we want.
• Type Name: the name of the type (here “Class”).
• Attribute Name: the name of the attribute to be indexed (here “name”).

Please allow some time after the dialog is closed to have Hawk generate the index.

Currently, Hawk can index attributes with strings, booleans and numbers. Indexing will speed up not only =, but also > and all the other relational operators.

Managing derived attributes

Sometimes we will need to filter model elements through a piece of information that is not directly stored among its attributes, but is rather computed from them. To speed up the process, Hawk can keep precompute these derived attributes in the graph, keeping them up to date and indexing them. For instance, if we wanted to quickly filter UML classes by their number of operations, we would go to the Hawk configure dialog, select the “Derived Attributes” tab and click on the “Add” button. This dialog would appear:

The fields are as follows:

• Metamodel URI: the URI of the metamodel with the type to be extended.
• Type Name: the name of the type we are going to extend.
• Attribute Name: the name of the new derived attribute (should be unique).
• Attribute Type: the type of the new derived attribute.
• isMany: true if this is a collection of values, false otherwise.
• isOrdered: true if this is an ordered collection of values, false otherwise.
• isUnique: true if the value should provide a unique identifier, false otherwise.
• Derivation Language: query language that the derivation logic will be written on. EOL is the default choice.
• Derivation Logic: expression in the chosen language that will compute the value. Hawk provides the self variable to access the model element being extended.

For this particular example, we'd set the fields like this:

• Metamodel URI: the URI of the UML metamodel.
• Type Name: Class.
• Attribute Name: ownedOperationCount.
• Attribute Type: Integer.
• isMany, isOrdered, isUnique: false.
• Derivation Language: EOLQueryEngine.
• Derivation Logic: return self.ownedOperation.size;.

After pressing OK, Hawk will spend some time computing the derived attribute and indexing the value. After that, queries such as return Class.all.select(c|c.ownedOperationCount > 20); will complete much faster.

Querying the graph

To query the indexed models, use the “Query” button of the Hawk view. This dialog will open:

The actual query can be entered through the “Query” field manually, or loaded from a file using the “Query File” button. The query should be written in the language selected in “Query Engine”. The scope of the query can be limited using the “Context Repositories” and “Context Files” fields: for instance, using set1.xmi on the “Context Files” field would limit it to the contents of the set1.xmi file.

Running the query with “Run Query” button will place the results on the “Result” field.