Skip to content

Using the Ontology API

When you have followed the Ontology development tutorial please continue from Using the JAVA API

GBOL API

When using the GBOL api, the compiled package can be found here.

Private API

When you have developed your own OWL/ShEx file you can generate an API package using the EmpusaCodeGen program.

For example to generate the GBOL (Java/R) Api we use the following command

java -jar EmpusaCodeGen.jar -i GbolAdditional.ttl gbol-ontology.ttl -o ../GBOLApi/ -r ../RGBOLApi

Compiling the private API

Installing the Java API

To compile the java package into a single jar run the install.sh script in the generated folder or you can use the java classes directly in your programming environment. To install the java API you need to have java 1.8 or higher and the gradle build system

#Install oracle java 1.8 or higher
sudo apt-add-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer

#Install gradle 3.4.1 or higher
sudo add-apt-repository ppa:cwchien/gradle
sudo apt-get update
sudo apt-get install gradle

#run the install script
./install.sh

The example at contain an example on how the use the API

git clone http://gitlab.com/gbol/example

Installing the R API

In addition when using the R API, besides R, the RJava package is required

#Install oracle java 1.8 or higher
sudo apt-add-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer

#Install gradle 3.4.1
sudo add-apt-repository ppa:cwchien/gradle
sudo apt-get update
sudo apt-get install gradle

#Install R and RJava
sudo apt-get install r-base r-cran-rjava

#run the install script
./install.sh

An example for using the R api is included in

git clone http://gitlab.com/gbol/example

Using the JAVA API

After the compilation of the ontology for the API we focus now on how to use the API to create your RDF files.

Using the API through the source code files

This example is written for Intellij but I am sure it should also work for eclipse.

We first load the code base as a new project into intellij.

Project overview

  • I have created a new empty project in which the API folder was imported as a module with Gradle support.
  • MyProgram.class should be created inside the following path MyJavaApi/src/main/java/, using the code outlined below:
import com.xmlns.foaf.domain.Agent;
import java.io.File;
import java.time.LocalDate;
import nl.wur.ssb.RDFSimpleCon.RDFFormat;
import nl.wur.ssb.RDFSimpleCon.api.Domain;
import org.purl.ontology.bibo.domain.Book;

public class MyProgram {

  public static void main(String[] args) throws Exception {
    Domain domain = new Domain("");

    // Creating the book object using the class type and a URL
    Book book = domain.make(org.purl.ontology.bibo.domain.Book.class,"http://example.com/mybook");

    book.setAbstract("The abstract of the book");

    // The book was accepted today!
    book.setDateAccepted(LocalDate.now());

    Agent agent = domain.make(com.xmlns.foaf.domain.Agent.class,"http://example/com/myAgent007");
    agent.setName("James Bond");
    book.addAuthorList(agent);

    // Saving the database to a file in the TURTLE format
    String output = new File("example.ttl").getAbsolutePath();
    domain.save(output , RDFFormat.TURTLE);

    System.out.println("Saved to: "+output);
  }
}

Breaking it down into smaller steps the following is happening:

Standard java class creation:

package nl.wur.ssb;

import com.xmlns.foaf.domain.Agent;
import java.io.File;
import java.time.LocalDate;
import nl.wur.ssb.RDFSimpleCon.RDFFormat;
import nl.wur.ssb.RDFSimpleCon.api.Domain;
import org.purl.ontology.bibo.domain.Book;

public class MyProgram {

