Download the owl2query protege plugin jar file. Copy the downloaded jar file into $PROTEGE_HOME/plugins directory and restart Protege. If the OWL2Query tab is not opened (it is not shown in the tab list) you must open the OWL2Query view. To open the view, go to the protege menu bar and select Window->Views->Misck views->OWL2Query.

GUI Map

Figure 1 shows the gui map, the parts of the plugin highlited in red borders. The highlited areas are linked to the topics that describes them.

Screenshot

Toolbar

toolbar

First row in the plugin is the toolbar, which contains demo , new , open and save query buttons. Next to them are two radio buttons used to switch between the graph view and the sparql view. The last two buttons in the toolbar are the undo and redo .

Prefix editor

Prefix editor

The prefix editor is capable of editing the short form of the prefix and to toggle the usage of the short form of the prefix in query. The editor is organized in a table the rows of which are the individual prefixes. The table has three columns. The first column in the table represents the usage state of the given prefix, it is shown as a checkbox component. The second column is rendered as text field and represents the full prefix value. This field is not editable. The third is also rendered as a text field and it represents the short form of the prefix. This filed is editable. The prefix editor contains logic to ensure the consistency of the short form prefixes(unique value for each row in the last column in the table).

On top of the table there are four buttons. The first two buttons are used to manipulate the usage column.

the invert usage button inverts the usage column.
use all button selects all the checkboxes in the usage column, makes all the prefixes to be used.

The last two buttons are used to restore the default values of the short from of the prefixes.

the restore selected rows button will restore only the selected (highlighted) rows in the table
the restore all button will restore all rows.

Variable editor

Prefix editor

The variable editor organizes the variables in a table. Each row in the table represents one variable. The first column is the name or the label of the variable. This column is represented as a not editable text field. The other five columns are rendered as a checkbox. Second Column represents whether the variable is distinguished. This column is editable if the variable is used only in the abox. The third column shows whether the variable is a result variable. This column is editable if the variable is distinguished. The last three columns represent in what boxes it is being used, abox, tbox, abox. The variable can be used in all of the boxes at the same time and will be used in at least one. These three columns are never editable.

Layout editor

Layout editor

The layout editor manages the layouts that are being associated with the query. The list shows the names of the layouts. The names of the layouts can be edited. Under the list there are three buttons snapshot, apply and delete. The snapshot button saves the current layout of the graph into a new layout and adds it to the list. The apply button uses the selected layout in the list to arrange the nodes in the graph. Layouting the graph using the apply button will change only nodes that were part of the graph at the time when the layout was created using the snapshot button. New nodes created after the time the layout was created will not change. The delete button deletes all the selected layouts in the list.

Query Graph

Query graph view

Here only basic functionality of the graph will be explained. Creating concrete query atoms and more detailed explanation of the functionality will be explained later. The graph editor has three ways in which one can edit the graph. The most intuitive one is interacting with the graph area using mouse gestures and the keyboard. By interacting with the graph we can move nodes and manually layout the graph. This however does not change the query it self. To change the query we can add and remove nodes and edges. To add a abox variable node simply doubleclick somewhere in the free abox area in the graph (where there are no nodes and edges). Creating tbox and rbox variables is the same, doubleclick on the area where you wish to create a variable.

Adding edges is only possible when you have two nodes. To add and edge place the mouse cursor any where near the border of the node. The cursor changes to the edge tool cursor if the node can have edges. If the cursor changed press the left mouse button and drag to the node you wish to connect to. When the cursor is over the target it changes to indicate weather it is correct to connect the to nodes. If the edge can be created the cursor changes to accept edge cursor , releasing the mouse button will cause the edge to be created. In the case of an abox edge (edge that both ends are abox nodes) a popup menu will be shone where we can choose the type of edge we want to create. If the target node is not connectable to the source node(the one that the drag was started on) the cursor is changed to deny edge cursor . Releasing the pressed button will not do anything.

