ObdaFileCompatibilityRepair
The OBDA File Compatibility Repair (OFCR; Officer) is a small utility tool that is used to convert the old version of OBDA file to a newer version that fits to the current API development. More specifically, the API is no longer support the processing of the initial OBDA file (i.e., version 1) and only supports two versions, namely, the version 2 and version 3. The comparison between these versions can be found in the next section "OBDA File History".
The tool is written in JAVA and uses the command line as its interaction interface. It offers several options for executing the conversion to create the valid versions. The details about the command and the options can be found in the section "The Commands".
This is the earliest version of OBDA file. The document includes three important elements:
- The mappings tag, which collects the mapping schema between the conjunctive query (CQ) strings and the database SQL query strings.
- The dataSource tag, which contains the input strings necessary to make a connection to the data source, e.g., to a database.
- The SavedQueries tag, which collects individual queries that are saved by users for later purposes.
<?xml version="1.0" encoding="ISO-8859-1"?>
<OBDA version="1.0">
<mappings
bodyclass="class inf.unibz.it.obda.api.mapping.RDBMSSQLQuery"
headclass="class inf.unibz.it.obda.api.domain.ucq.ConjunctiveQuery"
sourceuri="StockExchange">
<mapping id="mapping-addresses">
<CQ string="Address(getAddress($id)),
inStreet(getAddress($id),$street),
inCity(getAddress($id),$city)"/>
<SQLQuery string="select id, street, city from address"/>
</mapping>
<mapping id="mapping-brokers">
<CQ string="StockBroker(getPerson($id)),
firstName(getPerson($id),$name),
lastName(getPerson($id),$lastname)"/>
<SQLQuery string="select id, name, lastname from broker"/>
</mapping>
</mappings>
<dataSource URI="StockExchange" databaseDriver="..."/>
<SavedQueries>
<QueryGroup id="Simple queries">
<Query id="Addresses"
text="SELECT * WHERE {$x rdf:type 'Address'.}"/>
</QueryGroup>
</SavedQueries>
</OBDA>The later version 2 comes with namespace definitions that help to create URI references to the atom's predicates and terms. Notice that there are three major differences in this version compared to the earlier.
First, the OBDA tag now contains the namespace definitions.
Second, the headclass attribute of the mappings tag uses a new implementation of org.obda.query.domain.imp.CQIEImpl.
And lastly, the RDF type in the text attribute of the Query tag is no longer written as rdf:type 'Address' but instead it becomes rdf:type :Address
<?xml version="1.0" encoding="ISO-8859-1"?>
<OBDA version="2.0"
xml:base="http://www.owl-ontologies.com/onto.owl#"
xmlns="http://www.owl-ontologies.com/onto.owl#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#">
<mappings
bodyclass="class inf.unibz.it.obda.api.mapping.RDBMSSQLQuery"
headclass="class org.obda.query.domain.imp.CQIEImpl"
sourceuri="StockExchange">
<mapping id="mapping-addresses">
<CQ string="Address(getAddress($id)),
inStreet(getAddress($id),$street),
inCity(getAddress($id),$city)"/>
<SQLQuery string="select id, street, city from address"/>
</mapping>
<mapping id="mapping-brokers">
<CQ string="StockBroker(getPerson($id)),
firstName(getPerson($id),$name),
lastName(getPerson($id),$lastname)"/>
<SQLQuery string="select id, name, lastname from broker"/>
</mapping>
</mappings>
<dataSource URI="StockExchange" databaseDriver="..."/>
<SavedQueries>
<QueryGroup id="Simple queries">
<Query id="Addresses"
text="SELECT * WHERE {$x rdf:type :Address.}"/>
</QueryGroup>
</SavedQueries>
</OBDA>This is the latest version of OBDA file that includes the usage of DOCTYPE entities to read prefixes in the CQ string. Notice that this newest version includes the head &obdap;q(*) in the CQ string.
<?xml version="1.0" encoding="ISO-8859-1"?> <DOCTYPE OBDA[
<ENTITY obdap 'http://obda.org/mapping/predicates/'>
]>
<OBDA version="3.0"
xml:base="http://www.owl-ontologies.com/onto.owl#"
xmlns="http://www.owl-ontologies.com/onto.owl#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#">
<mappings
bodyclass="class inf.unibz.it.obda.api.mapping.RDBMSSQLQuery"
headclass="class org.obda.query.domain.imp.CQIEImpl"
sourceuri="StockExchange">
<mapping id="mapping-addresses">
<CQ string="&obdap;q(*) :- Address(getAddress($id)),
inStreet(getAddress($id),$street),
inCity(getAddress($id),$city)"/>
<SQLQuery string="select id, street, city from address"/>
</mapping>
<mapping id="mapping-brokers">
<CQ string="&obdap;q(*) :- StockBroker(getPerson($id)),
firstName(getPerson($id),$name),
lastName(getPerson($id),$lastname)"/>
<SQLQuery string="select id, name, lastname from broker"/>
</mapping>
</mappings>
<dataSource URI="StockExchange" databaseDriver="..."/>
<SavedQueries>
<QueryGroup id="Simple queries">
<Query id="Addresses"
text="SELECT * WHERE {$x rdf:type :Address.}"/>
</QueryGroup>
</SavedQueries>
</OBDA>The table below summarizes the differences among the versions.
| Version 1 | Version 2 | Version 3 | |
|---|---|---|---|
| Has NAMESPACE? | No | Yes | Yes |
| Has DOCTYPE? | No | No | Yes |
| CQ Head is shown? | No | No | Yes |
| The type term for rdf:type | enclosed by a single-quote ('X') | started by a colon (:X) | started by a colon (:X) |
| The class implementation for mapping-head | ConjunctiveQuery | CQIEImpl | CQIEImpl |
Below is the available options provided by the tool.
usage: java ObdaFileCompatibiltyRepair [OPTIONS] FILE1 [FILE2]...
Convert one or more old OBDA file (v1) to the newer standard.
Currently, the API accepts OBDA file v2 and v3 that support
namespace and doctype definitions. Thus, the conversion is
intended for creating the either version.
-base <URI> Define the URI reference for the BASE namespace.
-D <prefix=uri,...> Define one or more URI reference for custom
doctype. Separate each doctype definition with a
comma.
-depreciated Convert to the depreciated OBDA file v2.
-keepOriginal Retain the copy of the original file.
-N <prefix=uri,...> Define one or more URI reference for custom
namespace. Separate each namespace definition with
a comma.
-obdap Add the URI reference for the OBDAP namespace (only
if -depreciated is added, or otherwise it becomes a
DOCTYPE entity).
-owl Add the URI reference for the OWL namespace.
-owl2xml Add the URI reference for the OWL2XML namespace
(only if -depreciated is added, or otherwise it
becomes a DOCTYPE entity).
-rdf Add the URI reference for the RDF namespace.
-rdfs Add the URI reference for the RDFS namespace.
-xsd Add the URI reference for the XSD namespace.Important Issues
- The usage of -D option is supported if -depreciated is not added to the command line. If both options are used then the DOCTYPE definition are not shown.
- The -obdap and -owl2xml are actually DOCTYPE entities. If -depreciated is added then both references are shown as NAMESPACEs. If not, they are shown as DOCTYPE and not as NAMESPACE.
- The -keepOriginal option copies the original file and renames it with an ending .old extension.
- The program can run recursively if the target FILE is a directory. Thus, the same conversion settings will be applied to all files within the directory tree.
- Both -D and -N options support the insertion of multiple DOCTYPE and NAMESPACE definitions. The syntax is similar that each definition is separated by a comma (,) and it is written as a pair of prefix and uri separated by an equal sign (=). For example: -N bk=http://example.org/ns/books/,foaf=http://xmlns.com/foaf/0.1/.
- The -obdap is used by default if -depreciated is not added. The reason is because in v3 the CQ string will always have head "&obdap;q(*)".
In this example, we are going to execute the tool using Eclipse.
- Select "Run configuration..."
2. In the Run Configurations window, create a new Java Application.
3. In the next panel ("Main" tab), insert the "Name", "Project", and "Main class" as in the figure below.
4. Go to the "Arguments" tab and insert the following options in the "Program arguments" text field (see the figure below). You can experiment the program execution by modifying the options explained previously. Briefly, the arguments in the figure create a setting where it defines the BASE prefix as http://www.owl-ontologies.com/onto.owl#, puts OWL, RDF, RDFS and XSD in the NAMESPACE and puts OBDAP in the DOCTYPE. This setting is then applied to an input file located in src/test/java/resources/saved_stockexchange.obda. We also want to retain the original file so it doesn't get overridden. Note: we are going to create a OBDA file v3 since no -depreciated is added.