  public static void main(String[] args) throws Exception {

RDF / JENA store creation, using "" it creates a temporary memory store as long as the code runs this is available. Persistent disk stores can be used using a "file://" path.

Domain domain = new Domain("");

Once the domain object is created, classess can be spawned (according to the ontology) and filled with content.

For example example to create a book entry:

domain.make(org.purl.ontology.bibo.domain.Book.class,"http://example.com/mybook");

The source path as present in the "API" folder in this project + the class name (here Book) and the .class is needed. The second argument is the URL of this entry.

The nice thing about the Java api is to know what kind of properties are available for the Book class and all its parent classes. Just type variableName. and possibilities should pop up.

For example to set the Abstract a string object is required and can just be directly written like: ​
​ book.setAbstract("The abstract of the book");

Or instead of a string, setting the date for a publication can be done like this:

book.setDateAccepted(LocalDate.now());

Connecting properties can be done via first creating the other object for example the Author of a book which is an Agent:

Agent agent = domain.make(com.xmlns.foaf.domain.Agent.class,"http://example/com/myAgent007");

And what is an author without a name?

agent.setName("James Bond");

Now connecting the book to the author:

book.addAuthorList(agent);

As a book can have multiple authors the book.addAuthorList(agent) can be used multiple times to add other authors e.g. (book.addAuthorList(agent2))

Finally you would like to have the RDF database in a formatted RDF file.

domain.save(output , RDFFormat.TURTLE);

Ontology restrictions

Within the OWL/ShEx file you can set restrictions using the regex patterns (e.g. ?, *, +, integer / string etc...). An example is shown here in which the API will complain and stop because you forgot something...

import com.xmlns.foaf.domain.Agent;
import java.io.File;
import java.time.LocalDate;
import nl.wur.ssb.RDFSimpleCon.RDFFormat;
import nl.wur.ssb.RDFSimpleCon.api.Domain;
import org.purl.ontology.bibo.domain.Book;

public class MyProgram {

    public static void main(String[] args) throws Exception {
        Domain domain = new Domain("");

        // Creating the book object using the class type and a URL
        Book book = domain.make(org.purl.ontology.bibo.domain.Book.class,"http://example.com/mybook");

        book.setAbstract("The abstract of the book");

        // The book was accepted today!
        book.setDateAccepted(LocalDate.now());

        Agent agent = domain.make(com.xmlns.foaf.domain.Agent.class,"http://example/com/myAgent007");
        // agent.setName("James Bond");
        book.addAuthorList(agent);

        // Saving the database to a file in the TURTLE format
        String output = new File("example.ttl").getAbsolutePath();
        domain.save(output , RDFFormat.TURTLE);

        System.out.println("Saved to: "+output);
    }
}

We have commented out the following line // agent.setName("James Bond");. Now there is no author name attached to the agent which is added to the book. When an item (Agent) is added to another item (Book) the validator kicks in and checks the constraints. It then sees that the name is required and will show the following message stating that the cardinality for name is incorrect.

Exception in thread "main" java.lang.RuntimeException: Cardinality should be >=1 for property: http://xmlns.com/foaf/0.1/name
    at nl.wur.ssb.RDFSimpleCon.api.OWLThingImpl.checkCardMin1(OWLThingImpl.java:1187)
    at com.xmlns.foaf.domain.impl.AgentImpl.validate(AgentImpl.java:43)
    at nl.wur.ssb.RDFSimpleCon.api.OWLThingImpl.addRefListList(OWLThingImpl.java:794)
    at org.purl.ontology.bibo.domain.impl.BookImpl.addAuthorList(BookImpl.java:178)
    at MyProgram.main(MyProgram.java:23)

Uncommenting the line ensuring a name is given to the Agent makes the program work again.

Using the JAR file

You can also incorporate the JAR file into an already existing JAVA project.

To create a basic JAVA project in which you would like to include the jar execute the following in a new folder (e.g. test)

mkdir test
cd test
mkdir libs # Needed later to place the "API".jar file in
gradle init --type java-application

Open the build.gradle file in intellij as a new project.

Use gradle 'wrapper' task configuration

Once you are all set you should see the newly generated java main and test classes.

To incorporate your API you need to copy the jar file which in my case was my.project.group.jar into the libs folder.

Now you should modify the build.gradle file such that the jar files inside the libs folder are recognised (fileTree line).

dependencies {
    // This dependency is found on compile classpath of this component and consumers.
    compile 'com.google.guava:guava:23.0'

    // Use JUnit test framework
    testCompile 'junit:junit:4.12'
    // This includes all jar files from the libs folder
    compile fileTree(dir: 'libs', include: '*.jar')

}

The editor should see that a change occured and should allow you to reload the gradle build file by importing the changes.

For example:

public class App {
    public String getGreeting() {
        return "Hello world.";
    }

    public static void main(String[] args) throws Exception {
        Domain domain = new Domain("");
        Book book = domain.make(org.purl.ontology.bibo.domain.Book.class,"http://example.com/mybook");
        book.setAbstract("Abstract of the book");
        domain.save("book.ttl");
        System.out.println(new App().getGreeting());
    }
}

When executed this should create the book.ttl file which contains:

@prefix owl:   <http://www.w3.org/2002/07/owl#> .
@prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .

<http://example.com/mybook>
        a       <http://purl.org/ontology/bibo/Book> ;
        <http://purl.org/dc/terms/abstract>
                "Abstract of the book" .

There are more possibilities with the API, such as direct querying, merging databases and more!

Feel free to contact us for any Empusa / API / OWL/Shex related issues.