Deleting is done with the delete keyboard key. When the delete is pressed the selection in the graph is deleted. If the selection was a node all the edges that are connected to the node are deleted.

The other way to edit the graph is by editing the already created nodes and edges. The nodes are edited in the node editor. To edit a node single node is selected in the graph. The editor will appear on the right side in the graph view. The editor changes upon graph selection and hides if the selection is empty or more than one elements are selected. When editing a node in the node editor it is necessary to press the apply button at the bottom in order to apply changes.

To edit an edge simply doubleclick the edge. A in place editor will popup at the at the point that was clicked. To apply the changes the apply button at button in the editor must be clicked.

SPARQL query view

SPARQL view

The query can be also serialized in the SPARQL format. This is done by selecting the SPARQL radio button in the main toolbar of the plugin. The Sparql view consists of a simple text editor containing the query represented in sparql format.

SPARQL-DL preview

This text field result panel previews the query in SPARQL-DL format.

Resut panel

Result panel

The result panel has two components a run button at the top and a table in which the results are shown. The run button is disabled if the there is not a selected and started reasoner in the protege. When clicked the query runs and the button changes to a stop button. If the query takes too long to execute one can stop the execution by clicking the button. Doing so will cause the plugin to try to stop the reasoner. After the execution is completed the button changes back to a run button. After a successful execution the result table is filled with the result of the query. The columns in the table represent the result variables and the rows are the different bindings of the result variables in the query. The table is view only, no editing is supported.

Edge Editors

The edge editors are basically query atom choosers. The query atom list in the editor changes based on the type of edge that is being edited. The changes are applied after the apply button at the bottom of the form is clicked.

ABox edge editor

ABox-TBox edge editor

TBox edge editor

RBox edge editor

Property Value Editor

The property value editor is basically a property list editor. We can add named object or data properties to the list by using the current selection tree. The selection tree represents the hierarchy of object or data properties.We can switch between the two trees using the radio object and data buttons at the top of the editor. If any part of the query assumes that the node that represents the object of the property value query atom (the node that the arrow points to) either a object property or data property the editor is constrained. In this case the editor is constrained to make consistent changes and therefore one of the radiobuttons is disabled.To add new rbox variable not present in the query click the text field,type the new variable name and press enter. To add a existing rbox variable to the list click the arrow button on the right of the text field. A popup list of existing rbox query variables shows. Select the check box next to the desired variables and click somewhere in the property value editor to hide the popup. To remove entries from the list simply click the red cross next to the entry or select the desired rows in the list and then click the remove selection button under the list. To apply the changes click the apply button at the bottom of the editor.

Property list editor with object property tree selection, used to edit property value query atoms.

Property list editor with object property tree selection, used to edit property value query atoms.

Property list editor with object property tree selection, used to edit property value query atoms.

Abox node editor

The abox node editor three views variable, individual and literal. One can switch between the view using the radiobuttons at the top of the editor.

Variable node editor

The variable editor can only change the variable name of the node. The field must contain a correct value in order to be able to apply the change.

ABox node editor, variable view

Individual node editor

The individual editor is used to select the individual that the node will represent.This is done using the single selection list. By selection is meant a radiobutton selection. A value must be selected in order to be able to apply the changes made. For easier location in the list of individuals, they are alphabetically ordered. Another feature is that the selection in the class hierarchy tree will filter the individual list. Instances of the selected class will appear on top of the list and the rest of the individuals will be gray-colored. The text field under the selection list shows the selected individual if any. Clicking on the field the list will scroll to the chosen individual.

ABox node editor, individual view

Literal editor

In the literal editor use the the data type hierarchy to select a data type if desired. Use the text field to enter the literal value. This field is mandatory, it must contain a value.

ABox node editor, literal view

TBox Node editor

The tbox node editor has to view variable editor and constant editor. Switching between the view is done using the radiobuttons at the top of the editor.

Variable node editor

The variable editor can only change the variable name of the node. The field must contain a correct value in order to be able to apply the change.

Constant editor

