owloop: A Java repository from EmaroLab

Enabling a developer to use Ontology Web Language (OWL) along with its reasoning capabilities in an Object Oriented Programming (OOP) paradigm, by providing an easy to use API, i.e., OWLOOP.

Although OWL and OOP paradigms have similar structure, there are some key differences between them; see this W3C publication for more details about the differences. Nonetheless, it is possible to use OWL along with its reasoning capabilities within applications developed in an OOP paradigm, by using the classic OWL-API. But, the usage of the classic OWL-API leaves your project with lots of boilerplate code. Therefore, the OWLOOP-API (built on top of OWL-API), reduces boilerplate code by enabling interaction with 'OWL entities' (i.e, Concept (also known as Class), Individual, Object property and Data property) as objects within the OOP paradigm. These objects are termed as Descriptors (i.e., ClassDescriptor, IndividualDescriptor, ObjectPropertyDescriptor and DataPropertyDescriptor). By using descriptor(s), OWLOOP synchronizes axioms (OWL2-DL axioms) between the OOP paradigm (your application's code) and the OWL paradigm (OWL ontology XML/RDF file(s)).

Example of a real-world system that used OWLOOP API:

This video (link) shows a smart home system recognising human activities. The system uses a network of multiple ontologies to recognise specific activities. The network of multiple ontologies was developed using OWLOOP API.

1. Reference to the Publication

OWLOOP API is a peer reviewed software published by Elsevier in its journal SoftwareX. The publication presents in detail the motivation for developing OWLOOP. Furthermore, it describes the design of the API and presents the API's usage with illustrative examples.

Please, cite this work as:

@article{OWLOOP-2021,
  title = {{OWLOOP}: {A} Modular {API} to Describe {OWL} Axioms in {OOP} Objects Hierarchies},
  author = {Buoncompagni, Luca and Kareem, Syed Yusha and Mastrogiovanni, Fulvio},
  journal = {SoftwareX},
  volume = {17},
  pages = {100952},
  year = {2022},
  issn = {2352-7110},
  doi = {https://doi.org/10.1016/j.softx.2021.100952},
  url = {https://www.sciencedirect.com/science/article/pii/S2352711021001801}
}

2. Getting Started with OWLOOP

2.1. Prerequisites for your Operating System

Install an IDE, for example IntelliJ IDEA.
Install Java JRE and Java JDK.

2.2. Add OWLOOP dependencies to your project

Download OWLOOP related jar files.
- owloop-2.1.jar
- amor-2.2.jar
Add OWLOOP related jar files to your project:

First Step: Create a new project with Java as the programming language and Gradle as the build tool.

Second Step: Create a directory called lib and place the OWLOOP related jar files in it.

Third Step: Modify your build.gradle file, as follows:

Add flatDir { dirs 'lib' } within the repositories{} section, as shown below:

repositories {
    mavenCentral()

    flatDir {
        dirs 'lib'
    }
}

Add the required dependencies (i.e., owloop, amor and pellet), as shown below 👇

dependencies {
    // testCompile group: 'junit', name: 'junit', version: '4.12'

    implementation 'it.emarolab.amor:amor:2.2'
    implementation 'it.emarolab.owloop:owloop:2.1'
    implementation group: 'com.github.galigator.openllet', name: 'openllet-owlapi', version: '2.5.1'
}

It is normal that a warning like SLF4J: Class path contains multiple SLF4J bindings occurs.

Final Step: You are now ready to create/use OWL ontologies in your project/application 🔥, by using OWLOOP descriptors in your code!.

2.3. Use OWLOOP in your project

This is an example code that shows how to create an OWL file and add axioms to it.

import it.emarolab.amor.owlInterface.OWLReferences;
import it.emarolab.owloop.core.Axiom;
import it.emarolab.owloop.descriptor.utility.classDescriptor.FullClassDesc;
import it.emarolab.owloop.descriptor.utility.individualDescriptor.FullIndividualDesc;
import it.emarolab.owloop.descriptor.utility.objectPropertyDescriptor.FullObjectPropertyDesc;

public class someClassInMyProject {

    public static void main(String[] args) {

        // Disabling 'internal logs' (so that our console is clean)
        Axiom.Descriptor.OntologyReference.activateAMORlogging(false);

        // Creating an object that is 'a reference to an ontology'
        OWLReferences ontoRef = Axiom.Descriptor.OntologyReference.newOWLReferencesCreatedWithPellet(
                "robotAtHomeOntology",
                "src/main/resources/robotAtHomeOntology.owl",
                "http://www.semanticweb.org/robotAtHomeOntology",
                true
        );

        // Creating some 'classes in the ontology'
        FullClassDesc location = new FullClassDesc("LOCATION", ontoRef);
        location.addSubClass("CORRIDOR");
        location.addSubClass("ROOM");
        location.writeAxioms();
        FullClassDesc robot = new FullClassDesc("ROBOT", ontoRef);
        robot.addDisjointClass("LOCATION");
        robot.writeAxioms();

        // Creating some 'object properties in the ontology'
        FullObjectPropertyDesc isIn = new FullObjectPropertyDesc("isIn", ontoRef);
        isIn.addDomainClassRestriction("ROBOT");
        isIn.addRangeClassRestriction("LOCATION");
        isIn.writeAxioms();
        FullObjectPropertyDesc isLinkedTo = new FullObjectPropertyDesc("isLinkedTo", ontoRef);
        isLinkedTo.addDomainClassRestriction("CORRIDOR");
        isLinkedTo.addRangeClassRestriction("ROOM");
        isLinkedTo.writeAxioms();

        // Creating some 'individuals in the ontology'
        FullIndividualDesc corridor1 = new FullIndividualDesc("Corridor1", ontoRef);
        corridor1.addObject("isLinkedTo", "Room1");
        corridor1.addObject("isLinkedTo", "Room2");
        corridor1.writeAxioms();
        FullIndividualDesc robot1 = new FullIndividualDesc("Robot1", ontoRef);
        robot1.addObject("isIn", "Room1");
        robot1.writeAxioms();
        
        // Saving axioms from in-memory ontology to the the OWL file located in 'src/main/resources'
        ontoRef.saveOntology();
    }
}

After running the above code, the OWL file robotAtHomeOntology gets saved in src/main/resources. We can open the OWL file in Protege and view the ontology.

3. Overview of important Java-classes (in OWLOOP) and their methods

Java-classes	methods
Path: OWLOOP/src/.../owloop/core/ This path contains, all core Java-classes. Among them, one in particular is immediately useful, i.e., `OntologyReference`. It allows to create/load/save an OWL ontology file.
	The following method allows to enable/disable display of internal logging: `activateAMORlogging()`
	The following methods allow to instantiate an object of the Java-class `OWLReferences`: `newOWLReferencesCreatedWithPellet()` `newOWLReferencesFromFileWithPellet()` `newOWLReferencesFromWebWithPellet()`
	The object of Java-class `OWLReferences`, offers the following methods: `saveOntology()` `synchronizeReasoner()` `load()` // is hidden and used internally
Path: OWLOOP/src/.../owloop/descriptor/utility/ This path contains the directories that contain all Java-classes that are (as we call them) descriptors. The directories are the following: /classDescriptor /dataPropertyDescriptor /objectPropertyDescriptor /individualDescriptor.
	The object of a Descriptor, offers the following methods: `add...()` `remove...()` `build...()` `get...()` `query...()` `writeAxioms()` `readAxioms()` `reason()` `saveOntology()`

4. Wiki documentation

The OWLOOP API's core aspects are described in this repository's wiki:

Structure of the OWLOOP API project.
JavaDoc of the OWLOOP API project.
What is a Descriptor in OWLOOP?
- Types of descriptors.
- Expressions that can be implemented for each type of descriptor.
- Methods of a descriptor.
- Preconstructed Descriptors provided by OWLOOP.
Code examples that show how to:
- Construct a type of descriptor.
- Add axioms to an ontology by using descriptors.
- Infer some knowledge (i.e., axioms) from the axioms already present within an ontology by using descriptors. This example also highlights the use of the build() method.
- Remove axioms from an ontology by using descriptors.

5. Some details about OWLOOP dependencies

Please use Gradle as the build tool for your project, and include the following dependencies in your project's build.gradle file:

aMOR (latest release is amor-2.2): a Multi-Ontology Reference library is based on OWL-API and it provides helper functions to OWLOOP.
- OWL-API: a Java API for creating, manipulating and serialising OWL Ontologies. We have included owlapi-distribution-5.0.5 within amor-2.2.
OWLOOP (latest release is owloop-2.2): an API that enables easy manipulation of OWL (Ontology Web Language) ontologies from within an OOP (Object Oriented Programming) paradigm.
- Pellet: an open source OWL 2 DL reasoner. We have included openllet-owlapi-2.5.1 within owloop-2.2.

6. Developers' message

Feel free to contribute to OWLOOP by sharing your thoughts and ideas, raising issues (if found) and providing bug-fixes. For any information or support, please do not hesitate to contact us through this Github repository or by email.

Developed by luca.buoncompagni@edu.unige.it and kareem.syed.yusha@dibris.unige.it under the supervision of fulvio.mastrogiovanni@unige.it.

7. License

OWLOOP is under the license: GNU General Public License v3.0

EmaroLab/owloop