The constant editor is used to select an uri from the object or data property hierarchy single selection trees. The hierarchy tree is selected using the object and data property radiobuttons. Selection in the tree is also shown Ianthe "Selected Type" text field. Clicking the field will expand and scroll the tree to the selected property.

TBox node editor, constant view

RBox Node editor

The rbox node editor has two view a variable editor and a constant view. The can switch between the view using the variable and constant radio buttons. The variable editor can only change the variable name of the node. The field must contain a correct value in order to be able to apply the change.The constant editor is used to select a property uri from the object or data property hierarchy single selection tree. The tree hierarchy can be switched by selecting the object properties or the data properties radio buttons. The selection in the tree is also show in the SelectedProperty text field. By clicking this field the tree is expanding and scrolling to the selected value if it is not visible. In each view at the bottom of the rbox editor there is a checkbox list of property attributes. They represent unary rbox query atoms. A short representation of the attribute labels is shown in the parentheses.This short representation is used in the rbox node labels to visualize the properties attributes . The list of attributes is filtered in the different views of the editor or if the DataProperty attribute is selected in the variable view. The selection of the list is also constrained. Non of the next couples of attributes can be selected simultaneously : DatatypeProperty-ObjectProperty, Symmetric-Asymmetric,Irreflexive-Reflexive. If the constraints are violated the older selection of the conflicted attributes will be cleared. For example by selecting the Symmetric attribute the Asymmetric will be cleared if it was already selected. To apply the changes click the apply button.

RBox node editor, variable view

RBox node editor, variable view with data property attribute selected

RBox node editor, constant view with object property selection

RBox node editor, constant view with data property selection

Making query atoms

The SPARQL-DL query is represented as a list of query atoms(graph representation). When creating a query graph one have to create the graphical representation of the query atoms (in most cases they are represented as edges in the graph).
There are two ways to create query atoms.Unary query atoms (for now unary query atoms are present only in the RBox) are represented as letters in the description of a node. To create, add or delete a unary query atom double click an rbox node. The rbox node editor will appear. Select the desired query atoms from the list of checkboxes.
The rest of the query atoms are represented as edges between nodes. To add such query atom to the graph one must add an edge between the desired two nodes.To delete edge query atoms use delete selection. Details about adding and deleting an edges can be found in the Query Graph section. If there is a supported query atom between the nodes an edge query atom is created. In the case of binary query atoms an edge with default query atom is created. The default value depends on the edge type. Editing this query atoms is done by double clicking the edge. An in-place editor will popup. Select the desired query atom from the list of radiobuttons and click the apply button. Editing a property value atom is done by selecting the compound edge. An property value editor appears on the right of the graph. Use the editor to change the list of properties used in this query atom and click the apply button.

Conversion rules

The conversion of the query between graph, sparql and then again graph can change the graph (remove some of the nodes or add some query atoms). This is because the graph that was converted in SPARQL contained nodes that were not used in any query atom. The conversions separates the unused nodes in two categories constant and variable nodes. Constant nodes are ignored. So the graph will not contain any unused constant nodes after the switching from graph to sparql and back to graph. For variable nodes query atoms that include use them are added so that the nodes are no longer disconnected. For abox variable nodes an "instance of" query atom with type argument OWLThing is added. For tbox variable nodes a "subclass of" query atom is added with its second argument OWLThing. For rbox variable nodes "subproperty of" query atom is added with its second argument TopObjectProperty. The change in the graph is that new OWLThing constant tbox node and new TopObjectProperty constant rbox node are added (if they weren't present in the graph). Edges are added from unused abox nodes to the OWLThing node, from unused tbox variable nodes to OWLThing node and from unused rbox variable nodes to TopObjectProperty. The two images below show the graph changes after conversion. The yellow (constant) not connected nodes are removed. New constant nodes TopObjectProperty and OWLThing are added (if they are not present in the graph). Three edges are added from the unconnected variable nodes to the constant nodes added in the first step.

Graph before conversion

Graph after conversion